@warpgogol/forge 5.2.3 → 5.3.0

package/src/tests/doctor-nested-agents.test.ts

@@ -0,0 +1,160 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the nested-AGENTS.md doctor check — consumer-declared
+workspace discovery exclusions via bindings.workspaces.skipDirs (RFC-1150).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1150: initial nested-AGENTS.md skipDirs tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, appendFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDoctor } from "../onboarding/doctor.ts";
+import { generateNestedAgentsMd } from "../onboarding/nested-agents-generate.ts";
+import { buildGeneratedHeader } from "../utils/index.ts";
+import { loadForgeConfig } from "../config/forge-config.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "doctor-nested-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+function forgeYaml(skipDirs: string[]): string {
+  const skip = skipDirs.length > 0 ? `\n  workspaces:\n    skipDirs: [${skipDirs.join(", ")}]` : "";
+  return `schema: "forge/config@1"
+project:
+  name: test-project
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+  sessionsDir: docs/sessions
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: null
+    validateAdr: null
+    implementStamp: null
+    typecheck: null
+    test: null
+    scopedBuild: null
+    specValidate: null
+    sessionSave: null
+  paths:
+    invariantsFile: null
+    compassDocs: []
+    reviewsDir: null
+    handoffsDir: null
+    sessionsDir: null${skip}
+`;
+}
+
+test("nested-AGENTS.md check excludes dirs declared in workspaces.skipDirs", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), forgeYaml(["builds"]), "utf8");
+  // Artifact dir that would otherwise be discovered as a workspace
+  await mkdir(join(tempDir, "builds", "out"), { recursive: true });
+  await writeFile(join(tempDir, "builds", "out", "package.json"), "{}");
+  // Real workspace without AGENTS.md — must still be reported missing
+  await mkdir(join(tempDir, "packages", "real-pkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "real-pkg", "package.json"), "{}");
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check).toBeDefined();
+  // missing-only reports pass (warn requires stale>0) — assert on message
+  expect(check!.message).toContain("packages/real-pkg");
+  expect(check!.message).not.toContain("builds");
+});
+
+test("nested-AGENTS.md check reports artifact dir as missing without skipDirs", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), forgeYaml([]), "utf8");
+  await mkdir(join(tempDir, "builds", "out"), { recursive: true });
+  await writeFile(join(tempDir, "builds", "out", "package.json"), "{}");
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check).toBeDefined();
+  expect(check!.message).toContain("builds");
+});
+
+// RFC-1153: boundary-aware staleness -----------------------------------------
+
+test("AC-8: custom content below the forge:custom boundary reports in-sync, not stale", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), forgeYaml([]), "utf8");
+  await mkdir(join(tempDir, "packages", "pkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "pkg", "package.json"), '{"name":"pkg"}', "utf8");
+
+  const config = loadForgeConfig(tempDir);
+  await generateNestedAgentsMd(tempDir, config, false);
+
+  // Operator appends a custom section below the marker
+  await appendFile(
+    join(tempDir, "packages", "pkg", "AGENTS.md"),
+    "\n## Custom rules\n\n- workspace-specific note\n",
+    "utf8",
+  );
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check).toBeDefined();
+  expect(
+    check!.message,
+    "Below-boundary divergence must not count as stale — merge(expected, actual) compares only the head",
+  ).not.toContain("stale");
+});
+
+test("AC-6: divergent file without a resolvable boundary reports unmapped-customization", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), forgeYaml([]), "utf8");
+  await mkdir(join(tempDir, "packages", "legacy"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "legacy", "package.json"), '{"name":"legacy"}', "utf8");
+  // Marker-bearing (isGenerated) file that diverges and lacks footer/forge:custom
+  await writeFile(
+    join(tempDir, "packages", "legacy", "AGENTS.md"),
+    `${buildGeneratedHeader({ filePath: "AGENTS.md", ownerCommand: "forge.agents.generate", editable: true })}\n# Hand-maintained\n\ndivergent body\n`,
+    "utf8",
+  );
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check).toBeDefined();
+  expect(check!.status).toBe("warn");
+  expect(check!.message).toContain("unmapped-customization");
+  expect(check!.message).not.toContain("stale");
+});

