From ad2679dc24299e420f2c157198e95584bf674838 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 04:17:12 +0200
Subject: [PATCH 01/15] fix(docs): upgrade CHANGELOG completeness check,
 backfill Unreleased
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

audit F-2: scanUnreleasedTruth's own gate fired only when [Unreleased]
was entirely empty, so a single unrelated doc-sync bullet satisfied
"meaningful content" forever — 13 real feat/fix commits since v1.28.4
went completely undocumented, and the gate never noticed.

- scanUnreleasedTruth now requires every post-tag feat|fix|perf commit
  to be individually referenced in [Unreleased], either by its
  trailing PR number (the mid-subject issue ref some commits also
  carry, e.g. "(#553) (#621)", is correctly ignored in favor of the
  true trailing PR number) or by a bounded subject-slug match (>=60%
  of its most identifying words) for the few commits merged without
  one. Missing commits are named in the failure output.
- Backfilled CHANGELOG.md's [Unreleased] with all 13 currently-
  undocumented commits since v1.28.4 (project schema-version
  classification Slices A/B, the canonical document-projection
  foundation, the legacy-to-v1 admission primitive, filesystem-
  admission convergence, i18n startup-copy fixes, PR-size governance
  hardening, the attribution guard, and this session's own PR-1
  security-doc fix).
- Pulled TODO.md's Current Sprint forward: the 5 landed ledger-row-9
  PRs are now named, still correctly marked not-complete (no target
  release invented — none exists yet).
- 6 new regression tests for the completeness logic; README
  test-count resynced.
