@mmerterden/multi-agent-pipeline 18.0.0 → 19.1.0

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

@@ -11,7 +11,7 @@
 //
 // 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.
+//     template_version); mode must be full (lite removed in v19.0.0); 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.
@@ -27,7 +27,7 @@
 //   - Manual scenarios (Section 15.7): every MT- row carries a BR- id.
 //   - Variant coverage (Section 6.X): every axis row states the full axis and
 //     the subset this screen uses; half a row cannot be audited.
-//   - Traceability (Full mode only, Locked 31): every BR-<slug>-NN id defined in
+//   - Traceability (Full mode only, Locked 30): 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);
@@ -43,7 +43,7 @@
 import { readFileSync } from "node:fs";
 import { runMain } from "../lib/fatal.mjs";
 
-// A repo-less run (Locked 35) still splits by channel, derived from the evidence:
+// A repo-less run (Locked 34) still splits by channel, derived from the evidence:
 // "mobile" and "web" are its platform values. "none" is the narrower case where the
 // evidence describes no interface at all. All three are real values, not missing ones.
 // "web" is the pre-"web" spelling, still accepted so older documents validate.
@@ -63,7 +63,7 @@ const REQUIRED_SECTIONS = [
   { key: "references", any: ["References", "Referanslar"] },
 ];
 
