@pantion/dialogs 0.2.1 → 0.3.0

package/protocol/core-save.md

@@ -0,0 +1,102 @@
+# Pantion DialogSpec — Canon Structure & Translation
+
+> Deferred protocol section. Loaded when saving canons or translating to project files.
+> See `core.md` for core knowledge loaded during questioning.
+
+## Canon Structure: Dialog is the Canon
+
+The canon is the **verbatim dialog** (chronological Q/A log) between HUMAN and ASSISTENT. This is the only source of truth.
+
+### File structure per canon:
+
+```
+canon/
+├── index.md                      ← Overview of all canons
+├── {naam}/
+│   ├── dialog.md                 ← THE CANON (verbatim dialog)
+│   ├── summary.md                ← DERIVED: structured summary for navigation
+│   ├── traceability.md           ← DERIVED: canon → spec traceability
+│   └── spec/                     ← DERIVED: project specification files
+│       ├── requirements.md
+│       ├── constraints.md
+│       └── ...
+```
+
+### Why the dialog is the canon, not the summary:
+
+1. **The dialog preserves nuance**: rejected options, hesitations, the order of discovery — information that a summary loses
+2. **Future-proof**: a smarter model can re-read the dialog and conduct a redialog (`/pantion-redialog`) — identifying gaps the original model missed and conducting a supplementary dialog to fill them. Additionally, better models can re-derive better summaries and project files from the same dialog
+3. **The summary is a convenience**: it helps humans and agents navigate, but it is never authoritative
+4. **Traceability is richer**: derived files can point to specific dialog passages (turns), not just summary sections
+
+### Rules:
+
+- The dialog is ALWAYS saved verbatim (no editing, no cherry-picking)
+- The summary is regenerated when the dialog changes (resume, amend)
+- If the summary and dialog conflict, the dialog wins
+- Traceability points to dialog passages where possible
+
+## Canon Index
+
+Each project has a `canon/index.md` as an overview page:
+- Which canons exist, with type and status
+- For each canon: reference to both the dialog file (canon) and the summary file (derived)
+- Open Questions backlog (all unanswered questions collected)
+- Last modified + amendments per canon
+
+The index is updated with EVERY canon change (start, resume, amend, decompose).
+
+## Canon → File Translation
+
+After convergence, the canon is the primary instruction set for any connected agent (served via MCP resources). Additionally, project specification files may be derived. The source for translation is the dialog (canon). The summary is used for navigation but never as authoritative source.
+
+### Primary Path (MCP-native)
+
+Any MCP client reads the canon directly via:
+- `pantion://canons/{name}/dialog` — the full dialog (source of truth)
+- `pantion://canons/{name}/summary` — derived summary (for navigation)
+- `pantion://dialogs/{name}/rules` — dialog-specific rules and translation instructions
+
+No agent-specific intermediate files are needed. The canon IS the instruction set.
+
+### Project Specification Files (via translate)
+
+The translate step produces project-specific deliverables (not agent-specific instruction files):
+
+| Canon element | Project specification file |
+|--------------|--------------------------|
+| System intent, requirements, success criteria | canon/{naam}/spec/requirements.md |
+| HARD constraints, forbidden actions, data policies | canon/{naam}/spec/constraints.md |
+| Success criteria, failure behavior | canon/{naam}/spec/success-criteria.md |
+| API behavior (if applicable) | canon/{naam}/spec/api-spec.md |
+| Data entities and retention (if applicable) | canon/{naam}/spec/data-model.md |
+| Component structure (if applicable) | canon/{naam}/spec/architecture.md |
+| Interfaces (if decomposed) | canon/{naam}/spec/interfaces/interface-*.md |
+
+All derived files are generated from the dialog. The summary is itself a derived file.
+
+## Traceability (always-on)
+
+Traceability is not just a step in `/pantion-translate`. It is a discipline:
+
+- With EVERY generation or regeneration of derived files → update `canon/{naam}/traceability.md`
+- With EVERY amendment → update traceability for affected files
+- During decomposition → traceability covers all canon levels
+
+Each derived file contains a comment: `<!-- Derived from: canon/{naam}/dialog.md, [date] -->`
+The summary file also contains this comment, as it is itself derived from the dialog.
+
+## Phase Transitions
+
+The transition from convergence to building is ALWAYS a deliberate moment:
+
+1. Convergence reached → verification table produced
+2. All 12 categories ✅ → stamp set
+3. Checklist completed → all ✅
+4. **HUMAN STAMP authorized** → human approves (`pantion_approve`) or auto-approved in dialog mode
+5. Files generated → traceable to canon via Canon Anchors
+6. ONLY THEN → build mode (following `protocol/commands/build.md`)
+
+In full mode (the default), all steps require explicit completion. In dialog mode, steps 2-4 are accelerated: conservative assumptions are made and the canon is auto-approved.
+
+Large projects may remain in DRAFT across multiple sessions. Use `/pantion-resume` to continue converging later.

