@moretea-labs/forge 1.5.0-rc.1

package/assets/templates/helpers/architecture-event.ts

@@ -0,0 +1,822 @@
+#!/usr/bin/env bun
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+
+type Args = {
+  command: string;
+  options: Record<string, string>;
+  flags: Set<string>;
+};
+
+function usage(): never {
+  console.error(
+    [
+      "Usage:",
+      "  scripts/architecture-event.ts json-get --key <key> [--json <json>]",
+      "  scripts/architecture-event.ts safe-token --value <value>",
+      "  scripts/architecture-event.ts derive-scope --block <functional-block> [--format lines|json]",
+      "  scripts/architecture-event.ts repo-path --repo <repo> --path <path>",
+      "  scripts/architecture-event.ts event-json --ts <ts> --file-path <path> ... [--pretty]",
+      "  scripts/architecture-event.ts upsert-request --request-file <path> --event-json <json>",
+      "  scripts/architecture-event.ts upsert-from-request --source-request <path> --request-file <path>",
+      "  scripts/architecture-event.ts reindex-requests --index-file <path> --requests-dir <dir> [--check]",
+      "  scripts/architecture-event.ts request-info --request-file <path>",
+      "  scripts/architecture-event.ts sync-context-map --context-map <path> --block <path> ...",
+      "  scripts/architecture-event.ts sync-contract-files --functional-block <path> --contract-agents <path> --contract-claude <path> ...",
+    ].join("\n")
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    command: argv[0] || "",
+    options: {},
+    flags: new Set(),
+  };
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") usage();
+    if (!arg.startsWith("--")) {
+      console.error(`Unknown argument: ${arg}`);
+      usage();
+    }
+
+    const key = arg.slice(2).replace(/-([a-z])/g, (_, char: string) => char.toUpperCase());
+    if (key === "pretty" || key === "check") {
+      args.flags.add(key);
+      continue;
+    }
+
+    const value = argv[++index];
+    if (value === undefined) {
+      console.error(`Missing value for ${arg}`);
+      usage();
+    }
+    args.options[key] = value;
+  }
+
+  if (
+    ![
+      "json-get",
+      "safe-token",
+      "derive-scope",
+      "repo-path",
+      "event-json",
+      "upsert-request",
+      "upsert-from-request",
+      "reindex-requests",
+      "request-info",
+      "sync-context-map",
+      "sync-contract-files",
+    ].includes(args.command)
+  ) {
+    usage();
+  }
+
+  return args;
+}
+
+function requireOption(args: Args, key: string): string {
+  const value = args.options[key];
+  if (value === undefined || value === "") usage();
+  return value;
+}
+
+function readStdin(): string {
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function print(value: string): never {
+  process.stdout.write(value);
+  process.exit(0);
+}
+
+function fail(message?: string): never {
+  if (message) console.error(message);
+  process.exit(1);
+}
+
+function safeToken(value: string): string {
+  const token = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .replace(/-+$/, "")
+    .replace(/-{2,}/g, "-");
+  return token || "root";
+}
+
+function jsonGet(raw: string, key: string): string {
+  if (!raw) fail();
+  try {
+    const value = JSON.parse(raw)[key];
+    if (value === undefined || value === null) fail();
+    const output = typeof value === "object" ? JSON.stringify(value) : String(value);
+    if (output.length === 0) fail();
+    return output;
+  } catch {
+    fail();
+  }
+}
+
+function normalizeRepoPath(value: string, repoInput: string): string {
+  let next = value.trim().replace(/^file:\/\//, "").replaceAll("\\", "/");
+  const repo = resolve(repoInput).replaceAll("\\", "/");
+
+  if (next.startsWith(`${repo}/`)) {
+    next = next.slice(repo.length + 1);
+  } else if (next.startsWith("/")) {
+    throw new Error(`absolute path is outside repo: ${value}`);
+  }
+
+  next = next.replace(/^\.\//, "");
+  if (
+    next === "" ||
+    next === "." ||
+    next === ".." ||
+    next.startsWith("../") ||
+    next.includes("/../") ||
+    next.includes("\n") ||
+    next.includes("\r")
+  ) {
+    throw new Error(`unsafe repo path: ${value}`);
+  }
+  return next;
+}
+
+function deriveScope(block: string) {
+  const blockSlug = safeToken(block);
+  const parts = block.split("/").filter(Boolean);
+  let domainSlug = blockSlug;
+  let capabilitySlug = "_domain";
+
+  if (parts.length >= 2) {
+    domainSlug = safeToken(`${parts[0]}-${parts[1]}`);
+  }
+  if (parts.length > 2) {
+    capabilitySlug = safeToken(parts[parts.length - 1]);
+  }
+
+  return {
+    architecture_domain: domainSlug,
+    architecture_capability: capabilitySlug,
+    architecture_module: `docs/architecture/modules/${domainSlug}/${capabilitySlug}.md`,
+    workstream_dir: `tasks/workstreams/${domainSlug}/${capabilitySlug}`,
+  };
+}
+
+function parseBoolean(value: string): boolean {
+  if (["true", "1", "yes"].includes(value.toLowerCase())) return true;
+  if (["false", "0", "no"].includes(value.toLowerCase())) return false;
+  throw new Error(`expected boolean value, got: ${value}`);
+}
+
+function eventJson(args: Args): string {
+  const event = {
+    ts: requireOption(args, "ts"),
+    file_path: requireOption(args, "filePath"),
+    severity: requireOption(args, "severity"),
+    functional_block: requireOption(args, "functionalBlock"),
+    capability_id: requireOption(args, "capabilityId"),
+    matched_prefix: requireOption(args, "matchedPrefix"),
+    architecture_domain: requireOption(args, "architectureDomain"),
+    architecture_capability: requireOption(args, "architectureCapability"),
+    architecture_module: requireOption(args, "architectureModule"),
+    workstream_dir: requireOption(args, "workstreamDir"),
+    contract_agents: args.options.contractAgents ?? "",
+    contract_claude: args.options.contractClaude ?? "",
+    change_type: requireOption(args, "changeType"),
+    request_file: requireOption(args, "requestFile"),
+    spawn_recommended: parseBoolean(requireOption(args, "spawnRecommended")),
+    contract_sync_required: parseBoolean(requireOption(args, "contractSyncRequired")),
+  };
+  return JSON.stringify(event, null, args.flags.has("pretty") ? 2 : 0);
+}
+
+type ArchitectureEvent = {
+  ts?: string;
+  file_path?: string;
+  severity?: string;
+  functional_block?: string;
+  capability_id?: string;
+  matched_prefix?: string;
+  architecture_domain?: string;
+  architecture_capability?: string;
+  architecture_module?: string;
+  workstream_dir?: string;
+  contract_agents?: string;
+  contract_claude?: string;
+  change_type?: string;
+  request_file?: string;
+  spawn_recommended?: boolean;
+  contract_sync_required?: boolean;
+};
+
+function stripCode(value: string): string {
+  return value.trim().replace(/^`/, "").replace(/`$/, "");
+}
+
+function readMetadata(file: string): Record<string, string> {
+  const metadata: Record<string, string> = {};
+  if (!existsSync(file)) return metadata;
+  for (const line of readFileSync(file, "utf-8").split(/\r?\n/)) {
+    const match = line.match(/^> \*\*(.+?)\*\*:\s*(.*)$/);
+    if (!match) continue;
+    metadata[match[1]] = stripCode(match[2]);
+  }
+  return metadata;
+}
+
+function extractEventFields(file: string): ArchitectureEvent {
+  if (!existsSync(file)) return {};
+  const source = readFileSync(file, "utf-8");
+  const match = source.match(/## Event Fields\s*```json\s*([\s\S]*?)\s*```/);
+  if (match) {
+    try {
+      return JSON.parse(match[1]);
+    } catch {
+      // Fall through to metadata synthesis for older or manually edited files.
+    }
+  }
+  const metadata = readMetadata(file);
+  return {
+    ts: metadata.Detected || metadata.Updated || "",
+    file_path: metadata.File || "",
+    severity: metadata.Severity || "medium",
+    functional_block: metadata["Functional Block"] || "root",
+    capability_id: metadata["Capability ID"] || "root",
+    matched_prefix: metadata["Matched Prefix"] || metadata["Functional Block"] || "root",
+    architecture_domain: metadata["Architecture Domain"] || "root",
+    architecture_capability: metadata["Architecture Capability"] || "_root",
+    architecture_module: metadata["Architecture Module"] || "docs/architecture/index.md",
+    workstream_dir: metadata["Workstream Directory"] || "tasks/workstreams/root/_root",
+    contract_agents: metadata["Contract Files"]?.split(",")[0]?.trim().replace(/^`|`$/g, "") || "",
+    contract_claude: metadata["Contract Files"]?.split(",")[1]?.trim().replace(/^`|`$/g, "") || "",
+    change_type: metadata["Change Type"] || "unknown",
+    request_file: "",
+    spawn_recommended: (metadata["Spawn Recommended"] || "false") === "true",
+    contract_sync_required: (metadata["Contract Sync Required"] || "false") === "true",
+  };
+}
+
+function severityRank(severity: string): number {
+  switch (severity.toLowerCase()) {
+    case "critical":
+      return 4;
+    case "high":
+      return 3;
+    case "medium":
+      return 2;
+    case "low":
+      return 1;
+    default:
+      return 0;
+  }
+}
+
+function maxSeverity(values: string[]): string {
+  return values.sort((a, b) => severityRank(b) - severityRank(a))[0] || "unknown";
+}
+
+function requestStatus(file: string): string {
+  return readMetadata(file).Status || "Pending";
+}
+
+function isPendingRequest(file: string): boolean {
+  return requestStatus(file).toLowerCase() === "pending";
+}
+
+function requestEventsFromSource(file: string): ArchitectureEvent[] {
+  if (!existsSync(file)) return [];
+  const source = readFileSync(file, "utf-8");
+  const events: ArchitectureEvent[] = [];
+  const tableMatch = source.match(/## Touched Files\s*\n([\s\S]*?)(?:\n## |\n?$)/);
+  if (tableMatch) {
+    for (const line of tableMatch[1].split(/\r?\n/)) {
+      const cells = line
+        .split("|")
+        .map((cell) => cell.trim())
+        .filter(Boolean);
+      if (cells.length < 4 || cells[0] === "Last Event" || cells[0].startsWith("---")) continue;
+      events.push({
+        ts: cells[0],
+        severity: cells[1],
+        change_type: cells[2],
+        file_path: stripCode(cells[3]),
+      });
+    }
+  }
+  const latest = extractEventFields(file);
+  if (latest.file_path) events.push(latest);
+  return dedupeEvents(events);
+}
+
+function dedupeEvents(events: ArchitectureEvent[]): ArchitectureEvent[] {
+  const byFile = new Map<string, ArchitectureEvent>();
+  for (const event of events) {
+    const key = event.file_path || "(unknown)";
+    const previous = byFile.get(key);
+    if (!previous || String(previous.ts || "") <= String(event.ts || "")) {
+      byFile.set(key, event);
+    }
+  }
+  return Array.from(byFile.values()).sort((a, b) => {
+    const byTs = String(b.ts || "").localeCompare(String(a.ts || ""));
+    if (byTs !== 0) return byTs;
+    return String(a.file_path || "").localeCompare(String(b.file_path || ""));
+  });
+}
+
+function normalizeEvent(event: ArchitectureEvent, requestFile: string): ArchitectureEvent {
+  return {
+    ts: event.ts || new Date().toISOString(),
+    file_path: event.file_path || "unknown",
+    severity: event.severity || "medium",
+    functional_block: event.functional_block || "root",
+    capability_id: event.capability_id || "root",
+    matched_prefix: event.matched_prefix || event.functional_block || "root",
+    architecture_domain: event.architecture_domain || "root",
+    architecture_capability: event.architecture_capability || "_root",
+    architecture_module: event.architecture_module || "docs/architecture/index.md",
+    workstream_dir: event.workstream_dir || "tasks/workstreams/root/_root",
+    contract_agents: event.contract_agents || "",
+    contract_claude: event.contract_claude || "",
+    change_type: event.change_type || "unknown",
+    request_file: requestFile,
+    spawn_recommended: Boolean(event.spawn_recommended),
+    contract_sync_required: Boolean(event.contract_sync_required),
+  };
+}
+
+function renderRequiredFollowUp(event: ArchitectureEvent): string {
+  const functionalBlock = event.functional_block || "root";
+  const requestFile = event.request_file || "docs/architecture/requests/unknown.md";
+  return [
+    "## Required Follow-up",
+    "",
+    "- Read root `AGENTS.md` / `CLAUDE.md`.",
+    "- If functional block is not `root`, read its local `AGENTS.md` / `CLAUDE.md`.",
+    "- Decide whether this change affects module boundaries, entrypoints, dependency rules, runtime paths, or verification commands.",
+    "- For substantial changes, write a snapshot under `docs/architecture/snapshots/`.",
+    "- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.",
+    "- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.",
+    "- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.",
+    `- If this starts or advances durable execution, run \`scripts/workstream-sync.sh ensure --block "${functionalBlock}" --request "${requestFile}"\`.`,
+    "- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links to the latest artifacts.",
+  ].join("\n");
+}
+
+function renderRequestCard(event: ArchitectureEvent, events: ArchitectureEvent[], existingMetadata: Record<string, string>): string {
+  const firstDetected =
+    existingMetadata.Detected ||
+    events
+      .map((entry) => entry.ts || "")
+      .filter(Boolean)
+      .sort()[0] ||
+    event.ts ||
+    "unknown";
+  const latest = event;
+  const severity = maxSeverity(events.map((entry) => entry.severity || "unknown"));
+  const titleToken = event.capability_id || event.functional_block || "root";
+  const touchedRows = events
+    .map((entry) => {
+      return `| ${entry.ts || "unknown"} | ${entry.severity || "unknown"} | ${entry.change_type || "unknown"} | \`${entry.file_path || "unknown"}\` |`;
+    })
+    .join("\n");
+
+  const latestEvent = normalizeEvent({ ...event, ...latest, severity }, event.request_file || "");
+
+  return [
+    `# Architecture Queue Card: ${titleToken}`,
+    "",
+    "> **Status**: Pending",
+    `> **Detected**: ${firstDetected}`,
+    `> **Updated**: ${latestEvent.ts}`,
+    `> **Severity**: ${severity}`,
+    `> **Change Type**: ${latestEvent.change_type}`,
+    `> **File**: \`${latestEvent.file_path}\``,
+    `> **Functional Block**: \`${event.functional_block}\``,
+    `> **Capability ID**: \`${event.capability_id}\``,
+    `> **Matched Prefix**: \`${event.matched_prefix}\``,
+    `> **Architecture Domain**: \`${event.architecture_domain}\``,
+    `> **Architecture Capability**: \`${event.architecture_capability}\``,
+    `> **Architecture Module**: \`${event.architecture_module}\``,
+    `> **Workstream Directory**: \`${event.workstream_dir}\``,
+    `> **Contract Files**: \`${event.contract_agents || "none"}\`, \`${event.contract_claude || "none"}\``,
+    `> **Contract Sync Required**: ${Boolean(event.contract_sync_required)}`,
+    `> **Spawn Recommended**: ${events.some((entry) => Boolean(entry.spawn_recommended))}`,
+    `> **Open Edits**: ${events.length}`,
+    "",
+    renderRequiredFollowUp(event),
+    "",
+    "## Touched Files",
+    "",
+    "| Last Event | Severity | Change Type | File |",
+    "| --- | --- | --- | --- |",
+    touchedRows || "| unknown | unknown | unknown | `unknown` |",
+    "",
+    "## Event Fields",
+    "",
+    "```json",
+    JSON.stringify(latestEvent, null, 2),
+    "```",
+    "",
+  ].join("\n");
+}
+
+function upsertRequest(args: Args): void {
+  const requestFile = requireOption(args, "requestFile");
+  const rawEvent = args.options.eventJson ?? readStdin();
+  const parsed = JSON.parse(rawEvent) as ArchitectureEvent;
+  const event = normalizeEvent(parsed, requestFile);
+  const existingMetadata = readMetadata(requestFile);
+  const events = dedupeEvents([...requestEventsFromSource(requestFile), event]);
+  mkdirSync(dirname(requestFile), { recursive: true });
+  writeFileSync(requestFile, renderRequestCard(event, events, existingMetadata));
+}
+
+function upsertFromRequest(args: Args): void {
+  const sourceRequest = requireOption(args, "sourceRequest");
+  const requestFile = requireOption(args, "requestFile");
+  const parsed = normalizeEvent(extractEventFields(sourceRequest), requestFile);
+  parsed.request_file = requestFile;
+  const existingMetadata = readMetadata(requestFile);
+  const events = dedupeEvents([...requestEventsFromSource(requestFile), parsed]);
+  mkdirSync(dirname(requestFile), { recursive: true });
+  writeFileSync(requestFile, renderRequestCard(parsed, events, existingMetadata));
+}
+
+function requestInfo(args: Args): string {
+  const requestFile = requireOption(args, "requestFile");
+  const metadata = readMetadata(requestFile);
+  const event = extractEventFields(requestFile);
+  return JSON.stringify({ metadata, event }, null, 2);
+}
+
+function pendingRequestFiles(requestsDir: string): string[] {
+  return readdirMarkdown(requestsDir)
+    .filter((file) => !file.includes("/archive/"))
+    .filter((file) => isPendingRequest(file));
+}
+
+function renderPendingBlock(requestsDir: string): string {
+  const files = pendingRequestFiles(requestsDir);
+  if (files.length === 0) return "- (none)";
+  return files
+    .map((file) => {
+      const metadata = readMetadata(file);
+      const ts = metadata.Updated || metadata.Detected || "unknown";
+      const severity = metadata.Severity || "unknown";
+      const changedFile = metadata.File || "unknown";
+      const name = file.split("/").pop() || file;
+      const slug = name.replace(/\.md$/, "");
+      return `- [ ] ${ts} [${severity}] \`${changedFile}\` -> [${slug}](requests/${name})`;
+    })
+    .sort()
+    .join("\n");
+}
+
+function removeLoosePendingRequestLines(source: string): string {
+  return source
+    .split(/\r?\n/)
+    .filter((line) => !/^- \[ \] .*\]\(requests\/[^)]+\.md\)$/.test(line.trim()))
+    .join("\n");
+}
+
+function replacePendingRequestsBlock(source: string, block: string): string {
+  const begin = "<!-- BEGIN ARCHITECTURE PENDING REQUESTS -->";
+  const end = "<!-- END ARCHITECTURE PENDING REQUESTS -->";
+  const controlled = `${begin}\n${block}\n${end}`;
+  const cleaned = removeLoosePendingRequestLines(source);
+  const markerPattern = new RegExp(`${begin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+  if (markerPattern.test(cleaned)) {
+    return `${cleaned.replace(markerPattern, controlled).replace(/\s+$/, "")}\n`;
+  }
+  const headingPattern = /(^## Pending Requests\s*\n)([\s\S]*?)(?=^## |\s*$)/m;
+  if (headingPattern.test(cleaned)) {
+    return `${cleaned
+      .replace(headingPattern, (_match, heading: string) => `${heading}\n${controlled}\n\n`)
+      .replace(/\s+$/, "")}\n`;
+  }
+  return `${cleaned.replace(/\s+$/, "")}\n\n## Pending Requests\n\n${controlled}\n`;
+}
+
+function reindexRequests(args: Args): void {
+  const indexFile = requireOption(args, "indexFile");
+  const requestsDir = requireOption(args, "requestsDir");
+  const current = existsSync(indexFile)
+    ? readFileSync(indexFile, "utf-8")
+    : [
+        "# Architecture Index",
+        "",
+        "> Umbrella architecture ledger for current boundaries, drift requests, snapshots, and diagrams.",
+        "",
+        "## Pending Requests",
+        "",
+      ].join("\n");
+  const next = replacePendingRequestsBlock(current, renderPendingBlock(requestsDir));
+  if (args.flags.has("check")) {
+    if (current !== next) {
+      console.error("architecture-event: pending request index is stale");
+      process.exit(1);
+    }
+    return;
+  }
+  mkdirSync(dirname(indexFile), { recursive: true });
+  writeFileSync(indexFile, next);
+}
+
+function defaultContextMap() {
+  return {
+    version: 1,
+    profile: "stable-root-progressive-subdir",
+    functional_block_selector: {
+      script: "scripts/select-agent-context-blocks.sh",
+      config_file: ".ai/context/agent-context-blocks.txt",
+      env: "FORGE_CONTEXT_BLOCKS",
+      rule: "compatibility selector; capability registry is the source of truth",
+    },
+    root_context_files: ["CLAUDE.md", "AGENTS.md"],
+    discoverable_contexts: [],
+  };
+}
+
+function syncContextMap(args: Args): void {
+  const contextMap = requireOption(args, "contextMap");
+  const block = requireOption(args, "block");
+  const capabilityId = requireOption(args, "capabilityId");
+  const contractAgents = requireOption(args, "contractAgents");
+  const contractClaude = requireOption(args, "contractClaude");
+  const domain = requireOption(args, "architectureDomain");
+  const capability = requireOption(args, "architectureCapability");
+  const lspProfile = args.options.lspProfile || "typescript-lsp";
+
+  mkdirSync(dirname(contextMap), { recursive: true });
+  if (!existsSync(contextMap)) {
+    writeFileSync(contextMap, `${JSON.stringify(defaultContextMap(), null, 2)}\n`);
+  }
+
+  let data: any;
+  try {
+    data = JSON.parse(readFileSync(contextMap, "utf-8"));
+  } catch {
+    data = defaultContextMap();
+  }
+
+  if (!Array.isArray(data.discoverable_contexts)) data.discoverable_contexts = [];
+
+  for (const [fileName, entryPath] of [
+    ["CLAUDE.md", contractClaude],
+    ["AGENTS.md", contractAgents],
+  ]) {
+    const targetAgent = fileName === "CLAUDE.md" ? "claude" : "codex";
+    if (!data.discoverable_contexts.some((entry: any) => entry && entry.path === entryPath)) {
+      data.discoverable_contexts.push({
+        path: entryPath,
+        priority: "high",
+        char_budget: 1000,
+        purpose: "capability-contract",
+        capability_id: capabilityId,
+        functional_block: block,
+        matched_prefix: block,
+        architecture_domain: domain,
+        architecture_capability: capability,
+        target_agent: targetAgent,
+        lsp_profile: lspProfile,
+        doc_scope: "capability-contract",
+        verification_hint: "record local commands here before implementation",
+      });
+    }
+  }
+
+  writeFileSync(contextMap, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function metadataValue(file: string, label: string): string {
+  if (!existsSync(file)) return "";
+  const prefix = `> **${label}**:`;
+  for (const line of readFileSync(file, "utf-8").split(/\r?\n/)) {
+    if (line.startsWith(prefix)) return line.slice(prefix.length).trim();
+  }
+  return "";
+}
+
+function activeWorkstreams(workstreamDir: string): string {
+  if (!existsSync(workstreamDir)) return "- (none yet)";
+  const files = readdirMarkdown(workstreamDir).slice(0, 5);
+  if (files.length === 0) return "- (none yet)";
+
+  return files
+    .flatMap((file) => {
+      const status = metadataValue(file, "Status") || "unknown";
+      const currentSlice = metadataValue(file, "Current Slice") || "unknown";
+      const sourcePlan = metadataValue(file, "Source Plan") || "unknown";
+      return [
+        `- \`${file}\``,
+        `  - status: ${status}`,
+        `  - current_slice: ${currentSlice}`,
+        `  - source_plan: ${sourcePlan}`,
+      ];
+    })
+    .join("\n");
+}
+
+function readdirMarkdown(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+      .map((entry) => `${dir.replace(/\/+$/, "")}/${entry.name}`)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function findLatestMatchingFile(dir: string, token: string, extension: string): string {
+  const files = collectFiles(dir)
+    .filter((file) => file.includes(token) && file.endsWith(extension))
+    .sort();
+  return files.at(-1) || "(none yet)";
+}
+
+function collectFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const files: string[] = [];
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = `${dir.replace(/\/+$/, "")}/${entry.name}`;
+      if (entry.isDirectory()) {
+        files.push(...collectFiles(path));
+      } else if (entry.isFile()) {
+        files.push(path);
+      }
+    }
+  } catch {
+    return [];
+  }
+  return files;
+}
+
+function renderContractBlock(args: Args): string {
+  const functionalBlock = requireOption(args, "functionalBlock");
+  const capabilityId = requireOption(args, "capabilityId");
+  const matchedPrefix = requireOption(args, "matchedPrefix");
+  const architectureDomain = requireOption(args, "architectureDomain");
+  const architectureCapability = requireOption(args, "architectureCapability");
+  const architectureModule = requireOption(args, "architectureModule");
+  const workstreamDir = requireOption(args, "workstreamDir");
+  const blockSlug = safeToken(functionalBlock);
+  const latestSnapshot = findLatestMatchingFile("docs/architecture/snapshots", blockSlug, ".md");
+  const latestHumanDiagram = findLatestMatchingFile("docs/architecture/diagrams", blockSlug, ".html");
+  const semanticDiagramSource = latestSnapshot === "(none yet)" ? architectureModule : latestSnapshot;
+  const eventTs = args.options.eventTs || "unknown";
+  const filePath = args.options.filePath || "unknown";
+  const severity = args.options.severity || "unknown";
+  const changeType = args.options.changeType || "unknown";
+  const lspProfile = args.options.lspProfile || "typescript-lsp";
+  const requestFile = args.options.requestFile || "unknown";
+
+  return [
+    "<!-- BEGIN ARCHITECTURE CONTRACT -->",
+    "## Architecture Contract",
+    "",
+    `- Functional block: \`${functionalBlock}\``,
+    `- Capability ID: \`${capabilityId}\``,
+    `- Matched prefix: \`${matchedPrefix}\``,
+    `- Architecture domain: \`${architectureDomain}\``,
+    `- Architecture capability: \`${architectureCapability}\``,
+    `- Architecture module: \`${architectureModule}\``,
+    `- Last architecture event: ${eventTs}`,
+    `- Last changed path: \`${filePath}\``,
+    `- Severity: ${severity}`,
+    `- Change type: ${changeType}`,
+    "- Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.",
+    `- Entrypoints: \`${functionalBlock}\``,
+    "- Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.",
+    "- Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.",
+    `- Runtime path: \`${functionalBlock}\``,
+    `- LSP/tooling profile: \`${lspProfile}\``,
+    "- Verification: Use root required checks plus local commands recorded in this capability contract.",
+    `- Latest snapshot: \`${latestSnapshot}\``,
+    `- Semantic diagram source: \`${semanticDiagramSource}\``,
+    `- Latest human diagram: \`${latestHumanDiagram}\``,
+    `- Pending architecture request: \`${requestFile}\``,
+    "",
+    "## Active Workstreams",
+    "",
+    activeWorkstreams(workstreamDir),
+    "",
+    "## Current Session Projection",
+    "",
+    `- Durable progress lives under \`${workstreamDir}\`.`,
+    "- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.",
+    "- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.",
+    "<!-- END ARCHITECTURE CONTRACT -->",
+    "",
+  ].join("\n");
+}
+
+function replaceContractBlock(source: string, block: string): string {
+  // Refuse to rewrite when markers are unbalanced: a lazy regex over a file
+  // with a missing END or duplicate BEGIN would silently duplicate the block
+  // or pair the wrong markers. Mirrors the guard in context-contract-sync.sh.
+  const begins = source.match(/^<!-- BEGIN ARCHITECTURE CONTRACT -->[ \t]*$/gm)?.length ?? 0;
+  const ends = source.match(/^<!-- END ARCHITECTURE CONTRACT -->[ \t]*$/gm)?.length ?? 0;
+  const balanced =
+    (begins === 0 && ends === 0) ||
+    (begins === 1 &&
+      ends === 1 &&
+      source.search(/^<!-- BEGIN ARCHITECTURE CONTRACT -->[ \t]*$/m) <
+        source.search(/^<!-- END ARCHITECTURE CONTRACT -->[ \t]*$/m));
+  if (!balanced) {
+    throw new Error(
+      `unbalanced ARCHITECTURE CONTRACT markers (begin=${begins} end=${ends}); refusing to rewrite. Repair the markers manually, then re-run sync.`,
+    );
+  }
+
+  const pattern = /^<!-- BEGIN ARCHITECTURE CONTRACT -->[ \t]*\n[\s\S]*?^<!-- END ARCHITECTURE CONTRACT -->[ \t]*\n?/m;
+  if (pattern.test(source)) return source.replace(pattern, () => block);
+  if (!source) return block;
+  return `${source.endsWith("\n") ? source : `${source}\n`}\n${block}`;
+}
+
+function defaultContractContext(): string {
+  return [
+    "# Functional Block Agent Context",
+    "",
+    "Keep this file focused on the local contract for this primary functional block.",
+    "",
+  ].join("\n");
+}
+
+function syncContractFiles(args: Args): void {
+  const contractAgents = requireOption(args, "contractAgents");
+  const contractClaude = requireOption(args, "contractClaude");
+  const block = renderContractBlock(args);
+  const basePath = existsSync(contractAgents) ? contractAgents : existsSync(contractClaude) ? contractClaude : "";
+  const source = basePath ? readFileSync(basePath, "utf-8") : defaultContractContext();
+  const updated = replaceContractBlock(source, block);
+
+  mkdirSync(dirname(contractAgents), { recursive: true });
+  mkdirSync(dirname(contractClaude), { recursive: true });
+  writeFileSync(contractAgents, updated);
+  writeFileSync(contractClaude, updated);
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+try {
+  switch (args.command) {
+    case "json-get":
+      print(jsonGet(args.options.json ?? readStdin(), requireOption(args, "key")));
+      break;
+    case "safe-token":
+      print(safeToken(requireOption(args, "value")));
+      break;
+    case "derive-scope": {
+      const scope = deriveScope(requireOption(args, "block"));
+      if ((args.options.format || "lines") === "json") print(JSON.stringify(scope));
+      print(
+        [
+          scope.architecture_domain,
+          scope.architecture_capability,
+          scope.architecture_module,
+          scope.workstream_dir,
+        ].join("\n")
+      );
+      break;
+    }
+    case "repo-path":
+      print(normalizeRepoPath(requireOption(args, "path"), requireOption(args, "repo")));
+      break;
+    case "event-json":
+      print(eventJson(args));
+      break;
+    case "upsert-request":
+      upsertRequest(args);
+      process.exit(0);
+    case "upsert-from-request":
+      upsertFromRequest(args);
+      process.exit(0);
+    case "reindex-requests":
+      reindexRequests(args);
+      process.exit(0);
+    case "request-info":
+      print(requestInfo(args));
+      break;
+    case "sync-context-map":
+      syncContextMap(args);
+      process.exit(0);
+    case "sync-contract-files":
+      syncContractFiles(args);
+      process.exit(0);
+  }
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}