@jaggerxtrm/specialists 3.17.0 → 3.18.0

package/docs/design/roadmap/chain-templates/doc-sync.formula.json

@@ -0,0 +1,28 @@
+{
+  "formula": "doc-sync",
+  "type": "workflow",
+  "version": 1,
+  "description": "Single-document drift-aware update. sync-docs reads scoped report/commit context + the target doc + applies minimal-diff updates. For one doc at a time — not broad rewrites, not multi-doc audits.",
+  "vars": {
+    "root_title": { "default": "Sync doc with recent changes", "required": false },
+    "doc_path": { "default": "docs/README.md", "required": false },
+    "context_scope": { "default": "src/**", "required": false }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "chore",
+      "description": "PROBLEM: doc at {{doc_path}} has drifted from current code/behavior. Reconcile minimal-diff.\nSCOPE: {{doc_path}} only.\nNON_GOALS: no broad rewrites; no style changes; no other docs touched; no code edits.\nVALIDATION: doc accurately describes current behavior in {{context_scope}}; no orphan references to removed symbols.\nACCEPTANCE: doc is current; minimal diff (preserves existing structure where accurate).\n\nDoc-sync chain — single-doc drift update.",
+      "labels": ["chain-root", "kind:root", "type:chore", "documentation"]
+    },
+    {
+      "id": "sync-docs",
+      "title": "sync-docs:{{root_title}}",
+      "type": "task",
+      "needs": ["root"],
+      "description": "MANDATE: single-document drift-aware update. Read doc + relevant code context + recent commits/reports; apply minimal-diff edits to reconcile.\nINPUTS: {{doc_path}} current content; {{context_scope}} current code; recent xt reports referencing related changes.\nOUTPUTS: edited {{doc_path}} with minimal diff. Preserve structure; update content. Drift-detector pre-script runs before specialist starts.\nSCOPE: {{doc_path}} only.\nNON_GOALS: no broad rewrites; no style changes; no multi-doc audits; no code edits.",
+      "labels": ["chain-step", "kind:step", "role:sync-docs", "edge:implements->root"]
+    }
+  ]
+}

package/docs/design/roadmap/chain-templates/memory-hygiene.formula.json

@@ -0,0 +1,27 @@
+{
+  "formula": "memory-hygiene",
+  "type": "workflow",
+  "version": 1,
+  "description": "Memory consolidation pass. memory-processor curates persistent project memory into .xtrm/memory.md. Use after many closed runs or when stale/contradictory memories accumulate (e.g., post-epic completion). Single specialist, writes memory summary only.",
+  "vars": {
+    "root_title": { "default": "Memory hygiene pass", "required": false },
+    "trigger_reason": { "default": "post-epic-close", "required": false }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "chore",
+      "description": "PROBLEM: persistent project memory has accumulated stale, redundant, or contradictory entries. Reason: {{trigger_reason}}.\nSCOPE: .xtrm/memory.md + bd memories (project-scope).\nNON_GOALS: no code edits; no bd issue edits; no specialist edits; no removal of memories that are still relevant (only consolidate / dedupe / archive stale).\nVALIDATION: memory.md is current, dedupe'd, contradictions resolved. Bulk-export pre-script runs before specialist starts.\nACCEPTANCE: future sessions read consolidated memory and pick up relevant context faster.\n\nMemory hygiene chain — curates persistent memory.",
+      "labels": ["chain-root", "kind:root", "type:chore", "memory", "hygiene"]
+    },
+    {
+      "id": "memory-processor",
+      "title": "memory-processor:{{root_title}}",
+      "type": "task",
+      "needs": ["root"],
+      "description": "MANDATE: curate persistent project memory. Dedupe duplicates; consolidate related memories; archive stale (older than relevance window without recent reference); resolve contradictions (newest-wins unless explicitly marked); update .xtrm/memory.md with the consolidated summary.\nINPUTS: bd memories (full list, JSON); current .xtrm/memory.md; recent activity surface (which memories were referenced recently).\nOUTPUTS: edited .xtrm/memory.md with consolidated summary; structured report of: dedupe count, consolidate count, archive count, contradictions resolved. Optionally: list of bd kv keys to forget.\nSCOPE: .xtrm/memory.md + memory-processor's own bd queries.\nNON_GOALS: no code edits; no bd issue edits; no memories removed without explicit archive reason.",
+      "labels": ["chain-step", "kind:step", "role:memory-processor", "edge:implements->root"]
+    }
+  ]
+}

