@mmerterden/multi-agent-pipeline 16.5.0 → 16.7.0

package/pipeline/multi-agent-refs/analysis-template.md

@@ -42,7 +42,8 @@ Every per-platform file starts with this YAML block:
 ```yaml
 ---
 feature: <FeatureName>
-platform: ios | android | backend | frontend
+platform: ios | android | backend | frontend | none
+profile: global | corporate
 language: tr | en
 mode: full | lite
 ui_tests: true | false
@@ -63,6 +64,8 @@ template_version: v3
 
 `ui_tests` and `a11y_depth` record the Phase 0 Step 5a opt-ins (defaults `false` / `basic`) so the coverage choice is auditable and the pre-dispatch validator can enforce it: `ui_tests: true` requires Section 15.6, `a11y_depth: full` requires the Section 16.2 walkthrough.
 
+`profile` names the template the document was rendered against (Locked 32) and `platform: none` marks the stack-optional render (Locked 35). Both are read by `validate-analysis-doc.mjs`, which applies a different contract per profile: without the key a corporate document would be judged against the global rules and its backbone would read as a pile of Locked 2 violations.
+
 Phase 1 compares `evidence_digest` against an existing document to decide whether to reuse it (Locked 27). Phase 3 reads `platform` to verify file match, `mode` to know which section set to expect, and both `evidence_digest` and `base_commit` to judge freshness: the digest says the evidence changed, `base_commit` says the repo moved. Phase 2 parses the block but gates only on `template_version`.
 
 ## Layer headings (A / B / C)
@@ -912,25 +915,40 @@ Auto-populated rows (Locked 11, 23): repo-evidence direct-match candidates that
 
 ## 21. Referanslar / References
 
-Never omitted. Locked 20 - at the bottom, not at the top.
+Never omitted (Locked 21 - at the bottom, not at the top). Shared verbatim by both profiles.
+
+**Built deterministically, not written by the model.** `~/.claude/scripts/build-references.mjs` reads `state.analysisSpec.evidence.*` and emits this table. A hand-written references table drifts from what the run actually read: it lists what the author remembers consulting, which is a different set from what the evidence gathering fetched. Every row here is a source the run touched.
 
 ```markdown
 ## 21. Referanslar   <!-- TR -->
 ## 21. References    <!-- EN -->
 
