cyber-sdd 0.0.0

package/skills/resolve-tracking/scripts/resolve-tracking.mts

@@ -0,0 +1,213 @@
+// resolve-tracking — resolve one artifact's tracking signal (tracked | ignored).
+// Self-contained, no deps (repo's node-≥23.6 convention). Spec:
+// .agents/specs/sdd/intake/resolve-tracking/README.md
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export type Tracking = 'tracked' | 'ignored'
+
+// ─── .sddignore (.agents/sdd/.sddignore) — the universal override valve ───────────────
+//
+// gitignore syntax. Each non-blank, non-comment line is a pattern. A leading `!` marks the
+// path tracked (re-include); any other pattern marks it ignored. Matching is
+// last-match-wins: the LAST rule whose pattern matches the path decides.
+
+export interface IgnoreRule {
+	negated: boolean // leading `!` — re-includes (tracked)
+	regex: RegExp
+	source: string // the original pattern text (for notes)
+}
+
+// Compile the pattern body (no ! / trailing slash) to a regex fragment:
+// ** spans path separators, * and ? stay within a segment.
+function globToRegExpBody(glob: string): string {
+	return glob
+		.replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape regex specials (leave * ?)
+		.replace(/\*+/g, (m) => (m.length > 1 ? '.*' : '[^/]*')) // ** spans separators, * does not
+		.replace(/\?/g, '[^/]')
+}
+
+// Parse one raw line into a rule. Returns:
+//   - a rule for a well-formed pattern
+//   - 'skip' for a blank line or a comment (nothing loaded)
+//   - null for a malformed line (an empty pattern after stripping ! and trailing /)
+export function parseIgnoreLine(raw: string): IgnoreRule | 'skip' | null {
+	const line = raw.replace(/\r$/, '')
+	const trimmed = line.trim()
+	if (!trimmed || trimmed.startsWith('#')) return 'skip'
+
+	let body = trimmed
+	const negated = body.startsWith('!')
+	if (negated) body = body.slice(1)
+	const dirOnly = body.endsWith('/')
+	if (dirOnly) body = body.slice(0, -1)
+
+	let anchored = false
+	if (body.startsWith('/')) {
+		anchored = true
+		body = body.slice(1)
+	} else if (body.includes('/')) {
+		anchored = true
+	}
+
+	if (body === '') return null // nothing to match — malformed
+
+	// A leading `**/` matches at any depth; otherwise anchored patterns pin to root and
+	// unanchored patterns (no interior slash) match the name at any level. A trailing
+	// component (or dir-only pattern) also matches everything under it, mirroring git's
+	// "ignore a directory ⇒ ignore its contents".
+	const prefix = anchored ? '^' : '^(?:.*/)?'
+	const core = globToRegExpBody(body)
+	const suffix = '(?:/.*)?$'
+	try {
+		return { negated, regex: new RegExp(prefix + core + suffix), source: trimmed }
+	} catch {
+		return null // uncompilable — malformed
+	}
+}
+
+export function parseIgnoreFile(text: string): IgnoreRule[] {
+	const out: IgnoreRule[] = []
+	for (const raw of text.split('\n')) {
+		const rule = parseIgnoreLine(raw)
+		if (rule && rule !== 'skip') out.push(rule)
+	}
+	return out
+}
+
+// A missing file is legal — most projects need no overrides.
+export function loadIgnoreRules(root: string): IgnoreRule[] {
+	const path = join(root, '.agents', 'sdd', '.sddignore')
+	if (!existsSync(path)) return []
+	return parseIgnoreFile(readFileSync(path, 'utf8'))
+}
+
+// Last-match-wins: iterate rules in file order; the LAST rule that matches decides.
+// `!` => tracked, else => ignored. No match => null (fall through).
+export function resolveFromIgnore(rules: IgnoreRule[], path: string): Tracking | null {
+	let value: Tracking | null = null
+	for (const rule of rules) {
+		if (rule.regex.test(path)) value = rule.negated ? 'tracked' : 'ignored'
+	}
+	return value
+}
+
+// ─── kind default — the fixed agent-config location convention ───────────────────────
+//
+// Only skill / subagent / command carry a location-varying convention. Project-private
+// paths (`.agents/{skills,agents,commands}/**`) => ignored; project-public / shipped paths
+// (`skills/**`, `plugins/*/skills/**`, `packages/*/skills/**`, and the agents/commands
+// equivalents) => tracked. agents-section has one AGENTS.md (no location convention); code
+// artifact-types have no universal convention — both fall through with no kind default.
+const KIND_DEFAULT_GLOBS: Record<string, { ignored: string[]; tracked: string[] }> = {
+	skill: {
+		ignored: ['.agents/skills/**'],
+		tracked: ['skills/**', 'plugins/*/skills/**', 'packages/*/skills/**'],
+	},
+	subagent: {
+		ignored: ['.agents/agents/**'],
+		tracked: ['plugins/*/agents/**', 'packages/*/agents/**'],
+	},
+	command: {
+		ignored: ['.agents/commands/**'],
+		tracked: ['plugins/*/commands/**', 'packages/*/commands/**'],
+	},
+}
+
+function globMatch(glob: string, path: string): boolean {
+	return new RegExp(`^${globToRegExpBody(glob)}$`).test(path)
+}
+
+export function resolveKindDefault(artifactType: string | undefined, path: string): Tracking | null {
+	if (!artifactType) return null
+	const kind = KIND_DEFAULT_GLOBS[artifactType]
+	if (!kind) return null
+	if (kind.ignored.some((g) => globMatch(g, path))) return 'ignored'
+	if (kind.tracked.some((g) => globMatch(g, path))) return 'tracked'
+	return null
+}
+
+// ─── the four-step resolution ─────────────────────────────────────────────────────────
+
+export interface ResolveInput {
+	root: string
+	path: string
+	artifactType?: string
+	explicit?: Tracking
+}
+
+export interface ResolveResult {
+	value: Tracking
+	reason: string
+}
+
+export function resolveTracking(input: ResolveInput): ResolveResult {
+	if (input.explicit) {
+		return { value: input.explicit, reason: 'explicit override' }
+	}
+	const rules = loadIgnoreRules(input.root)
+	const ignoreMatch = resolveFromIgnore(rules, input.path)
+	if (ignoreMatch) {
+		return { value: ignoreMatch, reason: '.sddignore' }
+	}
+	const kindDefault = resolveKindDefault(input.artifactType, input.path)
+	if (kindDefault) {
+		return { value: kindDefault, reason: `kind-default (${input.artifactType})` }
+	}
+	return { value: 'tracked', reason: 'fail-closed (no signal)' }
+}
+
+// ─── validate the ignore file (no --path given) ───────────────────────────────────────
+
+export function validateIgnoreFile(root: string): { ok: boolean; message: string } {
+	const path = join(root, '.agents', 'sdd', '.sddignore')
+	if (!existsSync(path)) return { ok: true, message: '.sddignore OK (absent, fine)' }
+	const text = readFileSync(path, 'utf8')
+	const notes: string[] = []
+	const lines = text.split('\n')
+	lines.forEach((raw, i) => {
+		if (parseIgnoreLine(raw) === null) {
+			notes.push(`line ${i + 1}: not a valid gitignore pattern: ${raw.trim()}`)
+		}
+	})
+	if (notes.length > 0) {
+		return { ok: false, message: notes.join('\n') }
+	}
+	const loaded = parseIgnoreFile(text).length
+	return { ok: true, message: `.sddignore OK (${loaded} rule(s))` }
+}
+
+// ─── CLI ────────────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv: string[]) {
+	const out: Record<string, string> = {}
+	for (let i = 0; i < argv.length; i++) {
+		if (argv[i].startsWith('--')) {
+			out[argv[i].slice(2)] = argv[i + 1]
+			i++
+		}
+	}
+	return out
+}
+
+export function main(argv: string[]): void {
+	const args = parseArgs(argv)
+	const root = args.root ?? '.'
+
+	if (!args.path) {
+		const result = validateIgnoreFile(root)
+		process.stdout.write(`${result.message}\n`)
+		if (!result.ok) process.exitCode = 1
+		return
+	}
+
+	const explicit = args.explicit === 'tracked' || args.explicit === 'ignored' ? args.explicit : undefined
+	const result = resolveTracking({ root, path: args.path, artifactType: args['artifact-type'], explicit })
+	process.stdout.write(`${result.value}\n`)
+	process.stdout.write(`reason: ${result.reason}\n`)
+}
+
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+	main(process.argv.slice(2))
+}

