cyber-sdd 0.0.0 → 0.2.0

package/skills/concept-index/scripts/concept-index.mts

@@ -9,8 +9,9 @@
 // reaches the output. No dependencies (the repo's node-≥23.6 / no-deps convention). Pure functions
 // are exported for node:test; running the file directly drives the CLI.
 
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 export const BEGIN_MARKER = '<!-- BEGIN generated: by-concept (project-spec/concept-index) -->'
 export const END_MARKER = '<!-- END generated: by-concept -->'
@@ -240,6 +241,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
 	process.exit(main(process.argv.slice(2)))
 }

package/skills/discover-plans/scripts/discover-plans.mts

@@ -18,8 +18,9 @@
 // No dependencies (the repo's node-≥23.6 / no-deps convention). --format json for a flat
 // array; default output is TOON (the token-efficient tabular form the gateway scans).
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 export const TODO_STATUSES = new Set(['pending', 'in_progress', 'completed'])
 
@@ -209,4 +210,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.main) process.exit(main(process.argv.slice(2)))
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/discover-specs/scripts/discover-specs.mts

@@ -26,8 +26,9 @@
 // default output is TOON (the token-efficient tabular form the gateway scans). --resolve <name>
 // filters to the exact name matches (0 rows = none, 1 = resolved, >1 = ambiguous).
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 export const LIFECYCLE_STATUSES = new Set(['draft', 'approved', 'implemented', 'deprecated'])
 
@@ -393,4 +394,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.main) process.exit(main(process.argv.slice(2)))
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/doctrine-loop/README.md

