cyber-sdd 0.0.0

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

@@ -0,0 +1,45 @@
+# oracle-spec-governance
+
+This is an internal SDD governance about scope and the kill-or-ship call at the spec gate.
+
+Before a capability's spec is approved, someone has to ask the uncomfortable questions: is this one
+thing or two things glued together? Is it worth building at all? Does every scenario in its suite
+actually belong to it? This governance is that question list — the **Oracle** bar. It judges the
+**capability itself**, read from its spec and suite together — not how the document is written,
+which is a different bar (`spec-format-governance`).
+
+## What it requires — the bar
+
+| Check | What it demands |
+| --- | --- |
+| **One coherent intent** | The capability delivers a single nameable outcome. Two concerns are two capabilities — split them, each into its own node. Test: can you name the outcome without "and"? |
+| **Bounded, stated scope** | What is out of scope is named. A capability that keeps absorbing adjacent problems is scope creep — cut it back. |
+| **The node owns its decisions** | Every scenario tests a decision the node owns. A property co-owned across a seam — activation/routing, a sibling's behavior, harness wiring — is out of scope: relocate it to the node that owns it, or kill it. |
+| **Strict — non-decisions are killed** | An invariant that always holds is not acceptance and does not enter the suite. The one exception is a user `@pinned` scenario, kept whatever strict prunes. |
+| **Worth shipping, or kill** | The Why names a real problem and who feels it. If the value does not clear the cost of building, the verdict is kill. |
+| **Kill-or-revert** | A capability that passes every check but proves fatal goes back to Draft — surface the deal-breaker. |
+| **No premature commitment** | A decision that need not be made yet is deferred to the last responsible moment. |
+
+## Usage
+
+- **spec-producer:** self-aligns on scope against this bar before writing the spec
+- **spec-judge:** grades kill-or-ship cold at the **spec-gate**
+
+The same bar is loaded by both faces, but producer and judge stay separate agents. Oracle has no
+impl-gate face, so this is the only Oracle bar. It is SDD's default for the `oracle` bar — a plugin
+may bind its own per artifact-type, and this one loads only when the registry leaves `oracle`
+unbound.
+
+## Related governances
+
+This bar owns whether the capability is the right thing to commit to. Its neighbors own everything
+around that:
+
+- **`spec-format-governance`** — how the `spec.md` document itself is structured and written; this
+  bar deliberately does not read the prose.
+- **`builder-spec-governance`** — the Builder bar at the same gate: testability and coverage of the
+  `.feature`, not scope.
+- **`architect-spec-governance`** — the Architect bar at the same gate: structural fit of the spec
+  and solution, not whether it should exist.
+
+Internal SDD governance (`user-invocable: false`). Not triggered by users directly.

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

@@ -0,0 +1,45 @@
+---
+name: oracle-spec-governance
+description: "Partial Skill: invoke by name only"
+user-invocable: false
+metadata:
+  actor: oracle
+  gate: spec
+  compose: union
+---
+
+# Oracle-Spec Governance — the scope & kill-or-ship bar
+
+The **Oracle** bar at the **spec gate**: is this **capability** worth committing, and is its scope the
+node's to hold? Judges the capability (read from its spec + suite), not the document's prose — that is
+`sdd:spec-format-governance`. Loaded by both faces — the spec-producer self-aligns on scope before
+writing, the cold spec-judge judges kill-or-ship. Oracle has no impl face. The SDD default for the
+`oracle` bar; a plugin may bind its own per artifact-type, and this loads when the registry leaves
+`oracle` unbound.
+
+## The bar
+
+- **One coherent intent.** The capability delivers a single nameable outcome. **Two concerns are two
+  capabilities** — split them, each into its own node. Test: can you name the outcome without "and"?
+- **Scope is bounded and stated.** What is out of scope is named. A capability that keeps absorbing
+  adjacent problems is scope creep — cut it back.
+- **The suite's decisions are the node's to hold.** Every scenario tests a **decision the node owns**.
+  A property **co-owned** across a seam — activation/routing, a sibling's behavior, harness wiring —
+  is out of scope: relocate it to the node that owns it, or kill it.
+- **Strict — a non-decision is killed.** An **invariant** that always holds is not acceptance and does
+  not enter the suite. The one exception is a user **`@pinned`** scenario, kept whatever strict prunes.
+- **Worth shipping, or kill.** The Why names a real problem and who feels it. If value does not clear
+  the cost of building, the verdict is **kill**.
+- **Kill-or-revert is allowed.** A capability that passes every check but proves fatal goes back to
+  Draft — surface the deal-breaker.
+- **No premature commitment.** Defer a decision that need not be made yet to the last responsible
+  moment.
+
+## Key points (read-check)
+
+1. **One coherent intent** — two concerns are two capabilities; bounded and stated scope.
+2. **Every scenario tests a decision the node owns** — a co-owned seam property is out of scope
+   (relocate or kill).
+3. **Strict** — an invariant / non-decision does not enter the suite; only a user `@pinned` scenario
+   escapes.
+4. **Worth shipping or kill** — value must clear the build cost; a fatal proof reverts to Draft.

