cyber-sdd 0.0.0

package/skills/align-spec/scripts/align-spec.mts

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// align-spec — project-spec/align-spec's concrete engine. Detects prose↔suite drift across the
+// project spec's nodes and, on request, applies the mechanical write primitives a judge-directed
+// reconcile step uses (see this skill's README.md / SKILL.md).
+//
+// The 12 frozen scenarios split two ways (align-spec.feature):
+//   - Mechanical (this engine ships code + a test for each):
+//       * a scenario-diff flags a narrowing of the frozen suite → Clearance
+//       * check mode exits non-zero on drift and writes nothing
+//       * check mode exits zero when there is no drift
+//       * detect runs over every node of the project spec (a chosen set)
+//       * reconcile never writes lifecycle state (writes only prose or scenarios)
+//   - Judge-orchestrated (SKILL.md documents the procedure; no engine code):
+//       coverage-gap detection, prose/scenario contradiction detection, the aligned-report-no-
+//       drift aggregate, and every reconcile *decision* (add a scenario / trim prose / align the
+//       losing side / escalate a Clearance) — there are no scenario IDs in prose, so prose↔suite
+//       alignment is judge-only. This engine feeds that judge the mechanical scan (node
+//       iteration + scenario-diff); it never itself judges coverage or contradiction.
+//
+// Node iteration and the scenario-diff reuse the existing engines rather than re-implementing
+// them: check-spec-structure's scanProjectSpec (node discovery) and spec-gate's classify-edit-
+// class (the gherkin-cli-backed structural diff against a frozen baseline).
+//
+// 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 } from 'node:fs'
+import { isAbsolute, join, relative } from 'node:path'
+import { type NodeRecord, scanProjectSpec } from '../../check-spec-structure/scripts/check-spec-structure.mts'
+import { classifyFile } from '../../spec-gate/scripts/classify-edit-class.mts'
+
+export const DEFAULT_BASE = 'HEAD'
+
+export type DriftKind = 'narrowing'
+export type DriftSeverity = 'clearance'
+
+export interface DriftFinding {
+	kind: DriftKind
+	severity: DriftSeverity
+	/** The node's display path (a folder for a README-rooted node). */
+	node: string
+	detail: string
+}
+
+// ── Node selection — the "chosen set" a detect run scopes to ──
+// No `--nodes` arg selects every node scanProjectSpec finds; an explicit list scopes the sweep
+// to exactly those nodes (matched by display path or the README's relative path).
+export function selectNodes(records: NodeRecord[], only?: string[]): NodeRecord[] {
+	if (!only || only.length === 0) return records
+	const wanted = new Set(only.map(normalizeNodeRef))
+	return records.filter((r) => wanted.has(normalizeNodeRef(r.display)) || wanted.has(normalizeNodeRef(r.relPath)))
+}
+
+function normalizeNodeRef(ref: string): string {
+	return ref
+		.replace(/\\/g, '/')
+		.replace(/\/README\.md$/, '')
+		.replace(/\/+$/, '')
+}
+
+// ── Locate a node's sibling `.feature` file (same convention check-spec-structure scans by) ──
+export function findFeaturePath(specDir: string, node: NodeRecord): string | null {
+	const nodeDir = join(specDir, node.relPath.replace(/README\.md$/, ''))
+	if (!existsSync(nodeDir)) return null
+	const entries = readdirSync(nodeDir, { withFileTypes: true })
+	const feature = entries.find((e) => e.isFile() && e.name.endsWith('.feature'))
+	return feature ? join(nodeDir, feature.name) : null
+}
+
+// ── Mechanical scenario-diff: a modified/removed baseline scenario is a narrowing → Clearance ──
+// Reuses spec-gate's classify-edit-class rather than hand-rolling a line-diff (a line-diff is
+// fooled by a step reassigned off a frozen scenario onto a newly-added adjacent one).
+export function detectNarrowing(node: NodeRecord, specDir: string, base: string, cwd = '.'): DriftFinding[] {
+	const featurePath = findFeaturePath(specDir, node)
+	if (!featurePath) return []
+	// classifyFile (and the `git show <base>:<path>` it drives) needs a path relative to cwd
+	// (the git repo root) — resolve it, since specDir/featurePath may already be absolute.
+	const relFeaturePath = isAbsolute(featurePath) ? relative(cwd, featurePath) : featurePath
+	const result = classifyFile(relFeaturePath, base, cwd)
+	if (result.classification !== 'narrowing' && result.classification !== 'mixed') return []
+	const narrowed = result.scenarios.filter((s) => s.change === 'modified' || s.change === 'removed')
+	return [
+		{
+			kind: 'narrowing',
+			severity: 'clearance',
+			node: node.display,
+			detail: `scenario-diff vs ${base} narrows: ${narrowed.map((s) => s.name).join(', ')} — escalate a Clearance CR, do not silently rewrite`,
+		},
+	]
+}
+
+// Runs the mechanical scan over exactly the chosen node set — reports drift per node.
+export function detect(records: NodeRecord[], specDir: string, base: string, cwd = '.'): DriftFinding[] {
+	return records.flatMap((node) => detectNarrowing(node, specDir, base, cwd))
+}
+
+export function hasDrift(findings: DriftFinding[]): boolean {
+	return findings.length > 0
+}
+
+// ── The write boundary ──
+// Reconcile decisions (add/trim/align/escalate) are judge-orchestrated (SKILL.md), but the
+// mechanical write primitives the judge's verdict drives are engine code, and they are built to
+// make writing lifecycle state structurally impossible: a README write splits frontmatter from
+// body and only ever touches the body; a .feature write only ever appends a whole scenario block.
+export interface SplitDocument {
+	frontmatter: string
+	body: string
+}
+
+export function splitFrontmatter(text: string): SplitDocument {
+	const m = /^(---\r?\n[\s\S]*?\r?\n---\s*(?:\r?\n|$))([\s\S]*)$/.exec(text)
+	if (!m) return { frontmatter: '', body: text }
+	return { frontmatter: m[1], body: m[2] }
+}
+
+// Trims prose out of a node's README body — the frontmatter (and any status/approval/freeze
+// field it carries) passes through byte-for-byte untouched.
+export function trimProse(readmeText: string, proseToRemove: string): string {
+	const { frontmatter, body } = splitFrontmatter(readmeText)
+	return frontmatter + body.split(proseToRemove).join('')
+}
+
+// Appends a whole scenario block to a `.feature` file. `.feature` files carry no frontmatter /
+// lifecycle fields to begin with — this only ever appends, never rewrites an existing scenario
+// (a rewrite of an existing frozen scenario is the narrowing path above, which escalates instead).
+export function appendScenario(featureText: string, scenarioBlock: string): string {
+	const trimmed = featureText.replace(/\s+$/, '')
+	return `${trimmed}\n\n${scenarioBlock.trim()}\n`
+}
+
+// ── Render ──
+export function renderFindings(findings: DriftFinding[], specDir: string): string {
+	const lines: string[] = [`align-spec: spec-dir=${specDir}`, `drift[${findings.length}]:`]
+	for (const f of findings) lines.push(`  ${f.node} — ${f.kind} (${f.severity}): ${f.detail}`)
+	if (findings.length === 0) lines.push('  (none — mechanical scenario-diff found no narrowing)')
+	lines.push(
+		'note: coverage gaps and prose/scenario contradictions are judge-only (no scenario IDs in prose) — this engine reports only the mechanical scenario-diff',
+	)
+	return lines.join('\n')
+}
+
+// ── CLI ──
+function parseNodesArg(value: string | undefined): string[] | undefined {
+	if (!value) return undefined
+	const parts = value
+		.split(',')
+		.map((s) => s.trim())
+		.filter(Boolean)
+	return parts.length > 0 ? parts : undefined
+}
+
+export function main(argv: string[]): number {
+	let specDir = '.'
+	let base = DEFAULT_BASE
+	let mode: 'detect' | 'check' = 'detect'
+	let format: 'toon' | 'json' = 'toon'
+	let only: string[] | undefined
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i]
+		if (a === '--spec-dir') specDir = argv[++i] ?? '.'
+		else if (a === '--check') mode = 'check'
+		else if (a === '--base') base = argv[++i] ?? DEFAULT_BASE
+		else if (a === '--format') format = (argv[++i] as 'toon' | 'json') ?? 'toon'
+		else if (a === '--nodes') only = parseNodesArg(argv[++i])
+	}
+
+	const records = selectNodes(scanProjectSpec(specDir), only)
+	const findings = detect(records, specDir, base)
+
+	if (mode === 'check') {
+		if (hasDrift(findings)) {
+			process.stderr.write(`align-spec: ${findings.length} drift finding(s) (mechanical scenario-diff)\n`)
+			return 1
+		}
+		process.stdout.write('align-spec: no mechanical drift\n')
+		return 0
+	}
+
+	if (format === 'json') process.stdout.write(`${JSON.stringify(findings)}\n`)
+	else process.stdout.write(`${renderFindings(findings, specDir)}\n`)
+	return 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/architect-impl-governance/README.md

