refine(codemap): anchor paths at git root, add guards

- Anchor every codemap index and log path at the git toplevel instead of the process working directory, across the provider and all four consumer plugins: queries from a repository subdirectory previously compared subdirectory-relative paths against root-relative index entries (permanent stale, self-heal every call) or derived a different index path than the writer (false no_index), and log shards split across two directories so session joins returned nothing. Provider-side this covers the staleness git anchoring, the memoized single git SHA query, the stale_undetermined verdict when git fails inside a repository, and the log-root resolver; consumer-side it rewrites cc_develop's resolver/scanner/gate and skill bash blocks, cc_foundry's six agent files, and cc_oss's review-mode context block.
- Report the index file a query actually loaded as index.index_path, captured at load time rather than recomputed at emission; the codex-rig adapter records it per query, tolerates absence as null for older providers, and reports disagreement with the probe's resolver-derived path as evidence under index_path_divergence instead of reconciling it (structural-context artifact schema version 3).
- Compose coexisting codex-rig caveats into stale+degraded instead of letting a stale index mask a coverage gap, and let a targetless standard batch omit target-requiring queries so analysis without --target can report an honest status.
- Add fail-closed cache freshness to cc_oss's codemap cache via an index_stamp field (size plus mtime), and read the index under a shared rwgate lease in check-index-currency while raising the helper size ceilings from 50 MB to the engine's 512 MB — the old ceiling reported no_index for any index above 50 MB, measured against this repository's own 131 MB index.
- Canonicalize module names from the index instead of sed-based path guessing: resolve_centrality.py gains --modules-only and ordered_modules(), the cc_oss review and dispatch modes query it, and consumer project-name sanitization is dropped for the provider's raw-basename rule.
- Add guard infrastructure: new check_codemap_guard.py (MANIFEST-managed vs registry-declared vs provider-CLI taxonomy, wired into audit_static.py and a new check-codemap-guard pre-commit hook), a canonical codemap-context snippet for cc_foundry, and check_cli_flag_drift.py extended to validate flags in a script's own docstring Usage block against its argparse surface with origin tracking.
- Align the shared codemap-gates contract with reality: the build route is codemap-py index (the scan-index alias leases in-engine and is a deprecated shim, not ungated as four prose sites claimed), consumer wrappers drop their now-redundant override clauses, and the inject-preamble hook's stale ungated-scan comment and model-facing directive are corrected.
- Consolidate the five codemap-py hooks onto a shared _hookutil module for project_name and session_key so path derivation cannot silently diverge between the writer and reader of a session sentinel.
- Port setup_scan_env.sh to stdlib-only setup_scan_env.py (Windows-safe, no python3-on-PATH dependency, shared format_scan_args() quoting) with the .sh kept as a deprecated exec shim, and convert claude-skills dispatcher invocations to bare PATH-literal codemap-py form.
- Gate new codemap-py code on complexity limits (C901, PLR0911/0912/0915) from the root pyproject.toml via a negated per-file-ignore, refactor check_currency under the gate, and enumerate the six pre-existing offenders as accepted debt.
- Correct the codex usage-aggregation docstring to what the README literally claims and record the audit of all 401 captured real turns (exactly one usage event per turn, so max() and sum() are indistinguishable on real data), and add benchmarks/conftest.py so doctest collection can import _bench_common.
- Record per-skill codemap route selection in the codex-rig contract with a drift test, and bump plugin versions (codemap-py 0.30.0, codex-rig 0.7.5, cc_foundry 0.46.1, cc_develop 0.22.1, cc_oss 0.28.1, cc_research) with matching CHANGELOG and README updates.

---
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: OpenAI Codex <codex@openai.com>

Author: 3 people

.github/workflows/ci-manifests.yml