package/skills/resume-mission/README.md

@@ -0,0 +1,12 @@
+# resume-mission
+
+Project-private workflow skill for **resuming an in-progress SDD mission from its plan brief**
+(`.agents/plans/<cr-ref>.plan.md`). Invoke it at the start of a new session ("load the plan",
+"resume the mission", "continue github-NN") to re-establish the working method and spec context,
+find the next todo, and continue without relitigating settled decisions.
+
+The plan is the **state** (mission-specific todos, decisions, findings); this skill is one
+convenient **procedure** for picking any plan up — any session that reads the plan can continue
+without it. If no plan exists yet, it scaffolds one from a basic template. `internal: true` —
+contributor tooling for this repo, not a shipped SDD capability. If "mission resume" should become an SDD-delivered
+capability, spec it in `mission/` first and build the impl in the SDD plugin.

package/skills/resume-mission/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: resume-mission
+description: "Resume an in-progress SDD mission from its plan brief. Use when asked to 'load the plan', 'resume the mission', 'continue github-NN', or otherwise pick up an SDD .plan.md where it left off — re-establish the working method and spec context, find the next todo, and continue without relitigating settled ground."
+---
+
+# Resume an SDD mission from its plan
+
+An SDD mission is carried by a single tracked **plan brief** at
+`.agents/plans/<cr-ref>.plan.md` (the portable handoff artifact). The plan is the **state**;
+this skill is one convenient **procedure** for picking it up — any session that reads the plan
+can continue without it. It re-establishes context from the brief and continues the Mission Loop
+where it left off.
+
+## Procedure
+
+1. **Open the plan — create it if missing.** Open `.agents/plans/<cr-ref>.plan.md` and read it in
+   full: the frontmatter `todos` (the ordered task list; `status: pending | in_progress |
+   completed`) and the body (working method, resolved decisions, findings, `## NEXT`). **If no
+   plan exists** (the mission was never intook), scaffold a minimal one from a basic template
+   (frontmatter `todos` + a `## NEXT` anchor) and start the mission from there.
+
+2. **Find the next action.** Resume the single `in_progress` todo if one exists; otherwise the
+   first `pending` todo whose prerequisites are met. The body's `## NEXT` section names the
+   live frontier and any blocking decisions — honor it over guessing.
+
+3. **Reload the working method — do not relearn or relitigate it.** The plan records *how this
+   mission is run* (its phase model, per-step rhythm, suite/impl conventions, which plugin or
+   spec dirs are baseline vs fresh). Treat resolved decisions (the `## Resolved decisions`
+   block) as settled; reopen one only on new evidence, and say so.
+
+4. **Load only the spec context the next todo needs.** For a capability sub-mission, read that
+   capability's `README.md` under `.agents/specs/<project>/<cap>/` plus the SDD design rules and
+   governances it references — not the whole tree.
+
+5. **Continue, committing per unit.** Work in the plan's stated rhythm; commit each coherent
+   unit (Conventional Commits, one concern, tests green). Update the todo `status` and record
+   any new finding or decision **back into the plan** as you go, so the next resume is clean.
+
+6. **Surface blocking decisions; never guess past them.** If `## NEXT` names an open decision
+   (a scope call, an unresolved `<!-- open: -->` marker), raise it before proceeding past it.
+
+## Guardrails (carried across sessions)
+
+- **Reason to the correct answer, not a vote.** On a contradiction, reason from the design's
+  *intent*; corroboration, implementation, and recency are evidence to weigh, not ballots to
+  tally. Fix the side that is wrong.
+- **Spec the behavior, then build.** A skill or governance is a testable capability — spec it
+  (prose + a per-unit `.feature`) before or alongside building its implementation; never
+  hand-edit an implementation as a shortcut around its spec.
+- **Respect the baseline.** Build fresh where the plan says fresh; never mutate a directory the
+  plan marks as the untouched reference baseline.
+- **Commit boundary.** The unit of work is one co-committable change (clear message, green
+  tests) — not the whole CR. A CR's mission lands as many commits.