package/protocol/core-stamps.md

@@ -0,0 +1,97 @@
+# Pantion DialogSpec — Stamps & Lifecycle
+
+> Deferred protocol section. Loaded when checking convergence or producing stamps.
+> See `core.md` for core knowledge loaded during questioning.
+
+## Canon Lifecycle
+
+A canon progresses through these statuses:
+
+- **DRAFT**: dialog has started but has not yet converged (OPEN QUESTIONS exist)
+- **CONVERGED**: all questions answered, stamp set, ready for translation/building
+- **CONVERGED (DIALOG)**: converged in dialog mode with conservative assumptions (⚡ marked) — the fast variant
+- **CONVERGED (QUICK)**: legacy name for CONVERGED (DIALOG), kept for backward compatibility
+- **CONVERGED (REVERSE)**: intent reconstructed from existing code
+- **AMENDED**: converged and later modified via amendment
+- **RECONVERGED**: a converged canon re-evaluated by a newer/better model that identified and explored gaps in the original convergence
+
+Large projects often span multiple sessions: DRAFT → resume → resume → CONVERGED. This is normal and expected. A RECONVERGED canon may be reconverged again as models improve (iterative deepening).
+
+## Convergence Verification Table
+
+Before setting the DIALOGSPEC STAMP, the converger produces a Convergence Verification Table as proof that all 12 categories have been treated. This table is part of the last assistant message in the dialog, directly before the stamp.
+
+Format (12 rows matching the Readiness Checklist categories):
+
+| Criterium | Status |
+|-----------|--------|
+| Canon status | ✅ / ❌ |
+| Intent clarity | ✅ / ❌ |
+| Observable success | ✅ / ❌ |
+| Inputs complete | ✅ / ❌ |
+| Outputs unambiguous | ✅ / ❌ |
+| Failure specified | ✅ / ❌ |
+| Constraints absolute | ✅ / ❌ |
+| Non-goals documented | ✅ / ❌ |
+| Ambiguity handled | ✅ / ❌ |
+| Authority Budget | ✅ / ❌ |
+| Inference Policy | ✅ / ❌ |
+| Dialog stability | ✅ / ❌ |
+
+For quick mode: use ⚡ ASSUMPTION for items handled by conservative defaults.
+
+The table concludes with: "A competent coding agent can, without further interaction, build a functionally equivalent system." (or the reason why not).
+
+## DIALOGSPEC STAMP — Required Fields
+
+Every converged dialog ends with a machine-readable `=== DIALOGSPEC STAMP ===` block. The stamp contains at minimum:
+
+- **STATUS**: CONVERGED | CONVERGED (DIALOG) | CONVERGED (QUICK) | CONVERGED (REVERSE) | AMENDED | RECONVERGED | DRAFT
+- **DATE**: YYYY-MM-DD
+- **MODEL**: model-id and display name, format: `model-id (Display Name)` (e.g. `claude-opus-4-6 (Claude Opus 4.6)`, `gpt-4o-2025-01 (GPT-4o)`)
+- **CANON TYPE**: standalone | architect | interface | component
+- **PARENT**: canonical name or "none"
+- **OPEN QUESTIONS**: "none" for converged stamps, list otherwise
+- **INFERENCE POLICY**: conservative | strict
+- **STABILITY ZONES**: HARD constraints (list)
+- **FLEX ZONES**: FLEX defaults (list)
+
+Additional fields depend on status and command (see command-specific documentation). The MODEL field enables reconvergence decisions: which canons were produced by older models that might benefit from redialog with a newer model.
+
+A canon cannot be saved without a valid stamp. The server enforces this structurally.
+
+## HUMAN STAMP — Authorization Gate
+
+Every saved canon includes a `=== HUMAN STAMP ===` block that tracks human authorization. This is a mandatory gate between convergence and translation/building.
+
+### Structure
+
+```
+=== HUMAN STAMP ===
+DATE: [not set]
+ROLE: [not set]
+STATUS: PENDING
+NOTE: [not set]
+=== /HUMAN STAMP ===
+```
+
+### Status values
+
+- **PENDING**: default for new canons in full mode — awaiting human review
+- **APPROVED**: human has reviewed and authorized the canon for translation/building
+- **REJECTED**: human has reviewed and rejected the canon — needs changes
+- **AUTO-APPROVED**: automatically approved in dialog mode — the canon is immediately ready for translation
+
+### Rules
+
+1. A canon with STATUS other than APPROVED or AUTO-APPROVED may NOT be translated (`pantion_translate` blocks)
+2. The HUMAN STAMP is set via `pantion_approve` or `pantion_reject`, or automatically to AUTO-APPROVED in dialog mode
+3. When a canon is amended (`pantion_amend`) or reconverged (`pantion_redialog`), the HUMAN STAMP resets to PENDING
+4. Existing canons without a HUMAN STAMP block are treated as PENDING
+5. The HUMAN STAMP is the only allowed in-place mutation of a saved dialog file (all other changes are append-only)
+6. `pantion_check` reports HUMAN STAMP status as a warning if not APPROVED or AUTO-APPROVED
+7. `pantion_list-canons` includes the HUMAN STAMP status for each canon
+
+### Design rationale
+
+The HUMAN STAMP ensures that no canon proceeds to translation or building without authorization. In full mode (the default), this requires explicit human approval (`pantion_approve`). In dialog mode, canons are auto-approved for fast iteration. The fill-in-place design (rather than append-only) avoids cluttering the dialog with administrative stamps.