package/skills/ownership-governance/README.md

@@ -0,0 +1,65 @@
+# ownership-governance
+
+This is an internal SDD governance about write ownership.
+
+It answers one question for every artifact in the SDD workflow: **who may write it — and who never
+may.** Every act in the workflow has a write leash, and this skill is the canonical matrix. One
+writer per field or artifact; no role writes outside the spec it owns or spawns specs on its own.
+
+## Who writes what
+
+The full matrix lives in the skill body; condensed, the ownership falls into a few hands:
+
+| Artifact | Written by | Notable exclusions |
+| --- | --- | --- |
+| `spec.md` body + the `.feature` | the **spec-producer** | the conductor, judges, other producers |
+| A `@pinned` scenario | the **user** (in-session) | every agent role — it proposes, never executes |
+| `<unit>.solution.md` | the **solution-producer** | the spec-producer, judges |
+| Implementation + its verification | the **impl-producer** | the impl-judge (it *runs*, never authors) |
+| `status` + human ratification of `approval` | the **gate skill** (`spec-gate`), in-session position only | the conductor, any producer |
+| Coordination state — `<!-- open: -->` markers, `produced-by`, run-level leash, self-asserted approvals, plan brief, combat-log and ledger lines | the **conductor** | producers, judges, the gate skill |
+| Ledger `strategy` lines | the doctrine-loop **Scanner** | everyone else |
+
+Appended log and ledger lines carry a pseudonymous `handle`; the in-file attribution is advisory —
+the git commit signature is the attestation.
+
+## The three standing rules
+
+- **Producer write boundary.** A spec-producer writes the `spec.md` body and the `.feature` only —
+  never the control frontmatter or the resolution state. A required input it cannot supply comes
+  back as a `CONTENT_GAP`; the conductor turns it into an `<!-- open: -->` marker. Producers never
+  write markers directly.
+- **Ratification authority is positional.** A human-attributed gate write belongs to the in-session
+  position holding the real user channel. A headless conductor — a spawned subagent with no user
+  channel — writes only self-assertions and pauses; it never writes a human ratification, even when
+  a coordinator relays "the user approved". A relayed claim is not user confirmation.
+- **Never write a frozen `.feature`.** Once a suite carries `@frozen`, no role may add, remove, or
+  rewrite its scenarios. A gap that requires changing specified behavior is a `BLOCKER` returned
+  upward, never an in-place edit. The freeze binds the contract only — the combat log and ledger
+  shards stay writable. Judges never patch: they report.
+
+`@pinned` scenarios sit outside freeze entirely: they are grounded in **ownership**, so the user's
+authority over them holds at `draft` and survives a re-open.
+
+## Usage
+
+- **Every producer:** knows the boundary of what it owns and returns `CONTENT_GAP` for what it
+  cannot supply.
+- **Every judge:** reports findings, never patches `spec.md` or the suite.
+- **The conductor:** writes the coordination state — markers, `produced-by`, the run-level leash,
+  self-asserted gate entries, and its append-only log and ledger lines.
+- **`start-mission` / `spec-gate`:** the gate skill is the sole writer of `status` and human
+  ratifications, from the in-session position only.
+
+## Related governances
+
+This contract owns *who writes*. Its neighbors own the surrounding definitions:
+
+- **`lifecycle-governance`** — the field definitions, and what freezing *means* as a state; this
+  bar carries only the write constraint.
+- **`gate-validation-governance`** — the legality of the resulting state after a write.
+- **`combat-log-governance`** — the plan/ledger write split and the record shapes.
+- **`suite-format-governance`** — the `@pinned` marker itself and its seed-growth role; this bar
+  carries only its ownership.
+
+Internal SDD governance (`user-invocable: false`). Not triggered by users directly.

