@pantion/mcp-server 0.1.0

package/protocol/commands/update.md

@@ -0,0 +1,205 @@
+# /pantion-update — Upgrade the Pantion Protocol itself
+
+This command upgrades the Pantion Protocol itself — the protocol files, commands, rules, and templates.
+It uses the intent documents as source and your (newer) model capabilities to improve the protocol.
+
+---
+
+## WARNING
+
+**This command modifies the protocol, not a project.**
+
+Consequences:
+- New commands may work differently than the previous version
+- Existing canons may not be fully compatible with the new protocol
+- Project specification files (spec/*) generated with the old version may be outdated
+
+**This is NOT backward compatible by default.**
+
+After an update, you must run `pantion_migrate` on every project that used the old version.
+
+---
+
+## WHEN YOU ARRIVE HERE
+
+- You have access to a more powerful model than the one Pantion was originally built with
+- You want to improve the protocol with new insights
+- You want to regenerate the protocol files based on the intent documents
+
+---
+
+## STEP 0: CHECK PREREQUISITES
+
+Verify the intent documents are present:
+
+- [ ] `protocol/pantion-intent.md` — the intent and goals of Pantion
+- [ ] `protocol/pantion-future-prompt.md` — instructions for future rebuilding
+
+If these are missing:
+"I cannot upgrade the protocol without the intent documents. These files describe WHAT Pantion should be — without them I have no source of truth for the rebuild. Do you have them available?"
+
+---
+
+## STEP 1: INVENTORY CURRENT VERSION
+
+Read all current protocol files and produce a snapshot:
+
+```markdown
+## Pantion Version Snapshot
+
+**Date:** [today]
+**Files:** [count]
+**Commands:** [list]
+**Rules:** [list]
+**Skills:** [list]
+
+### Core concepts in current version:
+- [concept 1: short description]
+- [concept 2: short description]
+- ...
+```
+
+Save as `protocol/snapshots/pantion-snapshot-[date].md` (keep this — you'll need it if the update fails).
+
+---
+
+## STEP 2: READ INTENT DOCUMENTS
+
+Read both documents carefully:
+
+### From `protocol/pantion-intent.md` extract:
+- The core principles (what MUST remain)
+- The core promise (the touchstone)
+- The two directions (forward/reverse)
+- The scale levels
+
+### From `protocol/pantion-future-prompt.md` extract:
+- What works well (KEEP)
+- What can be improved (IMPROVE)
+- What you must NOT do
+- The ultimate test
+
+---
+
+## STEP 3: DELTA ANALYSIS
+
+Compare the current protocol files with the intent documents and your own insights:
+
+"Here is my analysis of what can be improved:
+
+**Keep (works well):**
+- [element]: [why it works]
+
+**Improve (can be better with current model capabilities):**
+- [element]: [what can be better] -> [how]
+
+**Add (missing, fits the intent):**
+- [element]: [why it fits]
+
+**Remove (has become redundant):**
+- [element]: [why it's no longer needed]
+
+**Risks of this update:**
+- [risk 1]: backward compatibility impact
+- [risk 2]: ...
+
+Would you like me to proceed with this update? You can also exclude specific items."
+
+**WAIT FOR CONFIRMATION.** Do not proceed without explicit approval.
+
+---
+
+## STEP 4: REGENERATE
+
+After confirmation, regenerate the protocol files:
+
+### Order:
+1. **`pantion-core.md`** first — this is the knowledge base everything depends on
+2. **Commands** in logical order
+3. **Skills**: update bundled skill files if needed
+4. **Souls**: update bundled soul files if needed
+
+### Rules for regeneration:
+- Each new file must respect the intent documents
+- The core principles are HARD — they must not disappear
+- The core promise is the touchstone: "code is replaceable, intent is rebuildable"
+- New concepts may only be added if they fit the intent
+- The protocol must remain simple — if it needs a 50-page manual, something is wrong
+
+---
+
+## STEP 5: SELF-CHECK
+
+After regeneration, check the new version against the intent documents:
+
+- [ ] Respects the core principles?
+- [ ] Core promise intact?
+- [ ] Not too complex?
+- [ ] No DSL or formal schema introduced?
+- [ ] Not tool-specific?
+- [ ] No features added that nobody asked for?
+- [ ] Ultimate test: can a human produce a buildable canon after one session?
+
+---
+
+## STEP 6: CHANGELOG
+
+Produce a changelog:
+
+```markdown
+# Pantion Changelog — [date]
+
+## Previous version: [snapshot date]
+## New version: [date]
+## Model: [which model performed this update]
+
+### Changed:
+- [file]: [what changed and why]
+
+### Added:
+- [file]: [why]
+
+### Removed:
+- [file]: [why]
+
+### Backward compatibility:
+- [breaking/compatible]: [impact on existing projects]
+
+### Migration needed:
+- [project type]: use `pantion_migrate` with [instruction]
+```
+
+Save as `protocol/snapshots/pantion-changelog-[date].md`.
+
+---
+
+## STEP 7: REPORT
+
+"The Pantion Protocol has been updated.
+
+**Changed:** [N] files
+**Added:** [N] files
+**Removed:** [N] files
+
+**Breaking changes:** [yes/no]
+[if yes: list]
+
+**Previous version saved in:** `protocol/snapshots/pantion-snapshot-[date].md`
+**Changelog:** `protocol/snapshots/pantion-changelog-[date].md`
+
+If you have existing projects that use Pantion:
+Run `pantion_migrate` in each project to update the project files.
+
+Would you like to keep the snapshot as a rollback option, or are you satisfied with the update?"
+
+---
+
+## META NOTE
+
+This command applies Pantion's own principles to Pantion itself:
+- The intent documents are the canon of Pantion
+- The protocol files are the derived implementation
+- `pantion_update` is essentially `pantion_reverse` + `pantion_translate` on the protocol itself
+- The snapshot is the amendment history
+
+The protocol that says "code is replaceable, intent is rebuildable" must apply that to itself as well.

package/protocol/commands/validate.md

@@ -0,0 +1,137 @@
+# /pantion-validate — Blind Reconstruction Test
+
+A validation test that proves a converged canon is sufficient to reconstruct the system without external knowledge.
+
+---
+
+## Purpose
+
+This test answers one question:
+
+> **Can a coding agent, without seeing the source code, reconstruct a functionally equivalent system from only the converged canon?**
+
+This is not a daily checklist. This is a proof that the canon is complete enough for autonomous implementation.
+
+---
+
+## When to Run
+
+- After completing your first DialogSpec with stamp
+- Before presenting the canon to other agents or developers
+- When in doubt whether the convergence is deep enough
+- As validation for a new domain
+- When `/pantion-check` recommends it
+
+---
+
+## STEP 1: Setup
+
+1. Select the canon to validate
+2. The testing agent receives ONLY:
+   - The converged dialog (canon)
+   - One sentence: "This is the behavior that was once realized by an existing system."
+3. The testing agent does NOT receive:
+   - Source code
+   - Architecture documents
+   - Technology hints
+   - Implementation notes
+
+---
+
+## STEP 2: Reconstruction
+
+Ask the testing agent:
+
+> "Build a system that is functionally equivalent to this behavior."
+
+The agent must:
+1. Reconstruct the behavior from: goals, success criteria, failure behavior, constraints, non-goals, authority budget
+2. Choose its own: language, runtime, libraries, architecture
+3. Produce derived evidence artifacts:
+   - Behavior Map (from `protocol/templates/behavior-map.md`)
+   - Acceptance Tests (from `protocol/templates/acceptance-tests.md`)
+   - Traceability Map (from `protocol/templates/traceability-map.md`)
+
+The agent must NOT:
+- Add behavior not in the canon
+- Reinterpret the intent
+- Assume implicit permissions
+- Relax constraints
+
+---
+
+## STEP 3: Acceptance Criteria
+
+Measure on **behavioral equivalence**, not code similarity.
+
+### Pass if:
+
+| Criterion | Verification |
+|-----------|-------------|
+| All described intents observably work | Functional tests |
+| All non-goals are respected | Negative tests |
+| Constraints are demonstrably enforced | Security/audit review |
+| Authority budget is demonstrably enforced | Permissions review + tests |
+| Unknown edge cases are handled conservatively | Edge case tests |
+| The system is explainable | Docs + mapping |
+| Traceability exists | Test/behavior -> dialog passage |
+
+### Fail if:
+
+| Fail signal | Meaning |
+|------------|---------|
+| Agent needs to ask questions already answered in the canon | Dialog was not converged |
+| Agent "must guess" between multiple plausible interpretations | Inference policy / open questions failed |
+| Agent wants to introduce its own canonical spec | Dialog was not complete |
+| Unexplainable behavior emerges | Agent interpreted beyond canon |
+| Implementation can do more than intended | Non-goals/constraints not respected |
+| Power/data boundaries are vague or too broad | Authority budget missing or failing |
+
+---
+
+## STEP 4: Report
+
+### On success:
+
+```markdown
+## Validation Report
+
+**System:** [name]
+**Canon:** [path to dialog]
+**Testing Agent:** [which agent]
+**Date:** [date]
+
+### Result: PASS
+
+**Chosen stack:** [what the agent chose]
+**Build time:** [duration]
+**Questions asked:** [0 = ideal]
+
+### Behavior verification:
+- [x] Intent 1: works
+- [x] Non-goal 1: respected
+- [x] Constraint 1: enforced
+- [x] Authority budget: enforced
+
+### Evidence:
+- Behavior Map: [path]
+- Acceptance Tests: [path]
+- Traceability Map: [path]
+
+### Observations:
+[What stood out, what the agent did well/differently]
+```
+
+### On failure:
+
+```markdown
+## Validation Report
+
+**Result: FAIL**
+
+### Failure reason:
+[What went wrong]
+
+### Implication for the canon:
+[What needs to change in the dialog or protocol]
+```

package/protocol/core-advanced.md

@@ -0,0 +1,188 @@
+# Pantion DialogSpec — Advanced Protocol Knowledge
+
+> This file contains advanced protocol knowledge that is loaded on-demand
+> for specific commands (decompose, reverse, redialog, create-skill, reskill).
+> For core protocol knowledge loaded in every session, see core.md.
+
+## Decomposition — Full Protocol
+
+Three levels:
+- **Architect Canon**: decomposes the system, defines shared boundaries
+- **Interface Canon**: describes the contract between two subsystems
+- **Component Canon**: buildable part with its own convergence
+
+Inheritance: constraints are additive (stricter is allowed, looser is not), authority budget Rights are a ceiling, Consumption is allocatable.
+
+## Interface Canon — Contract Fields
+
+Each Interface Canon describes at minimum:
+- Parties (which subsystems)
+- Delivered value (both directions)
+- Guarantees (what is always true)
+- Expectations (what may the receiver assume)
+- Failure behavior (what if something goes wrong)
+
+Plus five additional fields:
+- **Data Shape**: what is exchanged, described enumeratively (in natural language, not as a schema)
+- **Versioning/Compat**: what breaks compatibility? What is a backward-compatible change?
+- **Error Semantics**: what specific errors may B expect from A? How are they signaled?
+- **Privacy/Classification**: which data is PII, confidential, or classified? Which side may see what?
+- **Rate/Cost Expectations**: what is "normal" usage? What is a peak? Where are the limits?
+
+## Canon Anchors
+
+Canon Anchors are references to specific dialog turns. They enable traceability from derived artifacts (behavior map, acceptance tests, implementation) back to the canonical dialog.
+
+Notation: **H[N]** for HUMAN turn N, **A[N]** for ASSISTANT turn N (1-indexed).
+
+Example: H1 = first human message, A3 = third assistant message.
+
+Canon Anchors are used in:
+- Behavior Maps: every behavior links to the dialog turn that defines it
+- Acceptance Tests: every test cites the dialog turn it validates
+- Traceability Maps: full mapping from Canon Anchor to requirement to test to implementation
+- Implementation code comments: `// Canon Anchor: H3, A4`
+
+## Blind Reconstruction Test
+
+The ultimate validation of a converged canon: can a coding agent, without seeing source code, reconstruct the system from only the canon?
+
+Use `/pantion-validate` to run this test. See `protocol/commands/validate.md` for the full methodology.
+
+## Reverse Pantion (Code → Canon)
+
+In addition to the normal flow (Intent → Canon → Code), Pantion supports the reverse direction: analyzing an existing codebase and reconstructing the intent as a canon.
+
+Core principle: extract **what** the code does, not **how**. The output is a synthetic dialog that reads as if it were originally conducted.
+
+Applications: legacy migration, technology swap, documentation, audit, proof that intent canonization works.
+
+The output is a synthetic dialog that reads as if it were originally conducted. This dialog is the canon. A derived summary is generated alongside it.
+
+The generated canon gets STATUS: CONVERGED (REVERSE) and contains an extra AMBIGUITIES field for "bug or feature?" points. Traceability points in reverse: from canon element to source code location, with a confidence level (high/medium/low).
+
+The ultimate test: Code → Canon → Code' → behavior(Code) ≈ behavior(Code')
+
+## Re-convergence (Canon → Better Canon)
+
+The dialog is conducted by a specific model at a specific time. A newer or more capable model may identify gaps: questions that should have been asked, assumptions that were never made explicit, edge cases that were not explored. The answers to never-asked questions are simply not in the canon.
+
+**Re-convergence** is the solution: a better model reads the existing dialog, produces a gap analysis, and conducts a supplementary dialog with the user to fill those gaps. The original dialog stays intact (append-only).
+
+### How re-convergence differs from other commands
+
+| | Resume | Amend | Reconverge |
+|---|--------|-------|------------|
+| **Entry condition** | DRAFT with open questions | CONVERGED — user wants a change | CONVERGED — model identifies gaps |
+| **Who initiates** | User (wants to finish) | User (wants to change something) | Model (detects gaps) |
+| **Primary action** | Answer remaining open questions | Apply a specific change | Gap analysis → targeted supplementary dialog |
+| **Result status** | CONVERGED | AMENDED | RECONVERGED |
+
+### When to reconverge
+
+- **Model upgrade**: a significantly better model is available
+- **Periodic review**: important canons should be re-evaluated periodically
+- **Dissatisfaction**: the implementation reveals that the original convergence was too shallow
+- **New domain knowledge**: insights that weren't available during the original dialog
+- **Check recommendation**: `/pantion-check` detected thin or missing elements
+
+### Gap analysis dimensions
+
+1. **Unexplored convergence elements** — checklist items that are thin or absent
+2. **Implicit assumptions** — things assumed without being made explicit
+3. **Ambiguous resolutions** — vague answers that should have been probed further
+4. **Missing edge cases** — failure modes, boundary conditions not discussed
+5. **Authority budget gaps** — rights, consumption, or forbidden actions underspecified
+6. **Interface gaps** — contracts between components incomplete (for decomposed systems)
+
+### The future-proof promise
+
+The true future-proofing of Pantion is not just re-derivation (better artifacts from the same dialog) but **re-convergence** (a deeper dialog built on top of the original). The original dialog preserves the user's voice, decisions, priorities, and domain context — a better model uses this as a foundation, not a limitation.
+
+Use `/pantion-redialog` (alias: `/pantion-reconverge`) to initiate a redialog.
+
+## Souls (Interaction Style)
+
+A **soul** is a configurable interaction style that determines *how* the convergence dialog is conducted — the tone, pacing, jargon level, and questioning approach. It does NOT change *what* is discussed: convergence requirements (intent, constraints, success criteria, authority budget) remain identical regardless of soul.
+
+### How souls differ from skills
+
+| | Skill | Soul |
+|---|-------|------|
+| **Determines** | What convergence elements to cover (domain-specific) | How to communicate during convergence |
+| **Examples** | Software Development, Image Description | Balanced Professional, Beginner Friendly, Young Builder |
+| **Composable** | One skill per session | One soul per session, works with any skill |
+| **Location** | `skills/` directory | `souls/` directory |
+
+### Soul structure
+
+```
+souls/{name}/
+├── soul.json     (manifest: name, displayName, description, version)
+└── rules.md      (interaction rules — injected into system prompt)
+```
+
+### Search order
+
+Same as skills: project-local (`souls/`) → user-global (`~/.pantion/souls/`) → bundled.
+
+### Built-in souls
+
+- **default** — Balanced Professional: clear, direct, systematic. Used when no soul is specified.
+- **beginner** — Beginner Friendly: extra explanation, less jargon, smaller steps, understanding checks.
+- **young** — Young Builder: simple language, concrete examples, encouraging tone. For young users building their first project.
+
+### Rules
+
+- Soul rules are injected into the system prompt after skill rules
+- The soul is saved in the session (traceability: which style was used)
+- If no soul is specified, the "default" soul is used
+- Soul rules must never weaken convergence requirements — they only change presentation
+- Custom souls can be created by adding a directory to `souls/` (project-local or `~/.pantion/souls/`)
+
+## Dynamic Skills (Skills from Canons)
+
+Skills can be created through Pantion dialogs, making them **model-proof**. Instead of hand-crafting skill files, a user converges on domain knowledge through a skill-builder dialog. The resulting canon is the source of truth from which all skill files are derived.
+
+### Skill Canon Structure
+
+Dynamic skills store their source canon alongside the derived skill files:
+
+```
+skills/{name}/
+├── skill.json                 ← DERIVED from skill-canon
+├── convergence-rules.md       ← DERIVED from skill-canon
+├── translate.md               ← DERIVED from skill-canon
+├── prompts/                   ← DERIVED from skill-canon
+│   ├── convergence-intro.md
+│   └── translate-intro.md
+└── canon/                     ← SOURCE (model-proof)
+    ├── skill-dialog.md        ← THE CANON
+    └── skill-summary.md       ← DERIVED
+```
+
+### The Skill-Builder Meta-Skill
+
+The `skill-builder` is a bundled meta-skill that knows how to converge on domain knowledge. It guides the user through: what is this domain? What decisions matter? What do agents get wrong? What output should the skill produce?
+
+### Skill Canon Lifecycle
+
+- `pantion_create-skill`: start a skill dialog using the skill-builder
+- `pantion_save-canon` (with `skill_name`): save the skill canon to `skills/{name}/canon/`
+- `pantion_translate`: translate the skill canon into skill files
+- `pantion_reskill`: reconverge an existing skill canon to deepen domain knowledge
+
+### Compatibility
+
+- Existing bundled skills (software, image) work exactly as before — no canon needed
+- Dynamic skills are loaded by the same registry with `source: 'dynamic'`
+- The three-tier search (project > user > bundled) works for both hand-crafted and dynamic skills
+- A dynamic skill can override a bundled skill (project-local takes priority)
+
+### Rules
+
+- The skill dialog is the canon — skill files are derived
+- Skill canons are stored in `skills/{name}/canon/`, NOT in the project `canon/` directory
+- Skill canons do NOT appear in the project `canon/index.md`
+- Reconvergence on a skill canon (`pantion_reskill`) uses skill-builder rules
+- The skill-builder meta-skill is bundled and evolves only through protocol updates