feat: merge module map, bounded agent context, durable evidence, and review UX into main (#47)

This release consolidates the Phase 32–34 work into a broader structural-review, observability, and MCP-governance update.

It adds a derived Module Map and review-queue model to the canonical report, exposes the new projections through MCP, and introduces dedicated HTML surfaces for module topology, guided review, and Overview-to-Review navigation. The HTML application now shares one dependency-graph layout, one finding-card system, one filter system, and a unified token set for badges, counters, controls, tables, depth, focus states, and metric visualizations.

The analysis pipeline now records deterministic phase-level observability, including core micro-phases, logical SQL counts, context-unit estimates, benchmark scenarios, and expanded cockpit views. Cached and incremental execution paths are surfaced explicitly so maintainers can distinguish actual work from reused state.

MCP responses now follow a bounded-context contract across start, finish, memory retrieval, implementation context, and report-section access. The update adds passive context-governance metadata, explicit drill-down reachability, compact continuation cursors, paginated report sections, bounded start/finish payloads, and exact retrieval routes for durable receipts, Patch Trails, and blast artifacts.

Controlled-change workflows are hardened with idempotent start replay, stable workspace-intent identity hashing, finish receipt deduplication, typed external-artifact restrictions, improved claim validation for negated statements, and corrected trajectory/Patch Trail digest alignment.

Engineering Memory receives several performance and integrity improvements: incremental semantic sourcing, delta-based experience replacement, batched hydration instead of N+1 reads, safe handling of failed source reads, compact continuation cursors, and support for JetBrains as an IDE governance client.

Runtime reachability analysis is extended for FastAPI, Pydantic, and Starlette patterns. Corpus benchmarking is integrated into CI, benchmark summaries are expanded, and dependency/runtime constraints are refreshed for supported Python versions.

The documentation, README, help topics, plugin skills, manifests, and client-specific copies are synchronized with the new Module Map, Review Hub, observability, context-governance, durable artifact retrieval, replay, and architecture-triage contracts.

Tests are expanded across MCP workflows, memory retrieval, continuation binding, trajectory retrieval, plugin synchronization, fail-closed paths, and coverage gaps. Existing report, baseline, cache, fingerprint, finding, gate, and controller-permission semantics remain unchanged.

Author: orenlab

.github/workflows/benchmark.yml

@@ -112,6 +112,8 @@ jobs:
         env:
           RUNS: ${{ matrix.runs }}
           WARMUPS: ${{ matrix.warmups }}
+          SCENARIO_PROFILE: ${{ matrix.profile }}
+          STARTUP_RUNS: "3"
           CPUS: ${{ matrix.cpus }}
           MEMORY: ${{ matrix.memory }}
         run: |
@@ -125,6 +127,8 @@ jobs:
             --target . \
             --runs "${{ matrix.runs }}" \
             --warmups "${{ matrix.warmups }}" \
+            --scenario-profile "${{ matrix.profile }}" \
+            --startup-runs 3 \
             --tmp-dir "/tmp/codeclone-bench-${{ matrix.label }}" \
             --output "$BENCH_JSON"
 
@@ -143,21 +147,39 @@ jobs:
               raise SystemExit(1)
 
           payload = json.loads(report_path.read_text(encoding="utf-8"))
+          startup_probes = payload.get("startup_probes", [])
           scenarios = payload.get("scenarios", [])
           comparisons = payload.get("comparisons", {})
 
           print("CodeClone benchmark summary")
           print(f"label={os.environ.get('RUNNER_OS','unknown').lower()} / {os.environ.get('GITHUB_JOB','benchmark')}")
+          if startup_probes:
+              print("startup probes:")
+              for probe in startup_probes:
+                  name = str(probe.get("name", "unknown"))
+                  stats = probe.get("stats_seconds", {})
+                  cpu_stats = probe.get("child_cpu_stats_seconds", {})
+                  print(
+                      f"- {name:22s} median={float(stats.get('median', 0.0)):.4f}s "
+                      f"first={float(probe.get('first_seconds', 0.0)):.4f}s "
+                      f"cpu={float(cpu_stats.get('median', 0.0)):.4f}s"
+                  )
           for scenario in scenarios:
               name = str(scenario.get("name", "unknown"))
               stats = scenario.get("stats_seconds", {})
+              cpu_stats = scenario.get("child_cpu_stats_seconds", {})
+              inventory = scenario.get("inventory_sample", {})
               median = float(stats.get("median", 0.0))
               p95 = float(stats.get("p95", 0.0))
               stdev = float(stats.get("stdev", 0.0))
               digest = str(scenario.get("digest", ""))
               print(
                   f"- {name:16s} median={median:.4f}s "
-                  f"p95={p95:.4f}s stdev={stdev:.4f}s digest={digest}"
+                  f"p95={p95:.4f}s stdev={stdev:.4f}s "
+                  f"cpu={float(cpu_stats.get('median', 0.0)):.4f}s "
+                  f"files={inventory.get('analyzed', 0)}/{inventory.get('cached', 0)} "
+                  f"artifacts={float(scenario.get('artifact_total_kib_sample', 0.0)):.1f}KiB "
+                  f"exit={scenario.get('exit_code_counts', {})} digest={digest}"
               )
 
           if comparisons:
@@ -174,24 +196,57 @@ jobs:
               "",
               f"- Tool: `{payload['tool']['name']} {payload['tool']['version']}`",
               f"- Target: `{payload['config']['target']}`",
+              f"- Scenario profile: `{payload['config'].get('scenario_profile', 'smoke')}`",
               f"- Runs: `{payload['config']['runs']}`",
               f"- Warmups: `{payload['config']['warmups']}`",
+              f"- Startup runs: `{payload['config'].get('startup_runs', 0)}`",
               f"- Generated: `{payload['generated_at_utc']}`",
               "",
-              "### Scenarios",
-              "",
-              "| Scenario | Median (s) | p95 (s) | Stdev (s) | Deterministic | Digest |",
-              "|---|---:|---:|---:|:---:|---|",
           ]
 
