@mmerterden/multi-agent-pipeline 12.2.0 → 12.3.0

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

@@ -49,6 +49,24 @@
       "default": "v3",
       "description": "Template version emitted. v3 is the platform-agnostic + Pass B render template (Locked 22)."
     },
+    "options": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Coverage opt-ins captured at Phase 0 Step 5a. Absent = defaults (no UI tests, basic accessibility).",
+      "properties": {
+        "uiTests": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, Section 15.6 renders UI test scenarios (XCUITest / Compose UI test)."
+        },
+        "a11yDepth": {
+          "type": "string",
+          "enum": ["basic", "full"],
+          "default": "basic",
+          "description": "basic = Section 16.1 checklist only; full = also render the 16.2 VoiceOver/TalkBack walkthrough."
+        }
+      }
+    },
     "evidenceDigest": {
       "type": ["string", "null"],
       "pattern": "^sha256:[0-9a-f]{64}$",
@@ -110,6 +128,8 @@
               "url": { "type": "string", "format": "uri" },
               "fileKey": { "type": ["string", "null"] },
               "nodeId": { "type": ["string", "null"] },
+              "screenshotUrl": { "type": ["string", "null"], "description": "Local PNG path or signed render URL for this node." },
+              "tier": { "type": ["integer", "null"], "enum": [1, 2, 3, null], "description": "Figma access tier used to capture this record (mirrors state.figmaAccess.tier)." },
               "frames": {
                 "type": "array",
                 "items": {
@@ -134,6 +154,64 @@
                     "repoPath": { "type": ["string", "null"] }
                   }
                 }
+              },
+              "codeConnectSnippets": {
+                "type": "array",
+                "description": "Verbatim CodeConnectSnippet blocks captured on Tier 1 (component name + modifier chain).",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "nodeId": { "type": ["string", "null"] },
+                    "component": { "type": "string" },
+                    "snippet": { "type": ["string", "null"] }
+                  }
+                }
+              },
+              "tokens": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "name": { "type": "string" },
+                    "value": { "type": ["string", "null"] }
+                  }
+                }
+              },
+              "textLayers": {
+                "type": "array",
+                "description": "Visible text-layer content. Treated as placeholder copy when an annotation exists for the same node (annotation wins).",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "nodeId": { "type": ["string", "null"] },
+                    "name": { "type": ["string", "null"] },
+                    "text": { "type": "string" }
+                  }
+                }
+              },
+              "annotations": {
+                "type": "array",
+                "description": "Dev Mode annotations captured as authoritative copy ground truth (Phase 1 annotation ingestion). Empty unless annotations.enabled in the project figma-config.",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["nodeId", "mode"],
+                  "properties": {
+                    "nodeId": { "type": "string" },
+                    "name": { "type": ["string", "null"] },
+                    "designText": { "type": ["string", "null"], "description": "The visible-layer text at this node (often a placeholder)." },
+                    "raw": { "type": ["string", "null"], "description": "The raw annotation label/labelMarkdown before parsing." },
+                    "parsed": {
+                      "type": "object",
+                      "description": "Parsed copy keyed by language code (lowercased), e.g. { tr, en }.",
+                      "additionalProperties": { "type": "string" }
+                    },
+                    "mode": { "type": "string", "enum": ["prefixed", "two-line", "single", "empty"] }
+                  }
+                }
               }
             }
           }

package/pipeline/schemas/figma-project-config.schema.json

@@ -50,6 +50,55 @@
         }
       }
     },