package/src/tests/editable-generated-region.test.ts

@@ -0,0 +1,231 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the RFC-1153 preservation boundary — splitEditableGenerated
+and mergeEditableGenerated (forge:custom marker + canonical-footer fallback),
+plus an integration pass through generateNestedAgentsMd on a temp workspace.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1153: initial boundary merge tests — marker, footer fallback, fail-closed, comment styles, CRLF, integration.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile, readFile, appendFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  splitEditableGenerated,
+  mergeEditableGenerated,
+  canonicalFooterOf,
+} from "../utils/editable-region.ts";
+import {
+  CUSTOM_BOUNDARY_HINTS,
+  CUSTOM_BOUNDARY_MARKERS,
+  buildGeneratedHeader,
+} from "../utils/generated-marker.ts";
+import { generateNestedAgentsMd } from "../onboarding/nested-agents-generate.ts";
+import { loadForgeConfig } from "../config/forge-config.ts";
+
+const MD = "AGENTS.md";
+const MD_MARKER = CUSTOM_BOUNDARY_MARKERS["block-html"]; // <!-- forge:custom -->
+const MD_HINT = CUSTOM_BOUNDARY_HINTS["block-html"];
+
+const FOOTER = "See the root `AGENTS.md` for project-wide rules, skills, and capabilities.";
+
+function render(body: string): string {
+  return `${buildGeneratedHeader({ filePath: MD, ownerCommand: "forge.agents.generate", editable: true })}\n${body}\n\n${FOOTER}\n`;
+}
+
+test("AC-1: content below the forge:custom marker is preserved byte-identical", () => {
+  const tail = "\n## Workspace rules\n\n- always run pnpm test first\n- custom note\n";
+  const existing = `${render("old body v1")}${MD_MARKER}\n${MD_HINT}\n${tail}`;
+  const merged = mergeEditableGenerated(render("fresh body v2"), existing, MD);
+  expect(merged).not.toBeNull();
+  // Fresh head regenerated, tail below the marker verbatim
+  expect(merged).toContain("fresh body v2");
+  expect(merged).not.toContain("old body v1");
+  expect(
+    merged!.endsWith(tail.trimStart() === tail ? tail : `\n${tail}`) || merged!.includes(tail),
+  ).toBe(true);
+  expect(merged).toContain(MD_MARKER);
+});
+
+test("marker line itself belongs to the generated head — operator-placed marker also merges", () => {
+  const tail = "everything below survives\n";
+  const existing = `hand-tuned intro\n${MD_MARKER}\n${tail}`;
+  const merged = mergeEditableGenerated(render("body"), existing, MD);
+  expect(merged).toBe(`${render("body")}${MD_MARKER}\n${MD_HINT}\n${tail}`);
+});
+
+test("AC-2: footer fallback preserves text below the canonical template footer", () => {
+  const tail = "\noperator-appended rules\n";
+  const existing = `${render("stale body")}${tail}`; // marker-less, ends with footer + tail
+  const merged = mergeEditableGenerated(render("new body"), existing, MD);
+  expect(merged).not.toBeNull();
+  expect(merged!.endsWith(tail)).toBe(true);
+});
+
+test("AC-3: footer-fallback merge introduces the forge:custom marker as the new boundary", () => {
+  const existing = `${render("body")}\ncustom tail\n`;
+  const merged = mergeEditableGenerated(render("body"), existing, MD);
+  expect(merged).toContain(MD_MARKER);
+  expect(merged).toContain(MD_HINT);
+});
+
+test("AC-5: footer-less marker-less divergent content returns null — caller must skip", () => {
+  const existing = `${buildGeneratedHeader({ filePath: MD, ownerCommand: "forge.agents.generate", editable: true })}\n# Custom\n\ntotally divergent, no footer\n`;
+  expect(mergeEditableGenerated(render("body"), existing, MD)).toBeNull();
+});
+
+test("identical content is a clean regeneration — marker appended for future runs", () => {
+  const r = render("body");
+  const merged = mergeEditableGenerated(r, r, MD);
+  expect(merged).toBe(`${r}${MD_MARKER}\n${MD_HINT}\n`);
+});
+
+test("new file (existing null) gains the boundary marker and hint", () => {
+  const merged = mergeEditableGenerated(render("body"), null, MD);
+  expect(merged).toBe(`${render("body")}${MD_MARKER}\n${MD_HINT}\n`);
+});
+
+test("AC-4: boundary marker is emitted in the comment style of the target file", () => {
+  for (const [file, style] of [
+    ["AGENTS.md", "block-html"],
+    ["config.ts", "line-slash"],
+    ["data.yaml", "line-hash"],
+    ["styles.css", "block-css"],
+  ] as const) {
+    const merged = mergeEditableGenerated("content\n", null, file);
+    expect(merged, `marker for ${file} must use ${style} comment syntax`).toContain(
+      CUSTOM_BOUNDARY_MARKERS[style],
+    );
+  }
+});
+
+test("CRLF input normalizes to LF and still resolves the marker boundary", () => {
+  const tail = "preserved tail\n";
+  const existing = `a\r\nb\r\n${MD_MARKER}\r\n${tail}`;
+  const merged = mergeEditableGenerated("fresh\n", existing, MD);
+  expect(merged).toBe(`fresh\n${MD_MARKER}\n${MD_HINT}\n${tail}`);
+  expect(merged).not.toContain("\r\n");
+});
+
+test("mid-file marker freezes everything below the first occurrence", () => {
+  const tail = "mid doc\nfrozen rules\n";
+  const existing = `intro\n${MD_MARKER}\n${tail}`;
+  const merged = mergeEditableGenerated(render("body"), existing, MD);
+  expect(merged!.endsWith(tail)).toBe(true);
+});
+
+test("forge:custom token in prose is treated as a boundary (first occurrence wins)", () => {
+  const existing = `notes on the forge:custom feature\nkept anyway\n`;
+  const split = splitEditableGenerated(existing, MD);
+  expect(split.boundary).toBe("marker");
+  expect(split.customTail).toBe("kept anyway\n");
+});
+
+test("boundary none: split returns whole content as head", () => {
+  const split = splitEditableGenerated("plain\nfile\n", MD, FOOTER);
+  expect(split.boundary).toBe("none");
+  expect(split.customTail).toBeNull();
+});
+
+test("canonicalFooterOf returns the last non-empty line", () => {
+  expect(canonicalFooterOf("a\nb\n\n\n")).toBe("b");
+  expect(canonicalFooterOf("x\n")).toBe("x");
+});
+
+// --- Integration through the real write path -----------------------------
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "editable-region-it-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+const FORGE_YAML = `schema: "forge/config@1"
+project:
+  name: test-project
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+  sessionsDir: docs/sessions
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: null
+    validateAdr: null
+    implementStamp: null
+    typecheck: null
+    test: null
+    scopedBuild: null
+    specValidate: null
+    sessionSave: null
+  paths:
+    invariantsFile: null
+    compassDocs: []
+    reviewsDir: null
+    handoffsDir: null
+    sessionsDir: null
+`;
+
+test("generateNestedAgentsMd regenerates the head and preserves the custom tail", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, "packages", "pkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "pkg", "package.json"), '{"name":"pkg"}', "utf8");
+
+  const config = loadForgeConfig(tempDir);
+
+  // First run — fresh file gains the marker + hint
+  const first = await generateNestedAgentsMd(tempDir, config, false);
+  expect(first.generated).toContain(join("packages", "pkg", "AGENTS.md"));
+  const agentsPath = join(tempDir, "packages", "pkg", "AGENTS.md");
+  const initial = await readFile(agentsPath, "utf8");
+  expect(initial).toContain(MD_MARKER);
+  expect(initial).toContain(MD_HINT);
+
+  // Operator appends a custom section below the boundary
+  await appendFile(agentsPath, "\n## Workspace rules\n\n- never touch dist/\n", "utf8");
+
+  // Second run — head regenerated, tail preserved verbatim
+  const second = await generateNestedAgentsMd(tempDir, config, false);
+  expect(second.preserved).toContain(join("packages", "pkg", "AGENTS.md"));
+  const merged = await readFile(agentsPath, "utf8");
+  expect(merged).toContain("## Workspace rules");
+  expect(merged).toContain("- never touch dist/");
+  // Boundary sits between generated head and custom tail
+  expect(merged.indexOf(MD_MARKER)).toBeLessThan(merged.indexOf("## Workspace rules"));
+});
+
+test("generateNestedAgentsMd skips a divergent file without a resolvable boundary", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, "packages", "legacy"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "legacy", "package.json"), '{"name":"legacy"}', "utf8");
+  // Marker-bearing (isGenerated) file whose body diverges and lacks the footer
+  await writeFile(
+    join(tempDir, "packages", "legacy", "AGENTS.md"),
+    `${buildGeneratedHeader({ filePath: "AGENTS.md", ownerCommand: "forge.agents.generate", editable: true })}\n# Hand-maintained\n\ndivergent body\n`,
+    "utf8",
+  );
+
+  const config = loadForgeConfig(tempDir);
+  const result = await generateNestedAgentsMd(tempDir, config, false);
+  const skippedEntry = result.skipped.find((s) => s.includes("legacy"));
+  expect(
+    skippedEntry,
+    "Divergent file without forge:custom/footer boundary must be skipped as unmapped-customization",
+  ).toContain("unmapped-customization");
+  // File untouched
+  const content = await readFile(join(tempDir, "packages", "legacy", "AGENTS.md"), "utf8");
+  expect(content).toContain("divergent body");
+});

