@warpgogol/forge 5.3.4 → 6.2.0

package/os/compass/handlers/compass-docs-validate.ts

@@ -0,0 +1,361 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-1242: validate that the live root docs/*.xml corpus describes the repository as it exists — every path token, workspace id, and knowledge-graph link target must resolve to a real file, directory, or declared node.</purpose>
+<non-goals>
+  <item>Do not scan archived trees, vendored specs, sessions/metrics, or authored RFC/ADR/plan bodies — frozen history and forward-looking prose legitimately name paths that do not exist.</item>
+  <item>Do not validate markdown link targets — only the XML semantic layer is gated (markdown sweep is manual).</item>
+  <item>Do not mutate anything — this handler is read-only; pruning lives on compass.audit.validate --prune.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Tag-stack tokenizer over an XML dependency — small authored corpus; a balance check catches literal-tag breakage (COMPASS-DOC-00).</item>
+  <item>Link targets resolve to declared node ids OR file/dir conventions (DOC-03) — dangling-by-convention stays a warning, never an error.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-1242: review fixes — self-close detection strips quoted attr values first (a="foo/" no longer fakes a self-close), non-backticked path tokens get the same ellipsis strip, docs.* link slugs keep their basename prefix (docs.plans.plan-rfc-* resolves).</item>
+  <item>RFC-1242: created — scan docs/*.xml for unresolvable paths, workspace ids, and link targets (COMPASS-DOC-00..03).</item>
+  <item>RFC-1249: wire werkstatt.commands.validate into packages.check + retire CMD-OUTPUT debt</item>
+</CHANGE_SUMMARY>
+*/
+
+import { resolve } from "node:path";
+import { resolveIo } from "../../../src/utils/io.ts";
+import type { Diagnostic, WorkspaceIO } from "../../../src/types.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+const DOCS_GLOB = "*.xml";
+
+// Well-formedness: minimal tag-stack check. Skips comments, CDATA, PIs and
+// declarations; a literal `<name` inside prose opens a tag that never balances
+// → COMPASS-DOC-00. The corpus is authored XML without < in attribute values.
+function checkWellFormed(file: string, source: string): { line: number; message: string } | null {
+  const stack: Array<{ name: string; line: number }> = [];
+  let i = 0;
+  let line = 1;
+  const advanceLine = (chunk: string) => {
+    for (const c of chunk) if (c === "\n") line++;
+  };
+  while (i < source.length) {
+    const open = source.indexOf("<", i);
+    if (open === -1) break;
+    advanceLine(source.slice(i, open));
+    const rest = source.slice(open);
+    // comments / CDATA / PI / declarations
+    if (rest.startsWith("<!--")) {
+      const end = source.indexOf("-->", open + 4);
+      if (end === -1) return { line, message: "unterminated comment" };
+      advanceLine(source.slice(open, end + 3));
+      i = end + 3;
+      continue;
+    }
+    if (rest.startsWith("<![CDATA[")) {
+      const end = source.indexOf("]]>", open + 9);
+      if (end === -1) return { line, message: "unterminated CDATA" };
+      advanceLine(source.slice(open, end + 3));
+      i = end + 3;
+      continue;
+    }
+    if (rest.startsWith("<?")) {
+      const end = source.indexOf("?>", open + 2);
+      if (end === -1) return { line, message: "unterminated processing instruction" };
+      advanceLine(source.slice(open, end + 2));
+      i = end + 2;
+      continue;
+    }
+    if (rest.startsWith("<!")) {
+      const end = source.indexOf(">", open + 2);
+      if (end === -1) return { line, message: "unterminated declaration" };
+      advanceLine(source.slice(open, end + 1));
+      i = end + 1;
+      continue;
+    }
+    const tagMatch = /^<(\/?)([A-Za-z_][\w:.-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)?(\/?)>/.exec(rest);
+    if (!tagMatch) {
+      // `<` not starting a tag — literal text, tolerated.
+      advanceLine(source.slice(open, open + 1));
+      i = open + 1;
+      continue;
+    }
+    const [, closing, name, attrs = "", selfClose] = tagMatch;
+    advanceLine(tagMatch[0]);
+    i = open + tagMatch[0].length;
+    if (closing === "/") {
+      const top = stack.pop();
+      if (!top || top.name !== name) {
+        return {
+          line,
+          message: `mismatched closing tag </${name}>${top ? ` — expected </${top.name}> opened at line ${top.line}` : " — no open tag"}`,
+        };
+      }
+      continue;
+    }
+    const attrsUnquoted = attrs.replace(/"[^"]*"|'[^']*'/g, "");
+    if (selfClose !== "/" && !attrsUnquoted.trimEnd().endsWith("/")) {
+      stack.push({ name, line });
+    }
+  }
+  if (stack.length > 0) {
+    const top = stack[stack.length - 1]!;
+    return { line: top.line, message: `unclosed tag <${top.name}>` };
+  }
+  return null;
+}
+
+interface ExtractedRefs {
+  paths: Array<{ value: string; line: number }>;
+  workspaceIds: Array<{ id: string; line: number }>;
+  linkTargets: Array<{ target: string; line: number }>;
+}
+
+function extractRefs(source: string): ExtractedRefs {
+  const refs: ExtractedRefs = { paths: [], workspaceIds: [], linkTargets: [] };
+  const lineOf = (index: number) => source.slice(0, index).split("\n").length;
+  for (const m of source.matchAll(/<path>([\s\S]*?)<\/path>/g)) {
+    refs.paths.push({ value: m[1] ?? "", line: lineOf(m.index) });
+  }
+  for (const m of source.matchAll(/<workspace\s[^>]*?id="([^"]+)"/g)) {
+    refs.workspaceIds.push({ id: m[1]!, line: lineOf(m.index) });
+  }
+  for (const m of source.matchAll(/<node\s[^>]*>/g)) {
+    // DOC-02 only applies to ids that claim a workspace: <workspace> entries
+    // and workspace-typed nodes. Layer/symbolic ids (apps.rules,
+    // packages.rules, changelog.*) name semantic handles, not directories.
+    const id = /\bid="([^"]+)"/.exec(m[0])?.[1];
+    const type = /\btype="([^"]+)"/.exec(m[0])?.[1];
+    if (id && type === "workspace") {
+      refs.workspaceIds.push({ id, line: lineOf(m.index) });
+    }
+  }
+  for (const m of source.matchAll(/<link\s[^>]*?target="([^"]+)"/g)) {
+    refs.linkTargets.push({ target: m[1]!, line: lineOf(m.index) });
+  }
+  return refs;
+}
+
+// Normalize a <path> payload into checkable path tokens. Each backticked
+// fragment is one candidate — splitting on commas inside would shred brace
+// expansions (`{a,b}`) and ellipsis ranges (`docs/x/…` … `leaf`). A bare tail
+// fragment after an `…` outside the backticks resolves under the previous
+// fragment's directory (range shorthand for two versions of the same dir).
+function pathTokens(raw: string): string[] {
+  const tokens: string[] = [];
+  const fragments = [...raw.matchAll(/`([^`]*)`/g)].map((m) => m[1]!.trim());
+  if (fragments.length === 0) {
+    return raw
+      .split(/[\s,]+/)
+      .map((t) =>
+        t
+          .trim()
+          .replace(/(?:…|\.\.\.).*$/, "")
+          .replace(/\/+$/, ""),
+      )
+      .filter((t) => t.length > 0 && !t.startsWith("<") && t !== "…" && t !== "+");
+  }
+  const joinsWithEllipsis = raw.replace(/`[^`]*`/g, "").includes("…");
+  let parentDir: string | null = null;
+  for (const frag of fragments) {
+    const cleaned = frag.replace(/(?:…|\.\.\.).*$/, "").replace(/\/+$/, "");
+    if (!cleaned || cleaned === "+") continue;
+    if (joinsWithEllipsis && !cleaned.includes("/") && parentDir) {
+      tokens.push(`${parentDir}/${cleaned}`);
+      continue;
+    }
+    tokens.push(cleaned);
+    parentDir = cleaned.split("/").slice(0, -1).join("/") || parentDir;
+  }
+  return tokens;
+}
+
+/** Directory prefix that must exist for a path token (glob tails trimmed). */
+function pathCheckTarget(token: string): string {
+  const globIdx = token.search(/[*{[]/);
+  if (globIdx === -1) return token;
+  const prefix = token.slice(0, globIdx);
+  return prefix.replace(/\/[^/]*$/, "") || ".";
+}
+
+/** Resolve a workspace-style id to the package/service directory it names. */
+function workspaceIdTarget(id: string): string | null {
+  const pkg = /^pkg-([a-z0-9-]+)$/.exec(id);
+  if (pkg) return `packages/${pkg[1]}`;
+  const svc = /^svc-([a-z0-9-]+)$/.exec(id);
+  if (svc) return `services/${svc[1]}`;
+  const app = /^app-([a-z0-9-]+)$/.exec(id);
+  if (app) return `apps/${app[1]}`;
+  const dotted = /^(packages|apps|services)\.([a-z0-9-]+)/.exec(id);
+  if (dotted) return `${dotted[1]}/${dotted[2]}`;
+  return null;
+}
+
+/**
+ * DOC-03 resolution for dotted link targets: declared node id (checked by the
+ * caller) or a file/dir convention — docs.<dir>.<slug> → docs/<dir>/<slug>*,
+ * packages./apps./services. → workspace dir, spec.<x> → docs/specs/<x>*,
+ * dna-N → docs/architecture-dna.md, dotted command names → command manifest.
+ */
+async function linkTargetResolves(
+  target: string,
+  declaredIds: Set<string>,
+  io: WorkspaceIO,
+  docsDir: string,
+  commandNames: Set<string>,
+): Promise<"node" | "file" | "none"> {
+  if (declaredIds.has(target)) return "node";
+  if (commandNames.has(target)) return "file";
+  if (/^dna-\d+$/.test(target)) {
+    return (await io.exists(resolve(docsDir, "architecture-dna.md"))) ? "file" : "none";
+  }
+  const docsId = /^docs\.([a-z-]+)\.(.+)$/.exec(target);
+  if (docsId) {
+    const [, dir, slug] = docsId;
+    const hits = await io.glob(`${dir}/**/*${slug}*.md`, { cwd: docsDir }).catch(() => []);
+    if (hits.length > 0) return "file";
+    // generic fallback: any file whose basename contains the slug under docs/
+    const broad = await io.glob(`**/*${slug}*`, { cwd: docsDir }).catch(() => []);
+    if (broad.length > 0) return "file";
+    return "none";
+  }
+  const ws = workspaceIdTarget(target);
+  if (ws) return (await io.exists(ws)) ? "file" : "none";
+  const spec = /^spec\.([a-z0-9-]+)$/.exec(target);
+  if (spec) {
+    const hits = await io.glob(`specs/${spec[1]}*/**`, { cwd: docsDir }).catch(() => []);
+    const dirs = await io.glob(`specs/${spec[1]}*`, { cwd: docsDir }).catch(() => []);
+    return hits.length + dirs.length > 0 ? "file" : "none";
+  }
+  return "none";
+}
+
+export async function runCompassDocsValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<
+  ForgeCommandResult<{
+    command: "compass.docs.validate";
+    status: "pass" | "fail";
+    scanned: { xmlFiles: number; pathsChecked: number; idsChecked: number };
+    diagnostics: Diagnostic[];
+  }>
+> {
+  const io = resolveIo(context.io);
+  const docsDir = resolve(context.workspaceRoot, "docs");
+  const diagnostics: Diagnostic[] = [];
+  let pathsChecked = 0;
+  let idsChecked = 0;
+
+  // Command-name convention for DOC-03: dotted targets like ratgeber.hub.validate
+  // resolve when the command registry lists them.
+  const commandNames = new Set<string>();
+  const manifestPath = resolve(docsDir, "command-manifest.generated.yaml");
+  if (await io.exists(manifestPath)) {
+    const manifest = await io.readFile(manifestPath);
+    for (const m of manifest.matchAll(/^\s*- name: ([\w.-]+)\s*$/gm)) {
+      commandNames.add(m[1]!);
+    }
+  }
+
+  const xmlFiles = (await io.glob(DOCS_GLOB, { cwd: docsDir })).sort();
+  const declaredNodeIds = new Set<string>();
+
+  // Pass 1: collect declared node ids so link targets can resolve across files.
+  const sources = new Map<string, string>();
+  for (const rel of xmlFiles) {
+    const abs = resolve(docsDir, rel);
+    const source = await io.readFile(abs);
+    sources.set(rel, source);
+    for (const m of source.matchAll(/<node\s[^>]*?id="([^"]+)"/g)) {
+      declaredNodeIds.add(m[1]!);
+    }
+  }
+
+  for (const rel of xmlFiles) {
+    const file = `docs/${rel}`;
+    const source = sources.get(rel)!;
+
+    const malformed = checkWellFormed(file, source);
+    if (malformed) {
+      diagnostics.push({
+        ruleId: "COMPASS-DOC-00",
+        severity: "error",
+        file,
+        line: malformed.line,
+        message: `file is not well-formed XML: ${malformed.message}`,
+      });
+      continue; // refs from a broken file are noise
+    }
+
+    const refs = extractRefs(source);
+
+    for (const { value, line } of refs.paths) {
+      for (const token of pathTokens(value)) {
+        pathsChecked++;
+        const target = pathCheckTarget(token);
+        if (!(await io.exists(resolve(context.workspaceRoot, target)))) {
+          diagnostics.push({
+            ruleId: "COMPASS-DOC-01",
+            severity: "error",
+            file,
+            line,
+            message: `<path> references '${token}' — does not exist under the workspace root`,
+            fixHint: "Repoint to the live path or remove the stale reference",
+          });
+        }
+      }
+    }
+
+    for (const { id, line } of refs.workspaceIds) {
+      const target = workspaceIdTarget(id);
+      if (!target) continue;
+      idsChecked++;
+      if (!(await io.exists(resolve(context.workspaceRoot, target)))) {
+        diagnostics.push({
+          ruleId: "COMPASS-DOC-02",
+          severity: "error",
+          file,
+          line,
+          message: `id '${id}' names workspace path '${target}' — does not exist`,
+          fixHint: "Repoint to the live package or remove the stale entry",
+        });
+      }
+    }
+
+    for (const { target, line } of refs.linkTargets) {
+      idsChecked++;
+      const resolved = await linkTargetResolves(target, declaredNodeIds, io, docsDir, commandNames);
+      if (resolved === "none") {
+        diagnostics.push({
+          ruleId: "COMPASS-DOC-03",
+          severity: "warning",
+          file,
+          line,
+          message: `link target '${target}' resolves to no declared node and no file`,
+        });
+      }
+    }
+  }
+
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  for (const d of diagnostics) {
+    context.logger[d.severity === "error" ? "error" : "warn"](
+      `[compass.docs.validate] ${d.ruleId}: ${d.file}${d.line ? `:${d.line}` : ""}: ${d.message}`,
+    );
+  }
+
+  return {
+    data: {
+      command: "compass.docs.validate",
+      status: errors.length === 0 ? "pass" : "fail",
+      scanned: { xmlFiles: xmlFiles.length, pathsChecked, idsChecked },
+      diagnostics,
+    },
+    exitCode: errors.length > 0 ? 1 : 0,
+    summary:
+      errors.length === 0
+        ? `[compass.docs.validate] OK (${xmlFiles.length} files, ${pathsChecked} paths, ${idsChecked} ids)`
+        : `[compass.docs.validate] ${errors.length} error(s)`,
+  };
+}

package/os/compass/handlers/summary-record.ts

@@ -15,24 +15,18 @@ items to CHANGE_SUMMARY blocks per RFC-1095. Collapses the 5-item window into
   <item>Item text is sanitized on record — literal Compass tags would corrupt history parsing.</item>
 </KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>RFC-1097: steps 1-4 — compass.migrate codemod
-
-Add the v1 to v2 Compass header codemod: migrateFile pure transform (collapse, strip, seed, reorder, purpose-flag actions), migrateWorkspace walker, runCompassMigrate handler with dirty-tree refusal and --force/--files/--dry-run flags, module registration, and 15 unit tests.</item>
-  <item>RFC-1097: sweep — packages/forge + services clean
-
-Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PURPOSE-02), headers on mission/index + gen-upstreams, sanitizeItemText in summary.record (literal Compass tags corrupted history), excludedPaths for wrangler types, test-fixtures testPattern. forge+services now 0 diagnostics under --mode error.</item>
-  <item>RFC-1097: sweep — engine package clean
-
-Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. engine package now 0 diagnostics.</item>
   <item>RFC-1097: AC-4 banned literal in os/compass handlers
 
 compass-migrate-handler hint used a consumer-specific run command — switched to generic 'pnpm exec forge run' convention. Reworded recorded CHANGE_SUMMARY items in 3 handlers to drop the consumer-specific literal. compass-policy AC-4 test green (65/65).</item>
   <item>RFC-1220: step 2 — fail-closed guards in history paths</item>