+    "annotations": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Figma Dev Mode annotation ingestion. When enabled, /multi-agent:analysis treats annotations as the authoritative copy for a node (the visible text layer is a placeholder). Absent or disabled = current behavior (visible text layers only).",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "langPrefixes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["TR", "EN"],
+          "description": "Ordered language-code prefixes the annotation parser recognizes, e.g. [\"TR\",\"EN\"]. A `TR: ...\\nEN: ...` label parses by prefix; a two-line label with no prefix maps line 1 -> langPrefixes[0], line 2 -> langPrefixes[1]; a single line -> langPrefixes[0]."
+        },
+        "devModeCategory": {
+          "type": ["string", "null"],
+          "description": "Optional Dev Mode annotation category to filter on (e.g. a copy/UX-writing category). Null = accept all annotations on the node."
+        }
+      }
+    },
+    "localization": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How this project owns localization. Drives Section 10 of /multi-agent:analysis. Default `in-repo` keeps the historical hand-filled per-locale grid; `externally-owned` defers per-locale values to an authoring system (the analysis names key + status + copy source + base value only).",
+      "properties": {
+        "ownership": {
+          "type": "string",
+          "enum": ["in-repo", "externally-owned"],
+          "default": "in-repo"
+        },
+        "authoringPipeline": {
+          "type": ["string", "null"],
+          "description": "Human-readable reference to the owning localization system when ownership = externally-owned (e.g. a workflow or resource-bot name). Rendered as the Ownership column value; never a secret."
+        },
+        "locales": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Supported locale codes for this project (e.g. [\"tr\",\"en\",\"ar\",\"de\",\"es\",\"fr\",\"it\",\"ru\"]). Overrides the built-in default locale set used by Section 10.",
+          "minItems": 1
+        },
+        "baseLanguage": {
+          "type": "string",
+          "default": "en",
+          "description": "Source/base language code. A key missing its base-language value is a defect (renders the raw key at runtime)."
+        },
+        "keyPattern": {
+          "type": ["string", "null"],
+          "description": "Key naming convention hint, e.g. `Namespace.Case`. Documentation only; not enforced."
+        }
+      }
+    },
     "github": {
       "type": "object",
       "additionalProperties": false,

package/pipeline/schemas/prefs.schema.json

@@ -1258,6 +1258,28 @@
             "figmaConfigPath": {
               "type": "string",
               "description": "Path to per-project figma-config.json (for Figma pipeline projects)."
+            },
+            "standardsFile": {
+              "type": "string",
+              "description": "Filename (or absolute/tilde path) of the canonical home-dir Standards reference for this project, used by /multi-agent:analysis Q5 auto-detect (e.g. ~/<project>-Standards.md)."
+            },
+            "editableRelatedRepos": {
+              "type": "array",
+              "items": { "type": "string" },
+              "maxItems": 20,
+              "description": "Extra writable repos to offer in the dev-context picker beyond auto-detected submodules (iOS/Android/Backend)."
+            },
+            "frontendRepos": {
+              "type": "array",
+              "items": { "type": "string" },
+              "maxItems": 20,
+              "description": "Frontend repos for this project, used by /multi-agent:analysis Step 4 (Frontend is rarely in the iOS/Android submodule tree)."
+            },
+            "frontendRoots": {
+              "type": "array",
+              "items": { "type": "string" },
+              "maxItems": 20,
+              "description": "Whitelist source roots for the Frontend repo-evidence scan (overrides the default src/ app/ components/ features/ lib/)."
             }
           }
         }

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -2,18 +2,18 @@
 .claude/CLAUDE.md	1
 .claude/agents	8
 .claude/commands	44
-.claude/lib	26
+.claude/lib	27
 .claude/multi-agent-preferences.json	1
 .claude/multi-agent-refs	51
 .claude/rules	12
 .claude/schemas	23
-.claude/scripts	193
+.claude/scripts	195
 .claude/settings.json	1
 .claude/skills	428
 .copilot/.pipeline-version	1
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
-.copilot/lib	26
+.copilot/lib	27
 .copilot/schemas	23
-.copilot/scripts	193
+.copilot/scripts	195
 .copilot/skills	467

package/pipeline/scripts/smoke-fetchers-offline.sh

@@ -354,6 +354,46 @@ assert_in_file "^-i" "$WORK/security-argv.log" "security invoked in -i stdin mod
 assert_not_in_file "$SECRET_VALUE" "$WORK/security-argv.log" "secret absent from security argv"
 assert_in_file "$SECRET_VALUE" "$WORK/security-stdin.log" "secret delivered via stdin"
 
