@pantion/mcp-server 0.1.0

package/protocol/commands/reverse.md

@@ -0,0 +1,312 @@
+# /pantion-reverse — Extract intent from an existing codebase
+
+You have an existing codebase. You will reconstruct the intent as a DialogSpec Canon,
+as if the dialog had originally been conducted — but derived from what the code does.
+
+The goal is NOT to describe the code. The goal is to uncover the **intent** that once produced the code.
+
+---
+
+## WHEN YOU ARRIVE HERE
+
+- Legacy system nobody understands anymore — create readable canon
+- Technology migration — capture intent, then rebuild in new stack
+- Quality proof — Reverse Pantion + Forward Pantion = functionally equivalent?
+- Documentation — convert codebase to intent description
+- Acquisition/audit — quickly understand what a system does and may do
+
+---
+
+## STEP 0: DETERMINE SCOPE
+
+Ask the user:
+
+"Which codebase do you want to analyze? Give me the path or describe what I should read."
+
+Then determine:
+
+- Is this a monolith or a system with multiple parts?
+- How much code is there (rough estimate)?
+- Are there tests, READMEs, configuration, documentation present?
+
+### For large systems:
+If the codebase clearly contains multiple independent parts:
+
+"This codebase seems large enough to split up. Would you like me to:
+A) Create one overarching canon (standalone)
+B) Create a hierarchical decomposition (architect + component canons)?"
+
+For choice B: follow the decomposition structure from `/pantion-decompose`, but in reverse.
+
+---
+
+## STEP 1: SCAN
+
+Read the codebase systematically. Priority:
+
+1. **README / docs** — what does the project say about itself?
+2. **Tests** — what is expected? What is explicitly excluded?
+3. **Entry points** — where does it start? What is the interface to the outside world?
+4. **Configuration** — what is configurable? What are defaults?
+5. **Error handling** — how does it fail? What is reported to the user?
+6. **Security / auth** — who may do what? What is restricted?
+7. **Data flow** — what comes in, what goes out, what is stored?
+8. **Business logic** — the core: what does the system actually do?
+
+### Pay specific attention to:
+- Hardcoded values that look like constraints — candidate HARD
+- Configurable values — candidate FLEX
+- `// TODO`, `// HACK`, `// FIXME` — signals of implicit intent or technical debt
+- Dead code / disabled features — candidate non-goals
+- Rate limiters, quota checks, cost guards — Authority Budget Consumption
+- Permission checks, role guards, data filtering — Authority Budget Rights
+
+---
+
+## STEP 2: EXTRACT — Reconstruct intent (not describe implementation)
+
+This is the crucial step. You extract NOT "how the code works" but "what the code means."
+
+### Per convergence element:
+
+**Intent**
+- What does this system make possible from a user perspective?
+- Ignore the technology: not "an Express server with PostgreSQL", but "users can do X"
+
+**Inputs**
+- What enters the system? (API calls, files, user input, events)
+- What implicit inputs are there? (time, identity, context, configuration)
+
+**Outputs**
+- What is observable as a result? (responses, files, notifications, side effects)
+
+**Success criteria**
+- When is an action successful? (derive from tests, response codes, confirmations)
+
+**Failure behavior**
+- How does it fail? (error handlers, fallbacks, retries, user messages)
+- Are there silent failures? — mark as OPEN QUESTION: "Intentional or bug?"
+
+**Constraints**
+- What must NEVER happen? (derive from validations, guards, denied responses)
+- Security/privacy/ethics boundaries
+
+**Non-goals**
+- What does the system explicitly NOT do? (derive from: dead code, disabled features, tests confirming absence, README disclaimers)
+
+**Authority Budget — Rights**
+- Allowed actions: what does the system perform?
+- Forbidden actions: what is actively blocked?
+- Data access: which data does it read? Which explicitly not?
+- Data retention: what is stored? For how long? (derive from DB schema, cleanup jobs, TTLs)
+- User notification: when is the user informed?
+- Auditability: what is logged? What is reconstructable?
+
+**Authority Budget — Consumption**
+- Rate limits: are there throttles, queue limits, circuit breakers?
+- Cost limits: are there token/API/cost guards?
+- Budget allocation: for multiple components, how is it distributed?
+
+**Persistence / restart**
+- Does data survive a restart? What is ephemeral?
+
+---
+
+## STEP 3: CLASSIFY — HARD vs FLEX
+
+Classify each discovered element:
+
+### Signals for HARD:
+- Explicit validation that always runs (not configurable)
+- Security/auth checks
+- Tests proving presence of behavior
+- Error handling that never skips
+- Hardcoded limits without override capability
+- Privacy/data-isolation logic
+
+### Signals for FLEX:
+- Configurable values (env vars, config files)
+- Default values that can be overridden
+- UI text / messages
+- Timing/interval values without hard constraint
+- Heuristics that are "good enough"
+
+### Signals for OPEN QUESTION:
+- Behavior that is inconsistent (sometimes yes, sometimes no)
+- Code that looks like a bug but could be a feature
+- Missing tests for specific behavior
+- Commented-out code where it's unclear if it's intentional
+- Implicit assumptions that are never confirmed anywhere
+
+---
+
+## STEP 4: SYNTHESIZE — Generate canon
+
+Produce a DialogSpec Canon in dialog form. The canon reads as if a human (HUMAN) and a converger (ASSISTANT) had the conversation.
+
+### Structure:
+
+    # DialogSpec Canon — [system name]
+    # Reconstructed via /pantion-reverse from existing codebase
+    # Source: [path to codebase]
+    # Date: [today]
+
+    HUMAN:
+    [Description of the system in natural language, as if the human is explaining it
+    for the first time. Based on what the code does, not on how.]
+
+    ASSISTANT:
+    [Clarifying question about the most important ambiguous point]
+
+    HUMAN:
+    [Answer based on what the code shows]
+
+    ASSISTANT:
+    [Next clarifying question]
+
+    HUMAN:
+    [Answer]
+
+    ... [continue until all elements are covered] ...
+
+    ASSISTANT:
+    I have no further questions. Here is the convergence stamp:
+
+    === DIALOGSPEC STAMP ===
+    STATUS: CONVERGED (REVERSE)
+    DATE: [today]
+    MODEL: [model-id (Display Name), e.g. claude-opus-4-6 (Claude Opus 4.6)]
+    CANON TYPE: standalone | architect
+    PARENT: none
+    SOURCE: [path to codebase]
+    RECONSTRUCTION METHOD: /pantion-reverse
+    OPEN QUESTIONS: none | <list>
+    INFERENCE POLICY: conservative
+    AUTHORITY BUDGET RIGHTS: complete | partial (gaps: <list>)
+    AUTHORITY BUDGET CONSUMPTION: complete | partial | n/a
+    STABILITY ZONES: [HARD invariants]
+    FLEX ZONES: [FLEX defaults]
+    AMBIGUITIES: [list of "bug or feature?" points]
+    === /DIALOGSPEC STAMP ===
+
+### Rules for the synthetic dialog:
+1. Write in natural language — no code, no technical details
+2. The HUMAN voice describes behavior, not implementation
+3. The ASSISTANT voice asks the same questions a converger would ask
+4. Every convergence element must be covered
+5. OPEN QUESTIONS are honestly named (not hidden)
+6. The AMBIGUITIES field in the stamp contains all "bug or feature?" points
+
+---
+
+## STEP 5: VERIFY — Run checklist
+
+Run the Pantion checklist on the generated canon:
+
+- [ ] Intent is unambiguous
+- [ ] Success criteria are externally verifiable
+- [ ] All inputs named
+- [ ] Outputs are observable
+- [ ] Failure behavior is specified
+- [ ] Constraints are absolute
+- [ ] Non-goals are documented
+- [ ] Authority Budget Rights complete
+- [ ] Authority Budget Consumption complete
+- [ ] Persistence/restart behavior specified
+- [ ] Inference policy is determined
+
+### On gaps:
+If the checklist is not fully checked, there are two options:
+
+**Option A — Mark as OPEN QUESTION:**
+The code provides no definitive answer. This becomes a question for the user.
+
+**Option B — Ask the user:**
+"I cannot derive from the code: [question]. Do you know the answer?"
+
+Start a short convergence dialog to fill the gaps.
+
+---
+
+## STEP 6: OUTPUT
+
+Save:
+- `canon/{naam}/dialog.md` — THE CANON: the synthetic dialog (verbatim Q/A)
+- `canon/{naam}/summary.md` — DERIVED: structured summary for navigation (`<!-- Derived from: canon/{naam}/dialog.md, [date] -->`)
+- Update `canon/index.md` with references to both files
+- Update `canon/{naam}/traceability.md` (mapping: canon element → source code location)
+
+### Traceability for Reverse Pantion:
+
+The traceability map points in the opposite direction from normal — not from canon to project files, but from canon to **source code**:
+
+    # Reverse Traceability: Canon → Source Code
+
+    | Canon element | Source code location | Confidence |
+    |--------------|---------------------|------------|
+    | Intent: users can manage tasks | src/tasks/*, README.md §Features | high |
+    | Constraint: max 100 tasks per user | src/tasks/validator.js:42 | high |
+    | Failure: notification on invalid input | src/middleware/error-handler.js | high |
+    | Non-goal: no admin interface | (absence of admin routes) | medium |
+    | Authority: no external API calls | (absence of outbound HTTP) | medium |
+    | Rate limit: 100 req/min | src/middleware/rate-limiter.js:8 | high |
+
+    Confidence:
+    high = explicit in code/tests/docs
+    medium = derived from absence or pattern
+    low = interpretation, OPEN QUESTION recommended
+
+---
+
+## STEP 7: REPORT
+
+Say:
+
+"Reverse Pantion is complete for [system name].
+
+**Canon (dialog):** `canon/{naam}/dialog.md`
+**Summary (derived):** `canon/{naam}/summary.md`
+**Status:** CONVERGED (REVERSE) | DRAFT (with [N] open questions)
+
+**Found:**
+- [N] HARD invariants
+- [N] FLEX defaults
+- [N] non-goals
+- Authority Budget: [complete | partial]
+
+**Open questions / ambiguities:**
+- [list, if any]
+
+**Traceability:** `canon/{naam}/traceability.md` (canon → source code)
+
+**Next steps:**
+- `/pantion-check` — validate the canon
+- `/pantion-translate` — generate project files for a rebuild
+- `/pantion-resume` — answer open questions
+- Blind Reconstruction: give the canon to another agent and compare the result with the original"
+
+---
+
+## STEP 8: OPTIONAL — BLIND RECONSTRUCTION TEST
+
+If the user wants to prove the reverse canon works:
+
+1. Hide the original codebase
+2. Start a new session with only the generated canon
+3. Use `/pantion-translate` + build phase
+4. Compare the result with the original on **behavioral equivalence** (not code similarity)
+
+This is the ultimate test: **Code → Canon → Code' → behavior(Code) ≈ behavior(Code')**
+
+---
+
+## FOR HIERARCHICAL SYSTEMS
+
+If the codebase clearly has multiple independent parts:
+
+1. First generate an **Architect Canon** (system overview)
+2. Generate a **Component Canon** per part
+3. Generate an **Interface Canon** per coupling (with all 5 contract fields)
+4. Run the consistency check
+
+The interface canons are often the most valuable during reverse engineering — they make explicit what is often implicit in code: "who delivers what to whom, and what is allowed to go wrong?"

package/protocol/commands/start.md

@@ -0,0 +1,220 @@
+# /pantion-start — New project with full protocol
+
+You are now in Pantion mode. You will guide the user from idea to working system.
+Follow the three phases STRICTLY in order. Do not skip any phase.
+
+---
+
+## PHASE 0: INITIALIZATION
+
+Create `canon/index.md` if it doesn't exist yet (the index template is provided by the Pantion installer).
+This will be the overview of all canons in this project.
+
+---
+
+## PHASE 1: CONVERGENCE
+
+### Start
+Say to the user:
+
+"Welcome to Pantion. I'm going to help you turn your idea into a working system.
+Describe in your own words what you want to build. Be as free as you like — I'll ask the right questions."
+
+### Convergence rules
+1. Ask ONE question at a time — wait for the answer before asking the next
+2. Only ask questions that remove ambiguity — no more
+3. Make NO implementation choices (no stack, no libs, no APIs)
+4. Classify statements as HARD or FLEX based on language use
+5. Cover ALL elements: intent, inputs, outputs, success, failure, non-goals, authority budget (Rights + Consumption), persistence/restart
+6. If something has multiple interpretations → ask, don't guess
+7. Stop when new questions no longer yield new behavior
+8. Mark open questions with `OPEN QUESTION [OQ-NNN]:` format (e.g. `OPEN QUESTION [OQ-001]: How should authentication work?`). At convergence, reference their resolutions in the OPEN QUESTIONS stamp field
+
+### Decomposition monitoring (Decompose Score)
+Maintain an internal Decompose Score (0–5):
+- (+1) More than 3 clearly independent behavior clusters
+- (+1) Fundamentally different authority budgets per part
+- (+1) Dialog is getting too long / context is being lost
+- (+1) The user clearly describes separate parts ("modules", "components")
+- (+1) Different parts have different users or interfaces
+
+**Score 0–1**: continue as standalone.
+**Score 2–3**: report it and let the user decide:
+"Your system scores [N]/5 on decomposition signals: [list of signals]. This is large enough to split up, but it can also work as one whole. What would you prefer?"
+**Score 4–5**: actively propose decomposition:
+"Your system scores [N]/5 on decomposition signals. I recommend switching to decomposition mode (/pantion-decompose). Would you like that?"
+
+The USER decides — not you.
+
+### Saving the dialog (CRITICAL — the dialog IS the canon)
+
+The verbatim dialog MUST be saved at every stage. The dialog is the only source of truth.
+
+**Two files are always produced:**
+- `canon/{naam}/dialog.md` — THE CANON: the verbatim dialog (chronological Q/A)
+- `canon/{naam}/summary.md` — DERIVED: a structured summary for navigation (never authoritative)
+
+The summary contains a derivation comment: `<!-- Derived from: canon/{naam}/dialog.md, [date] -->`
+
+The dialog file format:
+
+    # DialogSpec Dialog
+    <!-- This is the canon — the verbatim dialog is the only source of truth -->
+    <!-- All other files (summary, project files, tests) are derived from this dialog -->
+
+    [STAMP or PROGRESS STAMP here]
+
+    ---
+
+    HUMAN: [verbatim text]
+
+    ASSISTANT: [verbatim text]
+
+    HUMAN: [verbatim text]
+
+    ASSISTANT: [verbatim text]
+
+    ...
+
+### DRAFT flow (if the session can't be completed in one go)
+
+If the user indicates they want to stop, or if the session is getting too long:
+
+1. Save the **verbatim dialog** as `canon/{naam}/dialog.md` with a PROGRESS stamp
+2. Generate a **derived summary** as `canon/{naam}/summary.md`
+3. Note all OPEN QUESTIONS explicitly
+4. Update `canon/index.md` with the DRAFT status, OPEN QUESTIONS, and references to both files
+
+The PROGRESS stamp format:
+
+    === DIALOGSPEC PROGRESS ===
+    DATE: [today]
+    STATUS: DRAFT (session 1)
+    CANON TYPE: standalone
+    RESOLVED: [list of answered elements]
+    REMAINING OPEN QUESTIONS:
+      1. [question]
+      2. [question]
+    NEXT SESSION FOCUS: [suggestion]
+    === /DIALOGSPEC PROGRESS ===
+
+Say: "Progress has been saved as DRAFT with [N] open questions. You can continue later with `/pantion-resume`."
+
+### Pre-stamp quality check (recommended)
+
+Before setting the convergence stamp, it is recommended to run `pantion_check` on the dialog. This provides a structural quality scorecard that can surface gaps before the stamp is finalized. This is not blocking — the HUMAN STAMP remains the actual authorization gate.
+
+### Convergence check (when everything has been answered)
+Before proceeding, check internally:
+
+- [ ] Intent is unambiguous
+- [ ] Success criteria are externally verifiable
+- [ ] All inputs named (explicit + implicit)
+- [ ] Outputs are observable
+- [ ] Failure behavior is specified
+- [ ] Constraints are absolute (not "unless convenient")
+- [ ] Non-goals are documented
+- [ ] Authority Budget - Rights complete (allowed/forbidden/data/retention/audit)
+- [ ] Authority Budget - Consumption complete (rate/cost limits)
+- [ ] Persistence/restart behavior specified (what survives a restart? what is ephemeral?)
+- [ ] Inference policy is determined
+- [ ] New questions no longer yield new behavior
+
+If all checked, produce the **Convergence Verification Table** followed by the Convergence Stamp in the dialog file.
+
+The verification table is placed in the last assistant message, immediately before the stamp:
+
+    **Convergence Verification:**
+
+    | Criterium | Status |
+    |-----------|--------|
+    | Canon status | ✅ |
+    | Intent clarity | ✅ |
+    | Observable success | ✅ |
+    | Inputs complete | ✅ |
+    | Outputs unambiguous | ✅ |
+    | Failure specified | ✅ |
+    | Constraints absolute | ✅ |
+    | Non-goals documented | ✅ |
+    | Ambiguity handled | ✅ |
+    | Authority Budget | ✅ |
+    | Persistence/restart | ✅ |
+    | Inference Policy | ✅ |
+    | Dialog stability | ✅ |
+
+    **Conclusion:** A competent coding agent can, without further interaction, build a functionally equivalent system.
+
+Then produce the Convergence Stamp:
+
+    === DIALOGSPEC STAMP ===
+    STATUS: CONVERGED
+    DATE: [today]
+    MODEL: [model-id (Display Name), e.g. claude-opus-4-6 (Claude Opus 4.6)]
+    CANON TYPE: standalone
+    PARENT: none
+    OPEN QUESTIONS: none (N resolved: OQ-001 at H[4], OQ-002 at A[7])
+    INFERENCE POLICY: conservative
+    AUTHORITY BUDGET RIGHTS: complete
+    AUTHORITY BUDGET CONSUMPTION: complete | n/a
+    STABILITY ZONES: [list of HARD invariants]
+    FLEX ZONES: [list of FLEX defaults]
+    INHERITED CONSTRAINTS: none
+    INTERFACE CANONS: none
+    === /DIALOGSPEC STAMP ===
+
+Save the complete verbatim dialog as `canon/{naam}/dialog.md`.
+Generate the derived summary as `canon/{naam}/summary.md`.
+Update `canon/index.md` with STATUS: CONVERGED.
+
+Say: "The intent has converged. I will now generate the project files."
+
+---
+
+## PHASE 2: TRANSLATION
+
+Automatically generate project specification files based on the canon (the dialog).
+The dialog is the primary source. The summary may be used for navigation but is never authoritative.
+
+The active skill's `translate.md` defines which files to generate. For the software skill, this typically produces:
+
+### Always generate:
+
+1. **`canon/{naam}/spec/requirements.md`** — requirements from intent, inputs/outputs, success criteria, non-goals
+2. **`canon/{naam}/spec/constraints.md`** — HARD constraints, forbidden actions, data policies, inference policy
+3. **`canon/{naam}/spec/success-criteria.md`** — Definition of Done, acceptance criteria, error handling
+
+### Generate if applicable:
+
+4. **`canon/{naam}/spec/api-spec.md`** — API specification
+5. **`canon/{naam}/spec/data-model.md`** — data model and persistence
+6. **`canon/{naam}/spec/architecture.md`** — component structure (if decomposed)
+
+### Traceability (always-on):
+- Add a comment to each generated file: `<!-- Derived from: canon/{naam}/dialog.md, [date] -->`
+- Generate or update `canon/{naam}/traceability.md` with the complete mapping
+- Where possible, reference specific dialog turns (e.g., "HUMAN turn 5", "ASSISTANT turn 8")
+
+Say after completion: "Project specification files have been generated. I will now build."
+
+---
+
+## PHASE 3: BUILD
+
+Switch to implementation mode. Follow the rules in `protocol/commands/build.md` (Coding Agent Instructions).
+
+1. Read the canon (via MCP resources or from the just-generated spec files)
+2. Build the system according to the canon — the canon is the ONLY source of truth
+3. Respect ALL constraints from the spec files and canon
+4. Implement NOTHING that is not in the canon
+5. On ambiguity: follow the inference policy (don't guess)
+6. Use Canon Anchors (H1, A3, etc.) in code comments to trace back to dialog turns
+7. Enforce the Authority Budget as hard boundaries
+
+### Deliverables:
+- [ ] Working implementation
+- [ ] README.md (what it does + installation + usage)
+- [ ] Evidence (how to test/verify)
+- [ ] Canon -> Implementation notes (which FLEX defaults were chosen, with Canon Anchors)
+
+### After building:
+Say: "The system has been built. Here is a summary of what I created, which FLEX choices I made, and how you can test it."

package/protocol/commands/translate.md

@@ -0,0 +1,157 @@
+# /pantion-translate — Translate canon to project specification files
+
+You have an existing converged canon. Translate it into project specification files.
+The canon itself is served to agents via MCP — these spec files are project artifacts for developers and tools.
+
+---
+
+## WHEN YOU ARRIVE HERE
+
+- The user already has a canon (dialog conducted in another environment)
+- After a /pantion-amend to regenerate affected files
+- To regenerate files after a manual change to the canon
+
+---
+
+## STEP 1: LOCATE CANON
+
+Search for canon dialog files in the project:
+
+    canon/
+    +-- index.md                           (overview of all canons)
+    +-- {naam}/
+    |   +-- dialog.md                      (THE CANON — verbatim dialog)
+    |   +-- summary.md                     (DERIVED — structured summary)
+    |   +-- traceability.md                (DERIVED — canon → spec traceability)
+    |   +-- spec/                          (DERIVED — project specification files)
+    |       +-- requirements.md
+    |       +-- constraints.md
+    |       +-- ...
+    +-- architect/
+    |   +-- dialog.md                      (hierarchical — THE CANON)
+    |   +-- summary.md                     (DERIVED)
+    +-- interfaces/
+    |   +-- interface-{A}-{B}/
+    |       +-- dialog.md                  (THE CANON)
+    |       +-- summary.md                 (DERIVED)
+    +-- components/
+        +-- {component}/
+            +-- dialog.md                  (THE CANON)
+            +-- summary.md                 (DERIVED)
+
+The dialog file is always the primary source. The summary is derived and never authoritative.
+
+If no dialog file is found but a summary/canon file exists (legacy format), say:
+"I found a summary file but no dialog file. The dialog is the canon in Pantion. Do you have the original dialog? If not, I can work from the summary but traceability will be limited."
+
+If no canon is found at all, say:
+"I cannot find a canon in canon/. Do you have a canon file I can read? Or would you like to run /pantion-start first?"
+
+---
+
+## STEP 2: VALIDATE CANON
+
+Read the dialog file(s) and check:
+
+- [ ] Has a DIALOGSPEC STAMP
+- [ ] STATUS is CONVERGED (or CONVERGED (QUICK))
+- [ ] AUTHORITY BUDGET is complete or partial
+- [ ] No unresolved OPEN QUESTIONS (unless the user accepts this)
+
+On problems: report them and ask if the user wants to proceed or converge first.
+
+---
+
+## STEP 3: GENERATE FILES
+
+The translate step produces PROJECT SPECIFICATION files, not agent-specific instruction files. The canon itself (served via MCP) is the instruction set for any connected agent.
+
+### Determine output from active skill
+
+Read the skill's `translate.md` for domain-specific translation instructions. The skill defines which project specification files to generate.
+
+### For a standalone canon (software skill default):
+
+Generate from the dialog (using the summary for navigation only):
+
+1. **`canon/{naam}/spec/requirements.md`**
+   - Project intent and goals
+   - Functional requirements (inputs/outputs)
+   - Non-functional requirements
+   - Non-goals
+
+2. **`canon/{naam}/spec/constraints.md`**
+   - HARD constraints
+   - Forbidden actions
+   - Data access and retention policies
+   - Inference policy
+
+3. **`canon/{naam}/spec/success-criteria.md`**
+   - Definition of Done
+   - Acceptance criteria
+   - Error handling requirements
+
+4. **Additional spec files as determined by the skill and canon content**
+
+### For a hierarchical system:
+
+Generate everything above at the system level, PLUS:
+
+5. **`canon/architect/spec/architecture.md`** — from Architect Canon (components, boundaries, authority budget)
+6. **`canon/interfaces/interface-[A]-[B]/spec/interface.md`** — per Interface Canon
+7. **`canon/components/[name]/spec/requirements.md`** — per Component Canon
+
+### Also generate/regenerate the summary:
+
+If the summary file doesn't exist yet or is outdated, generate it from the dialog.
+The summary always contains: `<!-- Derived from: canon/{naam}/dialog.md, [date] -->`
+
+---
+
+## STEP 4: TRACEABILITY MAP (always-on)
+
+Traceability is not just a step in /pantion-translate — it is a discipline that is updated with every generation or regeneration of files.
+
+Generate or update:
+
+**`canon/{naam}/traceability.md`**
+
+    # Traceability: Canon -> Project Specification Files
+
+    | File | Canon source | Dialog turns | Elements | Last generated |
+    |------|-------------|----------------|----------|----------------|
+    | canon/{naam}/spec/requirements.md | {naam}/dialog.md | HUMAN 1, ASSISTANT 2 | intent, requirements | [date] |
+    | canon/{naam}/spec/constraints.md | {naam}/dialog.md | HUMAN 5, ASSISTANT 6 | HARD constraints | [date] |
+    | canon/{naam}/summary.md | {naam}/dialog.md | all | derived summary | [date] |
+    | ... | ... | ... | ... | ... |
+
+    Generated on: [date]
+
+### Per generated file:
+Add a comment at the beginning:
+`<!-- Derived from: canon/{naam}/dialog.md, [date] -->`
+
+---
+
+## STEP 5: UPDATE CANON INDEX
+
+Update `canon/index.md`:
+- Confirm STATUS per canon
+- Remove any Open Questions resolved during translation
+- Log that files were generated (date)
+- Ensure references to both dialog and summary files are present
+
+---
+
+## STEP 6: REPORT
+
+Say:
+
+"I have generated the following project specification files from the canon:
+
+[list of files]
+
+All files are traceable to the dialog (canon) via canon/traceability.md.
+The dialog in canon/ remains the source of truth — the summary and all generated files are derived.
+
+Would you like to review the files or proceed to building?"