cyber-sdd 0.0.0 → 0.1.0

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

@@ -70,6 +70,45 @@ the current code**, never the baseline to patch. Reading the standing suite and
 a diff notices is not this procedure — it leaves stale scenarios in place and misses edges the CFG
 mandates (ADR-0029).
 
+## A fold node states its rule in closed form before its scenarios
+
+A **fold** (aggregation) node folds several sub-conditions into one verdict — a ready-frontier folding
+reachability against a mutex, a gate-legality aggregate, a per-cell matrix claim. **When the fold
+combines two or more *interacting* sub-conditions, state its rule in closed form — and re-derive that
+rule's soundness against the real data model — before you draw the CFG.** A **single-condition** fold
+may be specified by example; demanding a closed form of it is the failure mode of this rule, not its
+point. Scenarios drawn off a rule never written down are drawn off a rule never *agreed*, and each
+producer-judge round then rewrites a different corner of it: the corpus ran the A/B — the `github-192`
+fence, specified by example, **diverged** (`1 → 1 → 3` contradictions, each manufactured by the prior
+fix, reverted at the cap); `github-224` stated the rule first and **converged** (zero). Closed form
+buys **iteration convergence** — insurance a single-condition fold does not need and a
+multi-condition one rarely survives without. Three qualifications, each a way it is misapplied:
+
+- **Fire only on ≥2 *interacting* sub-conditions — over-firing is the failure mode.** A
+  single-condition fold by example converges fine (the WAW-mutex touch-set-intersection scenarios
+  settled in a handful, no stated rule). Mere aggregation is not the trigger; genuine interaction is.
+- **Closed form is not soundness — re-derive against the real data model.** A rule in closed form,
+  even one carrying a proof, can be unsound against the data it folds: `R''` shipped a termination
+  proof and still deadlocked, its project-scoped exemption violated by graph-global RAW closure, fixed
+  to `R'''` only once the assumption was re-derived against the real graph. A proof over an assumed
+  model proves nothing about the real one.
+- **Convergence is not coverage — pair the rule with a mutation sweep and a safety dual.** Stating
+  the rule kills the divergence, not the gaps. A **mutation sweep** mutates each interacting condition
+  and confirms each break lands on a *distinct* scenario — two mutations breaking one scenario mean
+  the conditions collapsed into one and the CFG has fewer real branches than it claims. A **safety
+  dual** guards the blind spot a convergence check cannot see: a liveness rule (*some grant path
+  exists*, *the frontier advances*) passes an **over-permissive** fold green, because over-permission
+  adds paths rather than removing them — pair every liveness scenario with the safety scenario
+  asserting the case it structurally cannot observe.
+
+**The matrix corollary — a per-cell claim is this rule applied.** An outcome stated per cell of a grid
+of interacting conditions is this rule with the closed form written as the **cell function**. Draw
+**every independent cell as its own CFG branch** and exclude the **degenerate** ones (a cell whose
+outcome reconverges with a sibling collapses under the reconvergence rule above, exactly as a
+**universal** "every cell behaves the same" claim is one convergence scenario, not a grid — the
+`github-278` round-4 draft asserted such a universal one row too wide and dropped it). Confirm the
+cells genuinely independent by the mutation sweep. This is not a separate bar; it is the fold rule.
+
 ## Sections mirror the spec's use-case groups; every scenario binds to a map edge
 
 `spec.md` sections the node by **use-case group**, each carrying a drawn **CFG** and an
@@ -119,10 +158,10 @@ only *where the node genuinely owns the routing decision*, and two different dec
   node's own content, so **the node owns it outright**.
 
 The two look alike in shape and differ only in who decides, so **step form does not classify them**
-and no mechanical check should try (see `.agents/specs/sdd/ssa-lowering/ssa-lowering.feature`, where
-a deletion that read the second case as the first was blocked at the gate and reverted). A
-deterministic, fully-owned decision table that selects *what an already-invoked subject does* is
-conduct, not engagement — it wants `@behavior`.
+and no mechanical check should try (see the frozen suite of the SDD project spec's `ssa-lowering`
+node, repo-only, where a deletion that read the second case as the first was blocked at the gate and
+reverted). A deterministic, fully-owned decision table that selects *what an already-invoked subject
+does* is conduct, not engagement — it wants `@behavior`.
 
 **`@frozen` is the only file-level tag** — it sits on the `Feature`, not a scenario.
 

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

