@rsaglobaltech/specgate 0.8.1

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

@@ -0,0 +1,764 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidateSpecsCommand = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const YamlLite_1 = require("../../../../packages/core/src/domain/YamlLite");
+const ChangeWorkspace_1 = require("../../../../packages/core/src/infrastructure/ChangeWorkspace");
+const ValidateChangeUseCase_1 = require("../../../../packages/core/src/application/ValidateChangeUseCase");
+const DiskProjectRepository_1 = require("../../../../packages/core/src/infrastructure/DiskProjectRepository");
+const diagnostics_1 = require("../../../lib/diagnostics");
+const against_lock_1 = require("../../../specops/against_lock");
+const requirement_graph_1 = require("../../../lib/requirement-graph");
+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 project_root_1 = require("../../../lib/project-root");
+const GherkinQuality_1 = require("../../../../packages/core/src/domain/GherkinQuality");
+const GherkinTags_1 = require("../../../../packages/core/src/domain/GherkinTags");
+const TraceabilityFormat_2 = 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");
+const ChangeWorkspace_2 = require("../../../../packages/core/src/infrastructure/ChangeWorkspace");
+class ValidateSpecsCommand extends command_1.BaseCommand {
+    io = null;
+    logInfo(msg) {
+        const stream = this.io && this.io.json ? process.stderr : process.stdout;
+        stream.write(`ℹ️ [INFO] ${msg}\n`);
+    }
+    logError(msg) {
+        process.stderr.write(`❌ [ERROR] ${msg}\n`);
+    }
+    usage() {
+        process.stdout.write("🔎 Usage:\n" +
+            "  validate_specs.js <project_dir> [--strict-tdd] [--strict-scenarios] " +
+            "[--strict-requirements] [--strict-links] [--against-lock]\n\n" +
+            "Checks:\n" +
+            "- minimum SDD structure\n" +
+            "- required files\n" +
+            "- at least one .feature file\n" +
+            "- unresolved placeholders ({{...}})\n" +
+            "- feature coverage in traceability.md\n" +
+            "- allowed status values in traceability.md\n" +
+            "- expected DDD Lite document headers when present\n\n" +
+            "--against-lock additionally enforces:\n" +
+            "- Every requirement the locked packs declare is present in the matrix\n" +
+            "- Its scenario and feature file still match what the pack declares\n\n" +
+            "--strict-scenarios additionally enforces, over features/**/*.feature:\n" +
+            "- No scenario Cucumber would see as empty (upper-case keywords are the usual cause)\n" +
+            "- Every scenario has a When and a Then, at least three steps and a title that names the behaviour\n" +
+            "- No vague, unfalsifiable step text; no Scenario Outline without Examples\n\n" +
+            "--strict-tdd additionally enforces:\n" +
+            "- No 'Test Artifact = TBD' when Status is In Dev or later\n" +
+            "- Every requirement has at least one traceability row\n" +
+            "- Every scenario row has a non-empty Scenario ID\n\n" +
+            "--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-links additionally enforces:\n" +
+            "- Every Feature file / Technical artifact / Test artifact the matrix declares as a\n" +
+            "  path still exists on disk\n");
+    }
+    logFix(lines) {
+        for (const line of Array.isArray(lines) ? lines : [lines]) {
+            process.stderr.write(`💡 [FIX] ${line}\n`);
+        }
+    }
+    logWarn(msg) {
+        const stream = this.io && this.io.json ? process.stderr : process.stdout;
+        stream.write(`⚠️ [WARN] ${msg}\n`);
+    }
+    /**
+     * True when the only Gherkin in the project is the placeholder `adopt` writes.
+     *
+     * `adopt` installs a skeleton and a baseline scenario so that `validate` passes
+     * on day one — deliberately, because a gate that rejects a fresh adoption is a
+     * gate nobody installs. The cost is that a project which never retro-filled a
+     * single requirement is indistinguishable from a healthy one at the only place
+     * most people look: the CI gate. Seen on `lixi-platform`, adopted months ago,
+     * still one placeholder requirement against 297 real tests (H15).
+     *
+     * So: still a pass, never an error — but it says so.
+     */
+    isAdoptionSkeletonOnly(targetDir, featureFiles) {
+        if (featureFiles.length !== 1)
+            return false;
+        const rel = path.relative(targetDir, featureFiles[0]).split(path.sep).join("/");
+        return rel === "features/adoption/baseline.feature";
+    }
+    fail(code, msg, exitCode = 1, fix = null) {
+        const fixLines = fix ? (Array.isArray(fix) ? fix : [fix]) : [];
+        if (this.io && this.io.json) {
+            const diag = (0, diagnostics_1.error)(code, msg, fixLines.length ? { fix: fixLines.join(" ") } : undefined);
+            if (exitCode === agent_1.EXIT.USAGE)
+                this.io.usage({ validation: null }, [diag]);
+            this.io.fail({ validation: null }, [diag]);
+            return;
+        }
+        this.logError(msg);
+        if (fixLines.length)
+            this.logFix(fixLines);
+        process.exit(exitCode);
+    }
+    validateMonorepo(targetDir, strictTdd, strictScenarios, strictRequirements, strictLinks) {
+        const cfgPath = path.join(targetDir, "specops.config.yaml");
+        if (!fs.existsSync(cfgPath))
+            return null;
+        let cfg;
+        try {
+            cfg = (0, YamlLite_1.parseYamlLite)(fs.readFileSync(cfgPath, "utf8"));
+        }
+        catch {
+            return null;
+        }
+        const projects = cfg && Array.isArray(cfg.projects) ? cfg.projects : null;
+        if (!projects || projects.length === 0)
+            return null;
+        this.logInfo(`🗂️ Monorepo: validating ${projects.length} project(s) from specops.config.yaml`);
+        const results = [];
+        for (const entry of projects) {
+            const rel = typeof entry === "string" ? entry : entry && entry.path;
+            if (!rel) {
+                results.push({ project: String(entry), ok: false, detail: "invalid projects entry" });
+                continue;
+            }
+            const subDir = path.join(targetDir, rel);
+            process.stdout.write(`\n── ${rel} ──\n`);
+            if (!fs.existsSync(subDir)) {
+                this.logError(`Project directory not found: ${rel}`);
+                this.logFix(`Fix the 'projects:' entry in specops.config.yaml or create ${rel}.`);
+                results.push({ project: rel, ok: false, detail: "directory not found" });
+                continue;
+            }
+            const root = (0, project_root_1.findCliRoot)(__dirname);
+            const scriptPath = fs.existsSync(path.join(root, "dist", "scripts", "validate_specs.js"))
+                ? path.join(root, "dist", "scripts", "validate_specs.js")
+                : path.join(root, "scripts", "validate_specs.js");
+            const args = [scriptPath, subDir];
+            if (strictTdd)
+                args.push("--strict-tdd");
+            if (strictScenarios)
+                args.push("--strict-scenarios");
+            if (strictRequirements)
+                args.push("--strict-requirements");
+            if (strictLinks)
+                args.push("--strict-links");
+            const r = (0, node_child_process_1.spawnSync)(process.execPath, args, { encoding: "utf8" });
+            process.stdout.write(r.stdout || "");
+            process.stderr.write(r.stderr || "");
+            results.push({ project: rel, ok: r.status === 0 });
+        }
+        const failures = results.filter((r) => !r.ok);
+        process.stdout.write("\n── monorepo summary ──\n");
+        for (const r of results) {
+            process.stdout.write(`  ${r.ok ? "✅" : "❌"} ${r.project}${r.detail ? ` (${r.detail})` : ""}\n`);
+        }
+        process.stdout.write(`\n${failures.length === 0 ? "✅" : "❌"} ${results.length - failures.length}/${results.length} project(s) passed\n`);
+        return { failures: failures.length };
+    }
+    /**
+     * `--strict-scenarios`: the pack's quality rules, applied where the harness
+     * actually runs (A3).
+     *
+     * `docs/specs/harness.md` says the gate is only as strong as its scenarios,
+     * and until now the rules that enforce that lived in `pack lint` and judged
+     * one thing: a `pack.yaml`. But a project's features arrive by three routes
+     * that never touch `pack lint` — `change archive`, `req add`, and a person
+     * with an editor. This closes that gap by reading the same domain rules.
+     *
+     * **Why a flag and not the default.** A project brought in with `specgate adopt`
+     * can have dozens of weak features written long before this tool existed;
+     * failing its first `validate` would teach people to skip the gate. `specgate
+     * doctor` reports the same findings as advisories, which is the gradual path
+     * 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) {
+        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));
+        }
+        if (findings.length === 0)
+            return;
+        if (this.io.json) {
+            this.io.fail({ validation: null }, findings);
+            return;
+        }
+        const errs = findings.filter((f) => f.severity === "error");
+        this.logError(`--strict-scenarios violations detected: ${findings.length} ` +
+            `(${errs.length} that make a scenario pass without testing anything)`);
+        for (const f of findings)
+            process.stderr.write(`  ${(0, diagnostics_1.formatDiagnostic)(f)}\n`);
+        this.logFix([
+            "Fix the errors first: a scenario Cucumber sees as empty reports `0 steps · exit 0`,",
+            "so the gate approves the requirement without having checked it.",
+        ]);
+        process.exit(1);
+    }
+    /**
+     * Does the scenario the matrix names actually exist in the file? (F4)
+     *
+     * The help text has been asking for a Scenario ID "that matches a scenario in
+     * its feature file" without ever comparing the two. Measured before writing
+     * this: rename the scenario and both `--strict-tdd` and `--strict-scenarios`
+     * still pass, with the matrix pointing at something that is not there.
+     *
+     * The check runs off tags, because a tag survives the rename and a title does
+     * not — and the matrix carries an id, not a title, so there is nothing else to
+     * compare. `specgate expand` writes them; nobody types them.
+     *
+     * **Only files that carry our tags are checked.** A project brought in with
+     * `specgate adopt`, or one scaffolded before this existed, has none — and failing
+     * it here would punish it for a link it was never given the means to make.
+     * Once a file is tagged, a row pointing into it has to be right.
+     */
+    checkScenarioTags(targetDir, traceContent) {
+        let rows = [];
+        try {
+            rows = (0, TraceabilityFormat_2.parseTraceabilityRows)(traceContent).rows || [];
+        }
+        catch {
+            return;
+        }
+        for (const row of rows) {
+            const scenarioId = String(row.scenarioId || "").trim();
+            const featureRel = String(row.featureFile || "")
+                .replace(/`/g, "")
+                .split("#")[0]
+                .trim();
+            if (!/^SCN-[A-Za-z0-9.]+$/.test(scenarioId) || !featureRel)
+                continue;
+            const file = path.join(targetDir, featureRel);
+            if (!fs.existsSync(file))
+                continue; // the coverage check below reports this
+            let tags = [];
+            try {
+                tags = (0, GherkinTags_1.csdaTagsIn)(fs.readFileSync(file, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            if (tags.length === 0)
+                continue; // untagged file — nothing to compare against
+            if (!tags.includes(`@${scenarioId}`)) {
+                this.fail("scenario_id_not_in_feature", `${featureRel} carries traceability tags but not @${scenarioId}, which ` +
+                    `${row.requirement || "a row"} declares. The matrix points at a scenario ` +
+                    `that is not there.`, 1, [
+                    `Tag the scenario: put \`@${scenarioId}\` above its \`Scenario:\` line,`,
+                    "or correct the Scenario ID in docs/specs/traceability.md.",
+                ]);
+            }
+        }
+    }
+    /**
+     * Does a declared link still point at something that exists? (F6 follow-on,
+     * `PLAN_PREDICTABLE_CODE_EVOLUTION.md` §8.5)
+     *
+     * The plan names the first honest check beyond paperwork: not formal
+     * verification, just the matrix's own promises kept — a file gets renamed
+     * or deleted and the row that names it is never updated, so the matrix
+     * points a reader (or an agent) at code that is not there.
+     *
+     * **`--strict-links`, not unconditional — measured, not assumed.** The
+     * first version of this check ran by default on the theory that "this path
+     * does not exist" has no legitimate reading. `tests/unit/validate-strict-
+     * tdd.test.ts` disproved that immediately: a `Draft` or `In Dev` row
+     * routinely names the file a requirement is *going to* land in before
+     * anyone writes it — planning ahead, not documentary drift. That is exactly
+     * the shape `DeclaredArtifacts`' own `declared_artifact_untouched` already
+     * treats as a warning, not a certainty, and the same reasoning applies here.
+     * Opt-in, same promise as `--strict-scenarios`: a project with aspirational
+     * rows does not fail its next `validate` over this.
+     */
+    checkDeclaredArtifactsExist(targetDir, traceContent) {
+        let rows = [];
+        try {
+            rows = (0, TraceabilityFormat_2.parseTraceabilityRows)(traceContent).rows || [];
+        }
+        catch {
+            return;
+        }
+        const findings = [];
+        const seen = new Set();
+        const columns = [
+            ["feature file", "featureFile"],
+            ["technical artifact", "technicalArtifact"],
+            ["test artifact", "testArtifact"],
+        ];
+        for (const row of rows) {
+            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];
+                    if (!rel || seen.has(`${row.requirement || row.feature}::${rel}`))
+                        continue;
+                    if (fs.existsSync(path.join(targetDir, rel)))
+                        continue;
+                    seen.add(`${row.requirement || row.feature}::${rel}`);
+                    findings.push((0, diagnostics_1.error)("declared_artifact_missing", `${row.requirement || row.feature || "a row"}'s ${label} \`${rel}\` does not exist.`, {
+                        target: row.requirement || row.feature,
+                        file: "docs/specs/traceability.md",
+                        fix: `Fix the path, or restore ${rel} if it was removed by mistake.`,
+                    }));
+                }
+            }
+        }
+        if (findings.length === 0)
+            return;
+        if (this.io.json) {
+            this.io.fail({ validation: null }, findings);
+            return;
+        }
+        this.logError(`Declared artifacts that no longer exist: ${findings.length}`);
+        for (const f of findings)
+            process.stderr.write(`  ${(0, diagnostics_1.formatDiagnostic)(f)}\n`);
+        this.logFix([
+            "The matrix is pointing at a file that is not there — fix the path,",
+            "or restore the file if it was removed by mistake.",
+        ]);
+        process.exit(1);
+    }
+    /**
+     * `--strict-requirements`: EARS-checkable requirement prose, at rest (F6).
+     *
+     * `PLAN_PREDICTABLE_CODE_EVOLUTION.md` §8.1 names the prerequisite for any
+     * code-level verifier: the spec has to say something a machine can check.
+     * `DeltaSpec` already enforces an obligation keyword (`no_rfc2119_keyword`),
+     * but only inside a delta — a capability spec at rest, `docs/specs/
+     * capabilities/<cap>/spec.md`, has never been checked. This reads every one
+     * of those, the only `spec.md` grammar in the project with a real parser
+     * (§8.3), and applies the same rule plus the one EARS shape a regex can
+     * check honestly.
+     *
+     * **Opt-in, same reasoning as `--strict-scenarios`.** A project's capability
+     * specs may predate this check; failing the default `validate` on them would
+     * teach people to skip the gate rather than fix the prose.
+     *
+     * **A project with no `docs/specs/capabilities/` is not a failure.** Most
+     * scaffolded projects never grow one — it is the change-lifecycle structure,
+     * not something `specgate init` writes. Nothing to check is not a violation.
+     */
+    checkRequirementSyntax(targetDir) {
+        const capabilitiesDir = path.join(targetDir, ChangeWorkspace_2.CAPABILITIES_DIR);
+        if (!fs.existsSync(capabilitiesDir))
+            return;
+        const findings = [];
+        for (const entry of fs
+            .readdirSync(capabilitiesDir, { withFileTypes: true })
+            .sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            const specPath = path.join(capabilitiesDir, entry.name, "spec.md");
+            if (!fs.existsSync(specPath))
+                continue;
+            const rel = path.relative(targetDir, specPath).split(path.sep).join("/");
+            const spec = (0, SpecParser_1.parseSpec)(fs.readFileSync(specPath, "utf8"));
+            for (const req of spec.requirements) {
+                const text = (0, SpecParser_1.blockText)(req.text);
+                if (!text.trim())
+                    continue;
+                findings.push(...(0, RequirementSyntax_1.analyseRequirementText)(text, {
+                    target: req.id || (0, SpecParser_1.requirementKey)(req) || req.name,
+                    file: rel,
+                    line: req.line,
+                }));
+            }
+        }
+        if (findings.length === 0)
+            return;
+        if (this.io.json) {
+            this.io.fail({ validation: null }, findings);
+            return;
+        }
+        this.logError(`--strict-requirements violations detected: ${findings.length}`);
+        for (const f of findings)
+            process.stderr.write(`  ${(0, diagnostics_1.formatDiagnostic)(f)}\n`);
+        this.logFix([
+            "State an obligation (SHALL / MUST / SHOULD / MAY, or DEBE / DEBERÁ), and if the",
+            "requirement opens with IF, resolve it with THEN in the same sentence.",
+        ]);
+        process.exit(1);
+    }
+    execute() {
+        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");
+        const againstLock = argv.includes("--against-lock");
+        const positional = argv.filter((a) => !a.startsWith("-"));
+        const targetDir = positional[0];
+        if (!targetDir) {
+            this.usage();
+            process.exit(2);
+        }
+        if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
+            this.fail("project_dir_not_found", `Directory not found: ${targetDir}`, agent_1.EXIT.USAGE, [
+                "Check the path for typos, or scaffold a new project first:",
+                "  specgate init",
+            ]);
+        }
+        const monorepo = this.validateMonorepo(targetDir, strictTdd, strictScenarios, strictRequirements, strictLinks);
+        if (monorepo !== null) {
+            process.exit(monorepo.failures === 0 ? 0 : 1);
+        }
+        const SKIP_DIRS = new Set([
+            "node_modules",
+            "dist",
+            "build",
+            "out",
+            "target",
+            "coverage",
+            "vendor",
+            ".git",
+            ".next",
+            ".gradle",
+            ".specops",
+        ]);
+        function walk(dir) {
+            const out = [];
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                if (entry.isDirectory() && SKIP_DIRS.has(entry.name))
+                    continue;
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory())
+                    out.push(...walk(full));
+                else
+                    out.push(full);
+            }
+            return out;
+        }
+        function findRecursive(rootDir, predicate) {
+            return walk(rootDir).filter(predicate);
+        }
+        const REQUIRED_FILES = [
+            "spec.md",
+            "AI_RULES.md",
+            "README.md",
+            "docs/specs/traceability.md",
+            "docs/specs/adr/README.md",
+        ];
+        const REQUIRED_DIRS = ["features", "docs/specs"];
+        const PLACEHOLDER_RE = /\{\{[A-Z_][A-Z0-9_]*\}\}/;
+        for (const d of REQUIRED_DIRS) {
+            if (!fs.existsSync(path.join(targetDir, d))) {
+                this.fail("missing_required_dir", `Missing required directory: ${d}`, 1, [
+                    `Create it: mkdir -p ${d}`,
+                    "Or scaffold the full SDD structure with `specgate init` / `specops add`.",
+                ]);
+            }
+        }
+        const FILE_FIXES = {
+            "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/adr/README.md": "Create docs/specs/adr/README.md as the index of your Architecture Decision Records.",
+        };
+        for (const f of REQUIRED_FILES) {
+            if (!fs.existsSync(path.join(targetDir, f))) {
+                this.fail("missing_required_file", `Missing required file: ${f}`, 1, [
+                    FILE_FIXES[f] || `Create ${f}.`,
+                    "Generated projects include every required file — compare with `specgate init --yes --out <tmp>`.",
+                ]);
+            }
+        }
+        const featuresDir = path.join(targetDir, "features");
+        const featureFiles = findRecursive(featuresDir, (f) => f.endsWith(".feature"));
+        if (featureFiles.length < 1) {
+            this.fail("no_feature_files", "No .feature files were found in features/", 1, [
+                "Write at least one Gherkin scenario, e.g. features/<area>/<name>.feature,",
+                "or pull scenarios from a domain pack: specgate specops add --pack-repo <url> …",
+            ]);
+        }
+        const featureCount = featureFiles.length;
+        if (strictScenarios) {
+            this.checkScenarioQuality(targetDir, featureFiles);
+        }
+        if (strictRequirements) {
+            this.checkRequirementSyntax(targetDir);
+        }
+        const offenders = (0, placeholders_1.findUnresolvedPlaceholders)(targetDir).map((rel) => path.join(targetDir, rel));
+        if (offenders.length > 0) {
+            this.logError("Unresolved placeholders detected");
+            const tokens = new Set();
+            for (const f of offenders) {
+                const lines = fs.readFileSync(f, "utf8").split("\n");
+                for (let i = 0; i < lines.length; i++) {
+                    if (PLACEHOLDER_RE.test(lines[i])) {
+                        process.stderr.write(`${f}:${i + 1}:${lines[i]}\n`);
+                        for (const m of lines[i].match(/\{\{[A-Z_][A-Z0-9_]*\}\}/g) || [])
+                            tokens.add(m);
+                    }
+                }
+            }
+            const varList = [...tokens].map((t) => String(t).replace(/[{}]/g, "")).join(", ");
+            this.logFix([
+                `Replace the tokens with real values, or re-expand the pack passing each variable:`,
+                `  specgate specops sync --project-dir . (after adding the missing vars to .specops.lock)`,
+                `Missing variables: ${varList}`,
+            ]);
+            process.exit(1);
+        }
+        const tracePath = path.join(targetDir, "docs/specs/traceability.md");
+        const traceContent = fs.readFileSync(tracePath, "utf8");
+        // Every judgement about the matrix's contents comes from the use case; this
+        // command's job from here is to render what it found and pick the exit code.
+        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,
+        });
+        const strictTddViolations = report.findings
+            .filter((f) => f.code === "strict_tdd_violation")
+            .map((f) => f.message);
+        for (const finding of report.findings) {
+            if (finding.code === "strict_tdd_violation")
+                continue; // reported together, below
+            this.fail(finding.code, finding.message, 1, [...(finding.fixLines || [])]);
+            return;
+        }
+        const traceMode = mode;
+        const TDD_FIXES = {
+            "TDD-1": "Write the test first, then set its path in the row's 'Test artifact' column (or move the status back to Draft).",
+            "TDD-2": "Give the row a Scenario ID that matches a scenario in its feature file (e.g. SCN-001).",
+            "TDD-3": "Add a traceability row for the requirement — run `specgate plan` to list what each REQ still needs.",
+        };
+        if (strictTddViolations.length > 0) {
+            if (this.io.json) {
+                this.io.fail({ validation: null }, strictTddViolations.map((v) => {
+                    const tdd = v.slice(1, 6);
+                    return (0, diagnostics_1.error)(`strict_tdd_${tdd.split("-")[1]}`, v, {
+                        fix: TDD_FIXES[tdd],
+                    });
+                }));
+                return;
+            }
+            this.logError("--strict-tdd violations detected:");
+            for (const v of strictTddViolations) {
+                process.stderr.write(`  ${v}\n`);
+            }
+            const codes = new Set(strictTddViolations.map((v) => v.slice(1, 6)));
+            this.logFix([...codes].sort().map((c) => `${c}: ${TDD_FIXES[c]}`));
+            process.exit(1);
+        }
+        this.checkScenarioTags(targetDir, traceContent);
+        if (strictLinks) {
+            this.checkDeclaredArtifactsExist(targetDir, traceContent);
+        }
+        for (const ff of featureFiles.sort()) {
+            const rel = path.relative(targetDir, ff).split(path.sep).join("/");
+            if (!traceContent.includes(rel)) {
+                const exampleRow = traceMode === "rich"
+                    ? `| REQ-TBD | SCN-TBD | \`${rel}\` | UC-TBD | TBD | TBD | TBD | TBD | TBD | Draft |`
+                    : `| \`${rel}\` | <scenario> | TBD | Draft |`;
+                this.fail("feature_not_in_matrix", `Feature file missing from traceability.md: ${rel}`, 1, [
+                    "Add a row for it to docs/specs/traceability.md, e.g.:",
+                    `  ${exampleRow}`,
+                ]);
+            }
+        }
+        const useCasesPath = path.join(targetDir, "docs/specs/use-cases.md");
+        if (fs.existsSync(useCasesPath)) {
+            const content = fs.readFileSync(useCasesPath, "utf8");
+            if (!content.includes("| ID | Use Case | Actor | Requirement | Command/Query | Aggregate | Emits")) {
+                this.fail("use_cases_header_missing", "use-cases.md is missing the expected table header", 1, [
+                    "Start the use-case table with:",
+                    "  | ID | Use Case | Actor | Requirement | Command/Query | Aggregate | Emits |",
+                ]);
+            }
+        }
+        const eventsPath = path.join(targetDir, "docs/specs/events.md");
+        if (fs.existsSync(eventsPath)) {
+            const content = fs.readFileSync(eventsPath, "utf8");
+            if (!content.includes("| ID | Event | Producer | Consumers | Payload |")) {
+                this.fail("events_header_missing", "events.md is missing the expected table header", 1, [
+                    "Start the events table with:",
+                    "  | ID | Event | Producer | Consumers | Payload |",
+                ]);
+            }
+        }
+        let changeCount = 0;
+        const changesDir = path.join(targetDir, "docs/specs/changes");
+        if (fs.existsSync(changesDir)) {
+            const ids = (0, ChangeWorkspace_1.listChangeIds)(targetDir);
+            changeCount = ids.length;
+            const problems = [];
+            const rawProblems = [];
+            for (const id of ids) {
+                const result = new ValidateChangeUseCase_1.ValidateChangeUseCase(new DiskProjectRepository_1.DiskProjectRepository(targetDir)).execute(id, {
+                    strict: false,
+                });
+                for (const d of result.diagnostics) {
+                    if (d.severity === "error") {
+                        rawProblems.push(d);
+                        problems.push((0, diagnostics_1.formatDiagnostic)(d));
+                    }
+                }
+            }
+            if (problems.length > 0) {
+                if (this.io.json) {
+                    this.io.fail({ validation: null }, rawProblems);
+                    return;
+                }
+                this.logError("Active changes have invalid delta specs:");
+                for (const line of problems)
+                    process.stderr.write(`  ${line}\n`);
+                process.exit(1);
+            }
+        }
+        let lockChecked = 0;
+        let lockAdvisories = [];
+        if (againstLock) {
+            const result = (0, against_lock_1.checkAgainstLock)(targetDir, {});
+            lockChecked = result.checked;
+            const errors = result.diagnostics.filter((d) => d.severity === "error");
+            const rest = result.diagnostics.filter((d) => d.severity !== "error");
+            if (!this.io.json) {
+                for (const d of rest)
+                    process.stdout.write(`  ${(0, diagnostics_1.formatDiagnostic)(d)}\n`);
+            }
+            if (errors.length > 0) {
+                if (this.io.json) {
+                    this.io.fail({ validation: null }, result.diagnostics);
+                    return;
+                }
+                this.logError("--against-lock violations detected:");
+                for (const d of errors)
+                    process.stderr.write(`  ${(0, diagnostics_1.formatDiagnostic)(d)}\n`);
+                process.exit(1);
+            }
+            lockAdvisories = rest;
+        }
+        {
+            const graph = (0, requirement_graph_1.requirementGraphFromProject)(targetDir, [...reqsInMatrix]);
+            const graphProblems = [];
+            for (const cycle of graph.cycles) {
+                const loop = [...cycle, cycle[0]].join(" → ");
+                graphProblems.push((0, diagnostics_1.error)("requirement_cycle", `Requirements depend on each other in a cycle: ${loop}`, {
+                    target: cycle[0],
+                    fix: `Remove one \`depends=\` from the csda:trace comment of one of them — ` +
+                        `${cycle.join(", ")} cannot all come after each other.`,
+                }));
+            }
+            for (const { requirement, dependency } of graph.unknown) {
+                graphProblems.push((0, diagnostics_1.error)("unknown_dependency", `${requirement} declares depends=${dependency}, which is not a requirement in this project.`, {
+                    target: requirement,
+                    fix: `Correct the id in ${requirement}'s csda:trace comment, or add a traceability row for ${dependency}.`,
+                }));
+            }
+            for (const requirement of graph.selfReferential) {
+                graphProblems.push((0, diagnostics_1.error)("self_dependency", `${requirement} declares that it depends on itself.`, {
+                    target: requirement,
+                    fix: `Remove \`depends=${requirement}\` from its csda:trace comment.`,
+                }));
+            }
+            if (graphProblems.length > 0) {
+                if (this.io.json) {
+                    this.io.fail({ validation: null }, graphProblems);
+                    return;
+                }
+                this.logError("Requirement dependency problems:");
+                for (const d of graphProblems)
+                    process.stderr.write(`  ${(0, diagnostics_1.formatDiagnostic)(d)}\n`);
+                process.exit(1);
+            }
+        }
+        const skeletonOnly = this.isAdoptionSkeletonOnly(targetDir, featureFiles);
+        const advisories = skeletonOnly
+            ? lockAdvisories.concat([
+                {
+                    severity: "warning",
+                    code: "adoption_not_retrofilled",
+                    message: "The only scenario in this project is the adoption baseline. Nothing the codebase actually does is specified yet.",
+                    target: "features/adoption/baseline.feature",
+                    fix: 'Retro-fill one requirement you already rely on: specgate onboard, then specgate req add "<behaviour>" and specgate req link.',
+                },
+            ])
+            : lockAdvisories;
+        if (this.io.json) {
+            this.io.emit({
+                validation: {
+                    projectDir: targetDir,
+                    passed: true,
+                    features: featureCount,
+                    activeChanges: changeCount,
+                    traceabilityMode: traceMode,
+                    strictTdd,
+                    againstLock,
+                    packsChecked: lockChecked,
+                    adoptionRetrofilled: !skeletonOnly,
+                },
+                status: advisories,
+            });
+            process.exit(agent_1.EXIT.OK);
+        }
+        this.logInfo("✅ Validation passed");
+        this.logInfo(`- Features detected: ${featureCount}`);
+        if (changeCount > 0)
+            this.logInfo(`- Active changes: ${changeCount} (deltas valid)`);
+        if (againstLock) {
+            this.logInfo(lockChecked > 0
+                ? `- Lock drift gate: passed (${lockChecked} pack(s) checked)`
+                : "- Lock drift gate: no locked packs to check");
+        }
+        this.logInfo("- Base SDD structure: complete");
+        this.logInfo(`- Traceability mode: ${traceMode}`);
+        if (strictTdd)
+            this.logInfo("- Strict TDD gate: passed");
+        if (skeletonOnly) {
+            this.logWarn("Adoption never retro-filled — the only scenario is the adoption baseline.");
+            this.logFix([
+                "This passes, but it certifies the skeleton, not the code.",
+                "  specgate onboard                     # what this codebase already implies",
+                '  specgate req add "<behaviour>"        # one requirement you already rely on',
+                "  specgate req link REQ-NNN --code <path> --test <path>",
+            ]);
+        }
+        process.exit(0);
+    }
+}
+exports.ValidateSpecsCommand = ValidateSpecsCommand;
+//# sourceMappingURL=ValidateSpecsCommand.js.map