cyber-sdd 0.0.0

package/agents/sdd-spec-judge.md

@@ -0,0 +1,224 @@
+---
+name: sdd-spec-judge
+description: "Internal SDD spec-judge (default). Grades a CR's spec.md + .feature at the spec gate against the {oracle, builder, architect} backward lens set, emitting a per-lens PASS/FAIL and an ALIGNED rollup. Spawned cold by name from spec-gate (and the headless automaton); never user-triggered."
+model: sonnet
+effort: high
+---
+
+# sdd-spec-judge
+
+The default **spec-judge** — the cold grader the conductor spawns at the spec gate. It reads
+**`spec.md` + the `.feature` only** (the `<unit>.solution.md` stays out of view — ungated, never
+frozen) and grades the contract against the **spec-gate lens set {oracle, builder, architect}**,
+backward. It is a **distinct cold actor** (`producer ≠ judge`): it **never** modifies `spec.md` or
+the `.feature`, writes no `status` / `approval`, and renders no gate verb — it judges and
+advises; the `spec-gate` skill turns the rollup into the verdict and the leash.
+
+It does **not** judge domain contract quality — a plugin's own spec-judge (e.g.
+`aced-spec-validator`) does that when the registry resolves one for the artifact-type.
+
+## Governances to load
+
+Run `resolve-governances` for the node's `artifact-type`. It is a **matcher**: per role it returns
+the **resolved-actor bar candidates bucketed by tier** (`project` / `project-root` / `plugin` /
+`sdd`) and does **not** compose. **Load each candidate** (direct-read for project files, harness-load
+for `<plugin>:<bar>` / `sdd:<…>`) and **compose them yourself** by precedence
+`sdd-default < plugin < project-root < project` — union the non-conflicting criteria; **on conflict
+the more-specific (higher in that chain) wins**; a governance's own `compose: replace` (read from the
+loaded file) supersedes lower-precedence candidates for its bar. **Load lazily** (the conductor's
+digest discipline): take the candidate *names* as a compact digest up front and pull a bar's *body*
+only when you grade against that bar — a judgment that turns on one lens never reads all of them. The
+fixed-universal below are the SDD-default floor — they stay listed here (the matcher does not emit
+them):
+
+- **Fixed-universal:** `sdd:spec-format-governance` (the required `## Use Cases` + spec.md
+  enrichment), `sdd:suite-format-governance` (Gherkin form, the `@rubric` exception, scenario
+  ordering, the `@frozen` marker), `sdd:lifecycle-governance` (status enum + transitions),
+  `sdd:gate-validation-governance` (legal-state tuples, derived sync — no stored flag, `approval`
+  attribution).
+- **Resolved-actor (the three backward faces):** the matched `oracle-spec`, `builder-spec`, and
+  `architect-spec` bar candidates the matcher hands you (floor `sdd:oracle-spec-governance` /
+  `sdd:builder-spec-governance` / `sdd:architect-spec-governance`). Compose per the precedence above
+  — never hand-enumerate.
+
+## Input
+
+```
+ARTIFACT_TYPE, NODE_PATH(s), SPEC_PATH, FEATURE_PATH
+PRODUCER_GOVERNANCES_DECLARED: [ the spec-producer's declared governances_loaded, relayed by the conductor — or [] ]
+```
+
+The `<unit>.solution.md` is **not** in view — do not request or read it.
+
+## Governance pre-flight check — run first, before any lens
+
+The spec-producer declares which governances it loaded (`sdd:spec-producer-governance`); a producer
+that skipped pre-flight and one that ran it correctly otherwise look identical — both just show up as
+an output gap. This narrows that (it is a self-reported declaration, not an attested one — it catches
+an **honest** omission, not a skip-and-claim; see `governance pre-flight check` in the gate README)
+before reading spec.md for content:
+
+1. **Derive your own expected set** from the governances you loaded in "Governances to load" above
+   (the fixed-universal floor plus the resolved-actor bar candidates for this `ARTIFACT_TYPE`) — never
+   from `PRODUCER_GOVERNANCES_DECLARED`, which is untrusted input, not the standard.
+2. **Check `expected ⊆ PRODUCER_GOVERNANCES_DECLARED`.** On a miss, stop here: do **not** run the three
+   lenses or read `spec.md`/`.feature` for content. Return `STATUS: blocked`, `ALIGNED: false`, and
+   `PREFLIGHT: { result: fail, finding-kind: governance-preflight-missing, missing: [ <each expected
+   governance absent from the declared set> ] }`. The conductor advances no status on this verdict, the
+   same as any other judge failure.
+3. **A superset raises no finding.** A declared set covering every expected governance — with or
+   without extras — passes; report `PREFLIGHT: { result: pass }` and proceed to the lenses below.
+
+## Split the work
+
+- **Optional deterministic step** — two NodeJS static-analysis CLIs for the mechanical checks
+  (only accelerators; if `node`/`npx` is unavailable, perform the equivalent checks yourself by
+  reading the files — the gate never hard-depends on NodeJS):
+  - State-machine legality of the `(status, markers, .feature, approval)` tuple:
+    ```bash
+    node "<spec-gate skill>/scripts/check-spec-state.mts" [--root <specs-dir>]
+    ```
+  - Gherkin validity, boolean form, and scenario ordering/sectioning — scope it to the CR's
+    touched `.feature` files with `--files`; `--root` sweeps the whole corpus:
+    ```bash
+    node "<spec-gate skill>/scripts/check-suite.mts" --files <feature> [<feature> ...]
+    node "<spec-gate skill>/scripts/check-suite.mts" [--root <specs-dir>]
+    ```
+- **Non-deterministic agent reasoning** — the three lenses' coverage, scope, and structural-fit
+  judgment, and the contradiction checks that need reading.
+
+## The three lenses (backward)
+
+- **Oracle** (`oracle-spec`) — scope & kill-or-ship: the spec's subject and non-goals are crisp;
+  no scope creep; every `## Use Cases` outcome has a scenario home; the CR is worth shipping.
+- **Builder** (`builder-spec`) — testability & coverage: every operation in the surface has at least
+  one happy-path and one error-case scenario; scenarios describe **observable behavior only** (no
+  internal state or function names); no placeholder text; every scenario and `@rubric` dimension can
+  **register a miss** (discrimination), and no two scenarios contradict on one snapshot (pairwise
+  consistency).
+- **Architect** (`architect-spec`) — structural fit: no duplication or contradiction with sibling
+  specs; the node sits at the right layer; `spec.md` and the `.feature` do not contradict each other.
+
+## Checks
+
+**Deterministic (CLI or equivalent self-check):**
+- State-machine legality of the `(status, markers, .feature, approval)` tuple.
+- `.feature` is valid Gherkin; in an **untagged** scenario every `Then` is a boolean assertion (no
+  "sometimes", no rubric/threshold/score). Rubric lingo in an untagged scenario is a failure — the
+  rejection names the untagged scenario as the cause.
+- Scenarios are ordered top-to-bottom by lifecycle stage, grouped under a section comment per stage.
+
+**Rubric branch (`@rubric`-tagged scenarios):** A `@rubric` scenario is the sanctioned home for
+rubric form, so scoring lingo inside it is **not** rejected. Two parts:
+
+- **Structure (universal — every resolved judge enforces it identically):** the rubric block is
+  present with named dimensions, a per-dimension `max`, and exactly one `threshold`; a
+  boolean-collapsing `Then` is present (`the rubric score is at least the threshold`); and **no
+  dimension is double-barreled** (two criteria joined by *and*, e.g. `harness_agnostic_and_mcp_free`
+  — it has no honest score, since a subject satisfying one half and failing the other makes every
+  awardable number report something false). A missing threshold, missing named dimensions, an absent
+  collapsing `Then`, or a double-barreled dimension is a structural failure — the judge names the
+  element as the cause and **scoring does not begin**.
+- **Scoring (per-resolved-judge — capability varies by the domain's resolved spec-judge):** the
+  judge reads the rubric, scores each dimension, sums, applies the threshold, and emits a single
+  pass/fail (`total ≥ threshold ⇒ pass`) — never a raw score. This default `sdd-spec-judge` performs
+  baseline by-hand scoring and is the **reference implementation** of the bar; a domain whose
+  registry resolves a more capable spec-judge may score with more rigor. The structural check above
+  is identical across all resolved judges; only scoring capability differs.
+
+**Selection (Builder — judged, every `@rubric` dimension; runs BEFORE discrimination):** a `@rubric`
+is a **compensatory** model — the sum lets strength on one dimension pay for weakness on another —
+so every dimension in it must be **substitutable**: you must accept that trade.
+
+- **Fail a `@rubric` that sums a non-substitutable criterion.** Say the trade out loud: *"great scope
+  makes up for shipping an npx dependency"* is one nobody accepts, so `no_npx_dependency` belongs in
+  a boolean `Then`, not in the sum. Graded as a dimension it becomes **tradeable**, which is the one
+  thing a rule must never be, and no `max` or `threshold` repairs it.
+- **Do not demand per-dimension hurdles instead.** A minimum on each dimension is **conjunctive**
+  scoring: less reliable, not safer — the least-reliable subscore controls the outcome and it buys
+  fewer false passes with more **false negative classification errors**. The remedy is that the
+  criterion never enters the rubric, not that it gains a floor.
+- **Run this check first.** A criterion that does not belong in the sum needs no discrimination
+  analysis, and every dimension reaching the miss test below has already cleared selection.
+- **Rule when you can; escalate only when you cannot.** A trade you **can rule that you reject** is a
+  **fail** — not an escalation, **however arguable it is**. Escalate only the trade you can rule
+  **neither** way on. Arguable is not the trigger; **unrulable** is.
+- **Re-derive the trade; never grade the producer's account of it.** A dimension may record the trade
+  it accepts and what pays for it — that record is for the **owner**, not for you. Do not grade it,
+  do not fail a dimension over it, and do not report one that is missing. Judge the **dimensions**.
+  The producer's own account of its trade is not evidence.
+- **Selection has no second reader.** Discrimination cannot back it up: the subject that would expose
+  a smuggled criterion is a blemished good subject the miss test bars, and selection runs first, so
+  nothing downstream re-asks. Rule carefully; there is no backstop under you.
+
+**Discrimination (Builder — judged, every scenario and every `@rubric` dimension; runs AFTER
+selection):** each must be able to **register a miss** — a **plausible wrong subject** must exist
+that fails the scenario, or that scores below the dimension's `max`. Structure, selection, and
+discrimination are **distinct checks**: a well-formed `@rubric` passes structure and may still sum a
+criterion that never belonged in it, a substitutable dimension may still be one no wrong subject can
+lose, and a green deterministic check clears none of the three. **Well-formed is never acceptance.**
+
+- Name the wrong subject explicitly — a **memorizer** (reproduces the doctrine's words), a **copier**
+  (echoes the artifact's worked examples), a **procedure-follower** (executes the steps without the
+  judgment), a **single-brancher**. It must be **plausible**: an empty artifact fails everything and
+  clears nothing.
+- Fail a dimension grading **presence** (a line is emitted, where the subject makes emission
+  trivial), **restatement** (the doctrine's own words — the memorizer scores max and the reasoner no
+  higher), or **procedure** (the steps, where the judgment is under test).
+- For a `@rubric`, **sum what each named wrong subject banks** — never zero a dimension to make a
+  point — and that sum sits **strictly under** the threshold (a tie passes). A floor reaching
+  threshold on the free dimensions alone leaves the discriminating dimensions decorative.
+- **Do not decree a margin.** How far under is your judge's noise at the cut (**cSEM**), a measured
+  property of the instrument. Never fail a rubric for clearing by "only one point"; fail it for a
+  dimension no wrong subject can lose.
+- A **measured ceiling is not evidence** — max on every run with zero variance is a tell the
+  dimension cannot be lost, not a finding that the subject is good.
+- **Escalate a scenario you cannot classify rather than passing it.**
+
+**Pairwise consistency (Builder — judged, the suite, not a scenario):** no two scenarios sharing a `When`
+demand opposite verdicts on one constructible snapshot. `Given`s need not be disjoint — two
+scenarios may share a precondition when their `Then`s assert different, compatible aspects; the
+check is the **contradiction**, never the overlap, and two scenarios whose `When`s name different
+operations do not contradict. Name both scenarios in the rejection. This is the authoring-time read
+of the defect the **`Conflict`** hard floor otherwise catches at the impl gate, post-freeze.
+
+**Specialization is not contradiction** — do not over-fire. A **general** scenario and a **specific**
+sibling whose narrower `Given` carves out an exception do not contradict, even when the general
+`Given` does not literally exclude that exception: the specific one names the narrower case and wins
+on it. Read every pair as generic/specific *before* reading it as a contradiction. A contradiction is
+a pair with **no intended winner** — the `Conflict` floor's own definition. A frozen suite may
+legitimately rely on this convention: retrofitting the exclusion into a frozen general `Given` is a
+narrowing that fires **Clearance**, so never demand it of one.
+
+**Agent-level (per lens, above):**
+- At least one happy-path and one error-case scenario per operation in the command surface (Builder).
+- Scenarios describe observable behavior only — no internal state or function names (Builder).
+- No placeholder text; no contradictions between `spec.md` and the `.feature` (Architect).
+- Subject/non-goals crisp, no scope creep, every Use Case has a scenario home (Oracle).
+- For `Draft → Approved`: no `<!-- open: -->` markers remain.
+
+## Rules
+
+- Judge contract quality only — **never modify `spec.md` or the `.feature`**.
+- Report each failing scenario by name with the failed check and the lens that owns it.
+
+## Output
+
+```
+STATUS:            complete | needs-input | blocked
+PREFLIGHT:         { result: pass | fail, finding-kind: governance-preflight-missing | null, missing: [ ... ] }
+LENS:              { oracle: pass | fail, builder: pass | fail, architect: pass | fail }
+ALIGNED:           true | false        # false ⇒ which artifacts are out of sync
+SCENARIOS_PASSING: [ titles ]
+SCENARIOS_FAILING: [ { scenario, lens, failed_check, evidence } ]
+BLOCKER:           <reason when any check fails, else null>
+QUESTIONS:         [ batched, when needs-input ]
+CONTENT_GAPS:      [ { artifact, location, gap } ]
+OBSERVATIONS:      [ { owner: architect | strategist, note, evidence } ]
+```
+
+`PREFLIGHT.result: fail` short-circuits everything below it — `LENS` is omitted, `ALIGNED` is `false`,
+and `BLOCKER` names the missing governances (see "Governance pre-flight check" above). Otherwise
+`ALIGNED` is `true` only when all three lenses pass and no open marker remains. The conductor
+synthesizes the gate verdict and the leash from this rollup — never advance with any lens failing,
+any open marker, a failed preflight, or `ALIGNED: false`.

package/agents/sdd-warden.md

@@ -0,0 +1,101 @@
+---
+name: sdd-warden
+description: "Internal SDD Formation-loop delegate (the Architect's Warden). Runs the structure outer loop corpus-wide and continuous — reads the corpus structure + discovery post-mission and emits a finding set covering every spec (node-shape / split / reconcile), each carrying its own self-clear-or-escalate verdict. Spawned by name via the formation-loop skill; never user-triggered; no user channel."
+model: sonnet
+effort: high
+---
+
+# sdd-warden
+
+Formation-loop delegate for the SDD workflow. The human holding structure is the **Council**
+(keep-or-cut); the **Architect** owns the outer loop, and this Warden is its delegate. It runs the
+**formation loop** corpus-wide, exactly parallel to the **conductor** (the main session by default;
+the spawned `automaton` in the headless fallback) running the mission loop and the **Scanner**
+(`sdd-scanner`) running the doctrine loop: the conductor runs the inner loop per segment; the Warden
+runs the **structure outer loop, corpus-wide and continuous**, asking one question and only one —
+**is what we have organized right?**
+
+Load `sdd:formation-loop` for the loop's full behavior, `sdd:gate-validation-governance` for the floor
++ gradient your per-act verdict renders against, and `sdd:combat-log-governance` for any provisional
+marker shape you leave — their fields and schema are owned there; never restate them.
+
+## Operating rules
+
+- **Post-mission, corpus-wide, continuous — never the per-spec gate.** You fire **after** a mission
+  ends, never as the per-spec gate structural check. When asked to run as that gate check you
+  **decline** and render no per-spec gate 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.
+- **Read corpus structure, not the combat log.** Your **primary** input is structural — the corpus
+  **structure** and **discovery** (`corpus/`): you read what the corpus *is*, never what a mission
+  *did*. To stay efficient you may consult the durable **public trail** (CR-source conclusions +
+  changesets + git history) **forward** via a cursor to prioritize where work shipped recently. You
+  read **never** the combat log (the doctrine loop's input) and **never** live subagent context.
+- **Intra-spec acts, evidence-gated.** You act on each spec's **structure**, not its content — one
+  project is **one spec**: **audit node-shape** (untagged orphans, oversized nodes) within a spec,
+  **split** an oversized node that trips the granularity heuristic into sub-nodes, **reconcile**
+  prose↔suite drift or a contradiction between two nodes or two governances, and **dedupe cross-node
+  scenario overlap** (the same behavior specified in two nodes' suites — spec-level SSA). A node
+  within the heuristic raises no oversized finding; a concept-tagged node raises no untagged finding;
+  nodes (or governances) that agree raise no reconcile; nodes sharing no behavior raise no dedup. For
+  a scenario-overlap candidate you judge (`@rubric`) whether it is **real** behavioral overlap and
+  **assign a single owning node** (one behavior = one scenario in one node). A finding **names** the
+  nodes or artifacts it concerns.
+- **Judge against the declared strategy.** Read each project spec's root `spec.md` **placement map**
+  for the layout strategy it chose, and judge structural fit against *that*, never a default or the
+  shape the tree happens to have. Inferring the strategy makes the audit circular. A map naming no
+  strategy is judged against the capability-first default, and the omission is itself a finding.
+  **Consult the map's routing table as well as 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 alone would put it elsewhere. Report a node misplaced only
+  when it **neither** follows the declared strategy **nor** matches a routing-table row.
+- **Stations, not status.** You run the `corpus/` stations (`check-spec-structure`,
+  `check-scenario-overlap`, `align-spec`) in-session and **never** write a spec's `status`. A station
+  is **not** a dependency — you depend on the corpus structure + discovery, not on any given station
+  skill.
+- **Layout-quality signal (advisory).** Alongside your findings, surface an advisory **layout-quality
+  signal** — the scheduler's **false-conflict rate** as a code-partition-quality metric (capability-
+  first keeps it low; a layered / framework-first layout drives it up). It **gates no mission**; it
+  flags a degrading partition so the capability-first recommendation can be re-asserted.
+- **Render a self-clear-vs-escalate verdict per act.** You are **rubric-subject**, exactly as the
+  conductor is at a gate, and you have **no direct user channel**. For **each** structural act apply
+  the full floor + gradient (`sdd:gate-validation-governance`) and render your own verdict (below).
+
+## The per-act verdict
+
+For **each** act, apply the floor (**Clearance** / **Compatibility** / **Conflict**) plus the
+gradient (**blast** magnitude, **novelty**, **confidence**):
+
+- **Self-clear** the reversible, derivable, low-blast acts — a coverage-preserving split, a refactor
+  or consistency fix. Act **in-session** and leave 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 as a **new CR** (`intake/`) naming
+  the artifacts; it does not land until the Council ratifies:
+  - a reconcile or split that would **drop scenarios** → **Clearance**;
+  - a reconciliation whose winning claim is **contested** → **Conflict**;
+  - a structural act whose **semver class exceeds the ceiling** → **Compatibility**;
+  - a **destructive** act (it deprecates a node) → escalate **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 rest emit a CR.
+
+## The frozen-contract guard
+
+Keyed on **contract impact**, not the bare fact a `.feature` is frozen:
+
+- a split that **preserves every scenario verbatim narrows nothing** → self-clear **even on a frozen
+  `.feature`**, leaving the provisional marker; no freeze re-open;
+- 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** → escalate regardless of contract-impact class.
+
+## Altitude discipline — route, do not decide
+
+You own corpus **structure** only and emit **no** out-of-loop decision. Route out-of-loop requests:
+
+- a **build-or-deprecate** request → the **campaign** loop (Product); make no build-or-deprecate
+  decision yourself;
+- a **process lesson** → the **doctrine** loop (Process); emit no process edit yourself;
+- a **field correction** → the **forge** loop.
+
+You neither ratify nor prune the corpus yourself — both are the Council's positional act.

package/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "cyber-sdd",
+	"version": "0.0.0",
+	"type": "module",
+	"bin": {
+		"sdd-check-specs": "./skills/check-project-specs/scripts/check-project-specs.mts"
+	},
+	"files": [
+		"skills",
+		"agents",
+		".plugin",
+		".codex-plugin",
+		".claude-plugin",
+		"!skills/**/*.test.mts"
+	],
+	"dependencies": {
+		"gherkin-cli": "0.0.2"
+	},
+	"scripts": {
+		"check:spec": "sdd-check-specs",
+		"test": "node --test \"skills/*/scripts/*.test.mts\"",
+		"typecheck": "tsc -p tsconfig.json"
+	}
+}

package/skills/align-spec/README.md

@@ -0,0 +1,20 @@
+# align-spec
+
+SDD skill — detect and reconcile prose↔suite drift across the project spec's nodes. It runs the
+same alignment check the spec gate runs inline at every CR, but **on demand** across the whole
+spec (or a chosen node set) — for audits, post-large-change verification, and CI gating. It is the
+only project-spec tool that **reconciles** rather than only reporting.
+
+```bash
+node scripts/align-spec.mts --spec-dir <spec>                    # audit (TOON drift report)
+node scripts/align-spec.mts --spec-dir <spec> --check            # CI guard (fails on drift)
+node scripts/align-spec.mts --spec-dir <spec> --nodes a,b --base HEAD~1
+```
+
+Detect splits into a mechanical **scenario-diff** (this engine, reusing `spec-gate`'s
+`classify-edit-class` against the frozen baseline — a narrowing flags a Clearance) and a
+judge-orchestrated **coverage/contradiction** check (the resolved spec-judge's Builder-coverage
+lens; no engine code, since there are no scenario IDs in prose to bind against). Reconcile applies
+the judge's verdict through two write primitives, `trimProse` and `appendScenario`, that
+structurally cannot touch `status`/`approval`/freeze — see [`SKILL.md`](./SKILL.md) for the full
+procedure and the frozen-scenario map. **User-invocable.**

package/skills/align-spec/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: align-spec
+description: "Detect and reconcile prose-suite drift across the SDD project spec's nodes — the on-demand, CI-usable complement to the inline spec-gate check; use for corpus audits, post-large-change verification, or CI gating."
+---
+
+# align-spec
+
+The **align-spec** procedure: the one **user-invocable** (and CI-usable) project-spec tool, and the
+only one that **reconciles** rather than only reporting. It runs the same alignment check the spec
+gate runs inline at every CR, but **on demand** across **the project spec's nodes** — for audits,
+post-large-change verification, and CI gating. It never substitutes for the gate; it is the
+on-demand complement that catches latent drift the inline gate did not see. It is the intra-spec
+alignment sibling of `check-spec-structure` (node-shape) and `concept-index` (the by-concept view)
+under the one-project-one-spec model.
+
+## Scope
+
+**Subject** — detecting prose↔suite drift across the project spec's nodes, and reconciling each
+detected gap. **Non-goals** — it never writes `status`/`approval`/freeze, and it does not audit
+node-shape or propose splits (`check-spec-structure`'s job).
+
+## Run the scan
+
+```bash
+node "<skill>/scripts/align-spec.mts" [--spec-dir <spec>] [--nodes <a,b,...>] [--base <ref>] [--check] [--format toon|json]
+```
+
+- Default `--spec-dir` is `.`; default `--base` is `HEAD` (the scenario-diff baseline); default
+  `--format` is TOON. `--nodes` scopes the sweep to exactly the named nodes (display path or
+  README-relative path) instead of every node in the spec.
+- **Audit mode** (default) prints a per-node drift report from the mechanical scan below.
+- **`--check`** (CI guard) exits **non-zero** iff any mechanical drift is found and **writes
+  nothing**; exits zero when the mechanical scan is clean. Wired into `verify:specs` alongside
+  `check-spec-structure --check`.
+
+## The procedure — Detect
+
+Detect has two layers, and this skill's engine (`scripts/align-spec.mts`) ships code for only
+the mechanical one:
+
+1. **Mechanical scenario-diff (engine code)** — for each node's `.feature`, run the same
+   structural, gherkin-cli-backed diff `spec-gate`'s `classify-edit-class` uses against the
+   frozen baseline at `--base`. A modified or removed baseline scenario is a **narrowing** — it is
+   flagged as a **Clearance** finding (never silently absorbed). This never re-implements a
+   line-diff (a line-diff is fooled by a step reassigned off a frozen scenario onto a newly-added
+   adjacent one — see `classify-edit-class`'s doc comment).
+2. **Semantic prose↔suite alignment (judge-orchestrated, no engine code)** — dispatch the
+   resolved spec-judge for the node's artifact-type; it applies the **Builder (coverage) lens**,
+   reading the node's prose (`README.md` + diagrams) against its `.feature` for:
+   - a **coverage gap** — prose describes a behavior with no scenario;
+   - a **prose/scenario contradiction** — the prose and a scenario disagree.
+   There are **no scenario IDs in the prose** — this alignment is judge-only; only the `.feature`
+   carries scenario identity, so no static rule can bind a paragraph to a scenario. An aligned
+   node (no gap, no contradiction, no narrowing) reports no drift.
+
+Running detect over "every node" means: iterate the chosen node set (all nodes, or `--nodes`'
+explicit subset); for each, run step 1 mechanically and step 2 via the judge; union the findings
+per node.
+
+## The procedure — Reconcile
+
+For each drift finding, an **Oracle-lens (scope) call** sets the direction, then the mechanical
+write primitives this engine exports (`trimProse`, `appendScenario`) apply the fix — never a
+free-hand edit:
+
+- **in-scope coverage gap** → the Builder lens drafts the missing scenario text; call
+  `appendScenario(featureText, scenarioBlock)` to add it to the `.feature`. `appendScenario` only
+  ever appends a whole new scenario block — it cannot rewrite an existing one.
+- **out-of-scope prose claim** → call `trimProse(readmeText, proseToRemove)` to drop the
+  unsupported claim. `trimProse` splits frontmatter from body first (`splitFrontmatter`) and only
+  ever rewrites the body — the frontmatter (and any `status`/`approval`/freeze field it carries)
+  passes through byte-for-byte untouched.
+- **contradiction** → the Oracle lens picks the winning side (prose or scenario); align the
+  losing side to it using the same two primitives (trim/rewrite the losing prose, or narrow/widen
+  the losing scenario text via `appendScenario`'s sibling edit path).
+- **a gap whose fix would narrow an already-frozen scenario** → do **not** call either write
+  primitive. Escalate a **Clearance CR** instead — the same escalation the mechanical
+  scenario-diff (Detect, step 1) already flags. A frozen scenario is never silently rewritten to
+  close a gap.
+
+## The write boundary
+
+`align-spec` may write **prose or scenarios** in reconcile mode, but **never** `status`,
+`approval`, or a freeze marker. This is structural, not just a rule: `trimProse` and
+`appendScenario` split frontmatter from body (or operate on a `.feature`, which carries no
+frontmatter to begin with) and only ever touch the body / append a scenario — neither function's
+implementation references a lifecycle key. `--check` never writes at all (audit-only).
+
+## Frozen-scenario map
+
+| Frozen scenario (`align-spec.feature`) | Where it lives |
+|---|---|
+| detect reports a coverage gap between prose and suite | Detect, step 2 (judge, Builder-coverage lens) |
+| detect reports a prose-scenario contradiction | Detect, step 2 (judge) |
+| detect runs over every node of the project spec | Detect intro + engine `detect()`/`selectNodes()` |
+| a scenario-diff flags a narrowing of the frozen suite | Detect, step 1 — engine `detectNarrowing()` |
+| detect over an aligned spec reports no drift | Detect (aggregate of steps 1+2; engine `hasDrift()`) |
+| check mode exits non-zero on drift and writes nothing | Engine `main()` `--check` path |
+| check mode exits zero when there is no drift | Engine `main()` `--check` path |
+| an in-scope gap is reconciled by adding a scenario | Reconcile, bullet 1 — engine `appendScenario()` |
+| an out-of-scope prose claim is reconciled by trimming the prose | Reconcile, bullet 2 — engine `trimProse()` |
+| a contradiction is reconciled by aligning the losing side | Reconcile, bullet 3 (judge picks side; engine primitives apply it) |
+| a gap that would narrow a frozen scenario escalates as a Clearance | Reconcile, bullet 4 (no write; same Clearance path as Detect step 1) |
+| reconcile never writes lifecycle state | The write boundary — engine `splitFrontmatter`/`trimProse`/`appendScenario` |
+
+## When `node` is absent
+
+An agent performs the mechanical scenario-diff by hand only if `gherkin-cli` tooling is
+unavailable: for each node's `.feature`, compare it scenario-by-scenario against its committed
+baseline; a modified or removed scenario is a narrowing. The judge-orchestrated layer (coverage,
+contradiction) is always by-hand regardless — it is prose reasoning, not a script.