@rsaglobaltech/specgate 0.8.1 → 0.10.0

package/dist/scripts/cli/commands/quality/ValidateSpecsCommand.js

@@ -44,16 +44,26 @@ const DiskProjectRepository_1 = require("../../../../packages/core/src/infrastru
 const diagnostics_1 = require("../../../lib/diagnostics");
 const against_lock_1 = require("../../../specops/against_lock");
 const requirement_graph_1 = require("../../../lib/requirement-graph");
+const MultiStack_1 = require("../../../../packages/core/src/domain/MultiStack");
+const ScenarioCoverage_1 = require("../../../../packages/core/src/domain/ScenarioCoverage");
+const TraceabilityFormat_1 = require("../../../../packages/core/src/domain/TraceabilityFormat");
+const crypto = __importStar(require("node:crypto"));
 const agent_1 = require("../../../lib/agent");
 const placeholders_1 = require("../../../lib/placeholders");
 const command_1 = require("../../../lib/command");
 const ValidateProjectUseCase_1 = require("../../../../packages/core/src/application/ValidateProjectUseCase");
 const DiskTraceabilityRepository_1 = require("../../../../packages/core/src/infrastructure/DiskTraceabilityRepository");
-const TraceabilityFormat_1 = require("../../../../packages/core/src/domain/TraceabilityFormat");
+const TraceabilityFormat_2 = require("../../../../packages/core/src/domain/TraceabilityFormat");
 const project_root_1 = require("../../../lib/project-root");
 const GherkinQuality_1 = require("../../../../packages/core/src/domain/GherkinQuality");
+/** Scenario findings that make a suite report a pass it did not run. */
+const SUITE_LIES = new Set([
+    GherkinQuality_1.QUALITY_CODES.NO_STEPS,
+    GherkinQuality_1.QUALITY_CODES.KEYWORD_CASE,
+    GherkinQuality_1.QUALITY_CODES.OUTLINE_WITHOUT_EXAMPLES,
+]);
 const GherkinTags_1 = require("../../../../packages/core/src/domain/GherkinTags");
-const TraceabilityFormat_2 = require("../../../../packages/core/src/domain/TraceabilityFormat");
+const TraceabilityFormat_3 = require("../../../../packages/core/src/domain/TraceabilityFormat");
 const RequirementSyntax_1 = require("../../../../packages/core/src/domain/RequirementSyntax");
 const DeclaredArtifacts_1 = require("../../../../packages/core/src/domain/DeclaredArtifacts");
 const SpecParser_1 = require("../../../../packages/core/src/domain/SpecParser");
@@ -69,7 +79,8 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
     }
     usage() {
         process.stdout.write("🔎 Usage:\n" +
-            "  validate_specs.js <project_dir> [--strict-tdd] [--strict-scenarios] " +
+            "  specgate validate <project_dir> [--strict] [--strict-tdd] [--strict-scenarios] " +
+            "  [--strict-coverage] " +
             "[--strict-requirements] [--strict-links] [--against-lock]\n\n" +
             "Checks:\n" +
             "- minimum SDD structure\n" +
@@ -93,6 +104,14 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
             "--strict-requirements additionally enforces, over docs/specs/capabilities/**/spec.md:\n" +
             "- Every requirement states an obligation (SHALL / MUST / SHOULD / MAY / DEBE / DEBERÁ)\n" +
             "- A requirement that opens with IF resolves with THEN in the same sentence\n\n" +
+            "--strict is the gate: every check below, in one flag. Prefer it — the\n" +
+            "individual flags exist so an existing CI invocation keeps meaning what it meant.\n\n" +
+            "--strict-coverage additionally enforces:\n" +
+            "- Every scenario in a declared feature file is named by the test artifact that\n" +
+            "  claims to prove it\n" +
+            "- Every declared test artifact names its requirement or one of its scenarios —\n" +
+            "  a path that exists is not evidence that it proves anything\n" +
+            "  Both are name matches, so this is opt-in: it does not run your suite\n\n" +
             "--strict-links additionally enforces:\n" +
             "- Every Feature file / Technical artifact / Test artifact the matrix declares as a\n" +
             "  path still exists on disk\n");
@@ -138,7 +157,64 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
             this.logFix(fixLines);
         process.exit(exitCode);
     }