+# -----------------------------------------------------------------------------
+note "7b. fetch-figma-annotations.sh (Tier-2 annotation ingestion)"
+# -----------------------------------------------------------------------------
+expect_rc 1 "no args exits 1 (usage)" \
+  "$SH" "$LIB/fetch-figma-annotations.sh"
+
+# Missing token -> blocked JSON + exit 2 (no network).
+expect_rc 2 "missing token exits 2 with blocked JSON" \
+  env HOME="$FAKE_HOME" USER=smoke \
+  "$SH" "$LIB/fetch-figma-annotations.sh" --file-key ABC --node-id "1:23"
+assert_in_file "missing-token" "$OUT" "blocked JSON names missing-token"
+
+# Fake curl returns a /nodes doc carrying a TR:/EN: annotation; with a stub
+# token the parser must reach + parse it (regression guard for the parser).
+BIN_CURL_ANNOT="$WORK/bin-curl-annot"
+mkdir -p "$BIN_CURL_ANNOT"
+cat > "$BIN_CURL_ANNOT/curl" <<'FAKE'
+#!/bin/bash
+out=""; prev=""
+for a in "$@"; do
+  [ "$prev" = "-o" ] && out="$a"
+  prev="$a"
+done
+if [ -n "$out" ]; then
+  cat > "$out" <<'JSON'
+{"nodes":{"1:23":{"document":{"id":"1:23","name":"Title","type":"TEXT","characters":"Giriniz","annotations":[{"label":"TR: Ucusunuzu secin\nEN: Select your flight"}]}}}}
+JSON
+fi
+printf '200'
+exit 0
+FAKE
+chmod +x "$BIN_CURL_ANNOT/curl"
+
+expect_rc 0 "stub token + annotation doc parses (exit 0)" \
+  env HOME="$FAKE_HOME" USER=smoke FIGMA_PAT=fake-token \
+      PATH="$BIN_CURL_ANNOT:$PATH" \
+  "$SH" "$LIB/fetch-figma-annotations.sh" --file-key ABC --node-id "1:23" --lang-prefixes TR,EN
+assert_in_file "\"mode\": \"prefixed\"" "$OUT" "annotation parsed as prefixed"
+assert_in_file "Select your flight" "$OUT" "EN copy extracted from annotation"
+
 # -----------------------------------------------------------------------------
 note "8. static source checks (bash-3.2 compat + no secrets on argv)"
 # -----------------------------------------------------------------------------