package/docs/design/roadmap/chain-templates/planning.formula.json

@@ -0,0 +1,27 @@
+{
+  "formula": "planning",
+  "type": "workflow",
+  "version": 1,
+  "description": "Turn vague feature/initiative into a phased bd issue board with dependencies and test planning. Single specialist (planner, HIGH-authority). Output is an executable bd issue graph the operator dispatches subsequent chains against.",
+  "vars": {
+    "root_title": { "default": "Untitled initiative", "required": false },
+    "scope": { "default": "src/**", "required": false }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "task",
+      "description": "PROBLEM: (the broad initiative — what we want to deliver and why)\nSCOPE: {{scope}} (initial; planner may propose expansion)\nNON_GOALS: NO implementation in this chain — planning only; no architecture decisions beyond what's needed for phasing.\nVALIDATION: planner produces a phased bd issue board with dependencies; each phase has acceptance criteria; test planning included.\nACCEPTANCE: operator can dispatch sub-chains against the planned board.\n\nPlanning chain — turn vague into structured work graph.",
+      "labels": ["chain-root", "kind:root", "type:task", "planning"]
+    },
+    {
+      "id": "planner",
+      "title": "planner:{{root_title}}",
+      "type": "task",
+      "needs": ["root"],
+      "description": "MANDATE: turn root's initiative into a phased bd issue board with dependencies, test planning, and acceptance criteria per phase. HIGH planning authority.\nINPUTS: root's PROBLEM + SCOPE; current codebase shape (read via grep/find/explorer-equivalent capability).\nOUTPUTS: bd issues created via bd create with proper --parent/--deps; each issue has change-contract sections; phases identified; companion test issues filed. Final summary memo lists the bead-ids + phase order.\nSCOPE: bd graph + design proposals; no code edits.\nNON_GOALS: no implementation; no architecture lock-in beyond what's needed to phase; no test execution.",
+      "labels": ["chain-step", "kind:step", "role:planner", "edge:implements->root"]
+    }
+  ]
+}

package/docs/design/roadmap/chain-templates/premortem.formula.json

@@ -0,0 +1,26 @@
+{
+  "formula": "premortem",
+  "type": "workflow",
+  "version": 1,
+  "description": "Devil's-advocate review of a risky design / architecture / tradeoff decision BEFORE implementation. Single specialist (overthinker, READ_ONLY, 4-phase chain-of-thought). Output is a structured premortem memo with explicit uncertainty + actionable mitigations. Forces the orchestrator to consult overthinker before high-stakes work.",
+  "vars": {
+    "root_title": { "default": "Risky design premortem", "required": false }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "decision",
+      "description": "PROBLEM: (the risky design / architecture choice / tradeoff being considered)\nSCOPE: design space; no specific file scope (this is pre-impl analysis).\nNON_GOALS: NO implementation; no architecture lock-in (premortem informs the decision, doesn't make it); no executor dispatch from this chain.\nVALIDATION: overthinker produces 4-phase premortem memo (initial analysis → critique → synthesis → distilled recommendation).\nACCEPTANCE: operator has explicit list of risks + mitigations + uncertainty markers; operator decides whether to proceed, modify, or abandon.\n\nPremortem chain — devil's advocate before commitment.",
+      "labels": ["chain-root", "kind:root", "type:decision", "premortem", "scope-empty:code"]
+    },
+    {
+      "id": "overthinker",
+      "title": "overthinker:{{root_title}}",
+      "type": "task",
+      "needs": ["root"],
+      "description": "MANDATE: 4-phase devil's-advocate review of root's design proposal. READ_ONLY.\nINPUTS: root's PROBLEM + design proposal narrative.\nOUTPUTS: structured 4-phase markdown:\n  Phase 1 — Initial Analysis: goals, constraints, assumptions, unknowns.\n  Phase 2 — Devil's Advocate: challenge every assumption; what could go wrong; what was missed; steelman opposing views.\n  Phase 3 — Synthesis: integrate critiques; resolve contradictions; acknowledge tradeoffs.\n  Phase 4 — Final Answer: distilled recommendation with explicit uncertainty + concrete mitigations.\nSCOPE: design space; no file scope.\nNON_GOALS: NO file edits; no implementation; no architecture decisions (recommend, don't decide).",
+      "labels": ["chain-step", "kind:step", "role:overthinker", "edge:informs->root", "advisor:standalone"]
+    }
+  ]
+}