package/skills/ownership-governance/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: ownership-governance
+description: "Partial Skill: invoke by name only"
+user-invocable: false
+---
+
+# SDD Ownership Governance
+
+Who may write what. Every act in the SDD workflow has a write leash; this skill is the canonical
+matrix. The field definitions are in `sdd:lifecycle-governance`; the legality of the resulting state
+is in `sdd:gate-validation-governance`; the plan/ledger write split is in `sdd:combat-log-governance`.
+
+## Write-ownership matrix
+
+| Field / artifact | Written by | Never written by |
+|---|---|---|
+| `status` | the gate skill (`spec-gate`) — on a human verdict, or to match a conductor self-assertion within leash | the conductor, any producer |
+| `project-path` | the **conductor** (at scaffold; `scaffold-project-spec`) | producers, the gate skill |
+| run-level leash + approach — the `kind: leash` ledger line (session-local; to the conductor's own ledger shard, **not** spec.md frontmatter — the conductor's autonomy bar, `start-mission`) | the **conductor** (initial evaluation) | producers, the gate skill |
+| `approval` **self-assertion** (`verdict: approve`/`pause` + `by: agent`/none + `why`) | the **conductor** (synthesis only) | producers, the gate skill |
+| `approval` **human ratification** (`verdict: approve`/`reject` + `by: <name>`) | the gate skill (`spec-gate`), **in-session position only** | the conductor, any producer, any spawned delegate |
+| `<!-- open: -->` markers | the **conductor** | producers (they *emit gaps*, not markers) |
+| `produced-by` map | the **conductor** (records the resolved producer per role at production) | producers, judges, the gate skill |
+| contested-type → chosen-plugin state (`.agents/sdd/`) | the **conductor** (or `start-mission` for a contested artifact-type); **distinct from `produced-by`** | producers, judges, the gate skill |
+| combat-log `report` / `correction` / `halt` lines | the **conductor** (append-only, to the plan's `*.log.jsonl`) | producers, judges, the gate skill |
+| ledger `gate` line — self-asserted (`by: agent`) | the **conductor** (append-only, to its own ledger shard) | producers, judges |
+| ledger `gate` line — human-ratified (`by: <name>`) | the gate skill (`spec-gate`), **in-session position only** | the conductor, producers, judges |
+| ledger `followup` line — the durable follow-up record (`class: blocking`/`backlog`) | the **conductor** (append-only, to its own ledger shard, at handoff, **unconditionally** — no permission, no forge, no human) | producers, judges, the gate skill |
+| ledger `strategy` lines | the doctrine-loop Scanner (append-only) | the conductor, producers, judges |
+| `spec.md` body + the `.feature` | the **spec-producer** | the conductor, judges, solution/impl producers |
+| a **`@pinned` scenario** (user-owned) | the **user** (in-session) | every agent role — may **propose**, never **executes** a change/removal without in-session user authorization |
+| `<unit>.solution.md` | the **solution-producer** | the spec-producer, judges |
+| plan brief + `todos` | the **conductor** | producers, judges |
+| implementation + its verification | the **impl-producer** | the impl-judge (it *runs*, never authors) |
+
+Each appended `*.log.jsonl` / ledger-shard line carries its writer's pseudonymous `handle`
+(`SDD_HANDLE` if set, else omitted — attribution falls back to the git commit author; **never**
+`user.email`, never a `git config` read); combat-log lines additionally carry a write-time UTC `ts`,
+while ledger lines carry none (`sdd:combat-log-governance`). The in-file `handle` / `by` is
+**advisory** — the git commit signature is the attestation.
+
+## Producer write boundary
+
+A **spec-producer** writes the `spec.md` body and the `.feature` only. It must **not** write the
+control frontmatter (`status`, `project-path`, `approval`, `produced-by`) or the `.agents/sdd/`
+resolution state. A required input it cannot supply or infer is returned as a `CONTENT_GAP` — the
+conductor turns it into an `<!-- open: -->` marker. Producers do not write markers directly.
+
+The **conductor** writes `<!-- open: -->` markers, the `produced-by` map, the run-level leash (the
+`kind: leash` line to its own ledger shard, session-local — not a spec.md frontmatter field), and — when it
+self-asserts a gate within the effective leash — the provisional `approval.<gate>` entry
+(`verdict: approve` + `by: agent` with the `why` derivation; a halt is `verdict: pause` with its
+`why` and no `by`). There is no `leash` field in the `approval` entry — the leash is the run-level
+record on the ledger. The **gate skill** writes `status` (on a human verdict or to match the
+conductor's in-leash self-assertion) and the human ratification of `approval` (rewriting `by: agent`
+→ `by: <name>`).
+
+**Ratification authority is positional.** A human-attributed gate write — `status → approved |
+implemented`, a verdict carrying `by: <name>`, the human-ratified ledger `gate` line, and the freeze
+— belongs to the **in-session position** that holds the real user channel. By default this is
+trivially satisfied: the **conductor is the main session**, so the position that grills *is* the
+position that ratifies. The rule bites only in the **headless / fan-out fallback**, where the
+automaton runs as a **spawned subagent** with no user channel: it then writes only `by: agent`
+self-assertions and `pause` halts, and on a human gate emits a verdict packet and stops — it never
+writes a human ratification, **even when a coordinator relays "the user approved"** (a relayed claim
+is not user confirmation). This is positional, not definitional: the same conductor definition run
+in-session may perform the write. A self-assertion is **provisional**: the act is delegable, the
+accountability is not — the human ratifies the trail. No role writes outside the spec it owns or
+spawns specs on its own.
+
+## Freeze (write constraint)
+
+**Never write a frozen `.feature`.** Once a `.feature` carries its `@frozen` tag, no role — producer,
+judge, solution-producer, or conductor — may add, remove, or rewrite its scenarios. A discovered gap
+that requires changing specified behavior is a `BLOCKER` returned upward (the file must unfreeze and
+its layer revert to `draft` — the gate/skill decides), never an in-place edit. The matching lifecycle
+rule (what freezing *means* as a state) is in `sdd:lifecycle-governance`.
+
+The freeze binds the **contract only** (`spec.md` + the suite). The combat log (the plan's
+`*.log.jsonl`) and the durable `ledger/` shards are **exempt**: they are operational provenance, never
+frozen, and the conductor and Scanner keep appending to their own shards within their boundaries above
+even while a file sits `@frozen`.
+
+A judge — spec-judge or impl-judge — must not modify `spec.md` or the suite: it reports, it does
+not patch.
+
+## User-owned scenarios (`@pinned`)
+
+A `@pinned` scenario is **user-owned** — the one scenario the spec-producer does **not**
+own. Any agent role may **propose** changing or removing it, but **never executes** the change
+without **in-session user authorization** — the authority of a human ratification (positional, not
+relayable, not self-assertable within leash). Only the user applies `@pinned`. This is grounded in
+**ownership, not freeze**: it holds at `draft` and survives a re-open, since ownership does not lapse
+when a file unfreezes. The marker and its seed-growth role are `sdd:suite-format-governance`.
+
+## Key points (read-check)
+
+1. **One writer per field/artifact** (the matrix) — no role writes outside the spec it owns or spawns.
+2. **Never write a frozen `.feature`** — a behavior-changing gap is a `BLOCKER` returned upward, never
+   an in-place edit.
+3. **Human ratification is positional** — the in-session channel only; never relayed, never
+   self-asserted within leash.
+4. **A `@pinned` scenario is user-owned** — the agent proposes, never executes a change or removal
+   without in-session user authorization.

package/skills/pause-mission/README.md

@@ -0,0 +1,18 @@
+# pause-mission
+
+Project-private workflow skill for **checkpointing an in-progress SDD mission into its plan
+brief** (`.agents/plans/<cr-ref>.plan.md`). Invoke it when stopping mid-mission ("pause",
+"checkpoint", "save state to the plan", "stop here") to update the todo statuses and rewrite
+the `## NEXT — resume here` anchor, then commit — so the working tree is clean and the next
+session resumes without rediscovery.
+
+Pass **`--approve`** to also clear the mission for **headless dispatch** — it sets the brief's
+top-level `status: approved` (a human review act; a headless automaton never self-approves), the
+go-signal the gateway's dispatch loop selects on.
+
+The checkpoint is **self-sufficient**: any later session that opens the plan can continue from
+it — [`resume-mission`](../resume-mission/README.md) is one convenient reader, not a required
+pair. Modeled after the handoff-skill pattern (reference artifacts instead of restating, keep it
+commit-message-grade, lead the `## NEXT` anchor with the next action *and the skill to invoke for
+it*) but targeted at the durable tracked plan rather than a temp file. `internal: true` —
+contributor tooling.

package/skills/pause-mission/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: pause-mission
+description: "Checkpoint an in-progress SDD mission INTO its plan brief so any later session can pick it up. Use this skill when asked to 'pause', 'wrap up for now', or 'stop here' mid-mission — update the plan's todo statuses and rewrite its ## NEXT anchor so a fresh session continues exactly where you left off. Pass --approve to also clear the mission for headless dispatch (sets the brief's status: approved)."
+argument-hint: "[what the next session should focus on] [--approve]"
+---
+
+# Pause an SDD mission into its plan
+
+An SDD mission's durable handoff is its **plan brief** at `.agents/plans/<cr-ref>.plan.md`. A
+pause writes this session's state back into that plan so **any** next session can pick the
+mission up by reading it — no special tool required (`resume-mission` is one convenient reader;
+the plan stands on its own). Capture *enough to continue, nothing to relitigate.*
+
+## Procedure
+
+1. **Honor the focus.** If the user named what the pause should emphasize, scope the checkpoint
+   to it; otherwise checkpoint the whole live frontier.
+
+2. **Locate the plan — scaffold it if missing.** Find `.agents/plans/<cr-ref>.plan.md`. If none
+   exists, create a minimal one (frontmatter `todos` + a `## NEXT` anchor) so the checkpoint has
+   a durable home; a pause always leaves a plan behind.
+
+3. **Update the todo statuses.** In the frontmatter `todos`, set each touched todo to its true
+   `status` (`pending | in_progress | completed`). Mark the one you were on `in_progress`; never
+   mark a todo `completed` unless it truly is — partial work stays `in_progress` with a one-line
+   note of what remains. Add a todo for any new work or decision that surfaced this session.
+
+4. **Rewrite the `## NEXT — resume here` anchor** (create it if absent) so a cold reader can
+   start in under a minute. Order it for pickup, **action first**:
+   - **The next action — first, concrete, runnable.** One line the resumer can act on
+     immediately: the file or unit to touch *and the skill or command to invoke for it* — e.g.
+     "build `<unit>`'s spec + suite via `start-mission`, then run the project's spec check," never
+     a vague "continue authoring."
+   - **Blocking decisions** — open scope calls and unresolved `<!-- open: -->` markers, each with
+     its options, so the next session *resolves* rather than rediscovers them.
+   - **Findings the commits won't show** — only what isn't obvious from the diff and changes the
+     next move. Skip the play-by-play.
+   - **A pointer to the working method / resolved decisions** already in the plan body ("do not
+     relearn — see `## Resolved decisions`").
+
+   Lead with the action; put history and findings *below* it. A resumer needs *what to do* first
+   and *what happened* second.
+
+5. **Reference, don't restate.** Point to commits (SHAs), files (**repo-relative paths**), design
+   rules, and issues by reference — never paste their contents. The plan is an index to the work,
+   not a copy of it. A file the brief depends on must live **in the repo**: if the source is a
+   machine-local doc (a plan-mode plan under `~/.claude/plans/…`), bring it in as a sibling
+   `<cr-ref>.design.md` and reference that, never the external absolute path.
+
+6. **Keep it commit-message-grade — the safe-to-publish floor.** The plan is tracked and committed,
+   so it carries the same floor as the combat log (`combat-log-governance`): **never committed** —
+   secrets, keys, prompts, PII, **absolute paths, OS usernames/hostnames, `$HOME`/`$USER`**, or any
+   machine-local reference outside the repo. Describe the decision or its class, not literal payloads
+   or machine-local locations.
+
+7. **Commit the checkpoint.** Before committing, run the plan-brief leak guard over the brief —
+   `node "<sdd-skills>/check-plan-safety/scripts/check-plan-safety.mts" --path <brief> --check` (the
+   `check-plan-safety` engine). A hit **blocks the commit**: scrub the machine-local reference (bring
+   the content in-repo, reference it repo-relative) and re-run. Then commit the plan update (`docs:`)
+   so the pause is durable in git and the working tree is clean. Leave no uncommitted work behind.
+
+## Reconcile-forward checkpoint
+
+When the mission's live state is "this CR's work is already merged, not something this session
+ran live" (e.g. resuming a plan and finding its commits already landed on `main`), treat it as a
+checkpoint whose input is git/ledger evidence instead of a live conductor session — same
+procedure above, plus one gate before declaring the plan retirement-ready:
+
+- **Only for a CR-bearing mission.** A mission that opened a real CR and reached
+  `status: approved` or `implemented` gets this check. A non-CR mission (the `start-mission`
+  escape hatch — no suite-relevant behavior, no CR opened, no gate invoked) needs none; mark it
+  complete on its own merits.
+- **Run the gate floor.** Run `checkGateFloor` (`plugins/sdd/skills/spec-gate/scripts/
+  check-spec-state.mts`, wired into `pnpm verify:specs`) before marking the plan
+  retirement-ready. A clean floor → mark it. A violation (the status is approved/implemented but
+  the ledger has no matching gate approve line) → do **not** mark the plan retirement-ready on
+  git evidence alone; record the violation explicitly in `## NEXT` so a human resolves it (either
+  the ledger line was genuinely never written, or it needs relocating/re-checking).
+
+**Write scope.** A checkpoint writes **only the plan brief** — the `todos`, the `## NEXT` anchor,
+and (with `--approve`) the top-level `status`. It never touches `spec.md`'s `status` or `approval`:
+the mission's contract lifecycle is the gates', not the checkpoint's.
+
+## Clear for headless dispatch — `--approve`
+
+A plain pause never touches the brief's top-level `status`. When invoked with **`--approve`**, the
+checkpoint additionally sets the brief's **`status: approved`** — the human review act that clears
+the mission for the gateway's headless dispatch queue (the go-signal `dispatch` selects on; the
+enum + the three-way `status` distinction live in the SDD `provenance-model`). Rules:
+
+- **Human act only.** Setting `approved` is a review decision — a person has read the brief (todos,
+  `## NEXT`, the run-level leash) and cleared it. A **headless automaton never self-approves**: with
+  no user channel it may checkpoint progress but must **refuse `--approve`** and leave `status`
+  unchanged (the same positional-authority rule that reserves a human-ratified gate verdict).
+- **Idempotent.** Approving an already-`approved` brief leaves it `approved`.
+- **Flag-only.** It writes the one frontmatter field; it does not dispatch the mission (that is the
+  gateway) and does not touch the run-level leash — `approved` says *run it*, the leash says *how far*.
+
+## What a good pause is not
+
+- **Not a transcript.** Capture decisions and the next action, not a play-by-play.
+- **Not a duplicate.** If it already lives in a commit, an ADR, the spec, or an issue, link it.
+- **Not buried.** The next action leads the anchor; if a resumer has to hunt for where to start,
+  the pause failed.
+- **Not self-referential.** The plan never tells its reader to "invoke `resume-mission`" or
+  explains how to resume — a session reading the plan is already past that, and the
+  `## NEXT — resume here` heading orients a human on its own. Open `## NEXT` with the *work*.
+- **Not final-sounding.** A pause is a *resumable* checkpoint — leave the live frontier and the
+  open questions explicit, not smoothed into a summary that hides where to begin.
+
+The plan is self-sufficient: any session that opens it can continue. `resume-mission` reads this
+back conveniently, but is not required.

package/skills/place-node/README.md

@@ -0,0 +1,12 @@
+# place-node
+
+Internal SDD skill — the concrete engine for the **place-node** step. Given a new node's `concept`
+(and optional name), suggests a **provisional** capability home (derived from where that concept
+already lives) and catches possible duplicates, so explore places a node in one lookup.
+
+```bash
+node scripts/place-node.mts --spec-dir <spec> --concept resolution --name leash
+```
+
+Read-only and advisory; placement is finalized at handoff. See [`SKILL.md`](./SKILL.md) for the full
+contract. Not user-invocable.

package/skills/place-node/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: place-node
+description: "Partial Skill: invoke by name only — project-spec/place-node's engine that suggests a capability home and surfaces duplicates for a new node — used by explore, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Place Node
+
+The concrete engine for the **place-node** step. Given a new
+node's `concept` (and optional name), it suggests a **provisional** capability home and catches possible
+duplicates, so explore places a node without holding the whole tree in its head (it scans the project-spec's
+`concept:` frontmatter and ranks the capability folders those facets already sit in). Self-contained `.mts`
+(the repo's node-≥23.6 / no-deps convention).
+
+## Run it
+
+```bash
+node "<skill>/scripts/place-node.mts" --spec-dir <spec> --concept <c> [--name <n>]
+```
+
+- `--concept` — suggests the capability folders where that concept's facets already sit, ranked by count
+  (the provisional home). A concept no node yet carries → an empty suggestion: pick any plausible
+  capability, finalized at handoff.
+- `--name` — surfaces existing nodes whose path overlaps the name ("belongs near X" duplicate-catch).
+
+The home is **derived** from the project-spec's own `concept:` tags — where that concept's facets
+already sit — never a stored routing list (the `corpus/discovery` no-drift rule). For genuinely
+contested overlaps, the human tie-break rules live in the placement-map routing table (root
+`spec.md`), which this tool points to rather than re-deriving.
+
+**Strategy-neutral by construction — and not this tool's call.** The derivation follows the tree as
+it actually is, so it returns a correctly-shaped home under whatever layout the project declared: a
+`mirror-source` project's concepts sit in mirror-shaped folders, and "where the siblings already
+are" answers that as well as it answers capability-first. This tool therefore neither reads nor
+recommends a strategy. Choosing one belongs to `scaffold-project-spec`, recording it to the root
+`spec.md` placement map, and judging fit against it to the formation Warden
+(`sdd:spec-structure-governance`).
+
+## Boundaries
+
+Read-only and advisory — it **writes nothing** (no scaffold, no relocation, no frontmatter); placement is
+provisional and finalized at handoff (the `start-mission` handoff step), so a
+suggestion never has to be correct — only useful. Frontmatter only — no node body is read. When `node` is
+absent, an agent does the same by hand: read the `concept:` tags, see where that concept already lives,
+and place near them.

package/skills/place-node/scripts/place-node.mts

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// place-node — project-spec/place-node's concrete engine. Given a new node's concept (and optional name),
+// suggests a provisional capability home and surfaces possible duplicates, so explore places a node in
+// one lookup instead of holding the tree in its head.
+//
+// Derivation, not a registry: the home for a concept is where that concept's facets already sit — read
+// live from the project-spec's `concept:` tags, never a stored routing list (the corpus/discovery no-drift
+// rule). Read-only and advisory: it writes nothing, and placement is finalized at handoff.
+//
+// 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 { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
+
+export interface NodeRecord {
+	/** Path relative to the spec directory (POSIX). */
+	relPath: string
+	/** The top-level folder — the capability. */
+	capability: string
+	/** Display form — a README.md node shows its folder, a design doc shows the file. */
+	display: string
+	concepts: string[]
+}
+
+export interface HomeSuggestion {
+	capability: string
+	count: number
+}
+
+// ── Frontmatter parse (concept only — the placement signal) ──
+export function parseConcepts(text: string): string[] {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text)
+	if (!m) return []
+	const lines = m[1].split('\n').map((l) => l.replace(/\r$/, ''))
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]
+		if (line.length - line.trimStart().length !== 0) continue
+		const [key, ...rest] = line.trim().split(':')
+		if (key !== 'concept') continue
+		const value = rest.join(':').trim()
+		if (value.startsWith('[') && value.endsWith(']')) {
+			return value
+				.slice(1, -1)
+				.split(',')
+				.map((s) => unquote(s.trim()))
+				.filter((s) => s.length > 0)
+		}
+		if (value !== '') return [unquote(value)]
+		// block list
+		const out: string[] = []
+		for (let j = i + 1; j < lines.length; j++) {
+			const item = lines[j]
+			if (item.trim() === '') continue
+			if (item.length - item.trimStart().length === 0) break
+			const dash = /^\s*-\s+(.*)$/.exec(item)
+			if (dash) out.push(unquote(dash[1].trim()))
+		}
+		return out
+	}
+	return []
+}
+
+function unquote(v: string): string {
+	return v.replace(/^["']|["']$/g, '')
+}
+
+function displayPath(relPath: string): string {
+	const p = relPath.replace(/\\/g, '/')
+	return p.endsWith('/README.md') ? p.slice(0, -'README.md'.length) : p
+}
+
+// ── Scan the project-spec — every concept-tagged node ──
+export function scanProjectSpec(specDir: string): NodeRecord[] {
+	const records: NodeRecord[] = []
+	walk(specDir, specDir, records)
+	return records
+}
+
+function walk(dir: string, specDir: string, out: NodeRecord[]): void {
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue
+		const full = join(dir, entry.name)
+		if (entry.isDirectory()) {
+			walk(full, specDir, out)
+		} else if (entry.name.endsWith('.md')) {
+			const concepts = parseConcepts(readFileSync(full, 'utf8'))
+			if (concepts.length === 0) continue
+			const relPath = full.slice(specDir.length + 1).replace(/\\/g, '/')
+			out.push({ relPath, capability: relPath.split('/')[0], display: displayPath(relPath), concepts })
+		}
+	}
+}
+
+// ── Suggest a home — where the concept's facets already sit, ranked by count ──
+export function suggestHomes(records: NodeRecord[], concept: string): HomeSuggestion[] {
+	const counts = new Map<string, number>()
+	for (const rec of records) {
+		if (!rec.concepts.includes(concept)) continue
+		counts.set(rec.capability, (counts.get(rec.capability) ?? 0) + 1)
+	}
+	return [...counts.entries()]
+		.map(([capability, count]) => ({ capability, count }))
+		.sort((a, b) => b.count - a.count || a.capability.localeCompare(b.capability))
+}
+
+// ── Duplicate-catch — existing nodes whose path/name overlaps the candidate name ──
+export function findNear(records: NodeRecord[], name: string): NodeRecord[] {
+	const needle = name.trim().toLowerCase()
+	if (needle === '') return []
+	return records
+		.filter((rec) => rec.relPath.toLowerCase().includes(needle))
+		.sort((a, b) => a.display.localeCompare(b.display))
+}
+
+// ── Render ──
+function render(homes: HomeSuggestion[], near: NodeRecord[], concept: string, name: string): string {
+	const lines: string[] = [`place-node: concept=${concept || '(none)'} name=${name || '(none)'}`]
+	if (homes.length > 0) {
+		lines.push(`homes[${homes.length}]{capability,facets}:`)
+		for (const h of homes) lines.push(`  ${h.capability},${h.count}`)
+	} else {
+		lines.push('homes[0]: (new concept — pick any plausible capability; finalized at handoff)')
+	}
+	if (near.length > 0) {
+		lines.push(`near[${near.length}]:`)
+		for (const n of near) lines.push(`  ${n.display}`)
+	} else {
+		lines.push('near[0]: (no name overlap)')
+	}
+	lines.push('note: placement is provisional — finalized at handoff')
+	return lines.join('\n')
+}
+
+// ── CLI ──
+export function main(argv: string[]): number {
+	let specDir = '.'
+	let concept = ''
+	let name = ''
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i]
+		if (a === '--spec-dir') specDir = argv[++i] ?? '.'
+		else if (a === '--concept') concept = argv[++i] ?? ''
+		else if (a === '--name') name = argv[++i] ?? ''
+	}
+	const records = scanProjectSpec(specDir)
+	const homes = concept ? suggestHomes(records, concept) : []
+	const near = name ? findNear(records, name) : []
+	process.stdout.write(`${render(homes, near, concept, name)}\n`)
+	return 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/plan-retirement/README.md