-| Tür / Type | Kaynak / Source | URL or Path | Rol / Role | Notlar / Notes |
-|---|---|---|---|---|
-| Standards | <name> | <url or path> | binding | <version> |
-| Wiki | <name> | <url> | binding | <pattern referenced> |
-| Figma | <design name> | <url> | UI design | <n variants, all screenshots embedded> |
-| Confluence | <spec name> | <url> | feature spec | <v<n>> |
-| Confluence | <api contract> | <url> | API contract | <endpoint summary> |
-| Jira | <ticket id> | <url> | ticket | <description> |
-| Firebase | events | <console url> | reference only | auth-gated |
-| OpenAPI | generated | <repo path> | DTO source | <regen plugin name> |
-| Repo | <module> | <repo path> | existing implementation | <reuse summary> |
+| Tür / Type | Kaynak / Source | URL / Yol | Sürüm / Ref | Rol / Role | Erişim / Access | Notlar / Notes |
+|---|---|---|---|---|---|---|
+| Figma | <design name> | <url> | node-id=<nodeId> | UI design | ok (Tier <n>) | <n frames> |
+| Confluence | <spec name> | <url> | pageId=<id> v<n> | feature spec | ok | - |
+| Confluence | <api contract> | <url> | pageId=<id> v<n> | API contract | ok | <endpoint summary> |
+| Jira | <ticket id> | <url> | - | ticket | ok | <summary> |
+| Swagger | <api name> | <url> | <spec version> | API contract | ok | <n endpoints> |
+| Repo | <module> | <repo path> | <commit sha> | existing implementation | ok | <reuse summary> |
+| Standards | <name> | <url or path> | <version> | binding | ok | <kind> |
+| Firebase | events | <console url> | - | reference only | erişilemedi (auth) | <n events> |
+| Doküman | <file name> | <local path> | <format> | scope document | ok | - |
+| Dış kaynak | <name> | <url> | <citation> | referans | ok | <claim> |
+| Serbest metin | kullanıcı notu | - | - | <what it settled> | - | "<verbatim quote>" |
+| Confluence | <unreachable page> | <url> | - | getirilemedi | erişilemedi (403) | - |
 ```
 
+These row types are exactly what `build-references.mjs` emits, and the example is kept in step with it deliberately: a shape shown here but never produced would send a reader hand-checking against a table that cannot exist. A wiki source arrives as a `Standards` row carrying `wiki` in its `kind` cell, and a generated OpenAPI client arrives as the `Repo` row of the module that holds it; neither has a row type of its own.
+
+**Column contract.**
+
+- **Sürüm / Ref** is the precision anchor: the node id for a Figma frame, `pageId` plus page version for Confluence, the commit SHA the repo was read at, the spec version for Swagger. Without it a reference points at a moving target, and a reader six weeks later cannot tell whether the document described what they are looking at.
+- **Erişim / Access** is `ok` or `erişilemedi (<reason>)`. A source that was declared but could not be fetched still gets a row. Dropping it hides the gap: the reader sees a document that never mentions the API contract and assumes there was none, rather than knowing it was unreachable.
+- **Serbest metin** rows carry what the user stated in conversation that no fetched source contains, quoted verbatim, with the decision it settled in the `Rol` column. Scope decisions made in chat are evidence; leaving them out is how a document loses the reason it excluded something.
+
+**Coverage gate (Locked 34).** Before the document is emitted, the validator compares this table against the evidence record. Every entry in `evidence.figma[]`, `evidence.confluence[]`, `evidence.jira[]`, `evidence.swagger[]`, `evidence.repo[]`, `evidence.standards[]`, `evidence.firebase[]`, `evidence.documents[]`, `evidence.outside[]`, `evidence.freeText[]` and every entry in `evidence.fetchErrors[]` must appear as a row. A source that shaped the document but is missing from References fails the dispatch gate, and a row with no matching evidence entry fails it too - an invented reference is worse than a missing one.
+
 ## 22. Sözlük / Glossary
 
 Footer. Optional in Lite mode. Alphabetical.

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -6,15 +6,18 @@
 
 ---
 
-## 1. Command Inventory (51 files, 47 live commands)
+## 1. Command Inventory (53 files, 49 live commands)
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels, complaint-analysis, create-jira, design-check, dev,
-dev-autopilot, dev-local, dev-local-autopilot, diff-explain, forget, garbage-collect,
-help, ios-coding-standard, issue, jira, kill, language, local,
-local-autopilot, log, manual-test, prune-logs, prune-prompts, purge, refactor, resume, review, review-issue, review-jira,
-routines, save, scan, search, setup, resume-local, stack, status, store-ready, sync, test, test-accessibility,
-test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation, uninstall, update
+analysis, analysis-resolve, autopilot, build-optimize, channels,
+complaint-analysis, create-jira, design-check, dev, dev-autopilot, dev-local,
+dev-local-autopilot, diff-explain, feedback, forget, garbage-collect, help,
+ios-coding-standard, issue, jira, kill, language, local, local-autopilot,
+log, manual-test, prune-logs, prune-prompts, purge, refactor, resume,
+resume-local, review, review-analysis, review-issue, review-jira, routines,
+save, scan, search, setup, stack, status, store-ready, sync, test,
+test-accessibility, test-dark-mode, test-dynamic-type, test-screenshots,
+testflight-validation, uninstall, update
 ```
 
 Categories:

package/pipeline/multi-agent-refs/website-deploy.md