@@ -12,4 +12,10 @@ the one project `ledger/` directory. The entry **shape** and the matchable `caus
 `sdd:combat-log-governance` (deferred, never restated). The Council holds keep-or-cut; the `sdd`
 gateway surfaces the count of pending unratified strategy when the Council re-enters.
 
+Separately, during its pass, the Scanner also cross-checks each plan brief's `todos-all-done`
+against its `source-closed` to **derive the retirement clearance set** — it never autofixes a
+plan's `status`; agreement feeds `sdd:plan-retirement`'s existing `--retire` input, disagreement
+surfaces a flagged finding in the Scanner's pass summary. This is distinct from strategy-drafting
+above: a flagged finding is never a ledger write.
+
 Plan retirement (doctrine's last retro step) is the sibling `sdd:plan-retirement` skill.

package/skills/doctrine-loop/SKILL.md

@@ -46,6 +46,40 @@ Each is an entry-point: a lifecycle-grained trigger, its post-hoc input, and the
 
 The Scanner **observes** the terminal transitions; it never writes a mission's `status`.
 
+## Idempotent Ship/Kill: detect an already-distilled mission by parsing the ledger, never grepping
+
+The **Ship** (`→ implemented`) and **Kill** (`→ deprecated`) triggers can meet the **same** terminal
+transition more than once — a later pass, a resumed segment, a fresh re-invocation. So they are
+**idempotent**: **before drafting** Ship/Kill strategy for a mission, first detect whether that
+mission was **already distilled** — a prior `strategy` entry whose **`distills` field equals the
+mission's `<cr-ref>`** — and if so, **draft nothing** (no duplicate strategy for a mission already
+recorded as distilled).
+
+**Determine distilled-ness by a structured JSONL parse, never a substring or regex text match.**
+The ledger shards are JSONL (one JSON object per line). **Reuse the existing parse contract** rather
+than hand-rolling one: run the exported **`distilledCrRefs`** engine from
+`../plan-retirement/scripts/retire-plans.mts` over the project `ledger/` directory and membership-test
+the mission's `<cr-ref>` against the set it returns, e.g.
+
+```
+node -e 'import("../plan-retirement/scripts/retire-plans.mts").then(m => console.log([...m.distilledCrRefs(process.argv[1])].join("\n")))' <ledger-dir>
+```
+
+`distilledCrRefs` parses **each line** with `JSON.parse` (keying only on `kind === "strategy"` with a
+non-empty `distills`), so it is correct against **any** valid-JSON formatting the Scanner or another
+writer emits — a **space after the colon** in a pretty-printed entry (`"distills": "<cr-ref>"` vs
+`"distills":"<cr-ref>"`), a line-wrapped or reordered object — where a naive no-space substring grep
+(`"distills":"<cr-ref>"`) **silently under-counts**, reports an already-distilled mission as
+undistilled, and **re-drafts** it. This is the same defect class as *grep is blind to wrapped terms*;
+a distilled-detection that under-counts causes false "undistilled" conclusions and wasted or duplicate
+drafting.
+
+Reusing the engine also inherits its exact semantics: it keys on the **structured `distills` field
+only** (an `<cr-ref>` appearing merely inside another entry's `evidence` cross-references does **not**
+count as distilled), **tolerates malformed and blank lines** (they are skipped, not fatal), and counts
+an **unratified** distilling entry — the Scanner's default — the same as a ratified one (the question
+is what was distilled, not sign-off). This is a **read** over the ledger; it changes nothing you write.
+
 ## Inputs: combat log (contract) vs transcripts (enrichment)
 
 The Scanner reads **persisted artifacts post-hoc** — never live subagent context.
@@ -64,6 +98,81 @@ post-merge loop keeps the dimension; the **numeric** breakdown lives only in tra
 never under it without a request). No raw token-cost number is written to the committed log — only
 the categorical class (the safe-to-publish floor, `sdd:combat-log-governance`).
 
+## Validate before drafting — a plan or log is a hypothesis, not present truth
+
+A persisted plan, combat log, or ledger line is **history**, never authoritative present truth. Every
+candidate improvement it surfaces — a gap to build, a defect to fix — is a **hypothesis about the
+current codebase** (the repo's own principle: *a source-read is a hypothesis, refuted by a repro
+against current code*). **Before you draft**, run a validation gate on each candidate: read the
+CURRENT code and decide whether the flagged gap still exists, or has since been **built / fixed /
+superseded** (by a later mission, a landed PR, a governance change).
+
+- **Resolved → cut.** A candidate current code already resolves is **cut**: draft **no** build-or-fix
+  strategy and emit **no** issue. Record the cut **explicitly, never silently** — append a `strategy`
+  entry marked **`disposition: resolved`** to your own shard, carrying the **resolving current-code
+  evidence** (the repro that refuted the hypothesis) in `evidence`. A `disposition: resolved` line is
+  a **tombstone**: not an actionable recommendation, so it emits no issue and is **not counted toward
+  pending strategy** at the gateway. It exists so the cut is auditable and a later run does not
+  silently re-surface the same closed candidate.
+- **Still open → draft.** A candidate current code does **not** resolve is a real improvement: draft
+  `strategy` for it marked **`disposition: open`** (the default; a line without the field grandfathers
+  as open), which counts toward pending strategy, and emit its issue (below).
+
+The gate applies to any candidate that asserts an **unmet gap or defect**, whether surfaced by a
+**plan or a combat log** (symmetric — each source has both a resolved→cut and a still-open→draft
+path). A pure distilled **retro lesson** (a success pattern, not a gap claim) carries no gap to
+validate and is drafted without a current-code check. Set the disposition **once at write** — never
+flip it (append-only); the Council's later keep-or-cut on a `disposition: open` line is a separate act
+(the keep-or-cut plan), not a field edit. The `disposition` field's shape is owned by
+`sdd:combat-log-governance`.
+
+This gate is what stops the loop reinforcing a **stale cache** — drafting "build X" for an X a later
+mission already built.
+
+## Cold-instrument evidence — non-author measurement + ablation before a rule-level recommendation
+
+A self-authored measurement is untrustworthy exactly when it grounds a **rule-level decision**: the
+author's own blind spot is baked into the instrument meant to catch it (op6/#224 — a masked generator
+"proved" its own conclusion twice, each ratified then walked back; op6-m5/#254 — a proposed revival
+measured Δ=0 dead weight, caught before landing). Two rules extend the validate-before-drafting gate to
+your rule-level recommendations. This is **the canonical statement** of the non-author-evidence
+standard — other faces (`sdd:spec-producer-governance`'s dimension/cut grounding) reference it.
+
+- **Non-author evidence.** Draft a recommendation to **adopt a rule, drop a rule, or set a threshold**
+  only when its grounding measurement was **produced by a party other than the proposer, *or*
+  independently reviewed by such a party, *or* ablated against a freshly and adversarially constructed
+  case**. A measurement on the proposer's **own generator or harness alone** is **withheld**: draft no
+  recommendation on it, and record that it needs non-author or fresh-adversarial evidence. A measurement
+  grounding **no** rule-level decision is unconstrained by this rule.
+- **Ablation before landing a revival.** Draft a candidate **reviving a dead measurement dimension** to
+  land only when an ablation against a control shows the dimension is **loseable**; **state the revived
+  rule abstractly with no worked example** (lifting a probe scenario's apparatus into the rule is
+  **absorption** — the probe then grades nothing). A revival whose ablation shows **no difference** from
+  the control is **dead weight**: **cut** it (a `disposition: resolved` tombstone, as above) and draft
+  no land recommendation.
+
+## Improvement output — validated-open findings become tracked issues
+
+The loop's **actionable output** for a validated-open improvement is a **new tracked issue**
+(`gh issue create`) — one titled, bodied issue per real improvement, **cross-linking the evidence**
+that drove it. This grounds the improvement plan in current code, not the stale narrative of a retired
+plan. The ledger `strategy` line stays the **provenance**; the issue is what a later mission is started
+from.
+
+- **Dedupe first.** Before filing, dedupe against the forge's existing issues — **open and closed**
+  (at least two keyword combinations: the full title, then the core noun/verb) — and on a mixed set
+  file only the unmatched.
+- **Emit is not dispatch.** Emitting an issue leaves the `strategy` **unratified** and spawns **no**
+  mission — it opens no CR and admits nothing to the mission graph (that is the graph's single writer's
+  act). Keep-or-cut stays the Council's; the issue re-enters SDD only when a **later** mission is
+  started from it.
+- **Outward-publish floor.** Compose the issue body to the same outward-publish floor the handoff
+  follow-up issues meet (owned by the handoff unit — do not restate it): **self-contained** (a reader
+  who cannot see the mission's internal artifacts can act on it), **no production-internal artifact
+  reference** (no ledger shard filename, no combat-log or plan-brief path), plus everything the
+  committed-record floor bans (absolute paths, `$HOME`/`$USER`, usernames, secrets, raw numbers).
+  Carry an **agent-filed marker** and name the evidence it was distilled from.
+
 ## Where strategy lands
 
 Every `strategy` entry lands in the **one project ledger** — the `ledger/` directory sibling of the
@@ -72,7 +181,9 @@ random hex once per session), so two concurrent Scanner runs write distinct shar
 There is no per-spec log to route to under the project-spec model. The Scanner's `handle` is
 `sdd-scanner`. Every entry is **unratified** (`ratified: false`) and carries its **driving evidence**
 (the distilled `cause` recurrence that drove it), per the shape in `sdd:combat-log-governance`. The
-shard is append-only — the next `seq` within it, never an edit; ledger lines carry **no `ts`**.
+shard is append-only — the next `seq` within it, never an edit; ledger lines carry **no `ts`**. Every
+entry also carries its validation **`disposition`** (`open` for a drafted still-open improvement,
+`resolved` for a validation tombstone; see *Validate before drafting* above) — set once at write.
 
 **Record the distilled subject.** When the entry is drafted from a **Ship** (`→ implemented`) or
 **Kill** (`→ deprecated`), set `distills: <cr-ref>` to the **one mission it was distilled from** —
@@ -90,8 +201,31 @@ strategy re-enters as a **new CR** that re-tunes the doctrine and grows the corp
 **PRUNE** removes the stale convention). On **cut**, it stays unratified and absent from the
 corpus.
 
+## Stale plan frontmatter — deriving the retirement clearance set, never autofixing status
+
+A plan brief's frontmatter `status` can lag reality (its own todos finish, or its source issue
+closes, without the value being flipped) but there is **no legal terminal value** to autofix it
+into — the plan-level `status` is a two-value dispatch flag (`active | approved`), and the
+contract's own answer to "this mission is over" is **retirement**, not a status write
+(`sdd:combat-log-governance`'s home, `design/provenance-model.md`). So during its pass, for each
+brief under `.agents/plans/`, the Scanner cross-checks `todos-all-done` (every `todos[].status`
+completed) against `source-closed` (the declared `source` queried natively, the same way
+`plan-retirement`'s own clearance check queries it) — never writing `status` either way:
+
+- **Both agree terminal** → the cr-ref is included in the **retirement clearance set** the Scanner
+  passes as `plan-retirement`'s existing `--retire` input. No new deletion mechanism —
+  `plan-retirement` still runs its own gated sweep.
+- **Both agree non-terminal** → no clearance, no finding.
+- **They disagree** → excluded from the clearance set; the Scanner surfaces a flagged finding
+  naming the disagreement in its pass summary (its only channel — it returns only its final
+  message), for a human to resolve. A flagged finding is ephemeral and never a ledger write — it
+  is neither a `kind: strategy` entry nor a `kind: report` line, and it is distinct from the
+  validated-open-improvement finding above that becomes a tracked issue.
+
 ## Plan retirement
 
 Doctrine's **last retro step** — the gated, idempotent **tracked deletion** of a retired plan — is
 a separate unit (`sdd:plan-retirement`). The distill (writing `strategy` here) fires early, at
-`→ implemented`; the delete is a later step gated on source = `done`/merged **and** distilled.
+`→ implemented`; the delete is a later step gated on source = `done`/merged **and** distilled. The
+source-cleared set `plan-retirement` consumes via `--retire` is, per above, the Scanner's derived
+retirement clearance set — never a raw, uncross-checked source-only judgment.

package/skills/formation-loop/SKILL.md

@@ -67,7 +67,7 @@ structure and discovery (`corpus/` + `project-spec/`), not on any given station
 | 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 |
+| **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 whose **organizing axis is first checked against a real capability/command boundary** (below); 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) |
 
@@ -76,6 +76,26 @@ raises **no** untagged finding; nodes (or governances) that **agree** raise **no
 two nodes that specify **no** shared behavior raise **no** dedup finding. The acts are evidence-gated,
 not run unconditionally.
 
+**The split-axis check — validate the organizing axis, not just the granularity.** An oversized node
+is a **granularity** signal, but a split carves it along a proposed **organizing axis**, and the
+wrong axis produces a split CR that gets **superseded rather than landed** — a full formation cycle
+wasted. So before proposing a split (self-clearing it or escalating its CR), the Warden **checks the
+proposed axis against a real capability/command boundary**: each side must map to a **distinct
+capability, command, or lifecycle phase**, not merely to an **internal implementation grouping** that
+shares one boundary.
+
+- an axis where each side is a distinct capability/command boundary **passes** — the split is
+  proposed on that axis;
+- an axis that only regroups internal implementation under one shared boundary **fails** — the Warden
+  does **not** carve sub-nodes on it, and raises the oversize as a **wrong-axis reorganization** (the
+  axis is wrong), not a granularity split to carve as-proposed.
+
+An oversize can be a symptom of the **wrong axis**, not just wrong granularity: turn "this node is too
+big" into "too big **along which axis** — and is that axis real?" (Precedent: a killed
+`identity/`→`presence/` split proposed a plausible-but-unreal axis and was superseded by a realignment
+that split along the package's actual command boundary; the producer/consumer boundary had even been
+validated as sound, yet the *split axis* was never checked against a real command boundary.)
+
 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

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

@@ -25,7 +25,7 @@ rules by reading frontmatter. The `(status, markers, .feature, approval)` tuple
 - 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>` has an off-enum `cause` (not `dimension` / `clearance` / `ceiling`) **without** a `cause-candidate: true` flag — the stop cause is a closed enum grown only by ratification, so an unflagged off-enum value fails closed; a `cause-candidate: true`-flagged off-enum value is **legal** (the off-enum candidate discipline, `sdd:combat-log-governance`).
 - 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.