package/docs/design/roadmap/chain-templates/release-prep.formula.json

@@ -0,0 +1,36 @@
+{
+  "formula": "release-prep",
+  "type": "workflow",
+  "version": 1,
+  "description": "Release preparation. Reconciles [Unreleased] CHANGELOG.md from xt reports + commit subjects in a tag range. changelog-drafter (READ_ONLY) produces bundle synthesis first; changelog-keeper edits CHANGELOG.md. Does NOT bump version, build, commit, tag, push, or publish — operator handles those via /releasing skill.",
+  "vars": {
+    "root_title": { "default": "Release prep", "required": false },
+    "prev_tag": { "default": "HEAD~50", "required": false },
+    "next_tag": { "default": "HEAD", "required": false }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "chore",
+      "description": "PROBLEM: prepare release by reconciling [Unreleased] CHANGELOG.md from {{prev_tag}}..{{next_tag}}.\nSCOPE: CHANGELOG.md only.\nNON_GOALS: no version bump; no build; no commit/tag/push/publish; no code edits.\nVALIDATION: CHANGELOG.md [Unreleased] section populated with Added/Changed/Fixed/Removed entries reflecting commits + xt reports in range.\nACCEPTANCE: operator runs /releasing and sees populated [Unreleased] ready for version bump.\n\nRelease prep chain: drafter synthesizes, keeper writes.",
+      "labels": ["chain-root", "kind:root", "type:chore", "release"]
+    },
+    {
+      "id": "changelog-drafter",
+      "title": "changelog-drafter:{{root_title}}",
+      "type": "task",
+      "needs": ["root"],
+      "description": "MANDATE: READ_ONLY bundle synthesis from {{prev_tag}}..{{next_tag}}. Group commits and xt reports by category (Added/Changed/Fixed/Removed).\nINPUTS: git log {{prev_tag}}..{{next_tag}}; .xtrm/reports/*.md in range.\nOUTPUTS: structured draft markdown — categorized bullet list with PR/commit refs. No file edits.\nSCOPE: read-only synthesis.\nNON_GOALS: no edits; no publishing; no tagging.",
+      "labels": ["chain-step", "kind:step", "role:changelog-drafter", "edge:informs->root", "advisor:pre-impl"]
+    },
+    {
+      "id": "changelog-keeper",
+      "title": "changelog-keeper:{{root_title}}",
+      "type": "task",
+      "needs": ["changelog-drafter"],
+      "description": "MANDATE: edit CHANGELOG.md [Unreleased] section using drafter's structured draft.\nINPUTS: changelog-drafter's draft; current CHANGELOG.md.\nOUTPUTS: edited CHANGELOG.md with [Unreleased] populated. Preserves existing entries below [Unreleased]. Single-file diff.\nSCOPE: CHANGELOG.md only.\nNON_GOALS: no version bump; no build; no commit/tag/push/publish; no other files touched.",
+      "labels": ["chain-step", "kind:step", "role:changelog-keeper", "edge:implements->root"]
+    }
+  ]
+}

package/docs/design/roadmap/chain-templates/research-only.formula.json

