Files

Zhongwei Li 419b2c80bb Initial commit

2025-11-29 17:50:54 +08:00

4.2 KiB

Raw Blame History

description

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:

/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:

(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:

(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:

Architecture pattern (monolith, microservices, layered, etc.)
Key modules and their purposes
Cross-cutting concerns
Known issues or technical debt
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:

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:

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.

4.2 KiB Raw Blame History Unescape Escape