-    validateMonorepo(targetDir, strictTdd, strictScenarios, strictRequirements, strictLinks) {
+    /**
+     * A shared spec that is only shared by convention is not shared.
+     *
+     * `init --multi-stack` symlinks spec.md, features/ and the ADR index into
+     * every stack, so there is one file with several names. Windows refuses to
+     * create symlinks without Developer Mode, and scaffolding copies instead —
+     * at which point "shared" is a claim rather than a fact, and the three stacks
+     * can quietly start describing different products.
+     *
+     * So the guarantee moves into the gate: a copy that no longer matches the
+     * root is an error. Symlinked trees skip this, because they cannot drift.
+     */
+    sharedSpecDrift(rootDir, projectRel) {
+        const digest = (target) => {
+            const h = crypto.createHash("sha256");
+            const stat = fs.statSync(target);
+            if (stat.isFile()) {
+                h.update(fs.readFileSync(target));
+                return h.digest("hex");
+            }
+            const entries = [];
+            const walkInto = (dir) => {
+                for (const name of fs.readdirSync(dir).sort()) {
+                    const full = path.join(dir, name);
+                    if (fs.statSync(full).isDirectory())
+                        walkInto(full);
+                    else
+                        entries.push(path.relative(target, full).split(path.sep).join("/"));
+                }
+            };
+            walkInto(target);
+            for (const rel of entries) {
+                h.update(rel);
+                h.update(fs.readFileSync(path.join(target, rel)));
+            }
+            return h.digest("hex");
+        };
+        const drifted = [];
+        for (const shared of MultiStack_1.SHARED_PATHS) {
+            const atRoot = path.join(rootDir, shared);
+            const inProject = path.join(projectRel, shared);
+            if (!fs.existsSync(atRoot) || !fs.existsSync(inProject))
+                continue;
+            // A link cannot drift from what it points at.
+            const link = fs.lstatSync(inProject, { throwIfNoEntry: false });
+            if (link && link.isSymbolicLink())
+                continue;
+            try {
+                if (digest(atRoot) !== digest(inProject))
+                    drifted.push(shared);
+            }
+            catch {
+                // Unreadable is a different problem, and the normal checks report it.
+            }
+        }
+        return drifted;
+    }
+    validateMonorepo(targetDir, strictTdd, strictScenarios, strictRequirements, strictLinks, strictCoverage) {
         const cfgPath = path.join(targetDir, "specops.config.yaml");
         if (!fs.existsSync(cfgPath))
             return null;
@@ -181,9 +257,24 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
                 args.push("--strict-requirements");
             if (strictLinks)
                 args.push("--strict-links");
+            if (strictCoverage)
+                args.push("--strict-coverage");
             const r = (0, node_child_process_1.spawnSync)(process.execPath, args, { encoding: "utf8" });
             process.stdout.write(r.stdout || "");
             process.stderr.write(r.stderr || "");
+            const drifted = this.sharedSpecDrift(targetDir, subDir);
+            if (drifted.length > 0) {
+                this.logError(`Shared spec has drifted in ${rel}: ${drifted.join(", ")} no longer matches the root`);
+                this.logFix([
+                    "These paths are meant to be one artifact for the whole tree. They were copied",
+                    "rather than symlinked (this platform would not create links), so an edit in one",
+                    "stack does not reach the others.",
+                    `Fix: copy the root's version over ${rel}'s, or move the edit to the root and`,
+                    "copy outward — then commit both.",
+                ]);
+                results.push({ project: rel, ok: false, detail: "shared spec drift" });
+                continue;
+            }
             results.push({ project: rel, ok: r.status === 0 });
         }
         const failures = results.filter((r) => !r.ok);
@@ -211,11 +302,15 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
      * this tool uses everywhere else. Under the flag, warnings fail too — asking
      * for strict and getting lenient is the H14 mistake in a different costume.
      */
-    checkScenarioQuality(targetDir, featureFiles) {
+    checkScenarioQuality(targetDir, featureFiles, delivering = "") {
+        const owed = this.featureFilesOwed(targetDir, delivering);
         const findings = [];
         for (const file of featureFiles.slice().sort()) {
             const rel = path.relative(targetDir, file).split(path.sep).join("/");
-            findings.push(...(0, GherkinQuality_1.analyseGherkinSource)(fs.readFileSync(file, "utf8"), rel));
+            const found = (0, GherkinQuality_1.analyseGherkinSource)(fs.readFileSync(file, "utf8"), rel);
+            // A scenario Cucumber reports as passing without running anything lies
+            // whatever the row's status (H14). The rest is owed on delivery.
+            findings.push(...(owed(rel) ? found : found.filter((d) => SUITE_LIES.has(d.code))));
         }
         if (findings.length === 0)
             return;
@@ -234,6 +329,41 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
         ]);
         process.exit(1);
     }
