@rsaglobaltech/specgate 0.8.1 → 0.10.0

package/dist/scripts/docs/highlight.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * Build-time syntax highlighting.
+ *
+ * ## Why not a library
+ *
+ * Prism and Shiki both do this better than 150 lines can. They would also be a
+ * new dependency in a repository that ships an SBOM, runs a licence allow-list
+ * over it (`npm run licences`) and puts "0 runtime dependencies" on its own
+ * landing page. The cost of a highlighter is not the download — it is that
+ * every future audit has to account for it.
+ *
+ * So: a deliberately conservative tokeniser. It knows strings, comments,
+ * numbers and a keyword list per language, and nothing else. It will not
+ * colour a nested template literal correctly and does not try.
+ *
+ * ## Why it cannot break a page
+ *
+ * The scanner only ever *wraps* text it has already escaped, and any input it
+ * does not recognise falls through as escaped literal. A language with no rules
+ * returns the same escaped source the old renderer produced, so an unknown
+ * fence is a plain block rather than a broken one.
+ *
+ * ## Why build time
+ *
+ * Highlighting in the browser means shipping a parser to every reader and
+ * repainting after first paint. These are static documents; the colours can be
+ * baked in and cost nothing at runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HIGHLIGHTED = void 0;
+exports.escapeHtml = escapeHtml;
+exports.highlight = highlight;
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** Shared shapes. Order matters: whatever matches first at a position wins. */
+const STRING = String.raw `"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|\`(?:[^\`\\]|\\.)*\``;
+const NUMBER = String.raw `\b\d+(?:\.\d+)?\b`;
+function keywords(...words) {
+    return String.raw `\b(?:${words.join("|")})\b`;
+}
+const LANGS = {
+    bash: [
+        { cls: "c", re: String.raw `#[^\n]*` },
+        { cls: "s", re: STRING },
+        { cls: "v", re: String.raw `\$\{?[A-Za-z_][\w]*\}?` },
+        {
+            cls: "k",
+            re: keywords("if", "then", "else", "fi", "for", "in", "do", "done", "while", "case", "esac", "function", "return", "export", "local", "set", "cd", "echo", "exit"),
+        },
+        { cls: "f", re: String.raw `(?<=^|\||&&|;|\n)\s*[a-z][\w-]*` },
+        // Anchored to whitespace: without it `your-existing-repo` reads as the
+        // flag `-existing-repo` and half the word turns blue.
+        { cls: "o", re: String.raw `(?<=^|\s)--?[A-Za-z][\w-]*` },
+        { cls: "n", re: NUMBER },
+    ],
+    json: [
+        { cls: "a", re: String.raw `"(?:[^"\\]|\\.)*"(?=\s*:)` },
+        { cls: "s", re: String.raw `"(?:[^"\\]|\\.)*"` },
+        { cls: "k", re: keywords("true", "false", "null") },
+        { cls: "n", re: NUMBER },
+    ],
+    yaml: [
+        { cls: "c", re: String.raw `#[^\n]*` },
+        { cls: "a", re: String.raw `(?<=^|\n)\s*[-\w.]+(?=\s*:)` },
+        { cls: "s", re: STRING },
+        { cls: "k", re: keywords("true", "false", "null", "yes", "no", "on", "off") },
+        { cls: "n", re: NUMBER },
+    ],
+    ts: [
+        { cls: "c", re: String.raw `//[^\n]*|/\*[\s\S]*?\*/` },
+        { cls: "s", re: STRING },
+        {
+            cls: "k",
+            re: keywords("import", "export", "from", "const", "let", "var", "function", "return", "if", "else", "for", "of", "while", "class", "extends", "implements", "interface", "type", "new", "await", "async", "try", "catch", "finally", "throw", "typeof", "instanceof", "readonly", "public", "private", "static", "true", "false", "null", "undefined", "this"),
+        },
+        { cls: "n", re: NUMBER },
+    ],
+    java: [
+        { cls: "c", re: String.raw `//[^\n]*|/\*[\s\S]*?\*/` },
+        { cls: "s", re: STRING },
+        { cls: "an", re: String.raw `@[A-Za-z]\w*` },
+        {
+            cls: "k",
+            re: keywords("package", "import", "public", "private", "protected", "class", "interface", "extends", "implements", "static", "final", "void", "new", "return", "if", "else", "for", "while", "try", "catch", "throws", "record", "var", "true", "false", "null"),
+        },
+        { cls: "n", re: NUMBER },
+    ],
+    xml: [
+        { cls: "c", re: String.raw `<!--[\s\S]*?-->` },
+        { cls: "s", re: String.raw `"(?:[^"\\]|\\.)*"` },
+        { cls: "t", re: String.raw `</?[A-Za-z][\w:.-]*|/?>` },
+    ],
+    gherkin: [
+        { cls: "c", re: String.raw `#[^\n]*` },
+        {
+            cls: "k",
+            re: String.raw `(?<=^|\n)\s*(?:Feature|Background|Scenario Outline|Scenario|Examples|Rule)(?=:)`,
+        },
+        { cls: "g", re: String.raw `(?<=^|\n)\s*(?:Given|When|Then|And|But)\b` },
+        { cls: "an", re: String.raw `@[\w-]+` },
+        { cls: "s", re: String.raw `<[^>\n]+>` },
+    ],
+    groovy: [
+        { cls: "c", re: String.raw `//[^\n]*|/\*[\s\S]*?\*/` },
+        { cls: "s", re: STRING },
+        {
+            cls: "k",
+            re: keywords("pipeline", "agent", "stages", "stage", "steps", "sh", "def", "if", "else", "return", "docker", "image", "any", "true", "false", "null"),
+        },
+        { cls: "n", re: NUMBER },
+    ],
+};
+/** Fences whose language is really another one. */
+const ALIASES = {
+    sh: "bash",
+    shell: "bash",
+    console: "bash",
+    javascript: "ts",
+    js: "ts",
+    typescript: "ts",
+    jsonc: "json",
+    yml: "yaml",
+    html: "xml",
+    svg: "xml",
+    feature: "gherkin",
+    kotlin: "java",
+    kts: "java",
+    groovy: "groovy",
+    jenkinsfile: "groovy",
+};
+const compiled = new Map();
+function scanner(lang) {
+    if (compiled.has(lang))
+        return compiled.get(lang);
+    const rules = LANGS[lang];
+    if (!rules)
+        return null;
+    // One alternation, groups in rule order, so priority is positional.
+    const re = new RegExp(rules.map((r) => `(${r.re})`).join("|"), "gm");
+    compiled.set(lang, re);
+    return re;
+}
+/**
+ * Escaped HTML for one code block, with `<span class="tok tok--X">` wrappers.
+ *
+ * Returns plain escaped text when the language is unknown, which is the same
+ * output the site produced before highlighting existed.
+ */
+function highlight(code, language) {
+    const lang = ALIASES[language.toLowerCase()] || language.toLowerCase();
+    const rules = LANGS[lang];
+    const re = scanner(lang);
+    if (!rules || !re)
+        return escapeHtml(code);
+    let out = "";
+    let last = 0;
+    re.lastIndex = 0;
+    for (let m = re.exec(code); m !== null; m = re.exec(code)) {
+        // A zero-width match would spin forever; step past it.
+        if (m[0] === "") {
+            re.lastIndex += 1;
+            continue;
+        }
+        out += escapeHtml(code.slice(last, m.index));
+        const which = m.slice(1).findIndex((g) => g !== undefined);
+        const cls = which === -1 ? "" : rules[which].cls;
+        out += cls ? `<span class="tok tok--${cls}">${escapeHtml(m[0])}</span>` : escapeHtml(m[0]);
+        last = m.index + m[0].length;
+    }
+    return out + escapeHtml(code.slice(last));
+}
+/** Languages that actually get colour, for the tests and for documentation. */
+exports.HIGHLIGHTED = Object.keys(LANGS);
+//# sourceMappingURL=highlight.js.map

