cyber-sdd 0.0.0

package/skills/formation-loop/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: formation-loop
+description: "Partial Skill: invoke by name only — the SDD formation loop, the Architect's outer loop run by the Warden — invoked by the formation-loop delegate, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# SDD Formation Loop
+
+The **structure outer loop** of the SDD model. Owned by the **Architect** and run by its delegate,
+the **Warden** (`sdd-warden`), parallel to the conductor running the mission loop. It fires
+**post-mission**, **corpus-wide and continuous**, and asks one question and only one — **is what we
+have organized right?** Its standing subject is `corpus/` + `project-spec/` and the whole organization: it evolves how
+the corpus is **arranged**, never what it says.
+
+Load `sdd:combat-log-governance` for any provenance it touches; the floor + gradient the Warden
+renders its per-act verdict against are the conductor's autonomy bar (`start-mission`) — this skill
+defers both and never restates them.
+
+## Corpus-wide, never the per-spec gate
+
+This is the load-bearing distinction. The Architect appears in **two** places that must never be
+conflated:
+
+| | **Formation loop** (this skill) | **The gate's Architect-backward face** |
+|---|---|---|
+| Scope | the **whole corpus** | **one spec** |
+| Cadence | **continuous**, across missions | **point-in-time**, at one spec's gate |
+| Question | is the corpus **organized** right? | does **this change** fit structurally? |
+| Acts | audit node-shape, split, reconcile | one approve/pause/reject structural verdict |
+
+Every run produces a **finding set covering every spec in the corpus**; a structural pass scoped to
+one spec is **not** a formation run. When asked to act as the per-spec gate structural check, the
+loop **declines** and renders no per-spec gate verdict.
+
+## Input — corpus structure + discovery, never the combat log
+
+The Warden reads what the corpus **is**, never what a mission **did**. Its **primary** input is
+structural: the corpus **structure** and **discovery** (`corpus/` + `project-spec/`). To stay efficient rather than
+cold-scanning the whole corpus every run, it may consult the durable **public trail** (CR-source
+conclusions + changesets + git history) **forward** via a cursor to learn what shipped recently and
+prioritize the structural pass there first. It reads **never** the combat log (the doctrine loop's
+input, retired at retro) and **never** live subagent context — like the other outer loops it fires
+strictly post-mission.
+
+**Read the declared strategy before judging.** Each project spec's root `spec.md` carries a
+**placement map** naming the layout strategy it chose (`capability-first | mirror-source | …`). Read
+it and judge structural fit **against that**, never against a default: a project that declared
+`mirror-source` is not misplaced for mirroring its source tree. **Never infer the strategy from the
+tree** — that makes the audit circular (the shape the corpus has becomes the standard it is judged
+by) and, on a half-migrated corpus, judges it against the layout it is migrating away from. A map
+naming no strategy is judged against the **capability-first** default, and the missing declaration
+is itself a finding. **Read the map's routing table too, not only its strategy:** a node placed by an
+explicit routing-table row (the "concept of kind K lives in home H" taxonomy and its tie-breaks) is
+correctly placed even where the strategy's own derivation would put it elsewhere, so report a node
+misplaced only when it **neither** follows the declared strategy **nor** matches a routing-table row
+— judging on the strategy alone raises false findings against placements a human already adjudicated. A declared layout settles *where a node goes*; it never licenses a capability to
+scatter across nodes. (Strategy is policy — read it; homes are data — derive them.)
+
+## The intra-spec structural acts
+
+It acts on each spec's **structure**, not its content — one project is **one spec**, so structural
+maintenance is **intra-spec**. A station is **not** a dependency — formation depends on the corpus
+structure and discovery (`corpus/` + `project-spec/`), not on any given station skill.
+
+| Act | Trigger | Station (`corpus/` + `project-spec/`) | Output |
+|---|---|---|---|
+| **Audit node-shape** | a formation pass fires post-mission | `check-spec-structure` | a finding set: untagged-node (blocking) + oversized-node (advisory), each naming the node |
+| **Split an oversized node** | the Warden's `@rubric` breadth-vs-depth judgment routes an oversized-node's shape profile to breadth-overflow | `check-spec-structure` | a sub-node split; depth-overflow instead down-levels via the scenario→test bridge (`verify-scenarios`) or is redesigned — the engine emits only the profile, never the route |
+| **Reconcile drift / contradiction** | prose↔suite drift, or two nodes contradict | `align-spec` | a reconcile finding (drift fixed by direction; contradiction → align the losing side) |
+| **Dedupe cross-node scenario overlap** | the same behavior is specified in two nodes' suites — a hard collision the scenario rung cannot see (spec-level SSA) | `check-scenario-overlap` | a dedup finding naming both nodes; the Warden's `@rubric` arm confirms real overlap and **assigns a single owning node** (one behavior = one scenario in one node) |
+
+A node **within** the granularity heuristic raises **no** oversized finding; a concept-tagged node
+raises **no** untagged finding; nodes (or governances) that **agree** raise **no** reconcile finding;
+two nodes that specify **no** shared behavior raise **no** dedup finding. The acts are evidence-gated,
+not run unconditionally.
+
+Alongside its findings a pass surfaces an **advisory layout-quality signal** — the scheduler's
+**false-conflict rate** doubles as a **partition-quality metric**: a layout that keeps node↔folder
+clean holds the rate low, and one that scatters a single concern across folders drives it up. Read
+the signal **against the strategy the project declared** — a high rate under `mirror-source` means the
+source tree itself scatters the concern, which is a different finding from a capability-first spec
+drifting toward layers. But the rate measures the same thing either way: **node <-> capability
+alignment**, which the scheduler depends on and which no declaration suspends (ADR-0025). The signal
+is **advisory** — it **gates no mission**; it points the Warden and Council at a degrading partition
+so the **declared** layout can be re-asserted, or deliberately re-declared.
+
+**Measuring it, when a pass wants the number.** `sdd:check-partition-quality` computes this signal
+from the project's git history — the parallelizable share of change pairs under the declared layout,
+against a shuffled control, optionally compared with a candidate cut. **Opt-in**: it reads `git log`,
+so a pass runs it deliberately rather than every time, and its output is a measurement, never a
+verdict. Read its headline (the parallelizable share) and ignore its labelled diagnostics — both
+reward a coarser partition for being coarse.
+
+## The Warden's self-clear-vs-escalate verdict
+
+The Warden is **rubric-subject**, exactly as the conductor is at a gate, and has **no direct user
+channel**. For **each structural act** it applies the full floor + gradient
+(the conductor's autonomy bar, `start-mission`) — the floor (**Clearance** for a narrowing act; **Compatibility**
+when the act's semver class exceeds the ceiling; **Conflict** for a contested reconciliation) plus
+the gradient (**blast** magnitude, **novelty**, **confidence**) — and renders its own verdict:
+
+- **Self-clear** the reversible, derivable, low-blast acts — a coverage-preserving split, a refactor
+  or consistency fix. The Warden acts **in-session** and leaves a **provisional, agent-attributed
+  marker** that is never final until the Council ratifies the trail; a Council reject unwinds it.
+- **Escalate** the narrowing, contested, or class-exceeding acts. The escalated finding re-enters as
+  a **new CR** (`intake/`) naming the artifacts; it does not land until the Council ratifies.
+  - **narrowing** — a reconcile or split that drops scenarios → **Clearance**;
+  - **contested** — a reconciliation whose winning claim is contested → **Conflict**;
+  - **class-exceeding** — a structural change whose semver class exceeds the ceiling →
+    **Compatibility**;
+  - a **destructive** act (it deprecates a node) → **escalates regardless** of contract-impact
+    class.
+
+It is **not** true that every act is proposed-and-ratified: the reversible/derivable acts self-clear
+under the provisional marker; the narrowing/contested/class-exceeding ones emit a CR.
+
+## Stations, not status — and the frozen-contract guard
+
+The Warden runs stations in-session and **never** writes a spec's `status`. The frozen-contract
+guard is keyed on **contract impact**, not the bare fact that a `.feature` is frozen:
+
+- a split that **preserves every scenario verbatim narrows nothing** — it self-clears **even on a
+  frozen `.feature`**, leaving the provisional marker; no freeze re-open needed;
+- a split that **alters or drops scenario truth is a narrowing** — it shards a frozen contract only
+  with a Council-ratified freeze re-open;
+- a **deprecating act is destructive** — it **escalates regardless** of contract-impact class.
+
+## Altitude discipline — route, do not decide
+
+Formation owns corpus **structure** only and emits **no** out-of-loop decision:
+
+- a **build-or-deprecate** request → routed to `campaign/` (Product); it makes no
+  build-or-deprecate decision itself;
+- a **process lesson** → routed to `doctrine/` (Process); it emits no process edit itself;
+- a **per-spec gate structural check** → **declined**; formation does not run as the gate check.
+
+Cross-capability outcome scenarios (a split or reconcile carried end-to-end) live in
+`../workflows/`; the loop and verdict behaviors are in `formation/formation.feature`.

package/skills/gate-validation-governance/README.md

@@ -0,0 +1,12 @@
+# gate-validation-governance
+
+Internal SDD governance (`user-invocable: false`). The **gate-legality** contract — what makes a
+spec's state legal and how a gate records its verdict: the legal `(status, markers,
+.feature, approval)` tuples, the per-node `spec-type` checks, derived sync (no stored flag), approval
+attribution, and the no-resolvable-producer fail-closed rule.
+
+A fixed-universal SDD governance, invariant per role. Loaded by spec-gate, the conductor, and the
+spec-judge. It carries **no leash** — the self-clear-vs-escalate bar is the conductor's autonomy bar
+(baked into `start-mission`). The field schema/transitions are `sdd:lifecycle-governance`;
+write-ownership is `sdd:ownership-governance`; the mechanical authority is the `check-spec-state`
+script in `spec-gate`. Not triggered by users directly.

package/skills/gate-validation-governance/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: gate-validation-governance
+description: "Partial Skill: invoke by name only — the SDD gate-legality contract. Loaded by spec-gate, the conductor, and the spec-judge, not user-triggered."
+user-invocable: false
+---
+
+# SDD Gate-Validation Governance
+
+What makes a spec's state legal, and how a gate records its verdict. The field schema and transitions
+are in `sdd:lifecycle-governance`; this skill is the legality layer on top of them. It carries **no
+leash** — the self-clear-vs-escalate bar that derives how far an agent may self-assert is the
+conductor's autonomy bar (baked into `start-mission`), a hard floor + a three-dimension gradient.
+
+## Legal-state tuples
+
+The mechanical authority is `spec-gate/scripts/check-spec-state.mts` — run it
+(`node <skill>/scripts/check-spec-state.mts`) to enforce; if `node` is unavailable, apply the same
+rules by reading frontmatter. The `(status, markers, .feature, approval)` tuple of the root
+`spec.md` — plus the durable gate lines globbed from its sibling `ledger/` shards (a legacy `ledger.jsonl` still counts) — is **illegal** when:
+
+- `status: approved` with no `.feature` — a spec requires a frozen `.feature` to be approved.
+- `status: approved` or `implemented` with any `<!-- open: -->` markers — markers block the gate.
+- `approval` names a gate other than `spec` or `impl`.
+- an `approval.<gate>` has a `verdict` other than `approve`, `pause`, or `reject`.
+- an `approval.<gate>` is `verdict: pause` carrying a `by` — a pause is always the agent's act and omits `by`.
+- an `approval.<gate>` is `verdict: approve` with no `by` — an approve must record its approver.
+- an `approval.<gate>` is `by: agent` with no `why` block — a self-assertion must record its derivation.
+- an `approval.<gate>` has a `cause` other than `dimension` or `ceiling` — the stop cause is a closed enum.
+- an `approval.<gate>` is `verdict: pause` on a gate the spec has already passed (spec once `approved`/`implemented`, impl once `implemented`).
+- `status: approved` or `implemented` with no `approval.spec` `verdict: approve` + `by` — the spec gate has no recorded ratification.
+- `status: implemented` with no `approval.impl` `verdict: approve` + `by` — the impl gate has no recorded ratification.
+- `status: approved` or `implemented` with no `gate` line `gate: spec`, `verdict: approve` in the sibling `ledger/` shards — **the durable gate floor is missing**. The `approval` map is the overwritten current-state twin; the ledger line is the **immutable durable twin**, so a status advance with no ledger gate line is an unenforced gate.
+- `status: implemented` with no `gate` line `gate: impl`, `verdict: approve` in the ledger — the impl-gate durable floor is missing.
+
+`implemented` is backed by the impl gate's runtime suite run, not a stored flag (ADR-0017); its
+static guard here is the recorded `approval.impl` ratification. Open markers at `draft` are permitted
+(they block only the *gate*, not the draft state). A `draft` requires **no** ledger shard (no gate
+has run); the durable floor applies only once a gate has advanced the status.
+
+Reject illegal tuples **before** any other gate work. If `check-spec-state.mts` changes, this list
+follows it — the script is the source of truth, this prose is the readable mirror.
+
+## Per-node `spec-type` checks
+
+Same fail-closed class, enforced by the same helper. A capability node README's `spec-type` marker
+must agree with its shape (`sdd:spec-format-governance`):
+
+- `spec-type: reference` with a sibling `.feature` — illegal (a reference artifact is suite-less by design).
+- `spec-type: reference` with no `## Subject` section — illegal (the reference descriptor is required).
+- `spec-type: behavioral` with no `## Use Cases` section — illegal (a behavioral spec maps use cases to scenarios).
+- a node README carrying any **lifecycle field** (`status`, `project-path`, `approval`, `produced-by`,
+  or a retired `aligned` / `spec-layout` / `strategy`) — illegal: lifecycle frontmatter is
+  **root-`spec.md`-only** (`sdd:lifecycle-governance`); a node carries only its `spec-type` marker.
+
+## The two gates
+
+| Gate | Transition | Object judged |
+|---|---|---|
+| spec gate | Draft → Approved | `spec.md` + the `.feature` (no implementation required) |
+| impl gate | Approved → Implemented | the implementation vs the frozen `.feature` |
+
+`producer ≠ judge` survives the gate fold: even though gates are no longer a fixed station, the judge
+stays a distinct actor from the producer, and never patches what it grades.
+
+## Sync is derived, not stored (no `aligned` flag)
+
+There is no `aligned` field (ADR-0017). "Synced" is two properties at two layers, each derived or
+judged — never a stored boolean:
+
+- **Contract layer** (`spec.md` ↔ `.feature`) — **judged** at the spec gate by the Builder coverage
+  lens; implementation is not required, and spike code is excluded as scaffolding.
+- **Impl layer** (impl ↔ frozen `.feature`) — derived by **running the frozen suite**; the impl gate
+  advances to `implemented` only when **every** impl-judge passes, else it stays `approved` and
+  surfaces the blocker.
+- **Per-node settled state** is the **`@frozen`** scan; **what is in flux now** is the `.plan.md`
+  todos.
+
+`status` alone carries the lifecycle — no segment-level toggle.
+
+## No-resolvable-producer fails closed
+
+A required production role **always** resolves to a real producer — a plugin agent or the SDD default
+for that role. When a gate runs and a required role has **no resolvable producer** (not a plugin
+agent and not even an SDD default), the gate **fails closed** with a blocker; it advances nothing.
+This is a **structural** error, the same fail-closed class as a malformed `produced-by` entry or an
+off-enum `cause` (defined in `sdd:combat-log-governance`). Distinct from availability: a recorded
+producer whose plugin is merely uninstalled is **flagged**, not blocked.

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