+    /**
+     * Which feature files the scenario rules apply to: the same line as
+     * `--strict-links` — a Draft row owes nothing yet, a delivered one owes
+     * everything. `specgate new` writes a scenario of `<placeholder>` steps for a
+     * person to fill in; failing the build the moment it exists would teach
+     * people to skip the gate, and passing it once delivered would be a green
+     * that means nothing. A file no row claims is always checked.
+     */
+    featureFilesOwed(targetDir, delivering) {
+        const tracePath = path.join(targetDir, "docs/specs/traceability.md");
+        if (!fs.existsSync(tracePath))
+            return () => true;
+        let rows = [];
+        try {
+            rows = (0, TraceabilityFormat_3.parseTraceabilityRows)(fs.readFileSync(tracePath, "utf8")).rows || [];
+        }
+        catch {
+            return () => true;
+        }
+        const claimed = new Set();
+        const owed = new Set();
+        for (const row of rows) {
+            const delivered = TraceabilityFormat_1.DELIVERED_STATUS.has(String(row.status || "").trim()) ||
+                (delivering !== "" && row.requirement === delivering);
+            for (const declared of (0, DeclaredArtifacts_1.declaredPaths)(row.featureFile)) {
+                const rel = (0, DeclaredArtifacts_1.artifactFile)(declared);
+                if (!rel)
+                    continue;
+                claimed.add(rel);
+                if (delivered)
+                    owed.add(rel);
+            }
+        }
+        return (rel) => owed.has(rel) || !claimed.has(rel);
+    }
     /**
      * Does the scenario the matrix names actually exist in the file? (F4)
      *
@@ -254,7 +384,7 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
     checkScenarioTags(targetDir, traceContent) {
         let rows = [];
         try {
-            rows = (0, TraceabilityFormat_2.parseTraceabilityRows)(traceContent).rows || [];
+            rows = (0, TraceabilityFormat_3.parseTraceabilityRows)(traceContent).rows || [];
         }
         catch {
             return;
@@ -309,10 +439,10 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
      * Opt-in, same promise as `--strict-scenarios`: a project with aspirational
      * rows does not fail its next `validate` over this.
      */