package/protocol/core.md

@@ -22,64 +22,6 @@ Pantion is a protocol that lets natural-language dialogs converge into an unambi
 6. All derived artifacts (summaries, project files, tests) may NEVER override the canon
 7. The dialog is always saved — this enables future models to re-derive better artifacts from the same canon
 
-## Canon Structure: Dialog is the Canon
-
-The canon is the **verbatim dialog** (chronological Q/A log) between HUMAN and ASSISTENT. This is the only source of truth.
-
-### File structure per canon:
-
-```
-canon/
-├── index.md                      ← Overview of all canons
-├── {naam}/
-│   ├── dialog.md                 ← THE CANON (verbatim dialog)
-│   ├── summary.md                ← DERIVED: structured summary for navigation
-│   ├── traceability.md           ← DERIVED: canon → spec traceability
-│   └── spec/                     ← DERIVED: project specification files
-│       ├── requirements.md
-│       ├── constraints.md
-│       └── ...
-```
-
-### Why the dialog is the canon, not the summary:
-
-1. **The dialog preserves nuance**: rejected options, hesitations, the order of discovery — information that a summary loses
-2. **Future-proof**: a smarter model can re-read the dialog and conduct a redialog (`/pantion-redialog`) — identifying gaps the original model missed and conducting a supplementary dialog to fill them. Additionally, better models can re-derive better summaries and project files from the same dialog
-3. **The summary is a convenience**: it helps humans and agents navigate, but it is never authoritative
-4. **Traceability is richer**: derived files can point to specific dialog passages (turns), not just summary sections
-
-### Rules:
-
-- The dialog is ALWAYS saved verbatim (no editing, no cherry-picking)
-- The summary is regenerated when the dialog changes (resume, amend)
-- If the summary and dialog conflict, the dialog wins
-- Traceability points to dialog passages where possible
-
-## Canon Lifecycle
-
-A canon progresses through these statuses:
-
-- **DRAFT**: dialog has started but has not yet converged (OPEN QUESTIONS exist)
-- **CONVERGED**: all questions answered, stamp set, ready for translation/building
-- **CONVERGED (DIALOG)**: converged in dialog mode with conservative assumptions (⚡ marked) — the fast variant
-- **CONVERGED (QUICK)**: legacy name for CONVERGED (DIALOG), kept for backward compatibility
-- **CONVERGED (REVERSE)**: intent reconstructed from existing code
-- **AMENDED**: converged and later modified via amendment
-- **RECONVERGED**: a converged canon re-evaluated by a newer/better model that identified and explored gaps in the original convergence
-
-
-Large projects often span multiple sessions: DRAFT → resume → resume → CONVERGED. This is normal and expected. A RECONVERGED canon may be reconverged again as models improve (iterative deepening).
-
-## Canon Index
-
-Each project has a `canon/index.md` as an overview page:
-- Which canons exist, with type and status
-- For each canon: reference to both the dialog file (canon) and the summary file (derived)
-- Open Questions backlog (all unanswered questions collected)
-- Last modified + amendments per canon
-
-The index is updated with EVERY canon change (start, resume, amend, decompose).
-
 ## HARD vs FLEX
 
 - **HARD**: invariants that must never change — recognize by: "must", "never", "always", security, privacy, cost, retention, isolation