-// Corporate profile backbone (Locked 33). These render even with zero evidence,
+// Corporate profile backbone (Locked 32). These render even with zero evidence,
 // carrying N/A or EKLENECEK, so their absence is a structural failure rather
 // than a legitimate omission.
 const CORPORATE_SECTIONS = [
@@ -245,16 +245,31 @@ function main() {
     for (const k of REQUIRED_FM) {
       if (!parsed.fm[k]) errors.push(`front-matter missing required key: ${k}`);
     }
+    // `mode` is accepted only as "full" now. Lite was removed in v19.0.0: it
+    // picked sections from a fixed list chosen by a three-signal score, which
+    // fought Locked 2 in both directions - a small feature with rich business
+    // rules lost Section 15 because it was not on the list, and a feature with
+    // no API contract kept Section 9 because it was. An older document carrying
+    // `mode: lite` is still readable; it is reported as a legacy value rather
+    // than rejected, because the document was valid when it was written.
     const mode = parsed.fm.mode;
-    if (mode && mode !== "full" && mode !== "lite") {
-      errors.push(`front-matter mode must be full|lite, got: ${mode}`);
+    if (mode === "lite") {
+      warns.push(
+        "front-matter says mode: lite  -  Lite was removed in v19.0.0 and this is a pre-v19 document. Sections are chosen by evidence now (Locked 2).",
+      );
+    } else if (mode && mode !== "full") {
+      errors.push(`front-matter mode must be full, 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";
+  // A pre-v19 `lite` document is validated as Full: the checks it skipped were
+  // skipped because of a mode that no longer exists, and re-skipping them here
+  // would carry that exemption forward forever.
+  const mode = "full";
+  void parsed?.fm?.mode;
   const profile = (parsed?.fm?.profile || "global").toLowerCase();
   if (profile !== "global" && profile !== "corporate") {
     errors.push(`front-matter profile must be global|corporate, got: ${profile}`);
@@ -275,7 +290,7 @@ function main() {
     // The development layer is legitimately absent when no repo was selected,
     // so requiring it there would fail every stack-optional document.
     .filter((sec) => !(noPlatform && REPO_DEPENDENT_KEYS.has(sec.key)));
-  const rule = profile === "corporate" ? "Locked 33" : "Locked 2";
+  const rule = profile === "corporate" ? "Locked 32" : "Locked 2";
   for (const sec of requiredSections) {
     if (!sec.any.some((kw) => headingBlob.includes(kw))) {
       errors.push(`missing required section (${rule}): ${sec.key}`);
@@ -301,7 +316,7 @@ function main() {
   //
   // It ran only in the corporate profile until now, which made the global one the
   // profile where an inline marker could point at nothing. Two documents already
-  // told it to: Locked 36 says an unstamped gap fails the dispatch gate with no
+  // told it to: Locked 35 says an unstamped gap fails the dispatch gate with no
   // profile clause, and analysis/render.md routes an external-dependency gap to
   // `AS-NN` in Section 20 for every run. The check was the only side that
   // disagreed. Nothing changes for a document that carries no markers: every loop
@@ -326,13 +341,13 @@ function main() {
       // A gap that names no id cannot be traced to an owner, which is the whole
       // point of admitting it.
       if (!/\bAS-\d{2,3}\b/.test(lines[i])) {
-        errors.push(`line ${i + 1}: EKLENECEK carries no AS-NN reference (Locked 33)`);
+        errors.push(`line ${i + 1}: EKLENECEK carries no AS-NN reference (Locked 32)`);
       }
     }
     for (const id of referencedIds) {
       if (!definedIds.has(id)) {
         errors.push(
-          `${id} is referenced in the body but not defined in Risks and Open Questions (Locked 33)`,
+          `${id} is referenced in the body but not defined in Risks and Open Questions (Locked 32)`,
         );
       }
     }
@@ -343,7 +358,7 @@ function main() {
         const row = risksBlock.split("\n").find((l) => l.includes(id)) || "";
         if (!/(no body reference|govde referansi yok)/i.test(row)) {
           errors.push(
-            `${id} is defined in Risks and Open Questions but never referenced in the body (Locked 33)`,
+            `${id} is defined in Risks and Open Questions but never referenced in the body (Locked 32)`,
           );
         }
       }
@@ -379,13 +394,13 @@ function main() {
         const owner = cells[oi] || "";
         if (!owner || /^(-|\?|TBD|EKLENECEK|N\/A)$/i.test(owner)) {
           const id = (row.match(/\bAS-\d{2,3}\b/) || ["a row"])[0];
-          errors.push(`${id} names no owner in Risks and Open Questions (Locked 36)`);
+          errors.push(`${id} names no owner in Risks and Open Questions (Locked 35)`);
         }
       }
     } else if (rows.some((l) => /\bAS-\d{2,3}\b/.test(l))) {
       // Only when there is something to own. A Section 20 with no stamped row
       // has no owner to check, and warning there would fire on every document
-      // that never needed the column - noise that Phase 4 runs under --strict.
+      // that never needed the column - noise that Phase 3 runs under --strict.
       warns.push(
         "Risks and Open Questions carries AS-NN rows but no owner column; ownership cannot be checked",
       );
@@ -424,7 +439,7 @@ function main() {
         }
       }
       for (const id of [...openMarkers].sort()) {
-        errors.push(`status: final but ${id} is still open (Locked 36 closure gate)`);
+        errors.push(`status: final but ${id} is still open (Locked 35 closure gate)`);
       }
       const stillOpen =
         risksStatusIdx >= 0
@@ -474,7 +489,7 @@ function main() {
     if (mode === "full") {
       const matrixStart = lines.findIndex((l) => /^#{2,4}\s/.test(l) && MATRIX_HEADING.test(l));
       if (matrixStart === -1) {
-        errors.push("corporate Full mode requires the requirement traceability matrix (Locked 33)");
+        errors.push("corporate Full mode requires the requirement traceability matrix (Locked 32)");
       } else {
         let matrixBlock = "";
         for (let i = matrixStart + 1; i < lines.length; i++) {
@@ -505,7 +520,7 @@ function main() {
       }
       mark("traceability-matrix");
     } else {
-      mark("traceability-matrix", "lite mode");
+      mark("traceability-matrix");
     }
   } else {
     mark("payload-in-table-cell", "global profile");
@@ -562,7 +577,7 @@ function main() {
       headingBlobLower.includes("ui-test");
     if (!hasUi) {
       errors.push(
-        "front-matter ui_tests: true but no Section 15.6 UI test scenarios found (Locked 31)",
+        "front-matter ui_tests: true but no Section 15.6 UI test scenarios found (Locked 30)",
       );
     }
   }
@@ -580,12 +595,12 @@ function main() {
 
   mark("optin-coverage-sections");
 
-  // 2c. The Test Plan is Phase 3's RED input (phase-3-dev.md step 5b): the tests
+  // 2c. The Test Plan is Phase 3's RED input (phase-2-dev.md step 5b): the tests
   // written first come from it. Full mode without it hands dev an empty matrix.
   // It is Section 15 in the global profile and Section 19 in the corporate one;
   // the check matches on the title, so only the stack-optional case needs an
   // exemption - there the whole development layer is legitimately absent
-  // (Locked 35) and there is no repo for a test to run against yet.
+  // (Locked 34) and there is no repo for a test to run against yet.
   if (mode === "full" && !noPlatform) {
     const hasTestPlan = ["Test Planı", "Test Plani", "Test Plan"].some((kw) =>
       headingBlob.includes(kw),
@@ -594,12 +609,12 @@ function main() {
       // The omission table allows exactly one case: a backend-only run with no
       // contract testing planned. The validator knows the platform, so that case
       // warns instead of blocking; every other platform hands dev an empty matrix.
-      const msg = "no Section 15 Test Plan; Full mode dev reads it as the RED input (Locked 31)";
+      const msg = "no Section 15 Test Plan; dev reads it as the RED input (Locked 30)";
       if (parsed?.fm?.platform === "backend") {
         warns.push(`${msg} - allowed for backend only when no contract testing is planned`);
       } else {
         errors.push(
-          `missing Section 15 Test Plan; Full mode dev reads it as the RED input (Locked 31)`,
+          `missing Section 15 Test Plan; Full mode dev reads it as the RED input (Locked 30)`,
         );
       }
     } else {
@@ -609,14 +624,13 @@ function main() {
         headingBlobLower.includes("unit test");
       if (!hasUnit && /BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/i.test(text)) {
         errors.push(
-          "Section 15 has no unit-test sub-table while business rules are defined (Locked 31)",
+          "Section 15 has no unit-test sub-table while business rules are defined (Locked 30)",
         );
       }
     }
   }
 
-  if (mode !== "full") mark("test-plan", "lite mode");
-  else if (noPlatform) mark("test-plan", "no target platform");
+  if (noPlatform) mark("test-plan", "no target platform");
   else mark("test-plan");
 
   // 2d. Section 3 carries the diagrams. Omission is legitimate under the
@@ -726,7 +740,7 @@ function main() {
 
   mark("concept-table-evidence", conceptBody ? undefined : "no concept table");
 
-  // 2g. Locked 31 main clause: a rule with no test scenario fails the gate.
+  // 2g. Locked 30 main clause: a rule with no test scenario fails the gate.
   // The pre-existing occurrence-count heuristic below stays as the looser net.
   if (mode === "full") {
     const idRx = /BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/gi;
@@ -741,15 +755,15 @@ function main() {
       const tested = new Set((testBody.join("\n").match(idRx) || []).map((x) => x.toUpperCase()));
       for (const id of defined) {
         if (!tested.has(id)) {
-          errors.push(`business rule ${id} has no Section 15 test scenario (Locked 31)`);
+          errors.push(`business rule ${id} has no Section 15 test scenario (Locked 30)`);
         }
       }
     }
   }
 
-  mark("rule-to-test", mode === "full" ? undefined : "lite mode");
+  mark("rule-to-test");
 
-  // 2h. Redesign mode (Locked 37). Eight checks, live only when the front-matter
+  // 2h. Redesign mode (Locked 36). Eight checks, live only when the front-matter
   // opts in. The contract they enforce is analysis/redesign.md, which loads only
   // on a redesign run; what is here is the enforcement, not the explanation.
   const redesign = String(parsed?.fm?.redesign || "false").toLowerCase() === "true";
@@ -773,7 +787,7 @@ function main() {
       [epBody, "4.6 Endpoint Mapping"],
       [dlBody, "9.5 Difference List"],
     ]) {
-      if (!body) errors.push(`redesign: true but Section ${name} is missing (Locked 37)`);
+      if (!body) errors.push(`redesign: true but Section ${name} is missing (Locked 36)`);
     }
 
     const STATUSES = ["Moved", "Partial", "Missing", "New", "Out of scope"];
@@ -790,11 +804,11 @@ function main() {
       // the row that was not marked.
       if (!/:\d+\b/.test(evidence) && !certainty.includes("uncertain")) {
         errors.push(
-          `current-behaviour row ${id} cites no file:line and is not marked uncertain (Locked 37)`,
+          `current-behaviour row ${id} cites no file:line and is not marked uncertain (Locked 36)`,
         );
       }
       // 3. A rule that lives only in a shared module legitimately reads this way,
-      // so it warns rather than blocks - and Phase 4 runs --strict, so it blocks
+      // so it warns rather than blocks - and Phase 3 runs --strict, so it blocks
       // there, which is where a human is already looking.
       if (/cross-cutting/i.test(evidence) && certainty.includes("confirmed")) {
         warns.push(
@@ -811,14 +825,14 @@ function main() {
       // 4. A controlled vocabulary decaying into free text.
       if (!status) {
         errors.push(
-          `difference-list row ${id} has status "${statusCell}"; expected one of ${STATUSES.join(" / ")} (Locked 37)`,
+          `difference-list row ${id} has status "${statusCell}"; expected one of ${STATUSES.join(" / ")} (Locked 36)`,
         );
         continue;
       }
       // 5. The reason the mode exists: a behaviour v2 drops with no decision.
       if ((status === "Missing" || status === "Partial") && !/\bAS-\d{2,3}\b/.test(row)) {
         errors.push(
-          `difference-list row ${id} is ${status} with no AS-NN open question (Locked 37)`,
+          `difference-list row ${id} is ${status} with no AS-NN open question (Locked 36)`,
         );
       }
     }
@@ -852,7 +866,7 @@ function main() {
       const cellCount = (line) =>
         line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").length;
       if (!header) {
-        errors.push("Section 4.6 has no v1/v2 header row (Locked 37)");
+        errors.push("Section 4.6 has no v1/v2 header row (Locked 36)");
       } else {
         const cols = cellCount(header);
         for (const row of tableDataRows(epBody)) {
@@ -871,7 +885,7 @@ function main() {
     // keyword as a raw substring of the heading line - deliberately, since Locked
     // 2 re-flows section numbers and the corporate profile numbers them
     // differently - so an unrelated `### 4.9 Notes on the old Current Behaviour
-    // audit process` matched, and Phase 4 runs --strict, which turns this warning
+    // audit process` matched, and Phase 3 runs --strict, which turns this warning
     // into a blocked document. The artefact itself is the honest signal: a
     // rendered current-behaviour table always carries `CB-<slug>-NN` ids, and a
     // paragraph that merely uses the words never does.
@@ -911,7 +925,7 @@ function main() {
 
   // 4. Placeholder whole-section bodies (Locked 2).
   // Not a defect in the corporate profile: there N/A and EKLENECEK are how a
-  // backbone section reports "considered, nothing to state" (Locked 33), and the
+  // backbone section reports "considered, nothing to state" (Locked 32), and the
   // EKLENECEK-to-open-question pairing above is what keeps them honest.
   if (profile === "global" && /^\s*(TBD|Not applicable|N\/A)\s*$/im.test(text)) {
     warns.push(
@@ -921,7 +935,49 @@ function main() {
 
   mark("placeholder-bodies", profile === "global" ? undefined : "corporate profile");
 
-  // 5. Traceability (Full mode only, Locked 31)
+  // 4b. Locked 2's numbering half, which was ungated until v19.0.0.
+  //
+  // It is NOT "numbering re-flows 1..N". That is what the rule used to say and
+  // it could not hold: Locked 30 threads ids across the document by section
+  // NUMBER ("Section 15.1 scenario", "Section 4.4", "Section 3/5 layout cells"),
+  // so a re-flowed document sends every one of those references to the wrong
+  // section. No emitted document ever re-flowed. The rule was the wrong half.
+  //
+  // What holds instead: a rendered section keeps its canonical template number,
+  // so gaps are correct and `1, 2, 4, 9, 13, 14, 21` is a valid document. Two
+  // things are still defects and both are checked here - a number outside the
+  // template's range, and numbers that repeat or go backwards. Either one means
+  // a cross-reference lands somewhere its author did not intend.
+  {
+    const MAX_SECTION = 23;
+    const nums = [];
+    for (const l of text.split("\n")) {
+      const m = /^##\s+(\d+)\.\s/.exec(l);
+      if (m) nums.push(Number(m[1]));
+    }
+    if (nums.length === 0) {
+      mark("section-numbering", "no numbered top-level sections");
+    } else {
+      const outOfRange = nums.filter((n) => n < 1 || n > MAX_SECTION);
+      const notAscending = [];
+      for (let i = 1; i < nums.length; i++) {
+        if (nums[i] <= nums[i - 1]) notAscending.push(`${nums[i - 1]} then ${nums[i]}`);
+      }
+      if (outOfRange.length > 0) {
+        errors.push(
+          `section number outside the 1..${MAX_SECTION} template range (Locked 2): ${outOfRange.join(", ")}`,
+        );
+      }
+      if (notAscending.length > 0) {
+        errors.push(
+          `section numbers repeat or go backwards (Locked 2): ${notAscending.slice(0, 4).join("; ")}`,
+        );
+      }
+      mark("section-numbering");
+    }
+  }
+
+  // 5. Traceability (Locked 30)
   if (mode === "full") {
     const idRe = /BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/gi;
     const all = text.match(idRe) || [];
@@ -931,18 +987,18 @@ function main() {
       counts.set(key, (counts.get(key) || 0) + 1);
     }
     if (counts.size === 0 && profile === "global") {
-      warns.push("Full mode but no BR-<slug>-NN business-rule ids found (Section 4.4 / Locked 31)");
+      warns.push("no BR-<slug>-NN business-rule ids found (Section 4.4 / Locked 30)");
     }
     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`,
+          `business rule ${id} is defined but never referenced downstream (test/acceptance/analytics) - Locked 30 traceability`,
         );
       }
     }
   }
 
-  mark("br-reference-count", mode === "full" ? undefined : "lite mode");
+  mark("br-reference-count");
 
   // 6. Manual test scenarios (Section 15.7): every MT row carries a BR id.
   // A manual scenario nobody can trace back to a rule is a scenario nobody can
@@ -951,7 +1007,7 @@ function main() {
     if (!/^\|\s*MT-[a-z0-9-]+/i.test(line)) continue;
     if (!/BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/i.test(line)) {
       const id = (line.match(/MT-[a-z0-9-]+/i) || ["MT row"])[0];
-      errors.push(`manual scenario ${id} has no BR- id (Section 15.7 / Locked 31)`);
+      errors.push(`manual scenario ${id} has no BR- id (Section 15.7 / Locked 30)`);
     }
   }
 
@@ -978,13 +1034,188 @@ function main() {
     if (/^-+$/.test(cells[1]) || /Bile\u015fen|Component/i.test(cells[1])) continue;
     if (!cells[3] || !cells[4]) {
       errors.push(
-        `variant row "${cells[1]}" is missing the all-values or used-here column (Section 6.X / Locked 29)`,
+        `variant row "${cells[1]}" is missing the all-values or used-here column (Section 6.X / Locked 28)`,
       );
     }
   }
 
   mark("variant-coverage");
 
+  // 2h. Locked 13, 14, 15, 17, 18 and 21.
+  //
+  // Each checks a SHAPE the template prescribes. None judges content: a gate
+  // that guesses at meaning fails honest documents, and a gate people learn to
+  // ignore is worse than the prose it replaced.
+  //
+  // Each is keyed off a structure only a real document carries, so a minimal
+  // document is skipped rather than failed. "Section 4 exists" is not evidence
+  // that anybody wrote scenarios, and "Section 4 has a 4.1 sub-heading" is.
+
+  // Locked 13: Section 4 scenarios are Gherkin, not prose.
+  const storiesBody = sectionBody(allLines, [
+    "Kullanıcı Hikayeleri",
+    "Kullanici Hikayeleri",
+    "User Stories",
+  ]);
+  if (storiesBody) {
+    const blocks = [];
+    let inFence = false;
+    let isGherkin = false;
+    let buf = [];
+    for (const line of storiesBody) {
+      if (line.trim().startsWith("```")) {
+        if (!inFence) {
+          inFence = true;
+          isGherkin = /^```\s*gherkin/i.test(line.trim());
+          buf = [];
+        } else {
+          if (isGherkin) blocks.push(buf.join("\n"));
+          inFence = false;
+        }
+        continue;
+      }
+      if (inFence && isGherkin) buf.push(line);
+    }
+    // Scenarios are 4.1 to 4.3. 4.4 is the business-rule table, and a redesign
+    // run adds 4.5 and up (Locked 36: current behaviour, endpoint mapping,
+    // difference list) - none of which is a scenario, so "everything except
+    // 4.4" would demand Gherkin of three tables.
+    const scenarioHeads = storiesBody.filter((l) => /^#{3}\s+4\.[1-3]\b/.test(l));
+    if (scenarioHeads.length && !blocks.length) {
+      errors.push(
+        `Section 4 has ${scenarioHeads.length} scenario sub-section(s) and no \`\`\`gherkin block; plain-prose user stories are rejected (Locked 13)`,
+      );
+    }
+    blocks.forEach((b, i) => {
+      const missing = ["Given", "When", "Then"].filter(
+        (k) => !new RegExp(`(^|\\n)\\s*${k}\\b`).test(b),
+      );
+      if (missing.length) {
+        errors.push(`Section 4 gherkin block ${i + 1} states no ${missing.join(", ")} (Locked 13)`);
+      }
+    });
+  }
+
+  mark("gherkin-scenarios", storiesBody ? undefined : "no User Stories section");
+
+  // Locked 14: Goals and Non-Goals are paired. A goal with an empty counterpart
+  // cell is the failure the decision names - omission cannot be read as
+  // exclusion, so the column has to say what is NOT covered.
+  const goalsBody = sectionBody(allLines, [
+    "Hedefler ve Karşı Hedefler",
+    "Hedefler ve Karsi Hedefler",
+    "Goals and Non-Goals",
+    "Goals",
+  ]);
+  let goalRows = 0;
+  if (goalsBody) {
+    for (const row of tableDataRows(goalsBody)) {
+      const cells = row
+        .split("|")
+        .map((c) => c.trim())
+        .filter((c, i, a) => i !== 0 && i !== a.length - 1);
+      if (cells.length < 2) continue;
+      goalRows++;
+      if (!cells[1] || cells[1] === "-") {
+        errors.push(`goal "${cells[0].slice(0, 40)}" has no paired non-goal (Locked 14)`);
+      }
+    }
+  }
+
+  mark("goals-paired", goalRows ? undefined : "no Goals/Non-Goals table");
+
+  // Locked 15: a new asset that is not SVG owes a rationale. The decision
+  // allows Lottie and optimized PNG - it does not allow them silently.
+  const assetsBody = sectionBody(allLines, ["Asset Envanteri", "Asset Inventory"]);
+  let assetRows = 0;
+  if (assetsBody) {
+    for (const row of tableDataRows(assetsBody)) {
+      const cells = row
+        .split("|")
+        .map((c) => c.trim())
+        .filter((c, i, a) => i !== 0 && i !== a.length - 1);
+      if (cells.length < 5) continue;
+      assetRows++;
+      const [name, format, existing, , notes] = cells;
+      const isNew = /^(no|hayır|hayir)\b/i.test(existing);
+      if (!isNew) continue;
+      if (/\bsvg\b/i.test(format)) continue;
+      if (!notes || !/\S/.test(notes.replace(/^new,?\s*/i, ""))) {
+        errors.push(
+          `new asset "${name.slice(0, 40)}" is ${format} rather than SVG and states no exception rationale (Locked 15)`,
+        );
+      }
+    }
+  }
+
+  mark("asset-format", assetRows ? undefined : "no Asset Inventory table");
+
+  // Locked 17: "other errors" is the phrase the decision exists to reject. An
+  // exhaustive list cannot be checked for exhaustiveness from inside the
+  // document, but the admission that it is not exhaustive can.
+  const apiBody = sectionBody(allLines, ["API Kontratları", "API Kontratlari", "API Contracts"]);
+  if (apiBody) {
+    const VAGUE = [
+      /\bother errors?\b/i,
+      /\bvarious \dxx\b/i,
+      /\bdiğer hatalar\b/i,
+      /\bdiger hatalar\b/i,
+      /\betc\.?\s*\|/i,
+    ];
+    for (const line of apiBody) {
+      const hit = VAGUE.find((rx) => rx.test(line));
+      if (hit) {
+        errors.push(
+          `Section 9 stands in for a status code instead of listing it: "${line.trim().slice(0, 60)}" (Locked 17)`,
+        );
+      }
+    }
+  }
+
+  mark("api-variants-exhaustive", apiBody ? undefined : "no API Contracts section");
+
+  // Locked 18: screenshots are embedded, not linked. A remote image survives
+  // exactly as long as whatever serves it, and the document outlives that.
+  const designBody = sectionBody(allLines, [
+    "Tasarım Referansı",
+    "Tasarim Referansi",
+    "Design Reference",
+  ]);
+  if (designBody) {
+    for (const line of designBody) {
+      const m = /!\[[^\]]*\]\((https?:\/\/[^)]+)\)/.exec(line);
+      if (m) {
+        errors.push(
+          `Section 5 links a remote screenshot instead of embedding a local file: ${m[1].slice(0, 60)} (Locked 18)`,
+        );
+      }
+    }
+  }
+
+  mark("screenshots-embedded", designBody ? undefined : "no Design Reference section");
+
+  // Locked 21: References sit at the bottom. The reader sees goals, flow and
+  // design before sources, which is only true if no numbered section follows.
+  const topNums = [];
+  let refNum = null;
+  for (const line of allLines) {
+    const m = /^##\s+(\d+)\.\s+(.*)$/.exec(line);
+    if (!m) continue;
+    const n = Number(m[1]);
+    topNums.push(n);
+    if (/Referanslar|References/i.test(m[2])) refNum = n;
+  }
+  if (refNum !== null && topNums.length) {
+    const highest = Math.max(...topNums);
+    if (refNum !== highest) {
+      errors.push(
+        `References is Section ${refNum} but Section ${highest} follows it, and sources go last (Locked 21)`,
+      );
+    }
+  }
+
+  mark("references-last", refNum === null ? "no References section" : undefined);
+
   // Report
   if (report) {
     const width = Math.max(...checkRows.map((r) => r.id.length));

package/pipeline/scripts/validate-planning.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// validate-planning.mjs  -  runtime validator for Phase 2 planning output.
+// validate-planning.mjs  -  runtime validator for Phase 1 planning output.
 //
 // Phase 2 returns a task decomposition conforming to
 // pipeline/schemas/planning-output.schema.json. Phase 3 iterates over `tasks`

package/pipeline/scripts/validate-reviewer.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// validate-reviewer.mjs  -  runtime validator for Phase 4 reviewer subagent output.
+// validate-reviewer.mjs  -  runtime validator for Phase 3 reviewer subagent output.
 //
 // Each of the 3 parallel reviewers (Opus, GPT-5.4, Sonnet) must return an
 // object matching pipeline/schemas/reviewer-output.schema.json. This validator

package/pipeline/scripts/validate-state.mjs

@@ -14,7 +14,7 @@
 // actually make a resume unsafe:
 //   - the file does not parse (truncated / corrupt)
 //   - root is not an object
-//   - currentPhase is missing or out of the 0..7 range (resume keys on it)
+//   - currentPhase is missing or out of the 0..5 range (resume keys on it)
 //   - phases is present but not an object, or an entry is not an object
 // Phase status strings are NOT enum-checked: real writers use "completed"
 // alongside the schema's "done", and an odd status does not make a resume
@@ -66,9 +66,33 @@ async function main() {
     process.exit(1);
   }
 
+  // Which numbering this file was written under. v19.0.0 renumbered eight
+  // phases into six, and a run that finished at `currentPhase: 7` in October
+  // was correct when it was written - calling it invalid now would mark most
+  // of the log directory broken and teach the reader to ignore this validator.
+  // Same decision the metrics file got: label the generation, do not rewrite
+  // history. A file stamped 2.2.0 or later is generation 2 and bounded 0..5;
+  // anything older, including the unstamped files that predate stamping
+  // entirely, is generation 1 and bounded 0..7.
+  const GEN2_FROM = "2.2.0";
+  const cmpVersion = (a, b) => {
+    const pa = String(a).split(".").map(Number);
+    const pb = String(b).split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+      if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+    }
+    return 0;
+  };
+  const gen1 = !s.schemaVersion || cmpVersion(s.schemaVersion, GEN2_FROM) < 0;
+  const maxPhase = gen1 ? 7 : 5;
+  const phaseKey = gen1 ? /^[0-7]$/ : /^[0-5]$/;
+
   // currentPhase is the field resume keys on - it must be present and in range.
-  if (!Number.isInteger(s.currentPhase) || s.currentPhase < 0 || s.currentPhase > 7) {
-    errors.push(`currentPhase must be integer 0..7, got ${JSON.stringify(s.currentPhase)}`);
+  if (!Number.isInteger(s.currentPhase) || s.currentPhase < 0 || s.currentPhase > maxPhase) {
+    errors.push(
+      `currentPhase must be integer 0..${maxPhase}, got ${JSON.stringify(s.currentPhase)}` +
+        (gen1 ? " (generation 1 file: unstamped or schemaVersion < 2.2.0)" : ""),
+    );
   }
 
   // phases is optional (some early/aborted states omit it), but if present it
@@ -78,12 +102,28 @@ async function main() {
       errors.push("phases, when present, must be an object keyed by phase number");
     } else {
       for (const [k, v] of Object.entries(s.phases)) {
-        if (!/^[0-7]$/.test(k)) {
-          errors.push(`phases key invalid: "${k}" (expected "0".."7")`);
+        if (!phaseKey.test(k)) {
+          errors.push(`phases key invalid: "${k}" (expected "0".."${maxPhase}")`);
           continue;
         }
         if (typeof v !== "object" || v === null) {
           errors.push(`phases["${k}"] must be an object`);
+          continue;
+        }
+        // The rework cap. Every phase doc says "hard-kill at retryCount === 3"
+        // and the schema writes `maximum: 3`, but nothing read either: a fourth
+        // round produced a state that violates the schema and passed this
+        // validator, which is the one place that could have said so.
+        //
+        // What this does NOT do is stop the loop - that is the orchestrator's
+        // job and it stays prose. What it does is make an over-cap state fail
+        // instead of being carried forward as if it were fine.
+        if (v.retryCount !== undefined) {
+          if (!Number.isInteger(v.retryCount) || v.retryCount < 0 || v.retryCount > 3) {
+            errors.push(
+              `phases["${k}"].retryCount must be integer 0..3 (the rework cap), got ${JSON.stringify(v.retryCount)}`,
+            );
+          }
         }
       }
     }