@@ -0,0 +1,46 @@
+# architect-impl-governance
+
+This is an internal SDD governance about structural fit at the impl gate.
+
+It is the **Architect** actor's bar — the question it answers is: does the implementation fit the
+existing structure, and is the suite's verification pyramid sound? Where its spec-gate twin judges
+how a capability sits in the project, this bar judges how the code that realizes it sits in the
+codebase.
+
+This is the SDD default for the `architect` bar at the impl gate: a plugin may bind its own version,
+and this one loads whenever the registry leaves `architect`/`impl` unbound. Its twin at the spec
+gate is **`architect-spec-governance`** — same actor, same structural-fit question, asked of the
+spec and solution instead of the implementation.
+
+## What it requires — the bar
+
+| Requirement | What it means |
+| --- | --- |
+| **No knowledge duplication** | A rule, contract, or piece of logic has **one home** in the implementation; whatever needs it calls that home. Two copies of one piece of knowledge drift — a change lands in one and misses the other. |
+| **…but coincidental resemblance is not duplication** | Two units that look alike yet change for different reasons stay separate — a premature shared abstraction couples them, and the wrong abstraction costs more than the repetition. The test: does a change to one force the same change to the other? Only then converge. |
+| **No conflict** | The implementation does not contradict conventions, module boundaries, or a spec's contract — including the project's **declared** layout, judged as declared (`spec-structure-governance`). The declaration is not a licence: node ↔ capability stays one-to-one under every strategy, because the scheduler cuts one mission per node (ADR-0025). |
+| **Contained complexity** | Watch cyclomatic complexity and coupling; a unit that is hard to test is usually mis-structured — flag it. |
+| **A sound verification pyramid** | Across the suite, the verification levels form a pyramid — a broad cheap base under a **thin e2e cap** that keeps the end-to-end path honest. An **all-e2e** suite is fragile and slow; a **capless** suite has no honesty check. The level of any *one* scenario is the builder's call (`builder-impl-governance`); this bar judges the overall shape. |
+| **An orthogonal axis** | Structural fit judges a property the builder was not optimizing. |
+| **Structural concerns are deferred** | A structural problem in *another* capability spawns a new spec — it does not block this one. |
+
+## Usage
+
+One merged bar loaded by **both faces** at the **impl gate**:
+
+- **impl-producer:** reads it forward to self-align while building.
+- **impl-judge:** reads it backward to verify.
+
+## Related governances
+
+This bar owns the structural fit of the **implementation**. Its neighbors own everything around
+that:
+
+- **`architect-spec-governance`** — the same Architect bar at the **spec gate**: structural fit of
+  the capability as specified, where this bar judges the code that realizes it.
+- **`builder-impl-governance`** — the per-scenario verification level is the builder's call under
+  that bar; this bar judges only the pyramid's overall shape.
+- **`spec-structure-governance`** — the declared layout law the no-conflict requirement judges
+  against.
+
+Internal SDD governance (`user-invocable: false`). Not triggered by users directly.