@@ -0,0 +1,87 @@
+# Website deploy: why the commit author decides whether the site updates
+
+Loaded by `/multi-agent:sync` Step 4. Read it when a website sync pushed cleanly
+and the live site did not change.
+
+## The failure
+
+The deploy platform builds a commit only when its author is a contributor on the
+project. A commit carrying any other identity is accepted by `git push` and then
+never built:
+
+```
+vercel ls   ->  Status UNKNOWN   Duration ?   Builds: . [0ms]
+API         ->  readyState: "BLOCKED"
+                readyStateReason: "The Deployment was blocked because the commit
+                                   author does not have contributing access ..."
+                seatBlock: { blockCode: "TEAM_ACCESS_REQUIRED", gitProvider: "github" }
+```
+
+Nothing in the push output says so, the deployment exists, and the site keeps
+serving the previous version. Pipeline v16.4.0 and v16.5.0 were both pushed this
+way; neither was ever built, and both syncs reported the website as done.
+
+## The rule
+
+The identity is the one `prefs.global.identities[]` routes to the website owner
+through `platformIdentityRouting`, which is not always the account the current run
+is working under. A run driven from a work account, or an exported
+`GIT_AUTHOR_EMAIL`, is exactly how the wrong author gets recorded.
+
+`$HOME/.claude/scripts/website-deploy-commit.sh` applies the rule:
+
+1. Read the clone's own `user.name` / `user.email` and write only on a mismatch.
+   The website clone is usually already configured correctly; overwriting it with
+   the caller's identity is the defect, not the fix.
+2. Commit only when something is staged.
+3. Read the author back off the commit with `git log -1 --format=%ae`. Setting
+   `git config` is not proof: an exported `GIT_AUTHOR_EMAIL` outranks it. On a
+   mismatch the script halts before pushing, so the bad commit stays local.
+4. Push, then wait for a Ready production build. A push is not a deploy.
+
+Exit codes: `0` committed and pushed (or nothing to do), `1` wrong author and
+nothing pushed, `2` usage or environment, `3` pushed but no Ready build.
+
+Env: `WEBSITE_SYNC_NO_PUSH=1` (local only), `WEBSITE_SYNC_NO_VERIFY=1` (skip the
+deployment check), `WEBSITE_SYNC_WAIT=<sec>` (default 45).
+
+## Recovery when a deployment is already blocked
+
+History does not need rewriting, and `main` is never force-pushed. The platform
+checks the HEAD commit of each new deployment, so a fresh commit under the right
+identity is enough:
+
+```bash
+git commit --allow-empty -m "chore(site): redeploy under the maintainer identity"
+git push origin main
+```
+
+Or deploy from the CLI, which attaches no rejected author:
+
+```bash
+cd "$WEBSITE_DIR" && vercel --prod --yes
+```
+
+Blocked deployments can be left in place; they hold no alias.
+
+## Diagnosing
+
+The CLI prints `UNKNOWN` and hides the reason; the API gives it:
+
+```
+GET https://api.vercel.com/v13/deployments/<dpl_id>?teamId=<team_id>
+    -> readyState, readyStateReason, seatBlock
+```
+
+Read the CLI token out of its own auth file into a variable. Never into argv, a
+log or a reply.
+
+## Verifying the live site
+
+- The repo directory name is not the domain. Check the domain the project
+  actually serves, not `$HOME/{website-host}`.
+- Version strings and counts are server-rendered and appear in the initial HTML.
+  Feature prose and lazily-loaded components do not: grep the JS chunks for those.
+- A `curl` on the HTML can return 403 bot mitigation (`x-vercel-mitigated:
+  challenge`) rather than the page, which reads like content that never shipped.
+  Static assets are not challenged.

package/pipeline/schemas/analysis-spec.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/{owner}/multi-agent-pipeline/pipeline/schemas/analysis-spec.schema.json",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "title": "Multi-Agent Pipeline - /multi-agent:analysis spec output (v3 template)",
   "description": "Contract for the feature-spec analysis document generated by /multi-agent:analysis. Platform-agnostic concept layer + Pass B per-platform render with repo-driven conventions. 23 sections in Full mode; 8 of them in Lite mode. Sections may be absent - omission is the policy when no evidence exists.",
   "type": "object",
@@ -49,6 +49,12 @@
       "default": "v3",
       "description": "Template version emitted. v3 is the platform-agnostic + Pass B render template (Locked 22)."
     },