---
 CHANGELOG.md                       | 56 +++++++++++++++++++
 README.md                          |  8 +--
 TODO.md                            | 18 +++++--
 scripts/check-doc-metrics.mjs      | 87 +++++++++++++++++++++++++++---
 tests/unit/checkDocMetrics.test.ts | 69 ++++++++++++++++++++++++
 5 files changed, 225 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9036b59cd..12fa4d6ff 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Project schema-version classification (Slice A, #553):** `PROJECT_SCHEMA_V1` as a fresh
+  production version marker, disjoint classification
+  (`LEGACY_UNVERSIONED`/`SUPPORTED_OLDER`/`UNSUPPORTED_OLDER`/`CURRENT`/`FUTURE`/`MALFORMED`),
+  raw/header parsing before typed parsing so a `FUTURE` document with a breaking shape still
+  classifies `FUTURE` rather than `MALFORMED`, and the `LEGACY_TO_V1` in-memory admission
+  primitive. PR #618.
+- **Schema-version classification observed on IDB project load (Slice B, 1/N, #553):** the first
+  ingress path wired to Slice A's classifiers, observation-only (classify and log, never alter
+  load behavior, never throw), matching the established Core shadow-validation pattern. PR #619.
+- **Canonical document projection foundation:** establishes the canonical parser/import/admission
+  boundary that retains the original JSON text alongside a bounded typed projection, the
+  foundation Slice C's admission primitive builds on.
+- **Explicit legacy-to-v1 admission primitive (#653):** the non-destructive `LEGACY_TO_V1`
+  in-memory admission path recognizes, fully validates, losslessly overlays the V1 version marker,
+  and revalidates the destination. PR #653.
+- **Filesystem admission converged after #654 (#658):** carries forward canonical filesystem
+  admission and closes legacy editable-admission authority gaps. PR #658.
+
+### Fixed
+
+- **`schemaVersion` now enforces raw integer grammar (#553):** rejects rounded fractional schema
+  versions and non-number schema-version tokens instead of silently coercing them. PR #621.
+- **Canonical document projection now reuses its own parsed input** instead of re-parsing,
+  removing a redundant-parse divergence risk between the raw and typed projections.
+- **Projection failure now retains the raw header verdict** instead of discarding the
+  already-classified version header when the typed projection itself fails.
+- **Unsupported-project startup copy added** alongside the existing migration-gap copy, so a
+  project whose schema version this build cannot open at all gets its own distinct startup
+  message rather than reusing the migration-gap wording.
+- **Migration-gap startup copy now distinguished from the unsupported-project case (#656):** the
+  two failure classes previously shared wording; each now gets copy specific to its actual cause.
+  PR #656.
+- **PR-size exception governance hardened (#657):** closes control gaps in how per-PR size-ceiling
+  exceptions are recorded and validated. PR #657.
+- **Security docs no longer cite closed PR #356 as active desktop-encryption remediation:**
+  `docs/SECURITY-THREAT-MODEL.md` and `docs/IDB-ENCRYPTION.md` both asserted PR #356 was the
+  active/pending remediation for desktop plaintext storage after it was closed as superseded on
+  2026-08-18. Rewritten to anchor on the living Ledger-row-9/R-15 state instead of a PR number, and
+  `check-doc-metrics.mjs` now mechanically rejects an unqualified live/pending-remediation claim
+  tied to a bare PR number in these two files. PR #673.
+- **CHANGELOG completeness-check upgrade, backfill Unreleased (audit F-2):** `scanUnreleasedTruth`
+  previously accepted any non-empty `[Unreleased]` section forever, so a single unrelated bullet
+  let arbitrarily many later `feat`/`fix`/`perf` commits go completely undocumented — 13 real
+  commits since `v1.28.4` had gone unrecorded. It now requires every governed commit to be
+  individually referenced by PR number or subject slug, naming any that aren't; this section was
+  backfilled with all 13 currently-undocumented entries above.
+
+### Security
+
+- **AI/session attribution now rejected in commits and PRs:** a fail-closed guard
+  (`check-commit-attribution.mjs`, a commit-msg hook, a pre-push scan of outgoing commits, and a
+  CI check on the commit range and PR title/body) blocks Claude/Anthropic attribution trailers,
+  session URLs, and generated-by footers before they can land in repository history. PR #672.
+
 ### Documentation
 
 - **Post-release v1.28.4 truth sync:** removed the now-stale release-candidate markers from
diff --git a/README.md b/README.md
index 381806a19..11eb7a6fb 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7593%2B_%2F_603_files-22C55E" alt="7593+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7599%2B_%2F_603_files-22C55E" alt="7599+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7593+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7599+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7593+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7599+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7593+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7599+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/TODO.md b/TODO.md
index be2beae0b..0d12e63ff 100644
--- a/TODO.md
+++ b/TODO.md
@@ -35,9 +35,21 @@ Status: 🔄 in progress | ⬜ open | ✅ done
   `TODO.md`/`README.md` reconciled, `v1.28.4` tag and GitHub Release published with all expected
   Desktop artifacts; post-merge main CI and CodeQL green (CodeQL has no tag trigger), tag-triggered
   CI/Tauri/Docker all green, and `AUDIT.md` updated with real evidence.
-- ⬜ Close the outstanding Wave 2 prerequisite (ledger row 9: project state-shape compatibility
-  adapter) — currently in progress, not complete. Wave 3/4 R-15 implementation stays blocked
-  (`S5_IMPLEMENTATION_READY=NO`) until this and `S5_TERMINAL=YES` are both true.
+- ✅ Attribution-hygiene guard merged (PR #672): fail-closed rejection of AI/session attribution
+  trailers and footers in commits, tags, and PR titles/bodies (commit-msg hook, pre-push scan, CI).
+- ✅ Post-audit truth/governance remediation PR #673 merged: stale `#356`-active-remediation
+  citations in `docs/SECURITY-THREAT-MODEL.md`/`docs/IDB-ENCRYPTION.md` rewritten to anchor on the
+  living ledger state, with a mechanical `check-doc-metrics.mjs` guard against recurrence (first
+  slice of the 2026-09-08 external audit's S1–S10 remediation sequence; further slices in progress).
+- 🔄 Ledger row 9 (project state-shape compatibility adapter) — five `feat`/`fix` PRs landed
+  (#618 Slice A persisted schema-version classification, #619 Slice B IDB-load observation, #621
+  raw-integer-grammar hardening, #653 the non-destructive `LEGACY_TO_V1` admission primitive, #658
+  filesystem-admission convergence) but **still not complete**: durable source-generation fencing,
+  writer integration, and universal ingress/egress remain open per
+  `docs/native/CORE-MIGRATION-LEDGER.md` row 9. Wave 3/4 R-15 implementation stays blocked
+  (`S5_IMPLEMENTATION_READY=NO`, recorded on row 10) until row 9 and `S5_TERMINAL=YES` are both
+  true — no target release is set for that yet (tracked, not invented; see the S1–S10 remediation
+  plan's exit-criterion work).
 - ⬜ #614 (narrow concurrent-first-install multi-tab race, requires cross-tab coordination) and
   #532 (WelcomePortal E2E entry nondeterminism root cause) remain open, tracked separately —
   not part of this sprint unless they directly block release or R-15 work.
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index 7bd124321..77dd541e2 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -330,19 +330,84 @@ export function scanReadmeReleaseTruth(readme, taggedVersions) {
   return findings;
 }
 
-function hasMeaningfulUnreleasedContent(changelog) {
+// QNBS-v3 (audit F-2): shared by the presence check below and the completeness check further
+// down — both need the raw [Unreleased] section text with HTML comments stripped.
+function getUnreleasedSectionText(changelog) {
   const heading = /^## \[Unreleased\]\s*$/m.exec(changelog);
-  if (!heading) return false;
+  if (!heading) return '';
   const afterHeading = changelog.slice(heading.index + heading[0].length);
   const nextHeading = afterHeading.search(/^##\s/m);
   const section = nextHeading === -1 ? afterHeading : afterHeading.slice(0, nextHeading);
-  const withoutHtmlComments = section.replace(/<!--[\s\S]*?(?:-->|$)/g, '');
-  return withoutHtmlComments.split('\n').some((line) => {
+  return section.replace(/<!--[\s\S]*?(?:-->|$)/g, '');
+}
+
+function hasMeaningfulUnreleasedContent(changelog) {
+  const section = getUnreleasedSectionText(changelog);
+  return section.split('\n').some((line) => {
     const trimmed = line.trim();
     return trimmed.length > 0 && !trimmed.startsWith('<!--') && !trimmed.startsWith('###');
   });
 }
 
+// QNBS-v3 (audit F-2): a single doc-sync bullet previously satisfied hasMeaningfulUnreleasedContent
+// forever, letting arbitrarily many later feat/fix/perf commits go undocumented — the exact gap
+// this audit found (13 of 13 real post-tag commits undocumented). Governed commits must each be
+// referenced by PR number OR a recognizable subject slug, not merely "some content exists."
+const GOVERNED_COMMIT_TYPE = /^(?:feat|fix|perf)(?:\([^)]*\))?!?:\s*/i;
+const TRAILING_PR_REF = /\(#(\d+)\)\s*$/;
+const SLUG_STOP_WORDS = new Set([
+  'the',
+  'a',
+  'an',
+  'and',
+  'or',
+  'of',
+  'to',
+  'in',
+  'on',
+  'for',
+  'with',
+  'from',
+  'at',
+  'by',
+  'is',
+  'are',
+  'this',
+  'that',
+  'not',
+]);
+// QNBS-v3: a commit not merged via the standard squash flow (no trailing "(#NNN)") has nothing to
+// key off but its own wording — require most of a bounded set of its most identifying words to
+// appear in [Unreleased], rather than an exact-sentence match this file's other scanners avoid.
+const SLUG_WORD_COUNT = 6;
+const SLUG_MATCH_RATIO = 0.6;
+
+function significantSlugWords(description) {
+  return description
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter((word) => word.length > 2 && !SLUG_STOP_WORDS.has(word))
+    .slice(0, SLUG_WORD_COUNT);
+}
+
+function isReferencedInUnreleased(subject, unreleasedSection) {
+  const prMatch = TRAILING_PR_REF.exec(subject);
+  if (prMatch && unreleasedSection.includes(`#${prMatch[1]}`)) return true;
+  const description = subject.replace(GOVERNED_COMMIT_TYPE, '').replace(TRAILING_PR_REF, '');
+  const words = significantSlugWords(description);
+  if (words.length === 0) return false;
+  const matched = words.filter((word) => new RegExp(`\\b${word}\\b`, 'i').test(unreleasedSection));
+  return matched.length / words.length >= SLUG_MATCH_RATIO;
+}
+
+function findUndocumentedGovernedCommits(postReleaseCommitSubjects, unreleasedSection) {
+  return postReleaseCommitSubjects.filter(
+    (subject) =>
+      GOVERNED_COMMIT_TYPE.test(subject) && !isReferencedInUnreleased(subject, unreleasedSection),
+  );
+}
+
 /**
  * Return post-release commit subjects when the checkout has enough history to answer reliably.
  * A tagless or shallow checkout intentionally returns null, so CI does not turn missing history
@@ -388,9 +453,19 @@ export function scanUnreleasedTruth(
     semverCompare(candidateVersion, latestTagged) > 0;
   // QNBS-v3: only the current untagged release candidate may defer Unreleased history until merge-time tagging.
   if (isActiveUntaggedCandidate) return [];
-  if (hasMeaningfulUnreleasedContent(changelog)) return [];
+  if (!hasMeaningfulUnreleasedContent(changelog)) {
+    return [
+      `CHANGELOG.md — ${postReleaseCommitSubjects.length} commit(s) exist after the latest release tag, but [Unreleased] is empty`,
+    ];
+  }
+  const unreleasedSection = getUnreleasedSectionText(changelog);
+  const undocumented = findUndocumentedGovernedCommits(
+    postReleaseCommitSubjects,
+    unreleasedSection,
+  );
+  if (undocumented.length === 0) return [];
   return [
-    `CHANGELOG.md — ${postReleaseCommitSubjects.length} commit(s) exist after the latest release tag, but [Unreleased] is empty`,
+    `CHANGELOG.md — [Unreleased] does not reference ${undocumented.length} post-tag feat/fix/perf commit(s) by PR number or subject: ${undocumented.map((s) => `"${s}"`).join('; ')}`,
   ];
 }
 
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index 0984a7fe7..9dde86b43 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -287,6 +287,75 @@ describe('Unreleased truth', () => {
       ]),
     ).toEqual([expect.stringContaining('[Unreleased] is empty')]);
   });
+
+  // QNBS-v3 (audit F-2): the actual bug this section exists to catch — a single unrelated doc-sync
+  // bullet previously satisfied "meaningful content" forever, so a real feat/fix commit could go
+  // completely undocumented while docs:check stayed green. Completeness must be checked per commit.
+  describe('completeness — every governed commit must be individually referenced', () => {
+    const populatedButUnrelated = '## [Unreleased]\n\n### Documentation\n\n- Unrelated doc sync.\n';
+
+    it('rejects a governed commit referenced by neither PR number nor subject slug', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const findings = scanUnreleasedTruth(populatedButUnrelated, [
+        'fix(project): retain raw header verdict on projection failure',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('does not reference 1 post-tag feat/fix/perf commit');
+      expect(findings[0]).toContain('retain raw header verdict');
+    });
+
+    it('accepts a governed commit referenced by its trailing PR number', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Something about migration-gap copy. PR #656.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(i18n): distinguish migration-gap startup copy (#656)',
+      ]);
+      expect(findings).toEqual([]);
+    });
+
+    it('extracts the TRAILING PR number, not a mid-subject issue reference', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      // QNBS-v3: real house style embeds an issue ref mid-subject ("(#553)") before the actual
+      // trailing squash-merge PR number ("(#621)") — referencing only the issue number must NOT
+      // satisfy the check for the PR.
+      const changelog = '## [Unreleased]\n\n### Fixed\n\n- Closes #553 eventually.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): enforce raw schemaVersion integer grammar (#553) (#621)',
+      ]);
+      expect(findings).toHaveLength(1);
+    });
+
+    it('accepts a governed commit with no PR number, referenced by subject slug', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Canonical document projection now reuses parsed input.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): reuse parsed canonical document input',
+      ]);
+      expect(findings).toEqual([]);
+    });
+
+    it('does not require build/chore/docs commits to be individually referenced', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const findings = scanUnreleasedTruth(populatedButUnrelated, [
+        'build(deps): bump some-package from 1.0.0 to 1.0.1 (#700)',
+        'chore(agent): unrelated housekeeping',
+        'docs: unrelated doc update',
+      ]);
+      expect(findings).toEqual([]);
+    });
+
+    it('lists every undocumented governed commit, not just the first', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const findings = scanUnreleasedTruth(populatedButUnrelated, [
+        'feat(project): establish canonical document projection foundation',
+        'fix(project): reuse parsed canonical document input',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('does not reference 2 post-tag feat/fix/perf commit');
+    });
+  });
 });
 
 describe('getTaggedVersions', () => {

From d2e08235e3ea5003c190588cf8cdd6f069d14c66 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 04:54:26 +0200
Subject: [PATCH 02/15] fix(docs): address review findings on the
 completeness-check upgrade
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- PR-number matching used a bare String.includes, so "#65" could
  incorrectly satisfy "#656" and vice versa. Now requires a non-digit
  boundary on both sides.
- Subject-slug matching now runs per Markdown entry (bullet, including
  wrapped continuation lines) instead of against the whole [Unreleased]
  section — words scattered across unrelated bullets could otherwise
  collectively satisfy a commit none of them documents, and one
  generic bullet could simultaneously "document" multiple different
  undocumented commits.
- P1: full per-commit completeness is now enforced only outside
  pull_request CI context. A pull_request run's git-log range
  enumerates every commit unique to that branch, not the one commit
  that will actually exist after squash-merge — a routine review-fix
  follow-up commit can't reference itself in [Unreleased] in advance.
  The section-non-empty check still applies in pull_request context;
  full completeness is enforced locally and on push to main right
  after merge.
- 8 new regression tests; GITHUB_EVENT_NAME declared in turbo.json;
  README test-count resynced.
---
 CHANGELOG.md                       |  8 ++-
 README.md                          |  8 +--
 scripts/check-doc-metrics.d.mts    |  1 +
 scripts/check-doc-metrics.mjs      | 58 +++++++++++++++++++--
 tests/unit/checkDocMetrics.test.ts | 81 ++++++++++++++++++++++++++++++
 turbo.json                         |  1 +
 6 files changed, 147 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 12fa4d6ff..bb455687d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,7 +54,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   let arbitrarily many later `feat`/`fix`/`perf` commits go completely undocumented — 13 real
   commits since `v1.28.4` had gone unrecorded. It now requires every governed commit to be
   individually referenced by PR number or subject slug, naming any that aren't; this section was
-  backfilled with all 13 currently-undocumented entries above.
+  backfilled with all 13 currently-undocumented entries above. Review findings addressed on this
+  same upgrade: PR-number matching now requires a non-digit boundary (a bare substring check let
+  `#65` satisfy `#656`), subject-slug matching is now scoped to one changelog entry at a time
+  instead of the whole section, and full per-commit completeness is enforced only outside
+  `pull_request` CI context — a PR's own git-log range enumerates every commit unique to that
+  branch, not the one commit that will exist after squash-merge, so a review-fix follow-up commit
+  can't reference itself in advance.
 
 ### Security
 
diff --git a/README.md b/README.md
index 11eb7a6fb..aa2e3923b 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7599%2B_%2F_603_files-22C55E" alt="7599+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7605%2B_%2F_603_files-22C55E" alt="7605+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7599+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7605+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7599+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7605+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7599+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7605+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/scripts/check-doc-metrics.d.mts b/scripts/check-doc-metrics.d.mts
index d446ca8c5..3ef74a93c 100644
--- a/scripts/check-doc-metrics.d.mts
+++ b/scripts/check-doc-metrics.d.mts
@@ -17,6 +17,7 @@ export function scanUnreleasedTruth(
   postReleaseCommitSubjects: string[] | null,
   packageVersion?: string,
   taggedVersions?: Set<string>,
+  isPullRequestContext?: boolean,
 ): string[];
 export function scanForDrift(
   content: string,
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index 77dd541e2..d88c3da82 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -391,20 +391,60 @@ function significantSlugWords(description) {
     .slice(0, SLUG_WORD_COUNT);
 }
 
-function isReferencedInUnreleased(subject, unreleasedSection) {
+// QNBS-v3 (coderabbit/CodeAnt): a bare String.includes let "#65" incorrectly satisfy a check for
+// "#656" (and vice versa) since one is a substring of the other — require a non-digit boundary on
+// both sides so only the exact PR number counts.
+function isReferencedByPrNumber(subject, unreleasedSection) {
   const prMatch = TRAILING_PR_REF.exec(subject);
-  if (prMatch && unreleasedSection.includes(`#${prMatch[1]}`)) return true;
+  if (!prMatch) return false;
+  return new RegExp(`(?:^|\\D)#${prMatch[1]}(?!\\d)`).test(unreleasedSection);
+}
+
+// QNBS-v3 (codex): match ratio is computed PER changelog entry, not against the whole section —
+// otherwise words scattered across several unrelated bullets could collectively satisfy the
+// threshold for a commit none of them actually documents, and one generic bullet could
+// simultaneously "document" multiple different undocumented commits.
+function isReferencedBySlug(subject, unreleasedEntries) {
   const description = subject.replace(GOVERNED_COMMIT_TYPE, '').replace(TRAILING_PR_REF, '');
   const words = significantSlugWords(description);
   if (words.length === 0) return false;
-  const matched = words.filter((word) => new RegExp(`\\b${word}\\b`, 'i').test(unreleasedSection));
-  return matched.length / words.length >= SLUG_MATCH_RATIO;
+  return unreleasedEntries.some((entry) => {
+    const matched = words.filter((word) => new RegExp(`\\b${word}\\b`, 'i').test(entry));
+    return matched.length / words.length >= SLUG_MATCH_RATIO;
+  });
+}
+
+// QNBS-v3: a Markdown bullet may wrap across several physical lines — join a bullet's own
+// continuation lines into one entry so slug-matching sees the whole thought, not a fragment.
+function splitUnreleasedEntries(unreleasedSection) {
+  const entries = [];
+  let current = [];
+  const flush = () => {
+    if (current.length > 0) entries.push(current.join(' '));
+    current = [];
+  };
+  for (const rawLine of unreleasedSection.split('\n')) {
+    const line = rawLine.trim();
+    if (/^-\s/.test(line)) {
+      flush();
+      current.push(line);
+    } else if (current.length > 0 && line !== '') {
+      current.push(line);
+    } else if (line === '') {
+      flush();
+    }
+  }
+  flush();
+  return entries;
 }
 
 function findUndocumentedGovernedCommits(postReleaseCommitSubjects, unreleasedSection) {
+  const entries = splitUnreleasedEntries(unreleasedSection);
   return postReleaseCommitSubjects.filter(
     (subject) =>
-      GOVERNED_COMMIT_TYPE.test(subject) && !isReferencedInUnreleased(subject, unreleasedSection),
+      GOVERNED_COMMIT_TYPE.test(subject) &&
+      !isReferencedByPrNumber(subject, unreleasedSection) &&
+      !isReferencedBySlug(subject, entries),
   );
 }
 
@@ -437,6 +477,7 @@ export function scanUnreleasedTruth(
   postReleaseCommitSubjects,
   packageVersion,
   taggedVersions,
+  isPullRequestContext = process.env.GITHUB_EVENT_NAME === 'pull_request',
 ) {
   if (!postReleaseCommitSubjects || postReleaseCommitSubjects.length === 0) return [];
   const candidateVersion = changelog.match(
@@ -458,6 +499,13 @@ export function scanUnreleasedTruth(
       `CHANGELOG.md — ${postReleaseCommitSubjects.length} commit(s) exist after the latest release tag, but [Unreleased] is empty`,
     ];
   }
+  // QNBS-v3 (codex, P1): a pull_request CI run's `git log` range enumerates every commit unique
+  // to that branch — not the one commit that will actually exist after squash-merge. Enforcing
+  // full per-commit completeness there would make a routine review-fix follow-up commit
+  // unsatisfiable (it cannot reference itself in [Unreleased] in advance). Completeness is
+  // enforced once those commits are real, permanent history: on the push to main right after
+  // merge (and locally, since a developer isn't fighting the multi-commit-per-PR shape there).
+  if (isPullRequestContext) return [];
   const unreleasedSection = getUnreleasedSectionText(changelog);
   const undocumented = findUndocumentedGovernedCommits(
     postReleaseCommitSubjects,
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index 9dde86b43..17102e147 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -30,6 +30,7 @@ type ReleaseTruthModule = {
     subjects: string[] | null,
     packageVersion?: string,
     taggedVersions?: Set<string>,
+    isPullRequestContext?: boolean,
   ) => string[];
 };
 // QNBS-v3: load the runtime-only scanners without making tsgo infer untyped .mjs exports.
@@ -355,6 +356,86 @@ describe('Unreleased truth', () => {
       expect(findings).toHaveLength(1);
       expect(findings[0]).toContain('does not reference 2 post-tag feat/fix/perf commit');
     });
+
+    // QNBS-v3 (coderabbit/CodeAnt): "#65" is a substring of "#656" — a naive String.includes
+    // check let a shorter/longer PR number incorrectly satisfy a completely different one.
+    it('does not let a shorter PR number satisfy a longer one that contains it as a substring', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog = '## [Unreleased]\n\n### Fixed\n\n- Something unrelated. PR #6567.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(i18n): distinguish migration-gap startup copy (#656)',
+      ]);
+      expect(findings).toHaveLength(1);
+    });
+
+    it('does not let a longer PR number satisfy a shorter one it contains as a substring', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog = '## [Unreleased]\n\n### Fixed\n\n- Something unrelated. PR #65.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(i18n): distinguish migration-gap startup copy (#656)',
+      ]);
+      expect(findings).toHaveLength(1);
+    });
+
+    // QNBS-v3 (codex): matching must be scoped to ONE changelog entry — words scattered across
+    // several unrelated bullets must not collectively satisfy a commit none of them documents,
+    // and one bullet's generic words must not simultaneously "document" multiple commits.
+    it('does not let slug words scattered across separate unrelated bullets satisfy a commit', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog = [
+        '## [Unreleased]',
+        '',
+        '### Fixed',
+        '',
+        '- Something about canonical naming conventions.',
+        '- A separate change involving document upload limits.',
+        '- Another unrelated projection-mapping utility update.',
+      ].join('\n');
+      const findings = scanUnreleasedTruth(changelog, [
+        'feat(project): establish canonical document projection foundation',
+      ]);
+      expect(findings).toHaveLength(1);
+    });
+
+    it('does not let one generic bullet satisfy multiple different undocumented commits', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog = '## [Unreleased]\n\n### Fixed\n\n- A change involving canonical data.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'feat(project): establish canonical document projection foundation',
+        'fix(project): reuse parsed canonical document input',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('does not reference 2 post-tag feat/fix/perf commit');
+    });
+
+    // QNBS-v3 (codex, P1): a pull_request CI run's git-log range enumerates every commit unique
+    // to that branch, not the one commit that will exist after squash-merge — a routine
+    // review-fix follow-up commit can't reference itself in [Unreleased] in advance. Full
+    // completeness is enforced only outside pull_request context (locally, and on push to main
+    // right after merge).
+    it('does not enforce per-commit completeness in pull_request CI context', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const findings = scanUnreleasedTruth(
+        populatedButUnrelated,
+        ['fix(project): retain raw header verdict on projection failure'],
+        undefined,
+        undefined,
+        true,
+      );
+      expect(findings).toEqual([]);
+    });
+
+    it('still rejects a completely empty [Unreleased] in pull_request CI context', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const findings = scanUnreleasedTruth(
+        '## [Unreleased]\n\n### Added\n',
+        ['fix(project): retain raw header verdict on projection failure'],
+        undefined,
+        undefined,
+        true,
+      );
+      expect(findings).toEqual([expect.stringContaining('[Unreleased] is empty')]);
+    });
   });
 });
 
diff --git a/turbo.json b/turbo.json
index f33e6e619..ebb0bf57a 100644
--- a/turbo.json
+++ b/turbo.json
@@ -11,6 +11,7 @@
     "CLOUDFLARE_PAGES_PROJECT",
     "DEPLOY_TARGET",
     "DEV",
+    "GITHUB_EVENT_NAME",
     "GRAPHIFY_SKIP",
     "PLAYWRIGHT_REUSE_SERVER",
     "PLAYWRIGHT_SKIP_VRT",

From 418feca4bfd96970c471a24be476f513b20503d7 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 05:21:34 +0200
Subject: [PATCH 03/15] fix(ci): stop scanUnreleasedTruth from reading
 GITHUB_EVENT_NAME as its own default

The isPullRequestContext parameter defaulted to reading
process.env.GITHUB_EVENT_NAME directly. That env var is set by GitHub
Actions for the WHOLE workflow run, not just this gate's own CLI
step -- so when the full Vitest suite ran inside this PR's own
pull_request-triggered Quality Gate job, every test that didn't
explicitly pass isPullRequestContext silently got the lenient
(GITHUB_EVENT_NAME=pull_request) default instead of the intended
deterministic one, failing 7 tests that expected the strict path.

The pure function's default is now a hardcoded false; only main()'s
real CLI invocation reads the actual environment. Verified locally by
simulating the exact failure with GITHUB_EVENT_NAME=pull_request
pnpm exec vitest run -- reproduced the same 7 failures before this
fix, all pass after it.
---
 CHANGELOG.md                  | 6 +++++-
 scripts/check-doc-metrics.mjs | 9 ++++++++-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bb455687d..277a31133 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -60,7 +60,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   instead of the whole section, and full per-commit completeness is enforced only outside
   `pull_request` CI context — a PR's own git-log range enumerates every commit unique to that
   branch, not the one commit that will exist after squash-merge, so a review-fix follow-up commit
-  can't reference itself in advance.
+  can't reference itself in advance. Stop reading the GitHub event name (`GITHUB_EVENT_NAME`) as
+  that `pull_request`-context check's own default: the same environment variable is ambiently
+  visible to the Vitest process too when the whole suite runs inside a `pull_request`-triggered
+  job — the pure function's default is now hardcoded `false`; only the real CLI invocation reads
+  the actual environment.
 
 ### Security
 
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index d88c3da82..1e3cd6f55 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -472,12 +472,18 @@ export function getPostReleaseCommitSubjects(repositoryRoot = root) {
   }
 }
 
+// QNBS-v3: deliberately NOT defaulted from process.env here — this same env var is ambiently
+// visible to the Vitest process itself when the whole suite runs inside a GitHub Actions
+// pull_request-triggered job (not just this gate's own CLI step), so a default read at this
+// pure-function boundary silently changed every test's behavior based on which CI context ran
+// it. Only main()'s real CLI invocation below reads the actual environment; tests always get a
+// deterministic, explicitly-passed value.
 export function scanUnreleasedTruth(
   changelog,
   postReleaseCommitSubjects,
   packageVersion,
   taggedVersions,
-  isPullRequestContext = process.env.GITHUB_EVENT_NAME === 'pull_request',
+  isPullRequestContext = false,
 ) {
   if (!postReleaseCommitSubjects || postReleaseCommitSubjects.length === 0) return [];
   const candidateVersion = changelog.match(
@@ -858,6 +864,7 @@ function main() {
       getPostReleaseCommitSubjects(),
       packageVersion,
       taggedVersions,
+      process.env.GITHUB_EVENT_NAME === 'pull_request',
     ),
   );
   allFindings.push(

From 4f5e7e000a619be89343a0200cd643c2312e6bb9 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 06:10:37 +0200
Subject: [PATCH 04/15] fix(docs): address 2nd review wave on the
 completeness-check upgrade

- P1: the pull_request-context exemption previously skipped strict
  enforcement for EVERY governed commit. Now only an un-numbered
  commit is exempted -- an already-numbered commit sitting in the
  same range from a separate, already-merged PR stays fully enforced
  even during a pull_request run.
- Renamed isPullRequestContext to isFeatureBranchContext and added
  isOnFeatureBranch(): the mandatory local `pnpm run ci:prepush` hook
  invokes this checker with no GitHub Actions event context at all, so
  GITHUB_EVENT_NAME alone left every local review-fix commit strictly
  enforced and unsatisfiable in advance. Checking the actual git
  branch (not just the CI event) means the same exemption now applies
  locally too, on the same reasoning: HEAD not being `main` is what
  actually distinguishes "not yet permanent history" in both contexts.
- A matched changelog entry is now claimed and excluded from later
  commits in the same pass, so one generic bullet can't simultaneously
  "document" multiple different undocumented commits -- verified with
  a case specific enough that both commits would clear the 60%
  threshold alone.
- A commit ending in a trailing PR number now requires that exact
  number; it no longer falls back to a slug match that could hit a
  different, older, unrelated bullet.
- ci.yml's Quality Gate checkout gains fetch-depth: 0 alongside its
  existing fetch-tags: true -- the latter makes a tag ref resolvable
  but doesn't deepen the commit graph, so `git log v<tag>..HEAD` could
  fail or truncate on a shallow checkout, which getPostReleaseCommitSubjects()
  would silently treat as "no history" and skip the whole completeness
  check without ever reporting a failure. Unverifiable from existing
  CI history until this PR's own post-merge push (no push-to-main run
  had exercised the new completeness logic yet) -- applied as a
  correctness fix regardless of prior symptoms.
- My own earlier three CHANGELOG bullets for this feature had drifted
  into exactly the "one bullet documents multiple commits" shape the
  exclusive-claiming fix above now rejects -- restructured into
  separate, distinct bullets.
- 9 new regression tests (exclusive claiming, exact-PR-number
  requirement, un-numbered-vs-numbered PR-context enforcement,
  isOnFeatureBranch against real git repos); README test-count resynced.
---
 .github/workflows/ci.yml           |   8 +-
 CHANGELOG.md                       |  27 ++++---
 README.md                          |   8 +-
 scripts/check-doc-metrics.d.mts    |   2 +-
 scripts/check-doc-metrics.mjs      | 123 +++++++++++++++++++----------
 tests/unit/checkDocMetrics.test.ts | 110 ++++++++++++++++++++++++--
 6 files changed, 215 insertions(+), 63 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a54c74c24..2cd778df9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -298,11 +298,17 @@ jobs:
         node-version: ['22', '24']
     steps:
       # QNBS-v3: fetch-tags — check-doc-metrics.mjs's stale-PLANNED-status check reads `git tag`
-      # and silently no-ops without one; a default shallow checkout has no tags at all.
+      # and silently no-ops without one; a default shallow checkout has no tags at all. fetch-depth:
+      # 0 (full history) is additionally required by scanUnreleasedTruth's completeness check
+      # (audit F-2): fetch-tags alone makes the tag ref resolvable but does not deepen the commit
+      # graph, so `git log v<tag>..HEAD` could still fail or truncate on a shallow checkout — which
+      # getPostReleaseCommitSubjects() would silently treat as "no history" and skip the entire
+      # check, defeating it without ever reporting a failure.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-tags: true
+          fetch-depth: 0
       - uses: ./.github/actions/setup
         with:
           node-version: ${{ matrix.node-version }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 277a31133..cdb9cab92 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,17 +54,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   let arbitrarily many later `feat`/`fix`/`perf` commits go completely undocumented — 13 real
   commits since `v1.28.4` had gone unrecorded. It now requires every governed commit to be
   individually referenced by PR number or subject slug, naming any that aren't; this section was
-  backfilled with all 13 currently-undocumented entries above. Review findings addressed on this
-  same upgrade: PR-number matching now requires a non-digit boundary (a bare substring check let
-  `#65` satisfy `#656`), subject-slug matching is now scoped to one changelog entry at a time
-  instead of the whole section, and full per-commit completeness is enforced only outside
-  `pull_request` CI context — a PR's own git-log range enumerates every commit unique to that
-  branch, not the one commit that will exist after squash-merge, so a review-fix follow-up commit
-  can't reference itself in advance. Stop reading the GitHub event name (`GITHUB_EVENT_NAME`) as
-  that `pull_request`-context check's own default: the same environment variable is ambiently
-  visible to the Vitest process too when the whole suite runs inside a `pull_request`-triggered
-  job — the pure function's default is now hardcoded `false`; only the real CLI invocation reads
-  the actual environment.
+  backfilled with all 13 currently-undocumented entries above.
+- **Completeness-check review findings addressed:** PR-number matching now requires a non-digit
+  boundary (a bare substring check let `#65` satisfy `#656`), subject-slug matching is scoped to
+  one changelog entry at a time instead of the whole section, each matched entry is claimed so one
+  generic bullet can't simultaneously "document" multiple different commits, a numbered commit now
+  requires its exact PR number rather than ever falling back to a slug match, and full per-commit
+  completeness is enforced only outside `pull_request` CI context (an un-numbered commit there is
+  exempted — a PR's own git-log range enumerates every commit unique to that branch, not the one
+  commit that will exist after squash-merge, so a review-fix follow-up commit can't reference
+  itself in advance — while an already-numbered commit from a separate, already-merged PR sitting
+  in the same range stays fully enforced).
+- **Stop reading the GitHub event name as the completeness check's own default:** the
+  `pull_request`-context parameter defaulted to reading `GITHUB_EVENT_NAME` directly, but that
+  environment variable is ambiently visible to the Vitest test process too when the whole suite
+  runs inside a `pull_request`-triggered job — the pure function's default is now hardcoded
+  `false`; only the real CLI invocation reads the actual environment.
 
 ### Security
 
diff --git a/README.md b/README.md
index aa2e3923b..20bbcf2a6 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7605%2B_%2F_603_files-22C55E" alt="7605+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7611%2B_%2F_603_files-22C55E" alt="7611+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7605+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7611+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7605+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7611+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7605+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7611+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/scripts/check-doc-metrics.d.mts b/scripts/check-doc-metrics.d.mts
index 3ef74a93c..7e37ebd03 100644
--- a/scripts/check-doc-metrics.d.mts
+++ b/scripts/check-doc-metrics.d.mts
@@ -17,7 +17,7 @@ export function scanUnreleasedTruth(
   postReleaseCommitSubjects: string[] | null,
   packageVersion?: string,
   taggedVersions?: Set<string>,
-  isPullRequestContext?: boolean,
+  isFeatureBranchContext?: boolean,
 ): string[];
 export function scanForDrift(
   content: string,
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index 1e3cd6f55..68ce04416 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -394,27 +394,11 @@ function significantSlugWords(description) {
 // QNBS-v3 (coderabbit/CodeAnt): a bare String.includes let "#65" incorrectly satisfy a check for
 // "#656" (and vice versa) since one is a substring of the other — require a non-digit boundary on
 // both sides so only the exact PR number counts.
-function isReferencedByPrNumber(subject, unreleasedSection) {
-  const prMatch = TRAILING_PR_REF.exec(subject);
-  if (!prMatch) return false;
-  return new RegExp(`(?:^|\\D)#${prMatch[1]}(?!\\d)`).test(unreleasedSection);
-}
-
-// QNBS-v3 (codex): match ratio is computed PER changelog entry, not against the whole section —
-// otherwise words scattered across several unrelated bullets could collectively satisfy the
-// threshold for a commit none of them actually documents, and one generic bullet could
-// simultaneously "document" multiple different undocumented commits.
-function isReferencedBySlug(subject, unreleasedEntries) {
-  const description = subject.replace(GOVERNED_COMMIT_TYPE, '').replace(TRAILING_PR_REF, '');
-  const words = significantSlugWords(description);
-  if (words.length === 0) return false;
-  return unreleasedEntries.some((entry) => {
-    const matched = words.filter((word) => new RegExp(`\\b${word}\\b`, 'i').test(entry));
-    return matched.length / words.length >= SLUG_MATCH_RATIO;
-  });
+function isReferencedByPrNumber(prNumber, unreleasedSection) {
+  return new RegExp(`(?:^|\\D)#${prNumber}(?!\\d)`).test(unreleasedSection);
 }
 
-// QNBS-v3: a Markdown bullet may wrap across several physical lines — join a bullet's own
+// QNBS-v3 (codex): a Markdown bullet may wrap across several physical lines — join a bullet's own
 // continuation lines into one entry so slug-matching sees the whole thought, not a fragment.
 function splitUnreleasedEntries(unreleasedSection) {
   const entries = [];
@@ -438,14 +422,56 @@ function splitUnreleasedEntries(unreleasedSection) {
   return entries;
 }
 
-function findUndocumentedGovernedCommits(postReleaseCommitSubjects, unreleasedSection) {
+// QNBS-v3 (codex): match ratio is computed PER changelog entry, and a matched entry is then
+// claimed (excluded from later commits in the same pass) — otherwise words scattered across
+// several unrelated bullets could collectively satisfy a commit none of them documents, AND one
+// generic bullet could simultaneously "document" multiple different undocumented commits.
+function findSlugMatchIndex(subject, unreleasedEntries, claimedIndices) {
+  const description = subject.replace(GOVERNED_COMMIT_TYPE, '').replace(TRAILING_PR_REF, '');
+  const words = significantSlugWords(description);
+  if (words.length === 0) return -1;
+  return unreleasedEntries.findIndex((entry, index) => {
+    if (claimedIndices.has(index)) return false;
+    const matched = words.filter((word) => new RegExp(`\\b${word}\\b`, 'i').test(entry));
+    return matched.length / words.length >= SLUG_MATCH_RATIO;
+  });
+}
+
+// QNBS-v3 (codex): a commit ending in a trailing PR number has an unambiguous way to be
+// referenced — require the exact number, never fall back to a fuzzy slug match that could match a
+// different, older bullet purely by generic word overlap.
+function isCommitDocumented(subject, unreleasedSection, entries, claimedIndices) {
+  const prMatch = TRAILING_PR_REF.exec(subject);
+  if (prMatch) return isReferencedByPrNumber(prMatch[1], unreleasedSection);
+  const matchIndex = findSlugMatchIndex(subject, entries, claimedIndices);
+  if (matchIndex === -1) return false;
+  claimedIndices.add(matchIndex);
+  return true;
+}
+
+function findUndocumentedGovernedCommits(
+  postReleaseCommitSubjects,
+  unreleasedSection,
+  isFeatureBranchContext,
+) {
   const entries = splitUnreleasedEntries(unreleasedSection);
-  return postReleaseCommitSubjects.filter(
-    (subject) =>
-      GOVERNED_COMMIT_TYPE.test(subject) &&
-      !isReferencedByPrNumber(subject, unreleasedSection) &&
-      !isReferencedBySlug(subject, entries),
-  );
+  const claimedIndices = new Set();
+  const undocumented = [];
+  for (const subject of postReleaseCommitSubjects) {
+    if (!GOVERNED_COMMIT_TYPE.test(subject)) continue;
+    // QNBS-v3 (codex, P1): an un-numbered commit observed while HEAD isn't `main` is, in
+    // practice, either a rare old direct-push commit (still checked below) or one of THIS
+    // branch's own not-yet-squashed intermediate commits (whether pushed to an open PR, or still
+    // only local, e.g. under the mandatory pre-push hook mid-review), which cannot reference
+    // itself in [Unreleased] in advance. Exempting only un-numbered commits here — not every
+    // governed commit — still enforces full completeness for an already-numbered commit sitting
+    // in the same range from a separate, already-merged PR.
+    if (isFeatureBranchContext && !TRAILING_PR_REF.test(subject)) continue;
+    if (!isCommitDocumented(subject, unreleasedSection, entries, claimedIndices)) {
+      undocumented.push(subject);
+    }
+  }
+  return undocumented;
 }
 
 /**
@@ -472,18 +498,39 @@ export function getPostReleaseCommitSubjects(repositoryRoot = root) {
   }
 }
 
-// QNBS-v3: deliberately NOT defaulted from process.env here — this same env var is ambiently
-// visible to the Vitest process itself when the whole suite runs inside a GitHub Actions
-// pull_request-triggered job (not just this gate's own CLI step), so a default read at this
-// pure-function boundary silently changed every test's behavior based on which CI context ran
-// it. Only main()'s real CLI invocation below reads the actual environment; tests always get a
-// deterministic, explicitly-passed value.
+// QNBS-v3 (codex): the mandatory local `pnpm run ci:prepush` hook runs this same checker on every
+// feature branch, mid-review, without any GitHub Actions event context at all — checking the
+// branch name directly (not just GITHUB_EVENT_NAME) means the un-numbered-commit exemption also
+// covers a local review-fix commit before it's ever pushed, not only a PR's own CI run. Fails
+// closed to "not a feature branch" (full strictness) on any git error, matching this file's other
+// git-plumbing helpers' fail-safe posture.
+export function isOnFeatureBranch(repositoryRoot = root) {
+  try {
+    const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: repositoryRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return branch !== '' && branch !== 'main';
+  } catch {
+    return false;
+  }
+}
+
+// QNBS-v3: isFeatureBranchContext deliberately has a plain `false` default, not one read from
+// process.env/git here — an env var is ambiently visible to the Vitest process itself when the
+// whole suite runs inside a GitHub Actions pull_request-triggered job (not just this gate's own
+// CLI step), so a default read at this pure-function boundary silently changed every test's
+// behavior based on which CI context ran it. Only main()'s real CLI invocation below computes the
+// actual value (from GITHUB_EVENT_NAME and/or the checked-out branch not being `main` — see
+// isOnFeatureBranch below, which covers local `pnpm run ci:prepush` on a feature branch too, not
+// just GitHub Actions pull_request jobs); tests always get a deterministic, explicitly-passed value.
 export function scanUnreleasedTruth(
   changelog,
   postReleaseCommitSubjects,
   packageVersion,
   taggedVersions,
-  isPullRequestContext = false,
+  isFeatureBranchContext = false,
 ) {
   if (!postReleaseCommitSubjects || postReleaseCommitSubjects.length === 0) return [];
   const candidateVersion = changelog.match(
@@ -505,17 +552,11 @@ export function scanUnreleasedTruth(
       `CHANGELOG.md — ${postReleaseCommitSubjects.length} commit(s) exist after the latest release tag, but [Unreleased] is empty`,
     ];
   }
-  // QNBS-v3 (codex, P1): a pull_request CI run's `git log` range enumerates every commit unique
-  // to that branch — not the one commit that will actually exist after squash-merge. Enforcing
-  // full per-commit completeness there would make a routine review-fix follow-up commit
-  // unsatisfiable (it cannot reference itself in [Unreleased] in advance). Completeness is
-  // enforced once those commits are real, permanent history: on the push to main right after
-  // merge (and locally, since a developer isn't fighting the multi-commit-per-PR shape there).
-  if (isPullRequestContext) return [];
   const unreleasedSection = getUnreleasedSectionText(changelog);
   const undocumented = findUndocumentedGovernedCommits(
     postReleaseCommitSubjects,
     unreleasedSection,
+    isFeatureBranchContext,
   );
   if (undocumented.length === 0) return [];
   return [
@@ -864,7 +905,7 @@ function main() {
       getPostReleaseCommitSubjects(),
       packageVersion,
       taggedVersions,
-      process.env.GITHUB_EVENT_NAME === 'pull_request',
+      process.env.GITHUB_EVENT_NAME === 'pull_request' || isOnFeatureBranch(),
     ),
   );
   allFindings.push(
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index 17102e147..73b823974 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -4,7 +4,9 @@
  * QNBS-v3: protects the drift gate from historical-section regressions — an untested exclusion heuristic would turn it into noise.
  */
 
+import { execFileSync } from 'node:child_process';
 import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import {
@@ -30,8 +32,9 @@ type ReleaseTruthModule = {
     subjects: string[] | null,
     packageVersion?: string,
     taggedVersions?: Set<string>,
-    isPullRequestContext?: boolean,
+    isFeatureBranchContext?: boolean,
   ) => string[];
+  isOnFeatureBranch: (repositoryRoot?: string) => boolean;
 };
 // QNBS-v3: load the runtime-only scanners without making tsgo infer untyped .mjs exports.
 const loadReleaseTruthModule = async () =>
@@ -408,12 +411,43 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('does not reference 2 post-tag feat/fix/perf commit');
     });
 
+    // QNBS-v3 (codex): the previous test's bullet is too generic for EITHER commit to individually
+    // clear the 60% threshold — this one is specific enough that BOTH would clear it alone,
+    // proving the fix is genuine "claim, don't reuse" exclusivity, not incidental low overlap.
+    it('claims a matched entry exclusively — a second commit cannot reuse it even above threshold', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Canonical document projection foundation established.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'feat(project): establish canonical document projection foundation',
+        'fix(project): reuse canonical document projection foundation',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('does not reference 1 post-tag feat/fix/perf commit');
+      expect(findings[0]).toContain('reuse canonical document projection foundation');
+    });
+
+    // QNBS-v3 (codex): a numbered commit has an unambiguous way to be referenced — it must not
+    // fall back to a fuzzy slug match against a different, older bullet that merely shares words.
+    it('requires the exact PR number for a numbered commit, never a slug fallback', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Canonical document projection now reuses parsed input.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): reuse parsed canonical document input (#999)',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('#999');
+    });
+
     // QNBS-v3 (codex, P1): a pull_request CI run's git-log range enumerates every commit unique
     // to that branch, not the one commit that will exist after squash-merge — a routine
-    // review-fix follow-up commit can't reference itself in [Unreleased] in advance. Full
-    // completeness is enforced only outside pull_request context (locally, and on push to main
-    // right after merge).
-    it('does not enforce per-commit completeness in pull_request CI context', async () => {
+    // review-fix follow-up commit (necessarily un-numbered, since it hasn't been squash-merged
+    // yet) can't reference itself in [Unreleased] in advance. Only UN-numbered commits are
+    // exempted in pull_request context; full completeness is otherwise enforced everywhere
+    // (locally, on push to main right after merge, and for any already-numbered commit even
+    // during a pull_request run — see the next test).
+    it('does not enforce completeness for an un-numbered commit in pull_request CI context', async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();
       const findings = scanUnreleasedTruth(
         populatedButUnrelated,
@@ -425,6 +459,23 @@ describe('Unreleased truth', () => {
       expect(findings).toEqual([]);
     });
 
+    // QNBS-v3 (codex, P1): exempting a PR's own in-flight commits must not weaken enforcement for
+    // an already-numbered commit sitting in the same range (e.g. from a separate, already-merged
+    // PR) — that one is real, permanent history and must still be caught even during a
+    // pull_request run.
+    it('still enforces completeness for an already-numbered commit in pull_request CI context', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const findings = scanUnreleasedTruth(
+        populatedButUnrelated,
+        ['fix(project): retain raw header verdict on projection failure (#999)'],
+        undefined,
+        undefined,
+        true,
+      );
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('#999');
+    });
+
     it('still rejects a completely empty [Unreleased] in pull_request CI context', async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();
       const findings = scanUnreleasedTruth(
@@ -439,6 +490,55 @@ describe('Unreleased truth', () => {
   });
 });
 
+describe('isOnFeatureBranch', () => {
+  function initTempRepo(prefix: string): string {
+    const repositoryRoot = mkdtempSync(join(process.cwd(), prefix));
+    execFileSync('git', ['init', '--quiet', '--initial-branch=main', repositoryRoot]);
+    execFileSync('git', ['-C', repositoryRoot, 'config', 'user.email', 'test@example.com']);
+    execFileSync('git', ['-C', repositoryRoot, 'config', 'user.name', 'Test']);
+    writeFileSync(join(repositoryRoot, 'file.txt'), 'content');
+    execFileSync('git', ['-C', repositoryRoot, 'add', 'file.txt']);
+    execFileSync('git', ['-C', repositoryRoot, 'commit', '--quiet', '-m', 'init']);
+    return repositoryRoot;
+  }
+
+  it('returns false when HEAD is main', async () => {
+    const { isOnFeatureBranch } = await loadReleaseTruthModule();
+    const repositoryRoot = initTempRepo('.tmp-worldscript-doc-metrics-branch-main-');
+    try {
+      expect(isOnFeatureBranch(repositoryRoot)).toBe(false);
+    } finally {
+      rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('returns true when HEAD is a feature branch', async () => {
+    const { isOnFeatureBranch } = await loadReleaseTruthModule();
+    const repositoryRoot = initTempRepo('.tmp-worldscript-doc-metrics-branch-feature-');
+    try {
+      execFileSync('git', ['-C', repositoryRoot, 'switch', '--quiet', '-c', 'fix/example']);
+      expect(isOnFeatureBranch(repositoryRoot)).toBe(true);
+    } finally {
+      rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+  });
+
+  // QNBS-v3: fails closed to "not a feature branch" (full strictness) on any git error, matching
+  // this file's other git-plumbing helpers' fail-safe posture — never fails open into leniency.
+  it('fails closed to false when not a git repository', async () => {
+    const { isOnFeatureBranch } = await loadReleaseTruthModule();
+    // QNBS-v3: git searches upward for a .git directory, so a plain subdirectory of THIS actual
+    // repository would still resolve to ITS branch — use a location outside any git repository
+    // (tmpdir(), not process.cwd()) so this genuinely exercises the no-repository failure path.
+    const repositoryRoot = mkdtempSync(join(tmpdir(), 'worldscript-doc-metrics-nogit-'));
+    try {
+      expect(isOnFeatureBranch(repositoryRoot)).toBe(false);
+    } finally {
+      rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('getTaggedVersions', () => {
   it('reads packed and loose tags from a standard repository', () => {
     const repositoryRoot = mkdtempSync(join(process.cwd(), '.tmp-worldscript-doc-metrics-'));

From deee192aa3de0ec566f4841e8603ff6c61f8f70b Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 06:37:54 +0200
Subject: [PATCH 05/15] fix(docs): replace greedy slug-entry claiming with
 maximum bipartite matching

Greedily claiming the first matching entry per commit was order-
dependent: a fully documented changelog could be wrongly rejected
depending only on which commit happened to be checked first. Example:
entries "Alpha beta gamma delta" / "Alpha beta epsilon zeta" against
subjects "alpha beta gamma delta epsilon zeta" then "alpha beta gamma
delta" -- the broader subject greedily claims the only entry the
narrower one can use, even though swapping which entry each takes
documents both.

Replaced with Kuhn's algorithm (augmenting-path maximum bipartite
matching between un-numbered commits and changelog entries), which
finds the best possible assignment regardless of input order. A
numbered commit is unaffected -- it never participated in slug
matching in the first place, per the prior commit's exact-PR-match fix.

2 new regression tests proving the exact adversarial case in both
commit orders; README test-count resynced.
---
 README.md                          |  8 +--
 scripts/check-doc-metrics.mjs      | 90 ++++++++++++++++++++----------
 tests/unit/checkDocMetrics.test.ts | 30 ++++++++++
 3 files changed, 94 insertions(+), 34 deletions(-)

diff --git a/README.md b/README.md
index 20bbcf2a6..f203b05c1 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7611%2B_%2F_603_files-22C55E" alt="7611+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7612%2B_%2F_603_files-22C55E" alt="7612+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7611+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7612+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7611+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7612+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7611+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7612+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index 68ce04416..62062e504 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -422,55 +422,85 @@ function splitUnreleasedEntries(unreleasedSection) {
   return entries;
 }
 
-// QNBS-v3 (codex): match ratio is computed PER changelog entry, and a matched entry is then
-// claimed (excluded from later commits in the same pass) — otherwise words scattered across
-// several unrelated bullets could collectively satisfy a commit none of them documents, AND one
-// generic bullet could simultaneously "document" multiple different undocumented commits.
-function findSlugMatchIndex(subject, unreleasedEntries, claimedIndices) {
+// QNBS-v3 (codex): the set of entry indices a given commit's slug could match — match ratio is
+// computed PER changelog entry (see findUndocumentedGovernedCommits's header comment for why).
+function candidateEntryIndices(subject, unreleasedEntries) {
   const description = subject.replace(GOVERNED_COMMIT_TYPE, '').replace(TRAILING_PR_REF, '');
   const words = significantSlugWords(description);
-  if (words.length === 0) return -1;
-  return unreleasedEntries.findIndex((entry, index) => {
-    if (claimedIndices.has(index)) return false;
+  if (words.length === 0) return [];
+  return unreleasedEntries.flatMap((entry, index) => {
     const matched = words.filter((word) => new RegExp(`\\b${word}\\b`, 'i').test(entry));
-    return matched.length / words.length >= SLUG_MATCH_RATIO;
+    return matched.length / words.length >= SLUG_MATCH_RATIO ? [index] : [];
   });
 }
 
-// QNBS-v3 (codex): a commit ending in a trailing PR number has an unambiguous way to be
-// referenced — require the exact number, never fall back to a fuzzy slug match that could match a
-// different, older bullet purely by generic word overlap.
-function isCommitDocumented(subject, unreleasedSection, entries, claimedIndices) {
-  const prMatch = TRAILING_PR_REF.exec(subject);
-  if (prMatch) return isReferencedByPrNumber(prMatch[1], unreleasedSection);
-  const matchIndex = findSlugMatchIndex(subject, entries, claimedIndices);
-  if (matchIndex === -1) return false;
-  claimedIndices.add(matchIndex);
-  return true;
+// QNBS-v3 (codex): try to (re)assign `commitIndex` an entry, freeing up its current entry (via
+// recursive reassignment) if every candidate is already claimed by a commit that itself has
+// another option — standard Kuhn's-algorithm augmenting path for maximum bipartite matching.
+function tryAssignEntry(commitIndex, adjacency, entryOwner, visited) {
+  for (const entryIndex of adjacency[commitIndex]) {
+    if (visited.has(entryIndex)) continue;
+    visited.add(entryIndex);
+    const currentOwner = entryOwner[entryIndex];
+    if (currentOwner === -1 || tryAssignEntry(currentOwner, adjacency, entryOwner, visited)) {
+      entryOwner[entryIndex] = commitIndex;
+      return true;
+    }
+  }
+  return false;
+}
+
+// QNBS-v3 (codex): greedily claiming the FIRST matching entry per commit is order-dependent — a
+// fully documented changelog could be wrongly rejected depending only on which commit happens to
+// be checked first (e.g. two entries "Alpha beta gamma delta" / "Alpha beta epsilon zeta" against
+// subjects "alpha beta gamma delta epsilon zeta" then "alpha beta gamma delta": greedy claiming in
+// that order leaves the second unmatched, even though swapping which entry each takes documents
+// both). A maximum bipartite matching (Kuhn's algorithm) finds the best possible assignment
+// regardless of input order, so this mandatory pre-push/CI check never blocks already-complete
+// history on an accident of commit ordering.
+function computeMaxSlugMatching(subjects, entries) {
+  const adjacency = subjects.map((subject) => candidateEntryIndices(subject, entries));
+  const entryOwner = new Array(entries.length).fill(-1);
+  const matchedSubjects = new Array(subjects.length).fill(false);
+  for (let commitIndex = 0; commitIndex < subjects.length; commitIndex++) {
+    if (tryAssignEntry(commitIndex, adjacency, entryOwner, new Set())) {
+      matchedSubjects[commitIndex] = true;
+    }
+  }
+  return matchedSubjects;
 }
 
+// QNBS-v3 (codex, P1): an un-numbered commit observed while HEAD isn't `main` is, in practice,
+// either a rare old direct-push commit or one of THIS branch's own not-yet-squashed intermediate
+// commits (whether pushed to an open PR, or still only local, e.g. under the mandatory pre-push
+// hook mid-review), which cannot reference itself in [Unreleased] in advance. Exempting only
+// un-numbered commits — not every governed commit, and never a numbered one — still enforces full
+// completeness for an already-numbered commit sitting in the same range from a separate,
+// already-merged PR, in every context.
 function findUndocumentedGovernedCommits(
   postReleaseCommitSubjects,
   unreleasedSection,
   isFeatureBranchContext,
 ) {
   const entries = splitUnreleasedEntries(unreleasedSection);
-  const claimedIndices = new Set();
   const undocumented = [];
+  const slugCandidates = [];
   for (const subject of postReleaseCommitSubjects) {
     if (!GOVERNED_COMMIT_TYPE.test(subject)) continue;
-    // QNBS-v3 (codex, P1): an un-numbered commit observed while HEAD isn't `main` is, in
-    // practice, either a rare old direct-push commit (still checked below) or one of THIS
-    // branch's own not-yet-squashed intermediate commits (whether pushed to an open PR, or still
-    // only local, e.g. under the mandatory pre-push hook mid-review), which cannot reference
-    // itself in [Unreleased] in advance. Exempting only un-numbered commits here — not every
-    // governed commit — still enforces full completeness for an already-numbered commit sitting
-    // in the same range from a separate, already-merged PR.
-    if (isFeatureBranchContext && !TRAILING_PR_REF.test(subject)) continue;
-    if (!isCommitDocumented(subject, unreleasedSection, entries, claimedIndices)) {
-      undocumented.push(subject);
+    const prMatch = TRAILING_PR_REF.exec(subject);
+    if (prMatch) {
+      // QNBS-v3 (codex): a numbered commit has an unambiguous way to be referenced — require the
+      // exact number, never fall back to a fuzzy slug match that could hit a different bullet.
+      if (!isReferencedByPrNumber(prMatch[1], unreleasedSection)) undocumented.push(subject);
+      continue;
     }
+    if (isFeatureBranchContext) continue;
+    slugCandidates.push(subject);
   }
+  const matched = computeMaxSlugMatching(slugCandidates, entries);
+  slugCandidates.forEach((subject, index) => {
+    if (!matched[index]) undocumented.push(subject);
+  });
   return undocumented;
 }
 
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index 73b823974..4b57657c1 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -427,6 +427,36 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('reuse canonical document projection foundation');
     });
 
+    // QNBS-v3 (codex): greedily claiming the FIRST matching entry is order-dependent — a fully
+    // documented changelog could be wrongly rejected depending only on which commit is checked
+    // first. Here the broader commit (6 words) can match EITHER entry, but the narrower commit
+    // (4 words) can only match the first entry; a correct maximum-matching assignment documents
+    // both regardless of processing order (the broader one takes the second entry, freeing the
+    // first for the narrower one).
+    it('finds a valid assignment even when a broader commit could greedily claim the only entry a narrower commit needs', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog = [
+        '## [Unreleased]',
+        '',
+        '### Fixed',
+        '',
+        '- Alpha beta gamma delta.',
+        '- Alpha beta epsilon zeta.',
+      ].join('\n');
+      const findingsForward = scanUnreleasedTruth(changelog, [
+        'fix(project): alpha beta gamma delta epsilon zeta',
+        'fix(project): alpha beta gamma delta',
+      ]);
+      expect(findingsForward).toEqual([]);
+
+      // QNBS-v3: same commits, reversed order — must still fully document both.
+      const findingsReversed = scanUnreleasedTruth(changelog, [
+        'fix(project): alpha beta gamma delta',
+        'fix(project): alpha beta gamma delta epsilon zeta',
+      ]);
+      expect(findingsReversed).toEqual([]);
+    });
+
     // QNBS-v3 (codex): a numbered commit has an unambiguous way to be referenced — it must not
     // fall back to a fuzzy slug match against a different, older bullet that merely shares words.
     it('requires the exact PR number for a numbered commit, never a slug fallback', async () => {

From 0c9291c67118b93021da99ae34a5784faaedaa11 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 07:09:30 +0200
Subject: [PATCH 06/15] fix(docs): flatten completeness-check nesting, fix
 detached-HEAD and self-reference gaps

- Extract classifyGovernedCommit() so findUndocumentedGovernedCommits is a flat
  loop with no nested conditionals (CodeScene Bumpy Road Ahead).
- isOnFeatureBranch() now treats detached HEAD (the literal string actions/checkout
  leaves for every event, push included) as non-feature-branch, so push-to-main
  runs never get silently exempted from full completeness enforcement.
- Add this PR's own eventual squash-merge PR number to the CHANGELOG bullet it
  documents, since the exact-PR-match-required rule would otherwise fail this
  PR's own post-merge CI run.
---
 CHANGELOG.md                  | 12 ++++++------
 scripts/check-doc-metrics.mjs | 30 ++++++++++++++----------------
 2 files changed, 20 insertions(+), 22 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cdb9cab92..6591d1f9b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,12 +49,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   2026-08-18. Rewritten to anchor on the living Ledger-row-9/R-15 state instead of a PR number, and
   `check-doc-metrics.mjs` now mechanically rejects an unqualified live/pending-remediation claim
   tied to a bare PR number in these two files. PR #673.
-- **CHANGELOG completeness-check upgrade, backfill Unreleased (audit F-2):** `scanUnreleasedTruth`
-  previously accepted any non-empty `[Unreleased]` section forever, so a single unrelated bullet
-  let arbitrarily many later `feat`/`fix`/`perf` commits go completely undocumented — 13 real
-  commits since `v1.28.4` had gone unrecorded. It now requires every governed commit to be
-  individually referenced by PR number or subject slug, naming any that aren't; this section was
-  backfilled with all 13 currently-undocumented entries above.
+- **CHANGELOG completeness-check upgrade, backfill Unreleased (audit F-2, PR #674):**
+  `scanUnreleasedTruth` previously accepted any non-empty `[Unreleased]` section forever, so a
+  single unrelated bullet let arbitrarily many later `feat`/`fix`/`perf` commits go completely
+  undocumented — 13 real commits since `v1.28.4` had gone unrecorded. It now requires every
+  governed commit to be individually referenced by PR number or subject slug, naming any that
+  aren't; this section was backfilled with all 13 currently-undocumented entries above.
 - **Completeness-check review findings addressed:** PR-number matching now requires a non-digit
   boundary (a bare substring check let `#65` satisfy `#656`), subject-slug matching is scoped to
   one changelog entry at a time instead of the whole section, each matched entry is claimed so one
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index 62062e504..9fbee9b31 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -477,6 +477,15 @@ function computeMaxSlugMatching(subjects, entries) {
 // un-numbered commits — not every governed commit, and never a numbered one — still enforces full
 // completeness for an already-numbered commit sitting in the same range from a separate,
 // already-merged PR, in every context.
+// QNBS-v3 (CodeScene): extracted so findUndocumentedGovernedCommits stays a flat loop with zero nested conditionals — returns 'documented', 'undocumented', or 'needsSlugCheck' for one subject.
+function classifyGovernedCommit(subject, unreleasedSection, isFeatureBranchContext) {
+  const prMatch = TRAILING_PR_REF.exec(subject);
+  if (prMatch) {
+    return isReferencedByPrNumber(prMatch[1], unreleasedSection) ? 'documented' : 'undocumented';
+  }
+  return isFeatureBranchContext ? 'documented' : 'needsSlugCheck';
+}
+
 function findUndocumentedGovernedCommits(
   postReleaseCommitSubjects,
   unreleasedSection,
@@ -487,15 +496,9 @@ function findUndocumentedGovernedCommits(
   const slugCandidates = [];
   for (const subject of postReleaseCommitSubjects) {
     if (!GOVERNED_COMMIT_TYPE.test(subject)) continue;
-    const prMatch = TRAILING_PR_REF.exec(subject);
-    if (prMatch) {
-      // QNBS-v3 (codex): a numbered commit has an unambiguous way to be referenced — require the
-      // exact number, never fall back to a fuzzy slug match that could hit a different bullet.
-      if (!isReferencedByPrNumber(prMatch[1], unreleasedSection)) undocumented.push(subject);
-      continue;
-    }
-    if (isFeatureBranchContext) continue;
-    slugCandidates.push(subject);
+    const status = classifyGovernedCommit(subject, unreleasedSection, isFeatureBranchContext);
+    if (status === 'undocumented') undocumented.push(subject);
+    if (status === 'needsSlugCheck') slugCandidates.push(subject);
   }
   const matched = computeMaxSlugMatching(slugCandidates, entries);
   slugCandidates.forEach((subject, index) => {
@@ -528,12 +531,7 @@ export function getPostReleaseCommitSubjects(repositoryRoot = root) {
   }
 }
 
-// QNBS-v3 (codex): the mandatory local `pnpm run ci:prepush` hook runs this same checker on every
-// feature branch, mid-review, without any GitHub Actions event context at all — checking the
-// branch name directly (not just GITHUB_EVENT_NAME) means the un-numbered-commit exemption also
-// covers a local review-fix commit before it's ever pushed, not only a PR's own CI run. Fails
-// closed to "not a feature branch" (full strictness) on any git error, matching this file's other
-// git-plumbing helpers' fail-safe posture.
+// QNBS-v3 (codex): checks the branch name directly (not just GITHUB_EVENT_NAME) so the un-numbered-commit exemption also covers a local pre-push run, but fails closed on detached HEAD (`git rev-parse --abbrev-ref HEAD` prints "HEAD" there, actions/checkout's default for every event including push) so push-to-main enforcement never silently weakens.
 export function isOnFeatureBranch(repositoryRoot = root) {
   try {
     const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
@@ -541,7 +539,7 @@ export function isOnFeatureBranch(repositoryRoot = root) {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
-    return branch !== '' && branch !== 'main';
+    return branch !== '' && branch !== 'HEAD' && branch !== 'main';
   } catch {
     return false;
   }

From 1fb73c852d3eea593d373f52ed9944f98ea36841 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 07:15:33 +0200
Subject: [PATCH 07/15] test(docs): cover detached-HEAD case for
 isOnFeatureBranch

Adds the regression test for the detached-HEAD fix in 0c9291c6 that a
prior reply to the review thread had already described as included -
it was written but not actually committed in that push. Resyncs
README.md's test-count metric for the added test.
---
 README.md                          |  8 ++++----
 tests/unit/checkDocMetrics.test.ts | 15 +++++++++++++++
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index f203b05c1..8dd5fdfb5 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7612%2B_%2F_603_files-22C55E" alt="7612+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7613%2B_%2F_603_files-22C55E" alt="7613+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7612+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7613+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7612+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7613+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7612+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7613+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index 4b57657c1..fce5ab343 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -553,6 +553,21 @@ describe('isOnFeatureBranch', () => {
     }
   });
 
+  // QNBS-v3: actions/checkout leaves every GitHub Actions event, push included, in detached HEAD.
+  it('returns false when HEAD is detached, matching a push-to-main CI checkout', async () => {
+    const { isOnFeatureBranch } = await loadReleaseTruthModule();
+    const repositoryRoot = initTempRepo('.tmp-worldscript-doc-metrics-branch-detached-');
+    try {
+      const headSha = execFileSync('git', ['-C', repositoryRoot, 'rev-parse', 'HEAD'], {
+        encoding: 'utf8',
+      }).trim();
+      execFileSync('git', ['-C', repositoryRoot, 'checkout', '--quiet', '--detach', headSha]);
+      expect(isOnFeatureBranch(repositoryRoot)).toBe(false);
+    } finally {
+      rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+  });
+
   // QNBS-v3: fails closed to "not a feature branch" (full strictness) on any git error, matching
   // this file's other git-plumbing helpers' fail-safe posture — never fails open into leniency.
   it('fails closed to false when not a git repository', async () => {

From 0a20b9d1eadd41cf7b399b599d617e58642304b7 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 07:42:24 +0200
Subject: [PATCH 08/15] fix(docs): reserve a numbered commit's changelog entry
 from slug-match reuse

A numbered commit's exact PR-number match never touched entryOwner, so an
unrelated un-numbered commit's slug match could reuse the same bullet and
go undetected as undocumented. Reserve the entry a numbered commit's PR
reference resolves to before slug matching runs, unless that entry
explicitly bundles multiple PR numbers (deliberately shared documentation).
---
 README.md                          |  8 ++++----
 scripts/check-doc-metrics.mjs      | 33 ++++++++++++++++++++++++++++--
 tests/unit/checkDocMetrics.test.ts | 28 +++++++++++++++++++++++++
 3 files changed, 63 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 8dd5fdfb5..6ffbd9e42 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7613%2B_%2F_603_files-22C55E" alt="7613+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7615%2B_%2F_603_files-22C55E" alt="7615+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7613+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7615+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7613+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7615+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7613+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7615+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index 9fbee9b31..9c4a14c98 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -398,6 +398,16 @@ function isReferencedByPrNumber(prNumber, unreleasedSection) {
   return new RegExp(`(?:^|\\D)#${prNumber}(?!\\d)`).test(unreleasedSection);
 }
 
+// QNBS-v3 (codex): an entry that explicitly bundles several PR numbers is deliberately shared, so it must stay available for slug matching rather than being reserved for just one of them.
+function countDistinctPrReferences(entry) {
+  const numbers = new Set();
+  const pattern = /(?:^|\D)#(\d+)(?!\d)/g;
+  for (let match = pattern.exec(entry); match !== null; match = pattern.exec(entry)) {
+    numbers.add(match[1]);
+  }
+  return numbers.size;
+}
+
 // QNBS-v3 (codex): a Markdown bullet may wrap across several physical lines — join a bullet's own
 // continuation lines into one entry so slug-matching sees the whole thought, not a fragment.
 function splitUnreleasedEntries(unreleasedSection) {
@@ -434,6 +444,9 @@ function candidateEntryIndices(subject, unreleasedEntries) {
   });
 }
 
+// QNBS-v3 (codex): unlike an entry merely held by another slug-matched commit, a reserved entry can never be freed up via recursive reassignment.
+const RESERVED_ENTRY = -2;
+
 // QNBS-v3 (codex): try to (re)assign `commitIndex` an entry, freeing up its current entry (via
 // recursive reassignment) if every candidate is already claimed by a commit that itself has
 // another option — standard Kuhn's-algorithm augmenting path for maximum bipartite matching.
@@ -442,6 +455,7 @@ function tryAssignEntry(commitIndex, adjacency, entryOwner, visited) {
     if (visited.has(entryIndex)) continue;
     visited.add(entryIndex);
     const currentOwner = entryOwner[entryIndex];
+    if (currentOwner === RESERVED_ENTRY) continue;
     if (currentOwner === -1 || tryAssignEntry(currentOwner, adjacency, entryOwner, visited)) {
       entryOwner[entryIndex] = commitIndex;
       return true;
@@ -458,9 +472,12 @@ function tryAssignEntry(commitIndex, adjacency, entryOwner, visited) {
 // both). A maximum bipartite matching (Kuhn's algorithm) finds the best possible assignment
 // regardless of input order, so this mandatory pre-push/CI check never blocks already-complete
 // history on an accident of commit ordering.
-function computeMaxSlugMatching(subjects, entries) {
+function computeMaxSlugMatching(subjects, entries, reservedEntryIndices = new Set()) {
   const adjacency = subjects.map((subject) => candidateEntryIndices(subject, entries));
   const entryOwner = new Array(entries.length).fill(-1);
+  reservedEntryIndices.forEach((entryIndex) => {
+    entryOwner[entryIndex] = RESERVED_ENTRY;
+  });
   const matchedSubjects = new Array(subjects.length).fill(false);
   for (let commitIndex = 0; commitIndex < subjects.length; commitIndex++) {
     if (tryAssignEntry(commitIndex, adjacency, entryOwner, new Set())) {
@@ -486,6 +503,14 @@ function classifyGovernedCommit(subject, unreleasedSection, isFeatureBranchConte
   return isFeatureBranchContext ? 'documented' : 'needsSlugCheck';
 }
 
+// QNBS-v3 (codex): reserves a numbered commit's entry so it can't silently double as an unrelated commit's own slug-matched documentation, unless the entry explicitly bundles several PRs.
+function reserveEntryForNumberedCommit(prNumber, entries, reservedEntryIndices) {
+  const entryIndex = entries.findIndex((entry) => isReferencedByPrNumber(prNumber, entry));
+  if (entryIndex === -1) return;
+  if (countDistinctPrReferences(entries[entryIndex]) > 1) return;
+  reservedEntryIndices.add(entryIndex);
+}
+
 function findUndocumentedGovernedCommits(
   postReleaseCommitSubjects,
   unreleasedSection,
@@ -494,13 +519,17 @@ function findUndocumentedGovernedCommits(
   const entries = splitUnreleasedEntries(unreleasedSection);
   const undocumented = [];
   const slugCandidates = [];
+  const reservedEntryIndices = new Set();
   for (const subject of postReleaseCommitSubjects) {
     if (!GOVERNED_COMMIT_TYPE.test(subject)) continue;
+    const prMatch = TRAILING_PR_REF.exec(subject);
     const status = classifyGovernedCommit(subject, unreleasedSection, isFeatureBranchContext);
     if (status === 'undocumented') undocumented.push(subject);
     if (status === 'needsSlugCheck') slugCandidates.push(subject);
+    if (status === 'documented' && prMatch)
+      reserveEntryForNumberedCommit(prMatch[1], entries, reservedEntryIndices);
   }
-  const matched = computeMaxSlugMatching(slugCandidates, entries);
+  const matched = computeMaxSlugMatching(slugCandidates, entries, reservedEntryIndices);
   slugCandidates.forEach((subject, index) => {
     if (!matched[index]) undocumented.push(subject);
   });
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index fce5ab343..3030db4aa 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -470,6 +470,34 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('#999');
     });
 
+    // QNBS-v3 (codex): a numbered commit's exact-PR-number match must reserve its entry — otherwise
+    // an unrelated un-numbered commit's slug match can silently reuse the same bullet, since the PR
+    // check never touches entryOwner the way the slug-matching bipartite algorithm does.
+    it("does not let a numbered commit's entry double as an unrelated commit's slug match", async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Canonical document projection foundation. PR #999.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): canonical document projection foundation (#999)',
+        'fix(project): reuse canonical document projection foundation',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('reuse canonical document projection foundation');
+    });
+
+    // QNBS-v3 (codex): an entry that explicitly bundles multiple PR numbers is deliberately shared
+    // documentation, so it must stay available for slug matching rather than being reserved.
+    it('still allows slug matching against an entry that explicitly lists multiple PR numbers', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Canonical document projection foundation. PR #999, PR #998.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): canonical document projection foundation (#999)',
+        'fix(project): reuse canonical document projection foundation',
+      ]);
+      expect(findings).toEqual([]);
+    });
+
     // QNBS-v3 (codex, P1): a pull_request CI run's git-log range enumerates every commit unique
     // to that branch, not the one commit that will exist after squash-merge — a routine
     // review-fix follow-up commit (necessarily un-numbered, since it hasn't been squash-merged

From e9a0216df60fbd97a8ca0c61d29302bb0be911f4 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 08:20:29 +0200
Subject: [PATCH 09/15] fix(docs): reserve multi-PR entries fully, exempt
 in-flight branch-local PR-shaped refs

Two genuine gaps from codex-connector review:

- reserveEntryForNumberedCommit's "skip reservation when an entry lists
  multiple PR numbers" carve-out was itself the bug: it left such an
  entry fully unreserved, so an unrelated un-numbered commit's slug
  match could still reuse it. Each numbered commit referencing that
  entry now reserves it independently (a Set, so idempotent) - no
  carve-out needed, since numbered commits never go through slug
  matching regardless.

- classifyGovernedCommit treated any commit ending in "(#NNN)" as an
  already-merged PR number, even on a feature branch where that token
  may only be an in-flight issue reference GitHub hasn't yet replaced
  with the real squash-merge PR number (this repo's own history shows
  the eventual form "... (#553) (#621)"). Added getBranchLocalCommitCount
  (git merge-base against origin/main, falling back to a local main) so
  commits unique to the current branch are exempted from the exact-PR-
  match requirement entirely, while commits already reachable from main
  stay fully enforced.

Also condensed several QNBS-v3 comments (including one from the prior
commit) down to the required single physical line.
---
 README.md                          |   8 +--
 scripts/check-doc-metrics.d.mts    |   1 +
 scripts/check-doc-metrics.mjs      |  71 +++++++++++++-----
 tests/unit/checkDocMetrics.test.ts | 112 +++++++++++++++++++++++++++--
 4 files changed, 164 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index 6ffbd9e42..c10db524b 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7615%2B_%2F_603_files-22C55E" alt="7615+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7621%2B_%2F_603_files-22C55E" alt="7621+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7615+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7621+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7615+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7621+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7615+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7621+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/scripts/check-doc-metrics.d.mts b/scripts/check-doc-metrics.d.mts
index 7e37ebd03..6bda6c358 100644
--- a/scripts/check-doc-metrics.d.mts
+++ b/scripts/check-doc-metrics.d.mts
@@ -18,6 +18,7 @@ export function scanUnreleasedTruth(
   packageVersion?: string,
   taggedVersions?: Set<string>,
   isFeatureBranchContext?: boolean,
+  branchLocalCount?: number,
 ): string[];
 export function scanForDrift(
   content: string,
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index 9c4a14c98..f60c39f31 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -398,16 +398,6 @@ function isReferencedByPrNumber(prNumber, unreleasedSection) {
   return new RegExp(`(?:^|\\D)#${prNumber}(?!\\d)`).test(unreleasedSection);
 }
 
-// QNBS-v3 (codex): an entry that explicitly bundles several PR numbers is deliberately shared, so it must stay available for slug matching rather than being reserved for just one of them.
-function countDistinctPrReferences(entry) {
-  const numbers = new Set();
-  const pattern = /(?:^|\D)#(\d+)(?!\d)/g;
-  for (let match = pattern.exec(entry); match !== null; match = pattern.exec(entry)) {
-    numbers.add(match[1]);
-  }
-  return numbers.size;
-}
-
 // QNBS-v3 (codex): a Markdown bullet may wrap across several physical lines — join a bullet's own
 // continuation lines into one entry so slug-matching sees the whole thought, not a fragment.
 function splitUnreleasedEntries(unreleasedSection) {
@@ -494,20 +484,20 @@ function computeMaxSlugMatching(subjects, entries, reservedEntryIndices = new Se
 // un-numbered commits — not every governed commit, and never a numbered one — still enforces full
 // completeness for an already-numbered commit sitting in the same range from a separate,
 // already-merged PR, in every context.
+// QNBS-v3 (codex): a branch-local commit's trailing "(#NNN)" may be an in-flight issue reference rather than the real PR number GitHub only appends at squash time, so isBranchLocal skips the exact-PR-match path entirely instead of trusting that number.
 // QNBS-v3 (CodeScene): extracted so findUndocumentedGovernedCommits stays a flat loop with zero nested conditionals — returns 'documented', 'undocumented', or 'needsSlugCheck' for one subject.
-function classifyGovernedCommit(subject, unreleasedSection, isFeatureBranchContext) {
+function classifyGovernedCommit(subject, unreleasedSection, isFeatureBranchContext, isBranchLocal) {
   const prMatch = TRAILING_PR_REF.exec(subject);
-  if (prMatch) {
+  if (prMatch && !isBranchLocal) {
     return isReferencedByPrNumber(prMatch[1], unreleasedSection) ? 'documented' : 'undocumented';
   }
   return isFeatureBranchContext ? 'documented' : 'needsSlugCheck';
 }
 
-// QNBS-v3 (codex): reserves a numbered commit's entry so it can't silently double as an unrelated commit's own slug-matched documentation, unless the entry explicitly bundles several PRs.
+// QNBS-v3 (codex): reserves a numbered commit's entry so it can't silently double as an unrelated commit's own slug-matched documentation — an entry bundling several PR numbers is reserved once per number, which is idempotent since they all resolve to the same index.
 function reserveEntryForNumberedCommit(prNumber, entries, reservedEntryIndices) {
   const entryIndex = entries.findIndex((entry) => isReferencedByPrNumber(prNumber, entry));
   if (entryIndex === -1) return;
-  if (countDistinctPrReferences(entries[entryIndex]) > 1) return;
   reservedEntryIndices.add(entryIndex);
 }
 
@@ -515,18 +505,26 @@ function findUndocumentedGovernedCommits(
   postReleaseCommitSubjects,
   unreleasedSection,
   isFeatureBranchContext,
+  branchLocalCount = 0,
 ) {
   const entries = splitUnreleasedEntries(unreleasedSection);
   const undocumented = [];
   const slugCandidates = [];
   const reservedEntryIndices = new Set();
-  for (const subject of postReleaseCommitSubjects) {
+  for (let index = 0; index < postReleaseCommitSubjects.length; index++) {
+    const subject = postReleaseCommitSubjects[index];
     if (!GOVERNED_COMMIT_TYPE.test(subject)) continue;
+    const isBranchLocal = index < branchLocalCount;
     const prMatch = TRAILING_PR_REF.exec(subject);
-    const status = classifyGovernedCommit(subject, unreleasedSection, isFeatureBranchContext);
+    const status = classifyGovernedCommit(
+      subject,
+      unreleasedSection,
+      isFeatureBranchContext,
+      isBranchLocal,
+    );
     if (status === 'undocumented') undocumented.push(subject);
     if (status === 'needsSlugCheck') slugCandidates.push(subject);
-    if (status === 'documented' && prMatch)
+    if (status === 'documented' && prMatch && !isBranchLocal)
       reserveEntryForNumberedCommit(prMatch[1], entries, reservedEntryIndices);
   }
   const matched = computeMaxSlugMatching(slugCandidates, entries, reservedEntryIndices);
@@ -574,6 +572,38 @@ export function isOnFeatureBranch(repositoryRoot = root) {
   }
 }
 
+// QNBS-v3 (codex): tries origin/main first (what CI actually has) and falls back to a local main so this still resolves in a plain developer clone.
+function resolveMainBranchPoint(repositoryRoot) {
+  for (const ref of ['origin/main', 'main']) {
+    try {
+      return execFileSync('git', ['merge-base', 'HEAD', ref], {
+        cwd: repositoryRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      // Try the next candidate ref below.
+    }
+  }
+  return null;
+}
+
+// QNBS-v3 (codex): a branch-local commit's trailing "(#NNN)" may still be an in-flight issue reference, not yet the real PR number GitHub appends at squash time, so counting how many of the newest post-tag commits sit above the main branch point lets the caller exempt exactly those from the exact-PR-match rule.
+export function getBranchLocalCommitCount(repositoryRoot = root) {
+  const branchPoint = resolveMainBranchPoint(repositoryRoot);
+  if (!branchPoint) return 0;
+  try {
+    const output = execFileSync('git', ['rev-list', '--count', `${branchPoint}..HEAD`], {
+      cwd: repositoryRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return Number.parseInt(output.trim(), 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
 // QNBS-v3: isFeatureBranchContext deliberately has a plain `false` default, not one read from
 // process.env/git here — an env var is ambiently visible to the Vitest process itself when the
 // whole suite runs inside a GitHub Actions pull_request-triggered job (not just this gate's own
@@ -588,6 +618,7 @@ export function scanUnreleasedTruth(
   packageVersion,
   taggedVersions,
   isFeatureBranchContext = false,
+  branchLocalCount = 0,
 ) {
   if (!postReleaseCommitSubjects || postReleaseCommitSubjects.length === 0) return [];
   const candidateVersion = changelog.match(
@@ -614,6 +645,7 @@ export function scanUnreleasedTruth(
     postReleaseCommitSubjects,
     unreleasedSection,
     isFeatureBranchContext,
+    branchLocalCount,
   );
   if (undocumented.length === 0) return [];
   return [
@@ -954,6 +986,8 @@ function main() {
 
   const taggedVersions = getTaggedVersions();
   const changelog = readFileSync(join(root, 'CHANGELOG.md'), 'utf8');
+  const isFeatureBranchContext =
+    process.env.GITHUB_EVENT_NAME === 'pull_request' || isOnFeatureBranch();
   const allFindings = [];
   allFindings.push(
     ...scanReleaseTruth(changelog, packageVersion, taggedVersions),
@@ -962,7 +996,8 @@ function main() {
       getPostReleaseCommitSubjects(),
       packageVersion,
       taggedVersions,
-      process.env.GITHUB_EVENT_NAME === 'pull_request' || isOnFeatureBranch(),
+      isFeatureBranchContext,
+      isFeatureBranchContext ? getBranchLocalCommitCount() : 0,
     ),
   );
   allFindings.push(
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index 3030db4aa..95bd5f22d 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -33,8 +33,10 @@ type ReleaseTruthModule = {
     packageVersion?: string,
     taggedVersions?: Set<string>,
     isFeatureBranchContext?: boolean,
+    branchLocalCount?: number,
   ) => string[];
   isOnFeatureBranch: (repositoryRoot?: string) => boolean;
+  getBranchLocalCommitCount: (repositoryRoot?: string) => number;
 };
 // QNBS-v3: load the runtime-only scanners without making tsgo infer untyped .mjs exports.
 const loadReleaseTruthModule = async () =>
@@ -470,9 +472,7 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('#999');
     });
 
-    // QNBS-v3 (codex): a numbered commit's exact-PR-number match must reserve its entry — otherwise
-    // an unrelated un-numbered commit's slug match can silently reuse the same bullet, since the PR
-    // check never touches entryOwner the way the slug-matching bipartite algorithm does.
+    // QNBS-v3 (codex): a numbered commit's exact-PR-number match must reserve its entry, otherwise an unrelated un-numbered commit's slug match can silently reuse the same bullet.
     it("does not let a numbered commit's entry double as an unrelated commit's slug match", async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();
       const changelog =
@@ -485,9 +485,8 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('reuse canonical document projection foundation');
     });
 
-    // QNBS-v3 (codex): an entry that explicitly bundles multiple PR numbers is deliberately shared
-    // documentation, so it must stay available for slug matching rather than being reserved.
-    it('still allows slug matching against an entry that explicitly lists multiple PR numbers', async () => {
+    // QNBS-v3 (codex): an entry listing several PR numbers still reserves for each, so it must keep refusing an unrelated commit's slug match.
+    it('reserves an entry that lists multiple PR numbers, still blocking an unrelated slug match', async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();
       const changelog =
         '## [Unreleased]\n\n### Fixed\n\n- Canonical document projection foundation. PR #999, PR #998.\n';
@@ -495,6 +494,19 @@ describe('Unreleased truth', () => {
         'fix(project): canonical document projection foundation (#999)',
         'fix(project): reuse canonical document projection foundation',
       ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('reuse canonical document projection foundation');
+    });
+
+    // QNBS-v3 (codex): reservation must never make the second numbered commit sharing that entry itself undocumented.
+    it('lets two numbered commits share one entry that lists both their PR numbers', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Canonical document projection foundation. PR #999, PR #998.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): canonical document projection foundation (#999)',
+        'fix(project): canonical document projection refinement (#998)',
+      ]);
       expect(findings).toEqual([]);
     });
 
@@ -534,6 +546,39 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('#999');
     });
 
+    // QNBS-v3 (codex): this repository's own history shows the eventual squashed form "... (#553) (#621)", so a branch-local "(#553)" must not be treated as an already-merged PR number.
+    it('exempts a branch-local commit whose trailing token is an in-flight issue reference, not a PR number', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const findings = scanUnreleasedTruth(
+        populatedButUnrelated,
+        ['fix(project): enforce raw schemaVersion integer grammar (#553)'],
+        undefined,
+        undefined,
+        true,
+        1,
+      );
+      expect(findings).toEqual([]);
+    });
+
+    // QNBS-v3 (codex): the branch-local exemption must only cover commits above the main branch point, never an older, already-merged numbered commit sitting lower in the same range.
+    it('still enforces an already-merged numbered commit below the branch-local window', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const findings = scanUnreleasedTruth(
+        populatedButUnrelated,
+        [
+          'fix(project): enforce raw schemaVersion integer grammar (#553)',
+          'fix(project): retain raw header verdict on projection failure (#999)',
+        ],
+        undefined,
+        undefined,
+        true,
+        1,
+      );
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('#999');
+      expect(findings[0]).not.toContain('#553');
+    });
+
     it('still rejects a completely empty [Unreleased] in pull_request CI context', async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();
       const findings = scanUnreleasedTruth(
@@ -612,6 +657,61 @@ describe('isOnFeatureBranch', () => {
   });
 });
 
+describe('getBranchLocalCommitCount', () => {
+  function initTempRepo(prefix: string): string {
+    const repositoryRoot = mkdtempSync(join(process.cwd(), prefix));
+    execFileSync('git', ['init', '--quiet', '--initial-branch=main', repositoryRoot]);
+    execFileSync('git', ['-C', repositoryRoot, 'config', 'user.email', 'test@example.com']);
+    execFileSync('git', ['-C', repositoryRoot, 'config', 'user.name', 'Test']);
+    writeFileSync(join(repositoryRoot, 'file.txt'), 'content');
+    execFileSync('git', ['-C', repositoryRoot, 'add', 'file.txt']);
+    execFileSync('git', ['-C', repositoryRoot, 'commit', '--quiet', '-m', 'init']);
+    return repositoryRoot;
+  }
+
+  function addCommit(repositoryRoot: string, message: string): void {
+    writeFileSync(join(repositoryRoot, `${message}.txt`), message);
+    execFileSync('git', ['-C', repositoryRoot, 'add', '-A']);
+    execFileSync('git', ['-C', repositoryRoot, 'commit', '--quiet', '-m', message]);
+  }
+
+  it('returns 0 on main itself', async () => {
+    const { getBranchLocalCommitCount } = await loadReleaseTruthModule();
+    const repositoryRoot = initTempRepo('.tmp-worldscript-doc-metrics-branchlocal-main-');
+    try {
+      expect(getBranchLocalCommitCount(repositoryRoot)).toBe(0);
+    } finally {
+      rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+  });
+
+  // QNBS-v3: mirrors this repository's own feat/553-universal-ingress-admission, several commits ahead of main with no open PR yet.
+  it('counts commits unique to a feature branch since it diverged from main', async () => {
+    const { getBranchLocalCommitCount } = await loadReleaseTruthModule();
+    const repositoryRoot = initTempRepo('.tmp-worldscript-doc-metrics-branchlocal-feature-');
+    try {
+      execFileSync('git', ['-C', repositoryRoot, 'switch', '--quiet', '-c', 'fix/example']);
+      addCommit(repositoryRoot, 'first');
+      addCommit(repositoryRoot, 'second');
+      expect(getBranchLocalCommitCount(repositoryRoot)).toBe(2);
+    } finally {
+      rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('fails closed to 0 when not a git repository', async () => {
+    const { getBranchLocalCommitCount } = await loadReleaseTruthModule();
+    const repositoryRoot = mkdtempSync(
+      join(tmpdir(), 'worldscript-doc-metrics-branchlocal-nogit-'),
+    );
+    try {
+      expect(getBranchLocalCommitCount(repositoryRoot)).toBe(0);
+    } finally {
+      rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('getTaggedVersions', () => {
   it('reads packed and loose tags from a standard repository', () => {
     const repositoryRoot = mkdtempSync(join(process.cwd(), '.tmp-worldscript-doc-metrics-'));

From 0d6ae5d6c5c4311aa38dcea174259b88f757e6f9 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 08:36:52 +0200
Subject: [PATCH 10/15] refactor(docs): flatten main() into a sequence of
 scanRequiredFiles calls

CodeFactor flagged main() as a Complex Method (five near-identical
read-file/handle-missing/scan loops). Extracted scanRequiredFiles() so
each loop becomes one call; behavior is unchanged (verified via
node scripts/check-doc-metrics.mjs and the full test suite).
---
 scripts/check-doc-metrics.mjs | 102 ++++++++++++++--------------------
 1 file changed, 41 insertions(+), 61 deletions(-)

diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index f60c39f31..c07655edc 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -970,6 +970,22 @@ export function scanSecurityDocPrStatus(content, filePath) {
 // QNBS-v3 (F-10, CodeRabbit follow-up): locales/it/help.json IS included — it's exactly where the F-10 stale-URL drift happened; the in-app link reads the constant directly so it can't drift and isn't listed here.
 const URL_CHECK_FILES = ['README.md', 'CLAUDE.md', 'locales/it/help.json'];
 
+// QNBS-v3 (CodeFactor): extracted so main() is a flat sequence of calls instead of five near-identical read/scan loops, each with its own try/catch for a missing file.
+function scanRequiredFiles(relPaths, scanFn, missingFindingFor) {
+  const findings = [];
+  for (const relPath of relPaths) {
+    let content;
+    try {
+      content = readFileSync(join(root, relPath), 'utf8');
+    } catch {
+      if (missingFindingFor) findings.push(missingFindingFor(relPath));
+      continue;
+    }
+    findings.push(...scanFn(content, relPath));
+  }
+  return findings;
+}
+
 function main() {
   const localeCount = getActualLocaleCount();
   const keyCount = getActualKeyCount();
@@ -1004,68 +1020,32 @@ function main() {
     ...scanReadmeReleaseTruth(readFileSync(join(root, 'README.md'), 'utf8'), taggedVersions),
   );
   allFindings.push(...scanReadmeTestMetrics(readFileSync(join(root, 'README.md'), 'utf8')));
-  for (const relPath of TARGET_FILES) {
-    const abs = join(root, relPath);
-    let content;
-    try {
-      content = readFileSync(abs, 'utf8');
-    } catch {
-      continue; // file doesn't exist in this checkout — not this gate's concern
-    }
-    allFindings.push(...scanForDrift(content, relPath, { localeCount, keyCount, latestVersion }));
-  }
-
-  for (const relPath of URL_CHECK_FILES) {
-    const abs = join(root, relPath);
-    let content;
-    try {
-      content = readFileSync(abs, 'utf8');
-    } catch {
-      continue;
-    }
-    allFindings.push(...scanForUrlDrift(content, relPath, canonicalUrl));
-  }
 
-  for (const relPath of SECURITY_STATUS_DOCS) {
-    const abs = join(root, relPath);
-    let content;
-    try {
-      content = readFileSync(abs, 'utf8');
-    } catch {
-      // QNBS-v3 (codex): these two files are this gate's required subjects — silently skipping a
-      // missing/unreadable one would make the live-status enforcement disappear exactly when its
-      // input is unavailable, the same failure mode as BUNDLE_BUDGET_DOCS below.
-      allFindings.push(`${relPath} — required security-status document is missing or unreadable`);
-      continue;
-    }
-    allFindings.push(...scanSecurityDocPrStatus(content, relPath));
-  }
-
-  for (const relPath of BUNDLE_BUDGET_DOCS) {
-    const abs = join(root, relPath);
-    let content;
-    try {
-      content = readFileSync(abs, 'utf8');
-    } catch {
-      allFindings.push(`${relPath} — required current bundle-budget document is missing`);
-      continue;
-    }
-    allFindings.push(...scanBundleBudgetTruth(content, relPath, bundleBudget));
-  }
-
-  // QNBS-v3: current locale help is shipped to users, so every active locale must carry the same budget truth.
-  for (const locale of getLocales()) {
-    const relPath = `locales/${locale}/help.json`;
-    const abs = join(root, relPath);
-    let content;
-    try {
-      content = readFileSync(abs, 'utf8');
-    } catch {
-      allFindings.push(`${relPath} — required current in-app help document is missing`);
-      continue;
-    }
-    allFindings.push(...scanLocalizedBundleBudgetTruth(content, relPath, bundleBudget));
-  }
+  // QNBS-v3 (codex): these two files are this gate's required subjects — silently skipping a missing/unreadable one would make the live-status enforcement disappear exactly when its input is unavailable, the same failure mode as the bundle-budget docs below.
+  allFindings.push(
+    ...scanRequiredFiles(TARGET_FILES, (content, relPath) =>
+      scanForDrift(content, relPath, { localeCount, keyCount, latestVersion }),
+    ),
+    ...scanRequiredFiles(URL_CHECK_FILES, (content, relPath) =>
+      scanForUrlDrift(content, relPath, canonicalUrl),
+    ),
+    ...scanRequiredFiles(
+      SECURITY_STATUS_DOCS,
+      scanSecurityDocPrStatus,
+      (relPath) => `${relPath} — required security-status document is missing or unreadable`,
+    ),
+    ...scanRequiredFiles(
+      BUNDLE_BUDGET_DOCS,
+      (content, relPath) => scanBundleBudgetTruth(content, relPath, bundleBudget),
+      (relPath) => `${relPath} — required current bundle-budget document is missing`,
+    ),
+    // QNBS-v3: current locale help is shipped to users, so every active locale must carry the same budget truth.
+    ...scanRequiredFiles(
+      getLocales().map((locale) => `locales/${locale}/help.json`),
+      (content, relPath) => scanLocalizedBundleBudgetTruth(content, relPath, bundleBudget),
+      (relPath) => `${relPath} — required current in-app help document is missing`,
+    ),
+  );
 
   if (allFindings.length > 0) {
     process.stderr.write(

From 7d88df9844b134c00896daf728d4fbe8d7915b6f Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 11:31:19 +0200
Subject: [PATCH 11/15] fix(docs): classify branch-local commits by ancestry,
 guard negation polarity, restrict PR matches to entries

- getBranchLocalSubjectIndices replaces the positional branchLocalCount
  heuristic with a per-commit git merge-base --is-ancestor check, so an
  interleaved main commit (from a branch that merged main back in) is
  never misclassified as branch-local.
- candidateEntryIndices now disqualifies a changelog entry whose negation
  polarity (not/never/no longer/...) differs from the commit description's,
  so a negated commit can no longer slug-match its semantic opposite.
- classifyGovernedCommit checks parsed [Unreleased] bullet entries instead
  of the raw section text, so a PR number mentioned only in surrounding
  prose no longer counts as documentation.
---
 README.md                          |   8 +--
 scripts/check-doc-metrics.d.mts    |   2 +-
 scripts/check-doc-metrics.mjs      |  74 +++++++++++++-------
 tests/unit/checkDocMetrics.test.ts | 106 +++++++++++++++++++++++++----
 4 files changed, 146 insertions(+), 44 deletions(-)

diff --git a/README.md b/README.md
index c10db524b..e934c9b56 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7621%2B_%2F_603_files-22C55E" alt="7621+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7625%2B_%2F_603_files-22C55E" alt="7625+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7621+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7625+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7621+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7625+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7621+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7625+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/scripts/check-doc-metrics.d.mts b/scripts/check-doc-metrics.d.mts
index 6bda6c358..fdedca18f 100644
--- a/scripts/check-doc-metrics.d.mts
+++ b/scripts/check-doc-metrics.d.mts
@@ -18,7 +18,7 @@ export function scanUnreleasedTruth(
   packageVersion?: string,
   taggedVersions?: Set<string>,
   isFeatureBranchContext?: boolean,
-  branchLocalCount?: number,
+  branchLocalIndices?: Set<number>,
 ): string[];
 export function scanForDrift(
   content: string,
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index c07655edc..6de769c8e 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -422,13 +422,21 @@ function splitUnreleasedEntries(unreleasedSection) {
   return entries;
 }
 
+// QNBS-v3 (codex): a negated description ("do not delete X") must never slug-match an entry describing the opposite, unnegated action ("Delete X") — word-overlap ratio alone can't tell these apart, so mismatched polarity disqualifies the entry outright, before the ratio is even computed.
+const NEGATION_MARKER = /\b(?:not|never|no longer|cannot|can't|doesn't|don't|won't|isn't)\b/i;
+function hasNegationMarker(text) {
+  return NEGATION_MARKER.test(text);
+}
+
 // QNBS-v3 (codex): the set of entry indices a given commit's slug could match — match ratio is
 // computed PER changelog entry (see findUndocumentedGovernedCommits's header comment for why).
 function candidateEntryIndices(subject, unreleasedEntries) {
   const description = subject.replace(GOVERNED_COMMIT_TYPE, '').replace(TRAILING_PR_REF, '');
   const words = significantSlugWords(description);
   if (words.length === 0) return [];
+  const isNegated = hasNegationMarker(description);
   return unreleasedEntries.flatMap((entry, index) => {
+    if (hasNegationMarker(entry) !== isNegated) return [];
     const matched = words.filter((word) => new RegExp(`\\b${word}\\b`, 'i').test(entry));
     return matched.length / words.length >= SLUG_MATCH_RATIO ? [index] : [];
   });
@@ -485,11 +493,13 @@ function computeMaxSlugMatching(subjects, entries, reservedEntryIndices = new Se
 // completeness for an already-numbered commit sitting in the same range from a separate,
 // already-merged PR, in every context.
 // QNBS-v3 (codex): a branch-local commit's trailing "(#NNN)" may be an in-flight issue reference rather than the real PR number GitHub only appends at squash time, so isBranchLocal skips the exact-PR-match path entirely instead of trusting that number.
+// QNBS-v3 (codex): checks parsed bullet entries, not the raw section text — a PR number mentioned only in surrounding prose (never inside an actual release-note bullet) must not count as documentation.
 // QNBS-v3 (CodeScene): extracted so findUndocumentedGovernedCommits stays a flat loop with zero nested conditionals — returns 'documented', 'undocumented', or 'needsSlugCheck' for one subject.
-function classifyGovernedCommit(subject, unreleasedSection, isFeatureBranchContext, isBranchLocal) {
+function classifyGovernedCommit(subject, entries, isFeatureBranchContext, isBranchLocal) {
   const prMatch = TRAILING_PR_REF.exec(subject);
   if (prMatch && !isBranchLocal) {
-    return isReferencedByPrNumber(prMatch[1], unreleasedSection) ? 'documented' : 'undocumented';
+    const isDocumented = entries.some((entry) => isReferencedByPrNumber(prMatch[1], entry));
+    return isDocumented ? 'documented' : 'undocumented';
   }
   return isFeatureBranchContext ? 'documented' : 'needsSlugCheck';
 }
@@ -505,7 +515,7 @@ function findUndocumentedGovernedCommits(
   postReleaseCommitSubjects,
   unreleasedSection,
   isFeatureBranchContext,
-  branchLocalCount = 0,
+  branchLocalIndices = new Set(),
 ) {
   const entries = splitUnreleasedEntries(unreleasedSection);
   const undocumented = [];
@@ -514,14 +524,9 @@ function findUndocumentedGovernedCommits(
   for (let index = 0; index < postReleaseCommitSubjects.length; index++) {
     const subject = postReleaseCommitSubjects[index];
     if (!GOVERNED_COMMIT_TYPE.test(subject)) continue;
-    const isBranchLocal = index < branchLocalCount;
+    const isBranchLocal = branchLocalIndices.has(index);
     const prMatch = TRAILING_PR_REF.exec(subject);
-    const status = classifyGovernedCommit(
-      subject,
-      unreleasedSection,
-      isFeatureBranchContext,
-      isBranchLocal,
-    );
+    const status = classifyGovernedCommit(subject, entries, isFeatureBranchContext, isBranchLocal);
     if (status === 'undocumented') undocumented.push(subject);
     if (status === 'needsSlugCheck') slugCandidates.push(subject);
     if (status === 'documented' && prMatch && !isBranchLocal)
@@ -573,14 +578,14 @@ export function isOnFeatureBranch(repositoryRoot = root) {
 }
 
 // QNBS-v3 (codex): tries origin/main first (what CI actually has) and falls back to a local main so this still resolves in a plain developer clone.
-function resolveMainBranchPoint(repositoryRoot) {
+function resolveMainRef(repositoryRoot) {
   for (const ref of ['origin/main', 'main']) {
     try {
-      return execFileSync('git', ['merge-base', 'HEAD', ref], {
+      execFileSync('git', ['rev-parse', '--verify', '--quiet', ref], {
         cwd: repositoryRoot,
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'ignore'],
-      }).trim();
+        stdio: 'ignore',
+      });
+      return ref;
     } catch {
       // Try the next candidate ref below.
     }
@@ -588,20 +593,39 @@ function resolveMainBranchPoint(repositoryRoot) {
   return null;
 }
 
-// QNBS-v3 (codex): a branch-local commit's trailing "(#NNN)" may still be an in-flight issue reference, not yet the real PR number GitHub appends at squash time, so counting how many of the newest post-tag commits sit above the main branch point lets the caller exempt exactly those from the exact-PR-match rule.
-export function getBranchLocalCommitCount(repositoryRoot = root) {
-  const branchPoint = resolveMainBranchPoint(repositoryRoot);
-  if (!branchPoint) return 0;
+// QNBS-v3 (codex): a merge-base cutoff plus a positional window mis-splits history once the branch has merged main back in — git log's default order can interleave an already-merged main commit between branch-local ones — so each commit's OWN ancestry (merge-base --is-ancestor against main) is checked individually instead.
+export function getBranchLocalSubjectIndices(repositoryRoot = root) {
+  const taggedVersions = getTaggedVersions(repositoryRoot);
+  const latestTagged = [...taggedVersions].sort(semverCompare).at(-1);
+  const mainRef = resolveMainRef(repositoryRoot);
+  if (!latestTagged || !mainRef) return new Set();
+  let shas;
   try {
-    const output = execFileSync('git', ['rev-list', '--count', `${branchPoint}..HEAD`], {
+    const output = execFileSync('git', ['log', '--format=%H', `v${latestTagged}..HEAD`], {
       cwd: repositoryRoot,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
     });
-    return Number.parseInt(output.trim(), 10) || 0;
+    shas = output
+      .split('\n')
+      .map((sha) => sha.trim())
+      .filter(Boolean);
   } catch {
-    return 0;
+    return new Set();
   }
+  const branchLocalIndices = new Set();
+  shas.forEach((sha, index) => {
+    try {
+      execFileSync('git', ['merge-base', '--is-ancestor', sha, mainRef], {
+        cwd: repositoryRoot,
+        stdio: 'ignore',
+      });
+    } catch {
+      // Non-zero exit means sha is not an ancestor of mainRef — it is branch-local.
+      branchLocalIndices.add(index);
+    }
+  });
+  return branchLocalIndices;
 }
 
 // QNBS-v3: isFeatureBranchContext deliberately has a plain `false` default, not one read from
@@ -618,7 +642,7 @@ export function scanUnreleasedTruth(
   packageVersion,
   taggedVersions,
   isFeatureBranchContext = false,
-  branchLocalCount = 0,
+  branchLocalIndices = new Set(),
 ) {
   if (!postReleaseCommitSubjects || postReleaseCommitSubjects.length === 0) return [];
   const candidateVersion = changelog.match(
@@ -645,7 +669,7 @@ export function scanUnreleasedTruth(
     postReleaseCommitSubjects,
     unreleasedSection,
     isFeatureBranchContext,
-    branchLocalCount,
+    branchLocalIndices,
   );
   if (undocumented.length === 0) return [];
   return [
@@ -1013,7 +1037,7 @@ function main() {
       packageVersion,
       taggedVersions,
       isFeatureBranchContext,
-      isFeatureBranchContext ? getBranchLocalCommitCount() : 0,
+      isFeatureBranchContext ? getBranchLocalSubjectIndices() : new Set(),
     ),
   );
   allFindings.push(
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index 95bd5f22d..e5e3a8860 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -33,10 +33,11 @@ type ReleaseTruthModule = {
     packageVersion?: string,
     taggedVersions?: Set<string>,
     isFeatureBranchContext?: boolean,
-    branchLocalCount?: number,
+    branchLocalIndices?: Set<number>,
   ) => string[];
   isOnFeatureBranch: (repositoryRoot?: string) => boolean;
-  getBranchLocalCommitCount: (repositoryRoot?: string) => number;
+  getBranchLocalSubjectIndices: (repositoryRoot?: string) => Set<number>;
+  getPostReleaseCommitSubjects: (repositoryRoot?: string) => string[] | null;
 };
 // QNBS-v3: load the runtime-only scanners without making tsgo infer untyped .mjs exports.
 const loadReleaseTruthModule = async () =>
@@ -459,6 +460,29 @@ describe('Unreleased truth', () => {
       expect(findingsReversed).toEqual([]);
     });
 
+    // QNBS-v3 (codex): a negated commit description must never slug-match an entry describing the opposite, unnegated action — ratio-based word overlap alone can't tell "do not delete X" from "Delete X".
+    it('does not let a negated commit description slug-match an entry with the opposite polarity', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Delete malformed project data during import.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): do not delete malformed project data',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('do not delete malformed project data');
+    });
+
+    // QNBS-v3: a genuinely negated entry documenting the negated behavior must still match normally.
+    it('still slug-matches when both the commit and the entry share the same negated polarity', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Do not delete malformed project data during import.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): do not delete malformed project data',
+      ]);
+      expect(findings).toEqual([]);
+    });
+
     // QNBS-v3 (codex): a numbered commit has an unambiguous way to be referenced — it must not
     // fall back to a fuzzy slug match against a different, older bullet that merely shares words.
     it('requires the exact PR number for a numbered commit, never a slug fallback', async () => {
@@ -472,6 +496,18 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('#999');
     });
 
+    // QNBS-v3 (codex): a PR number mentioned only in surrounding prose, never inside an actual release-note bullet, must not count as documentation.
+    it('does not treat a PR number mentioned in non-bullet prose as documentation', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\nFor context see #999.\n\n- Unrelated doc sync.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): resolve unrelated regression (#999)',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('#999');
+    });
+
     // QNBS-v3 (codex): a numbered commit's exact-PR-number match must reserve its entry, otherwise an unrelated un-numbered commit's slug match can silently reuse the same bullet.
     it("does not let a numbered commit's entry double as an unrelated commit's slug match", async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();
@@ -555,7 +591,7 @@ describe('Unreleased truth', () => {
         undefined,
         undefined,
         true,
-        1,
+        new Set([0]),
       );
       expect(findings).toEqual([]);
     });
@@ -572,7 +608,7 @@ describe('Unreleased truth', () => {
         undefined,
         undefined,
         true,
-        1,
+        new Set([0]),
       );
       expect(findings).toHaveLength(1);
       expect(findings[0]).toContain('#999');
@@ -657,7 +693,7 @@ describe('isOnFeatureBranch', () => {
   });
 });
 
-describe('getBranchLocalCommitCount', () => {
+describe('getBranchLocalSubjectIndices', () => {
   function initTempRepo(prefix: string): string {
     const repositoryRoot = mkdtempSync(join(process.cwd(), prefix));
     execFileSync('git', ['init', '--quiet', '--initial-branch=main', repositoryRoot]);
@@ -666,6 +702,7 @@ describe('getBranchLocalCommitCount', () => {
     writeFileSync(join(repositoryRoot, 'file.txt'), 'content');
     execFileSync('git', ['-C', repositoryRoot, 'add', 'file.txt']);
     execFileSync('git', ['-C', repositoryRoot, 'commit', '--quiet', '-m', 'init']);
+    execFileSync('git', ['-C', repositoryRoot, 'tag', '-m', 'v1.0.0', 'v1.0.0']);
     return repositoryRoot;
   }
 
@@ -675,37 +712,78 @@ describe('getBranchLocalCommitCount', () => {
     execFileSync('git', ['-C', repositoryRoot, 'commit', '--quiet', '-m', message]);
   }
 
-  it('returns 0 on main itself', async () => {
-    const { getBranchLocalCommitCount } = await loadReleaseTruthModule();
+  it('returns an empty set on main itself', async () => {
+    const { getBranchLocalSubjectIndices } = await loadReleaseTruthModule();
     const repositoryRoot = initTempRepo('.tmp-worldscript-doc-metrics-branchlocal-main-');
     try {
-      expect(getBranchLocalCommitCount(repositoryRoot)).toBe(0);
+      expect(getBranchLocalSubjectIndices(repositoryRoot)).toEqual(new Set());
     } finally {
       rmSync(repositoryRoot, { recursive: true, force: true });
     }
   });
 
   // QNBS-v3: mirrors this repository's own feat/553-universal-ingress-admission, several commits ahead of main with no open PR yet.
-  it('counts commits unique to a feature branch since it diverged from main', async () => {
-    const { getBranchLocalCommitCount } = await loadReleaseTruthModule();
+  it('identifies commits unique to a feature branch since it diverged from main', async () => {
+    const { getPostReleaseCommitSubjects, getBranchLocalSubjectIndices } =
+      await loadReleaseTruthModule();
     const repositoryRoot = initTempRepo('.tmp-worldscript-doc-metrics-branchlocal-feature-');
     try {
       execFileSync('git', ['-C', repositoryRoot, 'switch', '--quiet', '-c', 'fix/example']);
       addCommit(repositoryRoot, 'first');
       addCommit(repositoryRoot, 'second');
-      expect(getBranchLocalCommitCount(repositoryRoot)).toBe(2);
+      const subjects = getPostReleaseCommitSubjects(repositoryRoot) ?? [];
+      const branchLocalIndices = getBranchLocalSubjectIndices(repositoryRoot);
+      expect(branchLocalIndices.size).toBe(2);
+      expect([...branchLocalIndices].every((index) => subjects[index] !== undefined)).toBe(true);
+    } finally {
+      rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+  });
+
+  // QNBS-v3 (codex): git log's default order can interleave an already-merged main commit between branch-local ones once the branch has merged main in — the prior positional "newest N" window misclassified both sides here.
+  it('classifies each commit by ancestry, not log position, once the branch has merged main in', async () => {
+    const { getPostReleaseCommitSubjects, getBranchLocalSubjectIndices } =
+      await loadReleaseTruthModule();
+    const repositoryRoot = initTempRepo('.tmp-worldscript-doc-metrics-branchlocal-merge-');
+    try {
+      execFileSync('git', ['-C', repositoryRoot, 'switch', '--quiet', '-c', 'fix/example']);
+      addCommit(repositoryRoot, 'branch1');
+      execFileSync('git', ['-C', repositoryRoot, 'switch', '--quiet', 'main']);
+      addCommit(repositoryRoot, 'main-new');
+      execFileSync('git', ['-C', repositoryRoot, 'switch', '--quiet', 'fix/example']);
+      execFileSync('git', [
+        '-C',
+        repositoryRoot,
+        'merge',
+        '--no-ff',
+        '--quiet',
+        '-m',
+        'merge-main',
+        'main',
+      ]);
+      addCommit(repositoryRoot, 'branch2');
+
+      const subjects = getPostReleaseCommitSubjects(repositoryRoot) ?? [];
+      const branchLocalIndices = getBranchLocalSubjectIndices(repositoryRoot);
+      const mainNewIndex = subjects.indexOf('main-new');
+      const branch1Index = subjects.indexOf('branch1');
+
+      expect(mainNewIndex).toBeGreaterThanOrEqual(0);
+      expect(branch1Index).toBeGreaterThanOrEqual(0);
+      expect(branchLocalIndices.has(mainNewIndex)).toBe(false);
+      expect(branchLocalIndices.has(branch1Index)).toBe(true);
     } finally {
       rmSync(repositoryRoot, { recursive: true, force: true });
     }
   });
 
-  it('fails closed to 0 when not a git repository', async () => {
-    const { getBranchLocalCommitCount } = await loadReleaseTruthModule();
+  it('fails closed to an empty set when not a git repository', async () => {
+    const { getBranchLocalSubjectIndices } = await loadReleaseTruthModule();
     const repositoryRoot = mkdtempSync(
       join(tmpdir(), 'worldscript-doc-metrics-branchlocal-nogit-'),
     );
     try {
-      expect(getBranchLocalCommitCount(repositoryRoot)).toBe(0);
+      expect(getBranchLocalSubjectIndices(repositoryRoot)).toEqual(new Set());
     } finally {
       rmSync(repositoryRoot, { recursive: true, force: true });
     }

From 231421e9cbfdc76c799b71fe59bfafe56c9116bf Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 12:04:20 +0200
Subject: [PATCH 12/15] fix(docs): reject PR-number-boundary letters,
 typographic apostrophes, and multi-entry reservation gaps

- isReferencedByPrNumber now rejects any word-character continuation after
  the PR number (not just a digit), so a hex-color-like token such as
  #999abc no longer satisfies an exact reference to PR #999.
- NEGATION_MARKER now matches typographic apostrophes (don't) alongside
  straight ones, so a curly-quote contraction is still recognized as negation.
- reserveEntryForNumberedCommit reserves every changelog entry referencing a
  numbered commit's PR, not just the first match, closing a gap where a
  second entry for the same PR was free for an unrelated slug match.
- getBranchLocalSubjectIndices now only classifies a commit as branch-local
  on git's documented exit code 1 (confirmed non-ancestor); any other
  merge-base failure fails closed to the stricter, non-exempted path.
- Corrected a stale comment that no longer matched the scanRequiredFiles
  calls it was describing after they were consolidated.
---
 README.md                          |  8 +++----
 scripts/check-doc-metrics.mjs      | 21 +++++++++--------
 tests/unit/checkDocMetrics.test.ts | 37 ++++++++++++++++++++++++++++++
 3 files changed, 52 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index e934c9b56..4194c6d8a 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7625%2B_%2F_603_files-22C55E" alt="7625+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7628%2B_%2F_603_files-22C55E" alt="7628+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7625+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7628+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7625+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7628+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7625+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7628+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index 6de769c8e..ac35fbf66 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -395,7 +395,7 @@ function significantSlugWords(description) {
 // "#656" (and vice versa) since one is a substring of the other — require a non-digit boundary on
 // both sides so only the exact PR number counts.
 function isReferencedByPrNumber(prNumber, unreleasedSection) {
-  return new RegExp(`(?:^|\\D)#${prNumber}(?!\\d)`).test(unreleasedSection);
+  return new RegExp(`(?:^|\\D)#${prNumber}(?!\\w)`).test(unreleasedSection);
 }
 
 // QNBS-v3 (codex): a Markdown bullet may wrap across several physical lines — join a bullet's own
@@ -423,7 +423,8 @@ function splitUnreleasedEntries(unreleasedSection) {
 }
 
 // QNBS-v3 (codex): a negated description ("do not delete X") must never slug-match an entry describing the opposite, unnegated action ("Delete X") — word-overlap ratio alone can't tell these apart, so mismatched polarity disqualifies the entry outright, before the ratio is even computed.
-const NEGATION_MARKER = /\b(?:not|never|no longer|cannot|can't|doesn't|don't|won't|isn't)\b/i;
+const NEGATION_MARKER =
+  /\b(?:not|never|no longer|cannot|can[’']t|doesn[’']t|don[’']t|won[’']t|isn[’']t)\b/i;
 function hasNegationMarker(text) {
   return NEGATION_MARKER.test(text);
 }
@@ -504,11 +505,11 @@ function classifyGovernedCommit(subject, entries, isFeatureBranchContext, isBran
   return isFeatureBranchContext ? 'documented' : 'needsSlugCheck';
 }
 
-// QNBS-v3 (codex): reserves a numbered commit's entry so it can't silently double as an unrelated commit's own slug-matched documentation — an entry bundling several PR numbers is reserved once per number, which is idempotent since they all resolve to the same index.
+// QNBS-v3 (codex): reserves EVERY entry referencing the numbered commit, not just the first — a PR number split across multiple bullets must not leave a later one free for an unrelated commit's slug match.
 function reserveEntryForNumberedCommit(prNumber, entries, reservedEntryIndices) {
-  const entryIndex = entries.findIndex((entry) => isReferencedByPrNumber(prNumber, entry));
-  if (entryIndex === -1) return;
-  reservedEntryIndices.add(entryIndex);
+  entries.forEach((entry, index) => {
+    if (isReferencedByPrNumber(prNumber, entry)) reservedEntryIndices.add(index);
+  });
 }
 
 function findUndocumentedGovernedCommits(
@@ -620,9 +621,9 @@ export function getBranchLocalSubjectIndices(repositoryRoot = root) {
         cwd: repositoryRoot,
         stdio: 'ignore',
       });
-    } catch {
-      // Non-zero exit means sha is not an ancestor of mainRef — it is branch-local.
-      branchLocalIndices.add(index);
+    } catch (error) {
+      // QNBS-v3 (codex): only git's exit-1 confirms "not an ancestor" (branch-local); any other failure can't determine ancestry, so it fails closed to the stricter, non-exempted path.
+      if (error.status === 1) branchLocalIndices.add(index);
     }
   });
   return branchLocalIndices;
@@ -1045,7 +1046,7 @@ function main() {
   );
   allFindings.push(...scanReadmeTestMetrics(readFileSync(join(root, 'README.md'), 'utf8')));
 
-  // QNBS-v3 (codex): these two files are this gate's required subjects — silently skipping a missing/unreadable one would make the live-status enforcement disappear exactly when its input is unavailable, the same failure mode as the bundle-budget docs below.
+  // QNBS-v3 (codex): TARGET_FILES and URL_CHECK_FILES below pass no fallback message, so silently skipping a missing/unreadable file here would make live-status enforcement disappear exactly when its input is unavailable — the failure mode the explicit fallback messages below already guard against.
   allFindings.push(
     ...scanRequiredFiles(TARGET_FILES, (content, relPath) =>
       scanForDrift(content, relPath, { localeCount, keyCount, latestVersion }),
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index e5e3a8860..b48c26fa5 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -483,6 +483,18 @@ describe('Unreleased truth', () => {
       expect(findings).toEqual([]);
     });
 
+    // QNBS-v3 (codex): a typographic apostrophe ("don't") must be recognized as negation too, or the tokenizer turns it into the unmatched word "don" and the remaining words alone can clear the ratio against the opposite-polarity entry.
+    it('recognizes a typographic apostrophe as negation', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Delete malformed project data during import.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): don’t delete malformed project data',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('delete malformed project data');
+    });
+
     // QNBS-v3 (codex): a numbered commit has an unambiguous way to be referenced — it must not
     // fall back to a fuzzy slug match against a different, older bullet that merely shares words.
     it('requires the exact PR number for a numbered commit, never a slug fallback', async () => {
@@ -508,6 +520,18 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('#999');
     });
 
+    // QNBS-v3 (codex): a hex-color-like token such as "#999abc" must not satisfy an exact reference to PR #999 — the boundary must reject a letter continuation, not just a digit.
+    it('does not treat a hex-color-like token as a reference to a PR number', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Update accent color token to #999abc for contrast.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): resolve unrelated regression (#999)',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('#999');
+    });
+
     // QNBS-v3 (codex): a numbered commit's exact-PR-number match must reserve its entry, otherwise an unrelated un-numbered commit's slug match can silently reuse the same bullet.
     it("does not let a numbered commit's entry double as an unrelated commit's slug match", async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();
@@ -521,6 +545,19 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('reuse canonical document projection foundation');
     });
 
+    // QNBS-v3 (codex): the same PR number split across two separate bullets must reserve BOTH, not just the first findIndex() hit — otherwise an unrelated commit's slug match can claim the un-reserved second bullet.
+    it('reserves every entry referencing the same numbered commit, not just the first', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Canonical document projection foundation. PR #999.\n- Canonical document projection foundation restated. PR #999.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): canonical document projection foundation (#999)',
+        'fix(project): reuse canonical document projection foundation',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('reuse canonical document projection foundation');
+    });
+
     // QNBS-v3 (codex): an entry listing several PR numbers still reserves for each, so it must keep refusing an unrelated commit's slug match.
     it('reserves an entry that lists multiple PR numbers, still blocking an unrelated slug match', async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();

From bb55dfb66b9989db46c71f888e8dd0d15e0944eb Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 12:36:20 +0200
Subject: [PATCH 13/15] fix(docs): recognize avoidance-verb negation and stop
 truncating slug words

- NEGATION_MARKER now also matches avoid/prevent (and their inflections),
  so a preserve-first commit worded without a literal not/never still
  gets polarity-guarded against an opposite-meaning changelog entry.
- significantSlugWords no longer truncates to the first six words; a
  truncated word list could let a partial-overlap ratio wrongly clear the
  60% threshold when the full word list would correctly fall below it.
---
 README.md                          |  8 ++++----
 scripts/check-doc-metrics.mjs      | 10 +++-------
 tests/unit/checkDocMetrics.test.ts | 24 ++++++++++++++++++++++++
 3 files changed, 31 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 4194c6d8a..7435e851e 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7628%2B_%2F_603_files-22C55E" alt="7628+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7630%2B_%2F_603_files-22C55E" alt="7630+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7628+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7630+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7628+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7630+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7628+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7630+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index ac35fbf66..b4c24a97b 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -376,10 +376,7 @@ const SLUG_STOP_WORDS = new Set([
   'that',
   'not',
 ]);
-// QNBS-v3: a commit not merged via the standard squash flow (no trailing "(#NNN)") has nothing to
-// key off but its own wording — require most of a bounded set of its most identifying words to
-// appear in [Unreleased], rather than an exact-sentence match this file's other scanners avoid.
-const SLUG_WORD_COUNT = 6;
+// QNBS-v3 (codex): a commit not merged via the standard squash flow has nothing to key off but its own wording — require most of its significant words to appear in [Unreleased] rather than an exact-sentence match, and never truncate the word list, since a dropped trailing word can be the one that discriminates against an opposite-meaning entry.
 const SLUG_MATCH_RATIO = 0.6;
 
 function significantSlugWords(description) {
@@ -387,8 +384,7 @@ function significantSlugWords(description) {
     .toLowerCase()
     .replace(/[^a-z0-9\s]/g, ' ')
     .split(/\s+/)
-    .filter((word) => word.length > 2 && !SLUG_STOP_WORDS.has(word))
-    .slice(0, SLUG_WORD_COUNT);
+    .filter((word) => word.length > 2 && !SLUG_STOP_WORDS.has(word));
 }
 
 // QNBS-v3 (coderabbit/CodeAnt): a bare String.includes let "#65" incorrectly satisfy a check for
@@ -424,7 +420,7 @@ function splitUnreleasedEntries(unreleasedSection) {
 
 // QNBS-v3 (codex): a negated description ("do not delete X") must never slug-match an entry describing the opposite, unnegated action ("Delete X") — word-overlap ratio alone can't tell these apart, so mismatched polarity disqualifies the entry outright, before the ratio is even computed.
 const NEGATION_MARKER =
-  /\b(?:not|never|no longer|cannot|can[’']t|doesn[’']t|don[’']t|won[’']t|isn[’']t)\b/i;
+  /\b(?:not|never|no longer|cannot|can[’']t|doesn[’']t|don[’']t|won[’']t|isn[’']t|avoid(?:s|ed|ing)?|prevent(?:s|ed|ing)?)\b/i;
 function hasNegationMarker(text) {
   return NEGATION_MARKER.test(text);
 }
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index b48c26fa5..ff23ce2e1 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -495,6 +495,30 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('delete malformed project data');
     });
 
+    // QNBS-v3 (codex): "avoid"/"prevent" express negative polarity without any literal not/never — a preserve-first commit worded this way must not slug-match an entry describing the opposite, unguarded action.
+    it('treats avoidance verbs like "prevent" as negative polarity', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Delete malformed project data during import.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): prevent deleting malformed project data',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('prevent deleting malformed project data');
+    });
+
+    // QNBS-v3 (codex): truncating a long subject's significant words to the first six could drop trailing words entirely, letting a truncated 66%-overlap ratio wrongly clear the 60% threshold when the full word list would correctly fall below it.
+    it('does not drop trailing significant words that would prevent a false slug match', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Alpha beta gamma delta refactor summary.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): alpha beta gamma delta epsilon zeta eta',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('alpha beta gamma delta epsilon zeta eta');
+    });
+
     // QNBS-v3 (codex): a numbered commit has an unambiguous way to be referenced — it must not
     // fall back to a fuzzy slug match against a different, older bullet that merely shares words.
     it('requires the exact PR number for a numbered commit, never a slug fallback', async () => {

From 0260f0cb95d11941614cb9618eab2969941d81bd Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 13:14:32 +0200
Subject: [PATCH 14/15] fix(docs): scope branch-local exemption to actual
 locality, extend refusal-verb polarity, preserve short discriminator tokens
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- classifyGovernedCommit's un-numbered exemption now requires isBranchLocal
  too, not isFeatureBranchContext alone, so a commit already reachable from
  main can no longer get a free pass just because the checkout is on a
  feature branch.
- NEGATION_MARKER now also covers refuse/stop/disable (and inflections).
- hasNegationMarker now scopes its check to an entry's **bold** lead claim
  when present (this file's own changelog convention for the actual
  documented change), so a negation word in trailing rationale/context
  prose no longer disqualifies an otherwise-matching entry — found via a
  real false positive this fix produced against this repo's own CHANGELOG.
- significantSlugWords no longer discards a short alphanumeric token (a
  version, a limit) purely for being <=2 characters when it contains a
  digit.

Residual, intentionally out of scope: a short token that IS retained (e.g.
"v2" vs "v1") can still clear the 60% overlap ratio in a longer sentence
where only that one token differs, the same structural tolerance already
documented for the wave-3 truncation fix. Closing that fully would require
identifier-aware or antonym-pair comparison, which is the general semantic
parsing this file's design explicitly avoids.
---
 README.md                          |  8 ++--
 scripts/check-doc-metrics.mjs      | 11 ++++--
 tests/unit/checkDocMetrics.test.ts | 62 ++++++++++++++++++++++++++++++
 3 files changed, 73 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 7435e851e..eaa9d7f45 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Storage-IndexedDB_v8-F59E0B" alt="IndexedDB v8">
   <img src="https://img.shields.io/badge/PWA-v3.0-5BB974?logo=pwa" alt="PWA v3.0">
   <img src="https://img.shields.io/badge/i18n-19_locales-2942_keys-0EA5E9" alt="i18n 19 locales — 2942 keys">
-  <img src="https://img.shields.io/badge/Tests-7630%2B_%2F_603_files-22C55E" alt="7630+ tests / 603 files">
+  <img src="https://img.shields.io/badge/Tests-7635%2B_%2F_603_files-22C55E" alt="7635+ tests / 603 files">
   <img src="https://img.shields.io/codecov/c/github/qnbs/WorldScript-Studio?logo=codecov&label=Coverage" alt="Codecov Coverage">
   <img src="https://img.shields.io/badge/License-MIT-22C55E" alt="License MIT">
   <img src="https://img.shields.io/github/actions/workflow/status/qnbs/WorldScript-Studio/.github/workflows/ci.yml?branch=main&logo=github" alt="CI Status">
@@ -511,7 +511,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
 | **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2942 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
-| **Testing**          | Vitest 4.x (7630+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
+| **Testing**          | Vitest 4.x (7635+ tests / 603 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
 | **Desktop**          | Tauri v2                                                  | Cross-platform installer; auto-updater via `latest.json`             |
@@ -549,7 +549,7 @@ WorldScript-Studio/
 │   ├── sw.js             # PWA Service Worker
 │   └── manifest.json     # PWA Web App Manifest v3
 ├── tests/
-│   ├── unit/             # Vitest unit tests (7630+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
+│   ├── unit/             # Vitest unit tests (7635+ tests, 603 files) — count spans tests/, components/, packages/*/tests/, not just this folder
 │   │   ├── ai/           # aiSmallModules, aiCoreFallbackPaths
 │   │   └── settings/     # WebLlmPanel, AiSections
 │   └── e2e/              # Playwright specs + helpers.ts
@@ -714,7 +714,7 @@ The main pipeline is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Opt
 Raw bundle-budget ceilings (KB per uncompressed asset): entry **2500 KB**, vendor **6200 KB**, other JavaScript **2500 KB**, and WASM **30000 KB**.
 
 **Current test metrics (2026-09-07, source-synchronized; CI remains authoritative for pass/fail):**
-- **7630+ unit tests** across **603 test files** — CI is authoritative for pass/fail
+- **7635+ unit tests** across **603 test files** — CI is authoritative for pass/fail
 - Coverage thresholds: lines ≥ 80 · branches ≥ 66 · functions ≥ 72 · statements ≥ 78 — enforced in CI (see Codecov badge for live metrics)
 - i18n: **2942 keys × 19 locales** (en/de/fr/es/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta)
 
diff --git a/scripts/check-doc-metrics.mjs b/scripts/check-doc-metrics.mjs
index b4c24a97b..07cb09a87 100644
--- a/scripts/check-doc-metrics.mjs
+++ b/scripts/check-doc-metrics.mjs
@@ -379,12 +379,13 @@ const SLUG_STOP_WORDS = new Set([
 // QNBS-v3 (codex): a commit not merged via the standard squash flow has nothing to key off but its own wording — require most of its significant words to appear in [Unreleased] rather than an exact-sentence match, and never truncate the word list, since a dropped trailing word can be the one that discriminates against an opposite-meaning entry.
 const SLUG_MATCH_RATIO = 0.6;
 
+// QNBS-v3 (codex): a short alphanumeric token like "v2" or "10" can be the only thing distinguishing a change (a version, a limit, a count) — the length filter must not discard it just because it has no letters to spare.
 function significantSlugWords(description) {
   return description
     .toLowerCase()
     .replace(/[^a-z0-9\s]/g, ' ')
     .split(/\s+/)
-    .filter((word) => word.length > 2 && !SLUG_STOP_WORDS.has(word));
+    .filter((word) => (word.length > 2 || /\d/.test(word)) && !SLUG_STOP_WORDS.has(word));
 }
 
 // QNBS-v3 (coderabbit/CodeAnt): a bare String.includes let "#65" incorrectly satisfy a check for
@@ -420,9 +421,11 @@ function splitUnreleasedEntries(unreleasedSection) {
 
 // QNBS-v3 (codex): a negated description ("do not delete X") must never slug-match an entry describing the opposite, unnegated action ("Delete X") — word-overlap ratio alone can't tell these apart, so mismatched polarity disqualifies the entry outright, before the ratio is even computed.
 const NEGATION_MARKER =
-  /\b(?:not|never|no longer|cannot|can[’']t|doesn[’']t|don[’']t|won[’']t|isn[’']t|avoid(?:s|ed|ing)?|prevent(?:s|ed|ing)?)\b/i;
+  /\b(?:not|never|no longer|cannot|can[’']t|doesn[’']t|don[’']t|won[’']t|isn[’']t|avoid(?:s|ed|ing)?|prevent(?:s|ed|ing)?|refuse[sd]?|refusing|stop(?:s|ped|ping)?|disable[sd]?|disabling)\b/i;
+// QNBS-v3 (codex): a negation word in an entry's rationale/context prose after its **bold** lead claim (this file's own convention for the actual change being documented) must not disqualify the match — only the bold lead's own polarity is checked when one exists.
 function hasNegationMarker(text) {
-  return NEGATION_MARKER.test(text);
+  const boldLead = text.match(/\*\*(.+?)\*\*/);
+  return NEGATION_MARKER.test(boldLead ? boldLead[1] : text);
 }
 
 // QNBS-v3 (codex): the set of entry indices a given commit's slug could match — match ratio is
@@ -498,7 +501,7 @@ function classifyGovernedCommit(subject, entries, isFeatureBranchContext, isBran
     const isDocumented = entries.some((entry) => isReferencedByPrNumber(prMatch[1], entry));
     return isDocumented ? 'documented' : 'undocumented';
   }
-  return isFeatureBranchContext ? 'documented' : 'needsSlugCheck';
+  return isFeatureBranchContext && isBranchLocal ? 'documented' : 'needsSlugCheck';
 }
 
 // QNBS-v3 (codex): reserves EVERY entry referencing the numbered commit, not just the first — a PR number split across multiple bullets must not leave a later one free for an unrelated commit's slug match.
diff --git a/tests/unit/checkDocMetrics.test.ts b/tests/unit/checkDocMetrics.test.ts
index ff23ce2e1..d3c69337c 100644
--- a/tests/unit/checkDocMetrics.test.ts
+++ b/tests/unit/checkDocMetrics.test.ts
@@ -483,6 +483,28 @@ describe('Unreleased truth', () => {
       expect(findings).toEqual([]);
     });
 
+    // QNBS-v3 (codex): a negation word in an entry's rationale prose AFTER its **bold** lead claim must not disqualify the match — this repo's own CHANGELOG.md has real entries where the bold lead states the change and trailing prose incidentally uses a word like "cannot" to describe unrelated circumstances.
+    it("does not let a negation word in an entry's rationale prose outside its bold lead disqualify the match", async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- **Unsupported-project startup copy added** so a build that cannot open the project shows its own message.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(i18n): add unsupported-project startup copy',
+      ]);
+      expect(findings).toEqual([]);
+    });
+
+    // QNBS-v3 (codex): negation inside the bold lead itself must still be detected — the scoping must narrow the check, not silently disable it.
+    it('still detects negation inside the bold lead itself', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- **Do not delete malformed project data** during import.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): do not delete malformed project data',
+      ]);
+      expect(findings).toEqual([]);
+    });
+
     // QNBS-v3 (codex): a typographic apostrophe ("don't") must be recognized as negation too, or the tokenizer turns it into the unmatched word "don" and the remaining words alone can clear the ratio against the opposite-polarity entry.
     it('recognizes a typographic apostrophe as negation', async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();
@@ -507,6 +529,27 @@ describe('Unreleased truth', () => {
       expect(findings[0]).toContain('prevent deleting malformed project data');
     });
 
+    // QNBS-v3 (codex): "refuse"/"stop"/"disable" are further negative-polarity refusal verbs beyond avoid/prevent.
+    it('treats refusal verbs like "refuse" as negative polarity', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog =
+        '## [Unreleased]\n\n### Fixed\n\n- Delete malformed project data during import.\n';
+      const findings = scanUnreleasedTruth(changelog, [
+        'fix(project): refuse to delete malformed project data',
+      ]);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('refuse to delete malformed project data');
+    });
+
+    // QNBS-v3 (codex): a short alphanumeric token (a version, a limit) can be the only significant word distinguishing a short subject — the length filter must not silently drop it from the comparison.
+    it('preserves a short numeric token that is the only other significant word', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const changelog = '## [Unreleased]\n\n### Fixed\n\n- Retry 20.\n';
+      const findings = scanUnreleasedTruth(changelog, ['fix(project): retry 10']);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('retry 10');
+    });
+
     // QNBS-v3 (codex): truncating a long subject's significant words to the first six could drop trailing words entirely, letting a truncated 66%-overlap ratio wrongly clear the 60% threshold when the full word list would correctly fall below it.
     it('does not drop trailing significant words that would prevent a false slug match', async () => {
       const { scanUnreleasedTruth } = await loadReleaseTruthModule();
@@ -622,10 +665,29 @@ describe('Unreleased truth', () => {
         undefined,
         undefined,
         true,
+        new Set([0]),
       );
       expect(findings).toEqual([]);
     });
 
+    // QNBS-v3 (codex): the un-numbered exemption must key off the computed branch-local set, not the overall pull_request context alone — an unnumbered commit that is NOT branch-local (already reachable from main) must still go through the normal slug check.
+    it('does not exempt an unnumbered commit that is not actually branch-local, even in pull_request CI context', async () => {
+      const { scanUnreleasedTruth } = await loadReleaseTruthModule();
+      const findings = scanUnreleasedTruth(
+        populatedButUnrelated,
+        [
+          'fix(project): retain raw header verdict on projection failure',
+          'fix(project): apply an unrelated branch-local adjustment',
+        ],
+        undefined,
+        undefined,
+        true,
+        new Set([1]),
+      );
+      expect(findings).toHaveLength(1);
+      expect(findings[0]).toContain('retain raw header verdict on projection failure');
+    });
+
     // QNBS-v3 (codex, P1): exempting a PR's own in-flight commits must not weaken enforcement for
     // an already-numbered commit sitting in the same range (e.g. from a separate, already-merged
     // PR) — that one is real, permanent history and must still be caught even during a

From b9a497710fdf5df0c38b690c194ff7418295912b Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Wed, 9 Sep 2026 13:44:38 +0200
Subject: [PATCH 15/15] fix(docs): sync TODO ledger-row-9 enumeration with
 CORE-MIGRATION-LEDGER.md row 9 (4 items, not 3)

---
 TODO.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/TODO.md b/TODO.md
index 0d12e63ff..4ee341ef5 100644
--- a/TODO.md
+++ b/TODO.md
@@ -45,7 +45,7 @@ Status: 🔄 in progress | ⬜ open | ✅ done
   (#618 Slice A persisted schema-version classification, #619 Slice B IDB-load observation, #621
   raw-integer-grammar hardening, #653 the non-destructive `LEGACY_TO_V1` admission primitive, #658
   filesystem-admission convergence) but **still not complete**: durable source-generation fencing,
-  writer integration, and universal ingress/egress remain open per
+  writer integration, universal ingress/egress, and authority switch remain open per
   `docs/native/CORE-MIGRATION-LEDGER.md` row 9. Wave 3/4 R-15 implementation stays blocked
   (`S5_IMPLEMENTATION_READY=NO`, recorded on row 10) until row 9 and `S5_TERMINAL=YES` are both
   true — no target release is set for that yet (tracked, not invented; see the S1–S10 remediation