-    checkDeclaredArtifactsExist(targetDir, traceContent) {
+    checkDeclaredArtifactsExist(targetDir, traceContent, delivering = "") {
         let rows = [];
         try {
-            rows = (0, TraceabilityFormat_2.parseTraceabilityRows)(traceContent).rows || [];
+            rows = (0, TraceabilityFormat_3.parseTraceabilityRows)(traceContent).rows || [];
         }
         catch {
             return;
@@ -325,11 +455,20 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
             ["test artifact", "testArtifact"],
         ];
         for (const row of rows) {
+            // A row that has not been delivered names where the work is going to
+            // land; only a delivered one claims the file is there. Measured
+            // 2026-10-06: with `--strict` as the CI gate, every planned row failed
+            // the build — and in the harness, one pending requirement's paths failed
+            // its sibling's worktree.
+            const owesFiles = TraceabilityFormat_1.DELIVERED_STATUS.has(String(row.status || "").trim()) ||
+                (delivering !== "" && row.requirement === delivering);
+            if (!owesFiles)
+                continue;
             for (const [label, key] of columns) {
                 for (const declared of (0, DeclaredArtifacts_1.declaredPaths)(row[key])) {
-                    // A cell may anchor a line range (`src/auth/login.ts#L15-L89`); the
-                    // anchor is not part of the filesystem path.
-                    const rel = declared.split("#")[0];
+                    // A cell may point into a file — an anchor (`login.ts#L15-L89`) or a
+                    // test selector (`test_x.py::test_y`). Neither is part of the filename.
+                    const rel = (0, DeclaredArtifacts_1.artifactFile)(declared);
                     if (!rel || seen.has(`${row.requirement || row.feature}::${rel}`))
                         continue;
                     if (fs.existsSync(path.join(targetDir, rel)))
@@ -358,6 +497,162 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
         ]);
         process.exit(1);
     }
+    /**
+     * `--strict-coverage`: every declared scenario is named by something that
+     * claims to prove it (#168).
+     *
+     * A row names one `Scenario ID` and one feature file; the file may hold five
+     * scenarios, and nothing related the other four to anything. Measured: a
+     * feature declaring three scenarios with tests covering two passed
+     * `--strict-tdd --strict-scenarios --strict-links` all at once, with the row
+     * on `Implemented`.
+     *
+     * It is behind its own flag on purpose. The check is a name match — this tool
+     * does not run the suite and cannot know which assertion belongs to which
+     * scenario — and a project that names its tests some other way would fail
+     * through no fault of its own. Opting in is the honest interface for a
+     * heuristic.
+     */
+    checkScenarioCoverage(targetDir, traceContent) {
+        let rows = [];
+        try {
+            rows = (0, TraceabilityFormat_3.parseTraceabilityRows)(traceContent).rows || [];
+        }
+        catch {
+            return;
+        }
+        const readAll = (rel) => {
+            const full = path.join(targetDir, (0, DeclaredArtifacts_1.artifactFile)(rel));
+            if (!fs.existsSync(full))
+                return [];
+            const stat = fs.statSync(full);
+            if (stat.isFile())
+                return [fs.readFileSync(full, "utf8")];
+            const out = [];
+            const walkTests = (dir) => {
+                for (const name of fs.readdirSync(dir)) {
+                    const child = path.join(dir, name);
+                    if (fs.statSync(child).isDirectory())
+                        walkTests(child);
+                    else
+                        out.push(fs.readFileSync(child, "utf8"));
+                }
+            };
+            walkTests(full);
+            return out;
+        };
+        const findings = [];
+        const advisories = [];
+        const seen = new Set();
+        // Read every row once first, so the check can calibrate before it judges.
+        const readRow = (row) => {
+            const declaredTests = (0, DeclaredArtifacts_1.declaredPaths)(row.testArtifact).filter((t) => t && t !== "-" && t.toUpperCase() !== "TBD");
+            const featureRel = (0, DeclaredArtifacts_1.declaredPaths)(row.featureFile)[0];
+            const featurePath = featureRel ? path.join(targetDir, (0, DeclaredArtifacts_1.artifactFile)(featureRel)) : null;
+            return {
+                requirement: row.requirement || "",
+                featureRel,
+                feature: featurePath && fs.existsSync(featurePath) ? fs.readFileSync(featurePath, "utf8") : "",
+                tests: declaredTests.flatMap(readAll),
+                declaredTests,
+            };
+        };
+        const read = rows.map(readRow).filter((r) => r.declaredTests.length > 0);
+        // Does this project name requirements in its tests at all? A brownfield
+        // adoption points rows at tests written years before this tool existed, and
+        // the only way to satisfy a name match there is to edit them — which is the
+        // one thing `adopt` promises it will never make you do.
+        const conventionInUse = read.length > 0 && (0, ScenarioCoverage_1.usesNamingConvention)(read);
+        if (read.length > 0 && !conventionInUse) {
+            this.logWarn("--strict-coverage could not run: no test artifact in this project names its " +
+                "requirement or any of its scenarios.");
+            this.logFix([
+                "This check matches names, and nothing here uses that convention — which is normal",
+                "for a repository whose tests predate its specifications. It is not a finding:",
+                "failing every row for a convention nobody adopted would be the gate lying.",
+                "",
+                "To turn it on, name the requirement in the test that proves it — a comment or a",
+                "test name mentioning REQ-NNN is enough — and this check starts holding the rest",
+                "of the matrix to the same standard.",
+            ]);
+            return;
+        }
+        for (const row of rows) {
+            // A `TBD` or `-` test artifact is --strict-tdd's finding, not this one:
+            // reporting it twice under two flags helps nobody.
+            const declaredTests = (0, DeclaredArtifacts_1.declaredPaths)(row.testArtifact).filter((t) => t && t !== "-" && t.toUpperCase() !== "TBD");
+            if (declaredTests.length === 0)
+                continue;
+            const sources = declaredTests.flatMap(readAll);
+            const featureRel = (0, DeclaredArtifacts_1.declaredPaths)(row.featureFile)[0];
+            const featurePath = featureRel ? path.join(targetDir, (0, DeclaredArtifacts_1.artifactFile)(featureRel)) : null;
+            const feature = featurePath && fs.existsSync(featurePath) ? fs.readFileSync(featurePath, "utf8") : "";
+            // A row with no scenario has nothing for the per-scenario check to match
+            // on — and those are the rows that lie most easily, because `adopt` seeds
+            // them with a use case and no scenario. Measured on a real adoption: a
+            // "Vet" requirement declared `PetValidatorTests.java` as its proof and
+            // every gate stayed green. The requirement id is the only evidence left.
+            const requirementId = row.requirement || "";
+            // Advisory, not a failure. At row level this cannot tell "the team has
+            // not adopted the convention yet" from "this link is a lie", and failing
+            // the first to catch the second is what made adding one comment turn
+            // three unrelated rows red.
+            if ((0, ScenarioCoverage_1.linkIsUnevidenced)(requirementId, feature, sources)) {
+                const key = `${requirementId}::unevidenced`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    advisories.push((0, diagnostics_1.warning)("link_without_evidence", `${requirementId}'s test artifact names neither ${requirementId} nor any of ` +
+                        `its scenarios.`, {
+                        target: requirementId,
+                        file: "docs/specs/traceability.md",
+                        fix: `Name ${requirementId} or one of its scenarios in ` +
+                            `${declaredTests.join(" or ")}, or point the row at the test that ` +
+                            `really proves it. A path that exists is not evidence that it proves ` +
+                            `anything.`,
+                    }));
+                }
+                continue;
+            }
+            if (!featurePath || !fs.existsSync(featurePath))
+                continue; // --strict-links reports this.
+            for (const scenario of (0, ScenarioCoverage_1.skippedScenarios)(feature, sources)) {
+                const key = `${featureRel}::${scenario.title}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                findings.push((0, diagnostics_1.error)("scenario_not_covered", `Nothing proves "${scenario.title}" (${featureRel}).`, {
+                    target: row.requirement || row.feature,
+                    file: featureRel,
+                    fix: `Add a test naming ${scenario.needles[0]} to ` +
+                        `${declaredTests.join(" or ")}, or delete the scenario if it no ` +
+                        `longer describes behaviour this project promises.`,
+                }));
+            }
+        }
+        // Formatted like the errors, so an advisory carries its code and can be
+        // grepped for in CI output the same way.
+        for (const a of advisories) {
+            process.stderr.write(`  ${(0, diagnostics_1.formatDiagnostic)(a)}\n`);
+        }
+        if (findings.length === 0)
+            return;
+        if (this.io.json) {
+            this.io.fail({ validation: null }, [...findings, ...advisories]);
+            return;
+        }
+        this.logError(`Declared scenarios nothing proves: ${findings.length}`);
+        for (const f of findings)
+            process.stderr.write(`  ${(0, diagnostics_1.formatDiagnostic)(f)}\n`);
+        // Each finding already carries its own fix; this is the shared why. It used
+        // to say "a scenario no test names" for both codes, which was the wrong
+        // advice for half of them.
+        this.logFix([
+            "A promise with nothing behind it is the thing this gate exists to catch —",
+            "and it is what an agent leaves behind when it cannot satisfy a scenario.",
+            "Other rows in this project do name what proves them, so these stand out.",
+        ]);
+        process.exit(1);
+    }
     /**
      * `--strict-requirements`: EARS-checkable requirement prose, at rest (F6).
      *
@@ -378,6 +673,29 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
      * scaffolded projects never grow one — it is the change-lifecycle structure,
      * not something `specgate init` writes. Nothing to check is not a violation.
      */
+    /**
+     * The root `spec.md` plus every capability spec, concatenated.
+     *
+     * Concatenation is enough because the only question asked of it is "does this
+     * requirement have text somewhere". Nothing downstream cares which file the
+     * text came from.
+     */
+    collectSpecProse(targetDir, specPath) {
+        const parts = [];
+        if (fs.existsSync(specPath))
+            parts.push(fs.readFileSync(specPath, "utf8"));
+        const capabilitiesDir = path.join(targetDir, ChangeWorkspace_2.CAPABILITIES_DIR);
+        if (fs.existsSync(capabilitiesDir)) {
+            for (const entry of fs.readdirSync(capabilitiesDir, { withFileTypes: true }).sort()) {
+                if (!entry.isDirectory())
+                    continue;
+                const capSpec = path.join(capabilitiesDir, entry.name, "spec.md");
+                if (fs.existsSync(capSpec))
+                    parts.push(fs.readFileSync(capSpec, "utf8"));
+            }
+        }
+        return parts.length > 0 ? parts.join("\n\n") : null;
+    }
     checkRequirementSyntax(targetDir) {
         const capabilitiesDir = path.join(targetDir, ChangeWorkspace_2.CAPABILITIES_DIR);
         if (!fs.existsSync(capabilitiesDir))
@@ -423,12 +741,39 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
         const rawArgs = this.args[0] === "validate" ? this.args.slice(1) : this.args;
         const argv = rawArgs;
         this.io = (0, agent_1.agentIo)((0, agent_1.wantsJson)(argv));
-        const strictTdd = argv.includes("--strict-tdd");
-        const strictScenarios = argv.includes("--strict-scenarios");
-        const strictRequirements = argv.includes("--strict-requirements");
-        const strictLinks = argv.includes("--strict-links");
+        // `--strict` is the gate, singular.
+        //
+        // A cold evaluator counted ten places calling `--strict-tdd` "the gate" —
+        // the quickstart, `adopt`'s epilogue, the generated AI_RULES.md, `harness
+        // init`, the harness prompt — while `ci init` alone emitted
+        // `--strict-tdd --strict-links`. So a user who followed any of the ten got
+        // a check that passes on an Implemented requirement whose test file does
+        // not exist, and the one place that was right made the other nine look
+        // like a mistake rather than a policy.
+        //
+        // Fixing the wording in ten places would have left the same trap for the
+        // eleventh. One name that means all of them is the fix; the individual
+        // flags keep working, so every existing CI invocation still means what it
+        // meant.
+        const strict = argv.includes("--strict");
+        const strictTdd = strict || argv.includes("--strict-tdd");
+        const strictScenarios = strict || argv.includes("--strict-scenarios");
+        const strictRequirements = strict || argv.includes("--strict-requirements");
+        const strictLinks = strict || argv.includes("--strict-links");
+        const strictCoverage = strict || argv.includes("--strict-coverage");
         const againstLock = argv.includes("--against-lock");
-        const positional = argv.filter((a) => !a.startsWith("-"));
+        // `--delivering REQ-NNN` holds one requirement to what a delivered row
+        // owes while its Status still says Draft. `done --check` and the harness
+        // gate run before the status flips, so without it they would skip the very
+        // requirement they are about to mark Implemented.
+        const deliveringAt = argv.indexOf("--delivering");
+        const delivering = deliveringAt >= 0 ? argv[deliveringAt + 1] || "" : "";
+        const positional = argv.filter((a, i) => !a.startsWith("-") && !(deliveringAt >= 0 && i === deliveringAt + 1));
+        // Asking what a command does is not a usage error, and it exits 0.
+        if (argv.includes("--help") || argv.includes("-h")) {
+            this.usage();
+            process.exit(0);
+        }
         const targetDir = positional[0];
         if (!targetDir) {
             this.usage();
@@ -440,7 +785,7 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
                 "  specgate init",
             ]);
         }
-        const monorepo = this.validateMonorepo(targetDir, strictTdd, strictScenarios, strictRequirements, strictLinks);
+        const monorepo = this.validateMonorepo(targetDir, strictTdd, strictScenarios, strictRequirements, strictLinks, strictCoverage);
         if (monorepo !== null) {
             process.exit(monorepo.failures === 0 ? 0 : 1);
         }
@@ -494,7 +839,7 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
             "spec.md": "Author it from the shipped template (templates/base/spec.md.tpl) — one `## REQ-NNN — <title>` section per requirement.",
             "AI_RULES.md": "Author it from templates/backend/AI_RULES.md.tpl (or frontend) — it is the agent's project rulebook.",
             "README.md": "Add a README.md describing how to build and test the project.",
-            "docs/specs/traceability.md": `Create it with the rich matrix header:\n  ${TraceabilityFormat_1.RICH_HEADER}`,
+            "docs/specs/traceability.md": `Create it with the rich matrix header:\n  ${TraceabilityFormat_2.RICH_HEADER}`,
             "docs/specs/adr/README.md": "Create docs/specs/adr/README.md as the index of your Architecture Decision Records.",
         };
         for (const f of REQUIRED_FILES) {
@@ -515,7 +860,7 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
         }
         const featureCount = featureFiles.length;
         if (strictScenarios) {
-            this.checkScenarioQuality(targetDir, featureFiles);
+            this.checkScenarioQuality(targetDir, featureFiles, delivering);
         }
         if (strictRequirements) {
             this.checkRequirementSyntax(targetDir);
@@ -549,7 +894,14 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
         const specPath = path.join(targetDir, "spec.md");
         const { report, mode, requirements: reqsInMatrix, } = new ValidateProjectUseCase_1.ValidateProjectUseCase(new DiskTraceabilityRepository_1.DiskTraceabilityRepository()).checkMatrix(traceContent, {
             strictTdd,
-            specContent: fs.existsSync(specPath) ? fs.readFileSync(specPath, "utf8") : null,
+            // Every place a requirement's prose is allowed to live. Three shapes are
+            // in the wild and all three are legitimate: `## REQ-NNN` sections (what
+            // `adopt` writes), the `| ID | Requirement |` table in §8 (what the
+            // original `init` template wrote, and what this repository still uses),
+            // and a capability spec under docs/specs/capabilities/ (ADR-0022).
+            // Reading only the root spec.md flagged 14 requirements in our own repo
+            // that are documented perfectly well one directory down.
+            specContent: this.collectSpecProse(targetDir, specPath),
         });
         const strictTddViolations = report.findings
             .filter((f) => f.code === "strict_tdd_violation")
@@ -557,6 +909,15 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
         for (const finding of report.findings) {
             if (finding.code === "strict_tdd_violation")
                 continue; // reported together, below
+            // Severity decides. This loop used to fail on anything the report
+            // carried, which turned the first warning added to `checkMatrix` into a
+            // red build — the exact green-to-red flip ADR-0026 exists to avoid.
+            if (finding.severity === "warning") {
+                this.logWarn(finding.message);
+                if (finding.fixLines?.length)
+                    this.logFix([...finding.fixLines]);
+                continue;
+            }
             this.fail(finding.code, finding.message, 1, [...(finding.fixLines || [])]);
             return;
         }
@@ -586,7 +947,10 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
         }
         this.checkScenarioTags(targetDir, traceContent);
         if (strictLinks) {
-            this.checkDeclaredArtifactsExist(targetDir, traceContent);
+            this.checkDeclaredArtifactsExist(targetDir, traceContent, delivering);
+        }
+        if (strictCoverage) {
+            this.checkScenarioCoverage(targetDir, traceContent);
         }
         for (const ff of featureFiles.sort()) {
             const rel = path.relative(targetDir, ff).split(path.sep).join("/");
@@ -746,8 +1110,26 @@ class ValidateSpecsCommand extends command_1.BaseCommand {
         }
         this.logInfo("- Base SDD structure: complete");
         this.logInfo(`- Traceability mode: ${traceMode}`);
-        if (strictTdd)
-            this.logInfo("- Strict TDD gate: passed");
+        if (strictTdd) {
+            // The count travels with the pass. `passed` over rows that were never
+            // checked is how the tool and its own documentation ended up disagreeing.
+            let exempt = 0;
+            try {
+                exempt = (0, TraceabilityFormat_1.countDraftExempt)((0, TraceabilityFormat_3.parseTraceabilityRows)(traceContent).rows || []);
+            }
+            catch {
+                exempt = 0;
+            }
+            this.logInfo(exempt > 0
+                ? `- Strict TDD gate: passed (${exempt} row(s) exempt — still Draft, so not checked)`
+                : "- Strict TDD gate: passed");
+            if (exempt > 0) {
+                this.logFix([
+                    "A Draft row owes nothing yet, so --strict-tdd skips it. It starts being",
+                    "checked the moment its Status leaves Draft — `specgate done <REQ>` does that.",
+                ]);
+            }
+        }
         if (skeletonOnly) {
             this.logWarn("Adoption never retro-filled — the only scenario is the adoption baseline.");
             this.logFix([