@@ -0,0 +1,28 @@
+{
+  "formula": "research-only",
+  "type": "workflow",
+  "version": 1,
+  "description": "Investigation that deliberately does NOT produce code. Single specialist (default: explorer for local codebase; operator overrides to researcher for external sources). Output is a findings memo — saved to bd notes + optionally to a design doc. Use for: pre-feature research, post-mortem investigation, exploratory mapping.",
+  "vars": {
+    "root_title": { "default": "Untitled investigation", "required": false },
+    "scope": { "default": "src/**", "required": false },
+    "specialist": { "default": "explorer", "required": false }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "task",
+      "description": "PROBLEM: (the question being investigated)\nSCOPE: {{scope}} (or external research target)\nNON_GOALS: NO CODE CHANGES (this is research-only); no implementation; no design decisions (those go through separate planning chain).\nVALIDATION: findings memo produced; cites concrete evidence (file:line for code; URL+date for external).\nACCEPTANCE: operator has structured evidence to inform a follow-up decision.\n\nResearch-only chain. Single specialist ({{specialist}}). If external sources needed, override to researcher; if internal codebase, keep default explorer.",
+      "labels": ["chain-root", "kind:root", "type:task", "research", "scope-empty:code"]
+    },
+    {
+      "id": "investigation",
+      "title": "{{specialist}}:{{root_title}}",
+      "type": "task",
+      "needs": ["root"],
+      "description": "MANDATE: READ_ONLY investigation. Produce structured findings memo answering root's PROBLEM.\nINPUTS: root contract; relevant code in {{scope}} (for explorer) OR external sources (for researcher).\nOUTPUTS: structured findings — for explorer: call flows, dependencies, file:line evidence; for researcher: ecosystem evidence with URL+date citations. Markdown format.\nSCOPE: research-only.\nNON_GOALS: NO CODE EDITS; no implementation recommendations beyond what root asked.",
+      "labels": ["chain-step", "kind:step", "role:{{specialist}}", "edge:informs->root", "advisor:standalone"]
+    }
+  ]
+}

package/docs/design/roadmap/chain-templates/restitch.formula.json

