cyber-sdd 0.0.0

package/skills/blast-estimate/scripts/blast-estimate.mts

@@ -0,0 +1,583 @@
+#!/usr/bin/env node
+// blast-estimate — the concrete engine for blast-estimate's derivation: compute a Mission's BLAST
+// (low/medium/high) from its touch-set + the project corpus instead of trusting the hand-typed guess,
+// then line the computed level up against the declared one (agrees / under-called / over-called). See
+// .agents/specs/sdd/blast-estimate/README.md for the full contract this mirrors.
+//
+// Three inputs, each measured — never inferred — from the corpus:
+//   - count       — how many of the touch-set's areas resolve to a known work area
+//   - centrality  — dependency fan-in: how many OTHER work areas' files reference a touched one
+//   - sensitivity — whether a touched area is MARKED in the opt-in `.agents/sdd/sensitive-paths.toml`
+//     (absent file = no area sensitive, not an error; a file that fails to parse fails LOUD — the
+//     estimate computes no level rather than silently reading it as "nothing marked")
+//
+// Two exclusions are structural, not just documented: this engine takes no "breaking"/compatibility
+// input at all (that dimension cannot leak in), and centrality is measured fan-in only — a work area's
+// NAME (e.g. "public") never enters the score.
+//
+// A work area not found in the corpus is SURFACED (`unresolved`), never silently dropped. An empty
+// touch-set — or one that resolves to zero known areas — computes `unknown`, never `low` ("nothing
+// touched is not evidence of low reach").
+//
+// Work-area recovery is NOT this engine's to invent: it REUSES the sibling touch-set-correction's
+// pure `fileToNode(path, layouts)` over `discoverLayouts`' declared `ProjectLayout[]` — the same
+// cross-skill reuse collision-ladder does (which imports `fileToNode` + `collectChangedFiles` from
+// the same module). This matters and is not cosmetic: a work area spans MULTIPLE declared roots — a
+// spec root AND an impl root (`sdd/mission-graph` lives at BOTH `.agents/specs/sdd/mission-graph/`
+// and `plugins/sdd/skills/mission-graph/`) — so a node's identity comes from the declared layout,
+// never from a path's shape. Any local walk that keyed on "first two segments" would split one node
+// in two, miss it entirely from the repo root, and measure fan-in over spec prose alone.
+//
+// Read-only: only readdirSync/readFileSync/statSync ever run here. It RETURNS the estimate; the
+// mission-graph's single writer records it. Pure functions are exported for node:test; running the
+// file directly drives the CLI.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import {
+	discoverLayouts,
+	fileToNode,
+	type ProjectLayout,
+} from '../../touch-set-correction/scripts/touch-set-correction.mts'
+
+export type { ProjectLayout }
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
+const SENSITIVE_PATHS_FILE = '.agents/sdd/sensitive-paths.toml'
+
+export type BlastLevel = 'low' | 'medium' | 'high'
+export type DeclaredBlast = BlastLevel | 'unknown'
+
+// ── Corpus scan — work-area discovery over the DECLARED layouts (never a path-shape guess) ──
+
+/** Every repo-relative file path under `dir` (recursively), skipping build/vendor noise. Paths are
+ *  made relative with `path.relative`, never string-sliced: `join('.', x)` normalizes the `./` away,
+ *  so slicing by `root.length` silently corrupts every path under a RELATIVE root (`--root .`, the
+ *  CLI's default) while working fine under an absolute one. */
+function walkFiles(dir: string, root: string, out: string[]): void {
+	let entries: import('node:fs').Dirent[]
+	try {
+		entries = readdirSync(dir, { withFileTypes: true })
+	} catch {
+		return // an undeclared or absent root contributes nothing
+	}
+	for (const entry of entries) {
+		if (SKIP_DIRS.has(entry.name)) continue
+		const full = join(dir, entry.name)
+		if (entry.isDirectory()) walkFiles(full, root, out)
+		else out.push(relative(root, full).replace(/\\/g, '/'))
+	}
+}
+
+/**
+ * discoverWorkAreas — the corpus's work areas, grouped by node id, over the DECLARED layouts. Walks
+ * every root of every project, maps each file through touch-set-correction's pure `fileToNode`, and
+ * groups by the node it names. Because a node's roots include BOTH its spec root and its impl root,
+ * one node's file set spans both trees — which is exactly what makes fan-in measure real dependency
+ * rather than spec-prose cross-reference. A file that maps to no node (`fileToNode` returns null —
+ * the existing "unmapped" concept) is dropped from the area map, never invented into an atom.
+ *
+ * Values are repo-relative paths; `root` is the repo root they are resolved against.
+ */
+export function discoverWorkAreas(layouts: ProjectLayout[], root: string): Map<string, string[]> {
+	const byNode = new Map<string, string[]>()
+	const seen = new Set<string>()
+	for (const layout of layouts) {
+		for (const rawRoot of layout.roots) {
+			const rel = rawRoot.replace(/\/+$/, '')
+			const files: string[] = []
+			walkFiles(join(root, rel), root, files)
+			for (const path of files) {
+				if (seen.has(path)) continue // a path under two declared roots is counted once
+				seen.add(path)
+				const node = fileToNode(path, layouts)
+				if (node === null) continue // unmapped — surfaced by touch-set-correction, not an atom here
+				const bucket = byNode.get(node)
+				if (bucket) bucket.push(path)
+				else byNode.set(node, [path])
+			}
+		}
+	}
+	return byNode
+}
+
+function escapeRegExp(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+// ── The reference matcher — the forms the corpus ACTUALLY uses to name a work area ──
+//
+// A bare `project/capability` id is what a touch-set and the ledger write, but it is NOT how prose
+// references an area. Real references are links and paths; matching the bare id alone scored 56 of
+// this repo's 62 `sdd` areas at fan-in 0 — including `sdd/spec-gate`, referenced by a dozen files —
+// while the few non-zero scores came from glossary rows using an id as a typographic EXAMPLE. That
+// measures "how often a name got used as documentation filler", not "how much of the project leans
+// on this area", which is the opposite of what the rubric asks for and worse than no signal at all.
+//
+// Every path form is derived from the project's DECLARED layout roots, never hardcoded, so a
+// re-rooted project keeps working. The `(?:[\w.-]+/)*` segment matters: a node's spec can sit NESTED
+// under its root (`.agents/specs/sdd/authoring/spec-gate/`), in which case `fileToNode`'s
+// capability-first rule maps the spec side to `sdd/authoring` and only the impl side to
+// `sdd/spec-gate` — so a flat `<root>/<capability>/` derivation would still miss the spec path.
+//
+// This stays MENTION-based and cheap by design. Real produced/consumed symbol dependency is
+// ssa-lowering / collision-ladder territory; the boundary was never the problem, only the recall.
+
+/** Left boundary: a reference must not start mid-token. */
+const LB = '(?:^|[^\\w/:.-])'
+
+function stripTrailingSlash(s: string): string {
+	return s.replace(/\/+$/, '')
+}
+
+/** The reference forms that name `nodeId` unambiguously from ANYWHERE (each is project-qualified):
+ *  the bare id (`sdd/spec-gate`), the skill-style ref (`sdd:spec-gate`), and a path under any of the
+ *  project's declared roots, at any nesting depth (`plugins/sdd/skills/spec-gate/`,
+ *  `.agents/specs/sdd/authoring/spec-gate/`). */
+function globalReferencePattern(project: string, capability: string, roots: string[]): RegExp {
+	const alts = [
+		`${LB}${escapeRegExp(`${project}/${capability}`)}(?![\\w-])`,
+		`${LB}${escapeRegExp(`${project}:${capability}`)}(?![\\w-])`,
+	]
+	for (const root of roots) {
+		alts.push(`${escapeRegExp(stripTrailingSlash(root))}/(?:[\\w.-]+/)*${escapeRegExp(capability)}/`)
+	}
+	return new RegExp(alts.join('|'))
+}
+
+/** The relative-link form (`../spec-gate/`, `../../authoring/spec-gate/`) — a sibling-node link. It
+ *  carries no project, so it is only counted from a file in the SAME project; otherwise two projects
+ *  sharing a capability name (`manage`, `design`) would cross-credit each other's fan-in. */
+function relativeReferencePattern(capability: string): RegExp {
+	return new RegExp(`(?:\\.\\./)+(?:[\\w.-]+/)*${escapeRegExp(capability)}/`)
+}
+
+function projectRoots(project: string, layouts: ProjectLayout[]): string[] {
+	return layouts.filter((l) => l.project === project).flatMap((l) => l.roots)
+}
+
+/**
+ * computeFanInMap — centrality for the requested areas: area A's fan-in is the number of OTHER areas
+ * holding at least one file that REFERENCES A in any of the forms the corpus actually uses (see
+ * `globalReferencePattern` / `relativeReferencePattern`). Because a node's file set spans its spec
+ * AND impl roots, a reference from an implementation file counts exactly as spec prose does — fan-in
+ * measures the project's real lean on an area. An area's own files never count toward its own fan-in.
+ *
+ * `targets` defaults to every known area; passing only the areas actually being scored keeps the CLI
+ * cheap (a one-area touch-set costs 1 pattern × N files instead of 229 × N). Each file is read at
+ * most once, and an owner already credited for a target is skipped.
+ */
+export function computeFanInMap(
+	byNode: Map<string, string[]>,
+	root: string,
+	layouts: ProjectLayout[],
+	targets?: string[],
+): Map<string, number> {
+	const ids = targets ?? [...byNode.keys()]
+	const specs = ids.map((id) => {
+		const slash = id.indexOf('/')
+		const project = id.slice(0, slash)
+		const capability = id.slice(slash + 1)
+		return {
+			id,
+			project,
+			global: globalReferencePattern(project, capability, projectRoots(project, layouts)),
+			relative: relativeReferencePattern(capability),
+		}
+	})
+	const referencers = new Map<string, Set<string>>(ids.map((id) => [id, new Set<string>()]))
+	for (const [owner, files] of byNode) {
+		const ownerProject = projectOf(owner)
+		for (const rel of files) {
+			let text: string
+			try {
+				text = readFileSync(join(root, rel), 'utf8')
+			} catch {
+				continue
+			}
+			for (const spec of specs) {
+				if (spec.id === owner) continue
+				const seen = referencers.get(spec.id)
+				if (seen?.has(owner)) continue // this owner already counted for `spec.id`
+				// A relative link carries no project, so it only counts within the same project.
+				if (spec.global.test(text) || (ownerProject === spec.project && spec.relative.test(text))) {
+					seen?.add(owner)
+				}
+			}
+		}
+	}
+	return new Map(ids.map((id) => [id, referencers.get(id)?.size ?? 0]))
+}
+
+// ── Sensitivity — declared, never inferred ──
+
+/**
+ * Parses the opt-in `.agents/sdd/sensitive-paths.toml`: a `sensitive = [ "id", ... ]` string array.
+ *
+ * LINE-anchored and lenient, matching manage-spec-anchors' `anchors = [ … ]` parser byte for byte in
+ * shape — a leading comment, a trailing comment, or a neighbouring key are ordinary TOML and must
+ * parse. An earlier whole-file-anchored regex rejected all three, so a perfectly valid file that
+ * marked an area computed no level at all.
+ *
+ * An EMPTY file is `[]` (a real "nothing marked" declaration). A file with no `sensitive` array at
+ * all throws — that is genuinely malformed, and an unreadable marking is not evidence of no
+ * markings.
+ */
+export function parseSensitivePaths(text: string): string[] {
+	if (text.trim() === '') return []
+	const m = /(^|\n)\s*sensitive\s*=\s*\[([\s\S]*?)\]/.exec(text)
+	if (!m) throw new Error('expected a `sensitive = [...]` array')
+	const out: string[] = []
+	for (const q of m[2].matchAll(/"([^"]*)"|'([^']*)'/g)) out.push((q[1] ?? q[2]).trim())
+	return out.filter((s) => s !== '')
+}
+
+export type SensitiveResult = { ok: true; marked: string[] } | { ok: false; error: string }
+
+/** Reads the opt-in sensitive-paths file. **Absent** (ENOENT) = `{ ok: true, marked: [] }` — no area
+ *  is sensitive, and that is NOT an error. Anything else — present-but-unparseable, unreadable
+ *  (permissions), or not a regular file — = `{ ok: false, error }`, and the caller computes no level.
+ *
+ *  ONLY ENOENT is benign. A bare `catch` here would swallow EACCES and a directory-at-the-path into
+ *  "no markings", which fails in the DANGEROUS direction: the estimate silently UNDER-calls blast on
+ *  exactly the areas a project took the trouble to mark. A read that cannot classify must fail loud,
+ *  never default to the safe-looking answer — the same duty the absent-vs-unparseable scenarios draw:
+ *  an unreadable marking is not evidence of no markings. */
+export function readSensitivePaths(corpusRoot: string): SensitiveResult {
+	const file = join(corpusRoot, SENSITIVE_PATHS_FILE)
+	let text: string
+	try {
+		if (!statSync(file).isFile()) {
+			return { ok: false, error: `${SENSITIVE_PATHS_FILE} is not a regular file` }
+		}
+		text = readFileSync(file, 'utf8')
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { ok: true, marked: [] }
+		return { ok: false, error: `${SENSITIVE_PATHS_FILE} is unreadable: ${(err as Error).message}` }
+	}
+	try {
+		return { ok: true, marked: parseSensitivePaths(text) }
+	} catch (err) {
+		return { ok: false, error: `${SENSITIVE_PATHS_FILE} is unreadable: ${(err as Error).message}` }
+	}
+}
+
+// ── The computation — count × centrality × sensitivity ──
+//
+// The rubric fixes the three inputs and their ordering properties; the exact arithmetic is this
+// engine's choice (deliberately unpinned — see the node README). Buckets, not a smooth curve, keep
+// the mapping easy to explain and to hold constant under review:
+//   - breadth     max(countScore, coverageScore) — how much of the project is disturbed, 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 that has
+//         >= 2 work areas, else 0 (relative reach: a 3-area project touched entirely IS
+//         project-wide — the barrier agreement holds at every project size >= 2, not just 4+)
+//   - centrality  0 → 0; 1-2 → 1; 3+ → 2
+//   - sensitivity any touched area marked → +2 (a single marking is enough to move the level)
+// score >= 3 → high; score >= 1 → medium; score 0 → low.
+//
+// The `>= 2 work areas` guard on coverage is load-bearing, not a nicety, and since #238 it is the
+// CONTRACT rather than this engine's private tiebreaker. It is keyed per PROJECT, not per corpus: a
+// 1-area project inside a larger multi-project corpus is still never project-wide.
+//
+// Before #238 the frozen suite was self-contradictory here — on a 1-area project "a single
+// peripheral work area" (→ low) and "a touch-set reaching across every work area of its project"
+// (→ high) described the SAME input with opposite Thens, and this guard silently picked the winner.
+// The suite now 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.
+
+function countScore(n: number): number {
+	if (n <= 1) return 0
+	if (n <= 3) return 1
+	return 3
+}
+
+const COVERAGE_SCORE = 3
+
+// Centrality thresholds are calibrated against REAL fan-in, which spans roughly 0..17 on a corpus of
+// this size. They were originally 0/1-2/3+ — tuned while the reference matcher only saw bare ids, so
+// the observed corpus max was 4 and "3+" read as the top of the scale. With the matcher fixed, "3+"
+// covered most of the distribution and no single area could ever reach `high` on reach alone, which
+// under-called every hub (`sdd/spec-gate`, referenced by 10 other areas, computed `medium`). The top
+// tier now marks a genuine hub: touching an area that a large share of the project leans on IS
+// project-scale reach, even at count 1.
+function centralityScore(fanIn: number): number {
+	if (fanIn <= 0) return 0
+	if (fanIn <= 2) return 1
+	if (fanIn <= 6) return 2
+	return 3
+}
+
+const SENSITIVITY_SCORE = 2
+
+export function levelFromScore(score: number): BlastLevel {
+	if (score >= 3) return 'high'
+	if (score >= 1) return 'medium'
+	return 'low'
+}
+
+export interface Reasons {
+	count: number
+	maxFanIn: number
+	sensitiveAreas: string[]
+	/** Every touched project the touch-set covers ENTIRELY (and which has >= 2 work areas) — the
+	 *  coverage half of breadth, named so a `high` on reach alone is explainable. */
+	projectWide: string[]
+}
+
+/** The project a work area belongs to — the first segment of its `project/capability` id. */
+function projectOf(nodeId: string): string {
+	return nodeId.split('/')[0]
+}
+
+/**
+ * projectsCoveredEntirely — the touched projects whose EVERY work area is in the touch-set, among
+ * projects holding >= 2 work areas. Coverage is relative reach: it asks what fraction of a project
+ * is disturbed, where `count` only asks how many areas in absolute terms. A project with a single
+ * work area never qualifies (see the guard note above).
+ *
+ * "Every work area of its project" means every area the LAYOUTS declare — `byNode` is the discovered
+ * area map keyed by node id, so a project's area set is its nodes across all of its declared roots
+ * (spec + impl), not whatever a directory walk happened to find.
+ */
+export function projectsCoveredEntirely(resolved: string[], byNode: Map<string, string[]>): string[] {
+	const areasByProject = new Map<string, string[]>()
+	for (const node of byNode.keys()) {
+		const p = projectOf(node)
+		const areas = areasByProject.get(p)
+		if (areas) areas.push(node)
+		else areasByProject.set(p, [node])
+	}
+	const resolvedSet = new Set(resolved)
+	const covered: string[] = []
+	for (const project of new Set(resolved.map(projectOf))) {
+		const areas = areasByProject.get(project) ?? []
+		if (areas.length < 2) continue // a 1-area project is never "project-wide" — see the guard note
+		if (areas.every((a) => resolvedSet.has(a))) covered.push(project)
+	}
+	return covered.sort()
+}
+
+/** The pure scoring step, once `count`/`maxFanIn`/`sensitiveAreas`/`projectWide` are known. Exported
+ *  so the ordering-property scenarios (hub-vs-leaf, marked-vs-unmarked) can be driven directly. */
+export function scoreBlast(
+	count: number,
+	maxFanIn: number,
+	sensitiveAreas: string[],
+	projectWide: string[] = [],
+): { level: BlastLevel; reasons: Reasons } {
+	const breadth = Math.max(countScore(count), projectWide.length > 0 ? COVERAGE_SCORE : 0)
+	const score = breadth + centralityScore(maxFanIn) + (sensitiveAreas.length > 0 ? SENSITIVITY_SCORE : 0)
+	return { level: levelFromScore(score), reasons: { count, maxFanIn, sensitiveAreas, projectWide } }
+}
+
+// ── The line-up — declared against computed ──
+
+export type LineUpOutcome = 'agrees' | 'under-called' | 'over-called' | 'no-declared'
+
+export interface LineUp {
+	outcome: LineUpOutcome
+	computed: BlastLevel
+	declared?: BlastLevel
+}
+
+const ORDER: BlastLevel[] = ['low', 'medium', 'high']
+
+/** Lines the computed level up against the hand-typed declared one. An absent or `unknown` declared
+ *  blast is not an error — it is `no-declared`, and the computed level still stands on its own. */
+export function lineUp(computed: BlastLevel, declared?: DeclaredBlast): LineUp {
+	if (declared === undefined || declared === 'unknown') return { outcome: 'no-declared', computed }
+	const di = ORDER.indexOf(declared)
+	const ci = ORDER.indexOf(computed)
+	if (di === ci) return { outcome: 'agrees', computed, declared }
+	if (di < ci) return { outcome: 'under-called', computed, declared }
+	return { outcome: 'over-called', computed, declared }
+}
+
+// ── The whole estimate — pure once handed a corpus scan ──
+
+export interface EstimateResult {
+	touchSet: string[]
+	resolved: string[]
+	unresolved: string[]
+	computed: BlastLevel | 'unknown' | null
+	reasons: Reasons | null
+	lineUp: LineUp | null
+	error?: string
+}
+
+/** What `estimateBlast` needs beyond the touch-set and the layouts. `root` is the repo root the
+ *  layouts' repo-relative roots (and the opt-in sensitive-paths file) resolve against. */
+export interface EstimateOptions {
+	root?: string
+	declared?: DeclaredBlast
+}
+
+/**
+ * estimateBlast — the whole derivation, over INJECTED layouts. Discovers the corpus's work areas by
+ * mapping every file under every declared root through touch-set-correction's pure `fileToNode`,
+ * resolves the touch-set against those areas (unresolved areas are surfaced, never dropped), reads
+ * the opt-in sensitive-paths file (fails loud on a malformed one — computed/reasons/lineUp all come
+ * back null, `error` names why), and — when at least one area resolved — scores
+ * breadth × centrality × sensitivity and lines the result up against `opts.declared`. A touch-set
+ * that resolves to zero known areas (including the empty touch-set) computes `unknown`: nothing
+ * touched is not evidence of low reach.
+ *
+ * Layouts are INJECTED rather than discovered here: `fileToNode` is pure, so tests construct layouts
+ * as fixtures over a constructed corpus (the frozen suite's "never the live corpus" preamble holds),
+ * while the CLI sources them from `discoverLayouts`.
+ */
+export function estimateBlast(
+	touchSet: string[],
+	layouts: ProjectLayout[],
+	opts: EstimateOptions = {},
+): EstimateResult {
+	const root = opts.root ?? '.'
+	const byNode = discoverWorkAreas(layouts, root)
+	const known = new Set(byNode.keys())
+	// A touch-set is a SET of work areas: dedupe before counting. `count` measures how many distinct
+	// areas are disturbed, so naming one area twice must not read as twice the reach — otherwise the
+	// same change scores a higher level for being typed redundantly. The sibling touch-set-correction
+	// dedupes its own output, but the mission-graph store does not, so a duplicate genuinely arrives.
+	const unique = [...new Set(touchSet)]
+	const resolved = unique.filter((a) => known.has(a))
+	const unresolved = unique.filter((a) => !known.has(a))
+
+	const sensitive = readSensitivePaths(root)
+	if (!sensitive.ok) {
+		return { touchSet, resolved, unresolved, computed: null, reasons: null, lineUp: null, error: sensitive.error }
+	}
+
+	if (resolved.length === 0) {
+		return {
+			touchSet,
+			resolved,
+			unresolved,
+			computed: 'unknown',
+			reasons: { count: 0, maxFanIn: 0, sensitiveAreas: [], projectWide: [] },
+			lineUp: null,
+		}
+	}
+
+	const markedSet = new Set(sensitive.marked)
+	// Only the resolved areas are scored — fan-in for the rest of the corpus is never asked for.
+	const fanInMap = computeFanInMap(byNode, root, layouts, resolved)
+	const maxFanIn = Math.max(...resolved.map((a) => fanInMap.get(a) ?? 0))
+	const sensitiveAreas = resolved.filter((a) => markedSet.has(a))
+	const projectWide = projectsCoveredEntirely(resolved, byNode)
+	const { level, reasons } = scoreBlast(resolved.length, maxFanIn, sensitiveAreas, projectWide)
+
+	return { touchSet, resolved, unresolved, computed: level, reasons, lineUp: lineUp(level, opts.declared) }
+}
+
+// ── Render (TOON — the token-efficient tabular form the repo's other sdd engines emit) ──
+
+function toonQuote(v: string): string {
+	if (v === '' || /[",;]/.test(v) || v !== v.trim()) return `"${v.replace(/"/g, '""')}"`
+	return v
+}
+
+export function renderResultToon(r: EstimateResult): string {
+	if (r.error) {
+		return [
+			`blast-estimate: error="${r.error}"`,
+			`unresolved[${r.unresolved.length}]: ${r.unresolved.map(toonQuote).join(';')}`,
+		].join('\n')
+	}
+	const lines: string[] = []
+	const lu = r.lineUp
+	const lineUpPart = lu
+		? lu.outcome === 'no-declared'
+			? 'lineup=no-declared'
+			: `lineup=${lu.outcome}(declared=${lu.declared})`
+		: 'lineup=n/a'
+	lines.push(`blast-estimate: computed=${r.computed} ${lineUpPart}`)
+	if (r.reasons) {
+		lines.push(
+			`reasons: count=${r.reasons.count} maxFanIn=${r.reasons.maxFanIn} sensitiveAreas=[${r.reasons.sensitiveAreas.join(';')}] projectWide=[${r.reasons.projectWide.join(';')}]`,
+		)
+	}
+	lines.push(`resolved[${r.resolved.length}]: ${r.resolved.map(toonQuote).join(';')}`)
+	lines.push(`unresolved[${r.unresolved.length}]: ${r.unresolved.map(toonQuote).join(';')}`)
+	return lines.join('\n')
+}
+
+// ── CLI ──
+
+function flag(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name)
+	return i === -1 ? undefined : argv[i + 1]
+}
+
+function allFlags(argv: string[], name: string): string[] {
+	const out: string[] = []
+	for (let i = 0; i < argv.length; i++) {
+		if (argv[i] === name && argv[i + 1] !== undefined) out.push(argv[i + 1])
+	}
+	return out
+}
+
+function splitCsv(v: string | undefined): string[] {
+	if (v === undefined || v === '') return []
+	return v
+		.split(',')
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0)
+}
+
+/** Parses one `--layout '<project>:<root1>,<root2>'` flag value into a ProjectLayout (the same shape
+ *  and flag touch-set-correction accepts, so the two tools take identical layout overrides). */
+export function parseLayoutFlag(value: string): ProjectLayout | null {
+	const idx = value.indexOf(':')
+	if (idx === -1) return null
+	const project = value.slice(0, idx).trim()
+	const roots = splitCsv(value.slice(idx + 1))
+	if (project === '' || roots.length === 0) return null
+	return { project, roots }
+}
+
+/** The legal `--declared` values, exactly. Returns `null` for anything else so the CLI can fail loud
+ *  rather than let an unranked value masquerade as "below everything". Case-sensitive on purpose: the
+ *  store writes these lowercase, and quietly accepting `High` would invite a second spelling. */
+export function parseDeclared(raw: string): DeclaredBlast | null {
+	return raw === 'low' || raw === 'medium' || raw === 'high' || raw === 'unknown' ? raw : null
+}
+
+export function main(argv: string[]): number {
+	const root = flag(argv, '--root') ?? '.'
+	const touchSet = splitCsv(flag(argv, '--touch-set'))
+	const declaredRaw = flag(argv, '--declared')
+	// Validate rather than cast. `lineUp` ranks via ORDER.indexOf, so an unrecognized value scores -1
+	// and reads as "below every computed level" — silently fabricating the `under-called` finding this
+	// tool exists to raise, out of nothing but a typo. Fail loud instead: the same duty the
+	// sensitive-paths reader honors, and the dangerous direction is the one to refuse.
+	const declared = declaredRaw === undefined ? undefined : parseDeclared(declaredRaw)
+	if (declared === null) {
+		process.stderr.write(
+			`blast-estimate: --declared must be one of low, medium, high, unknown (got "${declaredRaw}")\n`,
+		)
+		return 1
+	}
+	const format = flag(argv, '--format') === 'json' ? 'json' : 'toon'
+
+	// Layouts come from `--layout` when given, else from discover-specs via discoverLayouts — the
+	// same resolution order touch-set-correction uses.
+	const layoutFlags = allFlags(argv, '--layout')
+	const layouts =
+		layoutFlags.length > 0
+			? layoutFlags.map(parseLayoutFlag).filter((l): l is ProjectLayout => l !== null)
+			: discoverLayouts(root, root)
+
+	const result = estimateBlast(touchSet, layouts, { root, declared })
+
+	process.stdout.write(`${format === 'json' ? JSON.stringify(result, null, 2) : renderResultToon(result)}\n`)
+	return result.error ? 1 : 0
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

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

@@ -0,0 +1,47 @@
+# builder-impl-governance
+
+This is an internal SDD governance about the Builder's bar at the **impl gate**.
+
+It answers two questions: does the implementation meet the frozen suite, and is each scenario
+verified at a level that earns confidence? In SDD, the `.feature` suite is frozen at the spec gate —
+it is the contract the implementation is built against and cannot be edited to make the build pass.
+This bar governs how conformance to that contract is demonstrated.
+
+It is one half of a matched pair: its sibling **`builder-spec-governance`** asks "is the contract
+testable and covered?" at the spec gate; this bar asks "does the implementation meet that frozen
+contract?" at the impl gate.
+
+## What it requires
+
+| Requirement | What it means |
+| --- | --- |
+| **The bar is not self-set** | Each check derives from the frozen suite — one per scenario — never free-authored from the producer's sense of done. The cold impl-judge re-derives the oracle (the expected answer) independently (ADR-0016). |
+| **Verify as high as it doesn't hurt** | Choose each scenario's verification *level* to maximize confidence until cost, fragility, or feasibility bites: a cheap base, a thin end-to-end cap on the paths that matter, and boundary (the external dependency mocked) as the honest substitute where end-to-end is infeasible or unsafe. Record the level chosen and why. |
+| **A graded subject still yields a boolean** | A non-deterministic subject reaches the per-scenario boolean through a rubric plus a threshold over N runs; the rubric stays out of the `.feature`. |
+| **No green-by-tampering** | Passing means the behavior holds — never that a check was edited to pass or the frozen suite modified to make the implementation conform. |
+| **Deterministic combinatorics go to units** | Where the domain has a deterministic inner layer, its combinatorial space (truth tables, matrices) is covered with unit tests drawn from the inner rules — the pyramid's base, separate from the one-verification-per-scenario duty. Missing that coverage is its own finding and withholds the pass. A non-deterministic subject has no such layer — verify at the acceptance level only. |
+
+This is the SDD default for the `builder` impl bar; a plugin may bind its own per artifact-type, and
+this one loads when the registry leaves `builder`/`impl` unbound.
+
+## Usage
+
+One merged bar loaded by both faces at the **impl gate**:
+
+- **impl-producer:** builds to it — derives its checks from the frozen suite and picks each
+  scenario's verification level
+- **impl-judge:** verifies against it, re-deriving the oracle independently
+
+`producer ≠ judge` holds at the agent level — the same bar, two independent readers.
+
+## Related governances
+
+This bar owns conformance and per-scenario verification level. Its neighbors own everything
+around that:
+
+- **`builder-spec-governance`** — the other half of the pair: testability and coverage of the
+  contract, judged at the spec gate. That bar freezes what must hold; this one verifies it held.
+- **`architect-impl-governance`** — the suite's overall pyramid shape. This bar picks each
+  scenario's level; the whole-suite shape is the architect's call.
+
+Internal SDD governance (`user-invocable: false`). Not triggered by users directly.

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

@@ -0,0 +1,47 @@
+---
+name: builder-impl-governance
+description: "Partial Skill: invoke by name only"
+user-invocable: false
+metadata:
+  actor: builder
+  gate: impl
+  compose: union
+---
+
+# Builder-Impl Governance — the conformance & verification-level bar
+
+The **Builder** bar at the **impl gate**: does the implementation meet the frozen suite, and is
+each scenario verified at a level that earns confidence? Loaded by both faces. The SDD default for the
+`builder` impl bar; a plugin may bind its own, and this loads when the registry leaves `builder`/`impl`
+unbound.
+
+## The bar
+
+- **The bar is not self-set.** Each check derives from the frozen suite — one per scenario —
+  never free-authored from the producer's sense of done. The cold impl-judge re-derives the oracle
+  independently (ADR-0016).
+- **Verify as high as it doesn't hurt.** Choose each scenario's verification **level** to maximize
+  confidence until cost, fragility, or feasibility bites: a cheap base, a **thin e2e cap** on the
+  paths that matter, **boundary** (the external mocked) as the honest substitute where e2e is
+  infeasible or unsafe. **Record the level and why.** The suite's overall pyramid shape is the
+  architect's call (`sdd:architect-impl-governance`).
+- **A graded subject still yields a boolean.** Reach the per-scenario boolean through a rubric +
+  threshold over N runs; the rubric stays out of the `.feature`.
+- **No green-by-tampering.** Passing means the behavior holds, not that a check was edited to pass;
+  the frozen suite is never modified to make the implementation conform.
+- **Deterministic combinatorics go to units.** Where the domain has a deterministic inner layer, cover
+  its combinatorial space (truth tables, matrices) with unit tests drawn from the inner rules — the
+  pyramid's base, separate from the one-verification-per-scenario duty. Missing that coverage is its
+  own finding and withholds the pass. A non-deterministic subject has no such layer — verify at the
+  acceptance level only.
+
+## Key points (read-check)
+
+1. **The bar is not self-set** — checks derive from the frozen suite, one per scenario; the judge
+   re-derives the oracle independently.
+2. **Verify as high as it doesn't hurt** — cheap base, thin e2e cap, boundary as substitute where e2e
+   is infeasible/unsafe; record level and why.
+3. **No green-by-tampering** — passing is the behavior holding, never an edited check or a modified
+   suite.
+4. **Deterministic combinatorics go to units** (the pyramid base); missing that coverage withholds the
+   pass; a non-deterministic subject verifies at the acceptance level only.