cyber-sdd 0.6.1 → 0.7.0

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

@@ -0,0 +1,12 @@
+// Launcher for the engine of the same name. Run it as `node <skill>/scripts/<engine>.mjs`.
+// A checkout runs the .mts source. An npm install keeps the skill under node_modules, where Node
+// will not strip types, so it runs the self-contained bundle built for the package.
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const self = fileURLToPath(import.meta.url)
+const installed = /[\\/]node_modules[\\/]/.test(self)
+const target = self.replace(/\.mjs$/, installed ? '.bundle.mjs' : '.mts')
+const run = spawnSync(process.execPath, [...process.execArgv, target, ...process.argv.slice(2)], { stdio: 'inherit' })
+if (run.error) throw run.error
+process.exitCode = run.status ?? 1

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

@@ -43,7 +43,7 @@ USER_ANSWERS:     <answers to previously returned QUESTIONS — or null>
 5. **Self-check the `.feature` form before returning.** Run the deterministic form check — the `check-suite` engine (`scripts/check-suite.mts` in the `spec-gate` skill), the executable form of `sdd:suite-format-governance` — scoped to what you just authored:
 
    ```bash
-   node "<spec-gate skill>/scripts/check-suite.mts" --files <the authored .feature path(s)>
+   node "<spec-gate skill>/scripts/check-suite.mjs" --files <the authored .feature path(s)>
    ```
 
    Exit `0` = form clean; exit `1` prints each `✗ <file>: <reason>`. **Fix every violation** (a non-boolean/hedged `Then`, leaked rubric lingo in an untagged scenario, a missing `Feature`/`Then`, or missing section comments over the sectioning threshold) and re-run until clean **before reporting `STATUS: complete`**. Settling this mechanical bar here spends no cold-judge round on a defect a linter catches every time; the same engine runs fail-closed at the gate (`../spec-gate/`), so an unfixed violation would block there anyway. If `node` is unavailable, self-review against the suite-format bar by hand.