@@ -0,0 +1,125 @@
+{
+  "formula": "restitch",
+  "type": "workflow",
+  "version": 1,
+  "description": "Conflict recovery after a failed merge. Debugger investigates the conflict + applies targeted resolution + re-validates. Seconder + QA pipeline apply after the fix.",
+  "vars": {
+    "root_title": {
+      "default": "Restitch failed merge",
+      "required": false
+    },
+    "conflict_source": {
+      "default": "",
+      "required": false
+    }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "bug",
+      "description": "PROBLEM: failed merge / conflict / restitch needed. Source: {{conflict_source}}\nSCOPE: the conflicted files identified by the failed merge.\nNON_GOALS: no scope expansion beyond conflict resolution; no refactoring; no feature additions.\nVALIDATION: targeted tests for the conflicted scope pass; integration smoke OK.\nACCEPTANCE: chain branch is mergeable cleanly to integration target.\n\nRestitch chain: debugger investigates + resolves + re-validates.",
+      "labels": [
+        "chain-root",
+        "kind:root",
+        "type:bug",
+        "restitch",
+        "conflict-recovery"
+      ]
+    },
+    {
+      "id": "debugger",
+      "title": "debugger:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "root"
+      ],
+      "description": "MANDATE: investigate conflict from {{conflict_source}}; identify whose change should win (upstream vs chain) per-hunk; apply minimal-diff resolution; re-run targeted validation.\nINPUTS: root's conflict description; git status output; conflicted files.\nOUTPUTS: resolved diff on chain branch; conflict-resolution rationale per hunk; passing targeted tests.\nSCOPE: conflicted files only.\nNON_GOALS: no scope creep; no refactoring; no `--no-verify`.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:debugger",
+        "edge:implements->root",
+        "non-skippable:true"
+      ]
+    },
+    {
+      "id": "seconder",
+      "title": "seconder:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "debugger"
+      ],
+      "description": "MANDATE: fused scope/compliance + quality gate on debugger's diff.\nINPUTS: debugger's diff; root contract.\nOUTPUTS: verdict JSON with scope_verdict, scope_findings, quality_verdict, quality_findings, overall_verdict.\nSCOPE: same as root.\nNON_GOALS: no edits.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:seconder",
+        "edge:validates->debugger",
+        "gate:mandatory"
+      ]
+    },
+    {
+      "id": "test-engineer",
+      "title": "test-engineer:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "seconder"
+      ],
+      "description": "MANDATE: write tests against the actual diff.\nINPUTS: debugger's diff; seconder verdict; root contract.\nOUTPUTS: tests, fixtures, smoke scripts, telemetry assertions, exact test-runner commands.\nSCOPE: test paths plus diff-adjacent harness code.\nNON_GOALS: no production source edits unless root explicitly authorizes helper/export change.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:test-engineer",
+        "edge:validates->debugger"
+      ]
+    },
+    {
+      "id": "test-runner",
+      "title": "test-runner:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "test-engineer"
+      ],
+      "description": "MANDATE: execute exact commands supplied by test-engineer and classify failures by owner.\nINPUTS: exact commands; tests; telemetry assertions.\nOUTPUTS: pass/fail counts, artifact evidence, owner routing, rerun guidance.\nSCOPE: requested commands only; fallback must be labeled.\nNON_GOALS: no edits; no scope expansion.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:test-runner",
+        "gate:mandatory"
+      ]
+    },
+    {
+      "id": "obligations-scanner",
+      "title": "obligations-scanner:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "test-runner"
+      ],
+      "description": "MANDATE: scan debugger's diff for unstructured markers in production code.\nINPUTS: debugger's diff.\nOUTPUTS: CLEAN | OBLIGATIONS_FOUND | BLOCKED.\nSCOPE: same as root.\nNON_GOALS: no edits.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:obligations-scanner",
+        "edge:validates->debugger",
+        "gate:mandatory"
+      ]
+    },
+    {
+      "id": "reviewer",
+      "title": "reviewer:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "obligations-scanner"
+      ],
+      "description": "MANDATE: compliance reviewer; verify restitch resolves the conflict without regressing the chain's intent.\nINPUTS: debugger diff + seconder verdict + obligations-scanner output + root's conflict context + chain's original intent.\nOUTPUTS: verdict PASS|PARTIAL|FAIL + Release Checklist.\nSCOPE: conflicted files + integration concerns.\nNON_GOALS: no edits; do not extend scope to non-conflict items.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:reviewer",
+        "edge:validates->root",
+        "gate:final"
+      ]
+    }
+  ]
+}

package/docs/design/roadmap/chain-templates/security-deep.formula.json