+    "profile": {
+      "type": "string",
+      "enum": ["global", "corporate"],
+      "default": "global",
+      "description": "Analysis profile chosen at Phase 0 Step 1b (Locked 32). 'global' renders analysis-template.md (23-section development handoff); 'corporate' renders analysis-template-corporate.md (IG/UC/FG requirements document). Both read the same evidence; only the projection differs."
+    },
     "options": {
       "type": "object",
       "additionalProperties": false,
@@ -523,6 +529,20 @@
             }
           }
         },
+        "freeText": {
+          "type": "array",
+          "description": "User statements made in conversation that no fetched source carries, recorded so Section 21 can cite the decisions they settled (Locked 34).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["text"],
+            "properties": {
+              "label": { "type": "string" },
+              "text": { "type": "string" },
+              "role": { "type": "string" }
+            }
+          }
+        },
         "fetchErrors": {
           "type": "array",
           "description": "Phase 1 access failures (401/403/login-redirect). Surfaced as warnings, not blockers.",

package/pipeline/schemas/prefs.schema.json

@@ -821,6 +821,47 @@
           "default": false,
           "description": "v6.1.0+ - Phase 4 Step 2.5 rebuttal round. When reviewers disagree (mixed blocker/approved verdict), each reviewer is re-prompted with the others' opposing arguments for one additional round before triage. Lifts signal quality on ambiguous findings at ~1\u00d7 Step 2 token cost. Off by default - flip for security-critical or release-branch reviews."
         },