package/skills/architect-impl-governance/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: architect-impl-governance
+description: "Partial Skill: invoke by name only"
+user-invocable: false
+metadata:
+  actor: architect
+  gate: impl
+  compose: union
+---
+
+# Architect-Impl Governance — the structural-fit bar (impl gate)
+
+The **Architect** bar at the **impl gate**: does the implementation fit the existing structure, and
+is the suite's verification pyramid sound? Loaded by both faces. The SDD default for the `architect`
+impl bar; a plugin may bind its own, and this loads when the registry leaves `architect`/`impl`
+unbound.
+
+## The bar
+
+- **No knowledge duplication.** A rule, contract, or piece of logic has **one home** in the
+  implementation; whatever needs it calls that home. Two copies of one piece of knowledge drift — a
+  change lands in one and misses the other. But **coincidental resemblance is not duplication**: two
+  units that look alike yet change for different reasons stay separate — a premature shared
+  abstraction couples them, and the wrong abstraction costs more than the repetition. Test: does a
+  change to one force the same change to the other? Only then converge.
+- **No conflict.** The implementation does not contradict conventions, module boundaries, or a spec's
+  contract — including the project's **declared** layout, judged as declared
+  (`sdd:spec-structure-governance`). The declaration is not a licence: node <-> capability stays 1:1
+  under every strategy, because the scheduler cuts one mission per node (ADR-0025).
+- **Contained complexity.** Watch cyclomatic complexity and coupling; a unit hard to test is usually
+  mis-structured — flag it.
+- **A sound verification pyramid.** Across the suite the verification levels form a pyramid — a broad
+  cheap base under a **thin e2e cap** that keeps the end-to-end path honest. An **all-e2e** suite is
+  fragile and slow; a **capless** suite has no honesty check. The per-scenario level is the builder's
+  call (`sdd:builder-impl-governance`); this bar judges the shape.
+- **An orthogonal axis.** Structural fit judges a property the builder was not optimizing.
+- **Structural concerns are deferred.** A structural problem in another capability spawns a new spec.
+
+## Key points (read-check)
+
+1. **No knowledge duplication** — one home per rule; but coincidental resemblance is not duplication
+   (don't merge units that change for different reasons). No conflict; contained complexity.
+2. **A sound verification pyramid** — cheap base, thin e2e cap; neither all-e2e nor capless.
+3. **Per-scenario level is the builder's call; this bar judges the shape.**
+4. **Structural concerns in another capability are deferred.**

package/skills/architect-spec-governance/README.md

@@ -0,0 +1,48 @@
+# architect-spec-governance
+
+This is an internal SDD governance about structural fit at the spec gate.
+
+It is the **Architect** actor's bar — the question it answers is: does this **capability** fit the
+project's structure, and is its control-flow graph (CFG) well-placed? It judges the capability
+itself, read from its spec and test suite — not the wording of the document. How the prose is
+written is a different bar (`spec-format-governance`).
+
+This is the SDD default for the `architect` bar at the spec gate: a plugin may bind its own version
+per artifact-type, and this one loads whenever the registry leaves `architect`/`spec` unbound. Its
+twin at the impl gate is **`architect-impl-governance`** — same actor, same structural-fit question,
+asked of the implementation instead of the spec.
+
+## What it requires — the bar
+
+| Requirement | What it means |
+| --- | --- |
+| **No knowledge duplication** | A capability, concept, rule, or contract has **one home**; whatever needs it references that home. Two copies of one piece of knowledge drift — a change lands in one and misses the other. |
+| **…but coincidental resemblance is not duplication** | Two capabilities that look alike yet change for different reasons stay separate — a premature shared abstraction couples them, and the wrong abstraction costs more than the repetition. The test: does a change to one force the same change to the other? Only then converge. |
+| **No conflict** | The capability does not contradict established conventions, module boundaries, or an existing capability's contract. |
+| **Placement matches the declared layout** | The project declares its layout strategy in its root `spec.md` placement map; placement is judged *within* that declaration, not against a preferred one. Under the screaming-architecture default a capability lives in a folder named for its intent; a project that declared `mirror-source` is correctly placed when it mirrors its source. |
+| **…and the layout preserves the partition** | The declaration is not a licence. Layouts are ranked by whether they keep node ↔ capability one-to-one, because the mission scheduler cuts one mission per node and a scattered capability degrades the schedule toward serial (ADR-0025). **One capability per node, never smeared across nodes** holds under every strategy, and a layered / framework-first top level stays discouraged however it is declared. |
+| **A well-formed CFG** | The capability's control-flow graph connects — every decision reachable, no dangling branch — and the suite's sections mirror it. |
+| **An orthogonal axis** | Structural fit judges a property the builder was not optimizing — a real independent check even from the same hand. |
+| **Structural concerns are deferred** | A structural problem in *another* capability is an observation that spawns a new spec — never a marker in the one being built. |
+
+## Usage
+
+One merged bar with an **asymmetric loadout** — the two faces read different inputs:
+
+- **solution-producer** (forward): self-aligns the ungated `<unit>.solution.md`, where structure is
+  chosen.
+- **cold spec-judge** (backward, at the **spec gate**): grades structure from `spec.md` + the suite
+  only — the solution is out of view, which keeps the grader independent.
+
+## Related governances
+
+This bar owns the structural fit of the **capability**. Its neighbors own everything around that:
+
+- **`architect-impl-governance`** — the same Architect bar at the **impl gate**: structural fit of
+  the implementation, where this bar judges the spec and solution.
+- **`spec-format-governance`** — the document's prose: sections, tables, the plain-language bar.
+  This bar reads *through* the document at the capability; that one judges the document itself.
+- **`spec-structure-governance`** — the layout law itself: the declared placement map this bar
+  judges placement against.
+
+Internal SDD governance (`user-invocable: false`). Not triggered by users directly.

package/skills/architect-spec-governance/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: architect-spec-governance
+description: "Partial Skill: invoke by name only"
+user-invocable: false
+metadata:
+  actor: architect
+  gate: spec
+  compose: union
+---
+
+# Architect-Spec Governance — the structural-fit bar (spec gate)
+
+The **Architect** bar at the **spec gate**: does this **capability** fit the project's structure, and
+is its control-flow graph (CFG) well-placed? Judges the capability (read from its spec + suite), not
+the document's prose — that is `sdd:spec-format-governance`. The SDD default for the `architect` spec bar;
+a plugin may bind its own per artifact-type, and this loads when the registry leaves `architect`/`spec`
+unbound.
+
+## The bar
+
+- **No knowledge duplication.** A capability, concept, rule, or contract has **one home**; whatever
+  needs it references that home. Two copies of one piece of knowledge drift — a change lands in one
+  and misses the other. But **coincidental resemblance is not duplication**: two capabilities that
+  look alike yet change for different reasons stay separate — a premature shared abstraction couples
+  them, and the wrong abstraction costs more than the repetition. Test: does a change to one force the
+  same change to the other? Only then converge.
+- **No conflict.** The capability does not contradict established conventions, module boundaries, or
+  an existing capability's contract.
+- **Placement matches the declared layout — and the layout preserves the partition.** Judge
+  *placement within* the strategy the project **declared** in its root `spec.md` placement map
+  (`sdd:spec-structure-governance`): under the screaming-architecture default a capability lives in a
+  folder named for its intent, while a project that declared `mirror-source` is correctly placed when
+  it mirrors its source. But the declaration is **not** a licence — layouts are ranked by whether
+  they keep **node <-> capability 1:1**, because the mission scheduler cuts one mission per node and a
+  scattered capability degrades the schedule toward serial (ADR-0025). **One capability per node,
+  never smeared across nodes**, holds under every strategy, and a layered / framework-first *top*
+  level stays discouraged however it is declared.
+- **A well-formed CFG.** Its control-flow graph connects — every decision reachable, no
+  dangling branch — and the suite's sections mirror it.
+- **An orthogonal axis.** Structural fit judges a property the builder was not optimizing — a real
+  independent check even from the same hand.
+- **Structural concerns are deferred.** A structural problem in another capability is an observation
+  that spawns a new spec, never a marker in the one being built.
+
+## Faces — asymmetric loadout
+
+The two faces read different inputs. **Forward (solution-producer):** self-aligns the ungated
+`<unit>.solution.md`, where structure is chosen. **Backward (cold spec-judge):** grades structure
+from `spec.md` + the suite only — the solution is out of view (grader independence).
+
+## Key points (read-check)
+
+1. **No knowledge duplication** — one home per concept; but coincidental resemblance is not
+   duplication (don't merge things that change for different reasons). No conflict with conventions or
+   boundaries.
+2. **Placement matches the *declared* layout** (`sdd:spec-structure-governance`), not a preferred
+   one; one capability per node either way, never smeared across nodes.
+3. **A well-formed CFG** the suite's sections mirror.
+4. **Structural concerns in another capability are deferred** — an observation that spawns a new spec.

package/skills/blast-estimate/README.md

@@ -0,0 +1,47 @@
+# blast-estimate
+
+The concrete engine for **blast-estimate** — a read-only estimate of how much of the project a
+Mission could disturb, computed from its touch-set and the project corpus instead of the hand-typed
+guess: **breadth** (how many work areas, *and* whether the touch-set covers a project entirely),
+`centrality` (dependency fan-in — how many other work areas reference a touched one), and
+`sensitivity` (declared, never inferred, in the opt-in `.agents/sdd/sensitive-paths.toml`). Lines the
+computed level up against the Mission's declared blast (`agrees` / `under-called` / `over-called`).
+
+Breadth is `max(countScore, coverageScore)` — reach measured absolutely *and* relatively, whichever
+says more — so a fully-covered project computes `high` at **any** project size (≥2 areas), not only
+once the raw count crosses a bucket. See [`SKILL.md`](./SKILL.md) for the full rule and the
+load-bearing ≥2-area guard that keeps the project-wide and single-peripheral scenarios disjoint.
+
+Work-area recovery reuses [`touch-set-correction`](../touch-set-correction/SKILL.md)'s pure
+`fileToNode` over `discoverLayouts`' declared `ProjectLayout[]` — never a path-shape guess. A work
+area spans its **spec root and its impl root** (`sdd/mission-graph` lives at both
+`.agents/specs/sdd/mission-graph/` and `plugins/sdd/skills/mission-graph/`), and fan-in is measured
+across **both**, so centrality counts implementation dependency rather than spec prose alone.
+Layouts are injected, so tests construct them as fixtures.
+
+```bash
+node scripts/blast-estimate.mts --root <corpus> --touch-set sdd/mission-graph,sdd/blast-estimate --declared medium
+```
+
+Read-only, deterministic, reports-never-writes — the mission-graph's single writer records the
+computed level. See [`SKILL.md`](./SKILL.md) for the full contract and
+[`.agents/specs/sdd/blast-estimate/README.md`](../../../../.agents/specs/sdd/blast-estimate/README.md)
+for the authoritative behavior description and
+[`blast-estimate.feature`](../../../../.agents/specs/sdd/blast-estimate/blast-estimate.feature) for
+the frozen 21-scenario contract.
+
+Fan-in counts the reference forms the corpus really uses — the bare id, a `sdd:spec-gate` skill ref,
+a path under any **declared root** at any depth, and a same-project relative link — not the bare id
+alone, which matched almost nothing on a real tree. It stays **mention-based** by design; symbol-level
+dependency is `ssa-lowering` / `collision-ladder` territory.
+
+- **Skill contract:** [`SKILL.md`](./SKILL.md)
+- **Script:** [`scripts/blast-estimate.mts`](./scripts/blast-estimate.mts)
+- **Tests:** [`scripts/blast-estimate.test.mts`](./scripts/blast-estimate.test.mts) (`node:test`) —
+  one test per frozen scenario, titled `scenario: <verbatim frozen scenario name>`.
+- **Live-corpus smoke check:**
+  [`scripts/blast-estimate.smoke.test.mts`](./scripts/blast-estimate.smoke.test.mts) — **not** bound
+  to any frozen scenario. The frozen suite mandates constructed corpora, so it is structurally blind
+  to whether the engine measures real reach on a real tree; three defects reached an impl gate
+  green-on-all-21 for exactly that reason. This asserts live properties (never magic numbers) and is
+  the tripwire for that class.

package/skills/blast-estimate/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: blast-estimate
+description: "Partial Skill: invoke by name only — blast-estimate's engine that computes a Mission's blast (low/medium/high) from its touch-set plus the project corpus and lines it up against the hand-typed declared blast — the engine for the blast-estimate node, consumed by the mission-graph's writer. Not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Blast Estimate
+
+The concrete engine for **blast-estimate** — a read-only derivation that works out how much of the
+project a Mission could disturb, instead of trusting the hand-typed guess. Given a Mission's
+**touch-set** (the work areas it names) and the project corpus, it computes a **blast** level
+(`low` / `medium` / `high`) from three measured inputs and lines that level up against the Mission's
+hand-typed **declared** blast (`agrees` / `under-called` / `over-called`). See
+`.agents/specs/sdd/blast-estimate/README.md` for the full contract and vocabulary.
+
+## The three inputs
+
+- **count** — how many of the touch-set's areas resolve to a known work area in the corpus, plus
+  **coverage**: whether the touch-set covers *every* work area of a touched project. Together these
+  are **breadth** — absolute reach and relative reach.
+- **centrality** (dependency fan-in) — for each resolved area, how many *other* work areas hold at
+  least one file that **references** it, measured across the area's **full root set** —
+  implementation files count exactly as spec prose does. The `max` across the resolved areas is used.
+  See *The reference matcher* below: a bare id alone is **not** how real prose references an area.
+- **sensitivity** — whether a resolved area is **marked** in the opt-in
+  `.agents/sdd/sensitive-paths.toml` — a `sensitive = [ "id", ... ]` string array, parsed
+  line-anchored and lenient exactly as `manage-spec-anchors` parses `anchors = [ … ]`, so a leading
+  comment, a trailing comment, or a neighbouring key are all ordinary TOML and parse. A file with no
+  `sensitive` array at all is malformed and fails loud. **Only an absent file (`ENOENT`) is benign** —
+  no area is sensitive, not an error. **Every other read failure fails loud** — unparseable,
+  unreadable (permissions), or not a regular file — returning `computed: null` and an `error` naming
+  the file. The narrow ENOENT test is deliberate: swallowing the rest into "nothing marked" fails in
+  the **dangerous direction**, silently under-calling blast on exactly the areas a project marked as
+  needing care. An unreadable marking is not evidence of no markings.
+
+The arithmetic is bucketed and deliberately simple (the rubric fixes only the ordering properties,
+not the exact numbers):
+
+- **breadth** = `max(countScore, coverageScore)` — reach measured two ways, whichever says more:
+  - `countScore`: 1→0, 2-3→1, 4+→3 (absolute reach — touching many areas is broad even in a large
+    project the touch-set nowhere near covers)
+  - `coverageScore`: 3 iff the touch-set covers **every** work area of a touched project holding
+    **≥2** work areas, else 0 (relative reach — a 3-area project touched entirely *is* project-wide;
+    the barrier agreement must hold at every project size **≥2**, not only at 4+)
+- **centrality**: 0→0, 1-2→1, 3-6→2, 7+→3 (a genuine hub: touching an area a large share of the
+  project leans on is project-scale reach even at count 1). Calibrated against **real** fan-in, which
+  spans roughly 0–17 on a corpus of this size.
+- **sensitivity**: any marked area →+2
+
+Sum the three, then `score>=3` → `high`, `score>=1` → `medium`, `score==0` → `low`. A touch-set that
+resolves to **zero** known areas (including the empty touch-set) computes `unknown` — never `low`.
+
+The **≥2 work areas** guard on coverage is load-bearing, and it is keyed per **project**, not per
+corpus: a 1-area project inside a larger multi-project corpus is still never project-wide. The
+contract states the precondition itself — the project-wide scenario requires a project holding more
+than one work area, and *"a lone work area is its whole project but is not project-wide reach"* pins
+the 1-area answer to `low` **for a lone area with no fan-in and no marking**. Coverage is reach
+**relative** to a project, and a project of one has none to cover, so coverage never fires there and
+**breadth** rests on absolute count alone — centrality and sensitivity still score, so a lone area
+that is central or marked computes `medium` or `high`.
+
+Two exclusions are structural, not just documented: there is no compatibility/breaking-change input
+at all (no seam for it to enter the score), and centrality is **measured** fan-in only — a work
+area's name never enters the computation.
+
+## Work-area recovery — declared layouts, never a path shape
+
+Node recovery is **not this engine's to invent**: it reuses `touch-set-correction`'s pure
+**`fileToNode(path, layouts)`** over `discoverLayouts`' declared `ProjectLayout[]` (the same
+cross-skill reuse `collision-ladder` does). This is load-bearing — a work area spans **multiple
+declared roots**, a spec root *and* an impl root:
+
+```
+project "sdd" -> roots [".agents/specs/sdd", "plugins/sdd/skills"]
+  .agents/specs/sdd/mission-graph/README.md  -> sdd/mission-graph
+  plugins/sdd/skills/mission-graph/SKILL.md  -> sdd/mission-graph   # SAME node, two roots
+```
+
+A node's file set is every file under **any** of its roots, so fan-in measures the project's real
+lean on an area rather than spec-prose cross-reference. `estimateBlast` takes layouts **injected**
+(`fileToNode` is pure, so tests construct them as fixtures); the CLI sources them from
+`discoverLayouts`, overridable with `--layout`.
+
+## The reference matcher
+
+Fan-in counts the forms the corpus **actually uses** to name an area — a bare id is what a touch-set
+and the ledger write, not how prose references anything. For node `<p>/<cap>`:
+
+| form | example |
+|---|---|
+| bare id | `sdd/spec-gate` |
+| skill-style ref | `sdd:spec-gate` |
+| path under any **declared root**, at any depth | `plugins/sdd/skills/spec-gate/`, `.agents/specs/sdd/authoring/spec-gate/` |
+| relative sibling link (**same project only**) | `../spec-gate/`, `../../authoring/spec-gate/` |
+
+Path forms are **derived from the project's declared roots**, never hardcoded, so a re-rooted project
+keeps working; the any-depth segment matters because a node's spec can sit nested under its root. A
+relative link carries no project, so it is only counted within the same project — otherwise two
+projects sharing a capability name (`manage`, `design`) would cross-credit each other.
+
+This stays **mention-based and cheap** by design. Real produced/consumed symbol dependency is
+`ssa-lowering` / `collision-ladder` territory — the boundary is deliberate. Only the resolved areas
+are scored, so a one-area touch-set costs one matcher pass over the corpus rather than one per area.
+
+## Run it
+
+```bash
+node "<skill>/scripts/blast-estimate.mts" --root <repo> --touch-set a,b,c \
+  [--layout 'sdd:.agents/specs/sdd,plugins/sdd/skills']... \
+  [--declared low|medium|high|unknown] [--format toon|json]
+```
+
+- `--root` defaults to `.` (the repo root the layouts' roots and
+  `.agents/sdd/sensitive-paths.toml` resolve against).
+- `--layout` is repeatable (`<project>:<root1>,<root2>`, the same shape `touch-set-correction`
+  accepts). Omit it to auto-discover via `discover-specs`.
+- `--touch-set` is a comma-separated list of `project/capability` ids.
+- `--declared` is optional; omitted or `unknown` lines up as `no-declared` — the computed level still
+  returns on its own.
+- Default output is **TOON**; `--format json` emits the full `EstimateResult`: `resolved`,
+  `unresolved` (surfaced, never dropped), `computed`, `reasons` (`count`, `maxFanIn`,
+  `sensitiveAreas`, `projectWide`), and `lineUp`.
+
+## Boundaries
+
+Read-only: it composes a corpus scan and the touch-set it is handed, and **returns** an estimate — it
+writes no file and mutates no store. It does **not** judge compatibility/breakage (a separate
+dimension), rank by surface location, decide HITL vs AFK, render a self-clear-or-escalate verdict (it
+only *modulates* a conductor's judgment), *produce* a touch-set (it consumes one — pre-work declared,
+or `touch-set-correction`'s post-work corrected one), or **reimplement node recovery** (it imports
+`fileToNode`; it never reinvents or shells out to it).