@@ -62,7 +62,7 @@ USER_ANSWERS:     <answers to previously returned QUESTIONS — or null>
    the `spec.md`/`README.md` you just authored or touched:
 
    ```bash
-   node "<spec-gate skill>/scripts/check-spec-state.mts" --files <the authored spec.md/README.md path(s)>
+   node "<spec-gate skill>/scripts/check-spec-state.mjs" --files <the authored spec.md/README.md path(s)>
    ```
 
    Exit `0` = every referenced path resolves; exit `1` prints each `✗ <file>: references nonexistent

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

@@ -21,8 +21,10 @@ Read `SKILL.md` beside this file for the law itself — that is what those four
 - **The node taxonomy** — descriptive, reference artifact, behavioral artifact; declared in
   frontmatter, never guessed from which files happen to exist.
 - **Placement** — screaming architecture (folders named for capabilities), the three deliberate
-  non-capability folders, rules-in-design vs behavior-in-capability, the two-level depth cap, and
-  the concept axis for anything that cuts across.
+  non-capability folders, rules-in-design vs behavior-in-capability, the two-level depth cap on
+  capability nodes, the concept axis for anything that cuts across, and the shape of `design/` —
+  the current design at the top and, while one is under construction, the next design in a version
+  folder beside it.
 - **One spec per project** — and when a spec is hoisted out of its project directory rather than
   colocated in it.
 - **Strategy is policy, homes are data** — the layout strategy is a choice, so it is declared once

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

@@ -41,7 +41,7 @@ folder names say what the project does. Three folders are deliberately *not* cap
 
 | Folder | Holds |
 |---|---|
-| `design/` | the **rules** — the model and the *why* (descriptive docs) |
+| `design/` | the **rules** — the model and the *why* (descriptive docs), in its own shape (below) |
 | `workflows/` | the **usage** — how capabilities compose into whole flows (the project-level suite) |
 | `ledger/` | the **provenance** — durable audit records; data, outside the node taxonomy |
 
@@ -55,9 +55,38 @@ mandated set stays minimal: anything that is one document lives as a **root file
 `glossary.md` — the project's ubiquitous language, every load-bearing term defined once — is
 required of every project spec.
 
-**Two levels, never three.** A node is `<capability>/<unit>` and never sits three deep. A
-sub-grouping inside a capability is a **cross-cutting concern**, so it is expressed as a `concept:`
-tag and recovered through the generated by-concept index — never as a third folder level.
+**Two levels, never three — for capability nodes.** A capability node is `<capability>/<unit>` and
+never sits three deep. A sub-grouping inside a capability is a **cross-cutting concern**, so it is
+expressed as a `concept:` tag and recovered through the generated by-concept index — never as a
+third folder level. The rule covers capability nodes only: its reason does not reach a design
+version, which is a whole alternate snapshot of the model that no `concept:` tag can express.
+
+**The `design/` shape — current at the top, the next design beside it.** `design/` is the single
+description of the system; ADRs are the frozen record of why it changed. A design stays trustworthy
+only if it is updated as a whole, so:
+
+- **Current at the top level, one file per perspective** — the angles a reader takes on the whole
+  system, one file each, **never a perspective folder**. The ADR log `design/decisions/` is the one
+  standing sub-folder.
+- **A version folder holds the next design while one exists.** The project names it (`design/next/`
+  is a suggestion; `design/v2/` works as well). It holds a **full copy** of the perspective files,
+  never a diff, so each version reads on its own and `diff -r` shows the whole change. It holds no
+  `decisions/`. At most one exists at a time.
+- **The cut is one commit**: the version folder's contents replace the top-level perspective files,
+  and the folder and its placement-map record go. Git keeps the previous version; `design/` never
+  carries a `previous/`.
+- **The cut trigger is recorded and checkable.** While a version folder exists, the root `spec.md`
+  placement map names it and what cuts it over — a capability set reaching `implemented`, or a named
+  release. Without a checkable trigger the next design drifts into an unofficial current. Making it
+  checkable is the author's duty; the formation Warden checks that one is recorded. A
+  sub-folder of `design/` the map does not name, other than `decisions/`, is a perspective folder.
+
+Current stays at the top rather than in `design/current/` so that links to a design doc survive
+every cut: most of a project's life has no next design, and links accumulate from ADRs, capability
+specs, and the docs site.
+
+**Rejected — a fourth exempt top-level folder** (`design-next/`). It grows the mandated set this
+governance keeps minimal, and it would sit among the capability folders as if it were one.
 
 **The concept axis.** The tree can privilege only one axis, and it privileges capability; a concern
 enacted across several capabilities is declared in `concept:` frontmatter and navigated through the
@@ -107,6 +136,8 @@ decisions the strategy alone does not settle, so a node placed by an explicit ro
 the strategy alone therefore reports false findings against exactly the placements a human already
 adjudicated. The test is a disjunction: a node is misplaced only when it **neither** follows the
 declared strategy **nor** matches a routing-table row.
+While a next design exists, the map also names the **design version** folder and its cut trigger
+(the `design/` shape above); a judgment of `design/` reads that entry.
 
 This is the same split the corpus-discovery rule already makes — fixed conventions are scanned,
 while an off-convention anchor list is declared and curated. "No drift" means *do not store what you
@@ -162,8 +193,12 @@ entry condition.
    folder, reference artifacts to the capability that owns them.
 3. **Screaming architecture** with three non-capability folders (`design/`, `workflows/`, `ledger/`)
    and **root files, not folders**, for single documents (`glossary.md` required).
-4. **Two levels, never three** — deeper sub-grouping is a `concept:` tag, not a folder.
-5. **One spec per project**; colocate by default and **hoist only when the spec cannot be kept out of
+4. **Two levels, never three, for capability nodes** — deeper sub-grouping is a `concept:` tag,
+   not a folder.
+5. **`design/` has its own shape** — current at the top, one file per perspective (never a
+   perspective folder), at most one project-named version folder holding a full copy of the next
+   design, a one-commit cut, and the cut trigger recorded in the placement map.
+6. **One spec per project**; colocate by default and **hoist only when the spec cannot be kept out of
    what ships** (the agentic plugin) — nesting is never the reason.
-6. **Strategy is policy, homes are data** — read the declared strategy from the placement map, derive
+7. **Strategy is policy, homes are data** — read the declared strategy from the placement map, derive
    homes from `concept:` tags, and let the strategy pick the derivation.

package/skills/start-mission/SKILL.md

@@ -62,7 +62,7 @@ Get the CR into the system and create its plan brief — the plan is a step-1 ar
 - **Recover the request.** From a general change prompt, name the change and the target. From a **source URL** (`work on <github issue url>`), fetch the issue and read it as the CR body.
 - **Locate the project spec** by running the **`discover-specs`** skill (the `corpus/discovery` engine) — it returns the TOON list of every project spec at the SDD spec locations (the three fixed conventions plus any declared extra anchors, ADR-0019) with its `status` and `project-path`. Resolve the CR's target to one spec by folder slug or `project-path`; an ambiguous match is disambiguated with the user, never guessed. One project is one spec — there is no spec fleet to pick from. If `discover-specs` finds **no** spec for the target project, that is the **backfill** path (load `scaffold-project-spec`).
 - **Scaffold `.agents/plans/<cr-ref>-<what>.plan.md`** — name the brief with a short kebab `<what>` slug naming what the CR does, even when the ref comes from an external source (`github-34-rejudge-sweep.plan.md`, not `github-34.plan.md`). The source name (`github`) is **optional** — most projects draw from one external source, so a bare `34-rejudge-sweep.plan.md` is fine; keep the source prefix only when a project mixes sources. Fill from a basic template: frontmatter `todos` (ordered, `status: pending`, each `content` a **short summary < 120 chars**) + a `## NEXT` anchor + the CR link. Keep the plan body **concise** — it is read by the agent each resume, so phrase for an agent first while staying human-legible (terse lead, no prose padding). This is the portable handoff brief `pause-mission` / `resume-mission` operate on. **Safe-to-publish floor** (the same one the combat log carries in `combat-log-governance`): the brief is **tracked and committed**, so it references **only repo-relative paths** — never an absolute path, `$HOME`/`$USER`, an OS username, or any machine-local location outside the repo. When the CR's design came from a plan-mode doc under a machine-local path (e.g. `~/.claude/plans/…`), bring that content **into** the repo (a sibling `<cr-ref>.design.md` beside the brief) and reference it repo-relative — do not link the external absolute path. The `check-plan-safety` engine enforces this mechanically. **When that brought-in content is a plan-mode preview** (a drafted spec + scenario list from a prior `### Plan-mode preview` run), the explore phase **adopts it as the settled draft** (see Step 2) rather than re-grilling from scratch.