@@ -0,0 +1,161 @@
+{
+  "formula": "security-deep",
+  "type": "workflow",
+  "version": 1,
+  "description": "Sensitive-surface chain. Security-auditor runs TWICE: as advisor before executor (threat modeling + recommendations) and as gate after test-runner (validates implementation). For changes touching auth, secrets, crypto, migrations, agent/MCP config, lockfiles, GitHub workflows, permissions. Scrutiny defaults to critical.",
+  "vars": {
+    "root_title": {
+      "default": "Untitled sensitive change",
+      "required": false
+    },
+    "scope": {
+      "default": "src/**",
+      "required": false
+    },
+    "scrutiny": {
+      "default": "critical",
+      "required": false
+    }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "task",
+      "description": "PROBLEM: (sensitive-surface change; specify auth/secrets/crypto/migration/config aspect)\nSCOPE: {{scope}}\nNON_GOALS: (fill in)\nVALIDATION: (tests + security smoke)\nACCEPTANCE: (functional + security invariants preserved)\n\nSensitive surface. Security-auditor runs pre (advisor) AND post (gate). Reviewer scrutiny={{scrutiny}}; reviewer may auto-escalate further on surface table match.",
+      "labels": [
+        "chain-root",
+        "kind:root",
+        "scrutiny:{{scrutiny}}",
+        "surface:sensitive"
+      ]
+    },
+    {
+      "id": "security-auditor-advisor",
+      "title": "security-auditor-advisor:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "root"
+      ],
+      "description": "MANDATE: LOW-permission threat-modeling pass BEFORE executor. Identify attack surface, dependency risks, auth/secret/crypto invariants.\nINPUTS: root contract; current code at {{scope}}.\nOUTPUTS: structured recommendations for executor — invariants to preserve, tests to add, library/config choices to avoid. Cite CVE/CWE refs where applicable.\nSCOPE: {{scope}} and adjacent security boundaries.\nNON_GOALS: no edits; no exploits; recommendations only.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:security-auditor",
+        "phase:advisor",
+        "edge:informs->root"
+      ]
+    },
+    {
+      "id": "executor",
+      "title": "executor:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "security-auditor-advisor"
+      ],
+      "description": "MANDATE: implement root's deliverable per its contract, applying security-auditor-advisor's recommendations.\nINPUTS: root contract + security-auditor-advisor's structured recommendations.\nOUTPUTS: diff on chain branch satisfying ACCEPTANCE; tests per VALIDATION; security invariants preserved.\nSCOPE: same as root.\nNON_GOALS: no `--no-verify`; no scope creep into adjacent security surfaces unless advisor flagged.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:executor",
+        "edge:implements->root"
+      ]
+    },
+    {
+      "id": "seconder",
+      "title": "seconder:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "executor"
+      ],
+      "description": "MANDATE: fused scope/compliance + quality gate on executor's diff.\nINPUTS: executor's diff; root contract.\nOUTPUTS: verdict JSON with scope_verdict, scope_findings, quality_verdict, quality_findings, overall_verdict.\nSCOPE: same as root.\nNON_GOALS: no edits.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:seconder",
+        "edge:validates->executor",
+        "gate:mandatory"
+      ]
+    },
+    {
+      "id": "test-engineer",
+      "title": "test-engineer:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "seconder"
+      ],
+      "description": "MANDATE: write tests, fixtures, smoke scripts, and telemetry assertions against the actual diff.\nINPUTS: executor's diff; seconder verdict; root contract.\nOUTPUTS: tests, fixtures, smoke scripts, telemetry assertions, exact test-runner commands.\nSCOPE: test paths plus diff-adjacent harness code.\nNON_GOALS: no production source edits unless root explicitly authorizes helper/export change.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:test-engineer",
+        "edge:validates->executor"
+      ]
+    },
+    {
+      "id": "test-runner",
+      "title": "test-runner:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "test-engineer"
+      ],
+      "description": "MANDATE: execute exact commands supplied by test-engineer and classify failures by owner.\nINPUTS: exact commands; tests; telemetry assertions.\nOUTPUTS: pass/fail counts, artifact evidence, owner routing, rerun guidance.\nSCOPE: requested commands only; fallback must be labeled.\nNON_GOALS: no edits; no scope expansion.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:test-runner",
+        "gate:mandatory"
+      ]
+    },
+    {
+      "id": "security-auditor-gate",
+      "title": "security-auditor-gate:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "test-runner"
+      ],
+      "description": "MANDATE: LOW-permission validation pass AFTER test-runner. Validate executor's diff against security-auditor-advisor's recommendations + general security review.\nINPUTS: executor's diff; security-auditor-advisor's recommendations; test evidence.\nOUTPUTS: verdict OK or FINDINGS (with severity + remediation). Reviewer treats OK as pre-condition for PASS.\nSCOPE: same as root.\nNON_GOALS: no edits; no exploits.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:security-auditor",
+        "phase:gate",
+        "edge:validates->executor",
+        "gate:mandatory"
+      ]
+    },
+    {
+      "id": "obligations-scanner",
+      "title": "obligations-scanner:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "test-runner"
+      ],
+      "description": "MANDATE: scan executor's diff for unstructured markers.\nINPUTS: executor's diff.\nOUTPUTS: CLEAN | OBLIGATIONS_FOUND | BLOCKED.\nSCOPE: same as root.\nNON_GOALS: no edits.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:obligations-scanner",
+        "edge:validates->executor",
+        "gate:mandatory"
+      ]
+    },
+    {
+      "id": "reviewer",
+      "title": "reviewer:{{root_title}}",
+      "type": "task",
+      "needs": [
+        "security-auditor-gate",
+        "obligations-scanner"
+      ],
+      "description": "MANDATE: compliance reviewer at SCRUTINY={{scrutiny}} (critical by default for this template).\nINPUTS: executor diff + seconder verdict + security-auditor-gate verdict + obligations-scanner output + advisor recommendations + root contract.\nOUTPUTS: verdict PASS|PARTIAL|FAIL + Release Checklist with security-specific items.\nSCOPE: same as root.\nNON_GOALS: no edits; do not waive security-auditor-gate findings.",
+      "labels": [
+        "chain-step",
+        "kind:step",
+        "role:reviewer",
+        "edge:validates->root",
+        "gate:final"
+      ]
+    }
+  ]
+}

