knodin 0.7.6 → 0.8.3

package/roadmap/competitive-roadmap.md

@@ -0,0 +1,3896 @@
+# knodin — Competitive Roadmap
+
+This is the authoritative active work queue after the original parity program
+closed on 2026-07-21. The completed R1–R48 history, including measured no-go and
+deferred performance decisions, is preserved in
+[`archive/parity-roadmap-2026-07-21.md`](archive/parity-roadmap-2026-07-21.md).
+
+## Product constraint
+
+knodin wins by being local, low-latency, and compact: one MCP tool, no hosted
+service, no required credentials, and no source-code egress. Competitor features
+belong here only when live evidence shows that they improve correctness or a
+core developer loop without undermining that constraint.
+
+## Evidence policy
+
+Every competitive item must link to a reproducible result under
+`benchmarks/competitors/`. A competitor having a feature is not sufficient by
+itself. Items use four dispositions:
+
+- **Must close** — correctness, safety, or a prerequisite for the stated product
+  position.
+- **Should close** — meaningful capability or efficiency improvement with a
+  bounded implementation path.
+- **Evaluate** — evidence is incomplete or implementation cost may outweigh the
+  benefit; do not implement before its gate passes.
+- **Won't pursue** — conflicts with the product constraint or duplicates a
+  better knodin mechanism.
+
+The first evidence set is
+[`GitNexus vs knodin`](../benchmarks/competitors/gitnexus-vs-knodin.md), backed
+by 49 local cases and their raw MCP results. Later competitor bake-offs append
+new items or strengthen existing ones; they do not reopen the archived roadmap.
+
+## Execution order
+
+| ID | Priority | Disposition | Item | Depends on |
+|---|---:|---|---|---|
+| C1 | P0 | Must close | Declare a permissive license | — |
+| C2 | P0 | Must close | Stable symbol identity and ambiguity-safe resolution | — |
+| C3 | P0 | Must close | Enforce truthful response budgets and minimal modes | — |
+| C4 | P1 | Must close | Symbol-level directional impact analysis | C2, C3 |
+| C5 | P1 | Should close | Explicit git diff scopes | C3 |
+| C6 | P1 | Should close | Deterministic import-cycle analysis | C2 |
+| C7 | P2 | Should close | MCP tool and handler mapping | C2 |
+| C8 | P2 | Evaluate | Local statement-level PDG | C2, C3 |
+| C9 | P2 | Evaluate | API contract and response-shape analysis | C2, C3 |
+| C10 | P3 | Evaluate | Bounded expert graph-query DSL | C2, C3 |
+| C11 | P0 | Must close | Call/reference precision and structural identity | C2 |
+| C12 | P1 | Should close | Uniform filters, pagination, and compact drill-downs | C2, C3 |
+| C13 | P1 | Should close | Typed traversal and architecture facets | C2, C3, C11 |
+| C14 | P2 | Should close | Portable budgeted context export | C3, C5 |
+| C15 | P2 | Evaluate | LSP diagnostics and guarded symbol editing | C2, C11 |
+| C16 | P2 | Should close | Index health, repair, and output telemetry | C3 |
+| C17 | P3 | Evaluate | DFS and feature-path navigation | C2, C3, C11 |
+| C18 | P1 | Should close | Unified competitive regression harness | — |
+| C19 | P2 | Evaluate | Salesforce LWC bundles and Apex/data bridges | C2, C3, C11 |
+| C20 | P2 | Evaluate | Salesforce metadata and Flow/automation model | C2, C3, C11 |
+| C21 | P3 | Evaluate | Aura bundles and Visualforce/Aura/LWC interop | C19 |
+| C22 | P3 | Evaluate | LWR and Experience Cloud topology | C19 |
+| C23 | P2 | Evaluate | Apex platform-entry and asynchronous semantics | C2, C3, C11 |
+| C24 | P0 | Must close | Competitive correctness contract and replay baseline | C18 |
+| C25 | P0 | Must close | Prove symbol identity and reference precision leadership | C24, C2, C11 |
+| C26 | P1 | Must close | Prove diff-review and directional traversal leadership | C24, C4, C5, C13 |
+| C27 | P1 | Must close | Prove architecture and community-analysis leadership | C24, C3, C12, C13 |
+| C28 | P1 | Must close | Prove dead-code and semantic-search quality | C24, C3, C11, C12 |
+| C29 | P1 | Must close | Prove context-packing and export leadership | C24, C3, C5, C14 |
+| C30 | P2 | Evaluate | Prove guarded editing and diagnostics leadership | C24, C2, C11, C15 |
+| C31 | P1 | Must close | Prove index lifecycle and output-telemetry leadership | C24, C3, C16, C18 |
+| C32 | P2 | Evaluate | Prove local API and statement-flow analysis leadership | C24, C2, C3, C8, C9 |
+| C33 | P0 | Must close | Preserve local privacy and one-tool schema economy | C24 |
+| C34 | P1 | Must close | Keep local graph indexes current across repository lifecycle events | C16, C24, C33 |
+| C35 | P2 | implemented | Produce local interactive architecture and call-flow visualizations | C3, C13, C24, C33 |
+| C36 | P0 | implemented | Instrument the current warm-operation performance paths | C18, C24 |
+| C37 | P0 | implemented | Reuse generation-scoped graph analytics and traversal snapshots | C36 |
+| C38 | P1 | implemented | Compose orientation context from one shared snapshot | C37 |
+| C39 | P1 | implemented | Separate fast truthful status from explicit deep audit | C36 |
+| C40 | P1 | implemented | Make context packing and artifact access linear and cache-safe | C36 |
+| C41 | P0 | evaluated — deferred | Replay like-for-like performance after the implementation batch | C37, C38, C39, C40 |
+| C42 | P0 | implemented | Enforce comparable competitive cases and correctness oracles | C41 |
+| C43 | P0 | implemented | Measure cold/warm p50, p95, and independent process RSS | C42 |
+| C44 | P0 | implemented | Restore low-latency diff review without weakening evidence | C43 |
+| C45 | P1 | implemented | Add facet-selective architecture fast paths | C43 |
+| C46 | P1 | implemented | Cache search state and hydrate only the requested page | C43 |
+| C47 | P1 | implemented | Reduce status, repair, and measured lifecycle resource cost | C43 |
+| C48 | P2 | evaluated — deferred | Decide an optional local project-memory boundary | C42 |
+| C49 | P1 | implemented | Keep immutable runs lint-safe and make the full suite terminate | — |
+| C50 | P0 | implemented | Make the single-worker full-suite gate start reliably | C49 |
+| C51 | P2 | evaluated — rejected for production | Native training-free embedding quantization | C46 |
+| C52 | P0 | implemented | Package repository lifecycle initialization and refresh | C16, C34, C50 |
+| C53 | P0 | implemented | Make repair observable, cancellable, and resumable | C47, C52 |
+| C54 | P0 | implemented | Certify the local 0.1.0 release artifact | C50, C52, C53 |
+| C55 | P0 | implemented | Pin and audit the authorized Token Optimizer source | C24 |
+| C56 | P0 | implemented | Replay all seven Token Optimizer workflows on shared fixtures | C55 |
+| C57 | P0 | implemented | Add bounded recoverable diagnostic-output compression | C3, C55 |
+| C58 | P0 | evaluated — rejected | Gate command execution on reviewed portable containment | C57 |
+| C59 | P1 | implemented | Connect diagnostic failures to source-evidenced graph context | C57 |
+| C60 | P1 | parked-external-evidence — 2026-08-02 (previous: active — legacy GHES 0.3.0 live; external mirror governance, workload identity, and native certification pending) | Complete two-minute cross-client and GHES onboarding | C52, C55 |
+| C61 | P1 | implemented | Deliver private real-token ROI telemetry and dashboard | C16, C55 |
+| C62 | P0 | parked-external-evidence — 2026-08-02 (previous: active — verifier implemented; production ceremony pending) | Define and implement signed update metadata trust | C55 |
+| C63 | P0 | parked-external-evidence — 2026-08-02 (previous: active — signed-only client implemented; production activation gated) | Add safe update status, check, explain, apply, and rollback policy | C62 |
+| C64 | P0 | parked-external-evidence — 2026-08-02 (previous: active — implementation and adversarial fixtures complete; live release evidence pending) | Produce provenance, SBOM, and cross-channel release attestation | C62 |
+| C65 | P0 | parked-external-evidence — 2026-08-02 (previous: active — bounded multi-step root recovery implemented; production drills pending) | Prove compromised-channel, rollback, freeze, and recovery defenses | C63, C64 |
+| C66 | P0 | parked-external-evidence — 2026-08-02 (previous: active — scorecard published; terminal refresh awaits active dependencies) | Publish an evidence-linked Token Optimizer scorecard | C56, C57, C59, C60, C61, C65, C68, C75 |
+| C67 | P0 | parked-external-evidence — 2026-08-02 (previous: Must close) | Certify and distribute the completed competitive release | C60, C62, C63, C64, C65, C66, C75 |
+| C68 | P0 | implemented | Close Token Optimizer structural output and latency gaps | C56 |
+| C69 | P0 | implemented | Stream large repository inventories with per-repository degradation | C52 |
+| C70 | P0 | implemented | Select portfolio repositories before inventory and reject unknown selectors | C69 |
+| C71 | P0 | implemented | Make portfolio init bounded, resumable, and truthful in dry-run mode | C69, C70 |
+| C72 | P0 | implemented | Make configure/init lifecycle claims atomic and drain compatible queued events | C52 |
+| C73 | P1 | implemented | Distinguish portfolio doctor and installed-versus-active MCP states | C60, C69 |
+| C74 | P1 | implemented | Bound and classify Salesforce metadata architecture candidates | C69 |
+| C75 | P0 | certified with recorded degradations | Certify the 61-repository portfolio under the one-GB memory ceiling | C69, C70, C71, C72, C73, C74 |
+| C76 | P1 | implemented | Replace duplicated CLI parsing/help with one responsive declarative command model | C73 |
+| C77 | P2 | evaluated — retained knodin unchanged | Replay CodeFlow edge-provenance and architecture-export claims | C24, C27, C42 |
+| C78 | P1 | evaluated — retained C8 unchanged | Add bounded source-to-sink resource reachability | C2, C3, C8, C24 |
+| C79 | P1 | implemented | Evaluate or add bounded repository applicability signals | C52, C69 |
+| C80 | P0 | implemented | Route retrieval through structural evidence before embeddings | C3, C24, C42, C43 |
+| C81 | P0 | evaluated — retained knodin unchanged | Run a powered end-to-end benchmark with a diagnose arm | C42, C43, C59, C80 |
+| C82 | P0 | implemented | Productize the retained compress diagnose workflow | C59, C81 |
+| C83 | P0 | implemented | Deliver progressive evidence with a verified hash handshake | C80, C82 |
+| C84 | P1 | implemented | Import optional SCIP evidence without a live-LSP dependency | C24, C80, C83 |
+| C85 | P1 | implemented | Add bounded, itemized git-history review signals | C24, C44, C81 |
+| C86 | P2 | evaluated — retained MiniLM unchanged | Evaluate static embeddings against retained MiniLM | C46, C51, C80, C81 |
+| C87 | P0 | implemented | Add a truthful structural cold-start fast path | C56, C68 |
+| C88 | P1 | implemented — macOS certified; Linux/Windows unavailable | Add profile-based contained execution | C57, C58, C59 |
+| C89 | P0 | implemented | Harden MCP request reliability and recovery | C3, C16, C53 |
+| C90 | P0 | implemented | Produce previewable privacy-safe support bundles | C16, C59, C89 |
+| C91 | P0 | parked-external-evidence — 2026-08-05 (previous: owner-approved adoption priority) | Certify boring macOS installation and Node runtime handoff | C52, C73, C89, C90 |
+| C92 | P0 | parked-external-evidence — 2026-08-06 (previous: proposed) | Unify fail-closed five-channel release orchestration | C64, C91 |
+| C93 | P1 | implemented | Measure engineering task outcomes with and without knodin | C24, C81 |
+| C94 | P1 | parked-external-evidence — 2026-08-06 (previous: blocked) | Make first use self-explanatory and demonstrable | C89, C90, C91 |
+| C95 | P1 | implemented | Codify and replay the defensible behavioral contract | C3, C24, C83 |
+| C96 | P2 | evaluated — deferred | Gate every new capability on a narrow outcome replay | C24, C93, C95 |
+| C97 | P1 | evaluated — retained existing design | Reclaim idle semantic memory without changing one-process architecture | C46, C51, C80, C87 |
+| C98 | P1 | implemented | Add bounded source-to-sink resource reachability | C2, C3, C8, C24, C78, C95 |
+| C99 | P1 | implemented | Resolve bounded TypeScript dependency-injection wiring | C2, C3, C24, C95 |
+| C100 | P1 | implemented | Prove bounded Salesforce Flow-to-Apex paths | C2, C3, C20, C23, C95, C96 |
+| C101 | P1 | implemented | Strengthen contract-led positioning | C95, C97, C98, C99, C100 |
+
+### C98 — Bounded source-to-sink resource reachability
+
+- Status: implemented
+- Evidence: `benchmarks/evaluations/c98-resource-reachability/` freezes the strengthened eight-path C78 oracle and records 100% precision, 100% recall, deterministic ordering, and historical cold/warm/RSS measurements across three local repositories. The verifier independently replays correctness and its current sub-1-GB memory gate; portfolio timings remain descriptive rather than acceptance gates.
+- Implementation: `query resource_reachability` performs cached, on-demand TS/JS analysis without persisted resource-flow tables. It recognizes literal `process.env` and `fs.readFileSync` sources, `console.log`, `fetch`, and `db.query` sinks, plus assignment, argument, return, and bounded recursive handoff.
+- Bounds: maximum depth 6 and 100 paths. Results are static heuristics, never runtime reachability or exploitability proof; dynamic names, reflection, computed aliases, unsupported languages, cycles, truncation, continuation, coverage, and freshness remain explicit.
+- Locality: no hosted service, authentication, credentials, source egress, network access, or production model is required.
+
+### C99 — Bounded TypeScript dependency-injection wiring
+
+- Status: implemented
+- Evidence: `benchmarks/evaluations/c99-typescript-di/` records 100% precision and recall on its declared Inversify/tsyringe oracle, including an explicit ambiguous-token omission; `npm run verify:c99` rejects stale evidence or any missed/extra edge.
+- Implementation: exact source-only `di_binding` and `di_resolution` references cover `bind().to`, `toSelf`, `register(useClass)`, `registerSingleton`, `@inject`, `get`, and `resolve`. Existing explain, impact, traversal, shortest-path, review, and architecture consumers reuse the persisted relationships.
+- Known bounds: only source-proven framework imports, receivers, token declarations, and uniquely resolved implementations qualify. Multiple bindings, computed tokens, aliases, factories, runtime container modules, conditionals, and reflection remain explicit omissions rather than inferred edges.
+
+### C100 — Bounded Salesforce Flow-to-Apex paths
+
+- Status: implemented
+- Evidence: `benchmarks/evaluations/c100-flow-apex-path/` records 100% precision and recall for one preregistered Salesforce DX Flow `actionCalls` to uniquely declared Apex `@InvocableMethod` boundary, including unannotated, missing, and overloaded negative cases. The paired missed-dependency replay improves from an imprecise file answer to a stable method identity with exact XML and Apex evidence.
+- Implementation: Flow indexing persists an exact `flow_apex_action` method reference in addition to its compatible file topology. `query cross_substrate_path <from> <to>` requires both endpoints and returns only that supported substrate transition with stable identities, per-step substrates, extracted provenance, confidence, freshness, exact source evidence, truthful truncation/continuation, and explicit omissions.
+- Known bounds: this is not a general path engine and does not support Terraform, dbt, arbitrary Salesforce metadata, runtime dispatch, namespaced packages, factories, aliases, or ambiguous/multiple Apex methods. One passing boundary and paired task do not establish broad cross-substrate or competitor superiority.
+- Locality: the replay requires no Salesforce org, hosted service, authentication, credentials, network access, or source egress.
+
+### C101 — Contract-led positioning closure
+
+- Status: implemented
+- Evidence: `benchmarks/evaluations/c101-contract-positioning/` and
+  `scripts/verify-c101.ts` source-bind the C97–C100 decisions, the behavioral
+  contract, public CLI/MCP declarations, positioning documents, and repository
+  stewardship instructions.
+- Contract: eight adversarial mutations of actual production responses reject
+  resource/path stale evidence, continuation-free truncation, a truncated
+  response presented as complete, heuristic-to-exact promotion, DI source
+  removal, DI ambiguity, and a path omission retained beside a supported step.
+  Fixture-backed CLI and one-tool MCP calls return the same bounded resource and
+  Flow-to-Apex envelopes; DI reuses
+  existing explain/query/review/map surfaces rather than adding a discriminator.
+- Positioning: value is less manual context assembly and fewer missed
+  dependencies; ROI's intended mechanism is fewer corrective round trips
+  without hosted-service, authentication, or source-egress overhead, while
+  C93's null two-task result authorizes no measured productivity claim;
+  tomorrow is `knodin init` plus the local CLI or single gateway; the secret
+  sauce is stable identity, source evidence, freshness, and truthful budgets
+  composed under one contract.
+- Known bounds: C98 is a static TS/JS heuristic, C99 covers only its declared
+  Inversify/tsyringe patterns, C100 proves one Flow-to-Apex boundary, and C97
+  does not reclaim idle semantic RSS. The closure proves checked fixtures, not
+  runtime causality, arbitrary cross-substrate paths, broad framework coverage,
+  client/platform certification, or competitor superiority.
+- Stewardship: pull requests invoke the full test matrix and Sonar analysis and
+  are therefore long and resource intensive. Related dependency-compatible
+  commits normally form one reasonably sized shared PR; assistants do not
+  auto-open per-item PRs, and unrelated changes are not bundled for size.
+
+## Roadmap completion contract
+
+This section is the control plane for completing this roadmap with a persistent
+goal prompt. The execution-order table remains the full historical ledger. The
+owner split remaining work on 2026-08-02 into Track A, active feature work whose
+acceptance evidence is local and checked in, and Track B, production-release and
+trusted-distribution work parked until its external evidence arrives. Parking
+does not close, weaken, or simulate any gate.
+
+Run the roadmap loop with:
+
+```text
+Complete Track A in roadmap/competitive-roadmap.md in dependency order. Preserve its
+product constraint, evidence policy, limitations, user-owned changes, and
+checked-in evidence. Work autonomously on every safe local step. For each item,
+run its acceptance gates and the repository verification bar, update its Status
+and evidence truthfully, and remove it from Track A only when its
+terminal condition is met. Never turn an evaluation into an implementation or
+a superiority claim unless its gate authorizes that outcome. When an external
+credential, production channel, independent custodian, or platform is required,
+route the item to Track B only by an explicit owner decision; do not simulate
+production evidence. Continue until `npm run check:roadmap -- --complete`
+passes. That command proves Track A completion only and reports Track B parked;
+it is not a production-release-readiness claim.
+```
+
+### Status and closure rules
+
+- `implemented`, `done`, `closed`, `certified`, `evaluated — deferred`,
+  `evaluated — rejected`, and `won't pursue` are terminal only when the item
+  links checked-in evidence satisfying its acceptance or evaluation gate.
+- `proposed`, `active`, `permission-gated`, and `blocked` are non-terminal.
+- An `Evaluate` item closes by recording one allowed disposition: retain the
+  current product unchanged, defer/reject the idea with evidence, or create a
+  separately numbered implementation item. Evaluation never silently expands
+  production scope.
+- P0/P1/P2/P3 affect ordering, not whether an active item must be resolved.
+  Track A completion does not close Track B or the entire roadmap.
+- External work is fail-closed. A missing credential, custodian, production
+  channel, Windows host, or approval may remain parked with exact evidence; it
+  may not produce a synthetic pass. Parked rows remain in Track B.
+- Proposals in ADRs, landscape documents, task systems, or competitor reports
+  are outside this roadmap's completion boundary until assigned a C-number in
+  the execution-order table. Repository applicability signals are C79 and ADR
+  006 items 1–7 are promoted intact as C80–C86;
+  later ADR 006 proposals remain outside the boundary until separately approved.
+- Closing an item requires updating its item-level `Status`, evidence links,
+  limitations, the execution-order disposition if needed, and its ledger in
+  the same change. Do not rewrite immutable raw benchmark artifacts.
+- `npm run check:roadmap -- --publish-ready` is the ordinary 0.x publication
+  guard. It requires Track A to be empty while retaining and reporting Track B.
+  The owner clarified on 2026-08-03 that early Docusign usage is a rollout
+  cohort, not a separate artifact channel; ordinary releases may publish while
+  Track B remains parked. `npm run check:roadmap -- --release-ready` remains the
+  stricter GA/trusted-distribution guard and fails unless both tracks are empty.
+- While Track B remains open, documentation and positioning must not claim
+  cross-platform certification, trusted distribution, or production-release
+  readiness. All existing qualifications and recorded limitations remain in
+  force.
+
+### Track A — Active local-work ledger
+
+Track A contains only feature or local-evidence work whose acceptance can be
+proved by checked-in tests and replays. Rows are ordered by dependency and then
+priority. The owner approved repository applicability signals as the top item
+on 2026-08-03, followed by ADR 006 items 1–7 intact as C80–C86;
+later ADR proposals remain outside the completion boundary until separately
+approved and numbered.
+
+| ID | State | Previous state | Depends on | Exit evidence |
+|---|---|---|---|---|
+
+### Track B — Parked external-evidence ledger
+
+Track B parked (10 items, external). The owner parked C60–C67 on 2026-08-02,
+parked C91 after its code-readiness increment on 2026-08-05, and parked C92
+and C94 on 2026-08-06 because their acceptance depends on C91 evidence.
+Every former state, dependency, exit condition, acceptance criterion, and
+limitation remains binding. Re-enter this track when either the documented C60
+packet or C62 packet arrives; completing one packet does not waive the other.
+The durable handoff index is
+`docs/evidence/handoff/README.md`, the C60 packet is
+`docs/evidence/c60-autonomous-preparation-2026-08-02.md`, and the C62 packet is
+`docs/ROOT-CEREMONY-RUNBOOK.md`.
+
+| ID | State | Previous state | Depends on | Exit evidence |
+|---|---|---|---|---|
+| C60 | parked-external-evidence — 2026-08-02 | active | C52, C55 | Mirror automation, timed onboarding, and Linux/Windows certification evidence |
+| C62 | parked-external-evidence — 2026-08-02 | active | C55 | Offline root ceremony, independent pin review, and recovery receipt |
+| C63 | parked-external-evidence — 2026-08-02 | active | C62 | Production activation/rollback evidence or explicit safe deferred policy |
+| C64 | parked-external-evidence — 2026-08-02 | active | C62 | Verified release-candidate provenance/SBOM bundles and attestation draft |
+| C65 | parked-external-evidence — 2026-08-02 | active | C63, C64 | Production ceremony and channel/runner/manager defense drills |
+| C66 | parked-external-evidence — 2026-08-02 | active | C56, C57, C59, C60, C61, C65, C68, C75 | Terminal scorecard refresh linked to closed dependencies |
+| C67 | parked-external-evidence — 2026-08-02 | proposed | C60, C62, C63, C64, C65, C66, C75 | Certified release record and distribution receipts |
+| C91 | parked-external-evidence — 2026-08-05 | owner-approved adoption priority | C52, C73, C89, C90 | Native macOS manager/client/Homebrew/Artifactory receipts plus transactional doctor repairs |
+| C92 | parked-external-evidence — 2026-08-06 | owner-approved release priority | C64, C91 | Dry-run preflight, retry replay, immutable artifact proof, and receipt schema |
+| C94 | parked-external-evidence — 2026-08-06 | owner-approved clarity priority | C89, C90, C91 | First-use copy tests and a checked-in five-minute real-repository demonstration |
+
+### Goal-loop ordering
+
+1. Keep Track A active work independent of release authority and prove every
+   item with local, checked-in acceptance evidence.
+2. Re-enter Track B when either C60 or C62's documented evidence packet arrives.
+   Execute C60 and C62 in parallel where people and platforms permit.
+3. After C62, produce C64's release-candidate artifacts. Close C63 with its
+   fail-closed deferred-activation policy, then use that terminal client as the
+   subject of C65's adversarial drills. C65, not C63, authorizes any later
+   production activation.
+4. Produce C66's terminal prerelease snapshot only from terminal dependency
+   evidence. C67 may append release receipts without reopening C66.
+5. Execute C67 last. GA and trusted-distribution claims remain prohibited until
+   Track B is empty and `npm run check:roadmap -- --release-ready` passes.
+   Ordinary 0.x publication requires `npm run check:roadmap -- --publish-ready`.
+6. Keep C92 and C94 parked behind C91. Re-enter C91 only when the named native macOS
+   environments and credentialed channels are available and the transactional
+   doctor repair contract is implemented; deterministic fixtures alone do not
+   satisfy certification.
+
+---
+
+## C1 — Declare a permissive license
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- Evidence: the GitNexus bake-off found GitNexus explicitly licensed under
+  PolyForm Noncommercial 1.0.0 while knodin has neither a `LICENSE` file nor a
+  `package.json` license field. “Local and free” is not a legally supportable
+  marketing claim until this is resolved.
+- Touches: `LICENSE`, `package.json`, `README.md`, `docs/COMPARISON.md`
+
+### Acceptance criteria
+
+1. The repository owner selects and adds an OSI-approved permissive license;
+   implementation must not guess the owner's legal choice.
+2. `package.json` declares the matching SPDX identifier.
+3. README and comparison copy use only claims permitted by that license.
+4. Package contents include the license after `bun pm pack --dry-run` or the
+   repository's equivalent packaging check.
+
+---
+
+## C2 — Stable symbol identity and ambiguity-safe resolution
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- Evidence: GitNexus's `trace(main, createEngine)` returned three ranked `main`
+  candidates and required disambiguation. knodin silently returned
+  `main → createEngine`, with no indication of which definition it selected.
+- Touches: `src/engine/index.ts`, `src/tools/knodin-tools.ts`, `bin/cli.ts`,
+  symbol/query/explain/rename/path tests, persisted schema if IDs must survive
+  rebuilds
+
+### Required behavior
+
+1. Every symbol-facing result exposes a stable repository-scoped identity.
+2. `explain`, structured queries, rename preview/apply, and shortest path accept
+   optional identity, file, and kind selectors.
+3. A bare-name request with multiple viable definitions returns an explicit
+   ambiguity result with ranked candidates; it never silently merges or chooses
+   definitions when that can change the answer.
+4. Existing unambiguous bare-name calls remain source-compatible.
+
+### Acceptance criteria
+
+1. A fixture with at least three same-named functions reproduces the GitNexus
+   `main` case and proves no conflated path is returned.
+2. Selecting each candidate by identity returns only that candidate's real
+   callers, callees, impact, and paths.
+3. Rename by identity edits only the selected definition and its resolved
+   references.
+4. Migration/rebuild behavior for persisted IDs is deterministic and tested.
+
+---
+
+## C3 — Enforce truthful response budgets and minimal modes
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- Evidence: knodin's minimal symbol context still returned 22,843 bytes because
+  source was always present, and minimal `map` returned 254,102 bytes. GitNexus
+  was usually more compact when source was not requested. Conversely,
+  GitNexus's source-inclusive query returned 606,235 bytes, demonstrating why a
+  hard cap—not convention—is required.
+- Reinforced by Graphify's 417-byte top-10 hubs versus knodin's 258,628-byte
+  mapped response, Aider's 425-byte mean at a 128-token budget versus knodin's
+  roughly 190 KB mapped mean, and Repomix/code2prompt's explicit token metrics.
+- Touches: `src/engine/index.ts`, `src/tools/knodin-tools.ts`, response-size and
+  operation tests, docs
+
+### Required behavior
+
+1. Every operation has a tested serialized-byte ceiling and reports truncation
+   plus total counts when the ceiling binds.
+2. Minimal `explain` omits source unless explicitly requested; standard explain
+   retains edit-ready source within its cap.
+3. Minimal `map` returns counts, aggregates, and bounded top-N summaries only;
+   it never leaks full community member arrays or full edge lists.
+4. Caps are applied after serialization-aware accounting so nested content
+   cannot bypass them.
+5. Callers may choose token, byte, and item budgets; all three produce honest
+   totals, truncation state, and a continuation/drill-down route.
+6. Hub, bridge, community, traversal, search, source, and export operations honor
+   their requested top-N or budget without constructing a full map response.
+
+### Acceptance criteria
+
+1. The GitNexus benchmark's `context-name-min` and `cypher-communities`
+   counterparts remain below documented budgets.
+2. Large-symbol and large-map fixtures assert both byte ceilings and honest
+   `truncated`/total-count metadata.
+3. No standard response silently loses edit-critical source without a clear
+   continuation or drill-down route.
+
+---
+
+## C4 — Symbol-level directional impact analysis
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C2, C3
+- Evidence: GitNexus distinguished upstream/downstream/both, depths 1/3/6,
+  tests, relation confidence, processes, and modules for `createEngine`.
+  knodin's closest public impact query was file-level and returned the same
+  broad 31-row set for every directional comparison.
+- Reinforced by codebase-memory-mcp's directional typed trace and argument-level
+  data-flow evidence, and Graphify's relation-filtered direct neighbors.
+- Touches: `src/engine/index.ts`, `src/tools/knodin-tools.ts`, `bin/cli.ts`,
+  impact/query tests and docs
+
+### Required behavior
+
+1. Impact accepts a stable symbol selector or an explicit file-level mode.
+2. Symbol mode supports direction, maximum depth, relation kinds, confidence
+   threshold, test inclusion, result limit, argument/data-flow evidence, and
+   compact summary.
+3. Results preserve depth and edge evidence and identify affected flows and
+   communities without presenting heuristic reach as exact.
+4. File-level impact remains available and is labeled distinctly.
+
+### Acceptance criteria
+
+1. The `createEngine` fixture produces meaningfully different upstream and
+   downstream results.
+2. Depth limits are monotonic and enforced; confidence/relation filters have
+   targeted fixtures.
+3. Ambiguous symbols use C2's candidate response rather than conflated reach.
+4. Compact output satisfies C3's byte budget.
+
+---
+
+## C5 — Explicit git diff scopes
+
+- Status: implemented
+- Priority: P1
+- Disposition: Should close
+- DependsOn: C3
+- Evidence: GitNexus supports `unstaged`, `staged`, `all`, and `compare`.
+  knodin cannot request staged-only review, and its result can omit changed
+  files when no indexed symbol maps to the diff.
+- Reinforced by code-review-graph's caller-supplied changed-file review and
+  code2prompt's working-tree diff, branch diff, and branch log exports.
+- Touches: git diff parsing, engine review contract, MCP/CLI schemas, review
+  tests and docs
+
+### Acceptance criteria
+
+1. Review accepts `unstaged|staged|all|compare`; compare requires or defaults a
+   documented base ref.
+2. Each scope has a fixture containing different staged and unstaged edits.
+3. Results always report changed files, including non-code/unindexed files,
+   separately from mapped changed symbols.
+4. Existing `base` behavior has a documented compatibility mapping.
+5. Review accepts an explicit file list or revision pair without requiring the
+   checkout to contain an equivalent live diff.
+
+---
+
+## C6 — Deterministic import-cycle analysis
+
+- Status: implemented
+- Priority: P1
+- Disposition: Should close
+- DependsOn: C2
+- Evidence: GitNexus exposes a bounded read-only cycle check; knodin has no
+  direct equivalent despite already storing import dependencies.
+- Touches: `src/engine/index.ts`, query schema/docs, cycle fixtures
+
+### Acceptance criteria
+
+1. A structured query returns canonical deterministic file-import cycles.
+2. Equivalent rotations of one cycle are deduplicated.
+3. Limits and truncation metadata prevent exponential output.
+4. Fixtures cover no cycle, one cycle, overlapping cycles, and type-only/import
+   edge policy.
+
+---
+
+## C7 — MCP tool and handler mapping
+
+- Status: implemented
+- Priority: P2
+- Disposition: Should close
+- DependsOn: C2
+- Evidence: GitNexus correctly detected knodin's `knodin` MCP tool and its
+  source file. knodin has endpoint patterns but no MCP registration-to-handler
+  map.
+- Touches: language extraction, schema, structured queries, MCP fixtures/docs
+
+### Acceptance criteria
+
+1. Index common TypeScript MCP SDK registration forms and associate tool name,
+   description, schema declaration, handler symbol, and file.
+2. A query supports all tools and lookup by tool name.
+3. Dynamic/unresolved registrations are labeled heuristic rather than exact.
+4. The repository's own `knodin` registration is found without matching prose
+   examples or benchmark fixture strings.
+
+---
+
+## C8 — On-demand local statement-level flow analysis
+
+- Status: implemented (bounded on-demand analysis; no persisted PDG)
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C2, C3
+- Evidence: GitNexus's opt-in local PDG returned concrete control-dependence and
+  reaching-definition rows, including variable-filtered `db` flows. knodin has
+  no statement-level answer. GitNexus also produced large 14–42 KB PDG
+  responses, so copying its output contract would conflict with knodin's
+  compactness goal.
+- Touches if approved: parser/extractor architecture, persisted schema,
+  performance harness, query surface, multi-language fixtures
+- Evaluation evidence: [`C8 summary and methodology`](../benchmarks/evaluations/c8-pdg/summary-methodology.md)
+- Decision: the disposable prototype passed the mechanical gate at 100% labeled
+	fixture precision, with three real repositories measured and responses below
+	the C3 ceiling. The supported implementation is the narrower on-demand
+	`flow_analysis` query for one selected TS/JS symbol, with optional variable
+	filtering, compact source evidence, C3 budgets, and explicit unresolved cases;
+	it does not persist a broad PDG.
+
+### Evaluation gate
+
+1. Prototype TS/JS control-flow and reaching-definitions on disposable code,
+   not the production schema.
+2. Measure clean-index time, incremental-index time, database growth, peak RSS,
+   query latency, precision, and response size against at least three real
+   repositories.
+3. Require ≥90% precision on a labeled control/data-flow fixture and a bounded
+   response below C3's ceiling.
+4. Approve implementation only if the value cannot be delivered more cheaply
+   through compiler/LSP facts or a narrower on-demand analysis.
+
+---
+
+## C9 — Evaluate API contract and response-shape analysis
+
+- Status: implemented
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C2, C3
+- Evidence: GitNexus exposes route maps, response-shape checking, and API impact,
+	but this repository had zero detected HTTP routes. The bake-off proves the
+	surface exists, not that it is correct or useful. knodin now persists
+	source-evidenced literal Express/Fastify route and fetch/Axios client facts,
+	with a bounded `api_contract_mismatches` query.
+- Touches: route extraction, schema/shape model, cross-file/client usage
+	resolution, fixtures and query surface
+- Evaluation evidence: [`C9 summary`](../benchmarks/evaluations/c9-api/summary.md)
+- Decision: the evaluation gate passed. GitNexus found the actionable `profile`
+	response mismatch that current handler, endpoint, and impact queries missed.
+	The production implementation shipped after the checked-in fixture produced
+	3 true positives, 0 false positives, and 0 false negatives (precision 1.00,
+	recall 1.00); dynamic routes remain unresolved and absolute-origin clients do
+	not link to local endpoints. See [`C9 production acceptance`](../benchmarks/evaluations/c9-api/production-acceptance.md).
+
+### Evaluation gate
+
+1. Build a local fixture with multiple verbs on one route, middleware, typed and
+   inferred response bodies, internal clients, mismatches, and dynamic routes.
+2. Run GitNexus and knodin endpoint primitives against the same fixture and
+   manually label precision/recall.
+3. Approve implementation only if shape analysis finds actionable breakage that
+   current handler/endpoint/impact queries miss.
+
+---
+
+## C10 — Evaluate a bounded expert graph-query DSL
+
+- Status: closed; general DSL will not be pursued
+- Priority: P3
+- Disposition: Evaluate
+- DependsOn: C2, C3
+- Evidence: GitNexus's parameterized Cypher expressed caller, community
+  aggregate, and custom dead-code queries outside a fixed enum. knodin's fixed
+  patterns are easier to route and safer but cannot answer arbitrary structural
+  questions. GitNexus's naive custom dead-code query also returned many false
+  positives, illustrating the cost of unconstrained power.
+- Touches if reopened: parser/validator, query planner, response budget,
+  read-only safety tests and docs
+- Evaluation evidence: [`C10 summary`](../benchmarks/evaluations/c10-dsl/summary.md)
+- Decision: no DSL is justified in this roadmap slice. Three bounded fixed-pattern
+  candidates covered 12 of 13 provenance-backed questions (92.3%), so the DSL
+  prototype gate is a no-go.
+
+### Evaluation gate
+
+1. Collect at least ten real questions that existing patterns cannot answer.
+2. Determine whether two or three new fixed patterns cover most demand.
+3. If not, design a read-only bounded DSL with explicit node/edge allowlists,
+   mandatory limits, traversal-depth caps, and no raw SQL/Cypher execution.
+4. Approve only with deterministic cost bounds and C3-compliant output.
+
+---
+
+## C11 — Call/reference precision and structural identity
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C2
+- Evidence: Graphify found four credible call neighbors for `createEngine` while
+  knodin included a known name-collision false positive; Serena returned precise
+  LSP references and structural `KnodinEngine` implementations knodin's nominal
+  inheritance query missed. grepai and codebase-memory-mcp also demonstrated
+  that imports/files must not be mislabeled as callers.
+
+### Acceptance criteria
+
+1. Labeled fixtures distinguish call, import, usage, containment, inheritance,
+   and TypeScript structural implementation edges.
+2. Callers/callees reach at least 95% precision and recall on those fixtures;
+   built-ins and same-name symbols never create cross-definition edges.
+3. Structural implementations are queryable separately from nominal inheritors.
+4. Tests cover top-level calls, aliases, barrels, object-literal interface
+   implementations, scripts, tests, and ambiguous names.
+
+---
+
+## C12 — Uniform filters, pagination, and compact drill-downs
+
+- Status: implemented
+- Priority: P1
+- Disposition: Should close
+- DependsOn: C2, C3
+- Evidence: code-review-graph filters semantic kind, large-code threshold/kind,
+  flow/community sort and detail; codebase-memory-mcp adds label, qualified name,
+  file, relationship, degree, total/offset pagination; Claude Context filters
+  extensions. Graphify honors top-N hubs and relation filters.
+
+### Acceptance criteria
+
+1. Search accepts language/extension, kind, path, test/production, and source
+   inclusion filters plus offset/cursor pagination with total and `hasMore`.
+2. Large-code queries accept explicit line/complexity thresholds, symbol kind,
+   and path; no requested parameter is silently ignored.
+3. Hub, bridge, community, flow, and traversal drill-downs honor top-N, sort,
+   relation, and detail controls under C3.
+4. Parameter-combination tests prove filters compose rather than overwrite one
+   another.
+
+---
+
+## C13 — Typed traversal and architecture facets
+
+- Status: implemented
+- Priority: P1
+- Disposition: Should close
+- DependsOn: C2, C3, C11
+- Evidence: codebase-memory-mcp beat knodin on inbound/outbound/both traces,
+  edge types, argument expressions, tests, risk labels, packages, layers,
+  boundaries, hotspots, and path scoping. Graphify adds direct relation-filtered
+  neighbors.
+
+### Acceptance criteria
+
+1. Traversal supports direction and explicit edge types with per-hop evidence.
+2. Call/data-flow results preserve argument expressions where extraction is
+   compiler-grounded and label heuristic facts honestly.
+3. Architecture exposes independently selectable packages, layers, boundaries,
+   hotspots, entry points, languages, and path scope.
+4. Results satisfy C11 precision fixtures and C3 budgets.
+
+---
+
+## C14 — Portable budgeted context export
+
+- Status: implemented
+- Priority: P2
+- Disposition: Should close
+- DependsOn: C3, C5
+- Evidence: Repomix, code2prompt, and Aider provide portable source-shaped
+  context, deterministic formatting, token accounting, file policies, ranged
+  retrieval, mention/chat awareness, and Git context. These are complementary
+  to knodin's graph rather than replacements for it.
+
+### Acceptance criteria
+
+1. Export supports Markdown, JSON, and XML with relative paths, optional line
+   numbers/tree, deterministic ordering, and explicit tokenizer cost estimate.
+2. Include/exclude rules and per-file `full|summary|structure-only` policies are
+   composable with a hard token/byte budget.
+3. Already-present/chat files can be excluded from duplicated source context.
+4. Optional diff/log sections use C5 scopes; packed artifacts support bounded
+   ranged reads and exact regex grep.
+
+---
+
+## C15 — Evaluate LSP diagnostics and guarded symbol editing
+
+- Status: implemented (read-only TypeScript language-service queries)
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C2, C11
+- Evidence: Serena successfully exposed diagnostics, declarations,
+  implementations, symbol-body replacement, before/after insertion, safe delete,
+  and guarded multi-file replacement. knodin's verified rename is safer but much
+  narrower. The 2026-07-22 disposable evaluation exercised TypeScript Language
+  Server, Pyright, JDTLS, Java/Javac, .NET compilation, and the official Roslyn
+  C# Language Server with guarded TypeScript previews and rollback. The final
+  raw result records a C# `textDocument/diagnostic` response and
+  `textDocument/implementation` navigation to the fixture's line-10
+  implementation; the passing compiler check remains corroboration rather than a
+  substitute for LSP evidence. knodin now ships optional local TypeScript
+  diagnostics, definition, declaration, and implementation queries with no
+  daemon, subprocess, workspace mutation, or index initialization. Missing or
+  unsupported adapters return explicit unavailable results; guarded editing and
+  cross-language mutation remain unapproved.
+
+### Evaluation gate
+
+1. Prototype a local TypeScript/LSP adapter for diagnostics, implementation, and
+   edit previews without adding a required daemon.
+2. Require all edits to produce a preview and reuse rename's compiler check and
+   rollback guarantees; never expose unguarded filesystem mutation.
+3. Measure startup/RSS/latency and verify behavior across TS, Python, Java, and
+   C# fixtures before approving a general editing surface.
+
+---
+
+## C16 — Index health, repair, and output telemetry
+
+- Status: implemented
+- Priority: P2
+- Disposition: Should close
+- DependsOn: C3
+- Evidence: codebase-memory-mcp exposes portable lifecycle modes and schema;
+  Claude Context exposes clear/status lifecycle; mcp-codebase-index statically
+  defines health/repair; grepai records output/token savings. knodin has strong
+  freshness internals but limited public health and budget telemetry.
+
+### Acceptance criteria
+
+1. Status reports schema/model/version, file and symbol coverage, orphaned or
+   missing records, last successful reconciliation, and actionable repair steps.
+2. A local repair command can rebuild only damaged/missing state and verify the
+   result without deleting healthy data.
+3. Benchmark telemetry records operation, latency, serialized bytes, estimated
+   tokens, truncation, and detail mode without recording source content.
+4. All telemetry is local, opt-in for persistence, and documented as such.
+
+---
+
+## C17 — Evaluate DFS and feature-path navigation
+
+- Status: implemented
+- Priority: P3
+- Disposition: Evaluate
+- DependsOn: C2, C3, C11
+- Evidence: Graphify and code-review-graph expose DFS; grepai adds deterministic
+  functional feature paths. `query feature_path <symbol>` now supplies a compact,
+  deterministic downstream DFS over C2/C11-resolved references. It includes
+  file/line edge evidence, cycle guards, depth/node caps, and explicit
+  truncation without adding persistent identity state. The focused fixture-led
+  regression in `feature-path.spec.ts` proves a branching result observably
+  differs from BFS while remaining stable after harmless line shifts.
+
+### Delivered behavior
+
+1. `feature_path` follows only resolved downstream references in stable DFS
+   order; `traverse` remains the existing selectable-direction BFS neighborhood.
+2. Standard-detail non-root nodes include C11-resolved identity; every hop
+   includes source file/line, kind, provenance, and confidence evidence.
+3. Cycles are visited once, depth is clamped to 1–6, the item cap is enforced,
+   and a larger reachable graph reports `truncated: true`.
+4. The feature is source-only: dynamic dispatch, reflection, unresolved calls,
+   and runtime execution order remain explicitly outside the contract.
+
+---
+
+## C18 — Unified competitive regression harness
+
+- Status: implemented
+- Priority: P1
+- Disposition: Should close
+- Evidence: the first program produced 12 independent protocols and 713 paired
+  cases. Without one version-pinned entry point, improvements to C1-C17 could
+  silently lose coverage or be compared against a different tool installation.
+- Touches: `scripts/competitive-bakeoff.ts`, `src/competitive-manifest.ts`,
+  `src/competitive-runner.ts`, `benchmarks/competitors/README.md`
+
+### Acceptance criteria
+
+1. One manifest selects competitors directly or by C1-C17 roadmap coverage and
+   records exact versions, prerequisites, preparation, commands, and blockers.
+2. Runs refuse dirty checkouts by default, validate installed versions, isolate
+   fixture mutations, and preserve immutable timestamp-and-commit artifacts.
+3. Heterogeneous raw results normalize into one summary and compare against the
+   checked-in baseline with a configurable latency tolerance and nonzero
+   regression exit status.
+4. List, prerequisite-check, and dry-run modes are non-mutating; commands use
+   argument arrays rather than shell interpolation.
+5. Unit tests cover selection, immutable history, normalization, blockers, and
+   material-regression detection.
+
+---
+
+## Salesforce scope boundary and remaining limitations
+
+The baseline parses Apex and Visualforce and now includes the bounded C19–C23
+implementations for LWC, selected metadata/Flow automation, Aura interop, LWR
+topology, and Apex platform entry/asynchronous semantics. Their individual
+sections and fixtures define the supported static evidence. This remains
+partial Salesforce coverage, not proof that every deployed-org dependency or
+runtime dispatch is resolved. Static dead-code candidates still require
+corroboration against deployed-org and platform dependency data before deletion.
+
+OmniStudio and industry-cloud packages are intentionally out of scope: promote
+them only after a concrete, legally usable Salesforce repository demonstrates a
+workflow that C19–C23 do not cover.
+
+Their proposed shared `src/engine/index.ts` footprint is a collision, so they
+must be scheduled sequentially even where their logical dependencies are
+independent.
+
+---
+
+## C19 — Evaluate Salesforce LWC bundles and Apex/data bridges
+
+- Status: implemented
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C2, C3, C11
+- Evidence: the version-pinned, source-only Salesforce DX fixture now records
+  13/13 exact bundle, component, Apex, schema, wire-adapter, and Lightning Data
+  Service labels (100% precision, 100% recall) in
+  `benchmarks/evaluations/c19-salesforce-lwc/raw-results-20260722T132842614Z.json`.
+  The replay copies the fixture to a temporary directory, needs no org login,
+  credentials, network access, or source egress, and records one-file LWC/Apex
+  reindex plus C3-bounded response measurements. Dynamic and namespaced forms
+  remain omitted rather than exact claims. The raw result hashes the evaluated
+  engine, runner, and label revision in addition to the fixture. This authorizes no broader Salesforce
+  product commitment beyond the evaluated static source edges.
+- Touches if approved: `src/engine/index.ts`, `src/__tests__/unit/salesforce.spec.ts`,
+  `src/__tests__/unit/lwc.spec.ts` (new),
+  `benchmarks/evaluations/c19-salesforce-lwc/` (new),
+  `src/competitive-manifest.ts`
+
+### Evaluation gate
+
+1. Build a self-contained Salesforce DX fixture with LWC JavaScript, HTML, CSS,
+   and `*.js-meta.xml` bundle members; include component-to-component imports,
+   `@salesforce/apex`, `@salesforce/schema`, wire adapters, and Lightning Data
+   Service usage alongside resolvable Apex methods.
+2. Label bundle containment plus LWC-to-Apex, LWC-to-object/field, and
+   component-to-component edges. Require at least 95% precision and 90% recall;
+   unresolved, dynamic, or namespaced references must be omitted or labeled
+   heuristic rather than reported as exact.
+3. Re-index a one-file LWC and one-file Apex change, measure index/response
+   cost against C3, and prove the analysis needs neither an org login nor source
+   egress.
+
+---
+
+## C20 — Evaluate Salesforce metadata and Flow/automation model
+
+- Status: implemented
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C2, C3, C11
+- Evidence: the version-pinned source-only Salesforce DX fixture records 15/15
+  exact custom-object/field/record-type, permission-set, Flow, workflow, and
+  approval-process labels (100% precision and recall) in
+  `benchmarks/evaluations/c20-salesforce-metadata/raw-results-20260722T134732728Z.json`.
+  The replay copies the fixture to a temporary directory, runs a metadata-only
+  one-file update, stays within C3's response budget, and needs no org login,
+  deployment, credentials, network access, or source egress. Formula and
+  runtime-selected targets remain explicit unknowns rather than exact edges.
+  This authorizes no broader Salesforce product commitment beyond the evaluated
+  static source relationships.
+- Touches if approved: `src/engine/index.ts`,
+  `src/__tests__/unit/salesforce-metadata.spec.ts` (new),
+  `benchmarks/evaluations/c20-salesforce-metadata/` (new),
+  `src/competitive-manifest.ts`
+
+### Evaluation gate
+
+1. Build a version-pinned Salesforce DX fixture containing custom objects and
+   fields, record types, permission sets, a record-triggered Flow, a screen or
+   autolaunched Flow, workflow/approval metadata, and a Flow-invoked Apex
+   action.
+2. Label only statically declared metadata edges: Flow/automation to Apex,
+   object, field, permission, and referenced UI component. Require at least
+   95% precision and 90% recall; dynamic formulas and runtime-selected targets
+   must remain explicit unknowns.
+3. Demonstrate that a metadata-only change updates the affected topology without
+   requiring deployment to an org, and keep output within C3's budget.
+
+---
+
+## C21 — Evaluate Aura bundles and Visualforce/Aura/LWC interop
+
+- Status: implemented
+- Priority: P3
+- Disposition: Evaluate
+- DependsOn: C19
+- Evidence: the version-pinned, source-only Salesforce DX fixture records 10/10
+  exact Aura containment, Aura-to-Apex, Aura-to-LWC, and Visualforce controller
+  labels (100% precision and recall) in
+  `benchmarks/evaluations/c21-salesforce-interop/raw-results-20260722T161801709Z.json`.
+  The replay copies its fixture to a temporary directory, needs no org login,
+  credentials, network access, or source egress, and verifies source evidence
+  for every claimed cross-stack edge. knodin supports these static source
+  relationships; `$A` runtime lookup strings remain omitted rather than exact
+  claims.
+- Touches: `src/engine/index.ts`,
+  `src/__tests__/unit/visualforce.spec.ts`,
+  `src/__tests__/unit/salesforce-interop.spec.ts` (new),
+  `benchmarks/evaluations/c21-salesforce-interop/` (new),
+  `src/competitive-manifest.ts`
+
+### Evaluation gate
+
+1. Build a fixture with Aura component, application, interface, event, and
+   design members; Visualforce page/component/controller bindings; and a
+   supported Aura-to-LWC or Visualforce-to-Lightning bridge.
+2. Label containment and cross-stack edges, including Aura-to-Apex and the
+   declared bridge target. Require at least 95% precision and 90% recall, while
+   `$A` runtime lookup strings and unresolvable expressions remain heuristic.
+3. Confirm that unchanged Apex/Visualforce behavior retains its current test
+   results and that cross-stack results expose the source evidence for every
+   claimed edge.
+
+---
+
+## C22 — Evaluate LWR and Experience Cloud topology
+
+- Status: implemented
+- Priority: P3
+- Disposition: Evaluate
+- DependsOn: C19
+- Evidence: the version-pinned, source-only LWR and Experience Cloud fixture
+  records 9/9 exact site, route, view, LWC/Aura, theme, and SVG asset labels
+  (100% precision and recall) in
+  `benchmarks/evaluations/c22-salesforce-experience/raw-results-20260722T162757428Z.json`.
+  The replay copies its fixture to a temporary directory, measures a route-only
+  reindex, stays within C3's 65,536-byte map budget, and needs no org login,
+  credentials, network access, source egress, server, or deployment. knodin
+  supports this static source topology; runtime route expressions remain
+  unresolved rather than fabricated.
+- Touches: `src/engine/index.ts`,
+  `src/__tests__/unit/salesforce-experience.spec.ts` (new),
+  `benchmarks/evaluations/c22-salesforce-experience/` (new),
+  `src/competitive-manifest.ts`
+
+### Evaluation gate
+
+1. Build a source-only fixture containing LWR configuration plus the supported
+   Experience Cloud metadata for one site, its routes, views, theme/assets, and
+   declared LWC or Aura targets.
+2. Label site-to-route-to-view-to-component and static-asset relationships.
+   Require at least 95% precision and 90% recall; route values assembled at
+   runtime must be labeled unresolved rather than fabricated.
+3. Measure a route/view-only incremental update and prove that topology output
+   is compact, locally computed, and does not require serving or deploying the
+   site.
+
+---
+
+## C23 — Evaluate Apex platform-entry and asynchronous semantics
+
+- Status: implemented
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C2, C3, C11
+- Evidence: the version-pinned, source-only Salesforce DX fixture records 20/20
+  exact REST/SOAP/invocable/trigger, async callback, enqueue, subscription, and
+  Salesforce Function labels (100% precision and recall) in
+  `benchmarks/evaluations/c23-apex-platform-semantics/raw-results-20260722T140720946Z.json`.
+  The replay copies the fixture to a temporary directory, reindexes one Apex
+  file, keeps map responses under C3's 65,536-byte budget, and requires no org
+  login, credentials, network access, or source egress. Transaction ordering,
+  bulk behavior, retries, and runtime payload shape remain unknown.
+- Touches if approved: `src/engine/index.ts`,
+  `src/__tests__/unit/salesforce.spec.ts`,
+  `src/__tests__/unit/apex-platform-semantics.spec.ts` (new),
+  `benchmarks/evaluations/c23-apex-platform-semantics/` (new),
+  `src/competitive-manifest.ts`
+
+### Evaluation gate
+
+1. Build a version-pinned fixture covering `@RestResource` and verb handlers,
+   `webService`/SOAP, `@InvocableMethod`, trigger object/event declarations,
+   `@future`, Queueable, Batchable, Schedulable, Platform Event or change-event
+   subscribers, and statically resolvable Salesforce Function invocations.
+2. Label entry-point, enqueue, callback, subscription, and invocation edges;
+   require at least 95% precision and 90% recall. Never infer transaction order,
+   bulk behavior, retries, or runtime payload shape from source alone.
+3. Validate that each result carries an exact-versus-heuristic confidence label,
+   stays within C3's response budget, and is produced with no org credentials or
+   network access.
+
+---
+
+## Competitive leadership program
+
+The competitive audit is evidence, not a second roadmap. C24-C33 turn every
+row of [`COMPETITIVE-AUDIT.md`](../benchmarks/competitors/COMPETITIVE-AUDIT.md)
+into a measurable delivery contract. A row is complete only when knodin meets
+or exceeds the stated criterion against the pinned competitor and shared
+fixture. A missing local prerequisite, incompatible license, hosted-service
+requirement, or resource failure is a reproducible blocker, never a pass.
+
+All replays must record the knodin commit, competitor version, command,
+fixture revision, warm/cold mode, requested scope, response budget, and oracle
+result. Correctness wins require a labeled oracle; latency, response size, or
+feature presence alone cannot establish a win. A replay that proves a loss
+must add a follow-on implementation item before the parent may close.
+
+### Product-claim gate
+
+Every roadmap item that changes a user-facing claim must state and verify all
+four parts of the adoption case:
+
+1. **Value:** the named developer or agent workflow and the concrete failure or
+   delay it removes.
+2. **ROI:** a labeled correctness, latency, size, safety, or effort measure
+   with its baseline and measurement window; do not substitute a vendor claim
+   or feature count.
+3. **Tomorrow:** a local, credential-free adoption path that is compatible with
+   existing Git, editor, and test workflows, including explicit unavailable or
+   degraded states.
+4. **Defensibility:** the evidence, integration, or outcome that remains hard
+   to substitute after the underlying model capability becomes commonplace.
+
+“Uses AI” and an unmeasured capability are never roadmap completion signals.
+An item without a measurable adoption case remains evaluation-only; a replay
+that finds a quality gap updates the roadmap and prioritizes the smallest
+workflow correction before any new surface area is added.
+
+| Audit row | Leadership item | Win target |
+|---|---|---|
+| Exact symbol identity and ambiguity | C25 | Correct selected identity or explicit ambiguity for every labeled duplicate-name case |
+| Caller/callee/reference accuracy | C25 | ≥95% precision and recall; zero cross-definition false positives |
+| Diff review and change scope | C26 | Exact changed-file/symbol oracle across each supported scope |
+| Blast radius and traversal | C26 | Oracle-checked typed edges, depth, filters, and truncation |
+| Architecture and communities | C27 | Oracle-checked topology plus deterministic bounded drill-downs |
+| Dead code | C28 | Reported precision/recall and no unlabelled heuristic claim |
+| Semantic orientation/search | C28 | Frozen relevance judgments with reported nDCG and recall@k |
+| Code/context packing | C29 | Exact inclusion/range/token oracle under equivalent budgets |
+| Source editing and diagnostics | C30 | Preview, compile/test, and rollback oracle on disposable fixtures |
+| Resource/index lifecycle | C31 | Comparable cold/warm/repair/RSS/disk evidence with successful recovery oracle |
+| API/PDG/specialized analysis | C32 | Precision/recall and bounded source-evidence oracle |
+| Local privacy and schema economy | C33 | Zero required credentials/egress/hosted service and one top-level MCP tool |
+
+### C24 — Competitive correctness contract and replay baseline
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C18
+- Evidence: the audit records 713 paired cases but explicitly says that most
+  current comparisons lack a labeled correctness oracle. Existing label sets
+  under `benchmarks/evaluations/` are fragmented and are not represented in
+  the normalized competitive-run summary.
+- Competitors: all locally runnable entries in `COMPETITIVE_MANIFEST`; keep
+  `mcp-codebase-index` blocked while it requires hosted Gemini embeddings.
+- Touches: `src/competitive-runner.ts`, `src/competitive-manifest.ts`,
+  `scripts/competitive-bakeoff.ts`,
+  `src/__tests__/unit/competitive-runner.spec.ts`,
+  `benchmarks/evaluations/`, `benchmarks/competitors/COMPETITIVE-AUDIT.md`,
+  `benchmarks/competitors/SYNTHESIS.md`, this roadmap
+- What: normalize competitor cases into a version-pinned, oracle-aware replay
+  contract and reconcile every historical audit claim with the current code.
+
+### Acceptance criteria
+
+1. The normalized summary separately records correctness-oracle status,
+   exact-match/precision/recall/false-positive results where applicable, and
+   performance/resource measurements; unavailable fields remain explicit nulls.
+2. Every audit row has a fixture inventory that either reuses a checked-in
+   labeled fixture or identifies the missing fixture as a blocked prerequisite.
+3. Every competitor run records pinned version, command, fixture revision,
+   mode, budgets, and reproducible blockers; a partial run cannot be reported
+   as a competitive win.
+4. The audit labels all existing rows `implemented—needs replay`, `unverified`,
+   `demonstrated gap`, or `non-goal` instead of treating historical results as
+   current product state.
+
+### C25 — Prove symbol identity and reference precision leadership
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C24, C2, C11
+- Competitors: GitNexus, Serena, codebase-memory-mcp, CodeGraph
+- Touches: `benchmarks/evaluations/competitive-symbols/`,
+  `src/__tests__/unit/symbol-identity.spec.ts`,
+  `src/__tests__/unit/reference-precision.spec.ts`,
+  `src/competitive-manifest.ts`, relevant competitor bake-off scripts,
+  `src/engine/index.ts` and `src/tools/knodin-tools.ts` only if replay fails
+- What: make exact target selection, ambiguity safety, and callers/callees/
+  references objectively comparable on shared duplicate-name and structural
+  implementation fixtures.
+- Replay evidence:
+  `benchmarks/evaluations/competitive-symbols/raw-results-20260723.json`.
+  knodin achieved 100% precision and recall with zero cross-definition false
+  positives under the shared response budget; every pinned competitor completed
+  against the same fixture and its oracle score is preserved.
+
+### Acceptance criteria
+
+1. A labeled fixture covers duplicate names, aliases, barrels, imports versus
+   calls, structural implementations, tests, and at least one unresolved case.
+2. knodin returns the selected stable identity or an explicit ambiguity result;
+   it never silently conflates viable candidates.
+3. knodin meets at least 95% precision and recall for labeled resolved
+   call/reference edges, with zero cross-definition false positives.
+4. The pinned competitors and knodin run against the same fixture and budget;
+   a win requires oracle parity or superiority, not a smaller response.
+
+### C26 — Prove diff-review and directional traversal leadership
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C24, C4, C5, C13
+- Competitors: GitNexus, code-review-graph, Graphify, codebase-memory-mcp
+- Touches: `benchmarks/evaluations/competitive-review/`,
+  `src/__tests__/unit/review-scopes.spec.ts`,
+  `src/__tests__/unit/impact.spec.ts`,
+  `src/__tests__/unit/typed-traversal.spec.ts`, relevant bake-off scripts,
+  engine/tool/CLI code only if replay fails
+- What: compare staged, unstaged, untracked, and revision-pair review results
+  plus typed directional traversal using source-evidenced expected edges.
+- Replay evidence:
+  `benchmarks/evaluations/competitive-review/raw-results-20260723.json`.
+  knodin matched every diff-scope, unindexed-file, directional traversal, and
+  edge-evidence oracle under the frozen budget. GitNexus reached traversal
+  parity; Graphify and code-review-graph did not, and the unavailable
+  codebase-memory query adapter remains an explicit blocker rather than a win.
+
+### Acceptance criteria
+
+1. The fixture labels changed files, mapped symbols, unindexed files, direct
+   and transitive typed edges, depth, and expected truncation.
+2. knodin supports every documented diff scope and reports all changed files
+   independently of index coverage.
+3. Upstream/downstream/both traversal obeys selected relation, confidence,
+   depth, test, and budget controls with oracle-checked edge evidence.
+4. A replay declares success only when knodin meets the oracle and normalized
+   budget; any competitor prerequisite failure is preserved as a blocker.
+
+### C27 — Prove architecture and community-analysis leadership
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C24, C3, C12, C13
+- Competitors: GitNexus, Graphify, codebase-memory-mcp, code-review-graph
+- Touches: `benchmarks/evaluations/competitive-architecture/`,
+  `src/__tests__/unit/map.spec.ts`, `src/__tests__/unit/uniform-filters.spec.ts`,
+  `src/__tests__/unit/typed-traversal.spec.ts`, relevant bake-off scripts,
+  engine/tool code only if replay fails
+- What: test boundaries, layers, packages, hubs, bridges, communities,
+  relation filters, pagination, and compact drill-downs against a labeled
+  module-topology fixture.
+- Replay evidence:
+  `benchmarks/evaluations/competitive-architecture/raw-results-20260723.json`.
+  knodin met the labeled topology oracle, deterministic pagination, and C3
+  budget. Pinned GitNexus, Graphify, and code-review-graph replays completed
+  against the same fixture; codebase-memory remains an explicit policy blocker.
+
+### Acceptance criteria
+
+1. The fixture labels module boundaries, allowed cross-boundary edges,
+   packages/layers, hub/bridge expectations, and known absent relationships.
+2. knodin produces deterministic, filterable, paginated results with explicit
+   totals and C3-compliant byte/token/item budgets.
+3. Architecture claims retain exact-versus-heuristic confidence and never turn
+   an inferred grouping into a precise boundary claim.
+4. A pinned replay proves oracle quality and budget parity or better.
+
+### C28 — Prove dead-code and semantic-search quality
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C24, C3, C11, C12
+- Competitors: GitNexus, CodeGraph, grepai, Claude Context
+- Touches: `benchmarks/evaluations/competitive-search/`,
+  `src/__tests__/unit/query.spec.ts`, `src/__tests__/unit/search.spec.ts`,
+  `src/__tests__/unit/response-budget.spec.ts`, relevant bake-off scripts,
+  engine/tool code only if replay fails
+- What: measure dead-code precision/recall and semantic-orientation relevance
+  using known-live/known-dead and judged-query fixtures.
+- Replay evidence:
+  `benchmarks/evaluations/competitive-search/raw-results-20260723T214300000Z.json`
+  preserves the frozen local oracle and exact version checks. The pinned
+  GitNexus 1.6.9 adapter normalizes ranked function definitions and its
+  read-only no-incoming-`CALLS` Cypher heuristic to the same `file::symbol`
+  labels. knodin records dead-code precision/recall of 1.0/1.0 versus
+  GitNexus's 0.667/1.0, and mean semantic nDCG/recall@3 of 0.855/1.0 versus
+  0.677/1.0. Both stay within the 32 KiB response budget with no source egress.
+  The remaining CodeGraph, grepai, and Claude Context capability blockers are
+  retained honestly but no longer prevent a comparable pinned competitor replay.
+
+### Acceptance criteria
+
+1. Dead-code labels cover exports, imports, reflection-like unresolved uses,
+   tests, barrels, and known live/dead symbols; results report precision,
+   recall, and false positives.
+2. Search has frozen relevance judgments and reports nDCG and recall@k under a
+   fixed source and response budget.
+3. knodin labels heuristic dead-code or semantic evidence honestly and offers a
+   bounded drill-down for excluded evidence.
+4. The replay establishes a win only with oracle parity or better and no
+   regression to C3 budgets.
+
+### C29 — Prove context-packing and export leadership
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C24, C3, C5, C14
+- Competitors: Repomix, Aider repo-map, code2prompt
+- Touches: `benchmarks/evaluations/competitive-context/`,
+  `src/__tests__/unit/context-export.spec.ts`,
+  `src/__tests__/unit/response-budget.spec.ts`, relevant bake-off scripts,
+  `src/context-export.ts` and tool/CLI code only if replay fails
+- What: compare deterministic packing, exact token accounting, file policy,
+  incremental/ranged retrieval, and optional Git context on a shared corpus.
+- Replay evidence:
+  `benchmarks/evaluations/competitive-context/raw-results-20260723.json`.
+  knodin met the shared inclusion, exclusion, range, Git, token, and byte
+  oracle for deterministic Markdown, JSON, and XML exports. Repomix and
+  code2prompt completed the bounded corpus replay with their unavailable
+  controls recorded; Aider is explicitly blocked because it has no comparable
+  artifact surface.
+
+### Acceptance criteria
+
+1. The fixture labels required/excluded source, tree, line ranges, Git changes,
+   and expected token/byte bounds for each request.
+2. knodin produces deterministic Markdown, JSON, and XML exports with relative
+   paths and a declared tokenizer estimate.
+3. Include/exclude and per-file policies compose with hard budgets; ranged
+   reads and exact regex grep return verifiable source positions.
+4. The competitor replay compares equivalent scope and budget and preserves
+   any unavailable command or format as an explicit blocker.
+
+### C30 — Prove guarded editing and diagnostics leadership
+
+- Status: implemented (evaluation found no production-surface gap)
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C24, C2, C11, C15
+- Competitors: Serena, code-review-graph
+- Touches: `benchmarks/evaluations/competitive-editing/`,
+  `src/__tests__/unit/lsp-readonly.spec.ts`,
+  `src/__tests__/unit/rename-apply.spec.ts`, relevant bake-off scripts,
+  `src/lsp-readonly.ts` and editing surfaces only if evaluation approves them
+- What: establish whether additional local, guarded edit previews deliver
+  enough value beyond compiler-verified rename and read-only TypeScript
+  language-service queries.
+- Replay evidence:
+  `benchmarks/evaluations/competitive-editing/raw-results-20260723.json`.
+  The disposable fixture verified diagnostic and navigation goldens,
+  preview-first compiler/test validation, rejected-edit rollback, and explicit
+  unavailable competitor adapters. It found no actionable gap requiring a new
+  production editing surface.
+
+### Acceptance criteria
+
+1. Fixtures include diagnostic goldens, definition/implementation navigation,
+   valid edits, rejected edits, rollback, and compile/test verification.
+2. Any proposed mutation is preview-first, bounded to a disposable copy, and
+   produces a compiler/test result before it can be judged successful.
+3. No daemon, credential, network access, or unguarded workspace mutation is
+   required; unsupported language adapters return explicit unavailable results.
+4. Promote an implementation only if the competitor comparison finds an
+   actionable, locally deliverable gap that rename and read-only queries cannot
+   cover.
+
+### C31 — Prove index lifecycle and output-telemetry leadership
+
+- Status: done
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C24, C3, C16, C18
+- Competitors: codebase-memory-mcp, grepai, Claude Context
+- Touches: `benchmarks/evaluations/competitive-lifecycle/`,
+  `src/__tests__/unit/index-health.spec.ts`,
+  `src/__tests__/unit/perf.spec.ts`, `src/competitive-runner.ts`, relevant
+  bake-off scripts, engine/tool/CLI code only if replay fails
+- What: compare cold index, incremental index, corruption repair, stale-index
+  recovery, output telemetry, peak RSS, disk, and failure behavior locally.
+- Replay evidence:
+  `benchmarks/evaluations/competitive-lifecycle/raw-results-20260723T220325Z.json`
+  records disposable four-phase replays for pinned codebase-memory-mcp and
+  grepai with verified versions and behavioral lifecycle oracles. Both expose
+  stale indexed state after a unique symbol replacement, recover through their
+  documented refresh/reindex mechanism, make the replacement queryable, remove
+  the old symbol, and preserve the healthy symbol. Native telemetry inspection
+  deterministically establishes the remaining capability gaps:
+  codebase-memory reports graph/index counts and repository state but lacks
+  detailed per-query output telemetry; grepai reports aggregate query/token
+  savings but lacks per-query latency, truncation, and detail mode. knodin
+  supplies those opt-in local fields. Claude Context remains a separately
+  classified Ollama/Milvus setup-resource blocker rather than an inferred win.
+
+### Acceptance criteria
+
+1. The fixture records cold and warm timing, peak RSS, database/disk growth,
+   failure injection, repair outcome, and telemetry fields without source
+   content.
+2. knodin detects stale/damaged state, provides an actionable repair, and
+   verifies the repaired result without deleting healthy state.
+3. Persisted telemetry is opt-in, local, and includes operation, latency,
+   serialized bytes, estimated tokens, truncation, and detail mode.
+4. A replay compares equivalent lifecycle phases; setup or resource failures
+   remain distinct from correctness and performance outcomes.
+
+### C32 — Prove local API and statement-flow analysis leadership
+
+- Status: implemented (evaluation found no production-surface gap)
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C24, C2, C3, C8, C9
+- Competitors: GitNexus
+- Touches: `benchmarks/evaluations/competitive-api-flow/`,
+  `src/__tests__/unit/flow-analysis.spec.ts`,
+  `src/__tests__/unit/api-contracts.spec.ts`, relevant bake-off scripts,
+  engine/tool code only if evaluation proves a gap
+- What: replay bounded API contract mismatch and statement-level flow results
+  against a labeled fixture, retaining knodin's compact local-only contract.
+- Replay evidence:
+  `benchmarks/evaluations/competitive-api-flow/raw-results-20260723.json`.
+  The labeled local replay produced 1.00 precision and recall with zero false
+  positives for both bounded API mismatches and variable-filtered statement
+  flow. It verifies source evidence, an explicit C3 continuation at the flow
+  budget, and the one-gateway/local-only constraints. No broader persisted PDG
+  or API surface is justified by this evaluation.
+
+### Acceptance criteria
+
+1. The fixture labels true API mismatches, true control/data-flow rows,
+   variable filtering, unresolved cases, and expected source evidence.
+2. knodin reports precision, recall, false positives, unresolved cases,
+   truncation, and continuation routes under C3 budgets.
+3. The comparison never treats broad persisted PDG output, raw Cypher, or
+   hosted analysis as required parity; it evaluates only proven local workflows.
+4. Promote broader implementation only when it finds actionable breakage that
+   existing bounded API/flow queries miss.
+
+### C33 — Preserve local privacy and one-tool schema economy
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C24
+- Competitors: all; `mcp-codebase-index` and Claude Context supply negative
+  evidence where hosted services or local service dependencies are required.
+- Touches: `src/tools/knodin-tools.ts`, `src/server.ts`,
+  `src/competitive-manifest.ts`, `src/__tests__/unit/mcp-tools.spec.ts`,
+  `benchmarks/evaluations/competitive-constraints/`, this roadmap
+- What: make the local/no-auth/no-egress and one-gateway constraints measurable
+  release gates for every competitive claim.
+
+### Acceptance criteria
+
+1. A clean local replay requires no credentials, hosted service, network
+   embeddings, source-code egress, or mandatory external daemon.
+2. The MCP surface remains one `knodin` gateway; a capability addition must
+   document schema-token cost and cannot create a top-level tool.
+3. Any optional local service is reported as optional and unavailable states
+   are explicit rather than silently degraded success.
+4. No item C24-C32 can close unless its replay records this constraint check.
+
+### C34 — Keep local graph indexes current across repository lifecycle events
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C16, C24, C33
+- Competitors: GitNexus, Graphify, codebase-memory-mcp
+- Touches: `bin/cli.ts`, `src/engine/index.ts`, `lefthook.yml`,
+  `templates/hooks/`, `src/__tests__/unit/freshness.spec.ts`,
+  `src/__tests__/unit/watcher-lifecycle.spec.ts`,
+  `benchmarks/evaluations/competitive-lifecycle/`, docs
+- What: make fresh, reconciled, stale, and unavailable graph states explicit
+  across file edits, branch switches, pulls, rebases, merges, and a restarted
+  local process; provide safe, local refresh commands for every supported graph
+  artifact without pretending an external index is current.
+- Evidence: `knodin refresh-artifacts [checkout|merge|code-change]` is an
+  explicit opt-in, 30-second-bounded refresh for locally installed GitNexus and
+  Graphify. It prefers the repository's GitNexus runner when present, records
+  success, failure, or skipped state without source content, and is never wired
+  into a commit hook. The lifecycle fixtures prove restart, replacement,
+  branch-switch, merge, watcher-loss, and external-tool states; the replay
+  records freshness latency, RSS, disk, and verified state.
+
+### Acceptance criteria
+
+1. knodin continues to reconcile its persisted index at cold start and before
+   answers after offline drift, reporting `fresh`, `reconciled`, or `unknown`.
+2. The repository exposes a documented local command or opt-in hook path to
+   refresh GitNexus after checkout/merge and Graphify after code changes; it
+   records success, failure, or skipped state and never blocks a commit on an
+   unbounded rebuild.
+3. A fixture proves correct behavior for edit, deletion, branch switch, merge,
+   pull/rebase-equivalent replacement, watcher loss, and restart; no answer may
+   silently claim an unverified index is fresh.
+4. The lifecycle replay reports freshness latency and resource cost separately
+   from query quality and preserves any unavailable external tool as a blocker.
+
+### C35 — Produce local interactive architecture and call-flow visualizations
+
+- Status: implemented
+- Priority: P2
+- Disposition: Should close
+- DependsOn: C3, C13, C24, C33
+- Competitors: Graphify, GitNexus
+- Touches: `bin/cli.ts`, `src/visualization.ts`,
+  `src/__tests__/unit/visualization.spec.ts`,
+  `benchmarks/evaluations/competitive-visualization/`, docs
+- What: evaluate and, if the evidence justifies it, generate deterministic
+  local HTML architecture and call-flow artifacts from knodin's bounded graph
+  facts without adding a new MCP tool, hosted renderer, source egress, or a
+  mandatory long-lived service.
+- Evaluation evidence:
+  `benchmarks/evaluations/competitive-visualization/raw-results-20260723.json`
+  records Graphify's pinned community-graph, tree, and call-flow artifacts and
+  GitNexus's explicit lack of a deterministic static-artifact command. knodin's
+  checked-in evaluation artifact is self-contained, deterministic, bounded,
+  source-commit/index-freshness tagged, and source-evidenced. `knodin visualize
+  <entry> --output <path.html>` now exposes that bounded artifact as a local
+  CLI-only export with 1–6 depth, a 4–64 KiB generation ceiling, safe in-repo
+  output paths, and stable identity/file/kind entry disambiguation. It adds no
+  MCP operation, hosted renderer, credential, telemetry, or source egress.
+
+### Acceptance criteria
+
+1. The evaluation compares Graphify's community graph, tree, and call-flow
+   artifacts with a knodin artifact generated from the same pinned fixture.
+2. Generated HTML is self-contained or uses only local static assets, records
+   its source commit/index freshness, and links every displayed edge to bounded
+   source evidence or an explicit heuristic label.
+3. The artifact supports at least subsystem drill-down, hub/bridge inspection,
+   and bounded call-flow navigation while respecting C3 output and generation
+   budgets.
+4. It remains an optional CLI/export capability behind the existing `knodin`
+   gateway: no new top-level MCP tool, network service, credential, or source
+   egress is introduced.
+
+### C36 — Instrument the current warm-operation performance paths
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C18, C24
+- Evidence: opt-in, source-free phase accounting now attributes freshness,
+  graph analytics, traversal snapshots, architecture facets, context
+  composition, status audit, pack walking/serialization, and artifact
+  read/grep. `perf.spec.ts` verifies the complete phase record without latency
+  thresholds.
+- Touches: `src/engine/perf.ts`, `src/engine/index.ts`, `src/context.ts`,
+  `src/context-export.ts`, targeted unit tests
+- What: add opt-in phase accounting around the current production paths without
+  changing response contracts or enabling a competitor replay.
+
+### Acceptance criteria
+
+1. Phase names separately cover freshness, graph analytics, traversal snapshot,
+   architecture facets, context composition, status audit, pack walk,
+   serialization, and artifact read/grep.
+2. Instrumentation remains inert unless a performance session is active and
+   records no source content.
+3. Targeted tests verify phase accounting without wall-clock thresholds.
+4. No competitor or before/after comparison is run until C37-C40 are complete
+   and the repository owner explicitly approves the replay.
+
+### C37 — Reuse generation-scoped graph analytics and traversal snapshots
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C36
+- Evidence: minimal and standard map now share one generation-keyed analytics
+  snapshot; traversal uses a compact signed adjacency plus cached definition
+  metadata; architecture membership/cohesion/coupling aggregation is one-pass.
+  Option-keyed analytics/minimal-map caches and per-repository traversal/status
+  caches have explicit entry ceilings rather than unbounded process growth.
+  `typed-traversal.spec.ts` proves both map and traversal snapshots invalidate
+  after an incremental index generation.
+- Touches: `src/engine/index.ts`, `src/__tests__/unit/map.spec.ts`,
+  `src/__tests__/unit/typed-traversal.spec.ts`,
+  `src/__tests__/unit/uniform-filters.spec.ts`
+- What: cache immutable graph analytics, bidirectional typed adjacency, and
+  symbol metadata by repository/federation configuration plus index generation.
+
+### Acceptance criteria
+
+1. Minimal and standard map modes share one generation-scoped analytics source
+   while retaining their existing response shapes and truthful totals.
+2. Traversal performs bounded BFS over cached adjacency with no per-result
+   symbol lookup and preserves identity, direction, filters, evidence, and
+   deterministic ordering.
+3. Architecture facets and coupling use one-pass identity-to-community indexes
+   rather than repeated community-by-edge searches.
+4. Index, reconcile, watcher flush, repair, and close invalidate every affected
+   cache; tests prove no stale result survives a generation change.
+
+### C38 — Compose orientation context from one shared snapshot
+
+- Status: implemented
+- Priority: P1
+- Disposition: Should close
+- DependsOn: C37
+- Evidence: `buildKnodinContext` establishes the standard map snapshot once,
+  then composes stats, flows, and optional review over that initialized
+  generation. `context-composition.spec.ts` verifies at most one probe and the
+  existing compact caps/contracts without timing assertions.
+- Touches: `src/context.ts`, `src/engine/index.ts`,
+  `src/__tests__/unit/knodin-tools.spec.ts`,
+  `src/__tests__/unit/freshness.spec.ts`
+- What: acquire one freshness-qualified engine snapshot, reuse C37 analytics,
+  and compose independent context fields without repeating graph construction.
+
+### Acceptance criteria
+
+1. One context request performs at most one freshness probe and one graph
+   analytics construction for its repository generation.
+2. Stats, communities, hubs, flows, and optional risk retain their current
+   contract, sorting, caps, and evidence.
+3. Independent work may run concurrently only after initialization is complete;
+   no SQLite writer concurrency or duplicate engine singleton is introduced.
+4. Tests use counters and cache state, not timing thresholds.
+
+### C39 — Separate fast truthful status from explicit deep audit
+
+- Status: implemented
+- Priority: P1
+- Disposition: Should close
+- DependsOn: C36
+- Evidence: warm status reuses a generation/database-fingerprint keyed deep
+  audit only after the existing bounded drift probe verifies the source state.
+  Responses identify `deep-audit` versus
+  `cached-after-freshness-probe` and include `verifiedAt`; `--deep` and MCP
+  `statusAudit: deep` force the complete audit. `index-health.spec.ts` proves
+  warm reuse, explicit deep mode, and file-change invalidation.
+- Touches: `src/engine/index.ts`, `src/tools/knodin-tools.ts`, `bin/cli.ts`,
+  `src/__tests__/unit/index-health.spec.ts`
+- What: return an invalidation-safe cached health snapshot for warm status and
+  expose the existing filesystem/database verification as an explicit deep
+  audit, with verification age and mode reported truthfully.
+
+### Acceptance criteria
+
+1. Default warm status never claims a fresh audit when it is returning cached
+   evidence; it reports verification mode and timestamp.
+2. Deep audit preserves current missing, damaged, orphaned, coverage, and repair
+   behavior.
+3. Index generation, watcher changes, repair, schema change, and relevant file
+   events invalidate the cached snapshot.
+4. Existing callers remain source-compatible and a caller can explicitly
+   request the deep audit.
+
+### C40 — Make context packing and artifact access linear and cache-safe
+
+- Status: implemented
+- Priority: P1
+- Disposition: Should close
+- DependsOn: C36
+- Evidence: glob/policy matchers are bounded and compiled once, walking uses one
+  accumulator, exact per-file serialization deltas replace accumulated
+  reserialization, and artifact lines use a two-entry/four-MiB-per-file
+  path/mtime/size cache. Context-export and response-budget tests preserve
+  formats, policies, ordering, hard budgets, safe paths, reads, grep, and cache
+  invalidation.
+- Touches: `src/context-export.ts`,
+  `src/__tests__/unit/context-export.spec.ts`,
+  `src/__tests__/unit/response-budget.spec.ts`
+- What: precompile selection policy, prune excluded directories, account bytes
+  incrementally, serialize once, and reuse a bounded artifact line index keyed
+  by path/mtime/size.
+
+### Acceptance criteria
+
+1. Candidate walking and pattern matching are linear in visited paths plus
+   patterns; patterns are compiled once per request.
+2. Packing does not rebuild the entire accumulated artifact per candidate and
+   still enforces exact response byte/token ceilings.
+3. Artifact read/grep reuse a bounded cache only when path, size, and mtime
+   match; mutation and replacement invalidate it.
+4. Markdown, JSON, XML, policies, tree/Git sections, deterministic ordering,
+   ranged reads, regex grep, and telemetry remain byte-for-byte compatible in
+   golden fixtures.
+
+### C41 — Replay like-for-like performance after the implementation batch
+
+- Status: evaluated — deferred
+- Priority: P0
+- Disposition: Evaluate
+- DependsOn: C37, C38, C39, C40
+- Evidence: the terminal bounded replay and strengthened-oracle verdict are
+  preserved at
+  `benchmarks/competitors/runs/20260802T203822521Z-3e27547d095e/`. Its
+  `c41-verdict.json` verifies all five competitors, explicit warm/cold p50/p95,
+  independently attributed two-sided RSS, and grepai cached/deep lifecycle
+  rows. Under the strengthened labels, 19 mapped rows passed, 10 failed, four
+  grepai trace rows were unavailable, and six intentionally unmatched Repomix
+  rows remained incomparable. Graphify passed its direct-call rows but not hub
+  rows; codebase-memory passed six of ten search/traversal/package rows;
+  Repomix passed seven pack/read/grep rows; code2prompt passed both pack rows;
+  and grepai produced no oracle-qualified latency row because its local index
+  remained empty. The bounded local-Ollama indexing attempts at
+  `20260802T205026646Z-18c1107af915/`,
+  `20260802T205625288Z-e97db4c32eb6/` preserve that setup limitation. Earlier
+  runs retain the sandbox-launch, timeout, and uninitialized-index failures
+  rather than overwriting them.
+- Evaluation disposition: retain the current product unchanged and defer any
+  aggregate performance claim or optimization response. Only oracle-passing
+  exact rows may support operation-specific observations; failures,
+  unavailable rows, and setup limits remain separate dimensions and cannot
+  become wins.
+- Touches if approved: competitor harness mappings, immutable run artifacts,
+  `benchmarks/competitors/COMPETITIVE-AUDIT.md`, this roadmap
+- What: after explicit repository-owner permission, run warm/cold p50/p95/RSS
+  measurements using equivalent operations, budgets, fixtures, and correctness
+  oracles. A user instruction to complete this roadmap constitutes permission
+  for the checked-in, zero-spend, local replay only; network access, installation
+  of unpinned software, publication, or external mutation still requires its own
+  authority.
+
+### Evaluation gate
+
+1. Graphify traversal/map rows use the same direction, relation, depth, item,
+   token, and evidence scope.
+2. codebase-memory architecture/search rows use the same facets, pagination,
+   source inclusion, and correctness labels.
+3. code2prompt and Repomix compare with knodin `pack`, packed read, and packed
+   grep—not semantic `context`, `search`, or `file_summary`.
+4. grepai status compares cached summary with cached summary and deep audit with
+   an equivalent verified lifecycle phase.
+5. Results record correctness before latency and treat RSS/setup failures as
+   separate dimensions.
+
+### C42 — Enforce comparable competitive cases and correctness oracles
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C41
+- Evidence: `src/competitive-contract.ts` and the competitor mappings enforce
+  typed equivalence/oracle dispositions; the Repomix replay qualifies 18
+  comparable rows and excludes wrong-fast, partial, unverified, and
+  incomparable rows from wins.
+- Touches: `src/competitive-manifest.ts`, `src/competitive-runner.ts`,
+  `scripts/competitive-bakeoff.ts`, competitor adapters, labeled competitive
+  fixtures and runner tests
+- What: define one typed case contract for equivalent operation scope, budgets,
+  fixtures, and correctness. Incomparable or wrong-fast rows must never count as
+  latency wins.
+
+### Acceptance criteria
+
+1. Every timed pair records use case, fixture revision, mode, scope, budgets,
+   and a comparable/incomparable disposition with a reason.
+2. Graphify, codebase-memory, Repomix, code2prompt, and grepai mappings satisfy
+   C41's exact equivalence rules; unmatched rows are excluded explicitly.
+3. Comparable rows carry checked-in correctness oracles, and summaries
+   distinguish oracle pass, oracle failure, unavailable, and incomparable.
+4. Partial runs and rows without passing oracles cannot produce a competitive
+   win or aggregate performance claim.
+
+### C43 — Measure cold/warm p50, p95, and independent process RSS
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C42
+- Evidence: `benchmarks/competitors/MEASUREMENT-CONTRACT.md` and shared sampling
+  record three warmups, at least 20 warm samples, raw values, p50/p95/range,
+  independently attributed RSS, descendant cleanup, and atomic partial
+  summaries across all 11 adapters.
+- Touches: shared competitive measurement helper, competitor adapters,
+  `scripts/competitive-bakeoff.ts`, lifecycle runner, normalized summaries and
+  tests
+- What: replace copied three-sample loops and aggregate process-tree ceilings
+  with a shared statistical and resource-measurement contract.
+
+### Acceptance criteria
+
+1. Warm and cold samples are separate and retain raw samples, warm-up count,
+   p50, p95, minimum, and maximum; the documented warm sample minimum supports a
+   meaningful p95.
+2. knodin and competitor RSS are attributed independently by process and phase;
+   combined harness RSS is never assigned to either product.
+3. Per-call and per-competitor timeouts reap descendants, preserve partial
+   evidence, identify the failed phase/case, and still write a terminal summary.
+4. Regression checks compare matching modes and enforce both p50 and p95
+   tolerances after correctness passes.
+
+### C44 — Restore low-latency diff review without weakening evidence
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C43
+- Evidence: `benchmarks/evaluations/competitive-review/` records an
+  oracle-qualified bounded-gateway replay at 53.018 ms p50, 89.449 ms p95, and
+  733 bytes; review tests preserve path-scoped churn/risk, diff scopes, flows,
+  cache invalidation, and immutable evidence provenance.
+- Touches: `src/engine/index.ts`, `src/engine/perf.ts`, review/flow tests and
+  competitive-review evidence
+- What: remove per-file Git history processes and whole-repository repeated work
+  from warm review while preserving changed-file, risk, flow, and source
+  evidence.
+
+### Acceptance criteria
+
+1. Review phase telemetry separates diff discovery, churn, parsing, flow lookup,
+   and serialization.
+2. Churn/history is collected in one bounded pass or a repository/HEAD cache,
+   and affected flows use a generation-scoped file-to-flow lookup.
+3. All diff scopes and existing correctness fixtures remain unchanged.
+4. The oracle-qualified warm minimal review meets the recorded C43 regression
+   threshold on both p50 and p95.
+
+### C45 — Add facet-selective architecture fast paths
+
+- Status: implemented
+- Priority: P1
+- DependsOn: C43
+- Evidence: `benchmarks/evaluations/competitive-architecture/` records an
+  oracle-qualified bounded-gateway replay at 0.082 ms p50 and 0.097 ms p95;
+  architecture tests prove facet-selective construction, zero minimal edge
+  materialization, mutation isolation, budgets, and generation/close
+  invalidation.
+- Touches: `src/engine/index.ts`, architecture/map tests and
+  competitive-architecture evidence
+- What: compute only requested architecture facets from reusable
+  generation-scoped metadata instead of building a complete standard map.
+
+### Acceptance criteria
+
+1. Language, package, layer, entry-point, boundary, coupling, and hotspot
+   requests construct only their required inputs.
+2. Minimal facet requests do not build full edge lists or hydrate unrelated
+   source/symbol detail.
+3. Identity, filters, pagination, totals, budgets, and cache invalidation remain
+   correct.
+4. Equivalent architecture rows pass their oracle and C43 thresholds.
+
+### C46 — Cache search state and hydrate only the requested page
+
+- Status: implemented
+- Priority: P1
+- DependsOn: C43
+- Evidence: `benchmarks/evaluations/competitive-search/` records a
+  same-oracle 500-symbol offset-page improvement from 5.309/5.865 ms to
+  0.310/0.481 ms p50/p95; tests preserve exact-default search, global ordering,
+  totals, pagination, filters, ANN gating, federation, corruption, and budgets.
+- Touches: `src/engine/index.ts`, search/tool contracts, search and ANN tests,
+  competitive-search evidence
+- What: reuse decoded generation-scoped search metadata, rank before hydration,
+  and perform source/caller work only for the requested page.
+
+### Acceptance criteria
+
+1. Cheap filters run before vector scoring and source hydration; community
+   lookup does not build a full map.
+2. Exact search remains the default unless the existing ANN recall gate passes.
+3. Global ordering, offset pagination, totals, corruption handling, federation,
+   and response budgets remain deterministic.
+4. A separately specified opaque cursor may be added only if it binds query,
+   filters, order, and generation and truthfully rejects stale cursors.
+
+### C47 — Reduce status, repair, and measured lifecycle resource cost
+
+- Status: implemented
+- Priority: P1
+- DependsOn: C43
+- Evidence: `benchmarks/evaluations/competitive-lifecycle/` records isolated,
+  ownership-labeled lifecycle stages and immutable provenance; health tests
+  prove lease expiry guards, single-flight deduplicated batch repair, one
+  invalidation, and final forced deep verification.
+- Touches: `src/engine/index.ts`, `src/engine/perf.ts`, lifecycle runner,
+  freshness/index-health/watcher tests
+- What: eliminate duplicate freshness/audit work, batch repair indexing, and
+  reduce only resource retention demonstrated by isolated C43 measurements.
+
+### Acceptance criteria
+
+1. Cached status reuses a valid freshness lease and deep-audit snapshot without
+   claiming unverified freshness; lease expiry still performs the missed-watcher
+   guard.
+2. Repair reuses valid audit evidence, deduplicates paths, batches indexing and
+   orphan cleanup, invalidates once, and completes one final deep verification.
+3. The lifecycle runner records isolated baseline, post-index, post-query,
+   post-close, peak RSS, and disk measurements for each product.
+4. Cache/parser changes are accepted only when attribution proves a retained
+   owner and lifecycle correctness remains intact.
+
+### C48 — Decide an optional local project-memory boundary
+
+- Status: evaluated — deferred
+- Priority: P2
+- DependsOn: C42
+- Decision: defer production work. The evaluated workflows do not yet
+  demonstrate value beyond repository-owned documentation, while a memory
+  surface would add a second source of truth, retention/privacy obligations,
+  and an output-budget surface. See
+  [`docs/adr/004-optional-project-memory.md`](../docs/adr/004-optional-project-memory.md)
+  and the
+  [C48 evaluation](../benchmarks/evaluations/c48-project-memory/evaluation.md).
+- Touches: roadmap/ADR and Serena memory evaluation evidence; no production
+  code because the evaluation gate did not pass
+- What: evaluate concrete durable-note workflows without turning generalized
+  agent memory into a core graph/index requirement.
+
+### Evaluation gate
+
+1. Record user workflows, path containment, retention/backup, privacy, output
+   budgets, and RSS/disk cost against Serena's memory operations.
+2. Prefer an optional local `.reckon/notes/` adapter that does not affect graph
+   identity, indexing, freshness, or the one-tool gateway count.
+3. Approve production work only when a labeled workflow demonstrates value
+   beyond ordinary repository documentation.
+4. If approved, require atomic writes, traversal protection, deterministic
+   list/read/edit/rename/delete behavior, and explicit size budgets.
+
+### C49 — Keep immutable runs lint-safe and make the full suite terminate
+
+- Status: implemented
+- Priority: P1
+- DependsOn: —
+- Evidence: Biome excludes only immutable `benchmarks/competitors/runs/**`;
+  handle diagnostics and teardown coverage close watchers, databases, queues,
+  and child processes. The full coverage suite terminates naturally within the
+  documented six-minute ceiling (474/474 in the final C47 gate).
+- Touches: `biome.json`, `package.json`, Vitest configuration/setup,
+  watcher/freshness teardown tests, competitive-run documentation
+- What: exclude immutable generated evidence from formatting gates while
+  diagnosing and fixing the open handle that prevents the full suite from
+  exiting.
+
+### Acceptance criteria
+
+1. Biome ignores `benchmarks/competitors/runs/**` but continues checking
+   generators, baselines, labels, schemas, and source.
+2. A hanging-process diagnostic command identifies active handles without
+   masking them through force-exit.
+3. Watchers, databases, queues, and spawned test children are asserted closed in
+   teardown, including injected-failure paths.
+4. `bun run lint` and the full test suite terminate naturally within the
+   repository's documented ceiling.
+
+### C50 — Make the single-worker full-suite gate start reliably
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C49
+- Touches: Vitest configuration/setup, embedding test doubles and teardown,
+  gate documentation, and a worker-start regression fixture
+- What: eliminate repeated native ONNX initialization or worker churn that can
+  exhaust Vitest's 600-second pool ceiling before all test files start, without
+  skipping files, forcing exit, weakening isolation blindly, or changing
+  production embedding behavior.
+
+### Acceptance criteria
+
+1. A diagnostic reproduces and attributes the failed fork-worker startup for
+   `knodin.test.ts`, `map.spec.ts`, and the lifecycle runner instead of
+   increasing the timeout.
+2. Tests use an explicit deterministic embedder where semantic model quality is
+   not under test; dedicated embedding tests retain production-path coverage.
+3. All test files start, the full suite passes, and each fresh-worker shard
+   exits naturally under its bounded five-minute test ceiling with immutable
+   run artifacts present in the checkout.
+4. Lint, typecheck, build, coverage thresholds, native-resource teardown, and
+   production local-embedding behavior remain unchanged.
+
+### Evidence and corrected diagnosis
+
+- Root cause (corrected): the handoff attributed the startup failures to repeated
+  ONNX init, but a diagnostic reproduced them with the three ONNX-free canary
+  files alone. The real cause is `isolate: true` (Vitest default): the pool
+  re-forks a **fresh process per test file** — the config's stated "keep one
+  long-lived worker" intent was never achieved — and under host load a per-file
+  fork spawn intermittently exceeds Vitest's 60 s worker-start handshake
+  (`START_TIMEOUT`), failing a neighbouring file. Actual test work is ~200 s
+  (well under the ceiling); the overage was pure per-file fork churn.
+- Fix: `isolate: false` + `singleFork` (one reused process — the documented
+  intent, not a blind isolation weakening), so native modules init once and only
+  one fork is ever spawned. Cross-file safety is preserved by explicit guards:
+  the shared deterministic lexical embedder is installed by setup and restored by
+  every teardown; a per-test env/cwd snapshot-restore plus `restoreMocks`/
+  `unstubEnvs`; the real ONNX model is isolated to `embeddings.spec` (loaded once,
+  disposed after) and guarded by a `getRealEmbedderLoadCount()` regression; the
+  six competitive benchmark `runner.spec.ts` files spawn their sub-benchmarks
+  asynchronously (no synchronous `execFileSync` blocking the worker); and removed
+  per-test repo state (SQLite handles + FSWatcher/FSEvent descriptors) is evicted
+  each test.
+- Verified: the gate uses 16 strictly sequential, fresh-worker shards so
+  native SQLite/watcher state cannot accumulate across the whole suite. The
+  two semantic-ranking specs pass on the deterministic lexical embedder; lint,
+  typecheck, and build pass. Final integration certification passed all 87
+  files/503 tests in 1,471.79 seconds with 597,917,696 bytes peak RSS, and its
+  merged 503-test coverage run passed at 89.5% statements, 79.25% branches,
+  90.62% functions, and 91.8% lines (901,840,896 bytes peak RSS). No tests or
+  files are quarantined or skipped to obtain these results.
+- Release certification still reruns the fully accumulated integration checkout
+  under C54; this distinction prevents cumulative-branch evidence from being
+  mislabeled as a final integration-branch run.
+
+### C51 — Native training-free embedding quantization (memory-efficient vector search)
+
+- Status: evaluated — rejected for production
+- Priority: P2
+- DependsOn: C46
+- Touches: `src/engine/embeddings.ts`, `src/engine/index.ts` (exact scan + ANN
+  path), the `symbol_embeddings` storage, and a recall-gate fixture
+- What: add an opt-in, in-process, data-oblivious quantization of the 384-dim
+  symbol embeddings — normalize → fixed deterministic rotation → precomputed
+  bucketing (the TurboQuant concept, implemented natively in TypeScript) —
+  shrinking stored vectors ~8× (4-bit) and speeding the cosine scan, with float32
+  remaining authoritative and the safe default. This is the memory-efficient
+  vector-search lever that keeps the zero-auth / local / no-egress / one-process
+  guarantees intact, versus competitors that reach for a hosted vector DB. It is
+  explicitly **not** a sidecar, external index, Rust dependency, or hosted store.
+  See [ADR 005](../docs/adr/005-native-embedding-quantization.md).
+- Evidence: `benchmarks/evaluations/c51-quantization/raw-results.json` binds a
+  2,048-vector real MiniLM fixture and preserves per-query top-5/top-10 overlap,
+  rank correlation, estimated database/resident payload bytes, conversion time,
+  3+20 warm and five cold samples, peak RSS, constraints, gates, and disposition. The fixed-seed
+  block-Hadamard 4-bit prototype used 20 unique queries per tier and achieved
+  mean top-10 recall 96%, 93.5%, and 92% at 128, 512, and 2,048 vectors. It
+  therefore failed the >=95% gate at two engagement sizes.
+  Payloads were 8× smaller, but warm p50 was not materially better and
+  conversion-inclusive cold p50 was worse at every size; 99,876,864-byte peak
+  process RSS did not establish an attributable end-to-end RSS win.
+- Disposition: reject production quantization from this design. Float32 remains
+  authoritative and unchanged. Representation shrink without the recall gate
+  and a material end-to-end latency or memory win does not authorize production
+  work, so no separately numbered implementation item is proposed.
+
+### Acceptance criteria
+
+Evaluation outcome: criteria 1 and 4 hold for the prototype; criterion 3 fails
+at 512 and 2,048 vectors. Criterion 2 is deliberately not implemented because
+the failed evaluation does not authorize a production path or environment gate.
+
+1. Encode/decode is deterministic (hard-coded rotation seed) and reproducible
+   across machines, with no trained or per-repo codebook and no calibration pass.
+2. Quantized codes are opt-in behind an env gate (default off); float32 stays the
+   source of truth and is rebuildable/invalidated by the existing generation
+   counter.
+3. A committed real-vector fixture proves at least 95% mean top-10 recall against
+   the float32 exact scan at every size where the path could engage, mirroring
+   the R18/R48 gate. Report top-5/top-10 overlap, rank correlation, database and
+   resident bytes, conversion time, cold/warm p50/p95, and peak RSS. Eligibility
+   additionally requires a material end-to-end latency or memory win; an inner-
+   loop-only improvement is insufficient.
+4. No external index, sidecar, Rust/native dependency, hosted DB, or source/vector
+   egress; the embedding model, its dimensionality, and its normalization are
+   unchanged.
+
+### C52 — Package repository lifecycle initialization and refresh
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C16, C34, C50
+- Touches: `src/init.ts`, `src/repository-management.ts`, the deprecated
+  `src/fleet.ts` compatibility adapter, `src/indexable-paths.ts`,
+  `bin/cli.ts`, `src/engine/index.ts`, `scripts/pack-install-smoke.ts`,
+  repository-init/CLI acceptance tests, package build output
+- What: make the compiled package usable across existing repositories without a
+  knodin source checkout. Resolve the installed executable in hooks, share one
+  canonical indexable-path policy, refresh after commit/checkout/merge/rewrite,
+  and initialize repository checkouts idempotently.
+
+### Acceptance and evidence
+
+1. `knodin init` preserves existing hook content, supports worktrees and
+   `core.hooksPath`, and repeated initialization produces no duplicate knodin
+   blocks.
+2. Hook refresh selects paths through the engine's canonical policy, including
+   TypeScript and supported Salesforce Apex, Aura, LWC, and metadata inputs.
+3. `knodin repos init` discovers Git roots deterministically, deduplicates real
+   paths/worktrees, supports dry-run and JSON output, and records individual
+   failures without abandoning the remaining repositories. The historical
+   `knodin fleet init` spelling remains a time-bounded compatibility alias.
+4. `scripts/pack-install-smoke.ts` installs the exact tarball in a clean external
+   repository and proves package-resolved hooks across post-commit,
+   post-checkout, post-merge, post-rewrite, rename, and deletion lifecycle
+   events.
+
+Evidence: packaged hooks landed in `c3a10a5`, fleet initialization in `72211ab`,
+and the clean-consumer gate in `1a6dbca`. The 0.1.0 candidate gate completed 49
+sequential commands with 465 MiB peak aggregate RSS.
+
+### C53 — Make repair observable, cancellable, and resumable
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C47, C52
+- Touches: `src/engine/index.ts`, `bin/repair-progress.ts`, `bin/cli.ts`,
+  `docs/specs/repair-progress-telemetry.md`, index-health and CLI progress tests,
+  packed-install repair acceptance
+- What: expose truthful phase/file progress for long repairs, preserve completed
+  transactions on cancellation, and provide composable human and machine CLI
+  output.
+
+### Acceptance and evidence
+
+1. Engine events carry monotonic sequences and counters, repository-relative
+   source-safe paths, Salesforce metadata families, and terminal completion,
+   cancellation, or failure without allowing callback errors to fail repair.
+2. `AbortSignal` boundaries leave committed files recoverable, avoid recording
+   a successful reconciliation on cancellation, and let the next audit resume
+   from `index_state`; concurrent callers receive their own event stream.
+3. CLI progress supports automatic TTY, plain, JSON, JSONL, and silent modes;
+   progress uses stderr except for JSONL envelopes, and final results retain
+   deterministic stdout.
+4. Unit/CLI tests and the installed-tarball smoke gate cover cancellation,
+   resumption, throttling, heartbeat, stream separation, and argument
+   validation.
+
+Evidence: the engine event foundation landed in `e0dcb5f`, cancellation and
+resumption in `1dc74cb`, and CLI rendering/validation in `a05edcd` and
+`c0d6745`; the installed-tarball gate exercises all five CLI output modes.
+
+### C54 — Certify the local 0.1.0 release artifact
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C50, C52, C53
+- Touches: `package.json`, `bun.lock`, `README.md`,
+  `docs/releases/0.1.0.md`, this roadmap,
+  `docs/specs/repair-progress-telemetry.md`,
+  `scripts/pack-install-smoke.ts`, compiled package/tarball evidence
+- What: version the first fleet-consumable package, prove it from a clean
+  consumer under the 3 GiB development cap, reconcile roadmap/spec truth, and
+  produce a local release commit and tag without claiming a remote or registry
+  publication.
+
+### Acceptance and evidence
+
+1. Package metadata identifies `0.1.0`, and `bun.lock` is regenerated from that
+   manifest (Bun's lock format does not duplicate the workspace version); the
+   exact `knodin-0.1.0.tgz` passes the clean-consumer acceptance gate with
+   an aggregate process-tree limit of 2,750 MiB.
+2. Lint, typecheck, build, documentation checks, and the full suite pass
+   sequentially under the memory cap; C50 is not closed through quarantine,
+   skipped files, or forced exit. Fresh-worker shards use a bounded five-minute
+   default test ceiling for loaded-host graph builds while replay subprocesses
+   retain tighter explicit limits.
+3. README and release notes distinguish source-checkout use, local packed
+   installation, and actual npm/remote publication state.
+4. Tasks 1–3 in the repair telemetry specification are recorded complete while
+   the MCP progress bridge, `--plan`, embedding detail, large Salesforce replay,
+   and incremental embedding work remain explicitly pending.
+
+Evidence to date: the final exact `knodin-0.1.0.tgz` replay passed 49
+sequential clean-consumer commands in 43,917 ms with 478 MiB peak aggregate RSS
+against the 2,750 MiB fail-closed limit. Final integration lint, typecheck,
+build, 503-test suite, and merged coverage gates pass under 3 GiB (the highest
+observed gate RSS is 901,840,896 bytes). The local release commit is tagged
+`v0.1.0`; no remote or registry publication is implied.
+
+### C55 — Pin and audit the authorized Token Optimizer source
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C24
+- Touches:
+  `benchmarks/evaluations/token-optimizer-20260730/comparison-manifest.json`,
+  `scripts/token-optimizer-source-audit.ts`, immutable raw audit evidence, and
+  manifest-consistency tests
+- What: replace the demo-only source assumption with an authorized,
+  commit-bound GHES audit while preserving the distinction between source
+  evidence and equivalent behavioral measurement.
+
+### Acceptance and evidence
+
+1. The comparison pins repository, revision, Git tree, file blobs, README hash,
+   and demo hash; branch movement cannot alter the evaluated input.
+2. An executable audit fetches blobs by immutable revision and fails closed on
+   a different commit, truncated tree, missing file, contradicted finding, or
+   failed behavioral probe.
+3. The audit verifies parser strategy, checked-in test inventory, shell and
+   containment posture, path scope, telemetry fields/defaults, token/baseline
+   math, compression budget behavior, dependency range, update/provenance
+   inventory, and installation steps.
+4. The manifest remains `behavior-partial`: source verification must not be
+   presented as production routing, savings, or end-to-end parity evidence.
+
+Evidence:
+`benchmarks/evaluations/token-optimizer-20260730/raw-source-audit-20260730.json`
+pins commit `a2b9cef5efdfcf0393e9e7a5ded229ffd9f613d7`, 17 files, and 16 verified
+findings. Its behavioral probe returns 104 lines for 100 matching input lines
+despite `max_lines=50`.
+
+### C56 — Replay all seven Token Optimizer workflows
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C55
+- Evidence:
+  `benchmarks/evaluations/token-optimizer-20260730/raw-behavior-replay-20260730.json`
+
+The immutable replay executes 20 warm and five cold-process samples per
+operation, uses the real `o200k_base` tokenizer, and applies shared correctness
+oracles to all five structural workflows. Both products pass those oracles.
+The final C68 replay records knodin as smaller in real tokens and faster at warm
+p50/p95 for all five structural cases on the small fixture; its cold-process
+startup remains materially slower, and command execution remains gated. The competitor compressor
+preserves the labeled diagnostic strings but returns 29 lines for a requested
+maximum of 20. knodin's C57 compressor preserves 7/7 detected signals in 14
+lines with hard byte/line budgets, exact omission accounting, and retained
+local drill-down. Its selected content is smaller; its complete recovery
+envelope remains 18 tokens larger on this fixture.
+
+### C57 — Bounded recoverable diagnostic-output compression
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C3, C55
+- Evidence:
+  `src/output-compression.ts`,
+  `src/__tests__/unit/output-compression.spec.ts`,
+  `src/__tests__/unit/output-compression-cli.spec.ts`,
+  `benchmarks/evaluations/token-optimizer-20260730/raw-behavior-replay-20260730.json`,
+  and `docs/COMMAND-OUTPUT-COMPRESSION.md`
+
+knodin accepts already-produced combined text, ordered stdout/stderr events, or
+a repository-contained log artifact. It deterministically applies `smart`,
+`head-tail`, or `errors-only` selection with generic and ecosystem-specific
+adapters; enforces hard rendered-line and UTF-8 content-byte budgets; preserves
+exit/signal metadata; reports unpreserved signals rather than overstating
+fidelity; records exact omitted line/source-byte ranges; and retains bounded
+private drill-down by SHA-256 identity without rerunning a command.
+
+The pinned adversarial replay measures 604 raw tokens. knodin returns 109
+content tokens and a 205-token recovery envelope while preserving 7/7 detected
+signals in 14/20 lines. The competitor returns 187 tokens and preserves every
+golden string, but emits 29 lines for a requested maximum of 20. This supports
+the narrow `verified-stronger-budget-and-recovery` classification, not a broad
+claim that every compression dimension is stronger.
+
+Command execution is not part of C57. C58's portable-containment evaluation was
+rejected, and direct MCP `text` input does not prove context savings when raw
+text has already crossed the model boundary.
+
+### C58 — Gate command execution on reviewed portable containment
+
+- Status: evaluated — rejected
+- Priority: P0
+- Disposition: evaluated — rejected
+- DependsOn: C57
+- Owner roles: security reviewer, release owner, and one platform certifier for
+  each supported operating system
+- Touches only if approved: a disposable command-runner prototype, adversarial
+  containment fixtures, platform evidence, threat model, and a separately
+  reviewed production implementation item
+- Evidence: `benchmarks/evaluations/c58-containment/` contains the disposable
+  prototype, adversarial fixture, native macOS raw result, methodology, threat
+  model, tests, and independent `c58-security-review-r1` dated 2026-08-02.
+- Terminal disposition: `evaluated — rejected`. Native macOS evidence passed
+	the bounded defense-in-depth cases, but repository cwd/path checks are not a
+	filesystem or network sandbox, process polling retains escape/PID races, and
+	Linux/Windows are explicitly unavailable. Production execution remains
+	absent and no implementation item is created.
+- Post-evaluation gate hardening: the three-level fixture now starts its 100 ms
+	containment window only after an exact bounded readiness handshake, with a
+	separate startup deadline and silent-tree cleanup test. This removes a
+	coverage-timing race without changing raw evidence, platform omissions,
+	security limitations, or the rejected disposition.
+
+The evaluation decides whether knodin can safely execute a caller-supplied
+command before compressing its output. C57's already-produced text and artifact
+inputs remain the production default. Merely matching a competitor workflow is
+not sufficient to authorize execution.
+
+Evaluation gate:
+
+1. Build no production command surface. First produce a disposable prototype
+   using no-shell argv execution, repository-root binding, a minimal sanitized
+   environment, stdin closure, output/time/RSS/process-count limits, and
+   process-tree termination on every proposed supported platform.
+2. Check in adversarial fixtures for shell metacharacters, traversal, symlink
+   escape, inherited secrets, descriptor inheritance, child/grandchild escape,
+   detached processes, output floods, timeout races, signals, and cancellation.
+3. Record native macOS, Linux, and Windows results independently. Unsupported
+   containment primitives or an unavailable platform are explicit omissions,
+   not inferred portability.
+4. Require an independent security review of the threat model and residual
+   risks. Retain its revision, date, findings, and disposition without including
+   credentials or private source.
+5. Close with exactly one disposition: `evaluated — rejected`, `evaluated —
+   deferred`, or a newly numbered implementation item with its own acceptance
+   criteria. C58 itself never authorizes shipping from prototype evidence.
+6. If rejected or deferred, keep command execution absent and update the
+   scorecard limitation. This is a valid terminal outcome and does not block
+   C67 when the exclusion remains explicit.
+
+### C57–C67 — Token Optimizer parity and trusted-distribution program
+
+- Status: parked-external-evidence — 2026-08-02
+- Previous status: active
+- Source objective: the checked-in comparison manifest and the DTS competitive
+  goal accepted on 2026-07-30
+- Ordering: behavioral replay (C56) precedes claims; safe compression (C57)
+  precedes failure-to-code intelligence (C59); command execution (C58) remains
+  excluded after its rejected evaluation; signed trust (C62) precedes update
+  mutation (C63), release attestation
+  (C64), and adversarial supply-chain proof (C65); the scorecard and release are
+  terminal gates.
+
+The program must preserve these invariants:
+
+1. Every competitor capability is either verified equivalent/stronger, recorded
+   weaker, or explicitly excluded by a reviewed safety gate.
+2. Compression has a hard truthful budget, exact omission accounting, retained
+   local drill-down data, and adversarial diagnostic-fidelity fixtures.
+3. No command runner ships without no-shell argv execution, repository binding,
+   sanitized environment, process-tree/resource/output containment, audit, and
+   supported-platform evidence.
+4. ROI telemetry is local and opt-in, uses a real tokenizer, separates measured
+   and modeled baselines, and excludes source, raw output, command text,
+   usernames, and absolute paths by default.
+5. Update availability is non-blocking and privacy-preserving. Mutation requires
+   expiring threshold-signed metadata, rollback/freeze/mix-and-match defenses,
+   digest/length/provenance checks, quarantine, health validation, atomic
+   activation, and rollback.
+6. A compromised npm, Homebrew, Artifactory, GitHub SaaS, or GHES account alone
+   cannot authorize installation.
+7. The terminal scorecard links every cell to source, executable tests,
+   benchmark output, and a limitation. Broad superiority language remains
+   prohibited until C66 and C67 close.
+
+### C59 — Source-evidenced failure-to-code diagnosis
+
+- Status: implemented
+- Priority: P1
+- DependsOn: C57
+- Evidence:
+  `src/failure-diagnosis.ts`,
+  `src/__tests__/unit/failure-diagnosis.spec.ts`,
+  `src/__tests__/unit/output-compression-cli.spec.ts`,
+  `src/__tests__/unit/knodin-tools.spec.ts`, and
+  `docs/COMMAND-OUTPUT-COMPRESSION.md`
+
+The retained compression artifact can be diagnosed through
+`knodin compress diagnose <artifact-id>` or
+`operation: "compress", compressionAction: "diagnose"` without rerunning the
+failed command or adding a second MCP tool. Direct already-produced text is
+also accepted behind the same input, redaction, and byte limits.
+
+The resolver extracts common JavaScript/TypeScript, Python, Java, C#, Go, and
+Rust source locations; binds exact or unique-suffix paths to tracked files;
+refuses traversal, external symlinks, untracked paths, and ambiguous basenames;
+and returns source-evidenced owning symbols, stable identities, nearest package
+manifests, tests, upstream callers, downstream dependencies, recent changes,
+bounded snippets, and indexed/current commit freshness.
+
+The aggregate source-context byte budget is hard. Incomplete input, exhausted
+context, unresolved locations, or non-current graph state makes the result
+`partial` rather than complete. Static relationships remain diagnostic
+candidates rather than runtime-causality proof; source maps, generated paths,
+dynamic dispatch, and framework wiring are recorded limitations.
+
+### C60 — Cross-client and GHES onboarding
+
+- Status: parked-external-evidence — 2026-08-02
+- Previous status: active — the legacy GHES source and versioned 0.3.0 release path are
+  live; local fail-closed mirror preparation is complete, while enterprise
+  governance/workload identity, timed independent cross-platform onboarding,
+  and Linux/Windows named-client certification remain external gates
+- Priority: P1
+- DependsOn: C52, C55
+- Evidence: `docs/PT-ACCESS-RECOMMENDATION.md`, `docs/INSTALLATION.md`,
+	`docs/evidence/pt-ghes-onboarding-2026-07-31.md`,
+	`docs/evidence/c60-macos-codex-native-2026-08-02.json`,
+	`docs/evidence/c60-macos-native-rss-fix-2026-08-02.json`,
+  `schemas/c60-named-client-evidence-v2.schema.json`,
+  `scripts/c60-native-certify.ts`, `scripts/c60-native-platform.ts`,
+  `scripts/c60-macos-codex-certify.ts`,
+  `src/__tests__/unit/c60-native-platform.spec.ts`,
+  `src/__tests__/unit/agent-integration.spec.ts`,
+  `src/__tests__/unit/doctor.spec.ts`, `scripts/pack-install-smoke.ts`,
+  `config/enterprise-mirror-policy.json`, and
+  `docs/evidence/c60-autonomous-preparation-2026-08-02.md`
+
+The `Enterprise-Apps/knodin` GHES repository is the DTS / Application Engineering
+read-only downstream mirror of the authoritative GitHub SaaS repository
+`DTS-Productivity-Engineering/knodin`. P&T engineers without GitHub SaaS
+access can download an exact versioned tarball from its
+release page, verify the recorded SHA-256, install with lifecycle scripts
+disabled, initialize an existing checkout, and diagnose the single MCP gateway.
+The observed 0.3.0 GHES asset is byte-identical to the retained CI artifact and
+public npm artifact. Docusign Artifactory currently stores the same bytes as a raw
+artifact, not npm registry metadata; the docs do not misrepresent that endpoint
+as an npm registry.
+
+Named Claude, Codex, Gemini, and Antigravity configuration plus a real generic
+MCP handshake are executable tests. The immutable schema-v2 macOS arm64
+Codex-configuration plus generic-MCP record certifies the exact 0.6.0 tarball in
+13.739 seconds using pre-populated offline npm/model caches: lifecycle-disabled
+install, existing-checkout init, project-local configuration without user-home
+mutation, bounded MCP initialize/list/status/query/doctor, and aggregate
+RSS/output evidence all pass.
+An isolated offline build and npm pack from the recorded source commit is
+byte-identical to the consumed tarball, with its prerequisite commands
+separately bounded and recorded. It does not prove cold-cache installation, an
+actual Codex process or active UI
+session, or the eventual distributed release artifact. Linux packed consumption
+remains release-gated. A first real Linux attempt falsified the original
+portability claim because zero-RSS kernel rows made RSS parsing fail before the
+first command completed; Windows PID 0 had the same defect. The fixed parser
+retains structural and integer validation, filters non-process/zero-resident
+rows, and rejects an all-filtered snapshot. A new provenance-bound macOS replay
+of the exact fix commit passed in 11.212 seconds with byte-identical package
+evidence, proving no macOS regression but not Linux/Windows readiness. The
+native Linux and Windows runs must restart from the fixed commit without source
+changes. GHES `main` is not protected, GHES releases are not
+immutable, and native Linux/Windows named-client runs, independent cross-platform review,
+and non-personal automated mirror synchronization are missing, so C60 remains
+active and no cross-platform-complete or universal two-minute claim is allowed.
+
+### C61 — Private real-token ROI telemetry and dashboard
+
+- Status: implemented
+- Priority: P1
+- DependsOn: C16, C55
+- Evidence: `src/output-telemetry.ts`, `src/cli-model.ts`, `bin/cli.ts`,
+  `src/tools/knodin-tools.ts`, `src/__tests__/unit/output-telemetry.spec.ts`,
+  `src/__tests__/unit/output-telemetry-cli.spec.ts`,
+  `src/__tests__/unit/knodin-tools.spec.ts`, and `docs/TELEMETRY.md`
+
+Persistence remains disabled by default and local. Opt-in JSONL records use the
+pinned real tokenizer, executed full-file baselines only when bounded source is
+available, explicit unknowns otherwise, cold/warm and outcome dimensions,
+agent-round-trip, latency, RSS, freshness, compression-fidelity, indexing-time,
+and index-storage measurements. Repository grouping uses a one-way identifier;
+source, raw output, command text, usernames, and absolute paths are excluded.
+
+The CLI and single MCP gateway expose status, static HTML report, sanitized JSON
+export, retention, and explicit clear operations. Inputs and outputs are
+repository-contained and symlink-refusing, persistence is atomic/private, and
+the self-contained dashboard reports summary, operation, time-series, private
+repository, latency p50/p95, indexing cost, freshness, and fidelity dimensions
+with light/dark rendering. Metrics with no defensible observation remain
+unavailable rather than modeled.
+
+### C62 — Signed update metadata trust
+
+- Status: parked-external-evidence — 2026-08-02
+- Previous status: active — verification core and fail-closed local ceremony preparation
+  implemented; production offline custodians, independent pin review, recovery
+  evidence, and trust-pin activation remain external gates
+- Priority: P0
+- DependsOn: C55
+- Evidence: `src/update-trust.ts`,
+	`src/__tests__/unit/update-trust.spec.ts`, `src/update-ceremony.ts`,
+	`src/__tests__/unit/update-ceremony.spec.ts`,
+	`scripts/root-ceremony-preflight.ts`,
+	`schemas/root-ceremony-manifest-v1.schema.json`,
+	`schemas/root-pin-review-receipt-v1.schema.json`,
+	`docs/ROOT-CEREMONY-RUNBOOK.md`, and `docs/SIGNED-UPDATES.md`
+
+The pure verifier implements deterministic signed payloads, content-addressed
+Ed25519 keys, disjoint root/targets/snapshot/timestamp roles, production
+thresholds for root and targets, bounded expiry, independent root pinning,
+dual-threshold one-step root rotation, version-and-digest rollback/equivocation
+state, timestamp→snapshot→targets length/hash/version binding, safe target
+paths, and signed artifact SHA-256/length verification. It performs no network
+or installation mutation.
+
+Adversarial fixtures reject missing thresholds, field and artifact
+substitution, expired timestamp freezes, rollback, same-version equivocation,
+mix-and-match metadata, role-key reuse, root-pin substitution, future metadata,
+and rotations not signed by the old root threshold.
+
+C62 is not closed merely because the verification code exists. No production
+private key is checked in or generated by tests. Release owners must complete
+the offline multi-custodian root ceremony, independently review and embed the
+initial root digest, and record rotation/recovery evidence. C63 now makes all
+doctor, CLI, and MCP update state consume only verified metadata; the former
+npm lookup has been removed. Production authorization still waits for the
+offline ceremony.
+
+### C63 — Signed-only update client and safe policy
+
+- Status: parked-external-evidence — 2026-08-02
+- Previous status: active — implementation and adversarial unit/CLI evidence complete;
+  closure requires a recorded fail-closed deferred-activation policy after C62
+- Priority: P0
+- DependsOn: C62
+- Evidence: `src/update-policy.ts`,
+  `src/__tests__/unit/update-policy.spec.ts`,
+  `src/__tests__/unit/update-policy-cli.spec.ts`,
+  `docs/DOCTOR-AND-UPDATES.md`, and `docs/SIGNED-UPDATES.md`
+
+The five `knodin update` actions work outside a repository. Periodic checks use
+an atomic background lease and never put network latency on ordinary commands.
+Fixed signed metadata paths are HTTPS-origin/path bound, redirect-free, capped,
+timed, privacy-preserving, and optionally byte-identical across mirrors.
+Verified state is atomic/private and retains monotonic evidence across failed
+checks.
+
+Apply enforces notify/download/patch/minor policy, minimum age, channels,
+enterprise mirrors, maintenance windows, exact artifact length/digest, signed
+provenance digest, candidate/rollback quarantine, no-shell exact local npm
+artifact invocation, symlink-safe exclusive quarantine, signed-version path
+validation, allowlisted enterprise cross-check origins, health validation,
+health-verified automatic rollback, and offline re-verification for explicit
+rollback. Mutable registry tags are never used.
+
+The production CLI remains fail-closed as `trust-unconfigured`: a root and its
+pin from one mutable user file are not accepted. No certified sandbox smoke
+adapter or Homebrew/Node-manager rollback adapter is enabled yet. C62's offline
+ceremony must embed the independent anchor. C63 closes by recording that
+automatic production activation remains disabled; it does not wait for C65.
+C65 then uses the terminal signed-only client to certify the smoke sandbox,
+multi-step rotation/recovery, compromised channels, and manager-specific
+activation before any later auto-apply enablement. This ordering removes a
+C63↔C65 closure cycle without weakening the fail-closed policy.
+
+### C64 — Provenance, SBOM, and cross-channel release attestation
+
+- Status: parked-external-evidence — 2026-08-02
+- Previous status: active — implementation and adversarial fixtures complete; a live
+  five-channel release attestation remains a C67 publication gate
+- Priority: P0
+- DependsOn: C62
+- Evidence: `src/release-attestation.ts`,
+  `src/__tests__/unit/release-attestation.spec.ts`,
+  `src/__tests__/unit/release-attestation-cli.spec.ts`,
+  `src/__tests__/unit/release-workflow.spec.ts`,
+  `src/__tests__/unit/release-candidate-workflow.spec.ts`,
+  `scripts/release-attestation.ts`, `.github/workflows/publish.yml`,
+  `.github/workflows/release-candidate.yml`, and `docs/RELEASING.md`
+
+The release workflow installs dependencies with lifecycle scripts disabled,
+runs tests, and packs the artifact in an unprivileged job with read-only
+repository access. A separate job with OIDC and attestation authority downloads
+only the retained artifact, generates a production-dependency CycloneDX SBOM,
+and uses full-commit-pinned official GitHub actions to sign SLSA build provenance
+and the SBOM. It independently verifies both retained bundles against the exact
+artifact, source digest, tag ref, repository, workflow certificate identity,
+and GitHub OIDC issuer before npm publication. A manual retry must run at the
+tag ref; checked-out commit, workflow SHA, tag, and package version disagreement
+is a hard failure. The exact tarball, signed evidence, and verification receipts
+are retained for 90 days before that tarball is passed to npm and Artifactory.
+
+The separate manual-only release-candidate workflow now structurally stops
+after the exact artifact and rollback bytes, provenance and SBOM bundles,
+verification and identity receipts, bounded input manifest, and incomplete
+five-channel attestation draft are retained for 90 days. Its build job is
+unprivileged and lifecycle-disabled; its OIDC job downloads the retained input
+set without a source checkout or dependency install and has no npm/JFrog/channel
+credential, publishing command, reusable publisher, or distribution mutation.
+This is local implementation evidence only: C64 remains active until a live OIDC
+run at an immutable tag produces the retained candidate bundle and independent
+verification. C67 alone authorizes distribution after that candidate is
+independently verified.
+
+The canonical schema derives, rather than accepts, `verified`, `incomplete`, or
+`quarantined` status. It records the exact artifact SHA-256/SHA-512/npm
+integrity, source commit, build identity, provenance and SBOM digests,
+publication timestamps and locations, all five approved destinations, and an
+exact rollback target whose digest the CLI derives from downloaded bytes rather
+than accepting from the manifest. Missing evidence is incomplete; any artifact, version,
+or source disagreement is quarantined. The CLI binds inputs beneath one
+directory, refuses direct or nested symlinks/traversal/unbounded files/output replacement,
+writes visible failure evidence, and exits nonzero for an incomplete final or
+any mismatch. It ignores a manifest's claimed verification state and invokes
+an explicitly approved absolute `gh attestation verify` executable without a
+shell or inherited credentials/environment against both local bundles and the
+exact artifact/source/ref/workflow/certificate policy before deriving verified
+signature evidence.
+
+Signed targets may bind the provenance, SBOM, SBOM-attestation, and release-
+attestation digests. Update quarantine and explicit rollback re-fetch or re-read
+all four objects, validate their exact bytes and attested channel state, and
+refuse missing or inconsistent evidence before a package manager is invoked.
+Apply cross-checks the candidate's attested rollback version, path, and digest
+against the separately quarantined rollback artifact.
+
+C64 is not a claim that the current 0.3.0 channels have been retroactively
+attested. GitHub/Sigstore build signatures are independently useful evidence,
+but do not replace C62's offline-controlled threshold root. C64 closes when the
+exact release-candidate artifact has verified provenance and SBOM bundles plus
+a complete attestation draft containing the five intended destinations. The
+draft remains `incomplete` until distribution. C67 publishes those exact bytes,
+fills the destination receipts, derives the final `verified` record, and
+TUF-authorizes it. This split prevents C64 and C67 from depending on each
+other's terminal evidence.
+
+The signature proves workflow identity and exact bytes, not that a compromised
+self-hosted runner built those bytes faithfully. Independent build reproduction
+and runner-compromise drills remain C65/C67 gates. The JFrog reusable workflow's
+`@master` reference also remains an explicit external constraint because its
+Vault OIDC policy rejects commit-pinned `job_workflow_ref` claims; this is not
+misreported as full workflow immutability.
+
+### C65 — Compromised-channel, rollback, freeze, and recovery defenses
+
+- Status: parked-external-evidence — 2026-08-02
+- Previous status: active — bounded multi-step root recovery is implemented; production
+  key ceremony, smoke sandbox, manager-specific activation, and live drills
+  remain required
+- Priority: P0
+- DependsOn: C63, C64
+- Evidence: `src/update-trust.ts`, `src/update-policy.ts`,
+  `src/__tests__/unit/update-trust.spec.ts`,
+  `src/__tests__/unit/update-policy.spec.ts`, `docs/SIGNED-UPDATES.md`, and
+  `docs/evidence/0.4.3-update-defense-drill.json`
+
+The update client can recover from up to 32 missed root rotations per check by
+fetching every numbered intermediate root, cross-checking its exact bytes across
+configured mirrors, and verifying each version under both the previous and new
+root thresholds. It never accepts a direct version jump or promotes a root from
+mutable state. Missing, malformed, wrong-version, skipped, or mirror-divergent
+intermediates fail before new trust is persisted; the rotation bound prevents a
+malicious terminal version from causing unbounded requests.
+
+This closes the implemented multi-step retrieval gap only. C65 still requires
+the offline multi-custodian production root/recovery rehearsal, certified smoke
+sandbox, npm/Homebrew/manager activation and rollback drills, compromised
+transport and runner exercises, and checked-in evidence from those executions.
+No automatic production activation or complete supply-chain claim is allowed
+until those gates and C67's live release are complete.
+
+The checked-in 0.4.3 isolated drill records one combined execution of 52 trust,
+policy, CLI, and attestation scenarios, including compromised-fixture refusal,
+multi-step recovery, automatic rollback, and unhealthy-rollback refusal. It
+strengthens repeatable local evidence but deliberately leaves the production
+ceremony, certified adapters/sandbox, real manager mutation, and live
+transport/runner exercises open.
+
+### C66 — Evidence-linked Token Optimizer scorecard
+
+- Status: parked-external-evidence — 2026-08-02
+- Previous status: active — scorecard published; terminal prerelease snapshot awaits
+  active dependencies
+- Priority: P0
+- DependsOn: C56, C57, C59, C60, C61, C65, C68, C75
+- Evidence: `docs/TOKEN-OPTIMIZER-SCORECARD.md`,
+  `benchmarks/evaluations/token-optimizer-20260730/scorecard.json`,
+  `src/__tests__/unit/docs-integrity.spec.ts`, and the pinned audit/replay
+  artifacts under `benchmarks/evaluations/token-optimizer-20260730/`
+
+The human scorecard and machine manifest classify every advertised competitor
+workflow plus the cross-cutting product dimensions. Every row links checked-in
+implementation, verification source/test paths, benchmark or live evidence,
+scope, readiness, and a material limitation. The manifest pins the competitor,
+the raw replay digest, its declared base revision, every evaluated source hash,
+and the first merged knodin commit containing that exact composite. Its integrity test
+rejects dimension omissions/duplicates, revision or replay-digest drift,
+missing evidence paths, or empty scope/limitation fields.
+
+The scorecard supports a qualified “more complete local code-intelligence
+system” statement. It explicitly prohibits “better across all dimensions”:
+command execution remains intentionally excluded, Windows/timed onboarding is
+not certified, cold startup is slower, and production trust ceremony, drills,
+and five-channel release evidence remain open. C66 publication does not close
+its active dependencies or C67. C66 becomes terminal when every listed
+dependency is terminal and the scorecard records the prerelease truth. C67
+appends the final release record and receipts as a non-gating amendment; C66
+does not depend on the release it gates.
+
+### C67 — Certify and distribute the completed competitive release
+
+- Status: parked-external-evidence — 2026-08-02
+- Previous status: proposed
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C60, C62, C63, C64, C65, C66, C75
+- Owner roles: release owner, offline-root custodians meeting the recorded
+  threshold, security reviewer, five channel operators, and Windows/macOS/Linux
+  certifiers
+- Evidence directory: `docs/evidence/releases/<version>/` with immutable raw
+  receipts under `benchmarks/evaluations/releases/<version>/`
+- Preflight implementation: `src/release-preflight.ts`,
+  `scripts/release-preflight.ts`, `schemas/release-plan-v1.schema.json`,
+  `src/__tests__/unit/release-preflight.spec.ts`, and `docs/RELEASING.md`
+
+C67 is the terminal release and roadmap gate. It certifies one exact version
+from one source commit and distributes one byte-identical package through all
+approved channels without relaxing any unresolved limitation.
+
+The pure C67 preflight is implemented without release authority. It validates
+a bounded plan, exact clean annotated-tag identity, the terminal roadmap and
+ledger state of every dependency, tracked repository-contained nonsymlink
+evidence including an immutable terminal artifact per dependency, certified
+native targets, exact verification commands, an independently reviewed
+production root/ceremony/digest tuple, and a new version-bound evidence path. It performs no publishing,
+tagging, evidence-directory creation, credential access, or other external
+mutation and does not change C64's nonpublishing candidate workflow. C67 remains
+proposed and open: against the current authoritative ledger the preflight must
+fail until C60, C62, C63, C64, C65, and C66 close; a passing local unit suite is
+not a release authorization or distribution receipt.
+
+Acceptance and execution contract:
+
+1. Preflight fails unless C60, C62, C63, C64, C65, C66, and C75 have terminal
+   statuses and checked-in evidence. Record package version, tag, source commit,
+   workflow commit, runtimes, target platforms, trust-root digest, and exact
+   verification commands before mutation.
+2. From a clean tag checkout, run `npm ci --ignore-scripts`, `npm run lint`,
+   `npm run typecheck`, `npm run build`, `npm run test`,
+   `npm run test:pack-install`, `npm run check:roadmap`, and the release-specific
+   competitive, trust, defense, and attestation replays. Record exit status,
+   elapsed time, peak RSS, and immutable artifact digests without overwriting an
+   earlier run.
+3. Build once in the unprivileged release job. Verify the retained package,
+   provenance, SBOM, SBOM attestation, and release-attestation draft before any
+   channel receives the artifact. A retry must use the same tag and bytes.
+4. Publish SHA-256/length-identical bytes to npm, Homebrew, Artifactory, GitHub
+   SaaS, and GHES. Record immutable channel identifiers, timestamps, downloaded
+   digests, and independently fetched receipts. Any missing or divergent channel
+   fails the release and triggers quarantine/recovery rather than success.
+5. Produce threshold-signed targets/snapshot/timestamp metadata bound to the
+   artifact and C64 evidence digests. Exercise update status, check, explain,
+   apply, health validation, and rollback from clean supported consumers.
+6. Re-run named-client onboarding on certified macOS, Linux, and Windows and
+   record C60's two-minute measurement. Verify `knodin init`, lifecycle refresh,
+   CLI query, and the single MCP gateway against an existing checkout.
+7. Publish a release record listing every gate, receipt, degradation,
+   unsupported case, rollback target, and authorized product claim. Append those
+   receipts to C66's already-terminal prerelease scorecard without reopening its
+   gate; preserve every limitation whose independent gate did not pass.
+8. Mark C67 terminal and remove its ledger row in the same change, then require
+   a fresh `npm run check:roadmap -- --complete` to succeed. If authority or
+   infrastructure is unavailable, retain `blocked` with the exact missing
+   authority and safe next action; never fabricate a receipt.
+
+### C68 — Close structural output and latency gaps
+
+- Status: implemented
+- Priority: P0
+- DependsOn: C56
+- Evidence: the initial C56 replay identified compactness and warm-latency gaps;
+  the final pinned replay proves the C68 compact mode passes its narrow shared
+  oracles and beats competitor response tokens and warm p50/p95 for all five
+  structural operations on the small fixture. Cold startup remains slower.
+
+Acceptance:
+
+1. Add a purpose-built compact structural response mode that preserves stable
+   identity, source location, ambiguity, freshness, and truthful budgets without
+   returning unrelated graph fields or telemetry envelopes.
+2. Measure gateway schema overhead separately from per-call output.
+3. Avoid repeated freshness/index startup work inside one session and document
+   the irreducible cold cost of a persistent graph separately from operation
+   latency.
+4. Re-run the exact C56 fixture. knodin must match or beat competitor response
+   tokens for all five structural workflows and must not be slower in warm
+   operation p50/p95 without an explicitly approved, evidence-backed tradeoff.
+5. Correctness, ambiguity, and stale-index oracles must remain passing; size or
+   latency cannot be improved by weakening evidence.
+
+Implementation evidence: `detailLevel: "compact"` now selects a purpose-built
+compact structural contract for file summary, exact source, structural search,
+batch outline, and project overview. Stable `~` identity prefixes are accepted
+as ambiguity-safe selectors, returned/total counts remain explicit, and no
+generic telemetry or response-budget envelope is added. Generation-scoped
+structural caching plus a watcher-invalidated freshness lease removes repeated
+session work; a no-subprocess HEAD check prevents Git movement from reusing the
+lease. The pinned C56 replay records gateway schema cost separately and passes
+all five correctness, token, warm-p50, and warm-p95 gates. Cold-process cost
+remains explicitly reported as a persistent-graph tradeoff.
+
+### C69–C75 — Large-portfolio lifecycle hardening
+
+- Status: certified with recorded degradations
+- Priority: P0/P1 as listed above
+- Source objective:
+  `knodin-Portfolio-Integration-Issues-2026-07-30.md` and the tested candidate
+  commit `c981480db89ffbbb646206a73660e9ab842686ba`
+- Scope: portfolio discovery, selection, initialization, lifecycle truth,
+  diagnostics, and Salesforce metadata candidate quality.
+- C75 Evidence: `docs/evidence/portfolio-initialization-2026-07-31.md`
+
+The candidate commit proves that a 256 MiB subprocess buffer, early selection,
+and sequential inventory can discover the current 61-repository portfolio, but
+that commit is evidence rather than the terminal design. It still materializes
+SalesforceCI's roughly 105 MB `git ls-files` response and portfolio dry-run
+peaked near the one-GB incremental-memory ceiling.
+
+Acceptance:
+
+1. Inventory tracked files with a streaming or equivalently bounded design.
+   SalesforceCI's 904,072 tracked files cannot abort the portfolio. A large,
+   malformed, timed-out, or otherwise failed repository produces a
+   machine-readable degraded record while other repositories continue.
+2. Apply include/exclude selection before tracked-file inventory. An include
+   selector that matches no discovered repository returns an explicit
+   diagnostic rather than a successful empty result.
+3. `repos discover ~/code --json` returns valid JSON for all 61 current
+   repositories while remaining below one GB of incremental RSS. Selected
+   searches do not inventory excluded repositories.
+4. Make portfolio init and dry-run sequential, resource-releasing, resumable,
+   and bounded. Dry-run performs no model or database work, estimates scale and
+   memory risk, and reports init/update/repair actions accurately. A
+   per-process memory ceiling degrades and continues rather than killing the
+   portfolio run.
+5. `knodin configure` is either clearly configuration-only or atomically
+   produces a usable graph and hooks. `knodin init` drains compatible queued
+   lifecycle events after graph health is established; incompatible events
+   receive an exact remediation. A `knodin wait --fresh` deadline must not
+   terminate a healthy lifecycle processor; dead or failed attempts are
+   retried at a bounded interval. Immediate status and search must agree with
+   the success message.
+6. Running `knodin doctor` on a non-Git portfolio parent warns and directs the
+   user to portfolio diagnostics. MCP diagnostics separately report on-disk
+   configuration, subprocess handshake, active-client exposure being unknown,
+   reload requirements, and the exact configuration path.
+7. Architecture and roadmap candidates use basename/directory-aware evidence,
+   bounded lists, reasons, and confidence. Salesforce object or metadata names
+   containing words such as `Design`, `WizardDesign`, or `Backlog` are not
+   promoted without qualifying path/content evidence.
+8. Certification records the 61-repository result, peak RSS, elapsed time,
+   degraded repositories, selector behavior, immediate queryability, and all
+   regression/typecheck/build/package-install gates. C66 and C67 cannot make a
+   portfolio-readiness claim until C75 closes.
+
+C72 lifecycle evidence is recorded in
+`docs/evidence/lifecycle-event-drain-2026-07-31.md`. Generated events now bind
+to the actual worktree root and status separately exposes a pending event and
+`idle`, `running`, or `stale-lock` processor state. The checked-in wait path
+retries a stranded compatible processor. The evidence explicitly does not
+claim that the installed 0.3.0 Homebrew release contains those source changes;
+distribution remains a C67 gate.
+
+C71 is implemented by `src/repository-init-process.ts` and the sequential
+orchestration in `src/repository-management.ts`. Every live repository runs in
+a disposable process with a 768 MiB RSS ceiling, independent parent-side RSS
+polling plus worker heartbeats, process-group termination on macOS/Linux,
+timeout escalation, repository-scoped degradation, aggregate resource evidence,
+and resumable manifests. `src/__tests__/unit/repository-init-process.spec.ts`
+and `src/__tests__/unit/repository-management.spec.ts` prove termination,
+continuation, and single-worker sequencing. That implementation evidence is
+separate from the following live C75 certification.
+
+C75 live evidence is recorded in
+`docs/evidence/portfolio-initialization-2026-07-31.md`. The 69-record run stayed
+below one GiB, completed 48 selected repositories, degraded 16 workers at the
+memory ceiling, preserved tracked team integration in four repositories, and
+continued after every failure. C75 therefore certifies bounded portfolio
+behavior with named limitations; it does not claim that all repositories are
+healthy or initialized.
+
+### C76 — Responsive declarative CLI model
+
+- Status: implemented
+- Priority: P1
+- DependsOn: C73
+- Evidence: PR #29 replaced the hand-authored parser/help template with the
+  declarative Commander model and pseudo-terminal width acceptance coverage.
+
+Acceptance:
+
+1. Immediately reflow help to the detected TTY width with deterministic
+   non-TTY output and narrow/wide pseudo-terminal tests.
+2. Migrate parsing, validation, global options, nested subcommands, and help to
+   one declarative command model so documentation cannot drift from accepted
+   arguments.
+3. Preserve every checked-in legacy invocation and JSON stdout contract.
+4. Prefer Commander unless an executable bakeoff disproves the choice:
+   current Commander supplies width-aware help, nested commands, TypeScript
+   support, a documented security policy, and zero runtime dependencies.
+5. Pin the exact dependency and integrity through the normal lockfiles and
+   release provenance. Do not adopt a broader dependency tree solely for
+   cosmetic terminal rendering.
+
+Implementation evidence: `src/cli-model.ts` is the single Commander-backed
+grammar for global options, root and nested commands, positional contracts,
+numeric parsing, unknown-option rejection, and root or command help.
+`bin/cli.ts` validates every non-help invocation through that model and reads
+shared option values from its parsed result before compatibility dispatch.
+Commander 15.0.0 is exact-pinned in both lockfiles and has no transitive runtime
+dependencies. `src/__tests__/unit/cli-model.spec.ts`,
+`src/__tests__/unit/cli-pty-help.spec.ts`, the existing CLI subprocess suite,
+and `docs/CLI.md` cover narrow/wide deterministic output, a real Unix
+pseudo-terminal when available, nested help, invalid syntax, legacy invocation
+compatibility, packaging, and the Windows-safe non-PTY path.
+
+### C77 — Replay CodeFlow edge-provenance and architecture-export claims
+
+- Status: evaluated — retained knodin unchanged
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C24, C27, C42
+- Motivation: CodeFlow is a browser-local, MIT architecture mapper with broad
+  language coverage, blast-radius views, and raw JSON export. A secondary
+  LinkedIn post says each dependency identifies its extraction mechanism, but
+  that claim was not found in the current repository or README. Knodin already
+  exposes provenance, confidence, exact-versus-heuristic labels, source evidence,
+  and source lines; only a shared replay can establish whether CodeFlow presents
+  uncertain edges or architecture exports more usefully.
+- In scope: add a pinned CodeFlow adapter or documented browser-local protocol;
+  compare dependency precision/recall, unsupported edges, uncertainty labels,
+  source evidence, blast-radius completeness, export fidelity, output size,
+  latency, and peak RSS on the existing architecture fixtures.
+- Out of scope: adopting CodeFlow, copying its browser UI, adding a new service,
+  or changing Knodin's extraction architecture solely from vendor or social-post
+  claims.
+- Touches: `benchmarks/competitors/TRACKER.md`, a CodeFlow comparison report and
+  immutable raw result, the shared competitive harness only if its existing
+  adapter contract is insufficient, and this roadmap.
+- Collision risk: competitor tracker and shared harness mappings; schedule apart
+  from other competitive-replay edits.
+- Source: https://github.com/braedonsaunders/codeflow
+- Source task: `6h8V3JGJMhV3m63h`
+- Evidence: `benchmarks/competitors/codeflow-vs-knodin.raw.json` records the
+  exact commit and MIT license, local-only protocol, original/normalized edges,
+  false-positive/false-negative sets, provenance coverage, export fidelity,
+  response bytes, 3+20 warm and five-process cold samples, and independently
+  measured RSS. Both products achieved precision/recall 1.0, unsupported-edge
+  rate 0, and blast completeness 1.0. CodeFlow used 105,955,328 bytes peak RSS
+  and had 122.788/186.788 ms cold p50/p95; knodin used 591,446,016 bytes and had
+  1,056.246/6,332.857 ms. Knodin warm p50/p95 was 0.532/0.736 ms versus
+  CodeFlow's 3.101/8.202 ms. CodeFlow supplied none of the six evaluated
+  file-relationship provenance categories; knodin supplied all six for all
+  three edges. Architecture block exports remain explicitly incomparable.
+- Disposition: retain knodin unchanged. CodeFlow demonstrates a real cold-start
+  and memory advantage, while knodin already supplies the evaluated provenance
+  and warm-query behavior. Neither the incomparable architecture exports nor
+  feature presence authorizes an architecture or presentation change, and this
+  evaluation makes no aggregate superiority claim.
+
+Acceptance:
+
+1. Pin the tested CodeFlow commit and record its MIT license, local execution
+   path, setup, and limitations; do not require an account, hosted service,
+   paid API, source egress, or new Knodin runtime dependency.
+2. Run both products against identical checked-in fixtures and correctness
+   oracles. Preserve false positives, false negatives, unresolved edges, and
+   unavailable cases in immutable raw results.
+3. For every exported relationship, record whether the tool supplies relation
+   kind, extractor identity, exact/heuristic confidence, source file and line,
+   and bounded source evidence. Treat the LinkedIn extractor-identity claim as
+   unverified unless the pinned implementation emits it.
+4. Report precision/recall, unsupported-edge rate, blast-radius completeness,
+   export fidelity, response bytes, cold/warm p50 and p95, and independently
+   measured peak RSS. Do not publish a win from incomparable or oracle-free rows.
+5. Keep incremental spend at zero and incremental memory below 1 GB. Keep all
+   fixture source local; if CodeFlow cannot run without GitHub egress, record a
+   blocker rather than uploading private source.
+6. Close with one evidence-based disposition: retain Knodin unchanged, improve
+   provenance presentation/export, or propose a separately reviewed roadmap
+   item. Do not infer an architecture change from feature presence alone.
+
+### C78 — Add bounded source-to-sink resource reachability
+
+- Status: evaluated — retained C8 unchanged
+- Priority: P1
+- Disposition: Evaluate
+- DependsOn: C2, C3, C8, C24
+- Motivation: Code-Graph-RAG's opt-in `READS_FROM`, `WRITES_TO`, and `FLOWS_TO`
+  edges answer a useful provenance question Knodin cannot currently answer:
+  whether a value from an environment variable, file, database, socket, or
+  network source can reach a log, file, database, or outbound-network sink.
+  Knodin's C8 `flow_analysis` is deliberately limited to bounded, on-demand
+  TS/JS facts inside one selected symbol; call-argument evidence is explicitly
+  heuristic and does not compose source-to-sink resource reachability.
+- In scope: prototype synthetic resource identities plus source-evidenced read,
+  write, assignment, argument, return, and kill facts; begin with environment or
+  local configuration flowing to logging, network, and database sinks; expose a
+  bounded query with exact coverage and omission metadata.
+- Out of scope: adopting Code-Graph-RAG, Memgraph, Qdrant, Docker, a hosted
+  model, unrestricted graph queries, autonomous vulnerability verdicts, a full
+  persisted PDG, SSA, alias-complete or path-sensitive analysis, or claims of
+  runtime reachability.
+- Touches if approved: language extraction, optional persisted resource/flow
+  schema or a cheaper on-demand representation, one compact query pattern,
+  source/sink registry, documentation, and labeled multi-language fixtures.
+- Collision risk: `src/engine/index.ts`, graph schema/migrations, MCP/CLI query
+  enums, and shared language extractors; schedule apart from other graph-schema
+  or query-surface work.
+- Source: https://github.com/vitali87/code-graph-rag/blob/d0b257b402bb25b54cf8f1dee0af3a71623c8d9e/docs/architecture/data-flow-edges.md
+- Source task: `6hC5Cv934v8xj2Gh`
+- Evidence: `benchmarks/evaluations/c78-resource-reachability/` contains the
+  labeled TS/JS oracle, disposable prototype, immutable raw result, tests, and
+  methodology. It achieved 100% precision but 62.5% recall, missing argument,
+  return, and recursion/cycle handoff. Three local repositories measured
+  bounded on-demand analysis against temporary-file persisted JSON; peak RSS was
+  129,859,584 bytes with zero spend and no egress.
+- Disposition: retain C8's bounded statement flow and call-argument evidence
+  unchanged. The precision gate passed, but recall failed the 80% minimum useful
+  threshold, so neither persistence nor a production query is authorized and no
+  separately numbered implementation item is proposed.
+
+Acceptance:
+
+1. First build a disposable prototype and labeled oracle containing true flows,
+   clean overwrites, shadowing, unrelated source/sink co-occurrence, dynamic
+   resource names, argument handoff, return handoff, recursion/cycles, and
+   deliberately unsupported constructs. Do not change the production schema
+   until the prototype passes the gate.
+2. Require at least 95% precision and report recall per supported language and
+   source/sink class. False positives are a hard failure because the result may
+   inform security review; unsupported or ambiguous paths must remain explicit.
+3. Every result identifies the source and sink, relation kind, bounded path,
+   source file and line evidence, extraction provenance, confidence, supported
+   language/registry coverage, omissions, truncation, and freshness. Label every
+   path static and heuristic; never call it proof of exploitability, secrecy, or
+   runtime reachability.
+4. Compare a bounded on-demand implementation with persisted resource/flow
+   edges. Choose the smallest design meeting correctness and warm-latency goals;
+   preserve stable identity, ambiguity safety, monotonic bounds, deterministic
+   ordering, hard item/byte/token budgets, and fail-closed stale-index behavior.
+5. Measure clean and incremental index time, database growth, cold/warm p50 and
+   p95 query latency, response bytes, and peak RSS on at least three real local
+   repositories. Incremental spend remains zero and incremental memory remains
+   below 1 GB, with no hosted service, credentials, source egress, or required
+   production model.
+6. Start with a deliberately narrow language and source/sink matrix justified by
+   fixtures. Adding a registry entry requires positive and negative acceptance
+   cases; a language without a verified registry emits an explicit omission,
+   not inferred coverage.
+7. If the gate fails, retain C8's current bounded statement flow and call-
+   argument evidence unchanged. Do not broaden or persist the feature merely to
+   match a competitor's schema.
+
+### C79 — Bounded repository applicability signals
+
+- Status: implemented
+- Priority: P1
+- Disposition: Evaluate
+- DependsOn: C52, C69
+- Touches: `repos discover` CLI option/schema, bounded repository inspection,
+  Git-remote parsing, worktree-aware discovery fixtures, CLI help/reference, and
+  compatibility evidence. It does not change `doctor` or the MCP surface.
+- What: decide whether repository marker and configuration detection belongs in
+  knodin's repository-discovery charter. If it does, add an additive, opt-in
+  `knodin repos discover <roots...> --json --signals` facet so consumers can use
+  knodin's existing repository/worktree classification instead of duplicating a
+  second traversal and a less reliable definition of a repository.
+- Scope: without `--signals`, output must remain byte-identical. With the flag,
+  every repository gains `signals`, using `{}` for honest absence. Detection is
+  read-only, offline, credential-free, bounded by existing bytes/tokens/items
+  budgets, and limited to a documented allowlist of marker paths rather than a
+  tree glob. Never read potentially secret file contents; the only content-read
+  exception is allowlisted hook-manager configuration needed to report whether
+  it references `aidev-track`. Linked worktrees inspect their own checkout and
+  preserve existing skip/include behavior.
+- Evidence: either a checked-in charter decision closing the item unchanged, or
+  a checked-in implementation with compatibility bytes, help/docs, unit
+  fixtures, bounded-resource results, and verifier output.
+
+Charter decision (2026-08-03): accepted. These path-derived, repository-scoped
+signals belong in discovery because they reuse knodin's existing bounded
+repository and linked-worktree classification. The facet remains opt-in and
+descriptive: it does not decide whether an agent skill applies or whether a
+detected service is configured correctly.
+
+Acceptance:
+
+1. First record the charter decision. If marker/config policy is outside
+   knodin's charter, close C79 unchanged with checked-in rationale; no feature
+   implementation is required. Otherwise implement only the opt-in facet.
+2. A golden compatibility test proves `repos discover <roots...> --json`
+   remains byte-identical without the flag. With `--signals`, every repository
+   entry has a deterministic `signals` object, including `{}` when the
+   allowlisted inspection finds nothing; schema version changes only if the
+   existing compatibility policy requires it.
+3. When detected, the deterministic contract must return `hookManager`,
+   allowlisted `markerFiles` (including Sonar, CI/PR-workflow, agent, and MCP
+   client markers), sanitized `remotes` with name/host/owner, `ciProviders`,
+   `agentConfigs`, and `aidevTrackReferenced: true|false` when an allowlisted
+   hook-manager config is present. Detection performs
+   no writes, network access, credential access, source egress, or secret-file
+   content reads, except the narrow allowlisted hook-manager parse for the
+   `aidev-track` reference. Incremental spend is zero.
+4. Unit fixtures cover lefthook, husky, pre-commit, no hook manager,
+   `aidev-track` reference detection, multiple remotes, multiple remote hosts,
+   missing `.git`, every marker absent, and linked worktrees. Tests prove fixed
+   allowlists and existing bytes/tokens/items budgets bound inspection and
+   serialization.
+5. `knodin doctor` behavior is unchanged. The repos CLI reference and
+   `repos discover --help` document the flag, returned fields, allowlist,
+   omissions, privacy constraints, and worktree behavior.
+
+Implementation evidence: the deterministic verifier and bounded-resource
+result are checked in at
+[`docs/evidence/c79-repository-signals-2026-08-03.md`](../docs/evidence/c79-repository-signals-2026-08-03.md)
+and
+[`docs/evidence/c79-repository-signals-2026-08-03.json`](../docs/evidence/c79-repository-signals-2026-08-03.json).
+The unit acceptance fixtures are in
+`src/__tests__/unit/repository-management.spec.ts`; CLI help coverage is in
+`src/__tests__/unit/cli-model.spec.ts`, and the unchanged doctor regression is
+`src/__tests__/unit/doctor.spec.ts`.
+
+Known limitations and decision gate: marker presence describes repository
+configuration; it does not prove that a skill applies or that a service is
+configured correctly. If the charter review rejects this application-policy
+facet, closing C79 unchanged is a valid terminal outcome and downstream tools
+may inspect only the repository paths knodin returns.
+
+### C80 — Structural-first retrieval routing
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C3, C24, C42, C43
+- Touches: retrieval dispatch and telemetry, search/context tests, a checked-in
+  cross-file oracle, and deterministic ablation replay artifacts.
+- What: route stable identity and exact name/signature/path evidence through
+  lexical/FTS and bounded graph expansion before loading embeddings. Serialize
+  the selected route and `embeddingsUsed` so behavior is explainable.
+- Scope: preserve the one-tool gateway, stable identities, ambiguity safety,
+  freshness, deterministic ordering, and current hard response budgets.
+- Evidence: a local checked-in implementation, fixtures, raw three-arm replay,
+  verifier, and report covering factual precision/recall, unsupported claims,
+  latency, and independently measured peak RSS.
+
+Acceptance:
+
+1. Exact symbol, path, and source-evidenced cross-file questions do not load the
+   embedding model when structural evidence is sufficient; tests assert the
+   route and `embeddingsUsed: false` through CLI and MCP-compatible responses.
+2. A checked-in multi-hop oracle replays lexical/vector-only, bounded graph
+   expansion, and the complete route deterministically. Graph expansion becomes
+   default only if correctness improves without increasing unsupported,
+   ambiguous, or stale claims; otherwise retain the narrower passing route.
+3. Preserve raw results and report precision, recall, omissions/refusals,
+   latency, response size, and peak RSS. Incremental spend is zero, source stays
+   local, no network or account is required, and incremental memory stays below
+   1 GB.
+
+Delivered evidence: structural-first dispatch and request-local retrieval
+telemetry are implemented in `src/engine/index.ts`; CLI/MCP parity, stable
+identity, exact path/name, lexical sufficiency, embedding fallback, bounded
+work, and duplicate-name safety are covered by
+`src/__tests__/unit/structural-routing.spec.ts`. The checked-in multi-hop and
+duplicate-name oracle, fixture, deterministic four-route raw replay, and
+verifier outputs are under
+`benchmarks/evaluations/c80-structural-routing/`; reproduce them with
+`npm run bench:c80 && npm run verify:c80`. The limitations-aware precision,
+recall, unsupported/ambiguous/stale, omission, latency, response-size, spend,
+locality, and independently isolated RSS report is
+`docs/evidence/c80-structural-routing-2026-08-03.md`.
+
+Decision: bounded graph expansion is the default structural route because the
+checked-in gate improves mean oracle recall from 0.389 to 1.000 while preserving
+1.000 precision, zero unsupported and stale claims, and the same one surfaced
+duplicate-name ambiguity. The complete route preserves those results and loads
+embeddings only when exact or all-token structural evidence is insufficient.
+The largest isolated incremental RSS sample was 160,284,672 bytes; incremental
+spend was zero and no network, account, credential, or hosted service was used.
+
+Known limitations and decision gate: structural routing is not proof that
+semantic retrieval is unnecessary. Embeddings remain a bounded fallback, and
+token reduction alone cannot authorize a route that weakens correctness. Graph
+expansion follows resolved source relationships only, is capped at two hops and
+200 selected nodes, and cannot recover runtime-only or unresolved relationships.
+The three-case deterministic oracle proves this decision only on its checked-in
+cross-file chains; sampled RSS can miss short-lived peaks between samples.
+
+### C81 — Powered end-to-end benchmark with a diagnose arm
+
+- Status: evaluated — retained knodin unchanged
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C42, C43, C59, C80
+- Touches: competitive benchmark corpus/runner, task labels, deterministic
+  patch/test oracles, raw trajectories, statistics, and evidence report.
+- What: compare ordinary filesystem tools, knodin, and one pinned local
+  competitor on retrieval and failing-build/test diagnosis using a powered,
+  paired design.
+- Scope: at least 40 tasks, at least three repetitions, pinned repositories,
+  commits, prompts, models, versions, seeds, and budgets; confidence intervals
+  and pre-registered analysis are mandatory.
+- Evidence: checked-in corpus and labels, immutable raw trajectories, verifier
+  output, confidence intervals, and a limitations-aware report.
+
+Acceptance:
+
+1. Each arm runs the same tasks and deterministic correctness oracles. The
+   diagnose subset scores turns to a correct patch and passing test, not an LLM
+   judge alone; unavailable and incomparable rows remain explicit.
+2. Cache behavior is controlled and recorded. Do not report billed-cost claims
+   unless cache economics are comparable; this item must incur zero model/API
+   spend and require no hosted service, credentials, or source egress.
+   Incremental spend is zero.
+3. Record patch-application rate, turns to correct edit, factual correctness,
+   tokens where measured, cold/warm latency, and peak RSS under 1 GB. Preserve
+   losing cases and raw data without overwriting prior evidence.
+
+Known limitations and decision gate: the benchmark may justify retaining the
+product unchanged. It authorizes no superiority claim beyond oracle-qualified,
+comparable rows and no production feature outside a separately numbered item.
+
+Delivered evidence: the pinned 40-task corpus, three-repetition paired runner,
+deterministic retrieval and patch/test oracles, immutable accepted and excluded
+pilot trajectories, integrity hashes, and verifier are under
+`benchmarks/evaluations/c81-powered-benchmark/`; reproduce validation and
+confidence intervals with `npm run verify:c81`. The limitations-aware report is
+[`C81 powered benchmark evidence`](../docs/evidence/c81-powered-benchmark-2026-08-03.md).
+
+Decision: retain knodin unchanged. All three available arms achieved 1.000
+factual correctness and patch-plus-passing-test rate on this narrow synthetic
+corpus, with paired correctness differences of 0.000. The result supports no
+superiority, token, billed-cost, or production claim. The conservative
+worker-plus-descendant peak-RSS upper bound was 351,469,568 bytes; spend,
+hosted-service use, credentials, and source egress were zero.
+
+### C82 — Productize `compress diagnose`
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C59, C81
+- Touches: existing compress diagnose CLI/MCP dispatch, discoverability and
+  documentation, stable response schema, fixtures, telemetry, and replay.
+- What: make the retained-failure-to-graph workflow discoverable and robust so
+  an artifact resolves to owning symbols, tests, callers, and bounded source
+  without rerunning the failed command.
+- Scope: reuse the existing single MCP tool and retained C59 primitive; preserve
+  stable artifact identity, freshness, ambiguity, traversal, and budget bounds.
+- Evidence: checked-in adversarial diagnostic fixtures, CLI/MCP parity tests,
+  golden responses, raw replay, verifier, and local evidence report.
+
+Acceptance:
+
+1. Representative compiler, test, stack-trace, multiline, truncated, malformed,
+   stale, ambiguous, and missing-artifact cases return stable schema fields and
+   exact owning source evidence or an explicit bounded refusal.
+2. CLI and MCP produce equivalent source identities, callers/tests, omissions,
+   freshness, confidence, and telemetry without a new MCP tool, command rerun,
+   hosted service, credential, source egress, or model/API spend.
+   Incremental spend is zero.
+3. The C81 diagnose corpus demonstrates the workflow end to end with checked-in
+   deterministic oracles, hard item/byte/token caps, recoverable continuation,
+   and peak incremental memory below 1 GB.
+
+Known limitations and decision gate: static graph evidence cannot prove runtime
+causality. Documentation must say that diagnoses are bounded source-evidenced
+candidates, not guaranteed root causes or automatic fixes.
+
+Delivered evidence: the existing CLI and single-tool MCP dispatch now share an
+additive stable diagnosis envelope with confidence, exact diagnostic/relation
+omissions, retained-artifact continuation, and command-rerun/cap telemetry.
+Focused parity and refusal coverage is in `src/__tests__/unit/`; adversarial
+fixtures, golden responses, immutable raw replay, hard-cap verification, and
+resource evidence are under
+`benchmarks/evaluations/c82-compress-diagnose/`. Reproduce all ten adversarial
+cases and all ten C81 diagnose tasks with `npm run verify:c82`. The evidence
+report is [`C82 compress diagnose evidence`](../docs/evidence/c82-compress-diagnose-2026-08-03.md).
+
+The conservative measured maximum RSS was 309,116,928 bytes, below 1 GB.
+Incremental spend, command reruns, network/hosted service use, credentials, and
+source egress were zero. Static candidates remain neither runtime root-cause
+proof nor automatic fixes; the synthetic replay does not cover every toolchain.
+
+### C83 — Progressive evidence delivery and hash handshake
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C80, C82
+- Touches: gateway response contracts, locate/outline/evidence/expand dispatch,
+  continuation/evidence handles, content hashing, CLI/MCP tests, and docs.
+- What: deliver recoverable evidence levels and allow delta/omission only when
+  the client supplies an exact content hash for the baseline it holds.
+- Scope: every level reports returned and omitted material, reason, `more`, a
+  stable continuation, freshness, confidence, and truthful hard budgets.
+- Evidence: checked-in golden protocol fixtures, tamper/staleness/rename tests,
+  raw bounded replay, verifier, and compatibility report.
+
+Delivered evidence: the additive `evidence` operation and CLI command share the
+source-preserving implementation in `src/progressive-evidence.ts`. Golden and
+raw 14-case protocol replays, fixture, resource record, compatibility report,
+and limitations are under `benchmarks/evaluations/c83-progressive-evidence/`;
+reproduce them with `npm run verify:c83`. Unit acceptance covers complete
+omission recovery, adversarial hashes/handles/paths, stale and renamed handles,
+and byte-identical CLI/MCP edit anchors. The evidence report is
+[`C83 progressive evidence evidence`](../docs/evidence/c83-progressive-evidence-2026-08-03.md).
+
+Acceptance:
+
+1. Exact hash match permits the documented delta or omission path; missing,
+   stale, truncated, renamed, or tampered baselines return full required source
+   and state which path was taken. Client assertion alone is never trusted.
+2. Locate, outline, evidence, and expand remain deterministic and recoverable
+   under item/byte/token caps; tests prove omitted evidence can be requested and
+   that edit anchors remain intact across CLI and MCP.
+3. The protocol remains local, zero-spend, offline, under 1 GB incremental RSS,
+   backward-compatible where promised, and fail-closed on stale or ambiguous
+   evidence. Checked-in fixtures include adversarial hash and handle inputs.
+
+Known limitations and decision gate: this is not lossy summarization and does
+not authorize token-savings or task-success claims until C81 measures them.
+The V1 surface addresses one exact regular repository file at a time, refuses
+symlinks and ambiguous/path-traversal input, and uses a lightweight top-level
+outline rather than claiming the engine's complete relationship model. The
+synthetic replay authorizes no production-readiness or cross-platform claim.
+
+### C84 — Optional SCIP import
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C24, C80, C83
+- Touches: optional SCIP ingestion, stable identity/provenance mapping, conflict
+  handling, LSIF/native fallbacks, fixtures, lifecycle bounds, and docs.
+- What: import compiler-produced SCIP facts as an opt-in precision tier while
+  retaining LSIF compatibility and the native AST/structural/heuristic ladder.
+- Scope: SCIP files are local inputs; import is deterministic, bounded, and
+optional. Live LSP integration is explicitly not part of C84.
+- Evidence: checked-in SCIP fixtures and expected graph facts, malformed/path/
+  oversize/conflict tests, fallback replay, verifier, and resource report.
+
+Delivered evidence: `knodin index --scip <file>` explicitly imports a bounded
+local SCIP protobuf snapshot without discovering or running a producer. The
+npm-integrity-pinned `@sourcegraph/scip-typescript@0.4.0` fixture, binary hash,
+source, configuration, expected facts, duplicate document-local symbols, and
+adversarial cases are under `fixtures/c84-scip/` and `src/__tests__/unit/`.
+The raw offline replay, distinct relationship kinds, native/LSIF fallback,
+stable identity refresh, 64 MiB/10,000-file/250,000-fact/30-second bounds, and
+502,431,744-byte incremental RSS record are under
+`benchmarks/evaluations/c84-scip-import/`; reproduce them with
+`npm run verify:c84`. The evidence report is
+[`C84 optional SCIP import evidence`](../docs/evidence/c84-optional-scip-import-2026-08-03.md).
+
+Acceptance:
+
+1. Pinned fixtures produce deterministic stable identities, relationships,
+   source ranges, and `scip` provenance. Conflicting tiers surface ambiguity and
+   never silently replace higher-confidence or fresher evidence.
+2. Missing, malformed, hostile-path, stale, and oversized inputs fail safely;
+   repositories without SCIP retain current native/LSIF behavior with no daemon,
+   account, network, source egress, or model/API spend.
+   Incremental spend is zero.
+3. Import and query replays remain within explicit file/fact/time limits and
+   below 1 GB incremental RSS. Raw local results, verifier output, and known
+   language/indexer coverage are checked in.
+
+Known limitations and decision gate: SCIP precision is bounded by the producer
+and languages represented in the imported index. Any live LSP tier requires a
+separately approved roadmap item and must never become a baseline dependency.
+
+### C85 — Bounded git-history review signals
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C24, C44, C81
+- Touches: review risk serialization, bounded Git history queries, unavailable/
+  shallow states, synthetic repository fixtures, telemetry, and docs.
+- What: add churn, co-change, and coupling as separately itemized review signals
+  beside graph impact, test gaps, and structural centrality; forbid opaque scores.
+- Scope: all Git operations have explicit commit/file/time bounds and preserve
+  deterministic ordering, source evidence, and graceful unavailable states.
+- Evidence: checked-in synthetic Git DAG, exact signal oracles, bounded-command
+  tests, raw review replay, verifier, and resource report.
+- Evidence delivered: `src/engine/git-history.ts` and
+  `src/__tests__/unit/git-history-signals.spec.ts` cover rename-aware itemized
+  facts, merge/unrelated separation, shallow deepen, unborn, missing Git,
+  non-repository, arbitrary HEAD failure, timeout, path containment, hard bounds,
+  deterministic truncation, cache validity, and CLI/MCP serialization.
+  `benchmarks/evaluations/c85-git-history/` checks in the exact synthetic DAG,
+  raw replay, latency/command/resource evidence, limitations, and verifier;
+  `npm run verify:c85` reproduces churn 2, co-change 2, coupling 1, three bounded
+  history commands, zero locality costs, and peak RSS below 1 GB.
+
+Acceptance:
+
+1. Fixtures cover renames, merges, unrelated co-occurrence, shallow history,
+   unborn repositories, missing Git, and bounded truncation. Each output exposes
+   the contributing facts and omissions rather than only a composite number.
+2. Review remains deterministic, fail-closed, and useful when history is absent;
+   commands cannot escape the repository or exceed configured commit/file/time
+   limits. CLI/MCP-compatible evidence retains freshness and confidence.
+3. Checked-in replay reports correctness, latency, command counts, and peak RSS
+   below 1 GB with zero spend, no network, no credentials, and no source egress.
+
+Known limitations and decision gate: co-change is correlation, not causation.
+History signals may influence itemized review context but cannot independently
+assert defect likelihood, ownership, or mandatory remediation.
+
+### C86 — Static-embedding bake-off
+
+- Status: evaluated — retained MiniLM unchanged
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C46, C51, C80, C81
+- Touches: isolated Model2Vec/MiniLM evaluation runner, fixed corpus and labels,
+  model provenance/digests, raw measurements, verifier, and decision record.
+- What: evaluate a pinned static-embedding candidate against retained MiniLM
+  before authorizing any runtime, index-format, or default-search change.
+- Scope: measure cold/warm indexing and query performance, RSS, storage, recall,
+  NDCG, and downstream task correctness with at least three repetitions.
+- Evidence: checked-in corpus/query labels, model identifiers and digests, raw
+  repeated results, verifier output, confidence/variance report, and disposition.
+- Evidence delivered: `benchmarks/evaluations/c86-static-embeddings/` contains
+  the pinned 20-document corpus, ten relevance/task labels, model revisions and
+  ONNX digests, six fresh-process raw repetitions, cold/warm timing, RSS and
+  storage measurements, descriptive confidence/variance, unsupported cases,
+  limitations, and the retain-MiniLM decision. `npm run verify:c86` checks the
+  identical-route/budget oracle, three repetitions per arm, local/offline and
+  zero-spend contract, sub-1-GB incremental RSS, artifact pins, and evaluation
+  isolation without requiring either model artifact.
+
+Acceptance:
+
+1. Both candidates run on identical local fixtures, retrieval routes, budgets,
+   and deterministic relevance/task oracles. Record setup, unsupported cases,
+   cold/warm timing, index size, recall/NDCG, correctness, and peak RSS.
+2. The replay is offline after documented local preparation, adds no production
+   dependency, uses no hosted API/account/source egress, incurs zero spend, and
+   stays below 1 GB incremental memory. Pin model identity and artifact digest.
+3. Retain MiniLM unless the pre-registered decision gate shows a reproducible
+   correctness-preserving win. Close by retaining MiniLM, deferring/rejecting
+   Model2Vec, or proposing a separately reviewed implementation item; evaluation
+   alone must not change production behavior or schema.
+
+Known limitations and decision gate: corpus results may not generalize to every
+language or repository. Publish only measured local outcomes, never a universal
+embedding-quality or product-superiority claim.
+
+Decision: retain MiniLM unchanged. On the checked-in fixture both models reached
+1.000 recall@5, 1.000 NDCG@10, and 10/10 top-1 task correctness in every
+repetition. Model2Vec was repeatably faster and smaller locally, but the corpus
+does not resolve repository-scale or multilingual-query quality, so the
+pre-registered gate's no-material-unsupported-category condition did not pass.
+No production runtime, dependency, index format, schema, default, or MCP surface
+changed, and no separately numbered implementation item is authorized.
+
+### C87 — Structural cold-start fast path
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C56, C68
+- Touches: packaged CLI launcher, structural snapshot publication, direct-file
+  fallback, compression routing, benchmarks, and truth-bound response fields.
+- What: bypass graph/model initialization for structural-only cold requests
+  while preserving the persistent graph route for relationship intelligence.
+- Scope: file outline, exact file-scoped extraction, batch outline, project
+  overview, and pure output compression only.
+- Evidence: `src/structural-snapshot.ts`, `src/structural-fast-path.ts`,
+  `src/pure-compression-cli.ts`, focused unit tests, and
+  `benchmarks/evaluations/c87-structural-cold-start/raw-results.json`.
+
+Indexing now publishes an atomic compact file/symbol snapshot. The packaged
+launcher routes file outlines, exact file-scoped extraction, batch outlines,
+project overview, and pure compression without importing the graph or embedding
+modules. A missing or fingerprint-stale requested file is parsed directly and
+labeled `lexical-structural-fallback`; graph-backed search, impact, review,
+relationships, and architecture retain their existing initialization and
+freshness contract.
+
+Acceptance:
+
+1. File-outline, exact-symbol, and project-overview fresh-process p50 are
+   at most 50 ms and p95 at most 75 ms after separating benchmark-parent spawn/
+   scheduling overhead from measured child-process lifetime. Preserve both raw
+   observations; do not hide an application or runtime-floor miss.
+2. Warm p50 regresses by no more than 10%, response tokens by no more than 5%,
+   and the existing shared correctness oracles remain 100% for both fast and
+   graph routes.
+3. Every fast answer includes path/fingerprint evidence, exact locations,
+   evidence quality, `graphEnriched: false`, file-scoped uniqueness limits, and
+   an upgrade handle. Dependency evidence proves no graph/model import.
+4. Graph-backed operations retain stable identity, relationships, and freshness
+   evidence. Snapshot absence/staleness never becomes a repository-wide
+   freshness claim. Checked-in replay evidence requires zero hosted spend,
+   network, account, credential, or source egress.
+
+Known limitations and decision gate: the direct fallback is a bounded lexical
+structural parser, not the full Tree-sitter graph extractor. Its classification
+is explicit and a later graph operation is the supported enrichment path. Keep
+the fast route only while all checked-in acceptance gates pass.
+
+### C88 — Profile-based contained execution
+
+- Status: implemented — macOS certified; Linux/Windows unavailable
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C57, C58, C59
+- Touches: one-tool schema/dispatcher, profile configuration, macOS Seatbelt
+  adapter, output compression/diagnosis, audit records, adversarial evidence,
+  and security documentation.
+- What: permit only preapproved single-process profiles behind enforceable
+  macOS filesystem/network/process boundaries and fail closed elsewhere.
+- Scope: test, lint, typecheck, and build-style profiles with immutable argv;
+  arbitrary commands, child processes, and portable containment claims remain
+  excluded.
+- Evidence: `src/execution-profile.ts`, `docs/CONTAINED-EXECUTION.md`, gateway/
+  adversarial unit tests, and `benchmarks/evaluations/c88-contained-execution/`.
+
+C58's portable polling prototype remains rejected. C88 authorizes a narrower
+production contract: independent global and repository enablement, immutable
+repository profile identity, absolute configured executable and fixed argv,
+no shell/caller suffix/cwd/environment, sanitized environment, repository cwd,
+hard timeout/output/fork limits, private profile-only audit, recoverable
+compression, and failure-to-code diagnosis.
+
+Acceptance:
+
+1. macOS native evidence proves literal metacharacter argv, denied ambient
+   credentials/user-data reads, denied network sockets, denied forks,
+   repository-only authorization, closed stdin, output/timeout termination, and
+   no raw command text in audit/telemetry.
+2. `fully-contained` is reported only by the certified macOS Seatbelt adapter.
+   Linux and Windows report `containment-unavailable` and spawn nothing until
+   independent native adapters and evidence exist.
+3. MCP accepts only `profile`; it cannot accept an executable, arguments, cwd,
+   environment, or limits. Every result names the profile, actual containment,
+   configured bounds, exit state, compressed artifact, and diagnosis state.
+4. Preserve the one-tool schema reduction gate and local-only operation. The
+   checked-in evidence requires zero hosted spend and zero source egress while
+   preserving the original C58 limitations. Do not describe deprecated
+   `sandbox-exec` as a supported Apple public security API.
+
+Known limitations and decision gate: profiles are single-process
+(`maxProcesses: 1`), system runtime paths remain readable, approved repository
+code can modify its checkout, and Linux/Windows execution is unavailable. Keep
+the surface only while native evidence proves the stated boundary; any broader
+profile or platform requires a separately certified adapter. Preserve no unrestricted command surface.
+
+### C89 — MCP request reliability and recovery
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C3, C16, C53
+- Touches: MCP server lifecycle, request dispatcher, cancellation/progress
+  bridge, durable diagnostic log, error taxonomy, and adversarial transport tests.
+- What: prevent one expensive or stuck operation from ending the useful MCP
+  session and make every failure attributable and recoverable.
+- Scope: per-operation deadlines, client cancellation, progress notifications,
+  request and trace IDs, bounded exit-safe logs, stuck-request isolation, and
+  distinct crash, lock, memory-pressure, timeout, and client-disconnect errors.
+- Evidence: `src/mcp-worker-supervisor.ts`, `src/mcp-graph-worker.ts`,
+  `src/mcp-reliability.ts`, `src/server.ts`, `docs/MCP.md`, and the checked-in
+  supervisor/lifecycle/CLI replays prove versioned IPC, real held-lock handling,
+  abrupt worker exit, the observed `Transport closed` disconnect cancellation
+  race, hard termination, bounded restart, predecessor-to-next-success
+  correlation, warm reuse, source-safe
+  bounded journals, and linked-worktree isolation without hosted dependencies.
+
+Acceptance:
+
+1. Every request receives stable request/trace correlation, an operation-aware
+   deadline, and cancellation that releases its resources without corrupting the
+   graph; expensive operations emit bounded truthful progress when supported.
+2. A killed worker, held graph lock, memory-pressure sentinel, deadline, and
+   disconnected client each produce a distinct actionable error. The server
+   remains usable or restarts automatically without retry loops or lost logs.
+3. Durable logs survive abrupt process exit, rotate within documented byte/time
+   bounds, omit repository source and secrets, and correlate progress, failure,
+   cleanup, restart, and the next successful request.
+4. Checked-in CLI/MCP parity, concurrency, cancellation-race, forced-exit, and
+   recovery replays pass locally with zero hosted spend, credentials, network,
+   or source egress.
+
+Known limitations and decision gate: deadlines and memory-pressure attribution
+are bounded diagnoses, not proof of an operating-system root cause. Do not claim
+transparent recovery unless the next independent request succeeds in replay.
+
+### C90 — Privacy-safe diagnostic support bundle
+
+- Status: implemented
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C16, C59, C89
+- Touches: diagnostics CLI, MCP trace store, lifecycle/graph health, redaction,
+  archive manifest, preview/report rendering, and privacy adversarial tests.
+- What: turn local diagnostics into one support-ready bundle whose exact shared
+  contents users can inspect before export.
+- Scope: recent MCP traces/failures, lifecycle and graph health, versions and
+  runtime, repository scale without source, manifest, human report, and preview.
+- Evidence: `src/diagnostics.ts`, `src/diagnostics-write-helper.ts`,
+  `schemas/support-bundle-v2.schema.json`, the C90 adversarial fixture and unit
+  replays, and packed-install preview/archive/inspect smoke prove a fail-closed
+  allowlist, exact content-addressed preview parity, bounded C89 trace recovery,
+  honest unavailable fields, linked-worktree isolation, bounded retention, and
+  repository-bound no-follow writes without hosted dependencies or source
+  egress.
+
+Acceptance:
+
+1. Preview and final manifest enumerate every file and field, byte size,
+   retention window, redaction applied, and unavailable section before sharing;
+   the concise report includes request/trace IDs and actionable recovery steps.
+2. Adversarial fixtures containing source, diffs, paths outside the repository,
+   credentials, environment values, usernames, and command output prove none can
+   enter the default bundle. Repository scale is aggregate metadata only.
+3. The bundle includes exit-surviving C89 traces and recent classified failures,
+   lifecycle/graph health, knodin/Node/platform versions, and honest missing or
+   stale states without initiating network activity.
+4. Checked-in deterministic CLI/MCP tests prove preview/archive parity, bounded
+   size and retention, zero hosted spend, no credentials, and no source egress.
+
+Known limitations and decision gate: automated redaction cannot certify arbitrary
+future fields. New diagnostic fields fail closed until included in the explicit
+allowlist and privacy oracle; sending a bundle remains a user action.
+
+### C91 — Boring macOS installation and runtime handoff
+
+- Status: parked-external-evidence — 2026-08-05
+- Previous status: owner-approved adoption priority
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C52, C73, C89, C90
+- Touches: package/install CI, runtime resolver, doctor repairs, client setup
+  guides, macOS acceptance fixtures, and package compatibility checks.
+- What: make install through first useful MCP call repeatable on environments the
+  project can actually validate.
+- Scope: macOS; Node 20 project handoff to an available Node 24 runtime; mise,
+  nvm, fnm, Volta, asdf, Homebrew, npm, and Artifactory; Copilot, Claude, Gemini,
+  and Codex; safe doctor repairs.
+- Evidence: checked-in automated install matrix, package-content/compatibility
+  gates, isolated runtime-manager fixtures, and timed acceptance receipts.
+
+Acceptance:
+
+1. Each named installation path is exercised from a clean macOS fixture through
+   install, `knodin init`, `knodin status`, one useful MCP call, and uninstall or
+   rollback; package compatibility is checked automatically in CI.
+2. A Node 20 project reliably hands execution to an already available compatible
+   Node 24 runtime without modifying the project's declared runtime. Missing or
+   conflicting runtimes produce one actionable diagnostic.
+3. Copilot, Claude, Gemini, and Codex each complete the same acceptance flow in
+   no more than two minutes under the documented warm/cold boundary, with exact
+   client/version/configuration evidence and no universal client claim.
+4. Doctor applies only enumerated idempotent repairs with preview and rollback;
+   checked-in tests require zero hosted spend for local fixtures and no source
+   egress. Credentialed Artifactory evidence is recorded only when available.
+
+Known limitations and decision gate: Linux and Windows certification are not a
+goal and unavailable platform evidence must stay unavailable. Runtime-manager
+fixtures prove supported configurations, not every shell customization.
+
+Code-readiness on 2026-08-05 added a merge-preserving GitHub Copilot/VS Code
+MCP adapter, doctor visibility, idempotent CLI-only reversal, and fail-closed
+malformed/symlink handling. Certification remains parked until native macOS
+install-to-uninstall receipts exist for nvm, fnm, Volta, and asdf; an exact
+GitHub Copilot/VS Code timed receipt joins the available Claude, Gemini, and
+Codex versions; a published Homebrew formula and credentialed Artifactory path
+are exercised where authorized; and the same four clients complete the bounded
+install, `init`, `status`, useful MCP call, and rollback flow. Doctor also still
+needs an enumerated transactional preview/apply/rollback implementation and
+acceptance replay. No fixture result may be promoted to this missing native
+evidence, and C94 remains dependency-blocked.
+
+### C92 — Unified five-channel release orchestration
+
+- Status: parked-external-evidence — 2026-08-06
+- Previous status: owner-approved release priority
+- Priority: P0
+- Disposition: Must close
+- DependsOn: C64, C91
+- Touches: release workflows, preflight, immutable package staging, npm,
+  Artifactory, Homebrew, GitHub SaaS/GHES synchronization, receipts, and retry tests.
+- What: replace fragmented publication paths with one fail-closed orchestrator
+  that promotes one immutable tarball everywhere.
+- Scope: npm, Artifactory, Homebrew, GitHub SaaS, and the read-only GHES mirror;
+  availability preflight, private-repository attestations, retries, and receipts.
+- Evidence: checked-in dry-run channel adapters, fault matrix, immutable digest
+  oracle, retry replay, receipt schema, and private-repository attestation fixture.
+
+Acceptance:
+
+1. Before any publication, preflight proves every required channel, credential,
+   permission, target version, and attestation mode is available; one failure
+   publishes nothing and leaves a machine-readable failure receipt.
+2. One staged tarball digest and length are promoted to all five channels.
+   Retries reconcile idempotently without moving or recreating source tags and
+   refuse any channel whose existing bytes differ.
+3. Private-repository attestations follow the supported trust path rather than
+   assuming public-repository identity behavior. The final receipt records each
+   channel's artifact identity, digest, status, attempt, and authoritative URL.
+4. Checked-in fault-injection tests cover every preflight/publish boundary with
+   zero real publication or spend. Live channel receipts remain Track B evidence
+   and cannot be simulated by this local implementation item.
+
+Known limitations and decision gate: dry-run adapters do not certify production
+availability. GitHub SaaS remains authoritative; GHES is a read-only mirror and
+must never be forced. Stop on divergence.
+
+Parking decision: C92 remains open behind C64 and C91. Ordinary 0.x publishing
+continues through the existing fail-closed tag workflow; this does not claim the
+unimplemented unified five-channel orchestrator or manufacture channel receipts.
+
+### C93 — Paired engineering-outcome measurement
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C24, C81
+- Touches: competitive runner, task corpus, patch evaluator, dependency oracle,
+  agent telemetry import, cost accounting, and outcome report.
+- What: measure whether knodin improves completed engineering work, not whether
+  it merely emits fewer tokens.
+- Scope: identical with/without-knodin tasks measuring task success,
+  missed-dependency rate, corrective round trips, time to first correct edit,
+  patch-application success, total billed cost, and performance.
+- Evidence: preregistered checked-in corpus/oracles, paired raw runs, variance and
+  failure accounting, verifier, and a limitations-bound report.
+- Evidence delivered: `benchmarks/evaluations/c93-engineering-outcomes/`
+  contains the preregistered two-arm corpus, executable dependency/patch oracle,
+  source-free raw event trajectories, deterministic local runner, paired
+  variance/uncertainty report, and visible limitations. `npm run verify:c93`
+  recreates all 12 runs from the identical fixture commit on isolated linked
+  worktrees and non-default branches, verifies independent arm commits and a
+  clean base checkout, and records zero hosted spend, observed network requests,
+  or source egress plus explicit process-isolation bounds and unavailable—not
+  inferred—token and billed-cost data.
+
+Acceptance:
+
+1. Both arms use identical repositories, commits, tasks, model/client versions,
+   prompts, permissions, time limits, repetitions, and correctness oracles; the
+   only intended treatment difference is knodin availability/instructions.
+2. Every named outcome is reported per task and in aggregate, including failures,
+   censored time, unavailable token/cost data, and confidence/variance. Token
+   counts may be diagnostic but are never the success metric.
+3. Dependency and patch oracles inspect the resulting edit and tests rather than
+   grading prose. Raw events support auditable round-trip and first-correct-edit
+   reconstruction without storing repository source in telemetry.
+4. The local harness and synthetic fixtures are checked in and run with zero hosted
+   spend; any paid model replay records actual total billed cost and is
+   never inferred from tokens alone.
+   Checked-in evidence requires zero hosted spend.
+
+Known limitations and decision gate: a bounded corpus cannot prove universal
+product superiority. Publish only measured effect sizes and uncertainty; a null
+or negative outcome must remain visible and may require product rollback.
+
+### C94 — First-use clarity and five-minute demonstration
+
+- Status: parked-external-evidence — 2026-08-06
+- Previous status: owner-approved clarity priority
+- Blocked by: C91 external certification
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C89, C90, C91
+- Touches: MCP/CLI help, status responses, client guides, examples, demo fixture,
+  freshness/error copy, and documentation integrity tests.
+- What: make the first session explain the tool identity, next action, evidence
+  limits, freshness, and recovery without requiring prior product knowledge.
+- Scope: `knodin.knodin` naming, operation discovery/examples, next-useful-action
+  recommendations, concise limitations/recovery, and a real-repository demo.
+- Evidence: checked-in golden help/status/error output, four-client guide checks,
+  timed demo transcript, and source-evidence links.
+
+Acceptance:
+
+1. Setup docs explain that clients display `knodin.knodin` as server name plus
+   tool name. Schema/help gives copyable examples and makes operation discovery
+   possible without adding MCP tools.
+2. Status recommends a context-sensitive next useful operation and presents
+   freshness, availability, known bounds, and repair/reindex actions concisely;
+   no healthy, stale, ambiguous, or repair-needed state is conflated.
+3. A checked-in five-minute demonstration runs `knodin init`, status, orientation,
+   source-evidenced impact/review, and bounded context on a real repository and
+   explicitly demonstrates value, ROI, tomorrow's action, and secret sauce.
+4. Golden CLI/MCP and docs-integrity tests run locally with zero hosted spend,
+   no credentials, and no source egress.
+
+Known limitations and decision gate: a scripted demonstration is onboarding
+evidence, not an outcome or superiority benchmark. Client UI labels may vary by
+version and must name the version actually checked.
+
+Parking decision: C94 remains open behind C91. The existing local help and
+documentation remain available, but no fixture is promoted into the missing
+native client demonstration or certification evidence.
+
+### C95 — Defensible behavioral-contract replay
+
+- Status: implemented
+- Priority: P1
+- Disposition: Must close
+- DependsOn: C3, C24, C83
+- Touches: contract manifest, cross-operation fixtures, freshness/identity/
+  evidence/budget/compression/diagnosis/privacy tests, and product positioning.
+- What: make the integrated behavior—not individual graph feature count—the
+  product's checked and release-gated contract.
+- Scope: truthful budgets, explicit freshness/availability, source evidence,
+  ambiguity-safe stable identity, recoverable compression, failure-to-symbol
+  diagnosis, and local operation without source egress.
+- Evidence: `contracts/behavior-contract-v1.json`,
+  `benchmarks/evaluations/c95-behavior-contract/runner.ts`,
+  `scripts/verify-c95.ts`, `docs/BEHAVIORAL-CONTRACT.md`, and the release
+  preflight gate map and dispatch all 22 production operations plus every
+  schema-declared query/action discriminator against linked-worktree fixtures.
+  The replays cover hard-budget continuation, stable evidence,
+  recoverable compression, freshness and ambiguity qualification, diagnosis,
+  and observed local privacy across fetch, HTTP(S), TCP/TLS, DNS, native-addon,
+  and subprocess boundaries. All 458 mapped fixture/clause rows have isolated
+  pre-serialization production-response mutations that fail the same release
+  oracle; omitted or mutated clauses fail closed.
+
+Acceptance:
+
+1. Every production operation is mapped to the applicable contract clauses and
+   adversarial fixtures prove honest truncation, stale/unavailable states,
+   evidence provenance, ambiguity, recovery handles, diagnosis confidence, and
+   privacy behavior.
+2. The replay verifies composition: a bounded response can be expanded by a
+   stable handle without changing identity/evidence, and stale or ambiguous
+   evidence cannot become a confident diagnosis or impact claim.
+3. Release preflight fails on a contract regression. Product documentation
+   answers value, ROI, tomorrow, and secret sauce with checked-in evidence and
+   preserves every roadmap limitation.
+4. Tests and replays run locally with zero hosted spend, credentials, network,
+   or source egress; no universal superiority claim is inferred.
+
+Known limitations and decision gate: the contract proves the checked operation
+and action fixtures, not all repositories or clients. Network construction is
+denied before request-body streaming, and opaque transport inside an
+already-loaded native library remains unobservable. A new operation or action
+must declare its clauses, positive response semantics, and isolated production
+mutation before release.
+
+### C96 — Replay-gated capability discipline
+
+- Status: evaluated — deferred
+- Priority: P2
+- Disposition: Evaluate
+- DependsOn: C24, C93, C95
+- Touches: roadmap policy, proposal template, outcome replay, one narrow
+  cross-substrate fixture, verifier, and decision record.
+- What: require evidence of correctness or workflow improvement before expanding
+  production capability, beginning with one bounded cross-substrate impact case.
+- Scope: one relationship crossing two explicitly named substrates; no broad
+  platform, language, repository, or superiority promise.
+- Evidence: checked-in baseline/treatment fixture, exact dependency and task
+  oracles, cost/resource report, limitations, and retain/defer/implement decision.
+
+Acceptance:
+
+1. Preregister one concrete missed-dependency or workflow failure and the exact
+   improvement threshold before implementation. Compare unchanged knodin with a
+   bounded prototype on the same task using C93 outcomes and C95 contracts.
+2. The fixture names supported substrates, edge provenance, ambiguity behavior,
+   freshness, budgets, and false-positive/negative oracles; unsupported crossings
+   remain explicit rather than generalized.
+3. Close by retaining knodin unchanged, deferring/rejecting the capability, or
+   creating a separately numbered implementation item only when the gate passes.
+4. Evaluation artifacts and verifier are checked in, require zero hosted spend,
+   credentials, network, or source egress, and preserve losing results.
+
+Known limitations and decision gate: one passing cross-substrate fixture does
+not authorize a broad platform claim. Implementation requires a separately
+reviewed item and must preserve the behavioral contract.
+
+Decision: defer production expansion. C93 found no correctness advantage on its
+narrow paired fixture, and C95 already requires every new operation or action to
+declare and replay its behavioral clauses. No preregistered cross-substrate
+missed-dependency case currently justifies a prototype, so knodin remains
+unchanged. Reopen under a separately numbered item only when a concrete failure,
+supported substrates, exact oracle, and improvement threshold are preregistered.
+Evidence: `benchmarks/evaluations/c93-engineering-outcomes/verification.json`,
+`contracts/behavior-contract-v1.json`, and
+`benchmarks/evaluations/c95-behavior-contract/runner.ts`.
+
+### C97 — One-process semantic residency reclamation
+
+- Status: evaluated — retained existing design
+- Priority: P1
+- Disposition: Evaluate
+- DependsOn: C46, C51, C80, C87
+- Touches: evaluation and decision evidence only; no runtime, status, API, or
+  storage change.
+- What: test whether idle model/vector/HNSW eviction can make a repeatable OS-RSS
+  guarantee while preserving Knodin's one-local-process architecture.
+- Evidence: `benchmarks/evaluations/c97-one-process-semantic-residency/` and
+  `scripts/verify-c97.ts` bind 10-trial fresh-process measurements to the runner,
+  engine, package, and embedding-test sources.
+
+Decision: retain the current lazy local model and bounded generation-scoped
+caches. No in-process candidate repeatedly reclaimed both 32 MiB and 15% of its
+attributable semantic increment across two corpus tiers. ONNX disposal and
+allocator behavior were nondeterministic; `worker_threads` retained the shared
+native address space; q8 lacks the required C28 retrieval-equivalence replay;
+fp16 failed to initialize. Child-process isolation is explicitly rejected
+because it would violate the one-local-process product contract. Do not claim
+idle RSS reclamation from model disposal or cache clearing on this evidence.
+
+Known limitations: resident semantic search retains a measurable one-process
+RSS cost after first use. Structural-first routing still avoids loading the model
+when evidence is sufficient, and decoded-vector/HNSW caches remain bounded and
+generation-invalidated. Reopen only with a portable allocator/runtime mechanism
+that passes the unchanged absolute, percentage, p95, retrieval, and 20-cycle
+gates.
+
+Final-stack refresh: C101 reran the full C97 measurement after C98–C100 changed
+the shared engine. Some individual cache/ONNX trials crossed the memory
+threshold, but no production candidate passed all 10 trials; the retained
+one-process decision therefore remains unchanged. The refreshed raw artifact
+replaces the mutable C97 measurement file and `verify:c97` recomputes this gate.
+
+## Explicit non-goals from the GitNexus comparison
+
+- Do not split knodin's gateway into one MCP schema per capability; the one-tool
+  surface is a measured differentiator.
+- Do not copy unrestricted Cypher directly into the MCP surface.
+- Do not require Milvus, Qdrant, Ollama, credentials, or any hosted service;
+  Claude Context and mcp-codebase-index validate this differentiator.
+- Do not add one MCP tool per capability; Serena's 29-tool and
+  code-review-graph's 30-tool surfaces reinforce the one-gateway advantage.
+- Do not make vector visualization, agent memory, or skill generation core graph
+  requirements. C35 is limited to deterministic local architecture/call-flow
+  artifacts with a concrete developer workflow; it does not authorize a hosted
+  visualization service or a generalized vector-visualization feature.
+- Do not enable network embeddings, hosted indexing, telemetry, or source-code
+  egress to chase competitor features.
+- Do not claim API-shape or cross-repository superiority until dedicated local
+  fixtures produce evidence.
+- Do not interpret every competitor option as a product requirement; parameters
+  that merely select nonexistent groups, branches, or services need real
+  fixtures before roadmap promotion.
+
+## Verification bar
+
+Every implementation item must run the repository's discovered gates and add a
+targeted acceptance fixture. At minimum:
+
+```bash
+bun run typecheck
+bun run lint
+bun run test
+```
+
+Competitive claims must also re-run the relevant harness under
+`benchmarks/competitors/` and update its result file without deleting losing
+cases.
+
+## Competitive replay — 2026-07-24 (Phase 2)
+
+Fresh, provenance-bound replays of every dimension were run against the real
+competitor CLIs and saved as **new** immutable artifacts (never overwriting
+prior results): search `raw-results-20260724T182246Z.json`, review + architecture
+`…T182448Z.json`, and symbols/editing/visualization/context/lifecycle
+`…T182707Z.json` under `benchmarks/evaluations/competitive-*/`.
+
+Applying the measurement contract (a WIN needs equivalent operation/fixture/mode/
+scope/budget/oracle **and** an oracle-qualified row; unavailable/unverified/
+incomparable rows are excluded from win claims):
+
+### Where knodin is ahead or level (oracle-qualified, comparable)
+
+- **Diff review — WIN.** traversal recall 1.0 and 733 B vs gitnexus (recall 1.0,
+  1458 B), code-review-graph (recall 0, 2269 B), graphify (recall 0.667).
+- **Architecture — WIN.** full package coverage + hubs + bridges; every completed
+  competitor is at best equal on coverage, none better.
+- **Search — WIN vs the only comparable competitor.** nDCG 0.855 vs gitnexus
+  0.677; dead-code precision 1.0 vs 0.667. codegraph (probe-only, unscored),
+  grepai (MCP probe blocked), claude-context (needs Ollama+Milvus) are
+  contract-excluded.
+- **Symbols — WIN/level.** precision 1 / recall 1: ties gitnexus (1/1), beats
+  codegraph (0/0), serena (0/0), codebase-memory (1/0.5).
+- **Lifecycle capability — WIN.** indexed/queryable/closed/stale-detection/
+  per-query telemetry all qualified; codebase-memory and grepai advertise
+  neither stale detection nor per-query telemetry.
+
+### Where the comparison is not oracle-qualified (excluded, not losses)
+
+- **Editing / Visualization / Context.** knodin passes its golden/export oracles;
+  the competitors either did not run (serena, code-review-graph, aider
+  unavailable/blocked) or ran without a shared correctness oracle (graphify,
+  repomix, code2prompt "complete" but unscored). No comparable head-to-head.
+- **Project memory.** knodin has no memory feature (deferred, ADR 004); Serena's
+  own value-beyond-docs gate also failed. No contest.
+
+### Where knodin still costs more — and why
+
+- **Lifecycle peak RSS: 83.8 MB vs codebase-memory 31.3 MB, grepai 22.9 MB.**
+  This is the one axis where knodin's raw number is worse. It is **not** an
+  oracle-qualified head-to-head: knodin is measured as a dedicated, long-lived
+  product process holding the real semantic model + graph resident (which is
+  precisely what wins the search-quality contest above), while the competitors
+  are measured at spawn-per-command peak. The RSS cost and the search-quality
+  lead are two sides of the same resident-model design; knodin cannot undercut
+  them on RSS without abandoning the model that beats them on search. C51
+  (native training-free quantization) targets the *stored-embedding* portion of
+  that footprint; the model-runtime portion is inherent to local semantic search.
+
+Bottom line: on every dimension with an oracle-qualified head-to-head against an
+available competitor, knodin is **as good or better** (wins or ties). The only
+place a competitor's raw number beats knodin is lifecycle RSS, which is an
+incomparable isolation model and the direct cost of knodin's search-quality lead.