@@ -83,5 +83,5 @@ A required production role **always** resolves to a real producer — a plugin a
 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
+**unflagged** off-enum `cause` (a `cause-candidate: true`-flagged one is legal; `sdd:combat-log-governance`). Distinct from availability: a recorded
 producer whose plugin is merely uninstalled is **flagged**, not blocked.

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

@@ -47,6 +47,14 @@ MODE: explore | implement
    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.
 
+   **Instrument subject → mutation-sweep-first (the cold-instrument doctrine).** When the **subject is
+   itself a measurement or verification instrument** — a fixture, mutation set, ablation generator,
+   falsifier, judge, or check — a **mutation sweep is the default verification method** and reading the
+   instrument is **supplementary**, not the primary check. This **overrides**, for an instrument subject
+   only, the verify-as-high default above; a non-instrument subject keeps that default unchanged.
+   Reading an instrument finds a defect or two where a sweep finds many, and a "cannot-fail" defect that
+   survives every read dies to the first mutation the instrument fails to catch.
+
 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`).
@@ -80,6 +88,7 @@ OBSERVATIONS:         [ { owner: architect | strategist, note, evidence } ]
 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).
+   tests (the pyramid base). **An instrument subject** (fixture / mutation set / ablation generator /
+   falsifier / judge / check) inverts the default: **mutation-sweep-first**, reading supplementary.
 5. **Never modify `spec.md` / the suite; never touch a `@pinned` scenario without user
    authorization.**

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

@@ -25,9 +25,10 @@
 // fresh wire ever adopts it.
 // Pure functions are exported for node:test; running the file directly drives the CLI. No deps.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 export const STATUS_FILE = '.agents/sdd/statusline'
 export const SETTINGS_FILE = '.claude/settings.json'
@@ -273,4 +274,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.main) process.exit(main(process.argv.slice(2)))
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/lifecycle-governance/SKILL.md

@@ -24,7 +24,7 @@ approval:               # per-gate verdict
   spec:                 # verdict: approve | pause | reject
     verdict: approve
     by: agent           # agent (self-asserted, provisional) | <human name> (ratified); omitted on pause
-    cause: dimension    # dimension | ceiling — what drove the verdict
+    cause: dimension    # dimension | clearance | ceiling — what drove the verdict (off-enum → flag cause-candidate: true)
     why:                # verdict derivation (agent self-assertion or pause)
       floor:       <none | clearance | conflict | compatibility | consent>
       blast:       <low|high — reason>

package/skills/manage-ignore/scripts/manage-ignore.mts

@@ -17,8 +17,9 @@
 // Pure functions are exported for node:test; running the file directly drives the CLI. No deps
 // (the repo's node-≥23.6 convention).
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 const IGNORE_FILE = '.agents/sdd/.sddignore'
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
@@ -291,4 +292,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.main) process.exit(main(process.argv.slice(2)))
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/manage-scenario-bridge/scripts/manage-scenario-bridge.mts

@@ -22,8 +22,9 @@
 // Pure functions are exported for node:test; running the file directly drives the CLI. No deps (the
 // repo's node-≥23.6 convention).
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { parseSourcesToml, type SourceConfig } from '../../verify-scenarios/scripts/verify-scenarios.mts'
 
 export type { SourceConfig }
@@ -153,4 +154,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.main) process.exit(main(process.argv.slice(2)))
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/manage-spec-anchors/scripts/manage-spec-anchors.mts

@@ -17,8 +17,9 @@
 // are implicit and cannot be curated here.
 // Pure functions are exported for node:test; running the file directly drives the CLI. No deps.
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 const ANCHORS_CONFIG = '.agents/sdd/spec-anchors.toml'
 const LIFECYCLE_STATUSES = new Set(['draft', 'approved', 'implemented', 'deprecated'])
@@ -325,4 +326,6 @@ export function main(argv: string[]): number {
 	return 0
 }
 
-if (import.meta.main) process.exit(main(process.argv.slice(2)))
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/mission-graph/README.md

@@ -3,11 +3,9 @@
 The concrete engine for the **mission-graph kernel** — a git-tracked, append-only work-graph store
 (nodes, edges, status, tombstones, schema `v:1`) folded into a read-only `ready` frontier and a
 `cycles` repair view, plus an Operation deliverability check. Built for Op1.M1 of the
-**cyberfleet-batch** change request; see
-[`.agents/specs/sdd/mission-graph/README.md`](../../../../.agents/specs/sdd/mission-graph/README.md)
-for the authoritative behavior description and
-[`mission-graph.feature`](../../../../.agents/specs/sdd/mission-graph/mission-graph.feature) for
-the frozen 36-scenario contract.
+**cyberfleet-batch** change request; the `mission-graph` node of the SDD project spec (in the
+cyberplace repository, not shipped in this package) carries the authoritative behavior description
+and the frozen 36-scenario contract.
 
 - **Skill contract:** [`SKILL.md`](./SKILL.md)
 - **Script:** [`scripts/mission-graph.mts`](./scripts/mission-graph.mts)

package/skills/mission-graph/SKILL.md

@@ -25,8 +25,9 @@ plus a zero-dependency **fold** into two read-only views and one write-time guar
 
 It carries a self-contained `.mts` script (the repo's node-≥23.6 / no-deps convention). Pure
 derivations (`fold`, `ready`, `cycles`, `checkOperation`, `proposeEdge`) take and return plain data
-only — no fs access — kept apart from a thin store-IO seam (v1: an in-tree JSONL file) so a later
-swap to a shared, branch-independent store never touches them.
+only — no fs access — kept apart from a thin store-IO seam with **two backends**: an in-tree JSONL
+file and the branch-independent orphan ref `refs/sdd/mission-graph`, resolved at run time. The swap
+never touches a derivation.
 
 ## Run it
 
@@ -45,11 +46,77 @@ node "<skill>/scripts/mission-graph.mts" append edge --kind RAW|parent-child|dis
 
 node "<skill>/scripts/mission-graph.mts" append tombstone --target node --id <id>
 node "<skill>/scripts/mission-graph.mts" append tombstone --target edge --kind <kind> --from <id> --to <id>
+
+# store home + reach (idempotent; --root defaults to .)
+node "<skill>/scripts/mission-graph.mts" migrate  [--root .]
+node "<skill>/scripts/mission-graph.mts" sync     [--root .] [--remote origin]
 ```
 