-  <history>RFC-1095</history>
+  <item>RFC-1233: stripGitTrailers at the record point + sanitizeItemText star-slash guard — commit-message trailers (Token: value / Token #value, plus markdown-link attribution lines like "Generated with [X](url)") no longer pollute injected items.</item>
+  <item>Session-retro 2026-10-08: id-in-diff dedup — auto-inject skips when the worktree diff already carries a same-ID item (HEAD-vs-worktree via git show HEAD:path), closing the descriptive+generic duplicate class seen on RFC-1237.</item>
+  <item>RFC-1249: wire werkstatt.commands.validate into packages.check + retire CMD-OUTPUT debt</item>
+  <history>CONTRACT-02, PURPOSE-02, RFC-1095, RFC-1097</history>
 </CHANGE_SUMMARY>
 */
 
-import { existsSync } from "../../../src/utils/sync-fs.ts";
+import { execFile, existsSync } from "../../../src/utils/sync-fs.ts";
 import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
 
 import { resolve, relative } from "node:path";
@@ -69,7 +63,7 @@ export interface SummaryRecordInput {
   workpiece?: string;
 }
 
-export type SummaryRecordSkipReason = "no-block" | "duplicate" | "unparseable";
+export type SummaryRecordSkipReason = "no-block" | "duplicate" | "unparseable" | "id-in-diff";
 
 export interface SummaryRecordResult {
   command: "compass.summary.record";
@@ -167,6 +161,41 @@ export function stripConventionalPrefix(subject: string): string {
   return subject.replace(CONVENTIONAL_PREFIX_RE, "").trim();
 }
 
+// RFC-1233: git-trailer tail block — strict `Token: value` / `Token #value`
+// lines (interpret-trailers shape, empty value allowed), plus lines ending
+// in a markdown link (the observed "Generated with [X](url)" attribution
+// boilerplate has no separator). A link-shaped line is admitted only when
+// the block also contains at least one strict trailer line — a lone link
+// tail is prose.
+const TRAILER_LINE_RE = /^[A-Za-z0-9-]+(:| #)\s*.*$/;
+const MARKDOWN_LINK_TAIL_RE = /^.*\[[^\]]*\]\([^)]+\)\s*$/;
+
+/**
+ * Remove a trailing git-trailer block: the contiguous tail of strict
+ * trailer lines and admitted markdown-link lines. A blank line ends the
+ * tail paragraph. Returns the message without the block; when the tail
+ * holds no strict trailer line the message is returned unchanged.
+ */
+export function stripGitTrailers(message: string): string {
+  const lines = message.trimEnd().split("\n");
+  let start = lines.length;
+  let sawStrict = false;
+  while (start > 0) {
+    const line = lines[start - 1]!.trim();
+    if (line === "") break;
+    if (TRAILER_LINE_RE.test(line)) {
+      sawStrict = true;
+      start--;
+    } else if (MARKDOWN_LINK_TAIL_RE.test(line)) {
+      start--;
+    } else {
+      break;
+    }
+  }
+  if (!sawStrict || start === lines.length) return message;
+  return lines.slice(0, start).join("\n").trimEnd();
+}
+
 // Literal Compass block tags inside an item corrupt block parsing — a commit
 // message saying "collapsed into history" would be matched by HISTORY_RE and
 // produce phantom non-ID tokens (CS-07). Strip the angle brackets on record.
@@ -174,7 +203,14 @@ const COMPASS_TAG_LITERAL_RE =
   /<\/?(?:CHANGE_SUMMARY|MODULE_CONTRACT|KEY_DECISIONS|history|item|purpose|non-goals)>/g;
 
 export function sanitizeItemText(text: string): string {
-  return text.replace(COMPASS_TAG_LITERAL_RE, (tag) => tag.replace(/[<>]/g, ""));
+  return (
+    text
+      .replace(COMPASS_TAG_LITERAL_RE, (tag) => tag.replace(/[<>]/g, ""))
+      // RFC-1233: a literal star-slash sequence would terminate the
+      // surrounding block comment when the item lands in /* ... */ headers.
+      // ∕ (U+2215) is visually near-identical, idempotent, and never re-forms.
+      .replace(/\*\//g, "*\u2215")
+  );
 }
 
 export function isValidGovernanceId(id: string, policy: CompassPolicy): boolean {
@@ -190,6 +226,8 @@ interface RecordOutcome {
 /**
  * Append `ID: text` to one file's CHANGE_SUMMARY and collapse the window.
  * Returns the outcome; writes the file only when mutated and not dry-run.
+ * `headSource` is the file's content at HEAD (when resolvable) — it enables
+ * the id-in-diff dedup; pass undefined outside git workspaces.
  */
 export async function recordSummaryItem(
   absPath: string,
@@ -198,6 +236,7 @@ export async function recordSummaryItem(
   text: string,
   dryRun: boolean,
   policy: CompassPolicy,
+  headSource?: string,
 ): Promise<RecordOutcome> {
   const source = await io.readFile(absPath);
   const blockMatch = source.match(CHANGE_SUMMARY_BLOCK_RE);
@@ -228,6 +267,22 @@ export async function recordSummaryItem(
     return { recorded: false, collapsed: false, skipReason: "duplicate" };
   }
 
+  // A same-ID item already in the worktree but absent from HEAD means the
+  // pending change already carries a hand-authored record for this governance
+  // ID — the auto-injected subject-derived item would duplicate it at lower
+  // specificity (observed 2026-10-08: 27 files carried descriptive + generic
+  // RFC-1237 items). HEAD-resident same-ID items do NOT suppress: consecutive
+  // commits under one RFC legitimately stack step items.
+  if (headSource !== undefined) {
+    const headBlock = headSource.match(CHANGE_SUMMARY_BLOCK_RE);
+    const headItems = headBlock ? parseChangeSummary(headBlock[0]).items : [];
+    const idInWorktree = items.some((item) => leadingGovernanceId(item, policy) === id);
+    const idInHead = headItems.some((item) => leadingGovernanceId(item, policy) === id);
+    if (idInWorktree && !idInHead) {
+      return { recorded: false, collapsed: false, skipReason: "id-in-diff" };
+    }
+  }
+
   const nextItems = [...items, newItem];
   const collapsedIds: string[] = [];
   while (nextItems.length > CHANGE_SUMMARY_WINDOW) {
@@ -246,6 +301,27 @@ export async function recordSummaryItem(
   return { recorded: true, collapsed };
 }
 
+function execGit(cwd: string, args: string[]): Promise<string | null> {
+  return new Promise((resolve) => {
+    execFile("git", args, { cwd, timeout: 5000 }, (err, stdout) => {
+      resolve(err ? null : stdout);
+    });
+  });
+}
+
+/**
+ * Read `path`'s content at HEAD — the baseline for the id-in-diff dedup.
+ * Returns undefined when the file is untracked or the workspace is not a git
+ * repo (the dedup then falls back to exact-text matching only).
+ */
+async function readHeadSource(gitTop: string | null, absPath: string): Promise<string | undefined> {
+  if (!gitTop) return undefined;
+  const rel = relative(gitTop, absPath).replace(/\\/g, "/");
+  if (rel === "" || rel.startsWith("..")) return undefined;
+  const source = await execGit(gitTop, ["show", `HEAD:${rel}`]);
+  return source ?? undefined;
+}
+
 function riskReminderNeeded(relPath: string, source: string, policy: CompassPolicy): boolean {
   const segments = relPath.split("/").filter(Boolean);
   const workspaceRel = getWorkspaceRelativeSegments(segments, policy).join("/");
@@ -278,7 +354,10 @@ export async function runCompassSummaryRecord(
       : [];
 
   const rawText = input.flags["text"];
-  const text = typeof rawText === "string" && rawText.trim().length > 0 ? rawText.trim() : id;
+  // RFC-1233: strip the git-trailer block at the single injection point —
+  // ecosystem.commit and mission.git.commit both pipe the raw message here.
+  const stripped = typeof rawText === "string" ? stripGitTrailers(rawText).trim() : "";
+  const text = stripped.length > 0 ? stripped : id;
 
   const result: SummaryRecordResult = {
     command: "compass.summary.record",
@@ -289,6 +368,9 @@ export async function runCompassSummaryRecord(
     keyDecisionsReminders: [],
   };
 
+  const gitTopRaw = await execGit(baseRoot, ["rev-parse", "--show-toplevel"]);
+  const gitTop = gitTopRaw?.trim() || null;
+
   for (const file of files) {
     const absPath = resolve(baseRoot, file);
     const relPath = relative(baseRoot, absPath).replace(/\\/g, "/");
@@ -298,7 +380,16 @@ export async function runCompassSummaryRecord(
       continue;
     }
     try {
-      const outcome = await recordSummaryItem(absPath, relPath, id, text, context.dryRun, policy);
+      const headSource = await readHeadSource(gitTop, absPath);
+      const outcome = await recordSummaryItem(
+        absPath,
+        relPath,
+        id,
+        text,
+        context.dryRun,
+        policy,
+        headSource,
+      );
       if (outcome.skipReason) {
         result.skipped.push({ file, reason: outcome.skipReason });
         continue;

package/os/compass/handlers/tests/compass-audit-record.test.ts

@@ -16,6 +16,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { parse as yamlParse } from "yaml";
 import { runCompassAuditRecord } from "../compass-audit-handler.ts";
+import { ambientIo } from "../../../../src/utils/io.ts";
 import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../../src/types.ts";
 
 const execFileAsync = promisify(execFile);
@@ -42,7 +43,7 @@ function makeContext(workspaceRoot: string): ForgeRuntimeContext {
     logger: logger as never,
     dryRun: false,
     outputFormat: "json",
-    io: {} as never,
+    io: ambientIo,
     actualState: undefined as never,
     fileIntents: [],
   } as unknown as ForgeRuntimeContext;