cyber-sdd 0.3.1 → 0.4.1

package/skills/spec-gate/scripts/check-suite.mts

@@ -6,7 +6,7 @@
 import { type Dirent, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { validateFeatures } from 'gherkin-cli'
+import { validate } from 'gherkin-cli'
 
 // ─── types ────────────────────────────────────────────────────────────────────
 
@@ -143,7 +143,7 @@ export interface ParseError {
 // Maps the pinned parser's per-file report to its errors (empty array when it parses) so callers
 // can look a path up directly.
 export function runGherkinValidate(paths: string[]): Map<string, ParseError[]> {
-	const { files } = validateFeatures(paths)
+	const { files } = validate(paths)
 	const out = new Map<string, ParseError[]>()
 	for (const f of files) {
 		out.set(

package/skills/spec-gate/scripts/classify-edit-class.mts

@@ -9,7 +9,7 @@
 // The classification is STRUCTURAL, never a raw git line-diff. A raw line-diff is fooled by a
 // trailing step orphaned off a frozen scenario onto a newly added adjacent scenario: the orphan
 // shows no `-` line and reads as purely additive, so a narrowing self-clears silently and
-// Clearance never fires. The pinned `gherkin-cli@0.0.2` `diffFeatures(paths, {base})` is AST-level
+// Clearance never fires. The pinned `gherkin-cli` `diffFeatures(paths, {base})` is AST-level
 // and is not fooled — it reports the losing baseline scenario as `modified` (`addOnly: false`).
 //
 // The pin is load-bearing, not incidental. Through `0.0.1` the differ's scenario identity covered
@@ -36,7 +36,7 @@ import { execFileSync } from 'node:child_process'
 import { readFileSync, realpathSync } from 'node:fs'
 import { dirname, join, relative, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { type DiffReader, diffFeatures, GitError } from 'gherkin-cli'
+import { GitError, diff as gherkinDiff, type ReadsGitDiff } from 'gherkin-cli'
 
 // ─── types ────────────────────────────────────────────────────────────────────
 
@@ -193,13 +193,13 @@ function readGitShow(base: string, path: string, cwd: string): string {
 	}
 }
 
-// Thin boundary around the pinned `gherkin-cli` `diffFeatures` — never a re-implemented differ.
+// Thin boundary around the pinned `gherkin-cli` `diff` — never a re-implemented differ.
 // classifyFromDiff / classifyFromFileResult carry the tested logic; this only wires the engine in.
-// Takes a batch of paths (`diffFeatures` is already variadic over paths) so a multi-file caller
+// Takes a batch of paths (`diff` is already variadic over paths) so a multi-file caller
 // pays for one parse pass, not one per file.
 export type GherkinDiffRunner = (base: string, paths: string[], cwd: string) => GherkinDiffOutput
 
-// `diffFeatures`'s default reader resolves each path via `path.resolve(file)` against
+// `diff`'s default reader resolves each path via `path.resolve(file)` against
 // `process.cwd()` and derives git's own cwd from THAT resolved location (`dirname` of the
 // resolved path, then `git ls-files --full-name` to recover the repo-relative path) — it never
 // trusts a caller-supplied cwd for the git commands at all. That self-derivation is why the
@@ -208,7 +208,7 @@ export type GherkinDiffRunner = (base: string, paths: string[], cwd: string) =>
 // This reader is the library's own extension seam ("Injectable so tests can skip git"), replicated
 // verbatim with the one substitution that matters here — `resolve(cwd, file)` instead of
 // `resolve(file)` — so a caller's `cwd` participates without discarding that self-correction.
-function makeCwdReader(cwd: string): DiffReader {
+function makeCwdReader(cwd: string): ReadsGitDiff['readDiff'] {
 	return (file, base) => {
 		const abs = resolve(cwd, file)
 		const dir = dirname(abs)
@@ -249,7 +249,7 @@ function makeCwdReader(cwd: string): DiffReader {
 }
 
 export const runGherkinDiff: GherkinDiffRunner = (base, paths, cwd) =>
-	diffFeatures(paths, { base, reader: makeCwdReader(cwd) })
+	gherkinDiff(paths, { base, full: true }, { readDiff: makeCwdReader(cwd) })
 
 // ─── per-file classification ────────────────────────────────────────────────────
 

package/skills/start-mission/SKILL.md

@@ -13,7 +13,47 @@ A CR is the **unit of change-intent** (git-PR-shaped); the mission loop is the w
 
 > **Advise a capable model (e.g. Opus) on entry.** The explore grill runs in this session, so its quality tracks the session model. Surface this **before** the grill so the user can switch if needed. (The harness cannot switch the session model on your behalf.)
 
-Load `sdd:lifecycle-governance` (status enum, the freeze re-open transition), `sdd:ownership-governance` (who writes each field), `sdd:spec-format-governance` + `sdd:suite-format-governance` (the node skeleton + suite bars), `sdd:spec-producer-governance` (the grilling procedure run inline), `sdd:impl-producer-governance` (what the spawned builder loads), `sdd:gate-validation-governance` (legal gate-state tuples), `sdd:remediation-governance` (how a producer answers a `change` verdict at either gate), and `sdd:combat-log-governance` (the provenance shapes). The autonomy bar is baked in (below).
+## Governances — load before you start
+
+You are **bound by** these bars, not merely aware of them. Read the **entry set** now, before
+Step 1 — each one governs every mission, so deferring it means acting unbound:
+
+| Governance | What it binds |
+|---|---|
+| `sdd:lifecycle-governance` | the status enum and the freeze re-open transition |
+| `sdd:ownership-governance` | who writes each field |
+| `sdd:spec-format-governance` | the node skeleton |
+| `sdd:suite-format-governance` | the suite bars |
+| `sdd:spec-producer-governance` | the grilling procedure you run inline |
+| `sdd:combat-log-governance` | the provenance shapes you write |
+| `sdd:gate-validation-governance` | the legal gate-state tuples you derive at both gates |
+
+The rest are **named now, read at the decision that invokes them** — each governs one moment rather
+than the run: `sdd:remediation-governance` (answering a `change` verdict — only when a judge returns
+one) and `sdd:impl-producer-governance` (what the spawned builder loads — at deliver). Naming them
+here is not loading them; load the body when you reach that moment.
+
+**Why `gate-validation` sits in the entry set although it fires only at a gate.** Every mission
+reaches a gate, and the set you declare is read downstream: the spec-judge's pre-flight derives its
+expected set from its **own** fixed-universal floor — which carries `gate-validation` — and checks it
+against the `producer_governances_declared` relay of your inline spec-producer's declaration
+(`sdd:sdd-spec-judge`). Deferring it makes that pre-flight fail by construction on a producer that
+did nothing wrong. Reach, not phase, decides the split.
+
+**Declare what you loaded.** On entry, state your own `governances_loaded` set — the same shape the
+spec-producer declares and you already relay as `producer_governances_declared`. The declaration is
+the conductor's, about the conductor: it makes a skipped load **visible instead of silent**. Declare
+the entry set at entry, and each deferred governance when you load it. Declare it **as it is** —
+never list a governance you did not read. Your declaration and the `producer_governances_declared`
+set you relay are **recorded separately; neither replaces the other** — one is what *you* loaded, the
+other is what the producer declared passing through you.
+
+The partition covers the conductor's **fixed-universal** bars only. A **resolved-actor** bar — one
+`resolve-governances` names per artifact-type, such as `sdd:spec-structure-governance` at placement —
+is neither entry-set nor deferred: it is resolved and loaded per touched file (Step 2), under the
+digest discipline there.
+
+The autonomy bar is baked in (below).
 
 ## Step 1 — intake: open the CR and scaffold the plan
 
@@ -32,7 +72,7 @@ Run authoring **in-session** as the conductor. Explore **builds the implementati
 
 **If plan mode is active, run the `### Plan-mode preview` (end of this step) instead of the live grill loop** — same reasoning, no repo writes, no build-to-learn spikes; the phase ends at **ExitPlanMode**, not the spec gate.
 
-**Resolution first.** Run `resolve-governances` over **only** the project registry `.agents/universal-plugin.json` (never scan plugin dirs), passing the current project's anchors (`--project`, plus `--project-root` in a monorepo — you know the project from `discover-specs` / context). For **each touched file's** `artifact-type` it names each production-chain role's agent (a plugin delegate or the SDD default) plus the resolved-actor bar **candidates bucketed by tier** (`project` / `project-root` / `plugin` / `sdd`). It does **not** compose — **load each candidate and compose them yourself** by precedence `sdd-default < plugin < project-root < project` (most-specific wins on conflict; a governance's own `compose: replace` supersedes its bar's lower-precedence candidates); the fixed-universal governances are loaded from the role/agent definition (the matcher does not emit them) — their **names** up front as a compact digest, each **body lazily** only at the gate/decision that invokes it (`gate-validation`/`lifecycle` at a gate, `suite-format` when authoring a `.feature`; `sdd` governance-resolution), so a one-line change never reads all six. A required role with no real delegate **fails closed**. A **resolved** delegate that **recuses** from a subject (produces nothing, declaring it outside its domain — e.g. a plugin bound by artifact-type meets a subject its lens does not fit) is **not** a fail-closed: **re-resolve that one unit's chain to the SDD defaults** (default producer + SDD-default bars + judge) and proceed, recording the recusal as a combat-log line (never a halt); other units keep their squad (`sdd:lifecycle-governance`). A domain claimed by two plugins → ask (answered live in-session).
+**Resolution first.** Run `resolve-governances` over **only** the project registry `.agents/universal-plugin.json` (never scan plugin dirs), passing the current project's anchors (`--project`, plus `--project-root` in a monorepo — you know the project from `discover-specs` / context). For **each touched file's** `artifact-type` it names each production-chain role's agent (a plugin delegate or the SDD default) plus the resolved-actor bar **candidates bucketed by tier** (`project` / `project-root` / `plugin` / `sdd`). It does **not** compose — **load each candidate and compose them yourself** by precedence `sdd-default < plugin < project-root < project` (most-specific wins on conflict; a governance's own `compose: replace` supersedes its bar's lower-precedence candidates); the fixed-universal governances are loaded from the role/agent definition (the matcher does not emit them) — the **entry set** is already read (above), and the **deferred** ones are read at the decision that invokes them (`remediation` on a `change` verdict, `impl-producer` at deliver), so a one-line change never reads the deferred bodies it never reaches. A required role with no real delegate **fails closed**. A **resolved** delegate that **recuses** from a subject (produces nothing, declaring it outside its domain — e.g. a plugin bound by artifact-type meets a subject its lens does not fit) is **not** a fail-closed: **re-resolve that one unit's chain to the SDD defaults** (default producer + SDD-default bars + judge) and proceed, recording the recusal as a combat-log line (never a halt); other units keep their squad (`sdd:lifecycle-governance`). A domain claimed by two plugins → ask (answered live in-session).
 
 For each unit the CR touches:
 
@@ -69,7 +109,7 @@ Run **only** when plan mode is active (the harness blocks every write except the
 
 On entering the gate, overwrite the statusline file with `spec gate` (same opt-in, best-effort write as explore — skip when plan mode escaped this step via ExitPlanMode).
 
-Run the spec gate as an **internal step** (not a user-invocable skill). Judge each touched unit suite against `sdd:suite-format-governance` (untagged scenarios boolean; `@rubric` well-formed) and the spec-format bars; load `sdd:lifecycle-governance` + `sdd:ownership-governance` + `sdd:gate-validation-governance` for the legal state tuple. **Never advance** with judge failures, open markers, or a suite that does not cover the spec. On a **change** verdict the findings are **evidence, not a work order**: substantiate each before acting, state the **rule** each instantiates and sweep for its other instances, re-derive every correction against the rule **governing the artifact** rather than against the finding alone, and account 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 instead of another round (`sdd:remediation-governance`). ("Regression" here is finding provenance, distinct from the grill loop's convergence above.) On **approve**: **freeze** each touched `.feature` via its `@frozen` tag, record a per-CR `gate` line in **your own shard** in the `ledger/` directory sibling to `spec.md`, and set `status: approved`. `spec.md` stays in sync, never frozen.
+Run the spec gate as an **internal step** (not a user-invocable skill). Judge each touched unit suite against `sdd:suite-format-governance` (untagged scenarios boolean; `@rubric` well-formed) and the spec-format bars; apply `sdd:lifecycle-governance` + `sdd:ownership-governance` + `sdd:gate-validation-governance` — all three already read at entry — for the legal state tuple. **Never advance** with judge failures, open markers, or a suite that does not cover the spec. On a **change** verdict the findings are **evidence, not a work order**: substantiate each before acting, state the **rule** each instantiates and sweep for its other instances, re-derive every correction against the rule **governing the artifact** rather than against the finding alone, and account 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 instead of another round (`sdd:remediation-governance`). ("Regression" here is finding provenance, distinct from the grill loop's convergence above.) On **approve**: **freeze** each touched `.feature` via its `@frozen` tag, record a per-CR `gate` line in **your own shard** in the `ledger/` directory sibling to `spec.md`, and set `status: approved`. `spec.md` stays in sync, never frozen.
 
 ## Step 3 — deliver: build to keep
 
@@ -104,6 +144,7 @@ Once landed, **do not spawn** the formation Warden. Surface a **one-line nudge**
 ## Autonomy, provenance, and the hard floor (baked in)
 
 - **Dispatch transport.** Every spawn beyond this session states a **dispatch intent** — role, brief, expected verdict schema — never a pinned command. When a harness-agnostic dispatch capability is available (detected at runtime; the concrete case is the Legate's `dispatch-governance` composing `cyberlegion` primitives — `agent resolve` + `unit spawn` + `mail await` — with **no** `dispatch` CLI verb, the seam named in the SDD project spec's `design/harness-spawning` node, repo-only), route through its intent seam and let it pick `subagent | channel | run-inline`, **preferring a warm unit** over a cold one-shot spawn; with no capability present, fall back to the portable cold subagent (depth-1) default — grader independence intact either way. **Warmth is a property of the unit/process; coldness of the context**: a judge's fresh-context guarantee (ADR-0016) is transport-agnostic — satisfied by a newly spawned cold subagent **or** a warm unit **context-cleared** to a fresh context before **each** judgment (re-deriving its oracle, carrying none of a prior round's context). Clear a warm unit with **`npx cyberlegion@0.3.1 unit clear <ref>`** (`<ref>` = unit id / handle / worktree branch or CR ref) — it injects the harness's own fresh-context command (`/clear` on Claude/Codex/Copilot, `/new-chat` on Cursor; fail-loud on a harness with no honest reset) so the **pane stays warm** while the **context goes cold**; it tears nothing down. The **impl-producer builder** instead stays warm and **keeps** its context across the explore spikes and the deliver build (never cleared between those uses). Warm units stay warm for **one mission** — reused within it, then **`unit clear`**'d or torn down at **handoff**, never carrying this mission's context into the next.
+- **SDD's own judges go to the seam by file, not by name.** A dispatch capability may resolve a definition by name only in the project's own agent folder (cyberlegion's `agent resolve` does), so it cannot find one SDD ships. When the judge role resolves to SDD's own `sdd-spec-judge` or `sdd-impl-judge`, locate the definition yourself at **`agents/<name>.md` under the SDD plugin root** — two levels above this skill's own base directory (`<skill dir>/../../agents/<name>.md`) — and hand the capability **that path** (cyberlegion: `agent resolve --file <path>`, `unit spawn --agent-file <path>`), never the bare name. If no file is there, send the capability **no request for that judge** (a by-name one would miss) and take the no-capability route: spawn it as a portable cold subagent through the harness's own plugin-agent spawn (`sdd:sdd-spec-judge` / `sdd:sdd-impl-judge`), which knows the plugin. A plugin-delegated judge is outside this rule.
 - **Initial strategy** (run start): assess blast radius + the other dimensions and emit a run-level `kind: leash` block to **your own ledger shard** (`ledger/<cr-ref>.<hash>.jsonl` — mint `<hash>` as 6 random hex **once per session** and reuse it for every line you append; `sdd:combat-log-governance`) — `leash` (`auto-none | auto-spec | auto-all`), `by: derived | user`, `approach[]`. It may be user-specified. This block is `kind: leash`, **not** `strategy` — `strategy` is the doctrine Scanner's alone. Ledger lines carry **no `ts`**.
 - **Per-gate verdict.** At each gate, derive the leash against discovered state and either **self-assert within leash** (write `approval.<gate>: { verdict: approve, by: agent, why }`; the spec lands in the async review queue) or **stop** with a verdict packet for the human. **Never advance** when any judge fails, any open marker remains, or (at the impl gate) any frozen scenario's verification does not pass. Human ratification (`by: <name>`, advance `status`) is reserved to the in-session position holding the user channel — by default you, in-session; a headless `automaton` emits the verdict packet and stops, **even when a coordinator relays "the user approved."**
 - **Combat log.** Append `report` / `correction` lines (and the halt that stopped you) to the plan's `*.log.jsonl` (these carry a UTC `ts`); your run-start `leash` block, self-asserted `gate` lines, and the handoff `followup` records go to **your own shard** in the durable `ledger/` directory sibling to `spec.md` — never another writer's shard, never a shared file (`strategy` there is the Scanner's alone). Free text is commit-message-grade — never code, prompts, secrets, or literal values.

package/skills/touch-set-correction/scripts/touch-set-correction.mts

@@ -13,7 +13,7 @@
 //     a live git diff or the live mission-graph store.
 //   - readChangedFiles / resolveArtifactType / changedScenarios / collectChangedFiles /
 //     discoverLayouts are the thin IO SEAM: they shell out to `git`, `resolve-governances.mts`, and
-//     the pinned `gherkin-cli@0.0.2` `diffFeatures` (the same differ classify-edit-class.mts uses —
+//     the pinned `gherkin-cli` `diff` (the same differ classify-edit-class.mts uses —
 //     this tool never reimplements a differ). NOT unit-tested (binary/fs boundary) — the tested
 //     logic is everything downstream of the file list.
 //   - main() is a thin CLI: argv -> collectChangedFiles + assembleCorrection, rendering TOON by
@@ -30,7 +30,7 @@ import { execFileSync } from 'node:child_process'
 import { readFileSync, realpathSync } from 'node:fs'
 import { dirname, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { type DiffReader, diffFeatures } from 'gherkin-cli'
+import { diff as gherkinDiff, type ReadsGitDiff } from 'gherkin-cli'
 
 // ── Types ──
 
@@ -226,7 +226,7 @@ export function resolveArtifactType(path: string, root: string, cwd: string): st
 	}
 }
 
-// `diffFeatures`'s default reader resolves paths against `process.cwd()` and derives git's own cwd
+// `diff`'s default reader resolves paths against `process.cwd()` and derives git's own cwd
 // from that resolved location (`git ls-files --full-name` to recover the repo-relative path) —
 // this reader is that same algorithm, re-pointed at `cwd` (same seam classify-edit-class.mts
 // uses), so it stays robust to a caller whose relative-path bookkeeping doesn't line up with its
@@ -234,7 +234,7 @@ export function resolveArtifactType(path: string, root: string, cwd: string): st
 // reads as "absent" — the outer `changedScenarios` catch-all is this call site's real fail-open
 // boundary, so a thrown `GitError` here is caught there rather than escalated.
 const cwdReader =
-	(cwd: string): DiffReader =>
+	(cwd: string): ReadsGitDiff['readDiff'] =>
 	(file, base) => {
 		const abs = resolve(cwd, file)
 		const dir = dirname(abs)
@@ -272,15 +272,15 @@ const cwdReader =
 		return { head, base: baseText }
 	}
 
-/** The changed scenario names of a touched `.feature`, via the pinned `gherkin-cli@0.0.2`
- *  `diffFeatures` (same tool classify-edit-class.mts uses — never a reimplemented differ). Gated
+/** The changed scenario names of a touched `.feature`, via the pinned `gherkin-cli`
+ *  `diff` (same tool classify-edit-class.mts uses — never a reimplemented differ). Gated
  *  by isFeature — a non-.feature never calls out. On any failure returns []. Reads any `.feature`
  *  regardless of freeze — the freeze gate is a separate concern (spec-gate), not this tool's
  *  business. */
 export function changedScenarios(base: string, path: string, cwd: string): string[] {
 	if (!isFeature(path)) return []
 	try {
-		const { files } = diffFeatures([path], { base, reader: cwdReader(cwd) })
+		const { files } = gherkinDiff([path], { base, full: true }, { readDiff: cwdReader(cwd) })
 		const fileResult = files.find((f) => f.file === path) ?? files[0]
 		return (fileResult?.scenarios ?? []).filter((s) => s.change !== 'unchanged').map((s) => s.name)
 	} catch {

package/skills/verify-scenarios/scripts/verify-scenarios.mts

@@ -49,7 +49,7 @@ import { execSync } from 'node:child_process'
 import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { isAbsolute, join } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { parseFeatures } from 'gherkin-cli'
+import { parse } from 'gherkin-cli'
 
 // Resolves a path argument against `--root`: relative paths join beneath root (which defaults to the
 // current directory); an absolute path is used verbatim, never double-prefixed under root.
@@ -132,7 +132,7 @@ export function scenarioKeysFromParse(parsed: GherkinParseOutput): ScenarioKey[]
 // `--feature-root` — see main()).
 export function getScenarioKeys(root: string, featurePath: string, featureRoot: string = root): ScenarioKey[] {
 	const abs = underRoot(featureRoot, featurePath)
-	return scenarioKeysFromParse(parseFeatures([abs]))
+	return scenarioKeysFromParse(parse([abs]))
 }
 
 // ── JUnit parsing (hand-rolled, no xml dep) ──