package/dist/scripts/docs/highlight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlight.js","sourceRoot":"","sources":["../../../scripts/docs/highlight.ts"],"names":[],"mappings":"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"}

package/dist/scripts/docs/icons.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * The icon set the site draws from.
+ *
+ * Inline SVG rather than an icon font or sprite sheet, for two reasons that
+ * both come from how this site is built: there is no bundler to subset a font
+ * with, and every colour on the page is a `var(--…)` token so the theme toggle
+ * works — `stroke="currentColor"` inherits that for free, a font glyph or a
+ * remote `<img>` would not.
+ *
+ * Twenty-four by twenty-four, 1.5 stroke, no fills. Keep them geometric: these
+ * sit at 16-20px in a sidebar and anything fussier turns to mud.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ICON_NAMES = void 0;
+exports.icon = icon;
+exports.hasIcon = hasIcon;
+const ICONS = {
+    // Start here — a flag planted at the beginning.
+    rocket: '<path d="M12 3c3 2 5 5.5 5 9l-5 4-5-4c0-3.5 2-7 5-9Z"/><circle cx="12" cy="10" r="1.6"/><path d="M9 17l-2 4 4-2M15 17l2 4-4-2"/>',
+    // Writing specs — a document with lines.
+    file: '<path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8Z"/><path d="M14 3v5h5M9 13h6M9 17h4"/>',
+    // Agents — a small machine with an eye.
+    robot: '<rect x="4" y="8" width="16" height="12" rx="2"/><path d="M12 8V4M8 4h8"/><circle cx="9" cy="13" r="1"/><circle cx="15" cy="13" r="1"/><path d="M9 17h6"/>',
+    // Running it for real — a stack of servers.
+    server: '<rect x="3" y="4" width="18" height="6" rx="1.5"/><rect x="3" y="14" width="18" height="6" rx="1.5"/><path d="M7 7h.01M7 17h.01"/>',
+    // Reference — a book.
+    book: '<path d="M4 5.5A2.5 2.5 0 0 1 6.5 3H20v15H6.5A2.5 2.5 0 0 0 4 20.5Z"/><path d="M4 5.5v15"/>',
+    // Background — a compass, for reading around the subject.
+    compass: '<circle cx="12" cy="12" r="9"/><path d="m15.5 8.5-2 5-5 2 2-5Z"/>',
+    // The gate itself.
+    shield: '<path d="M12 3l7 3v6c0 4-3 7.5-7 9-4-1.5-7-5-7-9V6Z"/><path d="m9 12 2 2 4-4"/>',
+    terminal: '<rect x="3" y="4" width="18" height="16" rx="2"/><path d="m7 9 3 3-3 3M13 15h4"/>',
+    play: '<circle cx="12" cy="12" r="9"/><path d="m10 8.5 6 3.5-6 3.5Z"/>',
+    package: '<path d="M21 8v8l-9 5-9-5V8l9-5Z"/><path d="m3 8 9 5 9-5M12 13v8"/>',
+    code: '<path d="m8 6-5 6 5 6M16 6l5 6-5 6"/>',
+    link: '<path d="M10 13a5 5 0 0 0 7 0l2-2a5 5 0 0 0-7-7l-1 1"/><path d="M14 11a5 5 0 0 0-7 0l-2 2a5 5 0 0 0 7 7l1-1"/>',
+    search: '<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/>',
+    spark: '<path d="M12 3v4M12 17v4M3 12h4M17 12h4M6 6l2.5 2.5M15.5 15.5 18 18M18 6l-2.5 2.5M8.5 15.5 6 18"/>',
+    check: '<circle cx="12" cy="12" r="9"/><path d="m8 12 3 3 5-6"/>',
+    arrow: '<path d="M5 12h14M13 6l6 6-6 6"/>',
+};
+/**
+ * One icon as inline SVG, or the empty string when the name is unknown.
+ *
+ * Unknown names return empty rather than throwing: an icon is decoration, and
+ * a missing one should not take the build down the way a missing diagram does.
+ * `aria-hidden` because every icon here sits beside its own text label.
+ */
+function icon(name, cls = "icon") {
+    if (!name)
+        return "";
+    const body = ICONS[name];
+    if (!body)
+        return "";
+    return (`<svg class="${cls}" viewBox="0 0 24 24" fill="none" stroke="currentColor" ` +
+        `stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`);
+}
+function hasIcon(name) {
+    return Boolean(name && ICONS[name]);
+}
+exports.ICON_NAMES = Object.keys(ICONS);
+//# sourceMappingURL=icons.js.map

