@warpgogol/forge 5.2.4 → 5.3.1

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,105 @@
 
 ## 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.
-
-| Operator says something like | Skill |
-| --- | --- |
+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                                   |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| "write tests for this code", "add unit tests", "add property-based tests", "write test coverage for this function"                                        | `fo-add-tests`                          |
+| "analyze codebase architecture", "find deepening opportunities", "review code structure quality"                                                          | `fo-architecture`                       |
+| "manage Compass headers", "annotate source files with Compass", "audit Compass module contracts"                                                          | `fo-compass-annotate`                   |
+| "design summit", "multi-persona review", "party mode"                                                                                                     | `fo-design-summit`                      |
+| "audit documentation sync", "update docs after code changes", "check AGENTS.md and README are in sync"                                                    | `fo-doc-audit`                          |
+| "explore this idea", "let me think about this", "what are the options for", "what if we"                                                                  | `fo-explore`                            |
+| "extract DNA invariant", "discover architectural invariants", "formalize implicit architectural rules"                                                    | `fo-extract-dna`                        |
+| "fix issues from review", "apply review findings and fix", "iterative fix workflow for code"                                                              | `fo-fix`                                |
+| "create a handoff document", "compact conversation for next agent", "prepare handoff for another agent"                                                   | `fo-handoff`                            |
+| "harvest portable patterns from code", "extract reusable code pattern to forge", "port this pattern to forge"                                             | `fo-harvest`                            |
+| "I have an idea for a change", "analyze this idea and route it", "decompose this feature idea", "does this need an RFC", "should I write an ADR for this" | `fo-idea`                               |
+| "audit this RFC", "check RFC for ecosystem fit", "review RFC against DNA and forward-only rules"                                                          | `fo-idea-audit`                         |
+| "record this architectural decision", "create an ADR", "document a local technical decision"                                                              | `fo-idea-create-adr`                    |
+| "draft an RFC", "create a full RFC", "scaffold an RFC from template"                                                                                      | `fo-idea-create-rfc`                    |
+| "enhance this RFC", "fix audit findings in RFC", "improve RFC based on audit"                                                                             | `fo-idea-enhance`                       |
+| "I just want to see the plan", "plan this feature without implementing", "run idea to plan pipeline"                                                      | `fo-idea-i-just-want-to-see-the-plan`   |
+| "I just want to see the result", "run the full pipeline automatically", "implement this end-to-end without pauses"                                        | `fo-idea-i-just-want-to-see-the-result` |
+| "implement this RFC", "execute the implementation plan", "realize this RFC end-to-end"                                                                    | `fo-idea-implement`                     |
+| "plan the implementation for this RFC", "create implementation plan", "map affected artifacts and draft steps"                                            | `fo-idea-plan`                          |
+| "show RFC and ADR status", "what is the status of this RFC", "list RFCs by status"                                                                        | `fo-idea-status`                        |
+| "distill knowledge", "compact skill knowledge", "knowledge lifecycle", "promote fix patterns"                                                             | `fo-knowledge-distill`                  |
+| "sync memory from codex", "import external agent knowledge", "recall sessions from other tools", "sync memory from claude code"                           | `fo-memory-sync`                        |
+| "I found a bug", "file a GitHub issue for this bug", "report a bug conversationally", "interactive QA session"                                            | `fo-qa`                                 |
+| "review this code diff", "check code against Forge standards", "fitness check on code changes"                                                            | `fo-review`                             |
+| "session retrospective", "triage session discoveries", "Завершаем эту сессию", "End session", "/session-end"                                              | `fo-session-retro`                      |
+| "save this session", "enhance session transcript with annotations", "save session with quality checks"                                                    | `fo-session-save`                       |
+| "ingest external specification", "vendor spec package into docs", "author spec skeleton"                                                                  | `fo-spec-ingest`                        |
+| "commit after request", "auto-commit changes", "step commit"                                                                                              | `fo-step-commit`                        |
+| "triage this issue", "categorize incoming bug report", "triage external pull request", "process feature request"                                          | `fo-triage`                             |
 
 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.
 