@@ -4,11 +4,9 @@ The concrete engine for **touch-set-correction** — a read-only, post-hoc recon
 Mission's declared touch-set against what its `git diff` actually changed, composing `git diff`,
 [`resolve-governances`](../resolve-governances/SKILL.md), and `gherkin-cli diff` into the corrected
 touch-set the mission-graph's single writer records at retirement. Built for the Op2 deferral of the
-cyberfleet-batch change request; see
-[`.agents/specs/sdd/touch-set-correction/README.md`](../../../../.agents/specs/sdd/touch-set-correction/README.md)
-for the authoritative behavior description and
-[`touch-set-correction.feature`](../../../../.agents/specs/sdd/touch-set-correction/touch-set-correction.feature)
-for the frozen 21-scenario contract.
+cyberfleet-batch change request; the `touch-set-correction` node of the SDD project spec (in the
+cyberplace repository, not shipped in this package) carries the authoritative behavior description
+and the frozen 21-scenario contract.
 
 - **Skill contract:** [`SKILL.md`](./SKILL.md)
 - **Script:** [`scripts/touch-set-correction.mts`](./scripts/touch-set-correction.mts)

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

@@ -4,8 +4,8 @@
 // touch-set (recovered from `git diff base..head`). It composes three tools — `git diff` (changed
 // files), `resolve-governances` (each file's artifact-type, best-effort), and `gherkin-cli diff`
 // (a touched .feature's changed scenarios) — into one three-way split (confirmed / missed /
-// over-declared) plus the corrected touch-set (= the actual touched set). See
-// .agents/specs/sdd/touch-set-correction/README.md for the full contract.
+// over-declared) plus the corrected touch-set (= the actual touched set). The touch-set-correction
+// node of the SDD project spec (repo-only) carries the full contract.
 //
 // Architecture — pure derivation kept apart from IO, on purpose (mission-graph.mts's convention):
 //   - isFeature / fileToNode / reconcile / assembleCorrection are PURE: they take and return plain
@@ -27,9 +27,9 @@
 // Pure functions are exported for node:test; running the file directly drives the CLI.
 
 import { execFileSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
+import { readFileSync, realpathSync } from 'node:fs'
 import { dirname, join, relative, resolve, sep } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { type DiffReader, diffFeatures } from 'gherkin-cli'
 
 // ── Types ──
@@ -415,4 +415,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/verify-scenarios/SKILL.md

@@ -29,6 +29,13 @@ artifact-type already falls through to SDD defaults).
 - **Many-to-one is fine.** Two tests can bind the same key; the fold is PASS only if none of them
   fail. A test that maps to an already-covered key and isn't the canonical rename shows up as an
   EXTRA (diagnostic, not a failure) — leave it.
+- **A punctuation-only near-miss still binds.** When no result matches a key exactly, the fold
+  retries on a comparison key that folds curly quotes/apostrophes, dashes, and the ellipsis to their
+  ASCII forms and collapses whitespace — so a pasted `’` for a `'` does not land the same scenario in
+  BOTH the UNBOUND list and the EXTRA list with nothing linking them. The bind is reported as a
+  **PROBABLE TITLE MISMATCH** naming both verbatim titles, so the typo still gets fixed. Nothing
+  rewrites a title, an **exact** match always wins, case is **not** folded, and an **ambiguous** fold
+  (two candidates folding alike) stays UNBOUND rather than binding the wrong one.
 
 ## Config schema
 
@@ -76,9 +83,9 @@ node "<skill>/scripts/verify-scenarios.mts" \
 - `--report <xml>` bypasses `--config` entirely — a single ad-hoc junit source, no command.
 - `--run` executes each source's `command` first; without it, existing reports are read as-is.
 - Default output is a readable per-scenario table + a `N/M BOUND, P pass, F fail, U unbound`
-  summary line + any EXTRA keys. `--format json` emits
-  `{node,total,bound,pass,fail,unbound,scenarios[],extras[]}`. `--format toon` emits the repo's
-  TOON tabular form.
+  summary line + any EXTRA keys + any PROBABLE TITLE MISMATCH pairs. `--format json` emits
+  `{node,total,bound,pass,fail,unbound,scenarios[],extras[],mismatches[]}`. `--format toon` emits the
+  repo's TOON tabular form.
 - Exit code is non-zero when any scenario is UNBOUND or FAIL; zero only at full BOUND+PASS.
 
 ## Monorepo rooting — `--feature-root` vs. `--root`

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