@@ -0,0 +1,32 @@
+# plan-retirement
+
+Internal, non-user-invocable SDD skill carrying the Doctrine loop's **last retro step** — the
+gated, idempotent **tracked deletion** of a retired mission plan. It holds a self-contained
+`scripts/retire-plans.mts` (node ≥23.6, no deps; an agent fallback when `node` is absent).
+
+**Distill and delete are decoupled.** The Scanner distills the combat log into ledger `strategy`
+early (at `→ implemented`); this sweep deletes the plan **later**, gated on source = `done`/merged
+**and** distilled. The two signals **split by verifiability**: **source** stays the caller's
+judgment (`sdd:doctrine-loop` Scanner passes the source-cleared set via `--retire`; it needs
+network/`gh`), while **distilled** is **verified mechanically by the sweep** against the project
+ledger (`--ledger <dir>`) — a `strategy` entry with `distills == <cr-ref>` must exist (keyed on the
+`distills` field, never an `evidence` mention; unratified still counts). The distilled gate guards
+an **existing** combat log: a cr-ref whose `<cr-ref>.log.jsonl` was **never written** (a non-gated
+mission — hand-run, chore-tracked, investigation) has nothing to distill, so it retires on clearance
++ presence alone, no distilling entry required. The sweep is the mechanical, **fail-closed**
+filesystem act — it deletes a cr-ref's whole **transient artifact set** (`<cr-ref>.plan.md` +
+`<cr-ref>.log.jsonl` plus the optional transient CR-level planning briefs `<cr-ref>.design.md`,
+`<cr-ref>.operations.md`, `<cr-ref>.evidence.md`) only for a cr-ref that is cleared, present
+(`<cr-ref>.plan.md` on disk), **and** (distilled **or** has no log to distill); a cleared, present
+cr-ref whose log **exists** but is undistilled fails closed, taking its briefs with it. Anything not
+cleared, not present, missing, or already gone is a no-op (idempotent, safe to re-run). Omitting
+`--ledger` fail-closes to deleting nothing (the no-log branch only applies once a ledger is present
+to consult).
+
+The briefs **ride along, never gate**: they do not widen the distilled gate (which keys on the
+combat log's presence only — a brief owes no distillation, so a cr-ref with briefs but no
+`log.jsonl` still retires clearance-only), and they do not anchor presence (`<cr-ref>.plan.md`
+alone does — a brief without a `plan.md` is untouched). Each brief is deleted only if present; an
+absent one is a no-op, same as the missing log half.
+
+Tests (`scripts/retire-plans.test.mts`) run under `pnpm verify:specs`.