cyber-sdd 0.0.0

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

@@ -0,0 +1,44 @@
+---
+name: solution-producer-governance
+description: "Partial Skill: invoke by name only — the SDD default solution-producer procedure. Loaded in-session by the conductor when it runs the solution-producer role inline, not user-triggered."
+user-invocable: false
+---
+
+# Solution-Producer Governance — the default solution-recording procedure
+
+The procedure the **conductor** follows when it runs the **solution-producer** role from the SDD default — no plugin covers the domain and no model-tuned producer agent is named for the slot, so the conductor **loads this governance and authors inline** in its own warm context (recorded `produced-by.solution-producer: sdd:automaton`). This is the relocation of the former `plan-producer` role's *functional-spec* half: the solution is the chosen approach + rejected alternatives, now recorded **per unit** as `<unit>.solution.md` rather than as a `plan.md`. The task DAG that `plan-producer` also wrote is **not** this role's output — it is the conductor's transient execution `.plan.md` `todos`.
+
+The solution is the unit's **third facet** (spec = *what*, suite = *proof*, solution = *why this shape*). It is **optional** and **ungated**: it gets no judge of its own, stays out of the spec-judge's view, and is never frozen. The implementation's frozen-scenario result validates it transitively.
+
+Load alongside this governance: the resolved **architect** actor bar (structural fit — no duplication or conflict with existing code/conventions) to self-align before writing, and `sdd:ownership-governance` for the write-ownership matrix — the solution-producer must **not** modify `spec.md`, the `.feature`, or any control frontmatter; a behavior gap discovered while recording the solution is a `CONTENT_GAP` / `OBSERVATIONS`, never an in-place edit.
+
+## Inputs (folded in by the conductor)
+
+```
+DOMAIN, DOMAIN_PATH, SPEC_PATH, FEATURE_PATH, SOLUTION_PATH
+MODE: explore | implement
+EXISTING_SOLUTION: <the current <unit>.solution.md, on a revise — or null>
+```
+
+## Procedure
+
+1. **Decide whether a solution is warranted at all.** Read `spec.md` and the `.feature`. Write a solution **only** when the unit has a **real design fork** — a non-obvious approach chosen over plausible alternatives that a later reader could not reconstruct from the spec alone. If the unit's shape follows directly from its spec, **write no file** and return `STATUS: complete` with `SOLUTION_WRITTEN: none`. A solution that would only paraphrase the spec's *what* or the suite's *proof* is noise — do not write it.
+
+2. **Record the solution at the design boundary, not per scenario.** Write `<SOLUTION_PATH>` (`<unit>.solution.md`, beside the unit's `README.md` + `.feature`) capturing: the **chosen approach**, the **rejected alternatives with why each lost**, and the trade-offs that decided it. Map to the **decision**, not one entry per scenario — the suite already covers scenarios. Apply the **architect** bar (does this shape fit existing code/conventions without duplication or conflict?).
+
+3. **Never restate the contract.** Do not paraphrase `spec.md` or the `.feature`. The solution adds *why this shape*; it carries no *what* the spec already states and no *proof* the suite already encodes.
+
+4. **On a revise, tighten in place.** When `EXISTING_SOLUTION` is non-null, sharpen the existing record rather than rewriting from scratch; if the design fork it documented no longer exists, remove the file (the optional facet returns to absent).
+
+5. **Never modify `spec.md` or the `.feature`** — four-eyes (the producer does not set its own bar). The solution is co-delivered with the other producers' artifacts, not in a separate gated phase.
+
+## Output (the conductor collects)
+
+```
+STATUS:          complete | needs-input | blocked
+SOLUTION_WRITTEN: written | tightened | removed | none
+NOTES:           <the fork recorded, or why none was warranted>
+QUESTIONS:       [ batched, when needs-input ]
+CONTENT_GAPS:    [ { artifact, location, gap } ]
+OBSERVATIONS:    [ { owner: architect | strategist, note, evidence } ]
+```

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

@@ -0,0 +1,73 @@
+# spec-format-governance
+
+This is an internal SDD governance about the project specification.
+
+It describes how one capability's `spec.md` is structured and what it should contain.
+
+Every behavioral spec in the project is written to the same shape, so a reader who has read one
+knows where to look in any other. This governance is that shape.
+
+## Where a spec lives — the folder structure
+
+A `spec.md` never sits on its own. The project spec is a folder tree organized by **capability** —
+the top-level folder names say what the project *does* (`gateway/`, `intake/`, `mission/`) — with
+three folders that are deliberately not capabilities:
+
+| Folder | Holds | Why it is not a capability |
+| --- | --- | --- |
+| `design/` | The **rules** — the model, and the *why*. | Describes the system rather than doing something in it. |
+| `workflows/` | The **usage** — how the capabilities compose into whole flows. | Cuts across every capability instead of being one. |
+| `ledger/` | The **provenance** — durable audit records. | Data, not a spec at all. |
+
+Two rules shape the tree:
+
+- **Two levels, never three.** A capability folder holds leaf units (`<capability>/<unit>/`), and
+  that is as deep as it goes. When something inside a capability wants its own sub-grouping — a
+  phase, a producer/judge pair — that grouping is a *cross-cutting concern*, so it is tagged with
+  `concept:` frontmatter and recovered through the by-concept index rather than given a third
+  folder level.
+- **Rules in `design/`, behavior in the capability folder.** The rule a thing follows and the
+  scenarios that enact that rule live apart, which keeps `design/` readable as a model while the
+  capabilities stay testable as behavior.
+
+Each leaf unit folder holds the `spec.md` this governance describes, its `.feature` suite alongside
+it, and optionally a `.solution.md`.
+
+The folder law itself — spec types, the folder kinds, screaming architecture, the depth cap — is
+owned by **`spec-structure-governance`**, not by this bar. It is summarized here so the file
+structure below has somewhere to sit.
+
+## What it requires — the file structure
+
+A `spec.md` has **four sections, in this order**:
+
+| Section | What goes in it |
+| --- | --- |
+| `## What` | What the capability is, the problem it solves, who has that problem, and what it deliberately does not do (non-goals). |
+| `## Use Cases` | Every distinct way the capability is invoked — one row each, as trigger / inputs / outcome. Each is named after the thing you actually call: a CLI verb, a function, an endpoint. |
+| `## Control Flow` | The decisions the capability makes once invoked, taken as one **control-flow graph (CFG)** and **drawn** as a diagram rather than described in prose. Use cases feed into one CFG; several usually share it. |
+| `## Scenario map` | A table pairing each branch in that diagram with the one test scenario covering it, grouped by use case. One-to-one, both directions — so a gap in coverage is visible instead of buried in prose. |
+
+It also sets a **plain-language bar**: a smart reader with no background in the domain should follow
+the spec on the first read. Simplify the writing, never the domain — define the domain terms in
+plain words instead of dropping them. This is a gate requirement, not a style preference, because
+`spec.md` is what gets reviewed.
+
+Descriptive indexes and reference documents are exempt — they carry none of these sections.
+
+## Usage
+
+- **spec-producer:** how to write the spec
+- **spec-judge:** grade the spec structure and content at the **spec-gate**
+
+## Related governances
+
+This bar owns the layout of a **single** `spec.md`. Its neighbors own everything around that:
+
+- **`spec-structure-governance`** — the layout law this sits inside, and the owner of the folder
+  structure summarized above: spec types, the folder kinds, screaming architecture, the depth cap.
+- **`suite-format-governance`** — how the `.feature` suite itself is written (Gherkin form, rubrics,
+  scenario ordering).
+- The **corpus-organization** bar — how big a spec should be in the first place.
+
+Internal SDD governance (`user-invocable: false`). Not triggered by users directly.

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

@@ -0,0 +1,114 @@
+---
+name: spec-format-governance
+description: "Partial Skill: invoke by name only"
+user-invocable: false
+---
+
+# Spec-Format Governance — the spec.md structure bar
+
+Universal bar for how a **behavioral** node's `spec.md` is structured. The spec-producer self-aligns
+to it before writing; the spec-judge grades structure backward at the spec gate. The layout law it
+sits inside — spec types, the four folder kinds, screaming architecture — is
+`sdd:spec-structure-governance`; this bar owns one node's `spec.md`. A descriptive index or reference
+artifact carries none of the sections below.
+
+## The four sections, in order (plus one optional)
+
+### `## What`
+The overview: what the capability is, the problem it solves, who has it — plus **Non-goals** (what it
+deliberately excludes). One or two short paragraphs; add a **Key terms** glossary when it leans on
+jargon. Legible to a non-engineer.
+
+### `## Use Cases`
+The **entry points** — one row per distinct way the capability is invoked, each **named to its
+implementation surface** (a CLI verb, a public function, an endpoint), given as
+**trigger / inputs / outcome**. A use case answers *"when, and with what, is this invoked?"* — never
+*"given this state, does it do that?"* (that is a scenario). Naming the impl surface keeps the spec,
+the suite, and the code on **one screaming structure**: the builder gives each use case its own
+module, so each change stays local.
+
+### `## Control Flow`
+The **control-flow graph (CFG)** the capability runs once invoked, **drawn** as a fenced Mermaid
+graph — nodes are decisions, edges are branches. Use cases **enter** the CFG, and several usually
+share one (many-to-one). When use cases run genuinely distinct decision logic (common for CLI verbs),
+section `## Control Flow` by sub-graph and have each use case name the one it enters. A single-branch
+capability may state its decision in a line.
+
+### `## Scenario map`
+The **explicit maintained table** binding the CFG to the suite, **grouped by use case**, with three
+columns — **`| Edge | Path (Given) | Scenario |`**. The unit is the **(path class, edge)** pair, not
+the edge alone: a scenario's `Given` is the path reaching the edge, its `When` is the edge under test
+(`sdd:suite-format-governance`).
+
+- **1:1 scenario↔row** — every scenario has exactly one row, every row one scenario.
+- **An edge may carry several rows.** That is **permutation coverage**, not duplication — legitimate
+  when each row's path class yields a *different* outcome. Same edge *and* same path class twice is a
+  duplicate.
+- **Collapse reconverged paths.** Where the outcome does not depend on which upstream branch was
+  taken, one row covers them all; write the path as the reconvergence point (or `any`), never the
+  route. Naming state the outcome does not depend on manufactures a false permutation.
+- An edge with **no** row is a coverage hole; a scenario with **no nameable edge** is not acceptance
+  and does not belong in the suite.
+
+Three columns make the shape legible at a glance: a `Path` column reading `any` is a **convergence**
+claim (the outcome does not vary), and an edge repeated with different paths shows exactly which
+distinctions the contract cares about. The grouping keeps coverage **visible per use case** — an
+uncovered surface is a hole, not a silent gap in prose. `check-suite` lints it. A `@pinned` behavior
+the CFG did not reach enters as a **seed** the agent grows the CFG around, adding the discovered
+edges to the map.
+
+### On backfill — draw the CFG and the scenario map, don't stop at Use Cases
+When the implementation already exists (a **backfill**), the four sections are **still mandatory**.
+Read the source, then **draw the `## Control Flow` CFG from the code** and its 1:1 `## Scenario map` —
+a spec that stops at `## Use Cases` has named its entry points but neither the decisions the
+capability takes nor their coverage. The suite is **re-derived from that CFG**, not patched from the
+standing one (`sdd:suite-format-governance`). `check-spec-structure`'s `incomplete-node` flags a
+behavioral leaf that skips a required section.
+
+### `## References` *(optional — any spec-type)*
+Where a decision in this node rests on **research or an external standard**, cite it here: the source
+and **what it backs**. Not a bibliography — a line earns its place only by carrying a decision that
+would otherwise read as taste.
+
+- **Cite the claim, not the topic.** "Vague steps produce defensive step definitions carrying flags,
+  so a `Given` must be buildable — [source]" beats "see [source] on BDD".
+- **External sources only.** A sibling spec, a `design/` model doc, or a governance is a normal
+  in-body reference, not a research citation.
+- **Optional and rare.** Most nodes decide from the domain and cite nothing. An empty section is
+  omitted, never stubbed.
+- **Not the design record.** A chosen-vs-rejected design fork belongs in the unit's
+  `<unit>.solution.md`; `## References` records the *evidence consulted*, which outlives the fork.
+
+It is the last section, after `## Scenario map` (or after `## Subject` on a reference artifact).
+Reason: a reader wants the contract first and the provenance only when they question it.
+
+## Plain language — a gate requirement, not a nicety
+
+`spec.md` is reviewed at the gate, so plain language is a bar it must clear. Write so a **smart
+reader with no domain context follows it on the first read**:
+
+- **Simplify the writing, never the domain.** Domain concepts are essential — define each in plain
+  words, never drop one to sound simpler. Jargon, long sentences, and unexplained acronyms are
+  accidental — drive them to zero.
+- **Lead with the plain word**, keep the specialized term as a parenthetical ("**safe to repeat**
+  (idempotent)"); carry a **Key terms** glossary when the spec leans on several.
+- **Short sentences, concrete over abstract.** Draw a diagram wherever it beats prose; format with
+  headings, tables, and callouts for the load-bearing decisions.
+
+The same bar binds the **suite**'s scenarios — plain `Given/When/Then` the same reader can follow.
+Enrichment (diagrams, formatting) is `spec.md` only; the suite stays plain Gherkin.
+
+## Key points (read-check)
+
+1. **Four sections in order** — `## What` (overview + non-goals), `## Use Cases`, `## Control Flow`,
+   `## Scenario map` — plus an optional `## References` last, citing research that backs a decision
+   (the claim it supports, not the topic).
+2. **A use case is an entry point named to its impl surface** (CLI verb / function / endpoint) — spec,
+   suite, and code share one screaming structure.
+3. **The CFG is shared** — use cases enter it (many-to-one); section by sub-graph only when the
+   decision logic genuinely differs.
+4. **The scenario map is 1:1 and grouped by use case** — coverage visible per use case; `check-suite`
+   lints it.
+5. **A `@pinned` behavior enters as a seed** the agent grows the CFG around.
+6. **Plain language is a gate bar** — a reader with no domain context follows the spec (and its
+   suite) on first read; define every term, simplify the writing not the domain.

package/skills/spec-gate/README.md

@@ -0,0 +1,26 @@
+# spec-gate
+
+Internal SDD skill that runs the **spec gate** (Draft → Approved) over a CR's spec + suite
+**diff**. It runs the deterministic structural checks (`scripts/check-spec-state.mts` — the root
+lifecycle tuple + the per-node `spec-type` reconcile) and the provenance structural checks first
+(fail-closed on malformed `produced-by` / no resolvable producer; flag-only on uninstalled
+producers), then — running **in-session** as the conductor at the gate — **spawns a distinct cold
+spec-judge** over `spec.md` + the `.feature` (the **{oracle, builder, architect}** lens set; the
+solution stays out of its view) and derives the leash, then takes the verdict — self-asserting into
+the async review queue when in leash, else showing the in-session digest and taking the human
+verdict directly (it holds the user channel).
+
+On **approve** it freezes each touched `.feature` per-file (`@frozen`), appends a per-CR `gate`
+line to the mission's own `ledger/` shard, and writes `status: approved`; `spec.md`/READMEs stay aligned, never frozen.
+The **impl gate** is the mission's, not here. The gate is verdict-only — it writes no setup
+frontmatter and never fixes issues automatically.
+
+References `sdd:lifecycle-governance`, `sdd:ownership-governance`, `sdd:gate-validation-governance`,
+`sdd:combat-log-governance` (provenance/freeze shapes), and the conductor's autonomy bar.
+
+## scripts/
+
+- `check-spec-state.mts` — deterministic state validator (root tuple + per-node spec-type
+  reconcile); run via `pnpm verify:specs-new`. Tested by `check-spec-state.test.mts`.
+- `check-suite.mts` — deterministic `.feature`-form validator (Gherkin validity, boolean-`Then`
+  form, scenario ordering); run via `pnpm verify:specs-new`. Tested by `check-suite.test.mts`.

package/skills/spec-gate/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: spec-gate
+description: "Partial Skill: invoke by name only — the SDD spec gate (Draft → Approved), the verdict on a CR's spec + suite diff — run by the conductor inside the mission loop, not triggered by users directly."
+user-invocable: false
+---
+
+# spec-gate
+
+Run the SDD **spec gate**: the verdict on a CR's spec + suite **diff** before it becomes the
+contract. This is an **internal step the conductor runs inside the mission loop** (loaded by
+`start-mission` at the end of explore), **not** a user-invocable skill. It **spawns a distinct
+cold spec-judge**, derives the **leash**, takes the verdict (the in-session conductor holds the user
+channel, so it is the positional ratifier), and on approval **freezes** each touched `.feature` file
+and records a durable per-CR `gate` line. The impl gate (Approved → Implemented) is **not** here — it
+is the mission's. This skill never collapses producing and judging into one voice.
+
+Load `sdd:lifecycle-governance` (status enum, transitions, the freeze state-transition),
+`sdd:ownership-governance` (who may write `status` / `approval`),
+`sdd:gate-validation-governance` (legal-state tuples, per-node spec-type checks, derived sync —
+no stored flag, `approval` attribution). The `produced-by` and sharded-ledger shapes the gate checks are in
+`sdd:combat-log-governance`; the freeze model in `sdd:lifecycle-governance`; the
+self-clear-vs-escalate bar and the four-C floor are the conductor's autonomy bar (`start-mission`).
+
+## 1. Structural checks (deterministic, run first)
+
+Run before any verdict work; structural validity **fails closed**, availability only **flags**:
+
+```bash
+node "<skill>/scripts/check-spec-state.mts" [--root <specs-dir>]
+```
+
+Exit `0` = legal; exit `1` prints each violation as `✗ <slug>: <reason>` — fix before continuing.
+It checks the root lifecycle tuple **and** the per-node `spec-type` reconcile: a `reference` node
+carrying a `.feature` or missing its `## Subject`, and a `behavioral` node missing `## Use Cases`,
+**fail closed**; a descriptive node (no marker) raises no violation. If `node` is unavailable,
+perform the same checks by reading each README's frontmatter yourself.
+
+The sibling `scripts/check-suite.mts` is the **`.feature`-form** authority — Gherkin validity,
+boolean-`Then` form (hedge-word + leaked-rubric detection), and scenario ordering/sectioning. When
+the CR touches any `.feature`, run it here **fail-closed, before spawning the cold judge**, scoped to
+the CR's touched files:
+
+```bash
+node "<skill>/scripts/check-suite.mts" --files <the CR's touched .feature files>
+```
+
+Exit `0` = form clean; exit `1` prints each `✗ <file>: <reason>` — **advance nothing and do not
+spawn the judge; report the violations for the producer to fix.** Scoping to `--files` keeps the gate
+on the CR's delta; the tree-wide `--root` sweep stays the `verify:specs-new` CI backstop. The cold
+spec-judge grades form qualitatively; this engine catches it mechanically, so the judge only ever
+sees a well-formed suite.
+
+The same `check-spec-state.mts` also carries **referenced-artifact-exists** — a backtick-wrapped
+path any touched **prose `.md` under the spec tree** names (not just `spec.md`/`README.md` — a
+`design/*.md` or nested node doc too; a relative `./`/`../` reference or a repo-root-relative one
+under `.agents/`, `plugins/`, `packages/`, `apps/`, `docs/`, `.claude/`) must resolve to a real
+file or dir; a template placeholder (`<project>`) or glob (`*.plan.md`) is exempt. **Diff-scoped +
+surface-for-judgment, not fail-closed:** the check gates only paths the CR **introduces** against
+the file's committed baseline (`--base <baseref>`, absent ⇒ every ref counts as introduced) — a
+pre-existing reference a touched file already carried is never gated. An unresolved *introduced*
+ref is printed as a `⚠` finding for the cold judge to weigh, but never blocks the gate on its own;
+the judge still runs. Referenced ≠ must-exist. Never the `--root` sweep, since the existing
+corpus's accumulated prose legitimately names example/convention paths a blind tree-wide scan
+cannot distinguish from a real broken reference. Pass every touched `.md` path (the engine filters
+internally to prose `.md` files that lie under the spec tree — `.agents/spec/`, `.agents/specs/`,
+or a nested `<project-path>/.agents/spec/` — so a touched `.md` outside the spec tree is never
+swept):
+
+```bash
+node "<skill>/scripts/check-spec-state.mts" --files <the CR's touched .md files> [--base <baseref>]
+```
+
+Exit `0` prints each `⚠ <file>: introduces unresolved reference ...` finding (if any) plus the
+summary line — **surface the findings for the judge's read, never a hard block by themselves.**
+An unreadable touched file still **fails closed** (`✗ <file>: cannot read file`, exit `1`) — that
+is a real error, not a can-exist judgment call.
+
+Also carried in the same `--files` pass: the **use-case-coverage** pre-filter. For each touched
+file whose `## Use Cases` section is written as a **table** with a `Scenario` column, every row's
+backtick-wrapped `Scenario:` title (or shared `@tag`) must resolve to a real `Scenario:` in the
+sibling `.feature` (same directory). Unresolved → **fail closed**, judge not spawned. Non-mandating:
+no `## Use Cases` section, or a table with no `Scenario` column, or prose/EARS use cases, raise no
+violation and stay the spec-judge's coverage backstop. Exit `1` prints each `✗ <file>: Use Cases
+table names scenario ... that does not resolve in the sibling .feature`.
+
+**Provenance structural checks** (`sdd:combat-log-governance`). Read the touched files'
+`produced-by` frontmatter and the root's `ledger/` shards (globbed; a legacy `ledger.jsonl` still counts):
+
+- **Malformed `produced-by` entry** — a value that is not a well-formed plugin-qualified name
+  (`<plugin>:<agent>`) → **flag and fail closed**.
+- **Uninstalled-but-valid recorded producer** — an entry whose plugin is not installed is valid
+  history → **flag only** (annotate `[unavailable]`), do not block.
+- **No resolvable producer** — a required production role that resolves to neither a plugin agent
+  nor an SDD default → **fail closed**.
+
+The gate stays verdict-only — it writes **no** setup frontmatter to resolve any of these.
+
+## 2. Identify the CR's diff footprint
+
+The gate decides a **CR**, not a single folder: resolve the set of files this CR **touched**
+(the spec READMEs + `.feature` files in its delta). The digest and freeze both operate over this
+footprint, never the whole tree and never one fleet-era folder.
+
+## 3. Judge and derive the leash
+
+Resolve the **spec-judge** for each `artifact-types` (a plugin judge or the SDD default
+`sdd-spec-judge`) and **spawn it cold** over the touched node(s) — pass it `spec.md` + the
+`.feature` only (the solution stays out of its view). It grades against the spec-gate lens set
+**{oracle, builder, architect}**. Then take the judge's **contract-sync verdict** (derived at this
+gate, never stored) and **derive the leash** (the conductor's autonomy bar,
+baked into `start-mission`) in-session. Collect the judge's `STATUS`,
+`ALIGNED`, failing scenarios, remaining `<!-- open: -->` markers, `OBSERVATIONS`, and the gate
+report. The judge is a **distinct cold actor** and never edits the artifact it grades.
+
+**Never advance** — by self-assertion or human verdict — with judge failures, any remaining open
+markers, or a misaligned suite. They fail the confidence dimension, so they forbid self-assertion
+too; report the blockers for the user to fix (surface `OBSERVATIONS`; on accept they become a new
+node, never a marker grown into this spec).
+
+## 4. Take the verdict — self-assert within leash, else the human
+
+- **In leash** (every dimension reads safe): the conductor **self-asserts** — writes
+  `approval.spec: { verdict: approve, by: agent, why }`. The diff lands
+  **provisionally** into the asynchronous review queue. Still emit the digest + gate report,
+  flagged **"agent-asserted — ratify or kick back."**
+- **Gated** (the leash stops, or the hard floor fires): present the **digest** above the gate
+  report so the human sees what they are deciding, then take the human verdict
+  (`approve` / `change` / `reject`).
+
+**Hard-floor escalations at this gate** (the conductor's autonomy bar): **Clearance** — a
+narrowing (weakening or deleting an e2e scenario), escalated unless the CR pre-authorized it; and
+**Compatibility** — the change's semver class exceeds the authorized change-class ceiling.
+**Conflict resolution** cases (a contradiction inside the suite) are surfaced here but formally
+fire at the impl gate; **Consent** never fires at authoring. Everything additive / internal / minor
+self-clears.
+
+## 5. Apply the verb + freeze
+
+| Verb | Action |
+|---|---|
+| **approve** | land the diff; **freeze** each touched `.feature` (set its own `@frozen` tag); append a per-CR `gate` line to the mission's **own shard** in the `ledger/` directory sibling to `spec.md` (`verdict: approve`, `frozen[]`, keyed by `cr`, no `ts`); write `status: approved` |
+| **change** | revise the diff; **nothing freezes**; stays `draft`. The findings are **evidence, not a work order** — the producer substantiates each before acting, states the **rule** each instantiates and sweeps for its other instances, re-derives every correction against the rule **governing the artifact**, and accounts for each finding's **provenance**: a finding naming an artifact the previous round's commits changed is a **regression**, which stops the loop for a re-plan (`sdd:remediation-governance`) |
+| **reject** | scope-kill — drop the delta; nothing freezes |
+
+**Freeze is per `.feature` file.** Each touched file hard-freezes via its `@frozen` tag; untouched
+files keep their state. An **additive** scenario folds into a frozen file without unfreezing it
+(self-clears) — the `addOnly` result of the mechanical diff above (`gherkin-cli diff`) confirms a
+change is purely additive with no judge round; a **narrowing/rewriting** edit (a `modified`/`removed`
+scenario) unfreezes its file and fires **Clearance** once the narrowing is confirmed semantically.
+The edit-class classification itself — additive / no-content-change / narrowing / mixed — comes from
+`scripts/classify-edit-class.mts` (`--files <paths> [--base <ref>]`): a **structural** per-named-`Scenario`
+diff via the pinned `gherkin-cli@0.0.2 diff`, plus git rename detection for a pure `git mv`, **never a raw
+line diff** (a step orphaned off a frozen scenario onto a new adjacent scenario shows no `-` line and
+would read as additive to a line-diff; the structural diff correctly reports the losing scenario as
+`modified`). It only classifies — additive / no-content-change self-clear, narrowing / mixed take the
+Clearance path above; it fires no verdict itself. Run it over the CR's touched frozen `.feature` files
+to read the edit class before applying the verb:
+
+```bash
+node "<skill>/scripts/classify-edit-class.mts" --files <the CR's touched .feature files> [--base <baseref>]
+```
+
+A `narrowing`/`mixed` result on a still-`@frozen` file routes to **Clearance** (escalated unless the CR
+pre-authorized it); `additive`/`no-content-change` self-clears; `unfrozen-skip` needs no edit-class gate.
+`spec.md`
+/ the node READMEs are **kept aligned, never frozen** — editable, but may not contradict a frozen
+scenario (enforced by the alignment check and the judge, not a flat freeze). Vocabulary is
+**freeze/unfreeze**; "lock" is the concurrency layer.
+
+**Attribution.** A **human verdict** writes `approval.spec: { verdict: approve, by: <name> }` (no
+`why`) — only the in-session position may write this. A **self-assertion** already wrote
+`by: agent, why`; this skill only writes the matching `status`. **Ratifying** a queued
+self-assertion rewrites `by: agent` → `by: <name>` and drops it from the queue. Re-run the state
+check after any write to confirm the tuple is legal.
+
+## The gate digest (folded in-session)
+
+Assemble the **digest** inline (no spawned skill) — a read-only, decision-free summary so a
+ratifier sees *what* they are approving. It covers **only the CR's touched files**, aggregated;
+a touched area with **no** `.feature` reports **zero scenarios, not an error**. It **writes
+nothing, advances no status, renders no verdict**. Fixed sections:
+
+| Section | Source |
+|---|---|
+| **CR** | the `cr` id + its what/why |
+| **What** | the `## What` line of each touched capability's README |
+| **Status** | the spec's `status` |
+| **Scenarios** | the **added / modified / removed** `Scenario:` names across the touched `.feature` files, from a **mechanical diff** against the committed baseline — `npx gherkin-cli@0.0.2 diff --base <baseref> <file> --format json` (its `addOnly` confirms a purely additive change; a `modified`/`removed` scenario is flagged for **semantic** narrowing review — narrowing-vs-widening within a modified scenario stays a judgment). A **brand-new** suite with no committed baseline is listed with `npx gherkin-cli@0.0.2 parse <file>` (compact names / tags / counts) rather than re-tokenizing the raw file by hand |
+| **Key decisions** | the `### ` headings under `## Design decisions` in the touched prose |
+| **Open items** | every `<!-- open: ... -->` marker in the touched files |
+
+## Report
+
+- PASS / FAIL per lens, relayed from the judge
+- `ALIGNED: true | false`; if false, which artifacts are out of sync
+- Open markers / failing scenarios still blocking, if any
+- The leash derivation and the effective leash for this gate
+- On success: the new `status`, the approver (`agent` = provisional, in the review queue; `<name>` =
+  ratified), and which `.feature` files were frozen
+
+Do not fix issues automatically — report them for the user to address or confirm intent.