+        "analysisProfiles": {
+          "type": "array",
+          "description": "v16.6+ - which analysis standards the /multi-agent:analysis Step 1b picker offers (Locked 32). Listing one value auto-resolves the step instead of asking a question whose answer is already settled. Omitted means both are offered.",
+          "items": {
+            "type": "string",
+            "enum": ["global", "corporate"]
+          },
+          "default": ["global", "corporate"],
+          "uniqueItems": true,
+          "minItems": 1
+        },
+        "analysisProfile": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v16.6+ - per-profile deployment bindings. These are site configuration, not part of the shipped template: an unconfigured run still renders the full document and asks for its destination at Phase 3.5 like any other run. Keys are deliberately generic so no organisation's space, page or tooling names live in the repo.",
+          "properties": {
+            "corporate": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Bindings for the corporate profile: where its documents are published and which house terms they use.",
+              "properties": {
+                "confluenceSpaceKey": {
+                  "type": "string",
+                  "description": "Space the analysis page is created in when the Phase 3.5 picker chooses Confluence."
+                },
+                "confluenceParentPageId": {
+                  "type": "string",
+                  "description": "Parent page the analysis is filed under."
+                },
+                "titleFormat": {
+                  "type": "string",
+                  "description": "Page-title pattern, e.g. \"{prefix}{module}_{flow}_{suffix}\". Placeholders are resolved at emit time."
+                },
+                "titlePrefix": {
+                  "type": "string",
+                  "description": "Prefix that marks pipeline-authored pages so they stay distinguishable from hand-written ones."
+                }
+              }
+            }
+          }
+        },
         "updateCheck": {
           "type": "object",
           "additionalProperties": false,

package/pipeline/scripts/build-references.mjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+// build-references.mjs  -  deterministic Section 21 References table for an
+// /multi-agent:analysis document (Locked 34).
+//
+// The references table used to be prose the model filled in. That lists what an
+// author remembers consulting, which is a different set from what the run
+// actually fetched: sources that failed to load vanish silently, scope decisions
+// made in conversation never appear, and a Figma link with no node id points at
+// whatever the file looks like today. This turns the table into a projection of
+// `state.analysisSpec.evidence.*` so the two cannot disagree.
+//
+// Zero deps. Two modes:
+//
+//   build   (default)  state JSON  -> markdown table on stdout
+//   --check <doc.md>   state JSON + emitted doc -> coverage gate, exit 1 on drift
+//
+// Usage:
+//   node build-references.mjs state.json [--lang tr|en]
+//   node build-references.mjs state.json --check analysis/Feature-ios.md
+//   cat state.json | node build-references.mjs - --lang en
+//
+// Exit codes: 0 ok, 1 coverage failure, 2 usage / parse error.
+
+import { readFileSync } from "node:fs";
+
+const HEADERS = {
+  tr: ["Tür", "Kaynak", "URL / Yol", "Sürüm / Ref", "Rol", "Erişim", "Notlar"],
+  en: ["Type", "Source", "URL / Path", "Version / Ref", "Role", "Access", "Notes"],
+};
+
+const OK = { tr: "ok", en: "ok" };
+const FAILED = { tr: "erişilemedi", en: "not reachable" };
+const NONE = "-";
+
+function argOf(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i === -1 ? null : argv[i + 1] ?? null;
+}
+
+function readState(path) {
+  const raw = path === "-" ? readFileSync(0, "utf8") : readFileSync(path, "utf8");
+  const parsed = JSON.parse(raw);
+  // Accept either the full task state or the analysisSpec alone.
+  return parsed.analysisSpec ?? parsed;
+}
+
+// A cell that would break the pipe table, or read as an empty column, is worse
+// than a visibly absent value: the reader cannot tell a missing cell from a
+// cell that was never meant to have content.
+function cell(value) {
+  if (value === null || value === undefined) return NONE;
+  const text = String(value).replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
+  return text === "" ? NONE : text;
+}
+
+function accessCell(ok, reason, lang) {
+  if (ok) return OK[lang];
+  return reason ? `${FAILED[lang]} (${cell(reason)})` : FAILED[lang];
+}
+
+// The identity of a source for coverage purposes. Two rows describing the same
+// URL are the same source; a row with no locator falls back to its label so a
+// free-text note still has something to match on.
+function keyOf(url, fallback) {
+  const value = url && String(url).trim() !== "" && url !== NONE ? url : fallback;
+  return value ? String(value).trim() : null;
+}
+
+function rowsFrom(spec, lang) {
+  const ev = spec.evidence ?? {};
+  const rows = [];
+  const push = (type, source, url, ref, role, access, notes) => {
+    rows.push({
+      type,
+      cells: [cell(type), cell(source), cell(url), cell(ref), cell(role), access, cell(notes)],
+      key: keyOf(url, source),
+    });
+  };
+
+  for (const f of ev.figma ?? []) {
+    const ref = f.nodeId ? `node-id=${f.nodeId}` : f.fileKey ? `fileKey=${f.fileKey}` : NONE;
+    const frames = Array.isArray(f.frames) ? f.frames.length : 0;
+    const tier = f.tier ? ` (Tier ${f.tier})` : "";
+    push(
+      "Figma",
+      f.frames?.[0]?.name ?? f.fileKey ?? "design",
+      f.url,
+      ref,
+      lang === "tr" ? "UI tasarım" : "UI design",
+      OK[lang] + tier,
+      frames ? (lang === "tr" ? `${frames} frame` : `${frames} frames`) : NONE,
+    );
+  }
+
+  for (const c of ev.confluence ?? []) {
+    const ref = [c.pageId ? `pageId=${c.pageId}` : null, c.version ? `v${c.version}` : null]
+      .filter(Boolean)
+      .join(" ");
+    push(
+      "Confluence",
+      c.title ?? c.pageId,
+      c.url,
+      ref || NONE,
+      c.embeddedApiTable
+        ? lang === "tr" ? "API kontratı" : "API contract"
+        : lang === "tr" ? "özellik spesifikasyonu" : "feature spec",
+      OK[lang],
+      NONE,
+    );
+  }
+
+  for (const j of ev.jira ?? []) {
+    push("Jira", j.id, j.url ?? NONE, NONE, lang === "tr" ? "ticket" : "ticket", OK[lang], j.summary);
+  }
+
+  for (const s of ev.swagger ?? []) {
+    const n = Array.isArray(s.endpoints) ? s.endpoints.length : 0;
+    push(
+      "Swagger",
+      s.title ?? s.url,
+      s.url,
+      s.version ?? NONE,
+      lang === "tr" ? "API kontratı" : "API contract",
+      OK[lang],
+      n ? (lang === "tr" ? `${n} endpoint` : `${n} endpoints`) : NONE,
+    );
+  }
+
+  for (const r of ev.repo ?? []) {
+    push(
+      "Repo",
+      r.repoName,
+      r.path ?? r.repoName,
+      r.commit ?? r.sha ?? NONE,
+      lang === "tr" ? "mevcut kod" : "existing implementation",
+      OK[lang],
+      r.reuseSummary,
+    );
+  }
+
+  for (const s of ev.standards ?? []) {
+    push(
+      "Standards",
+      s.title ?? s.source,
+      s.source,
+      s.version ?? NONE,
+      s.binding ? "binding" : lang === "tr" ? "referans" : "reference",
+      OK[lang],
+      s.kind,
+    );
+  }
+
+  for (const f of ev.firebase ?? []) {
+    const n = Array.isArray(f.events) ? f.events.length : 0;
+    push(
+      "Firebase",
+      f.kind ?? "events",
+      f.source,
+      NONE,
+      lang === "tr" ? "referans" : "reference only",
+      OK[lang],
+      n ? (lang === "tr" ? `${n} event` : `${n} events`) : NONE,
+    );
+  }
+
+  for (const d of ev.documents ?? []) {
+    push(
+      lang === "tr" ? "Doküman" : "Document",
+      d.title ?? d.path,
+      d.path,
+      d.format ?? NONE,
+      d.binding ? "binding" : lang === "tr" ? "kapsam dokümanı" : "scope document",
+      accessCell(d.fetched !== false, d.fetched === false ? d.reason : null, lang),
+      NONE,
+    );
+  }
+
+  for (const o of ev.outside ?? []) {
+    push(
+      lang === "tr" ? "Dış kaynak" : "External",
+      o.source,
+      o.url ?? NONE,
+      o.citation ?? NONE,
+      lang === "tr" ? "referans" : "reference",
+      OK[lang],
+      o.claim,
+    );
+  }
+
+  for (const s of ev.signals ?? []) {
+    push(
+      lang === "tr" ? "Sinyal" : "Signal",
+      s.source,
+      s.url ?? NONE,
+      s.observedAt ?? NONE,
+      lang === "tr" ? "referans" : "reference",
+      OK[lang],
+      s.claim,
+    );
+  }
+
+  // Statements the user made in conversation that no fetched source carries.
+  // These settle scope as often as a document does, and a document that drops
+  // them loses the reason it excluded something.
+  for (const t of ev.freeText ?? []) {
+    push(
+      lang === "tr" ? "Serbest metin" : "Free text",
+      t.label ?? (lang === "tr" ? "kullanıcı notu" : "user note"),
+      NONE,
+      NONE,
+      t.role ?? (lang === "tr" ? "kapsam kararı" : "scope decision"),
+      NONE,
+      t.text ? `"${t.text}"` : NONE,
+    );
+  }
+
+  // A declared source that could not be fetched still gets a row. Dropping it
+  // reads to the next person as a source that never existed, which is the
+  // opposite of what happened.
+  for (const e of ev.fetchErrors ?? []) {
+    push(
+      e.type ?? (lang === "tr" ? "Kaynak" : "Source"),
+      e.title ?? e.url,
+      e.url,
+      NONE,
+      lang === "tr" ? "getirilemedi" : "not fetched",
+      accessCell(false, e.reason, lang),
+      NONE,
+    );
+  }
+
+  return rows;
+}
+
+function renderTable(rows, lang) {
+  const head = HEADERS[lang];
+  const lines = [`| ${head.join(" | ")} |`, `|${head.map(() => "---").join("|")}|`];
+  for (const r of rows) lines.push(`| ${r.cells.join(" | ")} |`);
+  return lines.join("\n");
+}
+
+// The References table in an emitted document: from the Section 21 heading to
+// the next heading of the same level or the end of the file.
+function extractReferencesBlock(doc) {
+  const lines = doc.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^##\s+\d+\.\s+(Referanslar|References)\b/.test(l));
+  if (start === -1) return null;
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+\d+\./.test(lines[i])) break;
+    out.push(lines[i]);
+  }
+  return out.join("\n");
+}
+
+// The header row and the separator row carry no source to verify. Matching them
+// against the evidence record is how a correct table gets reported as carrying
+// an invented reference.
+const HEADER_CELLS = new Set(
+  Object.values(HEADERS)
+    .flat()
+    .map((h) => h.toLowerCase()),
+);
+
+function tableLocators(block) {
+  const found = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (!line.trim().startsWith("|")) continue;
+    const cells = line.split("|").slice(1, -1).map((c) => c.trim());
+    if (cells.length < 3) continue;
+    if (/^:?-{3,}:?$/.test(cells[0])) continue;
+    const locator = cells[2];
+    const source = cells[1];
+    if (!locator) continue;
+    if (HEADER_CELLS.has(locator.toLowerCase()) && HEADER_CELLS.has(cells[0].toLowerCase())) continue;
+    found.push({ locator, source, raw: line });
+  }
+  return found;
+}
+
+function check(spec, docPath, lang) {
+  const doc = readFileSync(docPath, "utf8");
+  const block = extractReferencesBlock(doc);
+  const problems = [];
+
+  if (block === null) {
+    problems.push("ERROR: no References section found; Section 21 is never omitted (Locked 21)");
+    return problems;
+  }
+
+  const expected = rowsFrom(spec, lang).filter((r) => r.key !== null);
+  const rendered = tableLocators(block);
+  const renderedText = block;
+
+  for (const row of expected) {
+    if (!renderedText.includes(row.key)) {
+      problems.push(
+        `ERROR: ${row.type} source consumed by the run but absent from References: ${row.key}`,
+      );
+    }
+  }
+
+  const expectedKeys = new Set(expected.map((r) => r.key));
+  for (const r of rendered) {
+    // Header rows and placeholder cells carry no locator to verify.
+    if (r.locator === NONE || r.locator === "" || /^<.*>$/.test(r.locator)) continue;
+    const known = [...expectedKeys].some((k) => r.locator.includes(k) || k.includes(r.locator));
+    if (!known) {
+      problems.push(
+        `ERROR: References row has no matching evidence entry (invented reference): ${r.locator}`,
+      );
+    }
+  }
+
+  return problems;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const statePath = argv[0];
+  if (!statePath || statePath.startsWith("--")) {
+    process.stderr.write(
+      "usage: build-references.mjs <state.json|-> [--lang tr|en] [--check <doc.md>]\n",
+    );
+    process.exit(2);
+  }
+
+  let spec;
+  try {
+    spec = readState(statePath);
+  } catch (err) {
+    process.stderr.write(`ERROR: cannot read state: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  const lang = argOf(argv, "--lang") ?? spec.language ?? "tr";
+  if (!HEADERS[lang]) {
+    process.stderr.write(`ERROR: unknown language "${lang}"; expected tr or en\n`);
+    process.exit(2);
+  }
+
+  const docPath = argOf(argv, "--check");
+  if (docPath) {
+    const problems = check(spec, docPath, lang);
+    if (problems.length) {
+      for (const p of problems) process.stderr.write(`${p}\n`);
+      process.stderr.write(`\n${problems.length} references coverage failure(s)\n`);
+      process.exit(1);
+    }
+    process.stdout.write("references coverage ok\n");
+    process.exit(0);
+  }
+
+  const rows = rowsFrom(spec, lang);
+  if (rows.length === 0) {
+    // An analysis with no sources at all is possible (a pure free-text run) but
+    // it should say so rather than emit an empty table with a header.
+    process.stdout.write(
+      lang === "tr"
+        ? "Bu koşuda getirilen kaynak yok.\n"
+        : "No sources were fetched for this run.\n",
+    );
+    process.exit(0);
+  }
+  process.stdout.write(`${renderTable(rows, lang)}\n`);
+}
+
+main();