cyber-sdd 0.0.0

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

@@ -0,0 +1,49 @@
+# builder-spec-governance
+
+This is an internal SDD governance about the Builder's bar at the **spec gate**.
+
+It answers one question: is this **capability** fully and testably specified? In SDD, a capability's
+contract is written down twice — as a `spec.md` (the decisions it makes, drawn as a **control-flow
+graph**, or CFG) and as a `.feature` suite (one test scenario per branch of that CFG). This bar
+judges whether that contract is complete and checkable *before* anyone builds against it. It judges
+the contract itself, read from the spec plus its suite — not how the document is written, which is a
+different bar
+(`spec-format-governance`).
+
+It is one half of a matched pair: this bar asks "is the contract testable and covered?" at the spec
+gate; its sibling **`builder-impl-governance`** asks "does the implementation meet that frozen
+contract?" at the impl gate.
+
+## What it requires
+
+| Requirement | What it means |
+| --- | --- |
+| **Every branch is covered** | Each edge of the capability's CFG has its scenario, and every guard/negative edge is paired with a positive companion. The scenario map is 1:1 in both directions — no orphan scenario, no uncovered edge. |
+| **Every scenario is testable** | Each scenario asserts an observable outcome a check can confirm — a boolean, no "sometimes". A behavior the capability cannot expose cannot be specced. |
+| **A graded subject is still a boolean** | A non-deterministic capability (one whose output varies run to run) still reaches a per-scenario boolean, through a rubric plus a threshold over N runs. The rubric form stays out of the boolean `.feature`, carried as a judge-only `@rubric` scenario. |
+
+This is the SDD default for the `builder` spec bar; a plugin may bind its own per artifact-type, and
+this one loads when the registry leaves `builder`/`spec` unbound.
+
+## Usage
+
+One merged bar loaded by both faces at the **spec gate**:
+
+- **spec-producer:** self-aligns to it while writing the testable suite
+- **cold spec-judge:** grades coverage and testability against it
+
+`producer ≠ judge` holds at the agent level — the same bar, two independent readers.
+
+## Related governances
+
+This bar owns the testability and coverage of the capability's contract. Its neighbors own
+everything around that:
+
+- **`builder-impl-governance`** — the other half of the pair: whether the *implementation* meets the
+  frozen contract, judged at the impl gate. This bar freezes what must hold; that one verifies it held.
+- **`spec-format-governance`** — the document's prose and section layout. That bar reads the
+  `spec.md` as a document; this bar reads the spec + suite as a contract.
+- **`suite-format-governance`** — how the `.feature` suite itself is written, including the 1:1
+  scenario-map rule this bar enforces coverage against.
+
+Internal SDD governance (`user-invocable: false`). Not triggered by users directly.

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

@@ -0,0 +1,36 @@
+---
+name: builder-spec-governance
+description: "Partial Skill: invoke by name only"
+user-invocable: false
+metadata:
+  actor: builder
+  gate: spec
+  compose: union
+---
+
+# Builder-Spec Governance — the testability & coverage bar
+
+The **Builder** bar at the **spec gate**: is this **capability** fully and testably specified? Judges
+the capability's contract (read from its spec + suite), not the document's prose — that is
+`sdd:spec-format-governance`. Loaded by both faces. The SDD default for the `builder` spec bar; a
+plugin may bind its own, and this loads when the registry leaves `builder`/`spec` unbound.
+
+## The bar
+
+- **Every branch of the capability is covered.** Each edge of its control-flow graph (CFG) has its
+  scenario, and every guard/negative edge is paired with a positive companion. The **scenario map
+  is 1:1** — no orphan scenario, no uncovered edge (`sdd:suite-format-governance`).
+- **Every scenario is testable.** Each asserts an observable outcome a check can confirm — a boolean,
+  no "sometimes". A behavior the capability cannot expose cannot be specced.
+- **A graded subject is still a boolean.** For a non-deterministic capability the contract reaches a
+  per-scenario boolean through a rubric + threshold over N runs; the rubric form stays out of the
+  boolean `.feature`, carried as a judge-only `@rubric` scenario.
+
+## Key points (read-check)
+
+1. **Every branch of the capability is covered** — every edge has its scenario, guards paired with
+   positives, the scenario map 1:1.
+2. **Every scenario is testable** — an observable boolean outcome; behavior the capability cannot
+   expose cannot be specced.
+3. **A graded subject still reaches a per-scenario boolean** via rubric + threshold; the rubric stays
+   out of the `.feature`.