@@ -0,0 +1,48 @@
+# impl-producer-governance
+
+This is an internal SDD governance about the default procedure for building an implementation.
+
+When a change request reaches the build phase and no plugin covers the domain, the conductor spawns
+a generic builder for the **impl-producer** role. This governance is the procedure that builder
+follows: read the frozen contract, build against it, author one verification per frozen scenario,
+and never touch the contract itself. It loads alongside the resolved **builder** and **architect**
+impl-gate bars (to self-align and to author the verification) and `ownership-governance` (who may
+write what). The grader stays separate: a cold impl-judge runs the verification this role authored —
+this role never declares its own pass.
+
+## What it requires — the procedure
+
+| Step | What it demands |
+| --- | --- |
+| **Read the contract** | Read the suite in full, `Given` steps included. In `implement` mode it is frozen — the fixed bar. In `explore` mode it is a draft — spike to probe it; a behavior the suite omits is reported as a `CONTENT_GAP`, never written into the spec or suite. |
+| **Build against the suite** | A `Given` is a test vector: conform to each scenario's `Then`, owe nothing to its `Given`'s apparatus. Draw illustrations from domains the suite does not probe; special-case no literal a `Given` names; self-check with the swap test. |
+| **Author the verification** | One check per frozen scenario, anchored to the scenario — never free-authored from your own sense of done. Prefer executing the frozen scenario directly, so the oracle stays spec-owned and only the glue is producer-authored. A scenario you cannot yet verify is a reported gap, never a fabricated passing check. |
+| **Verify as high as it doesn't hurt** | Pick each scenario's verification level to maximize confidence until cost, fragility, or feasibility bites: a cheap base, a thin e2e cap on the paths that matter, and boundary (the external mocked at its seam) as the honest substitute where e2e is infeasible or unsafe. Record the level and why. Where the domain has a deterministic inner layer, also cover its combinatorial space with unit tests — the pyramid's base, separate from the per-scenario duty. |
+| **Never modify the contract** | `spec.md` and the suite are off-limits (four-eyes). A behavior-changing gap is a `CONTENT_GAP` / `BLOCKER`, never an in-place edit. A `@pinned` scenario is never changed or removed without user authorization. |
+
+The builder reports back a structured output the conductor collects: status, artifacts written,
+verification written (one per frozen scenario, each with its level and why), content gaps, and
+observations routed to their owners.
+
+## Usage
+
+- **impl-producer (the spawned generic builder):** loaded via the harness when the conductor
+  dispatches the impl-producer role and no plugin covers the domain and no model-tuned producer is
+  named. This is a procedure the builder follows, not a bar graded at a gate — the grading happens
+  afterward, when the cold impl-judge runs the verification this procedure produced.
+
+## Related governances
+
+This governance owns *how the default builder works*. Its neighbors own the bars and contracts it
+works under:
+
+- **`builder-impl-governance`** — the Builder bar at the impl gate: does the implementation meet the
+  frozen contract. This procedure applies that bar; it does not define it.
+- **`architect-impl-governance`** — the Architect bar at the impl gate: structural fit of the
+  implementation. Same relation — applied here, defined there.
+- **`ownership-governance`** — the write-ownership matrix behind the never-edit-the-contract rule
+  and the `@pinned` authorization path.
+- **`suite-format-governance`** — how the `.feature` suite is written, including the
+  Given-is-a-test-vector doctrine this procedure builds under.
+
+Internal SDD governance (`user-invocable: false`). Not triggered by users directly.

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