package/src/tests/file-size-lint.test.ts

@@ -31,7 +31,10 @@ function mockContext(workspaceRoot: string): ForgeRuntimeContext {
   };
 }
 
-function input(flags: Record<string, unknown> = {}): { argv: string[]; flags: Record<string, unknown> } {
+function input(flags: Record<string, unknown> = {}): {
+  argv: string[];
+  flags: Record<string, unknown>;
+} {
   return { argv: [], flags };
 }
 
@@ -108,16 +111,10 @@ describe("runFileSizeLint (RFC-1088, command-level)", () => {
     const big = Array.from({ length: 700 }, (_, i) => `const x${i} = ${i};`).join("\n");
     await writeFile(join(tempDir, "packages", "some-pkg", "src", "big.ts"), big, "utf8");
 
-    const result = await runFileSizeLint(
-      input({ "write-baseline": true }),
-      mockContext(tempDir),
-    );
+    const result = await runFileSizeLint(input({ "write-baseline": true }), mockContext(tempDir));
     expect(result.exitCode ?? 0).toBe(0);
 
-    const baselineRaw = await readFile(
-      join(tempDir, "file-size-lint.baseline.yaml"),
-      "utf8",
-    );
+    const baselineRaw = await readFile(join(tempDir, "file-size-lint.baseline.yaml"), "utf8");
     expect(baselineRaw).toContain("schemaVersion");
     expect(baselineRaw).toContain("threshold: 600");
     expect(baselineRaw).toContain("big.ts");
@@ -155,9 +152,8 @@ describe("runFileSizeLint (RFC-1088, command-level)", () => {
     const result = await runFileSizeLint(input(), mockContext(tempDir));
     expect(result.exitCode ?? 0).toBe(0);
 
-    const diagnostics = (
-      result.data as { diagnostics: Array<{ ruleId: string; message: string }> }
-    ).diagnostics;
+    const diagnostics = (result.data as { diagnostics: Array<{ ruleId: string; message: string }> })
+      .diagnostics;
     const hit = diagnostics.find((d) => d.ruleId === "SIZE-01");
     expect(hit).toBeDefined();
     expect(hit!.message).toContain("grew from the baselined 700 to 800");

package/src/tests/fixtures/agents-generate-business-before.txt

@@ -35,76 +35,76 @@
 
 ## Skills
 
-| Name | Category | Invocation | Concerns |
-| --- | --- | --- | --- |
-| fo-add-tests | fo | user | code-mutation |
-| fo-architecture | fo | user | document-only |
-| fo-compass-annotate | fo | user | content-mutation |
-| fo-design-summit | fo | user | document-only |
-| fo-doc-audit | fo | user | document-only |
-| fo-explore | fo | user | document-only |
-| fo-extract-dna | fo | user | document-only |
-| fo-fix | fo | user | code-mutation |
-| fo-handoff | fo | user | document-only |
-| fo-harvest | fo | user | code-mutation |
-| fo-idea | fo | user | document-only |
-| fo-idea-audit | fo | user | read-only |
-| fo-idea-create-adr | fo | user | document-only |
-| fo-idea-create-rfc | fo | user | document-only |
-| fo-idea-enhance | fo | user | document-only |
-| fo-idea-i-just-want-to-see-the-plan | fo | user | document-only |
-| fo-idea-i-just-want-to-see-the-result | fo | user | code-mutation |
-| fo-idea-implement | fo | user | code-mutation |
-| fo-idea-plan | fo | user | document-only |
-| fo-idea-status | fo | user | read-only |
-| fo-knowledge-distill | fo | user | document-only |
-| fo-memory-sync | fo | user | content-mutation |
-| fo-qa | fo | user | document-only |
-| fo-review | fo | user | read-only |
-| fo-session-retro | fo | user | document-only |
-| fo-session-save | fo | user | document-only |
-| fo-spec-ingest | fo | user | document-only |
-| fo-step-commit | fo | model | code-mutation |
-| fo-triage | fo | user | document-only |
-| forge-bootstrap | meta | user | content-mutation |
-| grilling | shared | user | read-only |
-| my-preferences | shared | user | document-only |
-| port-to-forge | meta | user | code-mutation |
-| skill-create | meta | user | document-only |
-| windows-ai-tooling | shared | user | code-mutation |
-| writing-great-skills | shared | user | read-only |
+| Name                                  | Category | Invocation | Concerns         |
+| ------------------------------------- | -------- | ---------- | ---------------- |
+| fo-add-tests                          | fo       | user       | code-mutation    |
+| fo-architecture                       | fo       | user       | document-only    |
+| fo-compass-annotate                   | fo       | user       | content-mutation |
+| fo-design-summit                      | fo       | user       | document-only    |
+| fo-doc-audit                          | fo       | user       | document-only    |
+| fo-explore                            | fo       | user       | document-only    |
+| fo-extract-dna                        | fo       | user       | document-only    |
+| fo-fix                                | fo       | user       | code-mutation    |
+| fo-handoff                            | fo       | user       | document-only    |
+| fo-harvest                            | fo       | user       | code-mutation    |
+| fo-idea                               | fo       | user       | document-only    |
+| fo-idea-audit                         | fo       | user       | read-only        |
+| fo-idea-create-adr                    | fo       | user       | document-only    |
+| fo-idea-create-rfc                    | fo       | user       | document-only    |
+| fo-idea-enhance                       | fo       | user       | document-only    |
+| fo-idea-i-just-want-to-see-the-plan   | fo       | user       | document-only    |
+| fo-idea-i-just-want-to-see-the-result | fo       | user       | code-mutation    |
+| fo-idea-implement                     | fo       | user       | code-mutation    |
+| fo-idea-plan                          | fo       | user       | document-only    |
+| fo-idea-status                        | fo       | user       | read-only        |
+| fo-knowledge-distill                  | fo       | user       | document-only    |
+| fo-memory-sync                        | fo       | user       | content-mutation |
+| fo-qa                                 | fo       | user       | document-only    |
+| fo-review                             | fo       | user       | read-only        |
+| fo-session-retro                      | fo       | user       | document-only    |
+| fo-session-save                       | fo       | user       | document-only    |
+| fo-spec-ingest                        | fo       | user       | document-only    |
+| fo-step-commit                        | fo       | model      | code-mutation    |
+| fo-triage                             | fo       | user       | document-only    |
+| forge-bootstrap                       | meta     | user       | content-mutation |
+| grilling                              | shared   | user       | read-only        |
+| my-preferences                        | shared   | user       | document-only    |
+| port-to-forge                         | meta     | user       | code-mutation    |
+| skill-create                          | meta     | user       | document-only    |
+| windows-ai-tooling                    | shared   | user       | code-mutation    |
+| writing-great-skills                  | shared   | user       | read-only        |
 
 ## Capabilities
 
 Bindings resolved from `forge.yaml`:
 
-| Key | Status | Value |
-| --- | --- | --- |
-| commands.validateRfc | resolved | `pnpm exec forge rfc.validate` |
-| commands.validateAdr | resolved | `pnpm exec forge adr.validate` |
-| commands.typecheck | absent | — |
-| commands.test | absent | — |
-| commands.scopedBuild | absent | — |
+| Key                   | Status   | Value                           |
+| --------------------- | -------- | ------------------------------- |
+| commands.validateRfc  | resolved | `pnpm exec forge rfc.validate`  |
+| commands.validateAdr  | resolved | `pnpm exec forge adr.validate`  |
+| commands.typecheck    | absent   | —                               |
+| commands.test         | absent   | —                               |
+| commands.scopedBuild  | absent   | —                               |
 | commands.specValidate | resolved | `pnpm exec forge spec.validate` |
-| commands.sessionSave | resolved | `pnpm exec forge session.save` |
-| paths.invariantsFile | resolved | `docs/architecture-dna.md` |
-| paths.reviewsDir | resolved | `docs/reviews` |
-| paths.handoffsDir | resolved | `docs/handoffs` |
-| paths.sessionsDir | resolved | `docs/sessions` |
-| paths.compassDocs | resolved | `docs/requirements.xml` |
+| commands.sessionSave  | resolved | `pnpm exec forge session.save`  |
+| paths.invariantsFile  | resolved | `docs/architecture-dna.md`      |
+| paths.reviewsDir      | resolved | `docs/reviews`                  |
+| paths.handoffsDir     | resolved | `docs/handoffs`                 |
+| paths.sessionsDir     | resolved | `docs/sessions`                 |
+| paths.compassDocs     | resolved | `docs/requirements.xml`         |
 
 <!-- forge:begin behavioral-layer -->
 
 ## Behavioral layer
 
-This section defines the agent's core behavioral contract. It is generated from skill `triggers` and fixed policy text. The agent MUST follow these behaviors in every session.
+This section defines the agent's core behavioral contract. It is generated from skill `triggerPhrases` and fixed policy text. The agent MUST follow these behaviors in every session.
 
 ### Intent-to-skill routing
 
-When the operator expresses an intent in natural language, the agent routes to the matching skill. The routing table is generated from `triggers` fields in skill frontmatter.
+When the operator expresses an intent in natural language, the agent routes to the matching skill. The routing table is generated from `triggerPhrases` fields in skill frontmatter.
 
 | Operator says something like | Skill |
-| --- | --- |
+| ---------------------------- | ----- |
 
 The agent uses judgment to calibrate routing — minor edits (typo fixes, small CSS changes) do not require skill invocation, while significant changes (new features, architectural decisions) do.