@@ -35,11 +35,20 @@
 // feature scenario KEY: UNBOUND if no result; PASS if ≥1 result and none fail; FAIL if any fails.
 // EXTRA = bound result keys matching no feature scenario key (diagnostic, not a failure).
 //
+// Near-miss binding: a key that matches no result EXACTLY gets a second pass on a punctuation- and
+// whitespace-folded COMPARISON key (a pasted curly apostrophe, an em dash, a non-breaking space),
+// so a real binding is not split across the UNBOUND list and the EXTRA list with nothing saying the
+// two are the same scenario. Only unclaimed results are eligible, and only an unambiguous 1:1 fold
+// binds — an ambiguous fold stays UNBOUND rather than manufacturing a false bind. Nothing rewrites
+// a title: the fold is the only place the folded form exists, and every reported field carries the
+// verbatim key, with the matched test title reported alongside it as a probable title mismatch.
+//
 // Pure functions are exported for node:test; running the file directly drives the CLI.
 
 import { execSync } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { isAbsolute, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { parseFeatures } from 'gherkin-cli'
 
 // Resolves a path argument against `--root`: relative paths join beneath root (which defaults to the
@@ -248,6 +257,15 @@ export interface ScenarioReport {
 	key: string
 	state: ScenarioState
 	resultCount: number
+	/** The result key this scenario bound to when it bound on the folded comparison key, not exactly. */
+	matchedKey?: string
+}
+
+export interface TitleMismatch {
+	/** The frozen scenario's verbatim key. */
+	key: string
+	/** The test's verbatim leaf title it bound to — differing only by punctuation or whitespace. */
+	matchedKey: string
 }
 
 export interface FoldReport {
@@ -259,6 +277,43 @@ export interface FoldReport {
 	unbound: number
 	scenarios: ScenarioReport[]
 	extras: string[]
+	/** Bindings made on the folded comparison key — a probable one-character typo, reported so it gets fixed. */
+	mismatches: TitleMismatch[]
+}
+
+// Punctuation and whitespace variants that carry no meaning of their own: the smart-quote and dash
+// substitutions an editor, a copy-paste, or a Markdown renderer makes to a title on its way into a
+// test file. Case is deliberately NOT folded — a differing case is not a punctuation variant, and
+// folding it would bind two titles the author wrote differently on purpose.
+const PUNCTUATION_FOLDS: [RegExp, string][] = [
+	[/[‘’‚‛′´]/g, "'"], // curly/prime apostrophes -> straight
+	[/[“”„‟″]/g, '"'], // curly double quotes -> straight
+	[/[‐‑‒–—―−]/g, '-'], // hyphens/dashes/minus -> hyphen
+	[/…/g, '...'], // ellipsis -> three dots
+]
+// A no-break/thin/figure space needs no entry of its own — the trailing `\s+` collapse below
+// already covers every Unicode space separator.
+
+// The MATCH-ONLY form of a key: Unicode-composed, punctuation-folded, whitespace-collapsed. Never
+// written back anywhere — reports carry the verbatim key.
+export function comparisonKey(key: string): string {
+	let out = key.normalize('NFC')
+	for (const [re, rep] of PUNCTUATION_FOLDS) out = out.replace(re, rep)
+	return out.replace(/\s+/g, ' ').trim()
+}
+
+// Indexes values by their comparison key, dropping every comparison key claimed by more than one
+// value — an ambiguous fold must not bind, so only the 1:1 entries survive.
+function unambiguousByComparisonKey(keys: string[]): Map<string, string> {
+	const index = new Map<string, string>()
+	const ambiguous = new Set<string>()
+	for (const k of keys) {
+		const c = comparisonKey(k)
+		if (index.has(c)) ambiguous.add(c)
+		else index.set(c, k)
+	}
+	for (const c of ambiguous) index.delete(c)
+	return index
 }
 
 export function foldResults(scenarioKeys: ScenarioKey[], results: BoundResult[], node: string): FoldReport {
@@ -270,21 +325,39 @@ export function foldResults(scenarioKeys: ScenarioKey[], results: BoundResult[],
 		else byKey.set(r.key, [r])
 	}
 
+	const featureKeys = new Set(scenarioKeys.map((s) => s.key))
+	// Only a result no scenario claims exactly is eligible for a near-miss bind, and only a scenario
+	// that found no exact result looks for one — an exact binding always wins.
+	const unclaimed = [...byKey.keys()].filter((k) => !featureKeys.has(k))
+	const unmatchedScenarioKeys = scenarioKeys.map((s) => s.key).filter((k) => !byKey.has(k))
+	const unclaimedByComparison = unambiguousByComparisonKey(unclaimed)
+	const unmatchedByComparison = unambiguousByComparisonKey(unmatchedScenarioKeys)
+
+	const nearMisses = new Map<string, string>() // scenario key -> result key
+	for (const [comparison, scenarioKey] of unmatchedByComparison) {
+		const resultKey = unclaimedByComparison.get(comparison)
+		if (resultKey !== undefined) nearMisses.set(scenarioKey, resultKey)
+	}
+
 	const scenarios: ScenarioReport[] = scenarioKeys.map(({ name, key }) => {
-		const group = byKey.get(key) ?? []
+		const matchedKey = byKey.has(key) ? undefined : nearMisses.get(key)
+		const group = byKey.get(matchedKey ?? key) ?? []
 		const state: ScenarioState =
 			group.length === 0 ? 'unbound' : group.some((r) => r.outcome === 'fail') ? 'fail' : 'pass'
-		return { name, key, state, resultCount: group.length }
+		return { name, key, state, resultCount: group.length, ...(matchedKey === undefined ? {} : { matchedKey }) }
 	})
 
-	const featureKeys = new Set(scenarioKeys.map((s) => s.key))
-	const extras = [...byKey.keys()].filter((k) => !featureKeys.has(k)).sort()
+	const nearMissKeys = new Set(nearMisses.values())
+	const extras = unclaimed.filter((k) => !nearMissKeys.has(k)).sort()
+	const mismatches: TitleMismatch[] = scenarios
+		.filter((s): s is ScenarioReport & { matchedKey: string } => s.matchedKey !== undefined)
+		.map((s) => ({ key: s.key, matchedKey: s.matchedKey }))
 
 	const pass = scenarios.filter((s) => s.state === 'pass').length
 	const fail = scenarios.filter((s) => s.state === 'fail').length
 	const unbound = scenarios.filter((s) => s.state === 'unbound').length
 
-	return { node, total: scenarios.length, bound: pass + fail, pass, fail, unbound, scenarios, extras }
+	return { node, total: scenarios.length, bound: pass + fail, pass, fail, unbound, scenarios, extras, mismatches }
 }
 
 // ── Output ──
@@ -300,6 +373,10 @@ export function formatToon(report: FoldReport): string {
 		(s) => `  ${[toonField(s.name), toonField(s.key), s.state, String(s.resultCount)].join(',')}`,
 	)
 	const extras = [`extras[${report.extras.length}]{key}:`, ...report.extras.map((e) => `  ${toonField(e)}`)]
+	const mismatches = [
+		`mismatches[${report.mismatches.length}]{key,matchedKey}:`,
+		...report.mismatches.map((m) => `  ${[toonField(m.key), toonField(m.matchedKey)].join(',')}`),
+	]
 	const summary = `summary{node,total,bound,pass,fail,unbound}:\n  ${[
 		toonField(report.node),
 		report.total,
@@ -308,7 +385,7 @@ export function formatToon(report: FoldReport): string {
 		report.fail,
 		report.unbound,
 	].join(',')}`
-	return [header, ...rows, ...extras, summary].join('\n')
+	return [header, ...rows, ...extras, ...mismatches, summary].join('\n')
 }
 
 export function formatText(report: FoldReport): string {
@@ -322,6 +399,11 @@ export function formatText(report: FoldReport): string {
 		lines.push('')
 		lines.push(`EXTRA (bound results matching no scenario): ${report.extras.join(', ')}`)
 	}
+	if (report.mismatches.length > 0) {
+		lines.push('')
+		lines.push('PROBABLE TITLE MISMATCH (bound on punctuation/whitespace only — fix the test title):')
+		for (const m of report.mismatches) lines.push(`  scenario "${m.key}" <- test "${m.matchedKey}"`)
+	}
 	return lines.join('\n')
 }
 
@@ -383,4 +465,6 @@ export function main(argv: string[]): number {
 	return exitCode(report)
 }
 
-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)))
+}