cyber-sdd 0.0.0

package/skills/init/scripts/wire-statusline.mts

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// wire-statusline — gateway/init's concrete wiring engine for the mission statusline. It reads/writes
+// ONLY project `.claude/settings.json` (never the global `~/.claude/settings.json`) and, only when the
+// root is a git repo, `.gitignore`. It never touches spec/contract state (status, approval, spec.md).
+// It also READS the global `~/.claude/settings.json` (or an override path) to detect and, on a fresh
+// wire, compose its statusLine command as the wrapped base — read-only, never written.
+//
+// Operation:
+//   --wire --mode own-line|same-line   compose the SDD statusLine segment into project settings and
+//                                       (in a git repo) add the status file to .gitignore; idempotent
+//                                       [--global-settings <file>] [--no-global-base]
+//   --detect [--global-settings <file>]  read-only: report project/global statusLine state and shadow risk
+//
+// The wired command reads the single-line status file `.agents/sdd/statusline` the conductor writes
+// (`../../mission/conductor/`) and renders it — own-line (a new row) or same-line (an appended
+// segment) — falling through to nothing (or the composed base, unchanged) when the file is absent.
+// Compose, never stomp: an existing `statusLine` command is preserved as the wrapped "base"; the SDD
+// segment is added around it. Re-wiring (same or a different mode) rewrites the one managed block —
+// it never stacks a second SDD segment.
+//
+// Global shadow (issue #164): Claude Code's project statusLine REPLACES (never merges with) the
+// global one. When the project has no statusLine of its own, a fresh wire composes the global
+// command as the base by default so the global line keeps rendering instead of going blank. A
+// re-run of an already-wired (or foreign) project command never re-consults the global — only a
+// fresh wire ever adopts it.
+// Pure functions are exported for node:test; running the file directly drives the CLI. No deps.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const STATUS_FILE = '.agents/sdd/statusline'
+export const SETTINGS_FILE = '.claude/settings.json'
+export const GITIGNORE_FILE = '.gitignore'
+export const GLOBAL_SETTINGS_FILE = join(homedir(), '.claude', 'settings.json')
+
+export type StatusLineMode = 'own-line' | 'same-line'
+
+const MARKER_BEGIN = '# sdd-statusline:begin'
+const MARKER_END = '# sdd-statusline:end'
+const MODE_PREFIX = '# sdd-statusline:mode:'
+const ORIG_OPEN = '__sdd_orig() {'
+const ORIG_CLOSE = '}'
+const NO_BASE = ':'
+
+// ── the managed command block ──
+
+// Build the self-contained POSIX sh command that reads the status file and renders it in `mode`,
+// wrapping `base` (the pre-existing statusLine command, if any) so its output is preserved.
+export function buildCommand(base: string | undefined, mode: StatusLineMode): string {
+	const origBody = base && base.trim() !== '' ? base : NO_BASE
+	const render =
+		mode === 'own-line'
+			? `if [ -s "$__sdd_file" ]; then\n  __sdd_val="$(cat "$__sdd_file")"\n  printf '%s\\n%s\\n' "$__sdd_base" "$__sdd_val"\nelse\n  printf '%s\\n' "$__sdd_base"\nfi`
+			: `if [ -s "$__sdd_file" ]; then\n  __sdd_val="$(cat "$__sdd_file")"\n  printf '%s | %s\\n' "$__sdd_base" "$__sdd_val"\nelse\n  printf '%s\\n' "$__sdd_base"\nfi`
+	return [
+		MARKER_BEGIN,
+		`${MODE_PREFIX}${mode}`,
+		ORIG_OPEN,
+		origBody,
+		ORIG_CLOSE,
+		'__sdd_base="$(__sdd_orig 2>/dev/null)"',
+		`__sdd_file="${STATUS_FILE}"`,
+		render,
+		MARKER_END,
+	].join('\n')
+}
+
+export interface ParsedCommand {
+	wired: boolean
+	base?: string
+	mode?: StatusLineMode
+}
+
+// Recognize a previously wired command and recover its wrapped base + mode, so re-wiring rebuilds the
+// same managed block instead of stacking a second one. A command with no marker is not wired — the
+// whole string becomes the base to wrap.
+export function parseCommand(command: string | undefined): ParsedCommand {
+	if (!command?.includes(MARKER_BEGIN)) return { wired: false }
+	const modeMatch = new RegExp(`${MODE_PREFIX}(own-line|same-line)`).exec(command)
+	const origMatch = /__sdd_orig\(\) \{\n([\s\S]*?)\n\}/.exec(command)
+	const mode = (modeMatch?.[1] as StatusLineMode | undefined) ?? 'own-line'
+	const origBody = origMatch?.[1] ?? NO_BASE
+	return { wired: true, base: origBody === NO_BASE ? undefined : origBody, mode }
+}
+
+// The command to wrap as `base` when composing: an already-wired command hands back its recovered
+// original base (never nests); any other command is the base verbatim.
+function baseToWrap(existingCommand: string | undefined): string | undefined {
+	const parsed = parseCommand(existingCommand)
+	return parsed.wired ? parsed.base : existingCommand
+}
+
+// ── project settings.json ──
+
+interface StatusLineConfig {
+	type: string
+	command: string
+	[key: string]: unknown
+}
+
+interface Settings {
+	statusLine?: StatusLineConfig
+	[key: string]: unknown
+}
+
+function readSettingsFile(file: string): Settings {
+	if (!existsSync(file)) return {}
+	try {
+		return JSON.parse(readFileSync(file, 'utf8')) as Settings
+	} catch {
+		return {}
+	}
+}
+
+function readSettings(root: string): Settings {
+	return readSettingsFile(join(root, SETTINGS_FILE))
+}
+
+// Read a settings JSON file's statusLine.command, read-only. Absent file, unparseable JSON, or a
+// missing/non-string/blank command all collapse to undefined — a malformed global settings file is
+// treated the same as no global statusLine (frozen scenario).
+export function readStatusLineCommand(file: string): string | undefined {
+	const settings = readSettingsFile(file)
+	const command = settings.statusLine?.command
+	if (typeof command !== 'string' || command.trim() === '') return undefined
+	return command
+}
+
+function writeSettings(root: string, settings: Settings): void {
+	const file = join(root, SETTINGS_FILE)
+	mkdirSync(dirname(file), { recursive: true })
+	writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`)
+}
+
+export interface ComposeResult {
+	changed: boolean
+	command: string
+	globalBaseComposed: boolean
+}
+
+// Compose the SDD statusLine segment into project settings.json. Preserves any existing statusLine
+// command's output as the wrapped base (never overwrites it); creates the key when absent. Rewiring
+// the same mode over an already-wired command is a no-op (byte-identical command).
+//
+// Base selection: when the project settings define no usable `statusLine` command (the same
+// predicate detectStatusLines reports as `absent`), this is a fresh wire — the base is
+// `globalCommand` (possibly undefined). When a usable project `statusLine` already exists (foreign
+// or already wired), today's behavior is unchanged — the existing command's recovered base is used
+// and `globalCommand` is ignored entirely, so a re-run never re-consults or adopts the global.
+export function composeStatusLine(root: string, mode: StatusLineMode, globalCommand?: string): ComposeResult {
+	const settings = readSettings(root)
+	const existing = settings.statusLine?.command
+	const hasProjectStatusLine = typeof existing === 'string' && existing.trim() !== ''
+	const globalBaseComposed = !hasProjectStatusLine && globalCommand !== undefined
+	const base = hasProjectStatusLine ? baseToWrap(existing) : globalCommand
+	const command = buildCommand(base, mode)
+	if (existing === command) return { changed: false, command, globalBaseComposed: false }
+	settings.statusLine = { ...settings.statusLine, type: 'command', command }
+	writeSettings(root, settings)
+	return { changed: true, command, globalBaseComposed }
+}
+
+// ── .gitignore ──
+
+export function isGitRepo(root: string): boolean {
+	return existsSync(join(root, '.git'))
+}
+
+function splitLines(text: string): string[] {
+	const lines = text.split('\n')
+	if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+	return lines
+}
+
+// Idempotently add the status file to .gitignore (creating it if absent). Only called when the root
+// is a git repo; a no-op when the entry is already present.
+export function addGitignoreEntry(root: string): { changed: boolean } {
+	const file = join(root, GITIGNORE_FILE)
+	const lines = existsSync(file) ? splitLines(readFileSync(file, 'utf8')) : []
+	if (lines.some((l) => l.trim() === STATUS_FILE)) return { changed: false }
+	const next = [...lines, STATUS_FILE]
+	writeFileSync(file, `${next.join('\n')}\n`)
+	return { changed: true }
+}
+
+// ── global statusline detection ──
+
+export interface DetectResult {
+	project: 'absent' | 'wired' | 'foreign'
+	global: 'absent' | 'present'
+	shadow: boolean
+}
+
+// Read-only: report the project statusLine state, the global statusLine state, and whether wiring
+// would shadow a global statusLine that is currently rendering (project has none, global has one).
+// Never writes anything — used to surface the shadow risk before wiring and by `--detect`.
+export function detectStatusLines(root: string, globalSettingsFile?: string): DetectResult {
+	const projectCommand = readStatusLineCommand(join(root, SETTINGS_FILE))
+	const project = projectCommand === undefined ? 'absent' : parseCommand(projectCommand).wired ? 'wired' : 'foreign'
+	const global = readStatusLineCommand(globalSettingsFile ?? GLOBAL_SETTINGS_FILE) !== undefined ? 'present' : 'absent'
+	const shadow = project === 'absent' && global === 'present'
+	return { project, global, shadow }
+}
+
+// ── top-level wire ──
+
+export interface WireResult {
+	settings: ComposeResult
+	gitignore: { changed: boolean; skipped: boolean }
+}
+
+export interface WireOptions {
+	globalSettingsFile?: string
+	globalBase?: boolean
+}
+
+// Wire the reader into project settings and (only in a git repo) gitignore the status file. The
+// single entry point init's SKILL.md calls on consent. `globalBase` (default true) controls whether
+// a fresh wire composes the global statusLine command as the base; `globalSettingsFile` overrides
+// the default global settings path (for tests, or a non-default HOME).
+export function wireStatusline(root: string, mode: StatusLineMode, opts?: WireOptions): WireResult {
+	const globalBase = opts?.globalBase ?? true
+	const globalCommand = globalBase ? readStatusLineCommand(opts?.globalSettingsFile ?? GLOBAL_SETTINGS_FILE) : undefined
+	const settings = composeStatusLine(root, mode, globalCommand)
+	const gitignore = isGitRepo(root) ? { ...addGitignoreEntry(root), skipped: false } : { changed: false, skipped: true }
+	return { settings, gitignore }
+}
+
+// ── CLI ──
+
+function flag(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name)
+	return i === -1 ? undefined : argv[i + 1]
+}
+
+export function main(argv: string[]): number {
+	const root = flag(argv, '--root') ?? '.'
+	const globalSettingsFile = flag(argv, '--global-settings')
+	const w = (s: string) => process.stdout.write(`${s}\n`)
+
+	if (argv.includes('--detect')) {
+		const result = detectStatusLines(root, globalSettingsFile)
+		w(`project statusLine: ${result.project}`)
+		w(`global statusLine: ${result.global}`)
+		w(
+			result.shadow
+				? 'shadow risk: yes — wiring would shadow the global statusline; compose it as the base (default) or pass --no-global-base to shadow deliberately'
+				: 'shadow risk: no',
+		)
+		return 0
+	}
+
+	if (argv.includes('--wire')) {
+		const mode = flag(argv, '--mode')
+		if (mode !== 'own-line' && mode !== 'same-line') {
+			w('refused: --mode must be own-line or same-line')
+			return 1
+		}
+		const globalBase = !argv.includes('--no-global-base')
+		const result = wireStatusline(root, mode, { globalSettingsFile, globalBase })
+		w(result.settings.changed ? `wired statusLine (${mode})` : 'statusLine already wired (unchanged)')
+		if (result.settings.globalBaseComposed) w('composed the global statusLine command as the wrapped base')
+		if (result.gitignore.skipped) w('not a git repo — gitignore skipped')
+		else w(result.gitignore.changed ? `added ${STATUS_FILE} to .gitignore` : '.gitignore already up to date')
+		return 0
+	}
+
+	w(
+		'usage: wire-statusline --root <dir> --wire --mode own-line|same-line [--global-settings <file>] [--no-global-base]\n' +
+			'       wire-statusline --root <dir> --detect [--global-settings <file>]',
+	)
+	return 0
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

package/skills/lifecycle-governance/README.md

@@ -0,0 +1,11 @@
+# lifecycle-governance
+
+Internal SDD governance (`user-invocable: false`). The **lifecycle** contract — the state machine a
+`spec.md` moves through: the root frontmatter schema, the `status` enum, the legal status
+transitions, open-marker gating, and the per-file freeze state-transition.
+
+A fixed-universal SDD governance, invariant per role (not face-split). Loaded by `sdd`,
+`spec-gate`, `start-mission`, the conductor, and the spec-judge. Write-ownership of these fields
+lives in `ownership-governance`; legality of field combinations and gate verdicts in
+`gate-validation-governance`; the ledger shape in `combat-log-governance`. Not triggered by users
+directly.

package/skills/lifecycle-governance/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: lifecycle-governance
+description: "Partial Skill: invoke by name only — the SDD spec lifecycle contract. Loaded by sdd, spec-gate, start-mission, the conductor, and the spec-judge, not user-triggered."
+user-invocable: false
+---
+
+# SDD Lifecycle Governance
+
+The state machine a `spec.md` moves through, and the frontmatter that records it. This skill is the
+canonical home consumers load instead of restating it. Write-ownership of these fields lives in
+`sdd:ownership-governance`; legality of field combinations and gate verdicts in
+`sdd:gate-validation-governance`; the ledger shape in `sdd:combat-log-governance`.
+
+## Frontmatter schema
+
+The **root** `spec.md` carries YAML frontmatter:
+
+```yaml
+---
+status: draft           # draft | approved | implemented | deprecated
+project-path: plugins/sdd   # repo-relative source dir this spec governs; the location mode is derivable
+name: SDD               # OPTIONAL declared project name; authoritative for name→spec resolution
+approval:               # per-gate verdict
+  spec:                 # verdict: approve | pause | reject
+    verdict: approve
+    by: agent           # agent (self-asserted, provisional) | <human name> (ratified); omitted on pause
+    cause: dimension    # dimension | ceiling — what drove the verdict
+    why:                # verdict derivation (agent self-assertion or pause)
+      floor:       <none | clearance | conflict | compatibility | consent>
+      blast:       <low|high — reason>
+      novelty:     <low|high — reason>
+      confidence:  <low|high — reason>
+  impl: { verdict: approve, by: <human name> }   # ratified — no why needed
+produced-by:            # who produced each artifact; see sdd:combat-log-governance
+  spec-producer: <plugin>:<agent>
+---
+```
+
+Open input is recorded in the body as `<!-- open: ... -->` markers, not in frontmatter.
+
+The frontmatter is the **router's upfront index** (ADR-0017): the gateway scans every spec at the
+three SDD spec locations, frontmatter only (no bodies), to route, so it carries only what routing
+needs. `status` is the base schema;
+`project-path`, `approval`, and `produced-by` are the SDD-workflow additions. `project-path` records
+the repo-relative source dir the spec governs; the spec **location mode** (`colocated | hoisted |
+monorepo-member`) is *derived* from it (hoisted iff `project-path` is not the spec's own dir), never
+stored. There is **no `aligned`, `spec-layout`, or run-level `leash` field** — sync is derived
+(below), the organization strategy is declared in the body placement map, and the leash is
+session-local on the ledger/plan (the conductor's autonomy bar, `start-mission`).
+
+**A file's artifact-type is resolved per file, never stored here.** Each file's artifact-type (the
+squad key) resolves its own squad against the project's registered plugins
+(`sdd:plugin-contract-governance`); the conductor classifies it by convention, falling back to the
+optional `.agents/sdd/artifact-types.toml` tiebreaker on ambiguity. The contested-type →
+chosen-plugin disambiguation lives in `.agents/sdd/` resolution state, **distinct from
+`produced-by`**, never a frontmatter field. The project carries no root `artifact-types` summary.
+
+**This whole frontmatter is root-`spec.md`-only.** A capability node README (a `reference` or
+`behavioral` spec — `sdd:spec-format-governance`) carries **only** its `spec-type` marker, never a
+lifecycle field. Folders are views, never lifecycle units: the project has **one** lifecycle, on the
+root.
+
+## Spec discovery
+
+A spec is **location-bounded and shape-confirmed** (ADR-0017): an SDD spec is a git-tracked
+`spec.md` that sits at one of the three fixed SDD spec locations — **or** at an extra anchor the
+project declared (ADR-0019) — **and** whose frontmatter `status` is one of the enum values below:
+
+1. `.agents/spec/spec.md` — repo-root single-project
+2. `.agents/specs/<project>/spec.md` — repo-root multi-project
+3. `<project-path>/.agents/spec/spec.md` — a nested project (the `**` is the project-path, any depth)
+4. any extra anchor declared in `.agents/sdd/spec-anchors.toml` — **opt-in and additive**; absent
+   config ⇒ only 1–3 (today's behavior). The three fixed conventions need no registry; the extra
+   anchors are a declared, curated registry (`manage-spec-anchors`), not a derived hot path.
+
+To locate specs, scan the fixed conventions (plus any declared extra anchors) and keep git-tracked
+files whose `status` is in the enum. A `spec.md` at a recognized location with no lifecycle `status`
+is **not** a spec (so a stray file is never grabbed by accident); a status-bearing `spec.md` at
+neither a fixed convention nor a declared extra anchor is not a spec either. An unreadable/malformed
+`spec-anchors.toml` is ignored (fall back to the fixed conventions). The concrete engine is the
+`discover-specs` skill (frontmatter only, TOON output).
+
+Each spec carries a **project name** so a consumer can resolve a name → spec. The name is `declared`
+(the optional frontmatter `name`, authoritative), else `derived` (the repo-root single-project →
+`repo`; a `.agents/specs/<project>` folder names itself), else `guessed` (a nested project's folder
+basename — confirm with the user). The optional `name` field is **written at spec creation**
+(`sdd:scaffold-project-spec`) — it earns its router slot because the gateway presents project names
+to the user; it is required in practice only for a nested project whose folder is not the user's name.
+
+**Sync is derived, not stored (no `aligned` flag).** "Synced" is two properties, each derived or
+judged (ADR-0017): contract-sync (`spec.md` ↔ `.feature`) is *judged* at the spec gate (Builder
+coverage lens); impl-sync is the impl gate's *runtime suite run* (advance to `implemented` only when
+every impl-judge passes); per-node settled state is the **`@frozen`** scan; what is in flux now is the
+`.plan.md` todos. Do not commit SDD artifacts while a touched `.feature` is unfrozen or the plan's
+todos are incomplete.
+
+## Status enum
+
+| Status | Meaning |
+|---|---|
+| `draft` | Contract can still evolve; not yet implementable as a fixed bar |
+| `approved` | Contract is frozen; ready to implement against |
+| `implemented` | Implementation passed the impl gate |
+| `deprecated` | Historical spec only; not implementable work |
+
+## Status transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> draft: start-mission (new or backfill)
+    draft --> approved: spec gate (spec-gate --target spec)
+    approved --> implemented: impl gate (spec-gate --target impl)
+    approved --> draft: behavior change (re-open)
+    implemented --> draft: behavior change (re-open)
+    draft --> deprecated: Oracle-lens kill (scope)
+    approved --> deprecated
+    implemented --> deprecated
+```
+
+- **Draft → Approved** is the **spec gate**: judges `spec.md` + the `.feature`.
+- **Approved → Implemented** is the **impl gate**: judges the implementation against the frozen `.feature`.
+- A behavior change after approval is **not** a direct edit — revert to `draft` and re-pass the spec
+  gate. Re-open is a lightweight "change needed" flag an auditor sets; only re-approval is the heavy
+  positional act.
+- Deprecation retains the spec as a historical record; never treat it as implementable.
+
+## Freeze (per suite file)
+
+Reaching a spec-gate `approve` **freezes** the `.feature` files the CR *touched* — each via its own
+feature-level **`@frozen` tag** (set/cleared per file; the vocabulary is **freeze / unfreeze**, never
+lock/unlock — lock is the concurrency layer, `cr-concurrency`). Files the CR did not touch keep
+whatever state they held. "Which scenarios are the frozen contract" is answered by the set of
+`@frozen` files — a plain per-file flag, no computed baseline. The `@frozen` tag is metadata,
+excluded from the content the freeze protects; toggling it is not a scenario edit. The matching
+write constraint ("never write a frozen `.feature`") is in `sdd:ownership-governance`.
+
+- **The unfreeze trigger is risk, not phase.** *Narrowing or rewriting* a scenario unfreezes its
+  file (in explore or deliver alike) — at the gate that is **Clearance** (the conductor's autonomy
+  bar, `start-mission`), contract narrowed → escalate. An *additive* scenario never unfreezes its file:
+  it widens the contract, cannot break existing impl, and **self-clears** — folding into the frozen
+  file under the conductor's authority, logged as a detail-adjustment.
+- **A pure move/rename preserves the freeze.** What a freeze protects is the scenario **content**,
+  not where the file sits. A *pure rename* — a `git mv` with **zero content delta** (a git `R100`) —
+  does **not** unfreeze the file and is **not** a gate-able edit; it stays `@frozen` at the same
+  baseline. This is what lets **placement be finalized at handoff** (`design/spec-layout.md`): a node
+  may be relocated to its blessed home in the same change without re-opening its contract. Only a
+  *content* change (the narrowing/rewriting trigger above) unfreezes.
+- **`spec.md` is kept in sync, never frozen** — the readable abstraction of the suite, free to be
+  reworded/restructured as long as it does not contradict a frozen scenario. Enforced by the
+  spec-judge applying the Builder (coverage) lens, not by freezing the prose.
+- **The ledger is never frozen and never gated** — it keeps appending across the whole lifecycle,
+  including while files sit `@frozen` (`sdd:combat-log-governance`).
+- **Spec owns behavior.** If the implementation disagrees with `spec.md`, the implementation is
+  wrong — fix it, or unfreeze the relevant file for a new cycle. The **impl gate** is the only place
+  a frozen file reopens — via the Oracle-lens revert (building proved the contract wrong). Rare
+  and deliberate.
+
+**Two modes.** Before a file's freeze, exploration may update `spec.md`, that `.feature`, the plan
+(brief + ordered `todos`), and spikes. After it freezes, implementation proceeds against it; every
+frozen scenario must pass the full impl-gate run before `implemented`.
+
+## Open-marker gating
+
+Missing contributor input is recorded as `<!-- open: ... -->` in the owning artifact. Open markers
+must be resolved (count = 0) before a spec may advance to `approved`; they are permitted at `draft`
+(markers block only the *gate*, not the draft state). `sdd:gate-validation-governance` defines how
+markers interact with legal state; producers emit gaps that the conductor turns into markers
+(`sdd:ownership-governance`).

package/skills/manage/README.md

@@ -0,0 +1,9 @@
+# manage
+
+The user-facing entry for **manage-level (non-mission) work** on an SDD project — the handler for the gateway's **"Manage the corpus"** route, sibling to `start-mission`. Where `start-mission` **changes what the project specifies**, `manage` does non-mission work on the corpus: **setup & discovery**, **inspect**, **audit & align**, **housekeeping**.
+
+User-invocable. A **thin dispatcher** (the in-session realization of the manage unit): it classifies a manage request and **loads the matching engine in the current session**, holding no production logic, loading no governance, and writing no contract state.
+
+Bakes in: two-level intake (fast path when the operation is named; a four-group menu when bare, within the four-option rule); the group→engine routing table (Setup & discovery → `scaffold-project-spec` / `manage-spec-anchors`; Inspect → `discover-specs` / `concept-index` / `place-node` / `discover-plans`; Audit & align → `check-spec-structure` / `formation-loop` / `align-spec` (planned); Housekeeping → `plan-retirement`); loading the engine in-session (read-only engines run in place, write-capable ones stay owned by their engine); and the non-mission boundary — opens no CR, invokes no gate, writes no `status`/`approval`, and **hands a behavior change off to `start-mission`**. Reviewing pending strategy stays gateway-owned, not a manage operation.
+
+Pairs with the `sdd` gateway (which routes its option-2 here) and `start-mission` (which manage hands off to when an operation needs a real behavior change).

package/skills/manage/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: manage
+description: Use this skill when doing manage-level (non-mission) SDD work on the spec corpus — bootstrap, inspect, audit, or housekeeping — such as "set up the project spec", "backfill the spec", "list the SDD specs and statuses", "audit the corpus structure", "check for spec/suite drift", or "retire completed mission plans". Routes to the matching engine; it does not change what the project specifies (that is start-mission).
+---
+
+# manage
+
+The **manage-level** front door to an SDD project — the user-facing handler for the gateway's **"Manage the corpus"** route, sibling to `start-mission`. Where `start-mission` **changes what the project specifies** (opens a CR, runs the mission loop), `manage` does **non-mission** work on the corpus: **bootstrap**, **inspect**, **audit**, **housekeeping**.
+
+`manage` is a **thin dispatcher**: it classifies a manage request and **loads the matching engine in the current session**, holding **no production logic**, loading **no governance**, and writing **no contract state**. It **opens no CR**, **invokes no gate**, and **performs no behavior change** itself — a needed change to the project's specified behavior is **handed off to `start-mission`**.
+
+> **Manage picks no model.** Like the gateway, the model + effort a piece of work needs is set by the **engine you load** — the `.mts` engines are light; a `backfill` or `formation` grill wants a capable model. The loaded engine advises; the user switches manually. (Harness gap: `manage` cannot switch the session model itself.)
+
+## Intake
+
+- **Fast path — skip the menu.** When the invocation already **names the operation** — "backfill the project spec", "list the specs", "check spec structure", "retire the finished plans" — load the matching engine directly, no menu.
+- **Two-level menu — bare invocation.** When `manage` is invoked with **no operation named**, 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 the **four operation groups**; the second level picks the specific engine.
+
+| # | Operation group | Covers |
+|---|---|---|
+| 1 | **Setup & discovery** | scaffold a project's spec envelope for the first time → `scaffold-project-spec`; curate discovery's extra spec anchors → `manage-spec-anchors`; curate the ignore file → `manage-ignore`; wire a project's scenario bridge → `manage-scenario-bridge`; set up or configure the mission statusline → `init` (all are prerequisites for a project being found and usable, not routine cleanup) |
+| 2 | **Inspect** | list / navigate the corpus → `discover-specs`, `concept-index`, `place-node`, `discover-plans` |
+| 3 | **Audit & align** | audit node-shape, drift, structure → `check-spec-structure`, `formation-loop`, `align-spec` *(planned)*; scan plan briefs for machine-local path leaks → `check-plan-safety` |
+| 4 | **Housekeeping** | retire completed mission plans → `plan-retirement` |
+
+When a group's engine list would exceed four at the second level, present only the most-relevant few (≤ 4) or ask the user to name the engine directly; never enumerate into an over-four question and never truncate silently.
+
+## The routing table — group → engine
+
+Classification routes a manage request to the **handler** that handles it; every handler already exists and is loaded here — most are `user-invocable: false` engines, except `init`, which stays independently user-invocable.
+
+| Group | Request | Engine (handler) |
+|---|---|---|
+| **Setup & discovery** | set up / backfill a project's spec for the first time | **`scaffold-project-spec`** — scaffolds the spec envelope + stub nodes |
+| **Setup & discovery** | list / change discovery's extra spec anchors | **`manage-spec-anchors`** — list fixed + custom anchors, CRUD the custom ones, induce a pattern from a path, preview its match (writes only `.agents/sdd/spec-anchors.toml`) |
+| **Setup & discovery** | curate the ignore file | **`manage-ignore`** — curate `.agents/sdd/.sddignore` (list / add / remove / induce / preview); writes only the ignore file |
+| **Setup & discovery** | scaffold or curate a project's scenario-bridge config | **`manage-scenario-bridge`** — list / scaffold / add sources in `<project-path>/.agents/sdd/scenario-bridge.toml`; writes only that project's scenario-bridge config |
+| **Setup & discovery** | set up / configure the mission statusline | **`init`** — user-invocable onboarding skill; offers the opt-in statusline, wires the reader into project `.claude/settings.json` |
+| **Inspect** | list the specs + statuses | **`discover-specs`** — frontmatter-only corpus scan |
+| **Inspect** | render / refresh the by-concept view | **`concept-index`** — `--check` (read) / `--write` (refresh block) |
+| **Inspect** | where does a new concept belong | **`place-node`** — provisional home + duplicate catch |
+| **Inspect** | list in-progress (resumable) missions | **`discover-plans`** — plan-brief scan |
+| **Audit & align** | audit node-shape (orphans / oversized) | **`check-spec-structure`** — read-only advisory |
+| **Audit & align** | scan plan briefs for machine-local path leaks | **`check-plan-safety`** — read-only guard; flags home-abs paths + `$HOME`/`$USER` in `.agents/plans` |
+| **Audit & align** | reconcile prose↔suite drift | **`align-spec`** *(planned — spec-only, no engine yet)* — a fix that edits behavior **hands off to `start-mission`** |
+| **Audit & align** | corpus-wide audit / split / reconcile | **`formation-loop`** — emits new CRs (→ `start-mission`) |
+| **Housekeeping** | retire completed mission plans | **`plan-retirement`** — gated, idempotent deletion of retired briefs |
+
+Reviewing **pending strategy** is **not** a manage operation — it stays **gateway-owned** (the gateway's episodic pending-count, its option 3). `manage` does not surface or ratify strategy.
+
+## Load the engine in-session
+
+When the route resolves, **load the matched engine in the current session** and run it directly — **spawn nothing**. Read-only engines (`discover-specs`, `discover-plans`, `check-spec-structure`, `check-plan-safety`, `place-node`, `concept-index --check`) run in place; **write-capable** operations stay **owned by their engine** — `scaffold-project-spec` scaffolds the skeleton, `plan-retirement` performs its gated deletion, `concept-index --write` refreshes the generated block, `manage-spec-anchors` writes its `spec-anchors.toml` config, `manage-scenario-bridge` writes its project's `scenario-bridge.toml` config. `manage` only routes.
+
+## Non-mission — the boundary
+
+`manage` maintains and inspects the corpus; it **never changes what the project specifies**.
+
+- **Opens no CR, invokes no gate, writes no `status` / `approval`.** Those belong to `start-mission` and the internal gates.
+- **Hand off a behavior change.** When an operation surfaces a needed change to the project's specified behavior — a `formation` reconcile, an `align-spec` drift whose fix edits the spec/suite — **hand off to `start-mission`**, which opens a CR and runs the mission loop. Do not edit the spec/suite here.
+- **A change request is not a manage operation.** A request to **add or revise** the project's specified behavior is **redirected to `start-mission`**, not handled as a manage operation.
+- **Thin classifier.** Classifying loads **no governance** and holds **no production logic** — it only loads the matched engine.

package/skills/manage-ignore/README.md

@@ -0,0 +1,19 @@
+# manage-ignore
+
+The concrete engine for `.agents/sdd/.sddignore` — the optional gitignore-syntax file
+`resolve-tracking` reads to decide whether an artifact is tracked or ignored. A non-user-invocable
+skill, loaded in-session by the `manage` gateway (Housekeeping), carrying a self-contained `.mts`
+script that lists / adds / removes / induces / previews the ignore rules so users never hand-edit the
+file. Order is meaningful (last-match-wins), so rules are never re-sorted.
+
+- **Skill contract:** [`SKILL.md`](./SKILL.md)
+- **Script:** [`scripts/manage-ignore.mts`](./scripts/manage-ignore.mts)
+- **Tests:** [`scripts/manage-ignore.test.mts`](./scripts/manage-ignore.test.mts) (`node:test`)
+
+```bash
+node scripts/manage-ignore.mts --list
+node scripts/manage-ignore.mts --induce build/output/app.log
+node scripts/manage-ignore.mts --preview '*.log'
+node scripts/manage-ignore.mts --preview '!keep.log'
+node scripts/manage-ignore.mts --add '*.log'
+```

package/skills/manage-ignore/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: manage-ignore
+description: "Partial Skill: invoke by name only — intake/manage-ignore's curation engine for the SDD ignore rules — loaded by the manage gateway (Housekeeping), not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Manage Ignore
+
+The concrete engine for `.agents/sdd/.sddignore` — the optional gitignore-syntax file
+`resolve-tracking` consults to decide whether an artifact is **tracked** or **ignored**. It is the
+**write** side of the ignore file (`resolve-tracking` is the read side). It exists so a user curates
+the ignore rules through a clean interface instead of hand-editing the file. Loaded **in-session** by
+the `manage` gateway (Housekeeping group); it carries a self-contained `.mts` script (the repo's
+node-≥23.6 / no-deps convention).
+
+## The file it curates
+
+`.agents/sdd/.sddignore` is plain **gitignore syntax**: a bare pattern **ignores**, a leading `!`
+**re-includes** (re-tracks), `#` comments and blank lines are allowed. Order is **meaningful** —
+`.sddignore` is **last-match-wins**, so a later `!rule` re-tracks a path an earlier rule ignored. The
+engine therefore **never re-sorts**: `--add` appends, `--remove` preserves the order of the survivors.
+
+## Run an operation
+
+```bash
+node "<skill>/scripts/manage-ignore.mts" [--root .] <operation>
+```
+
+| Operation | Effect |
+|---|---|
+| `--list` | print every rule in file order (comments/blanks omitted); a missing file prints nothing, no error |
+| `--add <pattern>` | validate + append a well-formed rule (creates the file if absent); a malformed pattern is refused (file unchanged, nonzero exit) |
+| `--remove <pattern>` | drop the matching rule, keeping the order of the rest; removing an absent rule is a no-op (file byte-for-byte unchanged) |
+| `--induce <path>` | from a sample repo-relative path, offer a literal-path candidate and a `**/<basename>` generalization; persists nothing; refuses a path not under the repo |
+| `--preview <pattern>` | list the working-tree paths the candidate would **ignore** (or, for a `!pattern`, the paths it would **re-track**), without persisting it; a malformed pattern is refused |
+
+**Curate with preview.** The intended flow: take the user's sample path → `--induce` it → `--preview`
+each candidate to show the affected paths → confirm with the user → `--add` the chosen rule. Never
+write a rule the user has not seen the effect of.
+
+## Boundaries
+
+Writes **only** `.agents/sdd/.sddignore` — never a `spec.md`, `status`, `approval`, or a freeze; it is
+operational config, not spec content (so `manage`'s write-ownership guard holds). It does **not**
+resolve an artifact's tracking signal — that is `resolve-tracking`, which *reads* this file. The
+**read-side** fail-safe (an already-corrupted file never breaks intake) is `resolve-tracking`'s
+guarantee; this engine validates on the **write** side so a malformed pattern is never persisted.
+
+When `node` is absent, an agent performs the same edits by hand: read the file, apply the CRUD,
+validate a line is a well-formed gitignore pattern, and preserve rule order (never re-sort).