instar 1.3.476 → 1.3.478

package/upgrades/side-effects/cartographer-subtree-nav.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Cartographer Subtree Navigation (spec #5, Tier 2)
+
+**Version / slug:** `cartographer-subtree-nav`
+**Date:** `2026-06-10`
+**Author:** `Echo`
+**Spec:** `docs/specs/CARTOGRAPHER-SUBTREE-NAV.md` (converged 1 round + a focused buildability review, approved)
+**Second-pass reviewer:** `not required — convergence pinned the collapse rule, the two-phase scoring, batched fresh, and the migrator-only classification; this review covers the seven dimensions on the as-built deterministic code`
+
+## Summary of the change
+
+The capstone of cartographer-conformance: a **deterministic recursive navigator** over
+the doc-tree. Given a query, it walks the tree's summaries top-down (a bounded frontier,
+not all N nodes), scores nodes by relevance, and returns the **minimal relevant
+subtree** — the paths a sub-agent should be scoped to instead of the whole repo.
+`GET /cartographer/navigate`. Observe-only, deterministic-first; an optional LLM re-rank
+is a dark structural stub. Dark behind `cartographer.enabled`.
+
+## Files touched
+
+- NEW `src/core/CartographerNavigator.ts` (scoring + the bounded recursive walk + collapse + sanitization).
+- MODIFIED (additive): `src/core/CartographerTree.ts` (one public `currentOidMap()` accessor exposing the existing batched `currentOids()` — for batched `fresh`), `src/config/ConfigDefaults.ts` (`cartographer.subtreeNav`), `src/server/routes.ts` (the navigate route), `src/server/CapabilityIndex.ts`, `src/core/PostUpdateMigrator.ts` (CLAUDE.md section), `tests/unit/feature-delivery-completeness.test.ts` (legacy-migrator allowlist entry).
+- TESTS: 32 across 3 tiers.
+
+## 1. Over-block
+
+The navigator blocks nothing (observe-only — it returns a suggestion). No gate.
+
+## 2. Under-block / correctness
+
+A bounded walk could MISS a relevant deep node if an intermediate dir's provisional
+score gates it out. The build resolved this (a documented decision): the provisional
+dir score peeks at descendant path BASENAMES to a bounded depth (PEEK_DEPTH=2, path-only,
+non-recursive in score — no deadlock), so the spec's own example ("relevant code under
+`src/messaging/`") and the "never-swept tree navigates on path signal" requirement hold.
+A dir never enters `relevantPaths` on a single descendant's strength — only via the
+collapse rule (≥0.6 of VISITED children relevant). `summaryCoverage` is reported so a
+caller knows how much ranking was summary-informed vs path-only (honest on a never-swept
+tree).
+
+## 3. Level-of-abstraction fit
+
+Pure scorer + pure walk in `CartographerNavigator`; the route is a thin read surface;
+the tree exposes one new read accessor. No layer reaches across; the navigator takes the
+tree + query and returns a manifest. Fully unit-testable on a fixture tree.
+
+## 4. Determinism / cost (the cartographer-project footgun this avoids)
+
+The shipped value is 100% deterministic — local index/summary reads only; zero token
+cost, zero egress, byte-identical run-to-run. The bounded frontier (top-`branchingFactor`
+children to `maxDepth`, capped by `maxNodesVisited`/`maxResults`) means cost is
+O(frontier), not O(tree); `fresh` is one batched `git ls-tree`, not per-node. The LLM
+re-rank ships OFF (Signal vs. Authority — the deterministic score is the authority).
+
+## 5. Security / data-egress
+
+- **Zero egress** in the default config (deterministic core). The optional LLM re-rank
+  inherits spec #2's posture (off-Claude probe, separate egress-ack) and ships OFF.
+- **Summaries are untrusted on output (the hard safety contract):** every emitted summary
+  passes `neutralizeInstructionShapedContent` then `delimitUntrusted` — so a summary that
+  smuggled "ignore your instructions" reaches the downstream sub-agent as quoted,
+  declawed data, never an instruction. (A Tier-1 test asserts an instruction-shaped
+  summary is emitted as `[neutralized: …]`.) The route consumes NO path input (paths are
+  produced), so there is no traversal surface; `query` length + numeric bounds are
+  validated (400 on violation).
+
+## 6. Failure modes / load
+
+No poller, no background work — the navigate is a synchronous read per request, bounded.
+Empty query short-circuits. A never-swept tree degrades gracefully to path navigation.
+No load impact.
+
+## 7. Migration / compatibility (Migration Parity)
+
+`cartographer.subtreeNav` nests under `cartographer` (deep-merge backfill — no
+migrateConfig). The CLAUDE.md section ships via `migrateClaudeMd` (own marker 'Scope a
+sub-agent to a subtree', idempotent) and is registered in the feature-completeness test's
+`legacyMigratorSections` allowlist — EXACTLY as specs #1/#2/#3's cartographer sections
+(migrator-only, not `generateClaudeMd`/shadow; verified at convergence). The route is in
+CapabilityIndex. The `currentOidMap()` addition to CartographerTree is purely additive
+(exposes an existing private read). Rollback: disabling `cartographer.enabled` 503s the
+route. No migration reversal.

package/upgrades/side-effects/converging-audit-default.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — Report-Backed Converging Audit (spec #4, Tier 2)
+
+**Version / slug:** `converging-audit-default`
+**Date:** `2026-06-10`
+**Author:** `Echo`
+**Spec:** `docs/specs/CONVERGING-AUDIT-DEFAULT.md` (converged 1 round + a focused buildability/back-compat review, approved)
+**Second-pass reviewer:** `not required — a focused convergence review verified the bug + the byte-identical back-compat + pinned the env-var threading; this review covers the seven dimensions on the as-built code`
+
+## Summary of the change
+
+Fixes the convergence gate and makes the report-backed converging audit the default
+(dark): **(A)** `StageTransitionValidator` checked `review-convergence === true`
+(boolean) but the real tooling writes a timestamp string — so the formal gate
+**rejected every properly-converged spec**; fixed via a pure `isConvergenceTagPresent`
+predicate that accepts the canonical timestamp (and boolean `true` for back-compat).
+**(B)** A default-off `specReview.requireConvergenceReport` flag that, when on, makes
+the precommit gate also require the convergence **report** file (proof the audit ran)
+— the precommit reads it via an env var (it runs pre-compile and reads no config).
+**(C)** A cross-gate consistency test so the formal validator and the precommit gate
+cannot drift apart. **(D)** Surfaces the `cross-model-review` value in diagnostics
+(observe-only).
+
+## Files touched
+
+- `src/core/StageTransitionValidator.ts` — `isConvergenceTagPresent` predicate (Part A). The existing `CONVERGENCE_REPORT_MISSING` check is UNCHANGED + unconditional.
+- `src/config/ConfigDefaults.ts` + `src/core/types.ts` — `specReview.requireConvergenceReport: false` (deep-merge backfill).
+- `scripts/instar-dev-precommit.js` — Step-6 recognition routed through the new pure module; env-gated report check (Part B); cross-model surfacing (Part D).
+- `.husky/pre-commit` — fail-open one-liner exporting the env from config.
+- NEW `scripts/lib/convergence-recognition.mjs` — the pure recognizer both the precommit and the consistency test use.
+- Tests: validator (timestamp acceptance), consistency, `/projects/:id/advance` integration, the real-precommit E2E.
+
+## 1. Over-block
+
+Part A makes the formal gate accept MORE (the timestamp it should always have
+accepted) — it can never over-block more than before. Part B's report requirement can
+over-block only when the flag is ON (default off); and the formal gate already
+required the report unconditionally, so Part B merely brings the precommit to parity.
+
+## 2. Under-block
+
+Could a spec fake convergence? With the flag on, the report file must exist — a
+hand-added tag alone no longer passes the precommit. With the flag off, behavior is
+unchanged from today (the report requirement is inert). The predicate rejects
+empty/false/missing tags (tested).
+
+## 3. Level-of-abstraction fit
+
+The recognition logic is factored into one pure module (`convergence-recognition.mjs`)
+the precommit imports; the validator has its own pure predicate; a consistency test
+binds them. This is the right shape given the compile boundary (the precommit `.js`
+cannot import the TS validator).
+
+## 4. Back-compat safety (the critical dimension — this gate runs on every commit)
+
+The flag defaults false and the precommit's new branch is gated on the env var being
+`1`; when unset, the report `fs.existsSync` probe is skipped and the Step-6 checks
+reuse the IDENTICAL regexes as before — byte-identical. The `.husky/pre-commit` config
+read is fail-open (any error → env unset → today's behavior). **An E2E test runs the
+REAL precommit script and proves: env unset → a timestamp-tagged+approved spec with no
+report commits cleanly; env=1 + no report → blocked; env=1 + report → commits.** This
+very PR's own commit goes through the modified precommit with the flag off — a live
+proof the default path works.
+
+## 5. Tier-1 exemption
+
+The precommit's `tier1-lite` path exits before Step 6, so the new report check
+correctly does not apply to Tier-1 commits; the consistency test scopes its precommit
+fixtures to the tier-2/3 path.
+
+## 6. Security / load
+
+None — build-time gate only. The new checks are local `fs.existsSync`; no network, no
+LLM in-gate. No load impact.
+
+## 7. Migration / compatibility
+
+`specReview.requireConvergenceReport` rides `applyDefaults` add-missing deep-merge
+(Migration Parity automatic — no `migrateConfig` block). This is a dev-process gate,
+NOT an agent-facing runtime capability — so no CLAUDE.md template / migrateClaudeMd
+section is required (the feature-completeness test governs only agent-facing
+capabilities; verified it stays green) and no new route. Rollback: the flag
+default-false IS the rollback.