package/skills/check-partition-quality/README.md

@@ -0,0 +1,22 @@
+# check-partition-quality
+
+Internal SDD engine (`user-invocable: false`). Measures from a project's **git history** how much
+parallel work its layout permits, and compares candidate layouts on the same evidence.
+
+**Why it exists.** SDD's scheduler cuts one mission per spec-node, so a layout that scatters a
+capability makes ordinary changes collide and the schedule serializes. That was long asserted rather
+than measured; this produces the number, per project, so a layout decision rests on the project's own
+history instead of doctrine.
+
+**The headline is the parallelizable share** — how often two changes from history could run in
+parallel. Every run also reports a shuffled control, because a partition that cannot beat chance
+explains nothing.
+
+**One design note worth keeping.** Two more obvious metrics — within-node co-change ratio, and mean
+nodes touched per change — were tried first and **both preferred a layered layout**, because both
+reward a coarser partition for being coarse. They are still printed, labelled as confounded, so the
+mistake is visible rather than repeatable.
+
+Runnable standalone; opt-in from `scaffold-project-spec` (detection mode, to inform the strategy
+choice) and the formation loop (the layout-quality signal). Never a gate. Not triggered by users
+directly.

package/skills/check-partition-quality/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: check-partition-quality
+description: "Partial Skill: invoke by name only — project-spec/partition-quality's engine: measures from git history how much parallel work a layout permits, and compares candidate layouts. Opt-in from scaffold-project-spec and the formation loop, and runnable standalone; not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Check Partition Quality
+
+Measures, from a project's **own git history**, how much parallel work its layout actually permits —
+and compares candidate layouts on the same evidence. The mission scheduler cuts **one mission per
+spec-node**, so two changes touching a shared node must serialize; this reports how often that
+happens.
+
+Read-only and advisory: it moves no file, writes nothing, and renders **no verdict**. Layout is the
+owner's call (`sdd:spec-structure-governance` — adoption over purity).
+
+## Run it
+
+```bash
+node "<skill>/scripts/check-partition-quality.mts" \
+  --repo <path> --scope <dir> [--partition <name>]... [--floor N] [--limit N] [--format json]
+```
+
+- `--scope` — restrict to a subtree (e.g. `src`, `plugins/sdd/skills`). Files outside it are ignored.
+- `--partition` — repeatable; compare candidates on the same commits. Built in:
+  `top-folder` (the capability cut) · `second-folder` (capability/unit) · `role` (artifact role — the
+  layered analogue, useful as a contrast) · `single` (the degenerate floor: no parallel work).
+  Default compares `top-folder` against `role`.
+- `--floor` — minimum usable multi-file commits before a rate is emitted (default 20).
+
+## Reading the output
+
+**The headline is the parallelizable share** — of two changes drawn from history, how often they
+*could* run in parallel. Higher is better.
+
+**Check the control before believing it.** Every run reports the same metric over a **shuffled**
+partition of identical node sizes. A partition that does not beat its shuffle explains nothing, and
+the run says so.
+
+**The diagnostics are confounded — never headline them.** `within-node co-change` and `mean nodes
+touched` both reward a **coarser** partition for being coarse: a single-node partition scores a
+*perfect* 1 on each while permitting zero parallel work. They are printed only so a reader can see
+why they are not used. Two engines built on them would recommend a layered layout.
+
+## Boundaries
+
+Measurement only — no file is moved, no spec written, no layout approved or rejected. Thin history is
+**reported, never scored**: below the floor it emits no rate rather than a confident number drawn
+from noise. It reads `git log` and nothing else; no node body, no spec frontmatter.