@@ -363,6 +403,7 @@ OWNED_FILES=(
   "$LIB/fetch-swagger.sh"
   "$LIB/fetch-fortify.sh"
   "$LIB/fetch-graylog.sh"
+  "$LIB/fetch-figma-annotations.sh"
   "$LIB/figma-mcp-refresh.sh"
   "$LIB/figma-screenshot.sh"
   "$LIB/credential-store.sh"

package/pipeline/scripts/smoke-validate-analysis-doc.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# smoke-validate-analysis-doc.sh  -  contract for validate-analysis-doc.mjs,
+# the deterministic gate over an emitted /multi-agent:analysis document.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+V="$SCRIPT_DIR/validate-analysis-doc.mjs"
+
+PASS=0
+FAIL=0
+record_pass() { PASS=$((PASS + 1)); printf '  \342\234\223 %s\n' "$1"; }
+record_fail() { FAIL=$((FAIL + 1)); printf '  \342\234\227 %s\n' "$1"; }
+
+printf '\342\206\222 smoke-validate-analysis-doc: emitted-doc gate\n'
+
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/vdoc.XXXXXX")
+trap 'rm -rf "$tmp"' EXIT
+
+# A well-formed Full-mode doc (neutral UserProfile domain, BR referenced downstream).
+cat > "$tmp/good.md" <<'MD'
+---
+feature: UserProfile
+platform: ios
+language: tr
+mode: full
+template_version: v3
+---
+## 1. Özet
+Profile screen.
+## 2. Hedefler ve Karşı Hedefler
+goals.
+## 4. Kullanıcı Hikayeleri
+### 4.4 İş Kuralları
+| BR-profile-01 | rule | source | Given/When/Then |
+## 9. API Kontratları
+api.
+## 13. Mimari Plan
+arch.
+## 14. Eklenecek Dosyalar
+files.
+## 15. Test Planı
+BR-profile-01 happy path.
+## 20. Riskler ve Açık Sorular
+risk.
+## 21. Referanslar
+refs.
+MD
+
+if node "$V" "$tmp/good.md" >/dev/null 2>&1; then
+  record_pass "well-formed Full doc passes (exit 0)"
+else
+  record_fail "well-formed doc should pass"
+fi
+
+# Lite doc without Section 15 must still pass (Locked 31 mode-aware).
+cat > "$tmp/lite.md" <<'MD'
+---
+feature: UserProfile
+platform: ios
+language: en
+mode: lite
+template_version: v3
+---
+## 1. Summary
+s
+## 2. Goals and Non-Goals
+g
+## 4. User Stories
+### 4.4 Business Rules
+| BR-profile-01 | rule | source | Given/When/Then |
+## 9. API Contracts
+a
+## 13. Architecture
+x
+## 14. Files to Add
+f
+## 20. Risks and Open Questions
+r
+## 21. References
+ref
+MD
+if node "$V" "$tmp/lite.md" >/dev/null 2>&1; then
+  record_pass "Lite doc (no Section 15) passes - mode-aware Locked 31"
+else
+  record_fail "Lite doc without Section 15 must pass"
+fi
+
+# Missing front-matter -> ERROR.
+printf '## 1. Summary\nno front matter\n' > "$tmp/nofm.md"
+node "$V" "$tmp/nofm.md" >/dev/null 2>&1
+[ "$?" -eq 1 ] && record_pass "missing front-matter fails (exit 1)" || record_fail "missing front-matter should fail"
+
+# Banned punctuation (em-dash) -> ERROR.
+cp "$tmp/good.md" "$tmp/emdash.md"
+printf 'A line with an em-dash \342\200\224 here.\n' >> "$tmp/emdash.md"
+# Capture first (pipefail + node's nonzero exit would poison a direct pipe).
+emdash_out=$(node "$V" "$tmp/emdash.md" 2>&1 || true)
+if printf '%s' "$emdash_out" | grep -q "em-dash"; then
+  record_pass "em-dash flagged (Locked 7)"
+else
+  record_fail "em-dash should be flagged"
+fi
+
+# Missing a never-omitted section (References) -> ERROR.
+grep -v "Referanslar\|References" "$tmp/good.md" > "$tmp/noref.md"
+node "$V" "$tmp/noref.md" >/dev/null 2>&1
+[ "$?" -eq 1 ] && record_pass "missing References section fails" || record_fail "missing References should fail"
+
+# Define-only BR under --strict -> fail (WARN promoted).
+cat > "$tmp/orphan.md" <<'MD'
+---
+feature: UserProfile
+platform: ios
+language: en
+mode: full
+template_version: v3
+---
+## 1. Summary
+s
+## 2. Goals
+g
+## 4. User Stories
+### 4.4 Business Rules
+| BR-profile-42 | rule | source | Given/When/Then |
+## 9. API Contracts
+a
+## 13. Architecture
+x
+## 14. Files to Add
+f
+## 15. Test Plan
+no BR reference here
+## 20. Risks
+r
+## 21. References
+ref
+MD
+node "$V" "$tmp/orphan.md" >/dev/null 2>&1
+[ "$?" -eq 0 ] && record_pass "define-only BR is WARN, not error (default)" || record_fail "orphan BR should not hard-fail by default"
+node "$V" "$tmp/orphan.md" --strict >/dev/null 2>&1
+[ "$?" -eq 1 ] && record_pass "define-only BR fails under --strict" || record_fail "orphan BR should fail under --strict"
+
+# ui_tests: true but no Section 15.6 -> ERROR.
+sed 's/^mode: full/mode: full\nui_tests: true\na11y_depth: basic/' "$tmp/good.md" > "$tmp/uimiss.md"
+node "$V" "$tmp/uimiss.md" >/dev/null 2>&1
+[ "$?" -eq 1 ] && record_pass "ui_tests:true without Section 15.6 fails" || record_fail "ui_tests:true must require 15.6"
+
+# ui_tests: true WITH a Section 15.6 heading -> passes.
+cp "$tmp/uimiss.md" "$tmp/uiok.md"
+printf '## 15.6 UI test senaryolari\nUI-profile-01 flow.\n' >> "$tmp/uiok.md"
+node "$V" "$tmp/uiok.md" >/dev/null 2>&1
+[ "$?" -eq 0 ] && record_pass "ui_tests:true with Section 15.6 passes" || record_fail "ui_tests:true + 15.6 should pass"
+
+# a11y_depth: full but no Section 16.2 walkthrough -> ERROR.
+sed 's/^mode: full/mode: full\nui_tests: false\na11y_depth: full/' "$tmp/good.md" > "$tmp/a11ymiss.md"
+node "$V" "$tmp/a11ymiss.md" >/dev/null 2>&1
+[ "$?" -eq 1 ] && record_pass "a11y_depth:full without Section 16.2 fails" || record_fail "a11y_depth:full must require 16.2"
+
+printf '\n\342\225\220\342\225\220 smoke-validate-analysis-doc: %d passed, %d failed \342\225\220\342\225\220\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

package/pipeline/scripts/validate-analysis-doc.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// validate-analysis-doc.mjs  -  deterministic validator for an EMITTED
+// /multi-agent:analysis document (analysis/<feature>-<platform>.md).
+//
+// The analysis SKILL states many "fails the dispatch gate" invariants as prose
+// the model is asked to self-enforce. This turns the high-value, mechanically
+// checkable ones into a real gate so a malformed spec is caught before it is
+// handed to a human or to /multi-agent:dev.
+//
+// Zero deps. Reads one markdown file (path arg or STDIN).
+//
+// Checks (ERROR = blocking exit 1; WARN = advisory, still exit 0 unless --strict):
+//   - Front-matter block with required keys (feature, platform, language, mode,
+//     template_version); mode in {full, lite}; platform in the known set.
+//   - Never-omitted sections present by title keyword (Locked 2): Summary,
+//     Goals, User Stories, API Contracts, Architecture, Files to Add, Risks,
+//     References.
+//   - Humanizer punctuation policy (Locked 7): no em-dash / en-dash / ellipsis /
+//     section-sign / curly quotes anywhere in the body.
+//   - Traceability (Full mode only, Locked 31): every BR-<slug>-NN id defined in
+//     the Business Rules area is referenced again later (test / acceptance /
+//     analytics). A define-only rule is a WARN (heuristic).
+//   - No whole-section "TBD" / "Not applicable" placeholder bodies (Locked 2);
+//     the inline "[label TBD - see Open Questions]" marker is allowed.
+//
+// Usage:
+//   node validate-analysis-doc.mjs analysis/UserProfile-ios.md
+//   cat doc.md | node validate-analysis-doc.mjs -
+//   node validate-analysis-doc.mjs doc.md --strict   # WARN also fails
+//
+// Exit: 0 valid, 1 invalid (or WARN under --strict), 64 usage error.
+
+import { readFileSync } from "node:fs";
+
+const KNOWN_PLATFORMS = new Set(["ios", "android", "backend", "frontend"]);
+const REQUIRED_FM = ["feature", "platform", "language", "mode", "template_version"];
+
+// Never-omitted sections (Locked 2), matched by bilingual title keyword so the
+// re-flowed section numbering does not matter.
+const REQUIRED_SECTIONS = [
+  { key: "summary", any: ["Summary", "Özet", "Ozet"] },
+  { key: "goals", any: ["Goals", "Hedefler"] },
+  { key: "user stories", any: ["User Stories", "Kullanıcı Hikayeleri", "Kullanici Hikayeleri"] },
+  { key: "api contracts", any: ["API Contracts", "API Kontratları", "API Kontratlari"] },
+  { key: "architecture", any: ["Architecture", "Mimari"] },
+  { key: "files to add", any: ["Files to Add", "Eklenecek Dosyalar"] },
+  { key: "risks", any: ["Risks", "Riskler"] },
+  { key: "references", any: ["References", "Referanslar"] },
+];
+
+// Humanizer punctuation policy (Locked 7) - banned codepoints.
+const BANNED_PUNCT = [
+  { ch: "—", name: "em-dash" },
+  { ch: "–", name: "en-dash" },
+  { ch: "…", name: "ellipsis" },
+  { ch: "§", name: "section-sign" },
+  { ch: "“", name: "curly-double-open" },
+  { ch: "”", name: "curly-double-close" },
+  { ch: "‘", name: "curly-single-open" },
+  { ch: "’", name: "curly-single-close" },
+];
+
+function readInput() {
+  const args = process.argv.slice(2).filter((a) => a !== "--strict");
+  const arg = args[0];
+  if (!arg) {
+    console.error("usage: validate-analysis-doc.mjs <path|-> [--strict]");
+    process.exit(64);
+  }
+  if (arg === "-") return readFileSync(0, "utf-8");
+  return readFileSync(arg, "utf-8");
+}
+
+function parseFrontMatter(text) {
+  const lines = text.split("\n");
+  if (lines[0].trim() !== "---") return null;
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return null;
+  const fm = {};
+  for (let i = 1; i < end; i++) {
+    const m = lines[i].match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+    if (m) fm[m[1]] = m[2].trim();
+  }
+  return { fm, bodyStart: end + 1 };
+}
+
+function main() {
+  const text = readInput();
+  const strict = process.argv.includes("--strict");
+  const errors = [];
+  const warns = [];
+
+  // 1. Front-matter
+  const parsed = parseFrontMatter(text);
+  if (!parsed) {
+    errors.push("missing YAML front-matter block (--- ... ---) at the top");
+  } else {
+    for (const k of REQUIRED_FM) {
+      if (!parsed.fm[k]) errors.push(`front-matter missing required key: ${k}`);
+    }
+    const mode = parsed.fm.mode;
+    if (mode && mode !== "full" && mode !== "lite") {
+      errors.push(`front-matter mode must be full|lite, got: ${mode}`);
+    }
+    const plat = parsed.fm.platform;
+    if (plat && !KNOWN_PLATFORMS.has(plat)) {
+      errors.push(`front-matter platform not in known set: ${plat}`);
+    }
+  }
+  const mode = parsed?.fm?.mode || "full";
+
+  // 2. Never-omitted sections (by heading keyword)
+  const headings = text
+    .split("\n")
+    .filter((l) => /^#{1,3}\s/.test(l))
+    .map((l) => l.replace(/^#{1,3}\s/, "").trim());
+  const headingBlob = headings.join("\n");
+  for (const sec of REQUIRED_SECTIONS) {
+    if (!sec.any.some((kw) => headingBlob.includes(kw))) {
+      errors.push(`missing required section (Locked 2): ${sec.key}`);
+    }
+  }
+
+  // 2b. Opt-in coverage sections must be present when the front-matter says so.
+  const uiTests = String(parsed?.fm?.ui_tests || "false").toLowerCase() === "true";
+  const a11yDepth = String(parsed?.fm?.a11y_depth || "basic").toLowerCase();
+  const headingBlobLower = headingBlob.toLowerCase();
+  if (uiTests) {
+    const hasUi =
+      headingBlob.includes("15.6") ||
+      headingBlobLower.includes("ui test") ||
+      headingBlobLower.includes("ui-test");
+    if (!hasUi) {
+      errors.push("front-matter ui_tests: true but no Section 15.6 UI test scenarios found (Locked 31)");
+    }
+  }
+  if (a11yDepth === "full") {
+    const hasWalkthrough =
+      headingBlob.includes("16.2") ||
+      headingBlobLower.includes("walkthrough") ||
+      headingBlobLower.includes("gezinme");
+    if (!hasWalkthrough) {
+      errors.push("front-matter a11y_depth: full but no Section 16.2 screen-reader walkthrough found");
+    }
+  }
+
+  // 3. Humanizer punctuation
+  const bodyLines = text.split("\n");
+  for (let i = 0; i < bodyLines.length; i++) {
+    for (const b of BANNED_PUNCT) {
+      if (bodyLines[i].includes(b.ch)) {
+        errors.push(`banned punctuation ${b.name} at line ${i + 1} (Locked 7 humanizer policy)`);
+      }
+    }
+  }
+
+  // 4. Placeholder whole-section bodies (Locked 2)
+  if (/^\s*(TBD|Not applicable|N\/A)\s*$/im.test(text)) {
+    warns.push('a line is a bare "TBD"/"Not applicable"/"N/A" body; omit the section instead (Locked 2)');
+  }
+
+  // 5. Traceability (Full mode only, Locked 31)
+  if (mode === "full") {
+    const idRe = /BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/gi;
+    const all = text.match(idRe) || [];
+    const counts = new Map();
+    for (const id of all) {
+      const key = id.toUpperCase();
+      counts.set(key, (counts.get(key) || 0) + 1);
+    }
+    if (counts.size === 0) {
+      warns.push("Full mode but no BR-<slug>-NN business-rule ids found (Section 4.4 / Locked 31)");
+    }
+    for (const [id, n] of counts) {
+      if (n < 2) {
+        warns.push(`business rule ${id} is defined but never referenced downstream (test/acceptance/analytics) - Locked 31 traceability`);
+      }
+    }
+  }
+
+  // Report
+  for (const w of warns) console.error(`WARN: ${w}`);
+  for (const e of errors) console.error(`ERROR: ${e}`);
+  if (errors.length > 0) {
+    console.error(`validate-analysis-doc: FAIL (${errors.length} error(s), ${warns.length} warning(s))`);
+    process.exit(1);
+  }
+  if (strict && warns.length > 0) {
+    console.error(`validate-analysis-doc: FAIL under --strict (${warns.length} warning(s))`);
+    process.exit(1);
+  }
+  console.log(`validate-analysis-doc: OK (mode=${mode}, ${warns.length} warning(s))`);
+  process.exit(0);
+}
+
+main();