package/docs/design/roadmap/chain-templates/test-only.formula.json

@@ -0,0 +1,52 @@
+{
+  "formula": "test-only",
+  "type": "workflow",
+  "version": 1,
+  "description": "Single-writer test chain. test-engineer is primary writer, seconder validates scope+quality, test-runner executes exact commands, reviewer closes. No production diff by default.",
+  "vars": {
+    "root_title": { "default": "Untitled tests", "required": false },
+    "scope": { "default": "tests/**", "required": false },
+    "scrutiny": { "default": "medium", "required": false }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "task",
+      "description": "PROBLEM: (fill in: what tests need adding/updating and why)\nSCOPE: {{scope}}\nNON_GOALS: (fill in)\nVALIDATION: (fill in)\nACCEPTANCE: (fill in: externally observable outcome)\n\nTest-only chain. test-engineer is the primary writer; write tests that satisfy the bead contract.",
+      "labels": ["chain-root", "kind:root", "scrutiny:{{scrutiny}}"]
+    },
+    {
+      "id": "test-engineer",
+      "title": "test-engineer:{{root_title}}",
+      "type": "task",
+      "needs": ["root"],
+      "description": "MANDATE: you are the primary writer; write tests that satisfy the bead contract.\nINPUTS: root contract; existing test style; current implementation diff.\nOUTPUTS: tests, fixtures, smoke scripts, telemetry assertions, exact test-runner commands.\nSCOPE: test paths plus harness/fixture updates.\nNON_GOALS: no production source edits unless root explicitly authorizes helper/export change.",
+      "labels": ["chain-step", "kind:step", "role:test-engineer", "edge:validates->root", "position:primary-writer"]
+    },
+    {
+      "id": "seconder",
+      "title": "seconder:{{root_title}}",
+      "type": "task",
+      "needs": ["test-engineer"],
+      "description": "MANDATE: fused scope/compliance + quality gate on the test diff.\nINPUTS: test-engineer diff; root contract.\nOUTPUTS: verdict JSON with scope_verdict, scope_findings, quality_verdict, quality_findings, overall_verdict.\nSCOPE: same as root.\nNON_GOALS: no edits.",
+      "labels": ["chain-step", "kind:step", "role:seconder", "edge:validates->root", "gate:mandatory"]
+    },
+    {
+      "id": "test-runner",
+      "title": "test-runner:{{root_title}}",
+      "type": "task",
+      "needs": ["seconder"],
+      "description": "MANDATE: execute exact commands supplied by test-engineer and classify failures by owner.\nINPUTS: exact commands; tests; telemetry assertions.\nOUTPUTS: pass/fail counts, artifact evidence, owner routing, rerun guidance.\nSCOPE: requested commands only; fallback must be labeled.\nNON_GOALS: no edits; no scope expansion.",
+      "labels": ["chain-step", "kind:step", "role:test-runner", "gate:mandatory"]
+    },
+    {
+      "id": "reviewer",
+      "title": "reviewer:{{root_title}}",
+      "type": "task",
+      "needs": ["test-runner"],
+      "description": "MANDATE: compliance reviewer for test quality and coverage adequacy at SCRUTINY={{scrutiny}}.\nINPUTS: test diff + seconder verdict + test-runner evidence + root contract.\nOUTPUTS: verdict PASS|PARTIAL|FAIL + Release Checklist.\nSCOPE: same as root.\nNON_GOALS: no edits; do not waive mandatory gates.",
+      "labels": ["chain-step", "kind:step", "role:reviewer", "edge:validates->root", "gate:final"]
+    }
+  ]
+}