package/skills/check-partition-quality/scripts/check-partition-quality.mts

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+// check-partition-quality — project-spec/partition-quality's concrete engine. Measures, from a
+// project's own git history, how much parallel work its layout permits, and compares candidate
+// layouts on the same evidence (see this skill's README.md).
+//
+// THE METRIC IS COLLISION RATE, AND THAT CHOICE IS LOAD-BEARING. The scheduler cuts one mission per
+// spec-node, so two changes touching a shared node must serialize. Collision rate is the share of
+// change pairs that do. The headline is its complement — the parallelizable share.
+//
+// Two obvious alternatives were tried first and BOTH preferred a layered partition (the wrong
+// answer), because both are confounded by node count:
+//   - within-node co-change ratio  — a coarser partition scores well for being coarse
+//   - mean nodes touched per change — a single-node partition scores PERFECTLY while permitting
+//     zero parallel work
+// They are computed and reported here as DIAGNOSTICS, explicitly labelled, so that a later reader
+// does not "simplify" the engine back onto one of them. Do not headline them.
+//
+// Read-only: it runs `git log`, writes nothing, and renders no verdict — layout is the owner's call.
+// 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 { execFileSync } from 'node:child_process'
+
+/** Below this many usable multi-file commits, a rate would be noise — report, never score. */
+export const DEFAULT_FLOOR = 20
+
+export interface Change {
+	/** In-scope files touched by one commit. */
+	files: string[]
+}
+
+/** A partition names the node each file belongs to; `undefined` drops the file from the measure. */
+export type Partition = (file: string) => string | undefined
+
+export interface Measurement {
+	nodes: number
+	pairs: number
+	collisionRate: number
+	parallelizableShare: number
+	control: number
+	/** Positive when the partition explains more than a shuffle of the same node sizes. */
+	marginOverControl: number
+	explainsNothing: boolean
+	diagnostics: {
+		/** CONFOUNDED by node count — a coarser partition scores higher. Never headline. */
+		withinNodeCoChangeRatio: number
+		/** CONFOUNDED by node count — a single-node partition scores a perfect 1. Never headline. */
+		meanNodesTouched: number
+	}
+}
+
+export interface ThinHistory {
+	thin: true
+	usableCommits: number
+	floor: number
+}
+
+// ── Reading history ──────────────────────────────────────────────────────────
+// Only multi-file changes inform the measure: a single-file commit contributes no pair, because one
+// file can collide with nothing.
+
+export function parseGitLog(stdout: string, inScope: (f: string) => boolean): Change[] {
+	const out: Change[] = []
+	let cur: string[] | null = null
+	for (const line of stdout.split('\n')) {
+		const t = line.trimEnd()
+		if (t === '') {
+			if (cur && cur.length > 1) out.push({ files: [...new Set(cur)] })
+			cur = null
+			continue
+		}
+		if (/^[0-9a-f]{40}$/.test(t)) {
+			if (cur && cur.length > 1) out.push({ files: [...new Set(cur)] })
+			cur = []
+			continue
+		}
+		if (cur !== null && inScope(t)) cur.push(t)
+	}
+	if (cur && cur.length > 1) out.push({ files: [...new Set(cur)] })
+	return out.filter((c) => c.files.length > 1)
+}
+
+export function readHistory(repo: string, inScope: (f: string) => boolean, limit = 4000): Change[] {
+	const stdout = execFileSync('git', ['-C', repo, 'log', `-${limit}`, '--name-only', '--pretty=format:%H'], {
+		encoding: 'utf8',
+		maxBuffer: 256 * 1024 * 1024,
+	})
+	return parseGitLog(stdout, inScope)
+}
+
+// ── The metric ───────────────────────────────────────────────────────────────
+
+/** The set of nodes one change touches. A change touching none drops out of the measure. */
+function nodesOf(c: Change, p: Partition): Set<string> {
+	const s = new Set<string>()
+	for (const f of c.files) {
+		const n = p(f)
+		if (n !== undefined) s.add(n)
+	}
+	return s
+}
+
+export function collisionRate(changes: Change[], p: Partition): { rate: number; pairs: number } {
+	const sets = changes.map((c) => nodesOf(c, p)).filter((s) => s.size > 0)
+	let pairs = 0
+	let collided = 0
+	for (let i = 0; i < sets.length; i++) {
+		for (let j = i + 1; j < sets.length; j++) {
+			pairs++
+			const a = sets[i] as Set<string>
+			const b = sets[j] as Set<string>
+			for (const n of a) {
+				if (b.has(n)) {
+					collided++
+					break
+				}
+			}
+		}
+	}
+	return { rate: pairs === 0 ? 0 : collided / pairs, pairs }
+}
+
+// ── The control ──────────────────────────────────────────────────────────────
+// The same measurement over a SHUFFLED partition of identical node sizes. A partition whose rate
+// matches its shuffle explains nothing, and the headline should not be trusted. Deterministic seed:
+// the run must be reproducible.
+
+function mulberry32(seed: number): () => number {
+	let a = seed >>> 0
+	return () => {
+		a = (a + 0x6d2b79f5) >>> 0
+		let t = Math.imul(a ^ (a >>> 15), 1 | a)
+		t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+	}
+}
+
+export function shuffledControl(changes: Change[], p: Partition, seed = 7): number {
+	const files = [...new Set(changes.flatMap((c) => c.files))].filter((f) => p(f) !== undefined).sort()
+	const labels = files.map((f) => p(f) as string)
+	const rnd = mulberry32(seed)
+	for (let i = labels.length - 1; i > 0; i--) {
+		const j = Math.floor(rnd() * (i + 1))
+		const li = labels[i] as string
+		const lj = labels[j] as string
+		labels[i] = lj
+		labels[j] = li
+	}
+	const m = new Map(files.map((f, i) => [f, labels[i] as string]))
+	return collisionRate(changes, (f) => m.get(f)).rate
+}
+
+/**
+ * Rename `diagnostics` to `confoundedDiagnostics` on the way out to JSON.
+ *
+ * The text render carries the warning inline; a JSON consumer sees only keys, so a plain
+ * `diagnostics` object hands over two numbers indistinguishable from the headline. Renaming the key
+ * beats adding a note field: a consumer cannot read these numbers without typing the word
+ * "confounded", whereas a sibling note is trivially skipped.
+ */
+export function toJson([name, m]: [string, Measurement | ThinHistory]): [string, unknown] {
+	if (!('diagnostics' in m)) return [name, m]
+	const { diagnostics, ...rest } = m
+	return [name, { ...rest, confoundedDiagnostics: diagnostics }]
+}
+
+// ── Confounded diagnostics — labelled, never the headline ────────────────────
+
+export function withinNodeCoChangeRatio(changes: Change[], p: Partition): number {
+	let within = 0
+	let total = 0
+	for (const c of changes) {
+		const ns = c.files.map((f) => p(f)).filter((n): n is string => n !== undefined)
+		for (let i = 0; i < ns.length; i++) {
+			for (let j = i + 1; j < ns.length; j++) {
+				total++
+				if (ns[i] === ns[j]) within++
+			}
+		}
+	}
+	return total === 0 ? 0 : within / total
+}
+
+export function meanNodesTouched(changes: Change[], p: Partition): number {
+	const counts = changes.map((c) => nodesOf(c, p).size).filter((n) => n > 0)
+	return counts.length === 0 ? 0 : counts.reduce((a, b) => a + b, 0) / counts.length
+}
+
+// ── Measure ──────────────────────────────────────────────────────────────────
+
+export function measure(changes: Change[], p: Partition, floor = DEFAULT_FLOOR): Measurement | ThinHistory {
+	const usable = changes.filter((c) => nodesOf(c, p).size > 0)
+	if (usable.length < floor) return { thin: true, usableCommits: usable.length, floor }
+	const { rate, pairs } = collisionRate(usable, p)
+	const control = shuffledControl(usable, p)
+	const margin = control - rate // lower collision than the shuffle is the improvement
+	return {
+		nodes: new Set(usable.flatMap((c) => [...nodesOf(c, p)])).size,
+		pairs,
+		collisionRate: rate,
+		parallelizableShare: 1 - rate,
+		control,
+		marginOverControl: margin,
+		explainsNothing: margin <= 0,
+		diagnostics: {
+			withinNodeCoChangeRatio: withinNodeCoChangeRatio(usable, p),
+			meanNodesTouched: meanNodesTouched(usable, p),
+		},
+	}
+}
+
+export function isThin(m: Measurement | ThinHistory): m is ThinHistory {
+	return (m as ThinHistory).thin === true
+}
+
+// ── Built-in candidate partitions ────────────────────────────────────────────
+// Named so a caller can compare "what the tree does now" against "what a capability cut would do"
+// without writing code.
+
+export const PARTITIONS: Record<string, (scope: string) => Partition> = {
+	/** Top-level folder under the scope — the capability cut for a screaming layout. */
+	'top-folder': (scope) => (f) => {
+		const rel = f.startsWith(scope) ? f.slice(scope.length).replace(/^\//, '') : undefined
+		if (rel === undefined) return undefined
+		const seg = rel.split('/')[0]
+		return seg === undefined || seg === '' || !rel.includes('/') ? undefined : seg
+	},
+	/** Second-level folder — a finer cut, for a capability/unit tree. */
+	'second-folder': (scope) => (f) => {
+		const rel = f.startsWith(scope) ? f.slice(scope.length).replace(/^\//, '') : undefined
+		if (rel === undefined) return undefined
+		const p = rel.split('/')
+		return p.length > 2 ? `${p[0]}/${p[1]}` : undefined
+	},
+	/** File extension / artifact role — the layered analogue, useful as a contrast candidate. */
+	role: (scope) => (f) => {
+		if (!f.startsWith(scope)) return undefined
+		const n = f.split('/').pop() ?? ''
+		const dot = n.indexOf('.')
+		return dot === -1 ? n : n.slice(dot + 1)
+	},
+	/** Everything in one node — the degenerate floor: no parallel work is possible. */
+	single: (scope) => (f) => (f.startsWith(scope) ? 'all' : undefined),
+}
+
+// ── Render ───────────────────────────────────────────────────────────────────
+
+function pct(n: number): string {
+	return `${(n * 100).toFixed(1)}%`
+}
+
+export function renderOne(label: string, m: Measurement | ThinHistory): string {
+	if (isThin(m)) {
+		return `  ${label}: history too thin to measure — ${m.usableCommits} usable multi-file commits, floor ${m.floor}. No rate emitted.`
+	}
+	const lines = [
+		`  ${label}`,
+		`    parallelizable share : ${pct(m.parallelizableShare)}   ← the headline`,
+		`    collision rate       : ${pct(m.collisionRate)}  over ${m.pairs} change pairs, ${m.nodes} nodes`,
+		`    shuffled control     : ${pct(m.control)}  (margin ${m.marginOverControl >= 0 ? '+' : ''}${pct(m.marginOverControl)})`,
+	]
+	if (m.collisionRate >= 1) {
+		lines.push('    ⚠ every change pair collides — this partition permits no parallel work')
+	}
+	if (m.explainsNothing) {
+		lines.push('    ⚠ this partition explains no more than chance — do not trust the headline')
+	}
+	lines.push(
+		`    diagnostics (CONFOUNDED by node count — not the headline): within-node co-change ${pct(m.diagnostics.withinNodeCoChangeRatio)}, mean nodes touched ${m.diagnostics.meanNodesTouched.toFixed(2)}`,
+	)
+	return lines.join('\n')
+}
+
+export function render(results: [string, Measurement | ThinHistory][], repo: string, scope: string): string {
+	const out = [`check-partition-quality: repo=${repo} scope=${scope || '(whole repo)'}`]
+	for (const [label, m] of results) out.push(renderOne(label, m))
+	if (results.length > 1) {
+		const scored = results.filter(([, m]) => !isThin(m)) as [string, Measurement][]
+		if (scored.length > 1) {
+			const best = scored.reduce((a, b) => (b[1].parallelizableShare > a[1].parallelizableShare ? b : a))
+			out.push(`\nOn this history, "${best[0]}" permits the most parallel work (${pct(best[1].parallelizableShare)}).`)
+		}
+	}
+	out.push('note: a measurement, not a verdict — it moves no file and gates nothing; layout is the owner’s call')
+	return out.join('\n')
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+/**
+ * The effects `main` reaches the outside world through. Dependencies enter at the CLI boundary and
+ * nowhere below it: everything under `main` is pure over the history it is handed.
+ */
+export type Context = { readHistory: typeof readHistory }
+
+export function main(argv: string[], context: Context = { readHistory }): number {
+	let repo = '.'
+	let scope = ''
+	let floor = DEFAULT_FLOOR
+	let limit = 4000
+	let format: 'text' | 'json' = 'text'
+	const candidates: string[] = []
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i]
+		if (a === '--repo') repo = argv[++i] ?? '.'
+		else if (a === '--scope') scope = argv[++i] ?? ''
+		else if (a === '--floor') floor = Number(argv[++i] ?? DEFAULT_FLOOR)
+		else if (a === '--limit') limit = Number(argv[++i] ?? 4000)
+		else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? 'text'
+		else if (a === '--partition') candidates.push(argv[++i] ?? '')
+	}
+	if (candidates.length === 0) candidates.push('top-folder', 'role')
+	for (const c of candidates) {
+		if (!(c in PARTITIONS)) {
+			process.stderr.write(`unknown --partition "${c}" — known: ${Object.keys(PARTITIONS).join(', ')}\n`)
+			return 1
+		}
+	}
+	// Read ONCE, then measure every candidate over that one history — the comparison is only
+	// meaningful if each candidate is scored against the same commits and the same scope.
+	const changes = context.readHistory(repo, (f) => (scope ? f.startsWith(scope) : true), limit)
+	const results = candidates.map(
+		(c) =>
+			[c, measure(changes, (PARTITIONS[c] as (s: string) => Partition)(scope), floor)] as [
+				string,
+				Measurement | ThinHistory,
+			],
+	)
+	if (format === 'json') process.stdout.write(`${JSON.stringify(Object.fromEntries(results.map(toJson)), null, 2)}\n`)
+	else process.stdout.write(`${render(results, repo, scope)}\n`)
+	return 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/check-plan-safety/README.md

@@ -0,0 +1,17 @@
+# check-plan-safety
+
+Internal SDD skill — the concrete guard engine for the **plan brief's safe-to-publish floor**. Scans
+the tracked, portable handoff artifacts under `.agents/plans` (the `*.plan.md` brief + sibling design
+docs) for machine-local references that must never enter git history.
+
+```bash
+node scripts/check-plan-safety.mts --root .                 # audit (TOON finding set)
+node scripts/check-plan-safety.mts --root . --check         # CI guard (fails on any leak)
+node scripts/check-plan-safety.mts --path <file> --check    # check one explicit file
+```
+
+Flags a **home-directory absolute path** (`/home/<user>/…`, `/Users/<user>/…`, `C:\Users\<user>\…`)
+or a **`$HOME`/`$USER` expansion** — each leaks an OS username and breaks portability. A bare `~/` is
+deliberately not flagged (no username; legitimate in design prose). The plan-brief analog of the
+combat log's floor. Read-only; writes nothing. See [`SKILL.md`](./SKILL.md) for the full contract.
+Not user-invocable.

package/skills/check-plan-safety/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: check-plan-safety
+description: "Partial Skill: invoke by name only — plan-brief/check-plan-safety's guard engine against machine-local path leaks in tracked plan artifacts — the CI guard, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Check Plan Safety
+
+The concrete engine for the **plan brief's safe-to-publish floor**. The plan brief
+(`.agents/plans/<cr-ref>.plan.md`) and its sibling design docs are **tracked, portable** handoff
+artifacts — committed at handoff and read by any later session, agent, or checkout. This engine
+guards that floor mechanically: it scans those `*.md` files for **machine-local references** that
+must never enter git history. It carries a self-contained `.mts` script (the repo's node-≥23.6 /
+no-deps convention), and is the plan-brief analog of the combat log's safe-to-publish floor
+(`combat-log-governance`) — the same "never committed: absolute paths, OS usernames" rule, extended
+from the ledger to the brief.
+
+## What it flags
+
+- **home-abs-path** — a home-directory absolute path: `/home/<user>/…`, `/Users/<user>/…`, or a
+  Windows profile `C:\Users\<user>\…`. Leaks the OS username (privacy) **and** resolves on no other
+  checkout (portability).
+- **env-home** — a shell expansion of the home dir: `$HOME`, `${HOME}`, `%USERPROFILE%`, `%HOMEPATH%`.
+- **env-user** — a shell expansion of the identity: `$USER`, `${USER}`, `%USERNAME%`.
+
+Every finding is **blocking** — a leak is a leak. The fix is to bring the referenced content into
+the repo and reference it **repo-relative** (e.g. copy a `~/.claude/plans/` design doc to
+`.agents/plans/<cr-ref>.design.md`), never to link a machine-local path.
+
+### What it deliberately does NOT flag
+
+A bare `~/` is **not** a leak — it carries no username and legitimately appears in design prose
+describing home-rooted feature paths (a tool's own `~/.<tool>/` data root). `$HOMEBREW` / `$USERDATA`
+(a different variable that merely starts with `HOME`/`USER`) are not flagged either.
+
+## Run the scan
+
+```bash
+node "<skill>/scripts/check-plan-safety.mts" [--root .] [--path <file>]... [--check] [--format toon|json]
+```
+
+- Default `--root` is the current directory; default `--format` is **TOON** (the token-efficient
+  tabular form). Absent `--path`, it scans every `*.md` under `<root>/.agents/plans`.
+- **`--path <file>`** (repeatable) scans an explicit file set instead of the plan dir — used by
+  `pause-mission` to check the one brief it is about to commit.
+- **Audit mode** (default) emits the finding set (`file, line, kind, token`) and exits **0**.
+- **`--check`** (CI guard) exits **non-zero** iff any leak is found and **writes nothing** else.
+  Wired into `verify:specs` (`node …/check-plan-safety.mts --root . --check`).
+
+When `node` is absent, an agent performs the same derivation by hand: grep the plan `*.md` files for
+`/home/`, `/Users/`, `C:\Users\`, `$HOME`, and `$USER`.
+
+## Boundaries
+
+Read-only — it writes nothing and acts on no finding. It does not fix a leak (the author scrubs it),
+does not check gate legality (`spec-gate`), and does not audit node-shape (`check-spec-structure`).
+It is loaded by the `manage` gateway (Audit & align) for an on-demand scan and by `pause-mission`
+before a checkpoint commit.