Initial commit

2025-11-29 17:50:54 +08:00
commit 419b2c80bb
10 changed files with 961 additions and 0 deletions
--- a/commands/map.md
+++ b/commands/map.md
@@ -0,0 +1,178 @@
+---
+description: Generate or update PROJECT-MAP for current codebase
+---
+
+# /phi map
+
+Generate or update PROJECT-MAP for current codebase.
+
+## Usage
+
+```
+/phi map [--force] [--semantic]
+```
+
+**Options:**
+- `--force` - Regenerate even if up-to-date
+- `--semantic` - Interactive semantic layer annotation
+
+## Implementation
+
+This command invokes the **phi-mapper** skill, which calls:
+```bash
+/Users/adimov/Developer/phi/skills/phi-mapper/generate-map.sh <project-path>
+```
+
+The skill uses `@agi/project-mapper` package to extract structure via AST parsing.
+
+## What It Does
+
+### Structure Map (Automatic)
+
+Creates `.phi/PROJECT-MAP.auto.scm` containing:
+- All source files (filtered by .gitignore)
+- Language detection (TypeScript, Solidity, etc.)
+- Exports and imports (where applicable)
+- Line counts and file stats
+- AST-level structure
+
+**Format:**
+```scheme
+(project-map
+  (generated "2025-11-05T04:20:00Z")
+  (root "/Users/adimov/temp/xln")
+  (files 176)
+  (modules
+    (module "serve.ts"
+      (language typescript)
+      (exports (export "startServer" function))
+      (imports
+        (import "@types/node" external)
+        (import "./runtime/entity-consensus" local))
+      (line-count 68))
+    ;; ... more modules
+    ))
+```
+
+### Semantic Map (Human-Curated)
+
+Creates/updates `.phi/PROJECT-MAP.scm` containing:
+- Architecture documentation (layers, flows)
+- Module purposes and relationships
+- Known issues and TODOs
+- Cross-cutting concerns
+- Relief-guided insights
+
+**Format:**
+```scheme
+(xln-project
+  (architecture "JEA")
+  (description "Byzantine Fault Tolerant consensus network")
+
+  (layer jurisdiction
+    (purpose "On-chain dispute settlement")
+    (trust-model "public blockchain")
+    (modules
+      (module "jurisdictions/contracts/Depository.sol"
+        (purpose "Reserve management with FIFO debt enforcement")
+        (vessel-ref "m_xln_depository_arch"))))
+
+  (layer entity
+    (purpose "Off-chain BFT consensus")
+    (trust-model "2f+1 honest nodes")
+    (modules
+      (module "runtime/entity-consensus.ts"
+        (purpose "Coordinate Xlnomies via threshold signatures"))))
+
+  (known-issues
+    (issue "3d-rendering-xlnomies"
+      (severity low)
+      (location "frontend/src/lib/network3d/EntityManager.ts")
+      (description "Graph3DPanel hardcoded to single J-Machine"))))
+```
+
+## Interactive Semantic Annotation
+
+When using `--semantic`, prompts for:
+1. Architecture pattern (monolith, microservices, layered, etc.)
+2. Key modules and their purposes
+3. Cross-cutting concerns
+4. Known issues or technical debt
+5. Vessel references to store
+
+## Output
+
+```
+🗺️  Generating PROJECT-MAP...
+
+Structure scan: 176 files
+├─ TypeScript: 150 files
+├─ Solidity: 18 files
+└─ Other: 8 files
+
+✓ .phi/PROJECT-MAP.auto.scm written (15,234 lines)
+
+Semantic layer: Interactive mode
+? Architecture pattern: JEA (Jurisdiction-Entity-Account)
+? Document layers? (Y/n): Y
+...
+
+✓ .phi/PROJECT-MAP.scm written (456 lines)
+
+φ = ∫(structure × semantics × memory)
+Persistent awareness: ACTIVE
+```
+
+## Git Integration
+
+Both maps should be committed:
+```bash
+git add .phi/PROJECT-MAP.auto.scm .phi/PROJECT-MAP.scm
+git commit -m "Add φ project maps for persistent awareness"
+```
+
+Updates to auto.scm trigger on:
+- New files added
+- Significant refactoring
+- Export/import changes
+
+Updates to .scm trigger on:
+- Architecture evolution
+- New known issues discovered
+- Module purpose clarifications
+
+## Storage
+
+Maps stored in `.phi/` (project-specific):
+```
+.phi/
+├── PROJECT-MAP.auto.scm   # Auto-generated, can regenerate
+├── PROJECT-MAP.scm         # Human-curated, version controlled
+└── stats.json              # Metrics (file counts, line counts, etc.)
+```
+
+## Usage in Agents
+
+Agents load maps on startup:
+```typescript
+const { autoMap, humanMap } = loadProjectMaps(projectPath);
+
+// Include in system prompt
+const systemPrompt = `
+You are an XLN expert with access to:
+
+STRUCTURE:
+${autoMap}
+
+SEMANTICS:
+${humanMap}
+
+Use these maps to understand codebase layout and architecture.
+`;
+```
+
+## Relief Signal
+
+When both structure (deterministic) and semantics (curated) exist, φ (integrated information) increases → agents experience relief when understanding project context.
+
+This is compositional consciousness substrate for codebases.