feat: scaffold protocol docs for mission stacks

• [MSN] No active missions on the board
• [EXC] Board idle, no stories queued or active
• [HLT] 2 warnings, no structural errors detected

Author: rupurt

crates/keel-cli/src/cli/commands/setup/new.rs

@@ -35,7 +35,7 @@ struct FoundationalDocSpec {
     template: &'static str,
 }
 
-const FOUNDATIONAL_DOCS: [FoundationalDocSpec; 9] = [
+const FOUNDATIONAL_DOCS: [FoundationalDocSpec; 10] = [
     FoundationalDocSpec {
         path: "CONSTITUTION.md",
         description: "collaboration philosophy and decision hierarchy",
@@ -51,6 +51,11 @@ const FOUNDATIONAL_DOCS: [FoundationalDocSpec; 9] = [
         description: "system map, boundaries, and technical seams",
         template: templates::project::ARCHITECTURE,
     },
+    FoundationalDocSpec {
+        path: "PROTOCOL.md",
+        description: "coordination protocol and data contracts, including Mission Stack rules",
+        template: templates::project::PROTOCOL,
+    },
     FoundationalDocSpec {
         path: "USER_GUIDE.md",
         description: "operator-visible product story and workflow guidance",
@@ -515,6 +520,7 @@ mod tests {
         assert!(root.join("keel.toml").is_file());
         assert!(root.join("AGENTS.md").is_file());
         assert!(root.join("INSTRUCTIONS.md").is_file());
+        assert!(root.join("PROTOCOL.md").is_file());
         assert!(root.join("GEMINI.md").is_file());
         assert!(root.join("CLAUDE.md").is_file());
         assert!(report.initialized_git);

crates/keel-core/src/infrastructure/templates.rs

@@ -87,6 +87,8 @@ pub mod project {
     pub const POLICY: &str = include_str!("../../../../templates/project/POLICY.md");
     /// Project architecture template
     pub const ARCHITECTURE: &str = include_str!("../../../../templates/project/ARCHITECTURE.md");
+    /// Project protocol template
+    pub const PROTOCOL: &str = include_str!("../../../../templates/project/PROTOCOL.md");
     /// Project user guide template
     pub const USER_GUIDE: &str = include_str!("../../../../templates/project/USER_GUIDE.md");
     /// Project agents template
@@ -291,6 +293,13 @@ mod tests {
         assert!(project::AGENTS.contains("downstream from Keel"));
     }
 
+    #[test]
+    fn project_protocol_template_makes_mission_stack_formal() {
+        assert!(project::PROTOCOL.contains("Mission Stacks are a formal Keel protocol"));
+        assert!(project::PROTOCOL.contains("stack/<id>"));
+        assert!(project::PROTOCOL.contains("managed worktree"));
+    }
+
     #[test]
     fn project_keel_toml_template_exposes_workflow_defaults() {
         assert!(project::KEEL_TOML.contains("board_dir = \"{{board_dir}}\""));

templates/project/AGENTS.md

@@ -12,7 +12,7 @@ This repository uses Keel as its project-management engine. This file is downstr
 
 1. `INSTRUCTIONS.md` for the repo's procedural turn loop.
 2. `POLICY.md` for local operational invariants.
-3. `ARCHITECTURE.md` and `USER_GUIDE.md` for product and system context.
+3. `ARCHITECTURE.md`, `PROTOCOL.md`, and `USER_GUIDE.md` for system, coordination, and product context.
 4. `CODE_WALKTHROUGH.md` for source layout and key abstractions.
 5. `keel turn`, `keel mission next --status`, and `keel doctor --status` for the live board state.
 
@@ -21,6 +21,7 @@ This repository uses Keel as its project-management engine. This file is downstr
 - Use Keel as the canonical planning and lifecycle surface.
 - Prefer explicit proof over chat-only claims.
 - Close loop debt with sealing commits instead of leaving dirty work behind.
+- Treat Mission Stack coordination as a formal protocol defined in `PROTOCOL.md`, not as ad hoc repo folklore.
 - Escalate only when the work requires human product, design, legal, or operational judgment.
 
 ## Decision Resolution Hierarchy
@@ -40,6 +41,7 @@ These define the constraints and workflow of the {{project_name}} environment:
 - `POLICY.md` — Operational invariants and engine constraints.
 - `CONSTITUTION.md` — Collaboration philosophy and decision hierarchy.
 - `ARCHITECTURE.md` — Implementation architecture and technical boundaries.
+- `PROTOCOL.md` — Coordination protocol and data contracts, including Mission Stack rules.
 - `CODE_WALKTHROUGH.md` — Source layout, key abstractions, and data-flow orientation.
 - `USER_GUIDE.md` — Operator-visible product story and workflow guidance.
 - `.keel/adrs/` — Binding architecture decisions.

templates/project/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # {{project_name}} Architecture
 
-This document is downstream from Keel and should describe the actual technical shape of {{project_name}}. Keel owns the board engine; this file should explain the repo, runtime, and technical seams that agents need to understand before they change behavior.
+This document is downstream from Keel and should describe the actual technical shape of {{project_name}}. Keel owns the board engine; this file should explain the repo, runtime, and technical seams that agents need to understand before they change behavior. Protocol-level coordination rules, including Mission Stack behavior, belong in `PROTOCOL.md`.
 
 ## System Map
 
@@ -25,8 +25,15 @@ Document the major components and their responsibilities.
 - Which modules should remain thin?
 - Which dependencies or abstractions are intentionally avoided?
 
+## Protocol Boundaries
+
+- Where do external or Mission Stack requests enter the system?
+- Where is repo-local board authority enforced?
+- Which surfaces validate or emit stack handoffs, receipts, acknowledgments, or managed-worktree rules?
+
 ## Operational Seams
 
 - Note the verification surfaces that matter in this repo.
 - Note any architecture decisions enforced by ADRs.
 - Note any areas where future agents should be especially conservative.
+- Note how formal protocol surfaces intersect with runtime or delivery code.

templates/project/CLAUDE.md

@@ -10,6 +10,7 @@ Before doing work, read:
 2. `INSTRUCTIONS.md`
 3. `POLICY.md`
 4. `ARCHITECTURE.md`
+5. `PROTOCOL.md`
 
 Those files are the repo-wide operating contract. This file should stay thin and only capture Claude-specific harness notes.
 

templates/project/CODE_WALKTHROUGH.md

@@ -1,6 +1,6 @@
 # {{project_name}} Code Walkthrough
 
-This document orients contributors and agents to the source layout, key abstractions, and data flows in the {{project_name}} codebase. For governance philosophy see [CONSTITUTION.md](CONSTITUTION.md); for architectural contracts see [ARCHITECTURE.md](ARCHITECTURE.md).
+This document orients contributors and agents to the source layout, key abstractions, and data flows in the {{project_name}} codebase. For governance philosophy see [CONSTITUTION.md](CONSTITUTION.md); for architectural contracts see [ARCHITECTURE.md](ARCHITECTURE.md); for coordination and Mission Stack rules see [PROTOCOL.md](PROTOCOL.md).
 
 ## Repository Layout
 
@@ -33,6 +33,7 @@ Trace a representative operation from entry point to completion.
 - Where does user input enter the system?
 - What validation or enforcement happens before execution?
 - How are results persisted and presented back?
+- Where do external or Mission Stack requests get normalized before local board mutations?
 
 ## Configuration
 

templates/project/GEMINI.md

@@ -10,6 +10,7 @@ Before doing work, read:
 2. `INSTRUCTIONS.md`
 3. `POLICY.md`
 4. `ARCHITECTURE.md`
+5. `PROTOCOL.md`
 
 Those files are the repo-wide operating contract. This file should stay thin and only capture Gemini-specific harness notes.
 

templates/project/INSTRUCTIONS.md

@@ -6,6 +6,8 @@ Procedural instructions for humans and agents working with {{project_name}} thro
 
 This file is downstream from Keel and should keep the engine's turn-loop discipline recognizable while describing how {{project_name}} actually operates.
 
+Mission Stack coordination is part of the formal downstream protocol surface. Hydrate `PROTOCOL.md` instead of inventing ad hoc cross-repo rules in chat or commit lore.
+
 When syncing from a newer Keel version, preserve the `PROJECT-SPECIFIC` block instead of re-authoring the local operating surface from scratch.
 
 ## The Turn Loop
@@ -46,6 +48,7 @@ Focus on **technical discovery and fog reduction**.
 - Add the exact build, test, runtime, or preview commands this repo expects.
 - Add any mandatory local wrappers such as `just check`, `pnpm test`, `cargo test`, or deploy smoke tests.
 - Add role-specific expectations if the repo uses designer, marketer, legal, or executive lanes in practice.
+- If this repo participates in Mission Stacks, point to the branch, checkpoint, handoff, and managed-worktree rules in `PROTOCOL.md`.
 <!-- END PROJECT-SPECIFIC -->
 
 ## Hydration Checklist
@@ -61,5 +64,6 @@ Before relying on this file as a real operating contract, fill in:
 
 - Use the CLI as the canonical lifecycle surface.
 - Prefer board-backed proof over memory or chat summaries.
+- Treat Mission Stack coordination as a formal protocol. Another repo must not mutate this repo's `{{board_dir}}/` state directly.
 - Keep downstream wrappers truthful about the real repo commands.
 - Update this file when the repo workflow changes materially.

templates/project/POLICY.md

@@ -9,6 +9,7 @@ This document is downstream from Keel and should describe the operational invari
 - The board lives in `{{board_dir}}/`.
 - The canonical tactical rhythm is the Turn Loop exposed by `keel turn`.
 - Board mutations, proof, and lifecycle closure happen through the CLI, not manual file edits.
+- Cross-repo coordination, including Mission Stacks, follows `PROTOCOL.md`; no peer repo or reactor may mutate this repo's `{{board_dir}}/` state directly.
 
 ## The Core Objective: Zero Drift
 
@@ -34,6 +35,7 @@ Hydrate the rules that should always be true in this repository.
 - What must pass before a change can land?
 - What kinds of changes require explicit human review?
 - What evidence is required for code, product, UX, legal, or operational claims?
+- Which Mission Stack or external-ingress rules are binding for cross-repo work in this repository?
 
 ## Safety Rails
 

templates/project/PROTOCOL.md

@@ -0,0 +1,50 @@
+# {{project_name}} Protocol
+
+This document is downstream from Keel and should describe the protocol surfaces that external systems, peer reactors, and operators rely on when coordinating work with {{project_name}}.
+
+## Downstream Contract
+
+Use this file for stable coordination rules and data contracts, not for local implementation details.
+
+Mission Stack coordination is part of the formal protocol surface. It should be documented here as an explicit contract rather than left as chat lore or repo-local habit.
+
+## Protocol Scope
+
+Hydrate the protocol surfaces that matter in this repository:
+
+- ingress requests from humans, agents, or upstream systems
+- repo-to-repo handoff receipts
+- lifecycle acknowledgments and checkpoint signals
+- file, API, webhook, or queue payloads that other systems consume
+
+## Mission Stack Coordination
+
+Mission Stacks are a formal Keel protocol for cross-repo execution.
+
+- Each participating repository remains authoritative for its own `{{board_dir}}/` state.
+- Cross-repo work should flow through explicit stack negotiation and handoff rather than direct mutation of another repo's planning artifacts.
+- Stack-linked work should use `stack/<id>` as the coordination branch unless this repo intentionally documents a narrower rule here.
+- Foreign execution in another member repo should happen through a managed worktree rather than that repo's primary checkout.
+- Hydrate any repo-specific checkpoint, receipt, approval, or cleanup expectations here.
+
+## External Ingress
+
+Describe how outside work enters {{project_name}}:
+
+- accepted request shapes
+- validation and acknowledgment
+- how requests materialize into local mission lineage
+- rejection or retry behavior
+
+## Data Contracts
+
+Document stable contracts that other systems rely on:
+
+- input shapes
+- output shapes
+- receipt or acknowledgment fields
+- versioning or migration expectations
+
+## Local Exceptions
+
+If {{project_name}} intentionally narrows or extends Keel's default protocol rules, document those deviations explicitly here.