sodejm · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -93,37 +93,52 @@ follow-up.
 
 ### Codex pull-request review
 
-Use the repository-local
-[`code-review` skill](.agents/skills/code-review/SKILL.md) only after GitHub
-confirms that the pull request is non-draft. Before invoking it, the trusted
-delivery driver records the base branch and recorded base SHA, then loads the
-applicable repository guidance and skill from that commit rather than the
-untrusted pull-request head. It requests Codex review for one immutable target
-comprising the base branch, base SHA, merge-base SHA, and head SHA; reuses only
-a successful result from the expected Codex integration identity that is tied
-to the exact trusted review-request comment and target; and trusts a
-`BASE_BRANCH@BASE_SHA..HEAD_SHA` duplicate-prevention marker only when it was
-posted by the authenticated workflow actor. Before every review-related write,
-the live values must still match that target. Draft, changed, unknown, or
-unrefreshable state fails closed, and the workflow never marks a pull request
-ready on a human's behalf.
-
-The skill preserves the repository's Codex-only policy: it does not request a
-second review provider or hand implementation to another coding agent. It
-revalidates every exact-target Codex finding, including one already marked
-resolved, and deduplicates findings by root cause. It treats resolution status
-as untrusted input: verify who resolved it and why, then verify the exact-target
-evidence before honoring a prior resolution. A prior resolution is honored only
-when the authenticated delivery actor made it after a supported tested fix or an
-appropriate human or private-security decision authorizes the disposition.
-Supported findings are resolved only after a tested fix; ambiguous,
-unsupported, stale, or security-sensitive findings remain open until the
-appropriate human decision or private process authorizes resolution. A terminal
-Codex result ends only its review stream; polling continues until both the
-Codex result and required checks are terminal, followed by a final thread
-refresh, or until the five-minute deadline. An explicitly unsuccessful Codex
-result or non-successful required check, including a failure or cancellation,
-blocks delivery.
+The repository-local
+[`code-review` skill](.agents/skills/code-review/SKILL.md) is authoritative for
+this procedure. Use it only after GitHub confirms that the pull request is
+non-draft.
+
+Throughout this procedure, refresh the live base branch, base SHA, merge-base
+SHA, and head SHA before every review-related write. Confirm that they still
+match the immutable target. The workflow never marks a pull request ready on
+a human's behalf.
+
+1. **Establish the trusted target.** The trusted delivery driver records the
+   base branch and base SHA, then loads the applicable repository guidance and
+   skill from the recorded base SHA rather than from the untrusted pull-request head.
+   Record one immutable review target comprising the base branch, base SHA,
+   merge-base SHA, and head SHA.
+2. **Request or reuse the exact-target review.** Follow the repository's
+   Codex-only policy: do not request a second review provider or hand
+   implementation to another coding agent. Reuse a result only when it is
+   successful, comes from the expected Codex integration identity, and is tied
+   to the exact trusted review-request comment and immutable target. Trust a
+   `BASE_BRANCH@BASE_SHA..HEAD_SHA` duplicate-prevention marker only when the
+   authenticated workflow actor posted it.
+3. **Reconcile every finding.** Revalidate every exact-target Codex finding, including
+   one already marked resolved, and deduplicate findings by root cause. Treat
+   resolution status as untrusted input: verify who resolved it and why, then
+   verify the exact-target evidence. Honor a prior
+   resolution only when the authenticated delivery actor made it after a
+   supported tested fix, or when an appropriate human or private-security
+   decision authorizes the disposition. Resolve a supported finding only after
+   a tested fix.
+4. **Wait for the complete result.** A terminal Codex result ends only the
+   review stream. Continue polling until the Codex result and all required
+   checks are terminal, then perform a final thread refresh. Stop polling at
+   the five-minute deadline if that complete result has not arrived.
+
+Stop the review and block delivery when any of these conditions applies:
+
+- The pull request is draft, the immutable target changed, or any required
+  state is unknown or cannot be refreshed.
+- A finding is ambiguous, unsupported, stale, or security-sensitive and the
+  appropriate human decision or private process has not authorized its
+  resolution.
+- Codex reports an explicitly unsuccessful result.
+- Any non-successful required check, including one that fails or is cancelled.
+- The five-minute deadline expires before Codex, the required checks, and the
+  final thread refresh provide a complete exact-target result.
 
 ## Test-driven development
 