+          if startup_probes:
+              lines.extend(
+                  [
+                      "### Startup / Import Probes",
+                      "",
+                      "| Probe | Median (s) | First (s) | CPU Median (s) |",
+                      "|---|---:|---:|---:|",
+                  ]
+              )
+              for probe in startup_probes:
+                  stats = probe.get("stats_seconds", {})
+                  cpu_stats = probe.get("child_cpu_stats_seconds", {})
+                  lines.append(
+                      "| "
+                      f"{probe.get('name', '')} | "
+                      f"{float(stats.get('median', 0.0)):.4f} | "
+                      f"{float(probe.get('first_seconds', 0.0)):.4f} | "
+                      f"{float(cpu_stats.get('median', 0.0)):.4f} |"
+                  )
+              lines.append("")
+
+          lines.extend(
+              [
+                  "### Scenarios",
+                  "",
+                  "| Scenario | Median (s) | p95 (s) | CPU Median (s) | Files A/C | Artifacts KiB | Exit | Deterministic | Digest |",
+                  "|---|---:|---:|---:|---:|---:|---|:---:|---|",
+              ]
+          )
+
           for scenario in scenarios:
               stats = scenario.get("stats_seconds", {})
+              cpu_stats = scenario.get("child_cpu_stats_seconds", {})
+              inventory = scenario.get("inventory_sample", {})
               lines.append(
                   "| "
                   f"{scenario.get('name', '')} | "
                   f"{float(stats.get('median', 0.0)):.4f} | "
                   f"{float(stats.get('p95', 0.0)):.4f} | "
-                  f"{float(stats.get('stdev', 0.0)):.4f} | "
+                  f"{float(cpu_stats.get('median', 0.0)):.4f} | "
+                  f"{inventory.get('analyzed', 0)}/{inventory.get('cached', 0)} | "
+                  f"{float(scenario.get('artifact_total_kib_sample', 0.0)):.1f} | "
+                  f"{scenario.get('exit_code_counts', {})} | "
                   f"{'yes' if bool(scenario.get('deterministic')) else 'no'} | "
                   f"{scenario.get('digest', '')} |"
               )

.github/workflows/docs.yml

@@ -39,7 +39,7 @@ jobs:
         uses: actions/configure-pages@v5
 
       - name: Build docs site
-        run: uv run --with zensical==0.0.43 zensical build --clean --strict
+        run: uv run --with zensical==0.0.46 zensical build --clean --strict
 
       - name: Generate sample report artifacts
         run: uv run python scripts/build_docs_example_report.py --output-dir site/examples/report/live

.github/workflows/validation-corpus.yml

@@ -0,0 +1,92 @@
+name: validation-corpus
+run-name: validation corpus • ${{ github.event_name }} • ${{ github.ref_name }}
+
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      tier:
+        description: Corpus tier
+        required: true
+        default: all
+        type: choice
+        options:
+          - smoke
+          - gates
+          - full
+          - all
+      corpus-ref:
+        description: codeclone-validation-corpus ref
+        required: true
+        default: main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: validation-corpus-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validation-corpus:
+    name: corpus
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout CodeClone
+        uses: actions/checkout@v6.0.2
+
+      - name: Checkout validation corpus
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: orenlab/codeclone-validation-corpus
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.corpus-ref || 'main' }}
+          path: validation-corpus
+
+      - name: Set up Python
+        uses: actions/setup-python@v6.2.0
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install CodeClone from this checkout
+        run: uv sync --all-extras
+
+      - name: Install validation corpus dependencies
+        run: uv sync --project validation-corpus
+
+      - name: Resolve corpus tier
+        shell: bash
+        run: |
+          tier="all"
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            tier="${{ inputs.tier }}"
+          fi
+          echo "CORPUS_TIER=$tier" >> "$GITHUB_ENV"
+
+      - name: Run validation corpus
+        run: |
+          uv run --project validation-corpus python -m corpus_tools.cli \
+            --tier "$CORPUS_TIER" \
+            --codeclone-command "$GITHUB_WORKSPACE/.venv/bin/python -m codeclone.main" \
+            --work-root "$RUNNER_TEMP/codeclone-validation-corpus-work"
+
+      - name: Write summary
+        if: always()
+        shell: bash
+        run: |
+          {
+            echo "## CodeClone validation corpus"
+            echo
+            echo "- Tier: \`${CORPUS_TIER:-unknown}\`"
+            echo "- Corpus: \`orenlab/codeclone-validation-corpus\`"
+            echo "- CodeClone source: current checkout"
+          } >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -52,3 +52,5 @@ extensions/vscode-codeclone/node_modules
 /coverage.json
 /benchmarks/memory_semantic_eval.md
 /scripts/commit_memory_phases.sh
+/extensions/jetbrains-codeclone/
+/issues/

AGENTS.md

@@ -156,7 +156,7 @@ If you touched baseline/cache/report contracts or CLI/MCP audit surfaces, also e
 If you touched `docs/`, `zensical.toml`, docs publishing workflow, or sample-report generation, also run:
 
 ```bash
-uv run --with zensical==0.0.43 zensical build --clean --strict
+uv run --with zensical==0.0.46 zensical build --clean --strict
 ```
 
 If you touched the MCP surface, also run: