cyber-sdd 0.0.0

package/skills/combat-log-governance/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: combat-log-governance
+description: "Partial Skill: invoke by name only — the SDD combat-log contract, the durable provenance record's shape. Loaded by the conductor, spec-gate, and the doctrine-loop Scanner, not user-triggered."
+user-invocable: false
+---
+
+# SDD Combat-Log Governance
+
+The durable, harness-agnostic record of a spec's missions — what was produced, what was judged, what
+was corrected, and the strategy distilled from it. This skill defines the **shape**; the tracked
+deletion of a retired plan is the `plan-retirement` skill.
+
+## Two faces, two homes
+
+The record has two complementary faces: current-state in `spec.md` frontmatter
+(contract), the durable history in a sibling `ledger/` **directory** of per-writer shard files, sibling to the **root** `spec.md`.
+
+| Face | Home | Shape | Mutability | Holds |
+|---|---|---|---|---|
+| **Current-state** | `spec.md` frontmatter | `produced-by` (map by role) + `approval` (map by gate) | **overwritten** — last write wins | the **standing** present: who produced each artifact, the latest CR's verdict per gate |
+| **Ledger** | `ledger/` dir (root sibling), one `<cr-ref>.<hash>.jsonl` shard per CR per writer | one JSON object per line, appended to the writer's **own** shard | **immutable** — appended, never edited | the durable **history**: every CR's run-start `leash` block + `gate` verdict + `strategy` |
+
+`approval` is **standing, not historical** — the one durable spec is flowed through by many CRs, and
+`spec.md` `approval` holds only the **latest** CR's verdict (overwritten each time). The durable
+per-CR record (*"CR #34's diff was approved by X"*) is a `gate` ledger line, keyed by `cr`. There is
+no per-CR `approval` block and no sidecar file.
+
+**The ledger is operational provenance, not contract** — the `ledger/` shards are **never frozen and never
+gated**: writers keep appending across the whole lifecycle, including while `spec.md` + the `.feature`
+are frozen at `approved`.
+
+## Two logs: the combat log (plan) vs the ledger (sibling dir)
+
+Provenance splits by lifetime. Mid-flight detail is **per-mission and tracked with the work, then
+removed at retro** (durable in git history); the durable record is sparse and outlives the CR.
+
+- **Combat log** — `.agents/plans/<cr-ref>.log.jsonl`, beside the plan brief. Holds the chatty
+  mid-flight `report` / `correction` / `halt` lines. Tracked (committed, kept in the PR), deleted at retro
+  once distilled and the source is done/merged. Already one file per CR, so it never had the shared-file
+  merge problem.
+- **Ledger** — the `ledger/` **directory**, sibling to the root `spec.md`. Holds only the sparse durable
+  `leash` / `gate` / `strategy` lines, as one `<cr-ref>.<hash>.jsonl` shard **per CR per writer**. Never
+  deleted.
+
+**Sharded storage (ADR-0020).** Each writer appends only to its **own** shard, so no two writers ever
+touch the same file — concurrent appends (two branches, or two sessions sharing one working tree) are
+**non-colliding by construction**. A single shared `ledger.jsonl` conflicted on every concurrent mission
+(EOF-append merge conflict) or was silently clobbered by a same-tree fork; sharding removes the shared
+path, so **no merge driver is used or needed**. The reader **globs** `ledger/*.jsonl` (plus a legacy
+`ledger.jsonl` if present) and concatenates. `<hash>` is **6 random hex minted once per writer-session**
+(random, **not** a machine/host/user id — that would leak identity); same session + same CR → same shard.
+
+"Combat log" always means the live per-mission log in the plan; "ledger" always means the durable
+sibling `ledger/` directory. They are never the same store.
+
+## Entry shapes
+
+One JSON object per line (JSON Lines). Every line carries a **`seq`** (append order *within its shard* —
+its shard's own line count, restarting per shard, never a global counter), an optional pseudonymous
+**`handle`**, and a `kind`. **Combat-log** lines additionally carry a **write-time UTC `ts`**; **ledger**
+lines carry **no wall-clock time** (below). Seven kinds, split by tier: `report` / `correction` / `halt`
+→ the combat log; `leash` / `gate` / `strategy` / `followup` → the ledger. Every line carries an optional
+`cr` (the one project ledger spans many CRs against the one durable spec; outer-loop `strategy` lines may
+omit it).
+
+**Safe-to-publish floor (committed-record rule).** The combat log is committed → every line is
+**published to git history permanently** ("deleted at retro" is tree-only) and a distilled line may
+go **upstream via Forge**. The floor binds **all** fields:
+
+- **Categorical only** — structured fields are enums; the free-text `summary` / `detail` give the
+  decision or its class, commit-message-grade.
+- **Never committed:** email, OS usernames, hostnames, absolute paths, session/machine ids, secrets,
+  code, prompts, literal values, **raw numbers** (token/cost) — those stay in the uncommitted transcripts.
+- **Identity is a pseudonym** (`handle`, below), never `user.email`.
+
+**Write-time `ts` — combat-log lines only.** `report` / `correction` / `halt` carry a UTC `ts` (ISO-8601)
+stamped at write-time — the doctrine loop reads the committed combat log post-merge (possibly another
+machine), when the session clock is gone; within a mission `ts` orders those lines and feeds the pre-merge
+coarse-duration signal the efficiency dimension reads from the raw transcripts. **Ledger lines (`leash` /
+`gate` / `strategy`) carry no `ts`** — they are the forever-public durable record, and a wall-clock stamp
+on a committed cross-machine artifact leaks activity timing/timezone for no load-bearing gain (nothing
+reads ledger `ts`; ordering within a shard is `seq`; the cross-mission timeline is git history). Legacy
+ledger lines written before ADR-0020 carry a `ts` and are grandfathered (append-only, never rewritten).
+
+**Identity — the per-entry `handle`.** `report` / `correction` / `strategy` carry a `handle` (the
+writer's pseudonym); a `gate` line keeps `by` (the ratifier). Resolution at write-time: `SDD_HANDLE`
+(env) if set, else omit `handle` and fall back to the git commit author; **never** `user.email`,
+never a `git config` read. The in-file `handle` / `by` is **advisory, not proof** — a self-asserter
+can write any string, so the git commit signature plus positional authority are the control, not the
+field.
+
+### `report` — per-subagent dispatch (combat log)
+
+```jsonl
+{"seq": 3, "ts": "2026-06-28T18:30:11Z", "handle": "unional", "kind": "report", "role": "spec-producer", "agent": "sdd:automaton", "outcome": "pass", "summary": "wrote 14 scenarios covering the ledger expansion"}
+```
+
+`role` is the production role dispatched; `agent` is the plugin-qualified agent name; `outcome` is
+`pass | fail`.
+
+### `correction` — correction-with-cause (combat log)
+
+One line per correction: a gate rejection, a producer⇄judge iteration, or a Council kick-back. The
+matchable `cause` is the load-bearing field; at retro the doctrine loop folds recurring `cause`s into
+the ledger's `strategy` count.
+
+```jsonl
+{"seq": 7, "ts": "2026-06-28T18:41:02Z", "handle": "unional", "kind": "correction", "correction-kind": "gate-reject", "cause": "coverage-gap", "detail": "spec gate rejected — no negative scenario for the malformed-entry path"}
+```
+
+- **`correction-kind`** — the closed set `gate-reject | judge-iteration | council-kickback` (the
+  *occasion*, not the cause).
+- **`cause`** — a minimal, **discovered** enum (the matchable category of *why*). Grounded so far:
+
+  | Cause | Means |
+  |---|---|
+  | `coverage-gap` | a use case or operation lacked a covering scenario |
+  | `design-overreach` | the design added a mechanism the architecture did not need |
+  | `spec-feature-contradiction` | the `spec.md` body and the `.feature` asserted contradictory behavior |
+  | `prose-impl-contradiction` | a skill's own operating docs or a sibling design doc asserted behavior the shipped implementation no longer has |
+
+  **Growth:** closed at any moment, discovered from usage — a new value is added only when a real
+  recurring correction has no category. Adding one is an **edit to this governance, ratified by the
+  Council** (a producer/judge/conductor never edits the enum). An **absent or off-enum `cause` fails
+  closed** (it breaks cross-mission matchability).
+
+  **Efficiency** is a categorical correction class the committed log is designed to carry — the
+  conductor flagging notable token-waste (a class, **never raw counts**), so the post-merge doctrine
+  loop keeps the dimension. Its concrete `correction-kind` / `cause` are **not seeded**; they enter by
+  the same Council-ratified growth, and the numeric depth stays transcript-only (the floor admits no
+  raw token number).
+
+- **Durability discipline (the conductor's write duty).** A `correction` is a discrete line, never
+  left folded only into a verdict `why` (the doctrine loop matches `cause`, not prose):
+  - **At a gate reached via a judge-reject→fix→pass**, the self-asserting conductor appends the
+    `correction` line (`correction-kind: judge-iteration`, a matchable `cause`) **before** the gate
+    `why` it summarizes. A gate that passed clean with no iteration appends none.
+  - **At mission finalize**, a mission carrying a real correction whose line was **never flushed**
+    writes it now — **creating the combat log if none exists** — so the `cause` survives even the
+    no-log mission class (a mission with no correction forces nothing). The forced line stays a
+    combat-log `correction`, never a ledger line (the tier split above is invariant); its durability
+    is the retro distillation of the committed log into the ledger's `strategy` count.
+
+### `halt` — a mid-flight stop, not at a gate (combat log)
+
+The agent halts mid-phase (a hard floor, an input it cannot supply, a blast radius it will not cross).
+A gate-time stop is a `gate` line (`verdict: pause`); this `halt` line is its mid-flight twin, so *"why I
+halted"* is as durable as *"why I went"*. **Flush it to the committed log during the mission** — the
+doctrine loop reads only the committed log post-merge.
+
+```jsonl
+{"seq": 5, "ts": "2026-06-28T18:50:33Z", "handle": "unional", "kind": "halt", "phase": "explore", "why": {"floor": "clearance", "blast": "high — would drop scenarios from a frozen suite", "novelty": "low", "confidence": "high"}}
+```
+
+- **`phase`** — `intake | explore | deliver | handoff`, where the mission stopped.
+- **`why`** — the same categorical block the `approval` map carries (`floor` / `blast` / `novelty` /
+  `confidence`), **classes only** — never the raw blocker content.
+
+### `gate` — the durable per-CR gate verdict (ledger)
+
+```jsonl
+{"seq": 2, "kind": "gate", "cr": 34, "gate": "spec", "verdict": "approve", "by": "unional", "cause": "dimension", "frozen": ["intake/intake.feature", "mission/mission.feature"]}
+```
+
+- **`gate`** — `spec | impl`. **`verdict`** — `approve | pause | reject`. **`by`** — a human name
+  (ratified) or `agent` (self-asserted, provisional; carries the `why` derivation).
+- **`cause`** — `dimension | ceiling` (the **stop cause**, distinct from a `correction`'s matchable
+  `cause`).
+- **`frozen`** — the suite files this verdict froze (spec-gate `approve` only), so the ledger answers
+  *"what was frozen as of CR #34"* standalone — no git walk.
+
+### `leash` — the conductor's run-start autonomy block (ledger)
+
+The conductor's **initial strategy evaluation**, written once at run start: the run-level `leash`
+reach + the `approach[]` containment methods. It is the conductor's autonomy bar for the mission —
+**not** the Scanner's `strategy`, carries **no** `ratified` field, and is **never** counted as
+pending strategy. The write is owned by the **conductor** (`start-mission`).
+
+```jsonl
+{"seq": 1, "kind": "leash", "cr": "disambiguate-strategy-kind", "leash": "auto-spec", "by": "user", "blast": "medium", "approach": ["no-spike", "worktree"]}
+```
+
+`leash` — `auto-none | auto-spec | auto-all`; `by` — `derived | user`; `blast` — the assessed
+radius; `approach[]` — containment methods. The ceiling is not recorded (session-local). Pre-rename
+historical run-start blocks appear as `kind: strategy` and are grandfathered (append-only ledger).
+
+### `strategy` — drafted strategy (ledger)
+
+The Scanner records drafted strategy; this contract defines the **shape**, the **write is owned by
+the doctrine-loop Scanner**. It carries the distilled recurrence count for a `cause` (in `evidence`).
+
+```jsonl
+{"seq": 1, "handle": "sdd-scanner", "kind": "strategy", "recommendation": "codify the coverage-gap pattern as a spec-format-governance check", "evidence": ["coverage-gap x3 across sdd-foo, sdd-bar, sdd-baz"], "ratified": false}
+```
+
+`ratified: false` means the Council holds keep-or-cut — unratified strategy never enters the corpus.
+
+**The `distills` subject.** A strategy drafted from a **Ship** (`→ implemented`) or **Kill**
+(`→ deprecated`) records the **one mission it was distilled from** in a `distills` field carrying that
+mission's `<cr-ref>` — the same identifier that names the plan and the mission's `cr` on `leash` /
+`gate` lines:
+
+```jsonl
+{"seq": 2, "handle": "sdd-scanner", "kind": "strategy", "distills": "referenced-artifact-escalation", "recommendation": "...", "evidence": ["cross-ref: d2-correction-line-durability", "cross-ref: ba6a39"], "ratified": false}
+```
+
+`distills` names the **subject** (the mission the line was drafted from); the cr-refs in `evidence`
+are **cross-references** the recommendation leans on — never confuse the two. `distills` is the
+machine-checkable hook the retirement sweep keys on to confirm a plan was distilled before deleting
+its combat log (`sdd:plan-retirement` — the gate keys on `distills`, **never** an `evidence` mention,
+and an **unratified** entry still counts). Milestone / drift / token-waste strategy that has **no
+single subject mission omits `distills`** — only a Ship or Kill distillation gates a retirement.
+
+### `followup` — a recorded follow-up (ledger)
+
+The durable record of work handoff identified but held out of scope. Written by the **conductor at
+handoff**, unconditionally — no permission, no forge, no human — and **before any filing to the forge
+is attempted**. It is a ledger kind, never a combat-log kind: the combat log is deleted from the tree
+at retro, and a follow-up must outlive its mission.
+
+```jsonl
+{"seq": 4, "kind": "followup", "cr": "github-237-handoff-followups", "class": "blocking", "summary": "Operator's admission (proposeEdge) has no dedupe against RAW cycles for follow-up edges", "contradicts": "handoff proposes follow-ups; nothing yet admits them", "evidence": ["cyberfleet-plugin/operator README claims single-writer admission, unimplemented"]}
+```
+
+- **`class`** — `blocking` (the follow-up **contradicts a completion claim the mission already made**;
+  the line **names that claim** in `contradicts`) or `backlog` (genuinely new territory — `contradicts`
+  is omitted). A finding that the mission's own **frozen contract** was wrong is **not** a `followup` at
+  all — it is an Oracle-lens revert inside that mission, never routed here.
+- **`contradicts`** — required when `class: blocking`; names the completion claim the follow-up
+  contradicts.
+- **`evidence`** — the categorical support for the classification, commit-message-grade (the same floor
+  as every other field).
+- **No filed-state, ever.** The line is never edited to mark it filed — the ledger is append-only. What
+  is still outstanding is **re-derived** at each drain by deduping against the forge's existing issues,
+  **open or closed** (matching only open ones would re-file a duplicate for a follow-up already filed
+  and resolved).
+- **A proposal, not a verdict.** Recording a `followup` line grants nothing on its own — admission to
+  the mission graph is the graph's single writer's act; the conductor writes no node or edge here.
+
+## Write ownership
+
+Append-only; each writer adds lines to its **own shard** with the next `seq` within that shard, never
+editing another writer's shard, and never editing or deleting a prior line. Full matrix in
+`sdd:ownership-governance`:
+
+| Writer | May append | To |
+|---|---|---|
+| **conductor** | `report`, `correction`, `halt` | the **combat log** (plan `*.log.jsonl`) |
+| **conductor** | run-start `leash` block (leash reach + `approach[]`) | the **ledger** |
+| **conductor** | self-asserted `gate` (`by: agent`) | the **ledger** |
+| **conductor** | `followup` (record, at handoff, unconditionally) | the **ledger** |
+| **gate skill (`spec-gate`), in-session** | human-ratified `gate` (`by: <name>`) | the **ledger** |
+| **doctrine-loop Scanner** | `strategy` | the **ledger** |
+| producers / judges | nothing | — |
+
+A human-ratified `gate` line follows the **positional authority** rule (`sdd:lifecycle-governance`):
+only the in-session position holding the user channel writes `by: <name>`.

package/skills/concept-index/README.md

@@ -0,0 +1,13 @@
+# concept-index
+
+Internal SDD skill — the concrete engine for the **concept-index** step. Scans one project-spec for
+every node's `concept:` frontmatter and renders the **by-concept view** into the root `spec.md`,
+re-unifying a cross-cutting concern the capability folder tree scatters.
+
+```bash
+node scripts/concept-index.mts --spec-dir <spec> --write   # refresh the block
+node scripts/concept-index.mts --spec-dir <spec> --check   # no-drift guard
+```
+
+Pure derivation, frontmatter only; the write touches only the delimited generated block. See
+[`SKILL.md`](./SKILL.md) for the full contract. Not user-invocable.

package/skills/concept-index/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: concept-index
+description: "Partial Skill: invoke by name only — project-spec/concept-index's engine that derives the by-concept view of a project spec into spec.md — used to re-unify a cross-cutting concern the capability folder tree scatters, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Concept Index
+
+The concrete engine for the **concept-index** step. It scans
+one project-spec for every node's `concept:` frontmatter and renders the **by-concept view** —
+`concept → {its nodes across every folder}` — that re-unifies a cross-cutting concern the capability
+folder tree scatters (the concept axis: one concern enacted across several capability folders). It
+carries a self-contained `.mts` script (the repo's node-≥23.6 / no-deps convention).
+
+## Run it
+
+```bash
+node "<skill>/scripts/concept-index.mts" --spec-dir <spec> [--write | --check]
+```
+
+- default (no mode) — print the rendered "By concept" section to stdout (dry run).
+- `--write` — replace the generated block in `<spec>/spec.md` with the freshly rendered table;
+  inserts the block at the `## Invariants` anchor when the markers are absent.
+- `--check` — exit non-zero when `spec.md`'s block differs from the freshly rendered table (the
+  no-drift guard for CI).
+
+The view is **pure derivation** from the `concept:` tags: rendering twice is byte-identical and a
+`--write` over a current block is a no-op. Each node is annotated by **facet kind** — a node under `design/` → rule,
+under `workflows/` → workflow, else `reference` / `behavior` / `index` from its `spec-type`.
+
+## Boundaries
+
+Frontmatter only — no node body reaches the output. The write touches **only** the content between the
+generated-block markers; lifecycle frontmatter, prose, and the capability map are left untouched. It
+owns no lifecycle state and renders no verdict. When `node` is absent, an agent performs the same
+derivation by hand: read each node's `concept:` tag, group by concept, and render the table.

package/skills/concept-index/scripts/concept-index.mts

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// concept-index — project-spec/concept-index's concrete engine. Scans one project-spec for every node's
+// `concept:` frontmatter and renders the by-concept view (concept → its nodes across every folder),
+// which re-unifies a cross-cutting concern the capability folder tree scatters
+// (the concept axis).
+//
+// Pure derivation from the `concept:` tags: rendering twice is byte-identical, and the generated
+// block in the root spec.md is the only thing a --write touches. Frontmatter only — no node body
+// reaches the output. No dependencies (the repo's node-≥23.6 / no-deps convention). Pure functions
+// are exported for node:test; running the file directly drives the CLI.
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const BEGIN_MARKER = '<!-- BEGIN generated: by-concept (project-spec/concept-index) -->'
+export const END_MARKER = '<!-- END generated: by-concept -->'
+// Where the block is inserted when the markers are absent: just before this heading.
+const ANCHOR_HEADING = '## Invariants'
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
+
+export type FacetKind = 'rule' | 'workflow' | 'reference' | 'behavior' | 'index'
+
+export interface NodeRecord {
+	/** Path relative to the spec directory (POSIX). */
+	relPath: string
+	/** Display form — a README.md node shows its folder, a design doc shows the file. */
+	display: string
+	concepts: string[]
+	facet: FacetKind
+}
+
+export interface NodeFrontmatter {
+	concepts: string[]
+	specType?: string
+	model: boolean
+}
+
+// ── Frontmatter parse (a minimal YAML subset — only the node classification schema) ──
+// Reads the leading `---` … `---` block for `concept` (scalar | flow list | block list),
+// `spec-type`, and `model`. Returns null when there is no frontmatter block.
+export function parseFrontmatter(text: string): NodeFrontmatter | null {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text)
+	if (!m) return null
+	const fm: NodeFrontmatter = { concepts: [], model: false }
+	const lines = m[1].split('\n').map((l) => l.replace(/\r$/, ''))
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]
+		if (line.trim() === '' || line.trim().startsWith('#')) continue
+		if (line.length - line.trimStart().length !== 0) continue // only top-level keys
+		const [key, ...rest] = line.trim().split(':')
+		const value = rest.join(':').trim()
+		if (key === 'spec-type') fm.specType = unquote(value)
+		else if (key === 'model') fm.model = unquote(value) === 'true'
+		else if (key === 'concept') {
+			if (value === '' || value === '|' || value === '>') {
+				// block list on following more-indented `- item` lines
+				for (let j = i + 1; j < lines.length; j++) {
+					const item = lines[j]
+					if (item.trim() === '') continue
+					if (item.length - item.trimStart().length === 0) break
+					const dash = /^\s*-\s+(.*)$/.exec(item)
+					if (dash) fm.concepts.push(unquote(dash[1].trim()))
+				}
+			} else {
+				fm.concepts.push(...parseScalarOrFlow(value))
+			}
+		}
+	}
+	return fm
+}
+
+// `resolution` | `[governance, resolution]` → string[]
+export function parseScalarOrFlow(value: string): string[] {
+	const v = value.trim()
+	if (v.startsWith('[') && v.endsWith(']')) {
+		return v
+			.slice(1, -1)
+			.split(',')
+			.map((s) => unquote(s.trim()))
+			.filter((s) => s.length > 0)
+	}
+	const single = unquote(v)
+	return single.length > 0 ? [single] : []
+}
+
+function unquote(v: string): string {
+	return v.replace(/^["']|["']$/g, '')
+}
+
+// ── Facet kind — where this node's facet sits, mechanically ──
+export function facetKind(relPath: string, specType: string | undefined): FacetKind {
+	const p = relPath.replace(/\\/g, '/')
+	if (p.startsWith('design/')) return 'rule'
+	if (p.startsWith('workflows/')) return 'workflow'
+	if (specType === 'reference') return 'reference'
+	if (specType === 'behavioral') return 'behavior'
+	return 'index'
+}
+
+function displayPath(relPath: string): string {
+	const p = relPath.replace(/\\/g, '/')
+	return p.endsWith('/README.md') ? p.slice(0, -'README.md'.length) : p
+}
+
+// ── Scan the project-spec — every *.md node carrying a concept tag ──
+export function scanProjectSpec(specDir: string): NodeRecord[] {
+	const records: NodeRecord[] = []
+	walk(specDir, specDir, records)
+	return records
+}
+
+function walk(dir: string, specDir: string, out: NodeRecord[]): void {
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue
+		const full = join(dir, entry.name)
+		if (entry.isDirectory()) {
+			walk(full, specDir, out)
+		} else if (entry.name.endsWith('.md')) {
+			const fm = parseFrontmatter(readFileSync(full, 'utf8'))
+			if (!fm || fm.concepts.length === 0) continue
+			const relPath = full.slice(specDir.length + 1).replace(/\\/g, '/')
+			out.push({
+				relPath,
+				display: displayPath(relPath),
+				concepts: fm.concepts,
+				facet: facetKind(relPath, fm.specType),
+			})
+		}
+	}
+}
+
+// ── Group + render ──
+export function groupByConcept(records: NodeRecord[]): Map<string, NodeRecord[]> {
+	const grouped = new Map<string, NodeRecord[]>()
+	for (const rec of records) {
+		for (const concept of rec.concepts) {
+			const list = grouped.get(concept) ?? []
+			list.push(rec)
+			grouped.set(concept, list)
+		}
+	}
+	// stable order: concepts alphabetical, nodes by display path
+	return new Map(
+		[...grouped.entries()]
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([k, v]) => [k, [...v].sort((x, y) => x.display.localeCompare(y.display))]),
+	)
+}
+
+export function renderTable(grouped: Map<string, NodeRecord[]>): string {
+	const rows = [...grouped.entries()].map(([concept, nodes]) => {
+		const facets = nodes.map((n) => `\`${n.display}\` (${n.facet})`).join(' · ')
+		return `| \`${concept}\` | ${facets} |`
+	})
+	return ['| Concept | Facets |', '|---|---|', ...rows].join('\n')
+}
+
+// The full generated section, markers included.
+export function renderSection(grouped: Map<string, NodeRecord[]>): string {
+	return [
+		BEGIN_MARKER,
+		'',
+		'## By concept',
+		'',
+		'> Generated from `concept:` frontmatter by `project-spec/concept-index` — do not edit by hand.',
+		'',
+		renderTable(grouped),
+		'',
+		END_MARKER,
+	].join('\n')
+}
+
+// ── spec.md block maintenance ──
+// Replace the BEGIN…END block with `section`; insert at the anchor (or append) when absent.
+export function applySection(specText: string, section: string): string {
+	const begin = specText.indexOf(BEGIN_MARKER)
+	const end = specText.indexOf(END_MARKER)
+	if (begin !== -1 && end !== -1 && end > begin) {
+		const before = specText.slice(0, begin)
+		const after = specText.slice(end + END_MARKER.length)
+		return before + section + after
+	}
+	const anchor = specText.indexOf(ANCHOR_HEADING)
+	if (anchor !== -1) {
+		return specText.slice(0, anchor) + section + '\n\n' + specText.slice(anchor)
+	}
+	const trimmed = specText.replace(/\s*$/, '')
+	return `${trimmed}\n\n${section}\n`
+}
+
+// Extract the current block (BEGIN…END inclusive), or null when absent.
+export function extractSection(specText: string): string | null {
+	const begin = specText.indexOf(BEGIN_MARKER)
+	const end = specText.indexOf(END_MARKER)
+	if (begin === -1 || end === -1 || end < begin) return null
+	return specText.slice(begin, end + END_MARKER.length)
+}
+
+// ── CLI ──
+function parseArgs(argv: string[]): { specDir: string; mode: 'print' | 'write' | 'check' } {
+	let specDir = '.'
+	let mode: 'print' | 'write' | 'check' = 'print'
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i]
+		if (a === '--spec-dir') specDir = argv[++i] ?? '.'
+		else if (a === '--write') mode = 'write'
+		else if (a === '--check') mode = 'check'
+	}
+	return { specDir, mode }
+}
+
+export function main(argv: string[]): number {
+	const { specDir, mode } = parseArgs(argv)
+	const grouped = groupByConcept(scanProjectSpec(specDir))
+	const section = renderSection(grouped)
+	const specPath = join(specDir, 'spec.md')
+	if (mode === 'print') {
+		process.stdout.write(`${section}\n`)
+		return 0
+	}
+	if (!existsSync(specPath)) {
+		process.stderr.write(`concept-index: no spec.md at ${specPath}\n`)
+		return 2
+	}
+	const specText = readFileSync(specPath, 'utf8')
+	if (mode === 'check') {
+		const current = extractSection(specText)
+		if (current === section) {
+			process.stdout.write('concept-index: no drift\n')
+			return 0
+		}
+		process.stderr.write('concept-index: drift — spec.md by-concept block is stale; run --write\n')
+		return 1
+	}
+	// write
+	const next = applySection(specText, section)
+	if (next !== specText) writeFileSync(specPath, next)
+	process.stdout.write(`concept-index: ${next === specText ? 'unchanged' : 'updated'} ${specPath}\n`)
+	return 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/discover-plans/README.md

@@ -0,0 +1,16 @@
+# discover-plans
+
+The concrete engine for SDD **plan discovery**. A non-user-invocable skill carrying a self-contained
+`.mts` script that scans `.agents/plans` for `*.plan.md` mission briefs, treats each present brief as
+an unretired/resumable mission, tallies its todos, reads its top-level `status` dispatch flag
+(`active` when unset) and its `## NEXT` resume lead, and emits a TOON list. The plan sibling of
+[`discover-specs`](../discover-specs/README.md).
+
+- **Skill contract:** [`SKILL.md`](./SKILL.md)
+- **Script:** [`scripts/discover-plans.mts`](./scripts/discover-plans.mts)
+- **Tests:** [`scripts/discover-plans.test.mts`](./scripts/discover-plans.test.mts) (`node:test`)
+
+```bash
+node scripts/discover-plans.mts --root . --format toon
+node scripts/discover-plans.mts --root . --status approved   # the dispatch queue: approved briefs only
+```

package/skills/discover-plans/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: discover-plans
+description: "Partial Skill: invoke by name only — intake/plan-discovery's engine that surfaces resumable mission plan briefs — used by the sdd gateway on entry, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Discover Plans
+
+The concrete engine for SDD **plan discovery**. It
+locates the **resumable missions** in a repo — the mission **plan briefs** under `.agents/plans` —
+and returns each one's CR ref, name, todo tally, and `## NEXT` resume lead, **without reading the
+rest of the body**, so a consumer (the **gateway**, on entry) can offer resume cheaply. It carries a
+self-contained `.mts` script (the repo's node-≥23.6 / no-deps convention). It is the **plan** sibling
+of `discover-specs`: that engine finds **specs** by status shape; this one finds **missions** by
+their briefs.
+
+## Recognition — location-bounded and shape-confirmed
+
+A file is a mission brief only when **both** hold (`intake/plan-discovery`):
+
+- **Location** — it sits directly under the repo's **`.agents/plans/`** directory (the one plans
+  location intake scaffolds into).
+- **Shape** — its filename ends `.plan.md` **and** it carries a frontmatter block (the basic plan
+  template: `name` + a `todos` list + a `## NEXT` anchor). A `*.plan.md` with no frontmatter is a
+  stray and is skipped; a sibling that does not end `.plan.md` (a combat-log `*.log.jsonl`, a loose
+  `*.md`) is never a brief.
+
+**Present means resumable.** By default there is **no status filter** — a present brief is already
+unretired (the doctrine loop's `plan-retirement` deletes a brief once its CR is done/merged and
+distilled), so every brief the scan finds is a resumable mission. The todo tally lets the caller tell
+a barely-started mission from one near handoff.
+
+**The `status` dispatch flag.** Each brief may declare a top-level `status` (the mission dispatch
+flag — `active` by default, `approved` once a human clears it for headless dispatch). The scan
+**reports** it in every row (an unset value reads as `active`), and, **only when a caller passes
+`--status <value>`**, narrows the set to that status — the opt-in filter the gateway's dispatch loop
+uses to build the approved queue. A value no brief carries yields the empty set. The engine reports
+the flag; it never interprets or writes it.
+
+## Run the scan
+
+```bash
+node "<skill>/scripts/discover-plans.mts" [--root .] [--format toon|json] [--status <value>]
+```
+
+- Default `--root` is the current directory; default `--format` is **TOON** (the token-efficient
+  tabular form the gateway scans).
+- Emits one row per brief, sorted by CR ref, with columns
+  `cr,name,total,completed,inProgress,status,next` — `cr` is the filename slug (`<cr-ref>`), the
+  three counts are the todo tally, `status` is the dispatch flag (`active` when unset), and `next` is
+  the lead line of the brief's `## NEXT` anchor (the resume hint).
+- `--status <value>` narrows to the briefs at that dispatch status (e.g. `--status approved` for the
+  dispatch queue); absent, no status filter is applied.
+- `--format json` emits the same records as a flat JSON array for non-LLM consumers.
+
+Example (TOON):
+
+```
+plans[2]{cr,name,total,completed,inProgress,status,next}:
+  github-34,github-34: ...,34,21,0,active,"sub-corpus — suites done, impls pending"
+  add-auth,add-auth: ...,6,2,0,approved,"build the token exchange unit"
+```
+
+When `node` is absent, an agent performs the same derivation by hand: list `.agents/plans/*.plan.md`,
+keep each file carrying frontmatter, tally its `todos` by `status`, and read its `## NEXT` lead.
+
+## Boundaries
+
+Frontmatter + the `## NEXT` section only — it never reads the rest of a brief's body, owns no
+lifecycle state, and writes nothing. It **never resumes** a mission (that is `resume-mission`) and
+**never retires** a brief (that is `plan-retirement`). Ref resolution over the returned list
+(matching a CR ref to a filename slug) is the **caller's** step, not the script's.