@@ -0,0 +1,85 @@
+---
+name: impl-producer-governance
+description: "Partial Skill: invoke by name only"
+user-invocable: false
+---
+
+# Impl-Producer Governance — the default build procedure
+
+The procedure the **spawned builder** follows when the conductor runs the **impl-producer** role from
+the SDD default — no plugin covers the domain and no model-tuned producer is named, so the conductor
+spawns a generic builder that loads this and builds. Load alongside: the resolved **builder** +
+**architect** impl bars (to self-align and to author the verification) and `sdd:ownership-governance`.
+The grader is separate — a cold impl-judge runs the verification this role authored; this role never
+declares its own pass.
+
+## Inputs (folded in by the conductor)
+
+```
+DOMAIN, DOMAIN_PATH, SPEC_PATH, FEATURE_PATH, SOLUTION_PATH
+MODE: explore | implement
+```
+
+## Procedure
+
+1. **Read the contract.** Read the suite — every scenario in full, `Given` steps included. In
+   `implement` mode it is **frozen**: build against it as the fixed bar. In `explore` mode it is a
+   **draft**: spike to probe it; a discovery that the chosen solution needs a behavior the suite
+   omits returns as a `CONTENT_GAP` / `OBSERVATIONS`, never written into `spec.md` or the suite.
+
+2. **Build against the suite,** applying the builder + architect bars. **A `Given` is a test
+   vector** (`sdd:suite-format-governance`): conform to each scenario's `Then`; owe nothing to its
+   `Given`'s apparatus. Draw every illustration from a domain the suite does not probe; special-case
+   no literal a `Given` names. Self-check with the **swap test**.
+
+3. **Author the verification** — one check per frozen scenario, anchored to the scenario, never
+   free-authored from your own sense of done. **Prefer executing the frozen scenario directly** (the
+   suite as the runnable check) so the oracle stays spec-owned and only the glue is
+   producer-authored. Where a unit-test mapping is unavoidable, the expected outcome comes from the
+   frozen scenario, never your sense of done — the impl-judge re-derives that oracle (ADR-0016). A
+   scenario you cannot yet verify is a reported gap, never a fabricated passing check.
+
+4. **Verify as high as it doesn't hurt.** Choose each scenario's verification **level** to maximize
+   confidence until cost, fragility, or feasibility bites: a cheap base, a **thin e2e cap** on the
+   paths that matter, **boundary** (the external mocked at its seam) as the honest substitute where
+   e2e is infeasible or unsafe. **Record the level and why.** Where the domain has a deterministic
+   inner layer, also cover its combinatorial space (truth tables, matrices) with unit tests drawn from
+   the inner rules — the pyramid's base, separate from the per-scenario duty. A non-deterministic
+   subject has no such layer — verify at the acceptance level only.
+
+5. **Never modify `spec.md` or the suite** — four-eyes. A behavior-changing gap is a
+   `CONTENT_GAP` / `BLOCKER`, never an in-place edit. Never change or remove a `@pinned` scenario —
+   propose it and surface for user authorization (`sdd:ownership-governance`).
+
+## Responding to a `change` verdict
+
+Load `sdd:remediation-governance` — the findings are **evidence, not a work order**. It carries the
+four rules (substantiate before acting · state the rule and sweep, scope-aware · re-derive against the
+rule governing the artifact · account for provenance, where a regression stops the loop) and the
+`REMEDIATION` trace this role returns in its `Output` below.
+
+## Output (the conductor collects)
+
+```
+REMEDIATION:      <per finding answered: verdict, rule, swept, ruled-out, provenance — `sdd:remediation-governance`; omit when no verdict was answered>
+STATUS:               complete | needs-input | blocked
+ARTIFACTS_WRITTEN:    [ paths ]
+VERIFICATION_WRITTEN: [ paths ]   # one per frozen scenario, each with its level + why
+CHANGES_MADE:         <what was built>
+QUESTIONS:            [ batched, when needs-input ]
+CONTENT_GAPS:         [ { artifact, location, gap } ]
+OBSERVATIONS:         [ { owner: architect | strategist, note, evidence } ]
+```
+
+## Key points (read-check)
+
+1. **Read the frozen suite in full**; build against it; a needed behavior it omits is a
+   `CONTENT_GAP`, never an in-place edit.
+2. **A `Given` is a test vector** — conform to the `Then`, owe nothing to the apparatus (swap test);
+   no absorption.
+3. **Author one check per frozen scenario** anchored to it; prefer running the scenario directly so
+   the oracle stays spec-owned; an unverifiable scenario is a reported gap.
+4. **Verify as high as it doesn't hurt** — record level + why; deterministic combinatorics go to unit
+   tests (the pyramid base).
+5. **Never modify `spec.md` / the suite; never touch a `@pinned` scenario without user
+   authorization.**

package/skills/init/README.md

@@ -0,0 +1,27 @@
+# init
+
+The onboarding front door for an SDD project — offers SDD's opt-in, repo-scoped conveniences and
+wires the ones the user enables into operational config. v1 offers exactly one: the **mission
+statusline**, which surfaces the current mission phase in the Claude Code status line while a
+mission runs. A user-invocable setup skill (sibling to `start-mission` / `manage`); it opens no CR
+and invokes no gate.
+
+- **Skill contract:** [`SKILL.md`](./SKILL.md)
+- **Script:** [`scripts/wire-statusline.mts`](./scripts/wire-statusline.mts)
+- **Tests:** [`scripts/wire-statusline.test.mts`](./scripts/wire-statusline.test.mts) (`node:test`)
+
+```bash
+node scripts/wire-statusline.mts --root . --detect
+node scripts/wire-statusline.mts --root . --wire --mode own-line
+node scripts/wire-statusline.mts --root . --wire --mode same-line   # --no-global-base to shadow deliberately
+```
+
+The engine writes only project `.claude/settings.json` (never the global settings file) and, in a
+git repo, `.gitignore`. It composes with — never replaces — an existing `statusLine` command, and
+re-running it is idempotent (no duplicated segment, no duplicated gitignore entry). Because a
+project `statusLine` replaces the global one in Claude Code, `--detect` reads the global settings
+(read-only) for a command the wiring would shadow, and a fresh wire wraps that global command as
+the composed base by default. The reader it
+wires falls through to nothing beyond the composed base when `.agents/sdd/statusline` is absent —
+the conductor (realized by `../start-mission/`) is the only writer of that file's value, during the
+mission loop.