package/skills/scaffold-project-spec/README.md

@@ -0,0 +1,7 @@
+# scaffold-project-spec
+
+Non-user-invocable SDD skill holding the **project-level layout bootstrap**: when a project has **no spec yet**, choose how the spec is organized, scaffold that skeleton, and declare the choice. It serves an **existing** project and a **greenfield** one through one entry, branching on **evidence mode**.
+
+Loaded via the harness (`Skill`) by the **conductor** (the main session) **once at bootstrap** when `start-mission` explore finds a project lacking a spec. It is **not** a user entry — the single entry is `start-mission`; this is an internal explore-phase step. It runs a seven-step procedure — pick the evidence mode (is there source to read?) → establish the project shape (read the source, or ask what the project will do) → choose the spec location (colocated / hoisted / monorepo-member) → recommend + choose a strategy (capability-first default, mirror-source) → scaffold the shared envelope + the strategy skeleton (each node declaring a legal `spec-type`) → declare the `project-path` frontmatter + the body placement map → hand back to per-unit explore — and leaves the tree at `status: draft`.
+
+The skill is self-contained — it bakes in the whole layout model: the node taxonomy (three spec-types, the concept axis, the two-level depth cap, screaming-architecture default), the strategy menu + the shared envelope + the per-strategy SDD-fit, and the spec-location rules (the hoist-out-of-the-distributable rule). It also bakes in the boundary-aligned mirror-depth rule, the spec-type classifier, the reserved by-concept index block (filled by the `concept-index` skill, not by hand), ADR-as-facet (a `design/decisions/` log, never an ADR-organized body), and the output boundary — it authors no node's `## Use Cases`/`.feature`, renders no gate verdict, and writes no control frontmatter (those are `spec-gate`'s and the conductor's). Proposes node placement for the formation Warden to confirm.