-- Default `--root` is the current directory; the store lives at
-  `<root>/.agents/mission-graph/events.jsonl`. Default `--format` is **TOON**; `--format json`
-  emits the same records as JSON for non-LLM consumers.
+- Default `--root` is the current directory. The store home is resolved at run time — the orphan ref
+  `refs/sdd/mission-graph` inside a git work-tree, else the in-tree file
+  `<root>/.agents/mission-graph/events.jsonl`; `MISSION_GRAPH_STORE=in-tree|orphan-ref` overrides.
+  Default `--format` is **TOON**; `--format json` emits the same records as JSON for non-LLM
+  consumers.
+- **`migrate` retires the in-tree seed** after copying it into the ref — `git rm` the store file,
+  leaving the deletion **staged, not committed** (the engine's only working-tree write; it reports that
+  the commit is required for the migration to reach other clones). **Why it is not optional:** the seed
+  is a *tracked* file, so a seed left behind travels to every clone, where `resolveBackend` prefers it
+  over the (never-fetched) ref — the clone reads a **stale list that looks valid** and no `sync` can
+  dislodge it, because the seed is precisely what stops the clone consulting the ref. Two guards:
+  it **refuses** to retire a seed whose every line is not already in the ref (deleting otherwise would
+  be the data loss migration exists to avoid), and it **does** retire a seed an earlier migration left
+  behind, so a pre-fix project is repaired by re-running `migrate`.
+- **Reach.** `refs/sdd/*` is outside `refs/heads/*`, so git's default refspec never fetches or
+  pushes it: the ref is shared by every **worktree of one clone** and travels no further on its own.
+  `sync` is the one step that widens that reach.
+- **`sync` names the ref explicitly on its own command line**, so it needs **no git configuration and
+  writes none** — not a fetch refspec, not a push refspec. Verified: a fresh clone carrying only the
+  default `+refs/heads/*:refs/remotes/origin/*` fetches the store ref fine when the refspec is given
+  as an argument. The engine never touches `.git/config`.
+- **No refspec is ever written in its forced (`+`-prefixed) form.** A leading `+` means *force*: with
+  `+refs/sdd/*:refs/sdd/*` in play, a diverged store ref is overwritten at **exit 0** with
+  `(forced update)`, silently destroying the local appends — the exact data loss the compare-and-swap
+  write path exists to prevent. Non-forced, the same transfer reports
+  `! [rejected] (non-fast-forward)` and **exits 1**, leaving the ref intact.
+- `sync` is **fast-forward only**, in both directions. Its cases are a **total partition** of
+  `(local ref, remote ref)` — each side present or absent, and when both are present the pair is
+  exactly one of identical / one an ancestor of the other (either way) / neither:
+
+  Two checks run **before** the partition, in this order — (1) **backend**: under the in-tree backend,
+  no-op reporting the home, exit 0, no network touched (an in-tree project must not fail merely for
+  being offline); (2) **reachability**: a remote unreachable *or not configured* fails non-zero and is
+  **never** reported as "remote has none". Then:
+
+  | local | remote | action |
+  |---|---|---|
+  | absent | absent | report **both absent**, change nothing |
+  | present | absent | push |
+  | absent | present | collect |
+  | present | present, same commit | report agreement, change nothing |
+  | present | present, local is ancestor | fast-forward local |
+  | present | present, remote is ancestor | push |
+  | present | present, neither is ancestor | **refuse loudly**, report both tips, change nothing |
+
+  There is no `--force`; divergence means two write-deciders, which the store surfaces rather than
+  resolves. **The reachability row is load-bearing:** `git ls-remote` fails the same way for an
+  unreachable remote as for a missing ref, so a naive read conflates them and lands on "both absent" —
+  reporting a benign empty state for a remote it never saw. That is the silent-empty defect this whole
+  capability exists to remove; establish reachability first and fail non-zero when it cannot be
+  established.
+- **Making an ordinary `git fetch` collect the ref too is out of scope here.** That means writing a
+  persistent fetch refspec into a clone's config — an opt-in, per-clone setup act with a real cost (a
+  diverged store ref then makes unrelated `git fetch` calls exit 1). It belongs to the onboarding
+  skill that already asks consent before writing operational config, not to this engine.
+- **Recovering from a refused sync.** The refusal names both tips. Read each side's log with
+  `git cat-file -p <tip>:events.jsonl`, then — as the single write-decider — rebuild one list holding
+  both sides' events and append it forward from the tip you keep. The store is append-only, so no
+  event is dropped by that reconcile; `sync` does not automate it, because choosing the surviving
+  order is a decision, not a merge.
+- **Never configure `remote.<remote>.push`.** Setting it *replaces* the default branch push refspec,
+  so a plain `git push` silently stops sending the current branch while reporting
+  "Everything up-to-date". `sync` passes its push refspec as an argument and writes no push config.
+- **`sync` is orphan-ref-only.** Under the in-tree backend it is a **no-op** that reports the active
+  backend — an in-tree store rides its branch and needs no ref transport.
 - `append edge` runs the **write-time cycle guard** first: a RAW edge that would close a loop is
   **rejected** unless `--override` is passed (a genuinely-discovered mutual dependency). A
   parent-child/discovered-from edge is never guarded — only RAW ("wait for") edges can cycle.