-- **Escape a non-CR.** If the grill shows no suite-relevant behavior, escape: create no draft, invoke no gate, write no record. Independently, **escape by tracking**: for each artifact the request touches, run the **`resolve-tracking`** skill (`intake/resolve-tracking`'s concrete engine) — `node "<skill>/scripts/resolve-tracking.mts" --root . --path <path> [--artifact-type <type>] [--explicit tracked|ignored]`, passing `--explicit` when the requester stated tracking directly and `--artifact-type` when convention already makes it obvious. If **every** touched artifact resolves `ignored`, escape the whole request the same way. If the request is **mixed**, carve the tracked artifacts into the CR and escape the ignored ones (the same carve-and-escape shape already used for the no-behavior case). Escaping does not mean stopping: if the artifact-type has a producer with an escaped-request entry point (`define-skill` for `skill`), invoke it directly to do the work; only state "leaving the lifecycle" and stop when no such producer exists.
+- **Escape a non-CR.** If the grill shows no suite-relevant behavior, escape: create no draft, invoke no gate, write no record. Independently, **escape by tracking**: for each artifact the request touches, run the **`resolve-tracking`** skill (`intake/resolve-tracking`'s concrete engine) — `node "<skill>/scripts/resolve-tracking.mjs" --root . --path <path> [--artifact-type <type>] [--explicit tracked|ignored]`, passing `--explicit` when the requester stated tracking directly and `--artifact-type` when convention already makes it obvious. If **every** touched artifact resolves `ignored`, escape the whole request the same way. If the request is **mixed**, carve the tracked artifacts into the CR and escape the ignored ones (the same carve-and-escape shape already used for the no-behavior case). Escaping does not mean stopping: if the artifact-type has a producer with an escaped-request entry point (`define-skill` for `skill`), invoke it directly to do the work; only state "leaving the lifecycle" and stop when no such producer exists.
 
 ## Step 2 — explore: grill the spec + suite, build to learn
 

package/skills/touch-set-correction/SKILL.md

@@ -41,7 +41,7 @@ to `git`, `resolve-governances.mts`, and `npx gherkin-cli`.
 ## Run it
 
 ```bash
-node "<skill>/scripts/touch-set-correction.mts" --base <ref> --declared a,b,c \
+node "<skill>/scripts/touch-set-correction.mjs" --base <ref> --declared a,b,c \
   [--head HEAD] [--root .] \
   [--layout 'sdd:.agents/specs/sdd,plugins/sdd/skills']... \
   [--format toon|json]