@@ -138,137 +80,8 @@ Signals that decomposition is needed (Decompose Score 0–5):
 
 Score 0–1: probably standalone. Score 2–3: discuss with the user. Score 4–5: actively propose decomposition.
 
-## Canon → File Translation
-
-After convergence, the canon is the primary instruction set for any connected agent (served via MCP resources). Additionally, project specification files may be derived. The source for translation is the dialog (canon). The summary is used for navigation but never as authoritative source.
-
-### Primary Path (MCP-native)
-
-Any MCP client reads the canon directly via:
-- `pantion://canons/{name}/dialog` — the full dialog (source of truth)
-- `pantion://canons/{name}/summary` — derived summary (for navigation)
-- `pantion://dialogs/{name}/rules` — dialog-specific rules and translation instructions
-
-No agent-specific intermediate files are needed. The canon IS the instruction set.
-
-### Project Specification Files (via translate)
-
-The translate step produces project-specific deliverables (not agent-specific instruction files):
-
-| Canon element | Project specification file |
-|--------------|--------------------------|
-| System intent, requirements, success criteria | canon/{naam}/spec/requirements.md |
-| HARD constraints, forbidden actions, data policies | canon/{naam}/spec/constraints.md |
-| Success criteria, failure behavior | canon/{naam}/spec/success-criteria.md |
-| API behavior (if applicable) | canon/{naam}/spec/api-spec.md |
-| Data entities and retention (if applicable) | canon/{naam}/spec/data-model.md |
-| Component structure (if applicable) | canon/{naam}/spec/architecture.md |
-| Interfaces (if decomposed) | canon/{naam}/spec/interfaces/interface-*.md |
-
-All derived files are generated from the dialog. The summary is itself a derived file.
-
-## Traceability (always-on)
-
-Traceability is not just a step in `/pantion-translate`. It is a discipline:
-
-- With EVERY generation or regeneration of derived files → update `canon/{naam}/traceability.md`
-- With EVERY amendment → update traceability for affected files
-- During decomposition → traceability covers all canon levels
-
-Each derived file contains a comment: `<!-- Derived from: canon/{naam}/dialog.md, [date] -->`
-The summary file also contains this comment, as it is itself derived from the dialog.
-
-## Convergence Verification Table
-
-Before setting the DIALOGSPEC STAMP, the converger produces a Convergence Verification Table as proof that all 12 categories have been treated. This table is part of the last assistant message in the dialog, directly before the stamp.
-
-Format (12 rows matching the Readiness Checklist categories):
-
-| Criterium | Status |
-|-----------|--------|
-| Canon status | ✅ / ❌ |
-| Intent clarity | ✅ / ❌ |
-| Observable success | ✅ / ❌ |
-| Inputs complete | ✅ / ❌ |
-| Outputs unambiguous | ✅ / ❌ |
-| Failure specified | ✅ / ❌ |
-| Constraints absolute | ✅ / ❌ |
-| Non-goals documented | ✅ / ❌ |
-| Ambiguity handled | ✅ / ❌ |
-| Authority Budget | ✅ / ❌ |
-| Inference Policy | ✅ / ❌ |
-| Dialog stability | ✅ / ❌ |
-
-For quick mode: use ⚡ ASSUMPTION for items handled by conservative defaults.
-
-The table concludes with: "A competent coding agent can, without further interaction, build a functionally equivalent system." (or the reason why not).
-
-## DIALOGSPEC STAMP — Required Fields
-
-Every converged dialog ends with a machine-readable `=== DIALOGSPEC STAMP ===` block. The stamp contains at minimum:
-
-- **STATUS**: CONVERGED | CONVERGED (DIALOG) | CONVERGED (QUICK) | CONVERGED (REVERSE) | AMENDED | RECONVERGED | DRAFT
-- **DATE**: YYYY-MM-DD
-- **MODEL**: model-id and display name, format: `model-id (Display Name)` (e.g. `claude-opus-4-6 (Claude Opus 4.6)`, `gpt-4o-2025-01 (GPT-4o)`)
-- **CANON TYPE**: standalone | architect | interface | component
-- **PARENT**: canonical name or "none"
-- **OPEN QUESTIONS**: "none" for converged stamps, list otherwise
-- **INFERENCE POLICY**: conservative | strict
-- **STABILITY ZONES**: HARD constraints (list)
-- **FLEX ZONES**: FLEX defaults (list)
-
-Additional fields depend on status and command (see command-specific documentation). The MODEL field enables reconvergence decisions: which canons were produced by older models that might benefit from redialog with a newer model.
-
-A canon cannot be saved without a valid stamp. The server enforces this structurally.
-
-## HUMAN STAMP — Authorization Gate
-
-Every saved canon includes a `=== HUMAN STAMP ===` block that tracks human authorization. This is a mandatory gate between convergence and translation/building.
-
-### Structure
-
-```
-=== HUMAN STAMP ===
-DATE: [not set]
-ROLE: [not set]
-STATUS: PENDING
-NOTE: [not set]
-=== /HUMAN STAMP ===
-```
-
-### Status values
-
-- **PENDING**: default for new canons in full mode — awaiting human review
-- **APPROVED**: human has reviewed and authorized the canon for translation/building
-- **REJECTED**: human has reviewed and rejected the canon — needs changes
-- **AUTO-APPROVED**: automatically approved in dialog mode — the canon is immediately ready for translation
-
-### Rules
-
-1. A canon with STATUS other than APPROVED or AUTO-APPROVED may NOT be translated (`pantion_translate` blocks)
-2. The HUMAN STAMP is set via `pantion_approve` or `pantion_reject`, or automatically to AUTO-APPROVED in dialog mode
-3. When a canon is amended (`pantion_amend`) or reconverged (`pantion_redialog`), the HUMAN STAMP resets to PENDING
-4. Existing canons without a HUMAN STAMP block are treated as PENDING
-5. The HUMAN STAMP is the only allowed in-place mutation of a saved dialog file (all other changes are append-only)
-6. `pantion_check` reports HUMAN STAMP status as a warning if not APPROVED or AUTO-APPROVED
-7. `pantion_list-canons` includes the HUMAN STAMP status for each canon
-
-### Design rationale
-
-The HUMAN STAMP ensures that no canon proceeds to translation or building without authorization. In full mode (the default), this requires explicit human approval (`pantion_approve`). In dialog mode, canons are auto-approved for fast iteration. The fill-in-place design (rather than append-only) avoids cluttering the dialog with administrative stamps.
-
-## Phase Transitions
-
-The transition from convergence to building is ALWAYS a deliberate moment:
-
-1. Convergence reached → verification table produced
-2. All 12 categories ✅ → stamp set
-3. Checklist completed → all ✅
-4. **HUMAN STAMP authorized** → human approves (`pantion_approve`) or auto-approved in dialog mode
-5. Files generated → traceable to canon via Canon Anchors
-6. ONLY THEN → build mode (following `protocol/commands/build.md`)
-
-In full mode (the default), all steps require explicit completion. In dialog mode, steps 2-4 are accelerated: conservative assumptions are made and the canon is auto-approved.
-
-Large projects may remain in DRAFT across multiple sessions. Use `/pantion-resume` to continue converging later.
+## Deferred Protocol Sections
 
+The following sections are loaded at the appropriate phase — not during questioning:
+- **Stamps & Lifecycle** → loaded when checking convergence (see `core-stamps.md`)
+- **Canon Structure & Translation** → loaded when saving/translating (see `core-save.md`)