package/dist/scripts/docs/icons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icons.js","sourceRoot":"","sources":["../../../scripts/docs/icons.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAuCH,oBAQC;AAED,0BAEC;AAjDD,MAAM,KAAK,GAA2B;IACpC,gDAAgD;IAChD,MAAM,EACJ,kIAAkI;IACpI,yCAAyC;IACzC,IAAI,EAAE,2GAA2G;IACjH,wCAAwC;IACxC,KAAK,EACH,4JAA4J;IAC9J,4CAA4C;IAC5C,MAAM,EACJ,oIAAoI;IACtI,sBAAsB;IACtB,IAAI,EAAE,6FAA6F;IACnG,0DAA0D;IAC1D,OAAO,EAAE,mEAAmE;IAC5E,mBAAmB;IACnB,MAAM,EAAE,iFAAiF;IACzF,QAAQ,EAAE,mFAAmF;IAC7F,IAAI,EAAE,iEAAiE;IACvE,OAAO,EAAE,qEAAqE;IAC9E,IAAI,EAAE,uCAAuC;IAC7C,IAAI,EAAE,gHAAgH;IACtH,MAAM,EAAE,2DAA2D;IACnE,KAAK,EACH,oGAAoG;IACtG,KAAK,EAAE,0DAA0D;IACjE,KAAK,EAAE,mCAAmC;CAC3C,CAAC;AAEF;;;;;;GAMG;AACH,SAAgB,IAAI,CAAC,IAAwB,EAAE,GAAG,GAAG,MAAM;IACzD,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,OAAO,CACL,eAAe,GAAG,0DAA0D;QAC5E,wFAAwF,IAAI,QAAQ,CACrG,CAAC;AACJ,CAAC;AAED,SAAgB,OAAO,CAAC,IAAwB;IAC9C,OAAO,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;AACtC,CAAC;AAEY,QAAA,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC"}