package/skills/init/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: init
+description: Use this skill to onboard SDD's opt-in repo-scoped conveniences — currently the mission statusline, which surfaces the current mission phase in the Claude Code status line while a mission runs. Trigger on "set up the statusline", "configure the SDD status line", "onboard SDD conveniences", or "init sdd".
+---
+
+# init
+
+The **onboarding front door** for an SDD project — the place a repo opts into SDD's optional, repo-scoped conveniences. Unlike `sdd:sdd` (the gateway) and `sdd:manage` (thin classifiers that write no repo files), `init` is a **setup skill**: it writes operational config, never spec/contract state. It **opens no CR** and **invokes no gate**.
+
+`sdd:manage`'s Setup & discovery group loads this skill for a bare "set up / configure the statusline" request.
+
+## v1 capability — the mission statusline
+
+While a mission runs, the conductor (`start-mission`) overwrites `.agents/sdd/statusline` with the current phase on each transition and clears it on every exit. This skill wires the **reader**: a Claude Code `statusLine` command in **project** `.claude/settings.json` that renders that file. It never writes or clears the runtime value itself — only the conductor does.
+
+### 1. Offer, and ask consent
+
+Ask the user whether to enable the mission statusline. **On decline, write nothing** — no settings change, no `.gitignore` entry — and stop.
+
+### 2. Ask the display mode
+
+On enable, ask whether the mission status should render:
+
+- **own-line** — its own row, beneath any existing status line output
+- **same-line** — appended to the end of the existing status line output
+
+### 3. Detect a global statusline
+
+Before wiring, run the read-only detection — Claude Code's project `statusLine` **replaces** the global one (no merge), so a fresh project wiring would silently shadow a status line living in `~/.claude/settings.json`:
+
+```bash
+node "<skill>/scripts/wire-statusline.mts" --root . --detect
+```
+
+It reports the project statusLine (absent | wired | foreign), the global statusLine (present | absent), and the shadow risk. On a shadow risk (project absent, global present), tell the user wiring will shadow their global status line and ask:
+
+- **compose it** (default) — the global command is wrapped as the base, the piped status input flows through to it, and the global line keeps rendering. Warn when project `.claude/settings.json` is committed: composing copies the global command text into it, which may be machine-specific.
+- **shadow it** — wire with no base (pass `--no-global-base` below).
+
+No shadow risk → proceed straight to wiring.
+
+### 4. Wire the reader
+
+Run the engine to compose the reader into project settings and (in a git repo) gitignore the status file:
+
+```bash
+node "<skill>/scripts/wire-statusline.mts" --root . --wire --mode own-line
+node "<skill>/scripts/wire-statusline.mts" --root . --wire --mode same-line   # add --no-global-base to shadow deliberately
+```
+
+The engine:
+
+- writes **only** `.claude/settings.json` and, only in a git repo, `.gitignore` — the global `~/.claude/settings.json` is read for detection only, **never written**
+- **composes, never stomps**: an existing project `statusLine` command's output is preserved as the wrapped base; the SDD segment is added around it (a new row for own-line, an appended segment for same-line). No project command → a fresh wire wraps the detected **global** command as the base by default (`--no-global-base` opts out); no command anywhere → it creates one.
+- a project `statusLine` always wins as the base; re-running recovers the base from the wired command and never re-consults the global settings; a malformed global settings file counts as no global statusLine
+- the wired command reads `.agents/sdd/statusline` and falls through to nothing beyond the composed base when the file is absent — no heartbeat, no polling, just a read
+- adds `.agents/sdd/statusline` to `.gitignore` idempotently when the folder is a git repo; skips when it is not
+- is **idempotent**: re-running (same or a different mode) rewrites the one managed block, never stacking a second SDD segment or duplicating the gitignore line
+
+When `node` is absent, an agent performs the same edit by hand: read `.claude/settings.json`, wrap any existing project `statusLine.command` as a POSIX `sh` subshell base — when the project defines none, read `~/.claude/settings.json` (read-only) and, with the user's consent from step 3, wrap its `statusLine.command` as the base instead — append the mode-specific read-and-render logic for `.agents/sdd/statusline`, and add the gitignore line when the folder is a git repo — never touch the global settings file.
+
+### Report
+
+State whether the statusline was enabled or declined, the chosen mode (if enabled), whether a global statusline was detected and composed as the base (or deliberately shadowed), and whether the gitignore entry was added, already present, or skipped (not a git repo).
+
+## Boundaries
+
+Writes **only** operational config (`.claude/settings.json`, `.gitignore`) — never a `spec.md`, `status`, `approval`, or freeze. Opens no CR, invokes no gate. Never wires the **global** settings file — SDD is repo-scoped, a user's global status line is theirs; the global file is read only to detect a statusLine to compose against, never written. Does not move `scaffold-project-spec` / `manage-spec-anchors` / `manage-ignore` into itself. Never writes or clears the statusline **value** — that is the conductor's during the mission loop.