package/src/tests/markdown-table.test.ts

@@ -0,0 +1,107 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for alignMarkdownTable + parseMarkdownTable (RFC-1154):
+prettier-normal emission, separator dash-padding, escaped-pipe literals,
+idempotency, and a regression guard over forge emission surfaces.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial table-emitter tests + compact-separator regression guard.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { alignMarkdownTable, parseMarkdownTable } from "../utils/markdown-table.ts";
+
+test("aligns cells and pads separator with dashes to column width", () => {
+  const out = alignMarkdownTable(
+    ["Name", "Value"],
+    [
+      ["long-name-here", "x"],
+      ["a", "b"],
+    ],
+  );
+  expect(out).toBe(
+    [
+      "| Name           | Value |",
+      "| -------------- | ----- |",
+      "| long-name-here | x     |",
+      "| a              | b     |",
+    ].join("\n"),
+  );
+});
+
+test("minimum column width is 3 even for short cells", () => {
+  const out = alignMarkdownTable(["a", "b"], [["1", "2"]]);
+  expect(out).toBe("| a   | b   |\n| --- | --- |\n| 1   | 2   |");
+});
+
+test("escaped pipe inside a cell is a literal, not a delimiter", () => {
+  const out = alignMarkdownTable(["Pattern", "Meaning"], [["a \\| b", "or"]]);
+  const lines = out.split("\n");
+  expect(lines[0]).toBe("| Pattern | Meaning |");
+  expect(lines[1]).toBe("| ------- | ------- |");
+  expect(lines[2]).toBe("| a \\| b  | or      |");
+});
+
+test("rows shorter or longer than headers extend the column set", () => {
+  const out = alignMarkdownTable(["A"], [["x", "extra"]]);
+  expect(out.split("\n")[0]).toBe("| A   |       |");
+  expect(out.split("\n")[2]).toBe("| x   | extra |");
+});
+
+test("empty input emits empty string", () => {
+  expect(alignMarkdownTable([], [])).toBe("");
+});
+
+test("AC-5: re-aligning emitted output is byte-identical", () => {
+  const once = alignMarkdownTable(
+    ["Name", "Category", "Concerns"],
+    [
+      ["fo-idea", "fo", "classification"],
+      ["wg-mission", "wg", "lifecycle"],
+    ],
+  );
+  const parsed = parseMarkdownTable(once);
+  expect(parsed).not.toBeNull();
+  const twice = alignMarkdownTable(parsed!.headers, parsed!.rows);
+  expect(twice, "align(parse(emit)) must be byte-stable — check separator width math").toBe(once);
+});
+
+test("parseMarkdownTable returns null for non-table input", () => {
+  expect(parseMarkdownTable("just prose\nno table here")).toBeNull();
+  expect(parseMarkdownTable("| a |\nno separator")).toBeNull();
+});
+
+test("parseMarkdownTable splits on unescaped pipes only", () => {
+  const parsed = parseMarkdownTable("| a \\| b | c |\n| --- | --- |\n| 1 | 2 |");
+  expect(parsed).not.toBeNull();
+  expect(parsed!.headers).toEqual(["a \\| b", "c"]);
+});
+
+test("regression guard: no forge emitter emits a compact '| --- |' separator", () => {
+  const srcDir = join(import.meta.dirname, "..");
+  const offenders: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) {
+        if (entry === "tests" || entry === "__tests__") continue;
+        walk(full);
+        continue;
+      }
+      if (!entry.endsWith(".ts")) continue;
+      const content = readFileSync(full, "utf8");
+      // Flag compact separator literals — all tables must route through
+      // alignMarkdownTable. The aligner itself lives in utils/markdown-table.ts.
+      if (full.endsWith("markdown-table.ts")) continue;
+      if (/\| -{2,} \|/.test(content)) offenders.push(full);
+    }
+  };
+  walk(srcDir);
+  expect(
+    offenders,
+    "compact '| --- |' table literals found — route through alignMarkdownTable",
+  ).toEqual([]);
+});