package/skills/scaffold-project-spec/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: scaffold-project-spec
+description: "Partial Skill: invoke by name only — lay out an SDD project-spec"
+user-invocable: false
+---
+
+# scaffold-project-spec — lay out a project's spec
+
+The procedure the **conductor** follows, **once at bootstrap**, when `start-mission` explore finds a project
+with **no spec yet**. It chooses *how the spec is organized*, scaffolds that skeleton, and
+**declares the choice**, so the per-unit explore that follows (`spec-producer-governance`) slots work into known
+homes. It is **internal** — reached through `start-mission`, never a user entry — and leaves the tree at
+`status: draft`; it authors no node's `## Use Cases`/`.feature`, renders no gate verdict, and freezes nothing.
+
+**Load `sdd:spec-structure-governance`** for the layout law it applies: the node taxonomy (three
+spec-types, the concept axis), the two-level depth cap, screaming architecture and the
+non-capability folders, root-files-not-folders, and the colocate-or-hoist test. This skill does not
+restate that law — it **runs** it, and owns only what is genuinely its own: the **strategy menu**,
+the **shared envelope**, and the seven-step procedure below.
+
+Run the seven steps in order, surfacing each choice to the user (recommended-first), never assuming
+silently.
+
+## 0 — Pick the evidence mode
+
+**Detected, not chosen.** Ask one question of the tree, not of the user: **does this project have source to
+read?** Scope it to the **project**, never the repo — a new package inside an existing monorepo is a
+greenfield *project* in a populated *repo*.
+
+- **detection mode** — the project's source exists. Steps 1-3 read it.
+- **intent mode** — the project's source does not exist yet. Steps 1-3 have nothing to read for it, so they
+  run off what the user states the project *will* be.
+
+**The repo around an intent-mode project is still readable**, and reading it is not a mode switch: an
+existing monorepo's shape, conventions, and sibling packages inform the recommendation even when the
+project itself is empty. Intent mode means *this project* has no source — not that the disk is blank.
+
+Steps 4-6 are identical under both modes. Never run detection's signal-reading against an empty project and
+never let intent mode fall through to a silent default.
+
+## 1 — Establish the project shape
+
+**Detection mode** — read signals, do not guess: an **agentic plugin** (`.plugin/` + `skills/` + `agents/`);
+a **monorepo** (`apps/`+`packages/`, or multiple package anchors each with their own manifest); whether
+`src/` is **feature-** or **layer-organized**; framework markers; owners (`CODEOWNERS`); size.
+
+**Intent mode** — the project has no signals of its own. Establish by asking (reading the surrounding repo
+where it helps) the three things detection would otherwise have read:
+
+1. **What kind of project** — a repo harness, an agent plugin, an npm package, a website, an app
+   (`project-unit.md`). This is what the plugin/monorepo/plain classification stood for.
+2. **Where it will live** — the repo-relative dir its source will occupy. This is the **`project-path`** step
+   5 must write, and in a greenfield project that directory does not exist yet, so it can only be asked.
+   Confirm it rather than inventing a path.
+3. **What it will do** — the intended capabilities, which step 3 recommends a strategy from.
+
+(2) gives the `project-path`; (1) decides the **location**, per step 2 — nesting does not.
+
+## 2 — Choose the spec location
+
+Recommend, let the user override, never assume:
+
+**Colocate by default.** Hoist only when the spec **cannot be kept out of what ships** — nesting alone is
+never the reason.
+
+- **`<project>/.agents/spec/`** (colocated).
+  An npm package colocates fine: `files` / `.npmignore` excludes `.agents/` from the tarball.
+- **`<repo>/.agents/specs/<name>/`** (hoisted — named by the package). Only when the project dir is
+  distributed **wholesale**, with no include/exclude mechanism to leave the spec behind. The one identified
+  case is an **agentic plugin**: plugin install distributes the whole plugin directory, so a colocated spec
+  would ship to every consumer. If a new packaging format has the same all-or-nothing distribution, it joins
+  this case; otherwise colocate.
+- **monorepo** — offer to lay out **every package** (each hoisted to `<repo>/.agents/specs/<name>/`) plus the
+  outer project (`<repo>/.agents/spec/`). Run steps 1–6 **per selected project**, producing several draft
+  trees (the evidence mode is picked once, in step 0, for the whole run).
+
+In **intent mode** apply the same test to the **kind of project** established in step 1: an agentic plugin
+hoists, everything else colocates at the `project-path` given. Confirm with the user; never re-ask location
+as an independent choice, and never hoist merely because the path is nested.
+
+## 3 — Recommend + choose the strategy
+
+Present **one recommendation + its rationale + the alternative**; the user chooses. Shipped menu:
+
+- **capability-first** *(default)* — top-level folders by what the project *does*. Recommend when a capability
+  decomposition is discernible. For a fixed-layout plugin this is a spec-side abstraction over fixed source —
+  accepted for legibility; name the spec↔source divergence as a known cost.
+- **mirror-source** — spec nodes track the source tree. Offer whenever the team **navigates by code**;
+  a **feature-first** `src/` is the best case, not a precondition. Over a **layered** source, still
+  offer it — but name the cost: the folder partition is coarse, so the scheduler sees more collisions
+  and the schedule is slower (never wrong — an unresolved collision serializes, `sdd:spec-structure-governance`).
+  Say what recovers it (the collision ladder resolves most shared-node pairs at the file or symbol
+  rung) and what the exit looks like (concept tags accumulate; hoist a capability when the
+  false-conflict rate earns it). Mirror is **boundary-aligned** (step 4). **Detection mode only** —
+  there is no source tree to mirror in intent mode.
+
+**Offer to measure, rather than argue.** In **detection mode** on a repo with real history, offer to
+run `sdd:check-partition-quality` before the choice is made: it reports, from this project's own
+commits, how much parallel work each candidate layout would permit. Opt-in — it reads `git log`, so
+it is slow on a large repo and says nothing useful on a young one, and it renders no verdict. When it
+runs, present its parallelizable shares alongside the recommendation so the user chooses on their own
+numbers rather than on doctrine. Skip it silently in intent mode: a greenfield project has no history
+to measure.
+
+**Do not require a restructuring before the first spec.** An existing project adopting SDD keeps the
+shape it has; capability-first is the destination, reached on evidence, not an entry toll. Recommend
+capability-first, accept mirror-source with its cost stated, and let the data drive the migration.
+
+In **intent mode**, recommend from the capabilities the user stated in step 1. If they have not stated any,
+**ask for them** — never apply the capability-first default silently. (Detection mode's no-signal fallback
+*is* the capability-first default; intent mode has no equivalent, because a greenfield project always has an
+intent to state.)
+
+Never offer **layering** or **arc42 sections** as the *top* level — they nest *inside* a capability. **ADR is
+not a strategy** — it is the decisions facet (step 4). The deferred strategies (bounded-context, layered,
+doc-envelope) are off the shipped menu; surface them only on an explicit "show more options".
+
+## 4 — Scaffold the envelope + skeleton
+
+Write the **shared envelope** every strategy ships:
+
+- root **`spec.md`** (the index + the `project-path` frontmatter + the placement map + the reserved by-concept
+  index block — step 5);
+- **`design/`** — the rules/model home, **including `design/decisions/`** (the ADR log: append-only,
+  descriptive, ungated — the project-scope sibling of a unit's `<unit>.solution.md`; *organize no node as an
+  ADR body*);
+- **`workflows/`** — the workflows suite home (cross-capability usage flows);
+- a **tooling/project** home (build, CI, packaging, deps);
+- **`glossary.md`** — a root file beside `spec.md` (never a folder): the project's ubiquitous
+  language, every load-bearing term defined once in plain words. Seed it with the terms the scaffold
+  already commits to; per-unit explore adds the rest.
+
+Then the chosen strategy's **top-level skeleton** of **stub node READMEs**, each declaring a legal
+**`spec-type`** via the classifier:
+
+- a **testable surface** → `behavioral` (`## Use Cases`; its `.feature` is authored later, in explore);
+- a **shipped suite-less artifact** (a governance, a config) → `reference` (`## Subject`, no
+  `.feature`);
+- an **index / rule / structural grouping** → **descriptive** (no marker).
+
+The skeleton obeys the **two-level depth cap** under **every** strategy: a node is
+`<capability>/<unit>` and **never three deep** — a sub-grouping inside a capability is a `concept:` tag
+recovered by the by-concept index, not a third folder level. Under **mirror-source**, mirror **only to the
+unit boundary**: a folder with a testable surface becomes one behavioral leaf that owns its subtree; create
+**no node below a behavioral leaf** (nested `src/` there is impl detail). A capability node README carries
+**only** its `spec-type` marker — never a lifecycle field; its cross-cutting **`concept:`** tag is assigned
+later in per-unit explore (via the `place-node` skill), not at scaffold.
+
+## 5 — Declare the organization (do not leave it to be re-derived)
+
+In the same act that writes root `spec.md`, record both so a later edit reads, never re-scans:
+
+- **`project-path` frontmatter** — the repo-relative source dir this spec governs (the package for a
+  hoisted spec; the project root for a colocated one). It is the router's source→spec map; the spec
+  **location mode** (`colocated | hoisted | monorepo-member`) is *derived* from it, not stored. There is
+  **no `spec-layout` block** (ADR-0017: frontmatter is the router index — the strategy is not something the
+  router needs).
+- **`name` frontmatter (the project name)** — write it when the project's name is **not reliably
+  derivable** from the location (`discover-specs` derives `repo` for a repo-root single-project and the
+  folder for a `.agents/specs/<project>`, but only **guesses** a nested project's folder basename). For a
+  **hoisted / nested** project, **ask the user for the name and store it** (infer a default from the
+  invocation when the user named the project — e.g. `backfill <this-project>`); confirm before writing.
+  Skip it when the derived name is already right (a plain colocated repo-root project).
+- the **placement map** in the body — the maintained "a concept of kind K lives in home H" taxonomy + the
+  nesting rule, **naming the chosen strategy** in its heading/intro, so a newcomer routes a new concept
+  without holding the tree in their head and `start-mission` / the Warden read the strategy on demand.
+- the **reserved by-concept index block** beside it (generated by the `concept-index` skill) — the
+  cross-cutting `concept → its nodes` view. Reserve the block; **leave it for `concept-index` to
+  generate** from `concept:` frontmatter — pure derivation, never hand-maintained.
+
+Validate the result with the `spec-gate` skill's `check-spec-state` script (`check-spec-state.mts --root
+<specs-dir>`): the root lifecycle tuple must be legal.
+
+## 6 — Hand back
+
+Backfill ends with **stub** behavioral nodes (`## Use Cases` present, no `.feature`), not filled ones —
+filling them is the **per-unit explore grill** (`spec-producer-governance`), the interactive live loop. **Do
+not auto-continue into it.** Present the count of stub nodes and **ask the user**:
+
+- **Continue now** — proceed into per-unit explore in this session, node by node, to the spec gate.
+- **Defer to a mission** — stop at `status: draft`; the stubs stay a worklist any later `start-mission` /
+  `resume-mission` picks up (the explore grill may want a different model or session).
+
+Either way, **propose** the node placement for the formation **Warden** to confirm or relocate, and leave
+`status: draft`.
+
+## Output boundary
+
+Write the skeleton, the root envelope (`project-path` frontmatter + placement map + the reserved by-concept
+index block), the `design/decisions/` home, and `glossary.md` — nothing else. Do **not** author any node's `## Use Cases`/`.feature`, render a gate verdict,
+freeze, or write `status` / `approval` / `produced-by` (the conductor's and `spec-gate`'s; see
+`ownership-governance`).

package/skills/sdd/README.md

@@ -0,0 +1,7 @@
+# sdd
+
+The SDD **gateway** skill — the universal front door to a Spec-Driven-Development project. User-invocable: activates SDD, gathers missing intent, classifies what the user wants to do to the project, and **loads the handling skill in the current session** (`start-mission` for a change, the corpus tools, the outer loops), where the session works the task directly.
+
+A **thin classifier**: it holds no production logic, loads **no governance** (the macro-grill ruling), and writes no contract state. It does **not** pin a model — the skill it loads declares the model + effort its work needs. By default it **spawns nothing** — it loads the matched skill in the main session, which **is** the conductor (the user in the driver's seat). It spawns the **automaton** (the headless driver) **only** when there is no user channel (an unattended scheduler or a multi-CR fan-out).
+
+Bakes in: explicit activation (`$sdd`), the fast path (change + target → load directly), the two-level intake menu with the hard four-option rule, surface-pending-strategy (count the unratified `strategy` lines globbed from the `ledger/` shards sibling to `spec.md` — never the `*.log.jsonl` combat log; never draft or ratify), the routing-table-as-capability-index (a change → `start-mission`), load-in-session-vs-headless-automaton with write-ownership preserved, and escape / freeze recognition (a non-CR escapes with no record; a frozen `.feature` re-opens through a mission).

package/skills/sdd/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: sdd
+description: Use this skill when the user explicitly invokes SDD or wants to work on a creation artifact with Spec-Driven Development.
+---
+
+# SDD
+
+Gateway skill for Spec-Driven Development — the front door to the project. It **activates** SDD, gathers missing intent, classifies what the user wants to do to the project, and **loads the handling skill in the current session**, where the session works the task directly. It is a **thin classifier**: it holds **no production logic**, loads **no governance**, and writes no contract state. It does not edit project files, register hooks, install packages, or require a CLI command.
+
+For an attended session the gateway **spawns nothing** — it loads the matched skill (for a change to the project, `start-mission`) in the **main session** and the work proceeds there. The session itself is the **conductor** (the user in the driver's seat). The only thing the gateway spawns is the **automaton** — the headless driver — when there is **no user channel** (an unattended scheduler or a multi-CR fan-out).
+
+> **Model is set by the skill you load, not here.** The gateway does not pin a model: classification is light, but the skill it loads declares the model + effort its work needs (`start-mission` advises a capable model for the live grill). The routed skill advises; the user switches manually. (Harness gap: the gateway cannot switch the session model itself.)
+
+## Gateway intake
+
+Treat `$sdd`, "use SDD", and "use Spec-Driven Development" as explicit activation. **Most** activating requests are CRs; classification decides which source carried it and which skill handles it. A task with **no suite-relevant behavior**, or one confined to an **ignored** surface, is **not a CR** and escapes (below); recognition is the grill, so ambiguity routes *into* the lifecycle and is decided during explore.
+
+### Surface pending strategy
+
+When the Council re-enters, **surface the count of pending (unratified) strategy** — count the `strategy` lines with `"ratified": false` globbed from the project's **root `ledger/` shards** (the durable sibling directory of the root `spec.md`; a legacy `ledger.jsonl` still counts) and state "N pending strategy" alongside the intake; if the Council picks it, route them to review those entries. Count only `kind: strategy` — the conductor's `kind: leash` run-start blocks are **not** strategy and never counted. The gateway only *surfaces* the count — it never **drafts** strategy (the Scanner's job) nor **ratifies** it (the Council's positional act). A zero count is not surfaced. (`strategy` lives in the durable `ledger/` shards, **never** in the per-mission `*.log.jsonl` combat log.)
+
+### Surface in-progress missions
+
+On re-entry, **surface the resumable missions** — run the **`discover-plans`** skill (the engine for `intake/plan-discovery`), which scans `.agents/plans/` for `*.plan.md` briefs and returns each one's CR ref, todo tally, and `## NEXT` lead as TOON. A present brief is an **unretired** mission (the doctrine loop's `plan-retirement` deletes a brief once its CR is done/merged and distilled), so each one listed is **resumable**; state them alongside the intake (e.g. "3 in-progress: `github-34` 21/34, …") and, if the user picks one, **load `resume-mission`** on it. The gateway only *surfaces* — it never **resumes** (that's `resume-mission`) nor **retires** (that's `plan-retirement`). An empty set is not surfaced. This is a **read** (the same category as counting strategy lines), so the thin-classifier rule holds.
+
+This is the **resumable-mission** sibling of surface-pending-strategy — two distinct concerns, both surfaced: pending strategy is the doctrine loop's unratified ledger lines for the **Council** to keep-or-cut; in-progress missions are **paused work** any user can continue.
+
+### Fast path — skip the menu
+
+When the invocation already names **both** a change and a target — "add a start-mission skill to sdd", "implement the auth capability", "work on <issue url>" — skip the menu and load the handling skill directly. A partially-specified request resolves what it can and asks only for the missing piece, within the four-option rule.
+
+### Two-level menu — bare invocation
+
+When `$sdd` is invoked with no work item, artifact, or action, do not guess. Conduct intake as a **two-level menu**, never a flat list. **Never ask more than four options** in a single `AskUserQuestion` (the tool rejects more than four). The top-level question presents **exactly four** options:
+
+| # | Top-level option | Covers |
+|---|---|---|
+| 1 | **Make a change to the project** | open a CR against the project spec (add a capability, revise behavior, implement, land) → `start-mission` |
+| 2 | **Manage the corpus** | setup & discovery, inspect, audit, or housekeeping (non-mission) → `manage` |
+| 3 | **Review pending strategy** | the doctrine loop's unratified `strategy` lines, when any are pending |
+| 4 | **Help me choose** | scan the spec + statuses, suggest the most-actionable few (≤ 4), let the user pick |
+
+When a derived list would exceed four, present only the most-actionable few (≤ 4) or ask the user to name the target directly; never enumerate into an over-four question and never truncate silently.
+
+### Scan statuses with discover-specs
+
+For **Help me choose** — and whenever it needs to locate the project spec or rank the most-actionable few — the gateway runs the **`discover-specs`** skill, the frontmatter-only engine for `corpus/discovery`. It returns the TOON list of every project spec at the SDD spec locations — the three fixed conventions plus any opt-in extra anchors a project declared (ADR-0019) — with its `status`, `project-path`, and gate `approvals`; the gateway ranks from that and never opens a spec body. This is a read, not production logic — the same category as counting `ledger/` shard lines for pending strategy — so the thin-classifier rule still holds.
+
+**No spec found offers spec anchors.** When `discover-specs` finds no spec for a target project, do not assume it was simply never scaffolded — its spec may sit off the three fixed conventions and need a declared extra anchor. Offer `manage-spec-anchors` (via `manage`) alongside `scaffold-project-spec` as entry points, rather than routing straight to backfill.
+
+## The routing table is the user-skill→capability index
+
+Classification routes a request to the **skill** that handles it; the routing table doubles as the index of what a user can invoke (there is no separate `skills.md`).
+
+| User intent | Skill (handler) |
+|---|---|
+| Make any change to the project / spec (add, revise, implement, land) | **`start-mission`** — opens a CR against the project spec and runs the mission loop |
+| Manage the corpus — setup & discovery, inspect, audit, or housekeeping (non-mission) | **`manage`** — the manage dispatcher; loads the matching corpus engine in-session |
+| A task with no suite-relevant behavior, or confined to an ignored surface (not a CR) | **escape** — proceeds outside the lifecycle, leaves no SDD record |
+| Product / structure / process retrospective, or field corrections | the **campaign / formation / doctrine / forge** loop — emits a new CR (→ `start-mission`) |
+
+One project is one spec — routing classifies *what a user wants to do to the project*, never *which spec in a fleet*. Almost every change is one entry — `start-mission` — which runs the mission loop; whether the CR adds a capability, revises behavior, or reconciles overlap is decided during its **explore** phase, not by a separate entry skill.
+
+## Load the handling skill in-session
+
+When the route resolves, **load the matched skill in the current session** and work the task directly — spawn nothing.
+
+- **Default (a user session hosts the conductor): load in-session.** For a change to the project, load `start-mission`; it runs the mission loop over the project spec. The session **is** the conductor (the user in the driver's seat); it holds the user channel directly and spawns only the **cold judges** and the **impl-producer builder** at depth 1, where grader independence requires it.
+- **Headless (no user channel — an unattended scheduler or a multi-CR fan-out): spawn the automaton.** The **automaton** is the headless driver (the orchestrator delegate). It runs the same mission loop with no human in the seat: it self-asserts at the autonomy bar and batches `needs-input` rather than asking live, and whatever spawned it relays those questions. The automaton is **not** a separate orchestrator role — it is the driver run headless.
+
+### Dispatch the approved queue — the multi-CR fan-out
+
+When the work is a **queue of already-reviewed missions** (each brief cleared with `status: approved`), run the **dispatch loop** — entered by an attended "run the approved missions" request or an unattended trigger (cron):
+
+1. **Select the queue.** Run `discover-plans --status approved` — the approved briefs, in list order. An empty queue is a no-op.
+2. **Run sequentially, one fresh automaton per mission.** For each brief: if it has no remaining todos, **skip** it (nothing to run); otherwise **spawn a fresh `sdd-automaton` on that brief** — a cold context that reads only its own brief + on-disk artifacts. Collect its verdict packet, then move to the next. **Never run two missions in parallel on the shared working tree.**
+3. **Relay, never guess.** On a `needs-input` verdict, relay it live (attended) or batch it up the relay (unattended); never auto-accept past it. On a `halt` verdict, **stop that mission** and relay the halt (do not continue it), then move to the next brief.
+
+The **fresh spawn per mission is deliberate** — each automaton's context dies with it, so nothing carries from one mission to the next and the dispatch session holds only the queue + small verdict packets (not compaction, which would bleed a prior mission's settled decisions into the next grill). Dispatch **spawns and relays only** — it writes no contract state; each mission's automaton self-asserts and writes its own ledger lines, and the `approved` flag is the human's (set via `pause-mission --approve`), never dispatch's.
+
+**Write-ownership.** The gateway writes **no** contract state. The internal spec / impl gates own the `status` write and the human ratification of `approval`; the conductor (the in-session user, or the automaton when headless) owns any provisional self-assertion. The gateway writes neither.
+
+## Recognize the escape and the freeze
+
+- **Escape.** A task that is **not a CR** escapes: create no draft, invoke no gate, and **write no record** (a non-CR is not SDD's to track; a spec-prose-only change is already in git). Two independent triggers: **no suite-relevant behavior**, or an **ignored** touched artifact. Escaping does not mean stopping — if the artifact-type has a producer with an escaped-request entry point (e.g. `define-skill` for `skill`), invoke it directly to do the actual work; only state "leaving the lifecycle" and stop when no such producer exists. For tracking, run the `resolve-tracking` skill (`intake/resolve-tracking`'s concrete engine) per touched artifact:
+
+  ```bash
+  node "<resolve-tracking skill>/scripts/resolve-tracking.mts" --root . --path <repo-relative-path> [--artifact-type <type>] [--explicit tracked|ignored]
+  ```
+
+  `--explicit` carries a tracking statement the requester made directly in the prompt/CR, when present. Pass `--artifact-type` when convention already makes it obvious (`skill` under `skills/`, `subagent` under `agents/`, …) — a full `resolve-governances` classification is not needed just to gate the escape check. An `ignored` result escapes the same as no-suite-relevant-behavior; a `tracked` result (including the fail-closed default) proceeds toward CR classification. This is a **read**, the same category as counting strategy lines or scanning specs — the thin-classifier rule still holds. Recognition is the **grill + impact analysis**, not a gateway classifier — the grill may carve a CR out of the tracked parts of a mixed request and escape the ignored ones. Ambiguity defaults *into* the lifecycle and is decided during explore.
+- **Freeze.** SDD freezes the `.feature` at approval. A request to change a frozen scenario is **not** edited in place; it loads **`start-mission`**, which grills the spec back open through the explore phase before scenarios may be revised.

package/skills/solution-producer-governance/README.md

@@ -0,0 +1,9 @@
+# solution-producer-governance
+
+Non-user-invocable SDD skill holding the **default solution-producer procedure**: how to record a unit's `<unit>.solution.md` (the chosen approach + rejected alternatives) for a domain no plugin covers — **only** when the unit carries durable design rationale.
+
+Loaded via the harness (`Skill`) by the **conductor** (the main session) when it runs the solution-producer role from the SDD default — the conductor authors **inline** in its own warm context (recorded `produced-by.solution-producer: sdd:automaton`) rather than spawning a producer agent. Relocates the *functional-spec* half of the former `plan-producer` role to a per-unit, optional, ungated facet; the task-DAG half is now the conductor's transient execution `.plan.md` `todos`, not this role's output.
+
+The solution is the unit's **third facet** (spec / suite / solution). It is **optional** (most units have none), **boundary-aligned** (maps to the design decision, not one entry per scenario), and **ungated / unfrozen** — no judge grades it and the spec gate does not see it; the implementation's frozen-scenario result validates it transitively.
+
+References the resolved **architect** actor bar (structural fit) as its self-alignment criterion and `sdd:ownership-governance` for the write-ownership matrix (it never edits `spec.md`, the `.feature`, or control frontmatter). Bakes in the warranted-vs-not test (a real design fork vs a shape that follows from the spec) and the never-restate-the-contract rule.