package/docs/design/roadmap/chain-templates/triage.formula.json

@@ -0,0 +1,35 @@
+{
+  "formula": "triage",
+  "type": "workflow",
+  "version": 1,
+  "description": "Board health work. explorer (semantic clustering + duplicate detection) → overthinker (rewire recommendations, priority re-balancing, decompose-or-merge proposals). READ_ONLY chain — no code edits. Output is advisory; operator applies recommendations via bd dep / bd duplicate / bd supersede / bd close.",
+  "vars": {
+    "root_title": { "default": "Board triage pass", "required": false },
+    "filter": { "default": "status=open", "required": false }
+  },
+  "steps": [
+    {
+      "id": "root",
+      "title": "{{root_title}}",
+      "type": "chore",
+      "description": "PROBLEM: board accumulates open issues, duplicates, stale advisors, orphan tracking-beads, mis-prioritized work. Periodic triage keeps the graph navigable.\nSCOPE: bd issues matching filter `{{filter}}`.\nNON_GOALS: no bd edits during this chain — operator applies recommendations after; no specialist edits.\nVALIDATION: explorer produces clustering+dup table; overthinker produces ranked recommendation list.\nACCEPTANCE: operator has actionable list of bd dep / bd duplicate / bd supersede / bd close commands.\n\nBoard triage: explorer maps, overthinker recommends.",
+      "labels": ["chain-root", "kind:root", "type:chore", "triage", "board-health"]
+    },
+    {
+      "id": "explorer",
+      "title": "explorer:{{root_title}}",
+      "type": "task",
+      "needs": ["root"],
+      "description": "MANDATE: READ_ONLY board mapper. For filter `{{filter}}`: cluster semantically related issues, identify duplicates (mechanical + semantic), flag stale advisors (no recent activity), flag orphan tracking-beads (step-beads missing validates edge to root), surface priority-vs-blast-radius mismatches.\nINPUTS: bd list --status=open --json + filter.\nOUTPUTS: structured table — clusters, candidate dups, stale advisors, orphans, mismatches. Cite bead-ids.\nSCOPE: bd graph queries only.\nNON_GOALS: no bd edits; no specialist edits; no recommendations (that's overthinker's job).",
+      "labels": ["chain-step", "kind:step", "role:explorer", "edge:informs->root", "advisor:pre-impl"]
+    },
+    {
+      "id": "overthinker",
+      "title": "overthinker:{{root_title}}",
+      "type": "task",
+      "needs": ["explorer"],
+      "description": "MANDATE: devil's-advocate review of explorer's board map. 4-phase synthesis: initial analysis → critique (what would actually break if we merge cluster X? are these REALLY duplicates? is this stale advisor still relevant?) → synthesis → distilled recommendations.\nINPUTS: explorer's structured table.\nOUTPUTS: ranked recommendations — for each cluster/dup/orphan/mismatch, propose action (merge / supersede / close / re-prioritize / leave) with reasoning. Generate ready-to-run bd commands.\nSCOPE: explorer's findings only.\nNON_GOALS: no bd edits; no expansion of scope beyond explorer's findings.",
+      "labels": ["chain-step", "kind:step", "role:overthinker", "edge:informs->root", "advisor:pre-impl"]
+    }
+  ]
+}