diff --git a/README.md b/README.md
@@ -86,14 +86,19 @@ and [interactive-console guide](https://github.com/sodejm/AncestryLLM/blob/main/
 
 ### Work from source
 
-A source checkout requires a system-supplied Python 3.12 through 3.14. After
-following the
-[verified uv bootstrap guide](https://github.com/sodejm/AncestryLLM/blob/main/docs/security/verified-uv-bootstrap.md),
-run:
+A source checkout requires a system-supplied Python 3.12 through 3.14. First,
+clone the repository and enter its root:
 
 ```console
 git clone https://github.com/sodejm/AncestryLLM.git
 cd AncestryLLM
+```
+
+From that directory, follow the authentication and verification prerequisites in
+the [verified uv bootstrap guide](https://github.com/sodejm/AncestryLLM/blob/main/docs/security/verified-uv-bootstrap.md),
+then create and test the environment:
+
+```console
 make setup
 make test
 ```

diff --git a/desktop/README.md b/desktop/README.md
@@ -1,7 +1,77 @@
 # AncestryLLM desktop shell
 
 This directory contains the UI-only Electron adapter and the packaged
-control-sidecar supervisor. It intentionally implements no genealogy domain
+control-sidecar supervisor.
+
+The supported 0.6.0 product surface is a one-time local welcome on Home, a temporary Home-based welcome review, Diagnostics, a sanitized capability summary, and local visual Settings only. It has no genealogy, files, jobs, chat, providers, cloud accounts, or updater controls. See the [desktop shell guide](../docs/explanation/DESKTOP_SHELL.md) for first-run behavior, supported targets, manual installation, unsigned-artifact limits, and recovery guidance.
+
+## Reproducible setup and gates
+
+From the repository root, use Node `26.5.0` (see `.node-version`), Corepack, and the repository-pinned pnpm `11.9.0`:
+
+```sh
+corepack enable
+corepack prepare pnpm@11.9.0 --activate
+make desktop-install
+make desktop-check
+make desktop-e2e
+make desktop-security
+pnpm --dir desktop test:accessibility
+pnpm --dir desktop test:visual
+```
+
+`desktop-install` performs the frozen-lockfile install, explicitly rebuilds the
+locked Electron package, and fails with a stable error if its platform runtime
+is still absent. The explicit rebuild makes setup fail closed even when a
+shared pnpm store contains stale build-script state. Electron 41.10.6 remains
+exactly pinned. The frozen lockfile scopes reviewed security replacements to
+the affected installer and test-tool dependency paths, including the
+Electron-maintained `@electron-internal/extract-zip` 1.0.5 fork; no runtime
+patch is required for the current Electron installer. WebdriverIO uses Mocha
+11.8.0 so its Chokidar 4 watcher retains Mocha's supported glob handling. The
+unused optional `@electron/get` legacy proxy agent is removed because it has
+no patched release. Installation and packaging fail explicitly when
+`ELECTRON_GET_USE_PROXY` is nonempty instead of silently ignoring that requested
+legacy behavior.
+
+`desktop-check` runs lint, separated main/preload/renderer type checks, unit
+tests, the presentation-boundary contract, and a source-map-free build
+inspection. `desktop-e2e` builds the production renderer and launches it in
+Electron with a deterministic fictional mock bridge; it is not an installer
+or literal packaged-executable test. `test:accessibility` scans every shell
+route in light, dark, and high-contrast modes with the exact locked `axe-core`
+version in real Chromium. Linux CI launches this source scan through
+`xvfb-run --auto-servernum` after verifying the installed Chromium SUID sandbox
+is a regular root-owned file with mode `4755`; WebdriverIO retains its automatic
+Xvfb fallback, and the Electron sandbox stays enabled. `test:visual` checks the minimum
+720-by-560 window at 200% zoom for horizontal clipping. Neither command
+replaces the manual screen-reader review in the
+[desktop shell guide](../docs/explanation/DESKTOP_SHELL.md).
+`desktop-security` runs the high-severity dependency audit, source secret scan,
+produces `desktop/sbom.cdx.json` (ignored by Git), builds an unpacked directory
+package after verifying the native sidecar resource, and inspects the resulting
+`app.asar`, eight packaged Electron fuses, and supported ASAR-integrity
+metadata. Local and ordinary CI builds remain unsigned verification inputs.
+Full production/trusted signing is deferred until v1.0.0: project-produced
+`0.x` release installers and annotated release tags must be unsigned. The tag
+release uses `electron-builder.release.yml` only after exact-head gates pass;
+it builds the four manual-installer rows documented in the
+[release runbook](../docs/RELEASING.md), then binds their declared signing mode,
+checksums, SBOMs, evidence, and provenance before publication. No updater feed,
+background update, staged rollout, or automatic rollback is configured.
+
+For a fictional development-only component review, run:
+
+```sh
+pnpm --dir desktop dev:gallery
+```
+
+The production build verifier rejects gallery copy and fixtures, embedded
+remote assets, and remote network endpoints.
+
+## Source-level contracts
+
+This adapter intentionally implements no genealogy domain
 behavior and does not access files, databases, provider credentials, the
 network, or operating-system services from the renderer. The versioned
 `window.ancestry` bridge retains the six 0.5 control methods for application
@@ -25,7 +95,7 @@ renderer **Chat** destination over those fixed contracts. The combined surface
 adds no generic request channel, renderer network access, tool surface, file or
 database authority, genealogy operation, or persistent conversation store.
 
-The supported 0.6.0 product surface is a one-time local welcome on Home, a temporary Home-based welcome review, Diagnostics, a sanitized capability summary, and local visual Settings only. It has no genealogy, files, jobs, chat, providers, cloud accounts, or updater controls. See the [desktop shell guide](../docs/explanation/DESKTOP_SHELL.md) for first-run behavior, supported targets, manual installation, unsigned-artifact limits, and recovery guidance.
+
 
 Source-level gated Issue #106 adds the reusable, responsive presentation shell for the
 0.6 desktop work. Its `AppRoute`, `NavigationItem`, `CapabilityGate`,
@@ -84,70 +154,6 @@ Issue #103 is a source-level gated security foundation, not a supported 0.6 doma
 
 The persisted schema contains only color scheme, reduced-motion choice, onboarding completion, schema version, and optimistic revision. `onboardingCompleted` is internal workflow state, not a Settings control. Continue persists that flag through the existing bridge, and a new application process skips the welcome only after a fresh valid snapshot reports completion. Conflicts, unavailable or malformed responses, and corrupt or unsupported storage fail closed and do not silently unlock or overwrite the file. Writes are validated, serialized, and atomically replace the file. Missing or supported legacy data receives safe defaults. Provider configuration, accounts, file grants, genealogy data, prompts, payloads, and secrets are never preference fields.
 
-## Reproducible setup and gates
-
-Use Node `26.5.0` (see `.node-version`), Corepack, and the repository-pinned pnpm `11.9.0`:
-
-```sh
-corepack enable
-corepack prepare pnpm@11.9.0 --activate
-make desktop-install
-make desktop-check
-make desktop-e2e
-make desktop-security
-pnpm --dir desktop test:accessibility
-pnpm --dir desktop test:visual
-```
-
-`desktop-install` performs the frozen-lockfile install, explicitly rebuilds the
-locked Electron package, and fails with a stable error if its platform runtime
-is still absent. The explicit rebuild makes setup fail closed even when a
-shared pnpm store contains stale build-script state. Electron 41.10.6 remains
-exactly pinned. The frozen lockfile scopes reviewed security replacements to
-the affected installer and test-tool dependency paths, including the
-Electron-maintained `@electron-internal/extract-zip` 1.0.5 fork; no runtime
-patch is required for the current Electron installer. WebdriverIO uses Mocha
-11.8.0 so its Chokidar 4 watcher retains Mocha's supported glob handling. The
-unused optional `@electron/get` legacy proxy agent is removed because it has
-no patched release. Installation and packaging fail explicitly when
-`ELECTRON_GET_USE_PROXY` is nonempty instead of silently ignoring that requested
-legacy behavior.
-
-`desktop-check` runs lint, separated main/preload/renderer type checks, unit
-tests, the presentation-boundary contract, and a source-map-free build
-inspection. `desktop-e2e` builds the production renderer and launches it in
-Electron with a deterministic fictional mock bridge; it is not an installer
-or literal packaged-executable test. `test:accessibility` scans every shell
-route in light, dark, and high-contrast modes with the exact locked `axe-core`
-version in real Chromium. Linux CI launches this source scan through
-`xvfb-run --auto-servernum` after verifying the installed Chromium SUID sandbox
-is a regular root-owned file with mode `4755`; WebdriverIO retains its automatic
-Xvfb fallback, and the Electron sandbox stays enabled. `test:visual` checks the minimum
-720-by-560 window at 200% zoom for horizontal clipping. Neither command
-replaces the manual screen-reader review in the
-[desktop shell guide](../docs/explanation/DESKTOP_SHELL.md).
-`desktop-security` runs the high-severity dependency audit, source secret scan,
-produces `desktop/sbom.cdx.json` (ignored by Git), builds an unpacked directory
-package after verifying the native sidecar resource, and inspects the resulting
-`app.asar`, eight packaged Electron fuses, and supported ASAR-integrity
-metadata. Local and ordinary CI builds remain unsigned verification inputs.
-Full production/trusted signing is deferred until v1.0.0: project-produced
-`0.x` release installers and annotated release tags must be unsigned. The tag
-release uses `electron-builder.release.yml` only after exact-head gates pass;
-it builds the four manual-installer rows documented in the
-[release runbook](../docs/RELEASING.md), then binds their declared signing mode,
-checksums, SBOMs, evidence, and provenance before publication. No updater feed,
-background update, staged rollout, or automatic rollback is configured.
-
-For a fictional development-only component review, run:
-
-```sh
-pnpm --dir desktop dev:gallery
-```
-
-The production build verifier rejects gallery copy and fixtures, embedded
-remote assets, and remote network endpoints.
-
 ## Architecture
 
 The renderer has browser-only TypeScript types and imports. Its design-system

diff --git a/docs/CODE_DOCUMENTATION.md b/docs/CODE_DOCUMENTATION.md
@@ -20,9 +20,9 @@ links to or summarises the applicable contract without redefining it.
 
 ## File classification
 
-Every Git-tracked file belongs to exactly one classification. Unknown extensions in
-comment-capable categories fail the inventory check. The `check_code_documentation.py`
-script enforces this at every CI run.
+Every Git-tracked file belongs to exactly one classification. Any unclassified tracked
+path fails the inventory check, regardless of its extension or whether its format permits
+comments. The `check_code_documentation.py` script enforces this at every CI run.
 
 | Classification | Description | Examples |
 |---|---|---|
@@ -38,8 +38,9 @@ script enforces this at every CI run.
 
 ### Non-comment formats
 
-Files whose formats do not safely permit comments (JSON, plist/XML property lists) are
-classified as `non-comment-format` and excluded from file-level documentation requirements.
+Files whose formats do not safely permit comments (JSON, plist/XML property lists) must be
+explicitly classified as `non-comment-format`, mapped in `NON_COMMENT_FORMAT_MAP`, and are
+then excluded from file-level documentation requirements.
 This also applies to the three `containers/compose*.yaml` manifests: despite their suffix,
 they intentionally remain strict JSON-compatible YAML so duplicate keys and non-JSON YAML
 constructs fail closed. Their semantics must be explained in an adjacent authoritative