@@ -0,0 +1,58 @@
+name: CI manifests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - "plugins/**"
+      - "benchmarks/**"
+      - "pyproject.toml"
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  manifests:
+    name: manifest ${{ matrix.manifest }} (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest", "macos-latest", "windows-latest"]
+        manifest: ["provider-parity-methodology", "codex-integration", "codex-agentic"]
+    timeout-minutes: 10
+    env:
+      UV_PYTHON: "3.12"
+    steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v4
+
+      # The job-level UV_PYTHON is uv's own equivalent of --python, so no uv run below
+      # repeats the version; the action input installs that interpreter.
+      - name: 📦 Install uv and Python
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+
+      # Manifests are gitignored generated artifacts, so a fresh checkout has none to
+      # compare against: build first, then --check that a rebuild is byte-identical.
+      # The builders form a chain — codex-agentic hashes codex-integration.json, and both
+      # Codex builders read provider-parity-methodology.json — so a job builds every
+      # manifest its own target depends on before verifying that target alone.
+      # Bytes are Python-version independent but embed an OS-resolved scan root, so the
+      # matrix covers operating systems, not interpreter versions.
+      - name: 🔨 Build provider-parity-methodology
+        run: uv run --only-group test python benchmarks/build-provider-parity-methodology-manifest.py
+
+      - name: 🔨 Build codex-integration
+        if: matrix.manifest != 'provider-parity-methodology'
+        run: uv run --only-group test python benchmarks/build-codex-integration-manifest.py
+
+      - name: 🔨 Build codex-agentic
+        if: matrix.manifest == 'codex-agentic'
+        run: uv run --only-group test python benchmarks/build-codex-agentic-manifest.py
+
+      - name: 🔒 Verify ${{ matrix.manifest }} rebuilds byte-identically
+        run: uv run --only-group test python "benchmarks/build-${{ matrix.manifest }}-manifest.py" --check

.github/workflows/ci-tests.yml

@@ -15,6 +15,31 @@ defaults:
     shell: bash
 
 jobs:
+  codex-rig:
+    name: codex-rig entrypoints (windows-latest)
+    runs-on: windows-latest
+    timeout-minutes: 10
+    env:
+      UV_PYTHON: "3.12"
+    steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v4
+
+      # The job-level UV_PYTHON is uv's own equivalent of --python, so no uv run below
+      # repeats the version; the action input installs that interpreter.
+      - name: 📦 Install uv and Python
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+
+      - name: 🪟 Verify native Codex Rig entrypoints
+        shell: pwsh
+        run: |
+          $env:PYTHONDONTWRITEBYTECODE = "1"
+          uv run --only-group test python plugins/codex-rig/scripts/build_package.py --check
+          uv run --only-group test python plugins/codex-rig/scripts/validate_package.py
+          uv run --only-group test python plugins/codex-rig/shared/collect_pr.py --help
+
   tests:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -28,33 +53,17 @@ jobs:
       - name: 📥 Checkout
         uses: actions/checkout@v4
 
-      - name: 🐍 Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-
       - name: 🟢 Set up Node
         uses: actions/setup-node@v4
         with:
           node-version: "20"
 
-      - name: 📦 Install uv
+      # The action's python-version input sets UV_PYTHON, uv's equivalent of --python,
+      # so the pytest run below does not repeat the matrix version.
+      - name: 📦 Install uv and Python
         uses: astral-sh/setup-uv@v5
-
-      - name: 🔒 Verify deterministic benchmark manifests
-        run: |
-          uv run --only-group test --python ${{ matrix.python-version }} python benchmarks/build-provider-parity-methodology-manifest.py --check
-          uv run --only-group test --python ${{ matrix.python-version }} python benchmarks/build-codex-integration-manifest.py --check
-          uv run --only-group test --python ${{ matrix.python-version }} python benchmarks/build-codex-agentic-manifest.py --check
+        with:
+          python-version: ${{ matrix.python-version }}
 
       - name: 🧪 Run plugin tests (Python bin/ + JS hooks)
-        run: uv run --only-group test --python ${{ matrix.python-version }} pytest -W error::DeprecationWarning
-
-      - name: 🪟 Verify native Codex Rig entrypoints
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: |
-          $env:PYTHONDONTWRITEBYTECODE = "1"
-          uv run --only-group test --python ${{ matrix.python-version }} python plugins/codex-rig/scripts/build_package.py --check
-          uv run --only-group test --python ${{ matrix.python-version }} python plugins/codex-rig/scripts/validate_package.py
-          uv run --only-group test --python ${{ matrix.python-version }} python plugins/codex-rig/shared/collect_pr.py --help
+        run: uv run --only-group test pytest -W error::DeprecationWarning

.pre-commit-config.yaml

@@ -259,6 +259,13 @@ repos:
         pass_filenames: false
         always_run: true
 
+      - id: check-codemap-guard
+        name: 🗺️ unmanaged codemap index-guard copy
+        language: system
+        entry: python3 plugins/cc_foundry/bin/check_codemap_guard.py
+        pass_filenames: false
+        always_run: true
+
       - id: check-bash-persistence
         name: 🫙 shell var persistence across Bash blocks
         language: system

benchmarks/README.md

@@ -109,7 +109,7 @@ The current Codex agentic adapter uses all 16 committed BA tasks across `A_plain
 bash benchmarks/run-all.sh codex --agentic --dry-run
 ```
 
-The deterministic review lock is `benchmarks/manifests/codex-agentic.json`; regenerate or verify it with `python3 benchmarks/build-codex-agentic-manifest.py [--check]`. The dedicated human companion records the current manifest SHA, task order, treatment contract, exact approval variable, and retry-inclusive per-cell timeout in seconds. No-model dry runs require no credentials and no paid approval. A paid run requires the exact active machine-manifest SHA and private auth source; the launcher creates a fresh timestamped run directory automatically, with an optional `CODEX_RUN_DIR` override for a new path. Final run checksums attest the result artifacts, invocation launcher, and `source.sha256`; verify the archived source bytes separately with `(cd "$RUN_DIR/.launcher/source" && shasum -a 256 -c ../source.sha256)`. Codex CLI version is recorded as observed provenance only and is not a pinned or admission requirement. Each cell has only the retry-inclusive per-cell timeout; no total-run ceiling or wall-clock environment/CLI control applies. A non-default repetition or selected scope must additionally present the resolver's scope SHA-256.
+The deterministic review lock is `benchmarks/manifests/codex-agentic.json`; regenerate or verify it with `uv run python benchmarks/build-codex-agentic-manifest.py [--check]`. The dedicated human companion records the current manifest SHA, task order, treatment contract, exact approval variable, and retry-inclusive per-cell timeout in seconds. No-model dry runs require no credentials and no paid approval. A paid run requires the exact active machine-manifest SHA and private auth source; the launcher creates a fresh timestamped run directory automatically, with an optional `CODEX_RUN_DIR` override for a new path. Final run checksums attest the result artifacts, invocation launcher, and `source.sha256`; verify the archived source bytes separately with `(cd "$RUN_DIR/.launcher/source" && shasum -a 256 -c ../source.sha256)`. Codex CLI version is recorded as observed provenance only and is not a pinned or admission requirement. Each cell has only the retry-inclusive per-cell timeout; no total-run ceiling or wall-clock environment/CLI control applies. A non-default repetition or selected scope must additionally present the resolver's scope SHA-256.
 
 For approval UX, the matching no-model dry run prints a lowercase 16-character SHA-256 scope prefix for copyable `--paid-approval` (or its equivalent approval variable). The complete 64-character scope SHA-256 remains recorded in run metadata and provenance, and the CLI accepts that full value as well. Never mix a prefix or full scope from another dry run with the selected command; regenerate approval after any locked-source change.
 

benchmarks/_bench_codex/runtime.py

@@ -187,13 +187,18 @@ def _ingest_usage(result: CodexParseResult, usage: Mapping[str, Any]) -> None:
     """Fold one native usage event into the turn totals and count schema drift.
 
     ``max()`` rather than a running sum is deliberate: ``benchmarks/README.md``
-    records that native Codex input usage is *cumulative within a turn*, so each
-    usage event restates the turn total and summing would multiply the reported
-    cost. That semantic is an assumption about the provider, pinned here only by
-    a synthetic fixture in ``tests/test_codex_runtime.py``
-    (``test_usage_events_are_treated_as_cumulative_not_additive``) — it has not
-    been confirmed against a captured real stream. If a future CLI emits per-event
-    deltas instead, that fixture is the contract to revisit before changing this.
+    records that native Codex input usage is *cumulative within a turn* — its
+    literal claim is only that cached input is a subset of gross input; the
+    stronger reading that each usage event restates the turn total is this
+    module's interpretation, not the README's assertion. An audit of every
+    captured real stream (401 turns, 2026-08-13) found exactly one usage-bearing
+    event per turn, always terminal — so ``max()``, ``sum()`` and last-wins are
+    indistinguishable on real data and the cumulative property is unobservable
+    there, while the subset claim held on all 401 events. The semantic stays
+    pinned only by a synthetic fixture in ``tests/test_codex_runtime.py``
+    (``test_usage_events_are_treated_as_cumulative_not_additive``). If a future
+    CLI emits several usage events per turn, that fixture is the contract to
+    revisit before changing this.
     """
     result.raw_usage.update(dict(usage))
     for attribute, value in (

benchmarks/build-codex-agentic-manifest.py

@@ -17,6 +17,8 @@
 
 ROOT = Path(__file__).resolve().parents[1]
 BENCHMARKS = ROOT / "benchmarks"
+# Self-named so a rename cannot leave the stale-output hint pointing at a missing script.
+REBUILD_COMMAND = f"uv run python {Path(__file__).resolve().relative_to(ROOT).as_posix()}"
 MANIFESTS = BENCHMARKS / "manifests"
 SOURCE_MANIFEST = MANIFESTS / "provider-parity-methodology.json"
 TASKS_PATH = BENCHMARKS / "suites" / "tasks-agentic.json"
@@ -337,9 +339,7 @@ def _write_or_check(path: Path, expected: bytes, *, check: bool) -> None:
     """Write one generated artifact or fail closed when it differs."""
     if check:
         if not path.is_file() or path.read_bytes() != expected:
-            raise ValueError(
-                f"generated manifest is stale: {path}; run: python3 benchmarks/build-codex-agentic-manifest.py"
-            )
+            raise ValueError(f"generated manifest is stale: {path}; run: {REBUILD_COMMAND}")
         return
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_bytes(expected)

benchmarks/build-codex-integration-manifest.py

@@ -22,6 +22,8 @@
 
 ROOT = Path(__file__).resolve().parents[1]
 BENCHMARKS = ROOT / "benchmarks"
+# Self-named so a rename cannot leave the stale-output hint pointing at a missing script.
+REBUILD_COMMAND = f"uv run python {Path(__file__).resolve().relative_to(ROOT).as_posix()}"
 MANIFESTS = BENCHMARKS / "manifests"
 SOURCE_MANIFEST = MANIFESTS / "provider-parity-methodology.json"
 OUTPUT_MANIFEST = MANIFESTS / "codex-integration.json"
@@ -634,9 +636,7 @@ def _write_or_check(path: Path, expected: bytes, check: bool) -> None:
     """Write one generated record or reject any byte drift in check mode."""
     if check:
         if not path.is_file() or path.read_bytes() != expected:
-            raise ValueError(
-                f"generated record is stale: {path}; run: python3 benchmarks/build-codex-integration-manifest.py"
-            )
+            raise ValueError(f"generated record is stale: {path}; run: {REBUILD_COMMAND}")
         return
     path.write_bytes(expected)
 

benchmarks/build-provider-parity-methodology-manifest.py

@@ -21,6 +21,8 @@
 
 ROOT = Path(__file__).resolve().parents[1]
 BENCHMARKS = ROOT / "benchmarks"
+# Self-named so a rename cannot leave the stale-output hint pointing at a missing script.
+REBUILD_COMMAND = f"uv run python {Path(__file__).resolve().relative_to(ROOT).as_posix()}"
 OUTPUT_MANIFEST = BENCHMARKS / "manifests" / "provider-parity-methodology.json"
 POLICY_SEED = BENCHMARKS / "policy" / "provider-parity-methodology.json"
 POLICY_SEED_SHA256 = "1e5b1cad389513db9402ca2da39f58c1ff9b7cb36b0fdc4a23ce03886e12f1f1"
@@ -372,10 +374,7 @@ def _write_or_check(path: Path, expected: bytes, *, check: bool) -> None:
     """Write generated output or fail closed when its exact bytes are stale."""
     if check:
         if not path.is_file() or path.read_bytes() != expected:
-            raise ValueError(
-                f"generated methodology record is stale: {path}; "
-                "run: python3 benchmarks/build-provider-parity-methodology-manifest.py"
-            )
+            raise ValueError(f"generated methodology record is stale: {path}; run: {REBUILD_COMMAND}")
         return
     path.write_bytes(expected)
 

benchmarks/conftest.py

@@ -0,0 +1,18 @@
+"""Make ``_bench_common`` and sibling top-level benchmark modules importable at collection.
+
+``--doctest-modules`` (repo-root ``pyproject.toml``) imports every module under
+``benchmarks/`` during collection, and ``--import-mode=importlib`` deliberately does
+not put a module's parent directory on ``sys.path`` — so ``from _bench_common import
+presentation`` fails for any module collected outside ``benchmarks/tests/``, whose own
+conftest inserts the directory only for that subtree. This parent-level conftest runs
+first for the whole ``benchmarks/`` tree and applies the same insert once.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_BENCHMARKS_DIR = Path(__file__).resolve().parent
+if str(_BENCHMARKS_DIR) not in sys.path:
+    sys.path.insert(0, str(_BENCHMARKS_DIR))

benchmarks/run-codex-structural.py

@@ -2049,7 +2049,7 @@ def _treatment_artifact_lock_mismatch_message(artifact_name: str) -> str:
         f"installed treatment artifact does not match lock: {artifact_name}. "
         "The local treatment bytes changed after `benchmarks/manifests/codex-integration.json` was generated; "
         "no paid model call was started. Refresh the lock with "
-        "`python3 benchmarks/build-codex-integration-manifest.py`, then resolve a new scope for the same study, "
+        "`uv run python benchmarks/build-codex-integration-manifest.py`, then resolve a new scope for the same study, "
         "repository, model, and task IDs. Do not reuse the previous --paid-approval value. "
         "If Codex Rig edits are still in progress, regenerate only after the intended local bytes are ready."
     )
@@ -2065,7 +2065,7 @@ def _treatment_artifact_version_mismatch_message(version_drift: Mapping[str, tup
         f"installed treatment version differs from the active manifest ({observed}). "
         "No paid model call was started. The local plugin changed after the treatment manifest was generated. "
         "When the intended local plugin bytes are ready, run "
-        "`python3 benchmarks/build-codex-integration-manifest.py`, then resolve a new scope for the same study, "
+        "`uv run python benchmarks/build-codex-integration-manifest.py`, then resolve a new scope for the same study, "
         "repository, model, and task IDs. Do not reuse the previous --paid-approval value."
     )