package/dist/scripts/docs/nav.js

@@ -3,8 +3,8 @@
  * The shape of the documentation site, decided once.
  *
  * Ordered by the question a reader is asking, not alphabetically and not by
- * the order the files happened to be written. Someone who has just run `npx
- * create-spec-driven-app` needs a different page from someone deciding whether
+ * the order the files happened to be written. Someone who has just run
+ * `npx @rsaglobaltech/specgate` needs a different page from someone deciding whether
  * to adopt the tool at all, and the sidebar should make that obvious without
  * being read end to end.
  *
@@ -21,6 +21,7 @@ exports.neighbours = neighbours;
 exports.NAV = [
     {
         title: "Start here",
+        icon: "rocket",
         summary: "Fifteen minutes from nothing to a project whose specs are checked by CI.",
         entries: [
             {
@@ -47,6 +48,7 @@ exports.NAV = [
     },
     {
         title: "Working with specs",
+        icon: "file",
         summary: "What a specification is here, and what the tool does with it.",
         entries: [
             {
@@ -73,6 +75,7 @@ exports.NAV = [
     },
     {
         title: "Agents and the harness",
+        icon: "robot",
         summary: "The part that spends money. Read the harness page before pointing an agent at anything.",
         entries: [
             {
@@ -99,6 +102,7 @@ exports.NAV = [
     },
     {
         title: "Running it for real",
+        icon: "server",
         summary: "CI, boards, and the things an enterprise asks before it says yes.",
         entries: [
             {
@@ -114,7 +118,7 @@ exports.NAV = [
             {
                 slug: "deployment",
                 label: "Deployment",
-                blurb: "Where the generated project expects to be deployed from.",
+                blurb: "How specgate's own docs site, npm package and container image are published.",
             },
             {
                 slug: "supply-chain",
@@ -125,6 +129,7 @@ exports.NAV = [
     },
     {
         title: "Reference",
+        icon: "book",
         summary: "Look things up.",
         entries: [
             {
@@ -159,6 +164,7 @@ exports.NAV = [
         // documents that explain *why* the tool is shaped this way, which makes
         // them the wrong ones to leave unreachable.
         title: "Background",
+        icon: "compass",
         summary: "Why it works this way.",
         entries: [
             {

package/dist/scripts/docs/nav.js.map

@@ -1 +1 @@
-{"version":3,"file":"nav.js","sourceRoot":"","sources":["../../../scripts/docs/nav.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"nav.js","sourceRoot":"","sources":["../../../scripts/docs/nav.ts"],"names":[],"mappings":"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"}

package/dist/scripts/gen_mcp_tools.js

@@ -72,6 +72,7 @@ import {
   ReadSpecTool,
   ListRequirementsTool,
   UpdateTraceabilityTool,
+  assertContractEditable,
 } from "./native-tools";
 
 export interface ITool {
@@ -147,11 +148,26 @@ export class GenericCliTool implements ITool {
      * "Unknown flag(s)" and an empty payload over MCP. The surface already
      * records which is which in \`json.args\`; this reads it instead of assuming.
      */
-    public readonly dirStyle: "flag" | "positional" = "flag"
+    public readonly dirStyle: "flag" | "positional" = "flag",
+    /**
+     * True when this command may write a path the write-scope rules protect.
+     * Computed at generation time from scripts/lib/surface.ts and
+     * WriteScope.DEFAULT_PROTECTED_PATHS, so the rule has one definition.
+     */
+    public readonly editsContract = false
   ) {}
 
   public handler(args: Record<string, unknown>) {
     const dir = ProjectHelper.ensureProjectDir(args.projectDir);
+
+    // C10-04. The prompt has always told the agent not to rewrite the
+    // specification it is being measured against; nothing enforced it over MCP.
+    // An agent that cannot make a scenario pass can otherwise relax the
+    // scenario, and the gate approves — the exact failure this product exists
+    // to prevent. The change cycle is the way to edit a spec on purpose, and it
+    // leaves a reviewable trail.
+    if (this.editsContract) assertContractEditable(this.name, dir);
+
     const argv = this.csda.split(" ");
     
     if (this.dirStyle === "positional") argv.push(dir);
@@ -200,6 +216,9 @@ for (const command of surface_1.SURFACE) {
         // directory positionally rather than behind `--project-dir`.
         const jsonDef = subDef ? subDef.json : cmdDef.json;
         const dirStyle = jsonDef && jsonDef.args === "<dir>" ? "positional" : "flag";
+        // `change *` is how a specification is edited on purpose; refusing it would
+        // leave no way to open the change the guard asks for.
+        const editsContract = Boolean((subDef ? subDef.editsContract : cmdDef.editsContract) && cmdDef.name !== "change");
         out += `TOOLS["${toolName}"] = new GenericCliTool(
   "${toolName}",
   ${JSON.stringify(summary)},
@@ -212,7 +231,8 @@ for (const command of surface_1.SURFACE) {
     },
     required: ["projectDir"]
   },
-  "${dirStyle}"
+  "${dirStyle}",
+  ${editsContract}
 );\n`;
     };
     if (command.subcommands) {

package/dist/scripts/gen_mcp_tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"gen_mcp_tools.js","sourceRoot":"","sources":["../../scripts/gen_mcp_tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gen_mcp_tools.js","sourceRoot":"","sources":["../../scripts/gen_mcp_tools.ts"],"names":[],"mappings":"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"}

package/dist/scripts/harness/init.js

@@ -59,6 +59,7 @@ const project_root_1 = require("../lib/project-root");
 const agent_1 = require("../lib/agent");
 const diagnostics_1 = require("../lib/diagnostics");
 const command_1 = require("../lib/command");
+const TestCommand_1 = require("../../packages/core/src/domain/TestCommand");
 const ROOT_DIR = path.resolve(__dirname, "..", "..", "..");
 const TEMPLATES = path.join(ROOT_DIR, "templates", "harness");
 const CONFIG_FILE = "harness.config.yaml";
@@ -69,7 +70,7 @@ const NULL_SHAPE = { projectDir: null, files: [] };
  * or `null` when nothing gives it away.
  *
  * `null` matters more than the guesses. `test_cmd` is an *additional* gate —
- * `harness run` always runs `validate --strict-tdd` first — so leaving it
+ * `harness run` always runs `validate --strict` first — so leaving it
  * unset is safe, while filling it with a placeholder is not. A placeholder
  * like `echo "set this"` exits 0, which is a gate that passes unconditionally:
  * the harness would mark requirements done without ever running a test. A
@@ -77,36 +78,21 @@ const NULL_SHAPE = { projectDir: null, files: [] };
  * exists, so this is the common case, not the edge one.
  */
 function detectTestCommand(projectDir) {
-    const has = (file) => fs.existsSync(path.join(projectDir, file));
-    if (has("package.json")) {
-        try {
-            const pkg = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8"));
-            const scripts = pkg.scripts || {};
-            // `verify` is this project's own convention for "the fast gate";
-            // prefer it, because `test` in a spec-driven repo often includes the
-            // end-to-end suite that stays red until the last requirement lands.
-            if (scripts.verify)
-                return "npm run verify";
-            if (scripts.test)
-                return "npm test";
-        }
-        catch {
-            // A malformed package.json is the user's problem, not a reason to fail
-            // scaffolding. Fall through to the generic guess.
-        }
-        return "npm test";
-    }
-    if (has("pom.xml"))
-        return "mvn -B test";
-    if (has("build.gradle") || has("build.gradle.kts"))
-        return "./gradlew test";
-    if (has("Cargo.toml"))
-        return "cargo test";
-    if (has("go.mod"))
-        return "go test ./...";
-    if (has("pyproject.toml") || has("setup.py"))
-        return "pytest";
-    return null;
+    // One detector, shared with `adopt`/`onboard`. They used to disagree on the
+    // same pom.xml — `./mvnw -B test` there, `mvn -B test` here — which a cold
+    // evaluator found by running both. `preferVerify` is the one intentional
+    // difference, and it is an argument so that it stays intentional.
+    return (0, TestCommand_1.detectTestCommand)({
+        exists: (rel) => fs.existsSync(path.join(projectDir, rel)),
+        read: (rel) => {
+            try {
+                return fs.readFileSync(path.join(projectDir, rel), "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+    }, { preferVerify: true });
 }
 function projectName(projectDir) {
     const specPath = path.join(projectDir, "spec.md");
@@ -192,14 +178,40 @@ class InitCommand extends command_1.BaseCommand {
         // Rendered into the config as a live key when known, and as a commented-out
         // one when not — see detectTestCommand for why a placeholder would be worse
         // than an absent key.
+        // Shared with `doctor`, which used to call a Gherkin quality check
+        // "every scenario runnable" in projects where nothing runs one.
+        const hasGherkinRunner = (0, TestCommand_1.hasGherkinRunner)({
+            exists: (rel) => fs.existsSync(path.join(projectDir, rel)),
+            read: (rel) => {
+                try {
+                    return fs.readFileSync(path.join(projectDir, rel), "utf8");
+                }
+                catch {
+                    return null;
+                }
+            },
+        });
         const vars = {
             PROJECT_NAME: projectName(projectDir),
+            STEP_DEFS_LINE: hasGherkinRunner
+                ? "- `features/step_definitions/**` and `features/support/**` — step definitions\n" +
+                    "  are code, not specification. This is the one place inside `features/` you\n" +
+                    "  own."
+                : "\nThis project has no Gherkin runner, so nothing executes a `.feature` here.\n" +
+                    "The scenarios are the specification and your tests are the proof: make the\n" +
+                    "test named in the matrix assert what the scenario says, in the project's own\n" +
+                    "test framework. Do not add a BDD runner to satisfy this prompt.",
+            SCENARIO_STEP: hasGherkinRunner
+                ? "2. Write or extend the step definitions so the scenario fails **for the right\n" +
+                    "   reason** — a missing implementation, not a typo in a step."
+                : "2. Write the test named in the traceability matrix so it fails **for the right\n" +
+                    "   reason** — a missing implementation, not a typo in the test.",
             TEST_CMD_LINE: testCmd
                 ? `test_cmd: "${testCmd}"`
                 : '# test_cmd: "npm test"   # ← set this once the project has a test command',
             GATE_COMMAND: testCmd
-                ? `${testCmd}\nspecgate validate . --strict-tdd`
-                : "specgate validate . --strict-tdd",
+                ? `${testCmd}\nspecgate validate . --strict`
+                : "specgate validate . --strict",
         };
         const outputs = [
             {
@@ -258,7 +270,7 @@ class InitCommand extends command_1.BaseCommand {
         if (!testCmd) {
             status.push((0, diagnostics_1.warning)("harness_test_cmd_unset", "No test command detected, so `test_cmd` is commented out.", {
                 target: CONFIG_FILE,
-                fix: "Set it once the project has one. Until then the gate is `validate --strict-tdd` alone, which is a real gate — a placeholder that exits 0 would not be.",
+                fix: "Set it once the project has one. Until then the gate is `validate . --strict` alone, which is a real gate — a placeholder that exits 0 would not be.",
             }));
         }
         io.emit({
@@ -269,8 +281,18 @@ class InitCommand extends command_1.BaseCommand {
         }, () => {
             for (const file of written)
                 process.stdout.write(`ℹ️ [INFO] write ${file}\n`);
+            // Warnings only reached `--json` before, so a text-mode user learned
+            // that a tracked file had changed from `git status` instead of from the
+            // command that changed it.
+            for (const d of status) {
+                if (d.severity !== "warning")
+                    continue;
+                process.stderr.write(`⚠️ [WARN] ${d.message}\n`);
+                if (d.fix)
+                    process.stderr.write(`💡 [FIX] ${d.fix}\n`);
+            }
             process.stdout.write("ℹ️ [INFO] ✅ Harness configured.\n" +
-                `ℹ️ [INFO]   gate: validate --strict-tdd${testCmd ? ` + ${testCmd}` : " (no test command detected)"}\n` +
+                `ℹ️ [INFO]   gate: validate . --strict${testCmd ? ` + ${testCmd}` : " (no test command detected)"}\n` +
                 "ℹ️ [INFO]   agent: not set — that is your choice and your credentials.\n" +
                 "ℹ️ [INFO] Next:\n" +
                 "ℹ️ [INFO]   1. Read .harness/prompt-prefix.md and make it sound like your team.\n" +
@@ -311,16 +333,36 @@ exports.GITATTRIBUTES_LINE = `docs/specs/traceability.md merge=${exports.MERGE_D
 function installMergeDriver(projectDir) {
     const attributesPath = path.join(projectDir, ".gitattributes");
     const existing = fs.existsSync(attributesPath) ? fs.readFileSync(attributesPath, "utf8") : "";
+    let appendedToTracked = false;
     if (!existing.includes(exports.GITATTRIBUTES_LINE)) {
+        // `.gitattributes` is committed, so appending to it changes a file the
+        // whole team shares. A cold evaluator found this the way you always find a
+        // silent write — in `git status`, after the fact — so the command says it.
+        appendedToTracked = existing !== "";
         const separator = existing === "" || existing.endsWith("\n") ? "" : "\n";
         fs.appendFileSync(attributesPath, `${separator}# Merge the traceability matrix row by row, so parallel harness\n` +
             `# branches do not collide on adjacent rows. Needs the driver registered:\n` +
             `#   specgate harness init --project-dir .\n` +
             `${exports.GITATTRIBUTES_LINE}\n`, "utf8");
     }
-    // The driver runs from the installed CLI, so the path is resolved here rather
-    // than assumed: a project does not have specgate in its own tree.
-    const driverScript = path.join(__dirname, "..", "merge-traceability.js");
+    // How the driver is addressed decides whether it works on anybody else's
+    // clone.
+    //
+    // It used to be `node "/Users/someone/.../merge-traceability.js"` — the path
+    // of whichever checkout ran `harness init` — while `.gitattributes` said
+    // `merge=csda-matrix` and was committed. A cold evaluator found the pair: a
+    // shared rule pointing at a directory that exists on one laptop.
+    //
+    // A project that has specgate in its own `node_modules` can be addressed
+    // relatively, which every clone reproduces when it installs. Otherwise the
+    // running CLI's own path is the only thing that works here and now — and
+    // then the command says out loud that it is local, rather than leaving the
+    // next person to find out during a merge.
+    const localBin = path.join(projectDir, "node_modules", "@rsaglobaltech", "specgate", "bin", "specgate.js");
+    const driverIsPortable = fs.existsSync(localBin);
+    const driverCommand = driverIsPortable
+        ? `node node_modules/@rsaglobaltech/specgate/bin/specgate.js merge-traceability`
+        : `node ${JSON.stringify(path.join(__dirname, "..", "merge-traceability.js"))}`;
     const gitConfig = (key, value) => (0, node_child_process_1.spawnSync)("git", ["-C", projectDir, "config", key, value], { encoding: "utf8" });
     // Order matters, and getting it wrong is worse than not doing it at all.
     //
@@ -337,7 +379,7 @@ function installMergeDriver(projectDir) {
     //
     // So `driver` goes in first and `name` only follows if it landed; and if it
     // did not, any stale `name` is removed rather than left pointing at nothing.
-    const configured = gitConfig(`merge.${exports.MERGE_DRIVER_NAME}.driver`, `node ${JSON.stringify(driverScript)} %O %A %B`);
+    const configured = gitConfig(`merge.${exports.MERGE_DRIVER_NAME}.driver`, `${driverCommand} %O %A %B`);
     if (configured.status !== 0) {
         (0, node_child_process_1.spawnSync)("git", ["-C", projectDir, "config", "--unset", `merge.${exports.MERGE_DRIVER_NAME}.name`], {
             encoding: "utf8",
@@ -345,12 +387,31 @@ function installMergeDriver(projectDir) {
         return (0, diagnostics_1.warning)("merge_driver_not_registered", "Could not register the traceability merge driver in git config.", {
             target: ".gitattributes",
             fix: `Run it by hand inside the project:\n` +
-                `  git config merge.${exports.MERGE_DRIVER_NAME}.driver 'node ${driverScript} %O %A %B'\n` +
+                `  git config merge.${exports.MERGE_DRIVER_NAME}.driver '${driverCommand} %O %A %B'\n` +
                 "Until then git uses its built-in merge, which conflicts when two " +
                 "harness branches touch adjacent rows.",
         });
     }
     gitConfig(`merge.${exports.MERGE_DRIVER_NAME}.name`, "csda traceability matrix merge");
+    if (!driverIsPortable) {
+        return (0, diagnostics_1.warning)("merge_driver_is_machine_local", "The merge driver points at this machine's copy of specgate.", {
+            target: ".gitattributes",
+            fix: "`.gitattributes` is committed and names the driver; the driver itself is " +
+                "local git config, so every other clone and CI runner must run `specgate " +
+                "harness init` once or git falls back to its built-in merge (safe, just " +
+                "noisier on parallel branches).\n" +
+                "To make it reproducible instead, add specgate to the project: " +
+                "`npm i -D @rsaglobaltech/specgate` and re-run this — the driver is then " +
+                "a path inside node_modules that every clone rebuilds." +
+                (appendedToTracked ? "\nThis also appended to your existing .gitattributes." : ""),
+        });
+    }
+    if (appendedToTracked) {
+        return (0, diagnostics_1.warning)("gitattributes_modified", "Appended a merge rule to your existing .gitattributes — a tracked file.", {
+            target: ".gitattributes",
+            fix: "Review and commit it. The rule is shared; the driver behind it is per-clone.",
+        });
+    }
     return null;
 }
 if (require.main === module)