[Epic] Make Madar a trustworthy evidence-backed context compiler

[mohanagy]

Outcome

Turn Madar from an advanced prototype / early-production DevTool into a trustworthy evidence-backed context compiler for a clearly declared TypeScript/Node support corridor.

The product north star is:

Madar turns a task and a local repository into the smallest evidence-backed context pack that preserves the critical execution and impact paths while explicitly naming what it may have missed.

This epic is the authoritative execution index for the technical roadmap. Every implementation change must be tracked by a linked child issue with an explicit dependency, scope boundary, acceptance criteria, validation gate, and rollback path.

Audited baseline

All initial findings and architecture decisions are based on remote main at:

06b373a447acfce895412ac10eb4e5228c5df0b7

This is the v0.32.1 release line.

The audit confirmed six high-impact facts:

1. KnowledgeGraph is not a semantic multigraph. Edge identity is endpoint-only, so later facts overwrite earlier facts between the same nodes.
2. Graph construction detects dangling endpoints and then filters/skips them without durable accounting.
3. Production retrieval and context-pack code contains exact status-page/OpenStatus-era paths, symbols, and task concepts.
4. Automatic TS/JS generation builds SPI information, discards SPI topology, and reruns legacy semantic extraction over the same supported files.
5. Several common MCP installers default to a profile that does not expose context_pack.
6. The public production-default benchmark has zero valid Native-vs-Madar outcome comparisons.

Strategic principles

• Correctness and explicit uncertainty come before token reduction.
• The graph is infrastructure, not the product moat.
• A polished context pack must never hide missing, rejected, unresolved, stale, or conflicting evidence.
• Static execution paths are hypotheses, not observed runtime traces.
• Exact/path/symbol retrieval should seed bounded graph expansion; graph traversal should be used only where relationships add value.
• Production behavior must remain independent from qualification repositories and benchmark prompts.
• Pack v1, CLI, and MCP compatibility should be preserved behind adapters where safe.
• Compatibility must not preserve silent semantic loss.
• Do not rewrite Madar. Correct individual seams behind characterization and differential tests.

Complete dependency-ordered roadmap

Phase 0 — Trust foundations and qualification gates

Parent epic: #649

• [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 — Stabilize the complete Vitest suite and protected CI merge gate.
• [P0] Freeze the natural qualification corpus, independent rubrics, and stop rule #655 — Freeze the natural qualification corpus, independent rubrics, and stop rule.
• [P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 — Graph PR A: plural relationship queries and explicit topology APIs.
• [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657 — Graph PR B: deterministic semantic multigraph and artifact v2.
• [P0][Graph PR C] Account for every normalized graph candidate and retain unresolved facts #658 — Graph PR C: terminal accounting and unresolved/rejected/conflicting facts.
• [P0][Graph PR D] Cap answerability from graph-integrity state #659 — Graph PR D: graph-integrity answerability cap.
• [P0] Remove qualification-repository tuning from production retrieval and claims #660 — Remove qualification-repository tuning from production retrieval and claims.
• [P0] Add independent Tier 1 graph, retrieval, Pack, and negative-trust evaluation #661 — Add independent Tier 1 graph, retrieval, Pack, and negative-trust evaluation.

Execution note: #654 and #655 can start immediately. #656 may be implemented in parallel but cannot merge until #654 is resolved. The graph implementation sequence is strictly #656 → #657 → #658 → #659. Then complete #660 and #661.

Phase 1 — Trustworthy context under incomplete knowledge

Parent epic: #650

• [P0] Implement a versioned semantic uncertainty ledger across adapters #662 — Implement a versioned semantic uncertainty ledger across adapters.
• [P0] Prevent false-ready answerability under incomplete repository knowledge #663 — Prevent false-ready answerability under incomplete repository knowledge.
• [P1] Introduce one canonical internal context-compilation seam #664 — Introduce one canonical internal context-compilation seam.
• [P1] Add an end-to-end evidence, ranking, omission, and compaction trace #665 — Add an end-to-end evidence, ranking, omission, and compaction trace.
• [P1] Qualify and stage a context-pack-first default for supported agent hosts #666 — Qualify and stage a context-pack-first default for supported hosts.

Execution note: #662 → #663 → #664. After #664, #665 and the host-qualification portions of #666 may proceed according to their stated dependencies.

Phase 2 — Measurable product advantage

Parent epic: #651

• [P1] Establish a valid Tier 2 Native-vs-Madar benchmark harness and baseline #667 — Establish a valid Tier 2 Native-vs-Madar benchmark harness and baseline.
• [P1] Qualify TypeScript/Node execution and impact semantics for a declared support corridor #668 — Qualify TypeScript/Node execution and impact semantics for a declared support corridor.
• [P1] Establish a framework-adapter qualification and conformance contract #669 — Establish a framework-adapter qualification and conformance contract.
• [P1] Consolidate TypeScript/JavaScript semantic authority behind a parity gate #670 — Consolidate TypeScript/JavaScript semantic authority behind a parity gate.
• [P1] Persist exact path, symbol, and lexical indexes for hybrid seed retrieval #671 — Persist exact path, symbol, and lexical indexes for hybrid seed retrieval.
• [P1] Make automatic indexing semantically incremental with full-regeneration equivalence #672 — Make automatic indexing semantically incremental with full-regeneration equivalence.
• [P1] Run the Phase 2 outcome benchmark and decide Madar’s supported product claim #673 — Run the Phase 2 outcome benchmark and decide Madar’s supported product claim.
• [P2] Run a Tier 3 public outcome study before broad superiority or efficiency claims #677 — Run a Tier 3 public outcome study before broad superiority or efficiency claims.

Execution note: #667 establishes the truthful development baseline. #668 and #669 qualify the product corridor and adapter contract. #670 and #671 are evidence-gated architecture/performance work. #672 follows the stable identities, adapters, and indexes. #673 is the Phase 2 decision gate. #677 remains blocked until the protected packaged release from #676 exists.

Phase 3 — Supported surface and release trust

Parent epic: #652

• [P1] Rationalize supported, advanced, and maintainer CLI/MCP surfaces #674 — Rationalize supported, advanced, and maintainer CLI/MCP surfaces.
• [P1] Establish a versioned compatibility, support, and deprecation policy #675 — Establish a versioned compatibility, support, and deprecation policy.
• [P1] Publish npm releases from exact protected commits with provenance and packaged host verification #676 — Publish npm releases from exact protected commits with provenance and packaged host verification.

Execution note: #674 → #675 → #676. The protected release workflow also depends on the product-claim decision in #673.

Phase 4 — Measured scale and constrained ecosystem

Parent epic: #653

• [P2] Qualify large-repository and monorepo partitioning with explicit resource envelopes #678 — Qualify large-repository and monorepo partitioning with explicit resource envelopes.
• [P2] Prove a constrained adapter API with two independently qualified non-core adapters #679 — Prove a constrained adapter API with two independently qualified non-core adapters.

Execution note: Phase 4 is deliberately locked behind the trust, outcome, compatibility, incremental-equivalence, and protected-release gates. #679 follows #678 and must not become a marketplace project.

How agents should execute issues

1. Give the agent one issue number, not an entire phase.
2. The issue body is the execution contract. The agent must obey its Depends on, scope, explicit non-goals, tests, acceptance criteria, rollback, and handoff sections.
3. One issue should normally produce one coherent PR. Epics do not produce implementation PRs.
4. An agent must stop when completing the requested issue and must not continue into a dependent issue automatically.
5. A PR can be ready for review while a repository-wide prerequisite is open, but it is not ready for merge until every stated merge gate passes.
6. Any discovered work outside the issue scope becomes a new linked issue; it must not be smuggled into the current diff.
7. Close a child issue only after its acceptance criteria pass on the protected branch/PR, not merely because code was written.
8. Update the corresponding checkbox in this epic and the phase epic after closure.

Global execution contract

Every child issue must follow these rules:

1. One coherent outcome per issue and normally one implementation PR per issue.
2. Do not start an issue until every Depends on issue is complete, unless the issue explicitly permits parallel characterization work.
3. Start with failing characterization or qualification evidence where the issue changes semantics.
4. Separate facts observed in the repository from design inference.
5. Do not mix unrelated cleanup, naming changes, framework expansion, or architectural refactoring into roadmap PRs.
6. Preserve deterministic output and explain every retrieval, Pack, graph, or artifact difference.
7. Do not update snapshots merely to accept unexplained behavior changes.
8. Do not describe a test suite, host integration, benchmark, or release as green when it did not complete successfully.
9. Do not publish a release from a partially completed graph-integrity migration.
10. Each PR must identify rollback behavior and any source regeneration required.

Global protected gates

Unless a child issue defines a stricter gate, merge requires:

• supported Node version and exact lockfile;
• npm ci;
• typecheck;
• build;
• focused tests for the affected subsystem;
• complete protected test suite;
• coverage gate where configured;
• packed-package parity;
• npm pack --dry-run or the repository's stronger package check;
• Registry validation;
• release verification;
• deterministic artifact/output checks where affected;
• exact-head protected CI.

Token, latency, or tool-call improvements count only when answer correctness and critical-fact completeness are non-inferior.

Six-month completion target

For supported TypeScript/Node patterns, Madar should be able to:

• retain every admitted semantic fact;
• preserve separate evidence occurrences and provenance;
• account durably for unresolved, rejected, conflicting, and invalid graph candidates;
• refuse ready when graph integrity or critical obligations are unproven;
• provide direct source evidence for critical claims;
• reconstruct qualified route/service/repository and producer/consumer paths with independently measured precision;
• work through a context-first default in supported agent hosts;
• demonstrate non-inferior or better agent outcomes in repeated, blinded evaluation;
• report indexing, context-building, agent, token, latency, and cost measurements separately;
• ship through a protected, reproducible publication process.

Not now

Do not create implementation work for these until this epic explicitly unlocks them:

• another architecture reset or replacement beta line;
• broad Rust/Java/PHP or deeper Python/Go expansion;
• hosted/cloud repository indexing or team synchronization;
• live distributed tracing;
• autonomous code editing or security verdicts;
• mandatory vector database or LLM-based query interpretation;
• Neo4j-first architecture;
• more MCP tools or new transports;
• public plugin marketplace;
• major new Wiki/Obsidian/federation/time-travel investment;
• long-term repository memory before invalidation is trustworthy;
• token-reduction headline optimization before outcome proof.

Closure criteria

Close this epic only when:

• every non-parked child issue is complete;
• the declared TypeScript/Node corridor has independent outcome evidence;
• no P0 trust defect remains open;
• the supported host matrix passes real packaged acceptance tests;
• the final release is produced from an exact protected commit with verifiable provenance;
• public claims are narrower than or equal to the collected evidence.

[mohanagy]

Cross-vendor orchestration protocol

Beta target

Target the Phase 0 child issues #654–#661 for:

v0.33.0-beta.1 — Trust Foundation

The orchestration lead must create this GitHub milestone if it does not exist and assign issues #654–#661 to it before implementation begins. The beta must not be published until all Phase 0 issues and protected gates are complete.

Recommended control plane

Use one Claude Code team-lead session as the human-facing orchestrator.

Connect the official Codex MCP server to Claude Code, then let the lead create three isolated worktrees and three teammates:

1. test-gate — owns [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 and delegates implementation/investigation to Codex through the Codex MCP tools.
2. qualification — owns [P0] Freeze the natural qualification corpus, independent rubrics, and stop rule #655 and performs the independent qualification-contract work directly with Claude.
3. graph-api — owns [P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 and delegates implementation to Codex through the Codex MCP tools.

Claude teammates use the shared team task list and mailbox for coordination. Codex sessions return their thread IDs/results to the owning Claude teammate, which may continue the Codex thread for corrections and validation. GitHub issues, comments, branches, draft PRs, and CI remain the durable source of truth.

Initial concurrency

#654  Codex-backed teammate  ─┐
#655  Claude teammate        ├─ run in parallel
#656  Codex-backed teammate  ─┘

Constraints:

• [P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 may be implemented and opened as a draft PR while [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 runs, but must not merge before [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 is complete.
• The graph sequence remains strict: #656 → #657 → #658 → #659.
• Each teammate owns one worktree, one branch, one issue, and normally one PR.
• No teammate may continue automatically into a dependent issue.
• No automatic merges or npm publication.
• The lead reviews scope, acceptance criteria, CI, dependencies, and issue/PR status before recommending any merge.
• Resource-sensitive full-suite experiments for [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 must not overlap with another local full-suite run.

Lead responsibilities

• verify gh, claude, and codex authentication/version;
• create/assign the beta milestone;
• create and clean isolated worktrees;
• fetch and enforce issue bodies as execution contracts;
• spawn/monitor teammates and Codex MCP threads;
• keep issue comments and draft PRs updated;
• classify blockers and out-of-scope discoveries into separate issues;
• stop at human review/merge gates;
• never broaden public claims beyond collected evidence.

Worker completion contract

A worker is complete only when it has:

• produced the issue-specific deliverables;
• run every permitted/required validation it can run honestly;
• opened or prepared a focused draft PR where code changed;
• posted exact results and blockers to the issue/PR;
• explicitly stated ready for review and ready for merge separately;
• stopped without claiming or starting the next issue.

[mohanagy]

Phase 0 orchestration session started — wave 1 (#654, #655, #656)

Preflight (recorded)

Item	Value
origin/main at session start	06b373a447acfce895412ac10eb4e5228c5df0b7
Base SHA for all wave-1 worktrees	06b373a447acfce895412ac10eb4e5228c5df0b7
Node	v22.22.3
npm	12.0.2
gh auth	authenticated as mohanagy
Claude Code	2.1.228
Codex CLI	codex-cli 0.147.0
Codex MCP server	official codex mcp-server, connected, session tools verified

The user's working checkout was not modified. Its local main was 6 commits behind origin/main; all worktrees were created from origin/main, not from stale local main.

06b373a44… is also the exact audited baseline named in #654 and #656.

Milestone

Created v0.33.0-beta.1 — Trust Foundation (milestone number 8). Issues #654, #655, #656, #657, #658, #659, #660, #661 assigned and each assignment verified.

Worktrees

Issue	Branch	Worktree	Base	State
#654	roadmap/654-vitest-gate	../madar-654	06b373a44…	clean
#655	roadmap/655-qualification-contract	../madar-655	06b373a44…	clean
#656	roadmap/656-plural-graph-apis	../madar-656	06b373a44…	clean

No pre-existing roadmap/* branch or target path collided, so no -v2 suffix was required. No existing worktree was reset or deleted.

Team

Teammate	Issue	Model	Codex-backed
lead	orchestration	Opus	—
test-gate	#654	Sonnet	yes
qualification	#655	Opus	no
graph-api	#656	Sonnet	yes

Codex model deviation from the recommended configuration

The protocol prefers gpt-5.3-codex with model_reasoning_effort = "xhigh". That model was tested first and is not available on this account:

400 invalid_request_error
The 'gpt-5.3-codex' model is not supported when using Codex with a ChatGPT account.

Codex work therefore uses the strongest model this account can reach, gpt-5.6-sol, with model_reasoning_effort = "xhigh", sandbox = workspace-write, and approval-policy = never scoped to the isolated issue worktree only. Verified working against ../madar-656 before any teammate was dispatched.

Concurrency control

test-gate owns all local resource-sensitive complete-suite experiments. graph-api is restricted to focused tests and must obtain lead approval before any competing complete-suite run, so that #654's contention evidence is not corrupted.

Constraints in force this session

• [P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 may reach ready for review while [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 is open, but cannot reach ready for merge.
• The graph sequence #656 → #657 → #658 → #659 is not compressed; [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657 is not started in this run.
• No merges, no auto-merge, no npm publication.

[mohanagy]

Phase 0 wave 1 complete — #654, #655, #656

Three draft PRs opened. Nothing merged. No auto-merge. No publication. #657 not started. The graph sequence #656 → #657 → #658 → #659 remains uncompressed.

Issue	Branch	Draft PR	Review state	Merge state
#654	roadmap/654-vitest-gate	#682	ready for review	not a resolution to #654 — partial fix only
#655	roadmap/655-qualification-contract	#681	ready for review	blocked by #654 + exact-head CI
#656	roadmap/656-plural-graph-apis	#680	ready for review	blocked by #654

#654 — did NOT close, acceptance criteria NOT met

This is the headline result and it is deliberately not dressed up.

Fixed: one real defect. stdio-server.test.ts's auto-refresh test relied on the production default poll interval, which is too slow under load to land inside its 10s budget. Corrected through the pre-existing autoRefreshStarter / startGraphAutoRefresh seams — no new seam was introduced, no assertion was weakened, and zero production files changed. Verified 303/303 across --maxWorkers=1/2/4, and 41/41 for the file alone.

Not fixed: the Failed to start forks worker symptom. It is an IPC handshake timeout (Timeout waiting for worker to respond), not EMFILE/ENOMEM — ulimit -n is 1048576. Across six complete-suite runs (three before the fix, three after), every run failed and the affected file set was effectively random each time, never repeating. compare-native-agent.test.ts 60s timeouts persist, matching the original baseline symptom.

Zero clean complete-suite runs were achieved, before or after. PR #682 therefore says Refs #654, not Closes #654.

Leading hypothesis: local shared-machine resource contention / worker-startup starvation. Two independent supports — an lsof snapshot during a failing run showed concurrent unrelated node processes from other worktrees, and the graph-api teammate reproduced the same symptom on a different branch with unrelated code at 21-file batch width while small batches stayed clean.

Orchestration confound, disclosed: this session itself ran three worktrees concurrently, so the orchestration's own parallelism is part of the local load that #654 was measuring. The hypothesis is not confirmed against the protected CI matrix, and dedicated non-shared runners are the clean test. That is the remaining evidence gap and the recommended next step.

#655 — contract frozen, with one honest limit

Ten deliverables shipped in a new self-contained docs/qualification/ v1.0.0, with a .github/scripts validator that mechanically enforces the benchmark-independence boundary (it fails when a qualification literal reaches production code).

The corpus pins two genuine external repositories at immutable SHAs — unkeyed/unkey @ 47e64533… and payloadcms/payload @ c6e79520… — deliberately chosen outside docs/benchmarks/suite/repos.json so Tier 2 does not inherit repositories that production heuristics or published receipts were shaped around.

The limit, stated plainly: Tier 1 is hermetic and self-authored; both natural repositories sit at pinned_no_truth and carry no independent truth; the sealed holdout is unsatisfied. The contract therefore produces no measurable evidence on natural code today. Every status is honestly labeled in corpus.json. Establishing natural-code truth is follow-up work.

Also declared rather than faked: hidden holdouts cannot be genuinely hidden in a single-author repository, truth ownership is recorded as independent_of_production_rule_author: false, and Tier 1 thresholds are pre-registered and uncalibrated — the first execution is a measurement, and a failure there is a product finding, not a licence to edit the contract.

#656 — behavior-preserving, differentially proven

Plural semantic APIs (factsBetween, relationsBetween, factEntries) and explicit topology APIs (endpointEntries, numberOfFacts, numberOfEndpointPairs, uniqueNeighborDegree) added; ~140 internal call sites across 26 files migrated; compatibility surface preserved and @deprecated-annotated.

Lead-verified mechanically: edgeAttributes( survives at exactly one site (the compatibility implementation); no positional selection anywhere; zero snapshot, fixture, or artifact files touched; storage internals (edgeMap, edgeKey(), addEdge()) unchanged.

Differential validation was measured, not inferred: two builds, 44 output files byte-identical except a single generated_at field, plus identical output from query, pack (×4), handoff, prompt, summary, explain, path, diff, and serve --stdio. Two gaps are named rather than skipped: time-travel's live git-comparison path and the paid-model benchmark commands.

The five scalar-projection helpers are documented deterministic total orders (order-independent folds, or explicit lexicographic tie-breaks) and will not degenerate into arbitrary selection under PR B multiplicity. Separately confirmed: uniqueNeighborDegree() is a character-identical copy of the old degree() body, so the substitution cannot shift self-loop handling or centrality inputs.

Cross-vendor process findings

• gpt-5.3-codex is unavailable on this account (400 invalid_request_error). Codex work used gpt-5.6-sol @ xhigh.
• The Codex MCP sandbox has no outbound network. npm ci failed with ENOTFOUND — the model reported the failure honestly rather than fabricating a result, and the owning teammate ran the install itself. Worth pre-empting in future runs.
• One Codex session aborted at 1800s returning no threadId ([P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656), so no codex-reply correction cycle was possible; the diff was verified post hoc from filesystem state and independently validated. Recorded as a genuine protocol deviation.

Issue candidates (not opened — awaiting approval)

1. P1 — receipt emitter gap: src/infrastructure/compare.ts emits no invalidation reason codes, no aggregatable flag, no adoption classification, and no separate indexing / context-build / agent cost accounts.
2. P2 — reclassify runtime-proof.json: grader input carrying per-repo expected symbols and paths, whose isolation from retrieval is asserted in methodology.md but not mechanically enforced.
3. P3 — sealed-holdout owner: needs a real second person and a schedule, not a code change.
4. P4 — natural-code independent truth for the two pinned Tier 2 repositories.

Recommended review order

#682 → #680 → #681. Review #682 first because it is the smallest and because its honest non-closure of #654 sets the merge posture for the other two. Merging #682 as a standalone flakiness improvement is reasonable; it must not be recorded as closing #654.

[mohanagy]

Amendment to the wave-1 report — #655 superseded

My previous comment described #655's corpus as pinning unkeyed/unkey and payloadcms/payload at pinned_no_truth, with the limitation that the contract produced no measurable evidence on natural code. That description is now obsolete. #655 was reworked in commit d49b86cb and the limitation is resolved rather than merely documented.

#655 as it now stands

Both self-authored fixtures were deleted. corpus.json#/proxy_targets is empty. The corpus is natural repositories only:

Target	Source	Coupling
hono	honojs/hono @ 26de7313… (MIT)	declared_framework_adapter
unstorage	unjs/unstorage @ e6be6135… (MIT)	none_found
hono-seeded-compose	same commit + one-line patch to src/compose.ts	—
hono-seeded-error-disclosure	same commit + one-line patch to src/hono-base.ts	—
sealed-holdout-a	—	still unsatisfied

All six truth files were rewritten from the pinned upstream sources, with Madar never run against any target. Each target records a cited_blobs map (path → git blob SHA) so citation checking stays offline and deterministic at pull-request time, while npm run qualify:validate -- --verify-corpus proves the pins over the network on demand. That verification passed: 4 targets, 25/25 blob digests matched, both patches apply cleanly.

Seeded defects now live in real framework internals — the middleware re-entrancy guard and the default error handler — rather than in a synthetic workspace.

Disclosed coupling — the most important finding in this PR

Madar ships src/pipeline/spi/framework-hono.ts, and src/runtime/retrieve.ts carries Hono-aware classification (explicit-Hono token check at line 4449; hono_route / hono_middleware at 4854–4857). A hono result therefore partly measures Madar's own declared adapter.

This is declared corridor support rather than a repository-specific special case, so it is not a #660 finding. It is disclosed per target as production_coupling: declared_framework_adapter, every hono prompt is test-enforced to avoid naming the framework, and unstorage is retained at none_found as an uncoupled control.

The benchmark-independence guard was adjusted accordingly: bare target ids are deliberately not forbidden, because a target id may legitimately equal a framework Madar declares generic support for, and banning the word would conflate a declared adapter with a benchmark special case. The guard now bans repository URLs, refs, task ids, prompt strings, negative-trust probe prompts, and a curated per-target symbol list of real repository internals.

Correction to my own earlier characterization

In directing this work I asserted that docs/benchmarks/suite/repos.json contained no entry pinning a repository URL and commit SHA. That was wrong, and it was never published here — I record it only because it shaped the instruction given to the worker.

Measured at the baseline, repos.json has 11 rows: five in-repo proxies keyed by path (ts-small, nestjs-mid, ts-monorepo-large, python-service, go-service) and six git-backed rows that do pin URL and immutable SHA (documenso, formbricks, dub, twenty, cal-diy, novu). The worker verified this, declined to record my stronger claim, and published the accurate version in evidence-categories.md.

The direction was still correct for a narrower reason: the five proxy rows are the ones backing the checked-in deterministic fixture bundles, so the corpus was substantially proxy-based.

Unchanged

Validation passed: typecheck, build, qualify:validate, qualify:validate --verify-corpus, registry:validate, release:verify, npm pack --dry-run (0 qualification entries), 101 focused tests. Not run: the complete Vitest suite (owned by #654) and verify:pack-parity.

Still honestly declared: the sealed holdout remains unsatisfied pending a real second person; the receipt emitter still lacks invalidation reason codes, an aggregatable flag, adoption classification, and separate indexing / context-build cost accounts; Tier 1 thresholds remain pre-registered and uncalibrated.

Verdicts unchanged — ready for review: yes (pending one one-line fix: a _note string in forbidden_target_symbols is folded into the literal list by Object.values(...).flat()). Ready for merge: no — blocked by #654 and exact-head protected CI.

A fifth issue candidate is added: Tier 1 now depends on upstream repository availability, so a durable mirror would remove that dependency.

[mohanagy]

Wave 1 closed — final state

The one-line fix noted as outstanding in my amendment is done. All three teammates have stood down.

Issue	Branch head	Draft PR	Review	Merge
#654	db7300ce	#682	ready	not a resolution to #654 — partial fix only
#655	765802fe	#681	ready	blocked by #654 + exact-head CI
#656	d9904462	#680	ready	blocked by #654

Nothing merged. No auto-merge enabled. No package published. #657 not started. The graph sequence #656 → #657 → #658 → #659 remains uncompressed.

#655 finished on four commits: initial contract, corpus rebuilt on natural pinned repositories, the no-measured-evidence limitation statement, and a fix to the forbidden-literal scan. That last one removed a latent trap where a prose _note string was folded into the literal list by Object.values(...).flat(); the correction skips _-prefixed keys and additionally fails loudly on a non-array value, a non-identifier entry, or a key that does not name a real corpus target — closing the class rather than the instance. The guard was negative-tested by planting a real target symbol in a production file and confirming the check fired.

Recommended review order

#682 → #680 → #681. Review #682 first: it is the smallest, and its honest non-closure of #654 sets the merge posture for the other two. Merging #682 as a standalone flakiness improvement is reasonable — it must not be recorded as closing #654.

Required before any Phase 0 merge

#654 remains open on its own evidence. The next step is protected-CI-matrix evidence from dedicated, non-shared runners, to establish whether the Failed to start forks worker handshake timeout is exclusively a local shared-machine artifact. This session's own three-worktree parallelism is a disclosed confound in the local measurements and cannot be resolved locally.

Issue candidates awaiting maintainer decision

1. runtime-proof.json retrieval/grader boundary asserted in methodology.md but mechanically unenforced — bears on [P0] Remove qualification-repository tuning from production retrieval and claims #660. Sharpened by contrast: qualify:validate does enforce its equivalent boundary in CI.
2. Receipt emitter in src/infrastructure/compare.ts lacks invalidation reason codes, an aggregatable flag, adoption classification, and separate indexing / context-build cost accounts.
3. Sealed holdout requires a real second person and a schedule.
4. Durable corpus mirror — Tier 1 now depends on honojs/hono and unjs/unstorage remaining reachable; commits are immutable but availability is not.

A further orchestration session is required for #654. Wave 2 (#657 onward) must not begin until #654's gate question is settled.

[mohanagy]

Independent maintainer review — Wave 1 is not yet ready as reported

I reviewed the three remote PR heads, their patches, and their exact-head GitHub Actions results.

#682 — standalone improvement conditionally approved

• Remote head: af16e41b14a4e63f2dc6b92025c520effc79ecfc.
• Scope is test-only (.gitignore, tests/unit/stdio-server.test.ts).
• The six-job protected CI matrix completed successfully once.
• It is acceptable as a standalone flakiness/diagnostic improvement after the recorded head mismatch is resolved.
• It must remain Refs #654, must not close [P0] Stabilize the complete Vitest suite and protected CI merge gate #654, and must not be represented as fixing the broader forks-worker handshake symptom.

The previous Wave-1 comment reports #682 head db7300ce; that commit does not exist in the remote repository. Reconcile/push the intended local head or correct the record before merge.

#680 — changes required

Two Windows jobs are red because the new source-boundary test compares a forward-slash path against Windows relative() output containing backslashes.

Two semantic-multiplicity defects were also found:

1. src/pipeline/cluster.ts::edgeWeight() sums weights across factsBetween(). Once [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657 returns parallel facts, Louvain topology weight will inflate with fact multiplicity, violating the ADR's unique-endpoint-pair topology rule. Use an explicit non-additive projection, directionally maximum valid positive weight with default 1, and characterize it.
2. src/infrastructure/neo4j.ts iterates factEntries() but still MERGEs only by endpoints and relation type, so same-relation/different-discriminator facts would collapse externally. Either establish a safe temporary fact projection or explicitly guard/defer the unsupported export behavior to [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657; do not call it multigraph-safe.

Review comments were posted on #680. It is not ready for merge, independently of #654.

#681 — changes required

The exact-head CI matrix is red on both Windows Node 20 and Node 22.

• raw-byte freeze digests differ after CRLF checkout conversion;
• multiline prose assertions are LF-specific.

Add an explicit LF policy (preferably .gitattributes for docs/qualification/**) and make prose assertions line-ending agnostic. Re-run and require all six jobs to pass. Review comments were posted on #681.

Issue-candidate decisions

1. The unenforced runtime-proof.json grader/retrieval boundary is approved as a mandatory amendment to existing [P0] Remove qualification-repository tuning from production retrieval and claims #660, not a duplicate issue. The detailed acceptance criteria were added to [P0] Remove qualification-repository tuning from production retrieval and claims #660.
2. Benchmark receipt emission gap approved and opened as [P1] Emit validity-aware benchmark receipts with attributable adoption and separated costs #683.
3. Independent sealed-holdout owner approved and opened as [Human gate] Recruit and seal an independent qualification holdout owner #684. This human gate blocks broad generalization/[P2] Run a Tier 3 public outcome study before broad superiority or efficiency claims #677, not current Phase 0 regression work.
4. Durable corpus mirror approved and opened as [P2] Mirror pinned qualification corpora for availability-independent reproduction #685. This is supporting/public-reproducibility work and does not block the current graph sequence.

Authorized next wave

A follow-up orchestration session is authorized, but #657 must not start. The next session should:

1. reconcile the test: fix flaky stdio auto-refresh polling timeout (partial evidence for #654) #682 local/remote head and run repeated dedicated protected-CI attempts on the final exact head;
2. correct feat(graph): PR A — plural relationship queries and explicit topology APIs (#656) #680's Windows path test, topology-weight projection, and Neo4j multiplicity limitation;
3. correct feat(qualification): freeze the independent qualification contract (#655) #681's Windows line-ending/freeze behavior;
4. update PR evidence and this epic;
5. stop before merge or [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657.

The graph sequence remains uncompressed.

[mohanagy]

Record correction and remediation wave

The independent maintainer review is accepted in full. Two corrections to my Wave-1 report, both mine.

1. #682's recorded head was wrong — af16e41b, not db7300ce

Resolved definitively. This was neither a typo nor an unpushed commit.

The reflog in the #654 worktree shows db7300ce was created at 09:54:41 and amended into af16e41b at 09:54:56, fifteen seconds later. git diff db7300ce af16e41b is empty — the trees are identical. Local worktree, local branch, and remote branch are all af16e41b, and nothing is unpushed.

db7300ce was a pre-amend commit that never reached the remote. My report captured it in the window between the commit and the amend. No content is missing, and nothing needs pushing. The authoritative head for #682 is:

af16e41b14a4e63f2dc6b92025c520effc79ecfc

2. My "ready for review" verdicts on #680 and #681 were not supported

I verified diffs, scope boundaries, differential outputs, and focused test results, and I audited each PR against its issue contract. I did not check exact-head CI before declaring readiness. Both PRs are red on Windows Node 20 and Node 22 and have been since they were pushed:

PR	head	ubuntu 20/22	macos 20/22	windows 20/22
#682	af16e41b	pass	pass	pass
#681	765802fe	pass	pass	fail
#680	d9904462	pass	pass	fail

A readiness verdict that omits the protected gate is not a readiness verdict. The two red PRs should have been reported as changes required regardless of their #654 dependency.

I also missed both multiplicity defects on #680. Worth recording precisely why, because it is a specific and repeatable blind spot: I audited the five scalar projection helpers, judged them deterministic and multigraph-safe, and directed the worker to re-characterize them as such — a conclusion I still hold. But I treated that as covering the projection question and never audited cluster.ts::edgeWeight(), which is a sixth site and is additive. Verifying a named set and then generalizing to the category is the same error that produced my repos.json mistake earlier in this wave.

Remediation dispatched

Three isolated tasks, one owner each, running in parallel:

• A — [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 / test: fix flaky stdio auto-refresh polling timeout (partial evidence for #654) #682. Head record corrected to af16e41b; no push required. One six-job matrix has already passed on that head; two further complete sequential attempts to run, each counted only if all six jobs complete. Then a per-criterion determination of whether [P0] Stabilize the complete Vitest suite and protected CI merge gate #654's documented-local-resource-distinction alternative is genuinely satisfied.
• B — [P0] Freeze the natural qualification corpus, independent rubrics, and stop rule #655 / feat(qualification): freeze the independent qualification contract (#655) #681. Explicit LF policy via .gitattributes for docs/qualification/**; prose assertions normalized to test semantic content. The raw-byte freeze contract is preserved and freeze.json will not be regenerated to absorb CRLF conversion.
• C — [P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 / feat(graph): PR A — plural relationship queries and explicit topology APIs (#656) #680. Windows path-separator fix; edgeWeight() replaced with a deterministic non-additive projection (directionally maximum valid positive weight, default 1) plus a characterization test proving multiplicity cannot inflate endpoint topology weight; and a Neo4j audit that will either establish a safe temporary projection or explicitly guard and defer to [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657 — the exporter will not be presented as fact-preserving either way.

Local heavy Vitest runs are serialized against Task A; remote Actions attempts run concurrently.

Unchanged: no merges, no auto-merge, nothing published, #657 not started.

[mohanagy]

Remediation wave complete — all three PRs green on their exact heads

Every PR now passes the complete six-job protected matrix at its current head. #654 still cannot close, and a new blocker was found while proving it.

PR / issue	Final head	Six-job CI	Review	Merge
#682 / #654	af16e41b	6/6, 5/6, 6/6 across three attempts	ready	standalone only — does not resolve #654
#681 / #655	88c4d526	6/6	ready	blocked by #654
#680 / #656	57b1e453	6/6	ready	blocked by #654

#682 — three attempts, and a new flake

Attempts on the exact head af16e41b: 6/6 → 5/6 → 6/6. Attempt 2's failure was validate (ubuntu-latest, Node 20), and it is not the symptom #654 is chasing.

It is a previously undiscovered flaky test: tests/unit/watch.test.ts:478, asserting the idle-reconciliation backoff reaches the 80 ms rung inside a fixed await delay(190) while also satisfying reconciliations.length <= 5. Constrained from both sides, so it cannot be stabilised by widening the wall clock. Unrelated to #682's diff and to worker-start starvation.

The forks-worker evidence is genuinely strong: 0 of 3 attempts — 18 job-runs — reproduced Failed to start forks worker, against 6 of 6 local full-suite runs. Dedicated runners without concurrent load did not exhibit it once. That substantially supports the local-shared-machine hypothesis.

But that is one criterion. Criterion 3 fails on a plain reading of "repeatedly" at 2 of 3, and criterion 5 is now unmet twice over — the local symptom remains a hypothesis, and the watch.test.ts flake is undiagnosed. Criterion 8 (npm 12.0.2 vs the issue's 12.0.1) is still unresolved. #654 stays open.

A pattern that may reframe #654

Three failures this wave are one family: the stdio-server.test.ts flake that was fixed, the watch.test.ts flake just found, and the polling-interval sensitivity behind both — wall-clock assertions over timing the test does not control, passing on fast unloaded machines and failing under load. This suggests the suite's unreliability may be substantially a timing-assumption problem rather than a worker-scheduling one. That would change #654's leading hypothesis and is worth deciding on before more contention analysis.

A second pattern — gates narrower than the guarantees they advertise

Validate qualification contract was gated to ubuntu-latest && Node 22, so the byte-exact freeze was verified on one lane of six; Windows tests failed on digests while the validator that checks those digests never ran there. Now ungated: skipped → success on both Windows lanes is the direct evidence.

A follow-up audit, classifying by reading each script rather than inferring from names, found two more platform-sensitive single-lane gates. release:verify, registry:validate, npm audit, and npm pack --dry-run were confirmed genuinely platform-independent.

#681 and #680

#681 — LF pinned via .gitattributes (docs/qualification/** text eol=lf, plus patches/*.patch -text); prose assertions normalized to semantic content while the freeze digest deliberately still reads raw bytes. freeze.json was not regenerated and no frozen content changed — the guarantee was pinned, not loosened. Verified by simulating a Windows checkout (git clone -c core.autocrlf=true) with a live-simulation control and a negative test confirming the digest and CRLF checks still fire.

#680 — Windows path portability fixed via relativePosixPath(); cluster.ts::edgeWeight changed from an additive fold to a non-additive Math.max projection (strongest valid positive weight, default 1) with five characterization tests proving [2,5,3] → 5, not 10; Neo4j multiplicity explicitly deferred, not solved, behind Neo4jUnsupportedFactMultiplicityError — inert today, loud the moment #657 lands. Differential validation was re-run from scratch post-fix, not assumed: 44-file generate tree plus ten CLI surfaces, byte-identical.

New issue candidates

1. tests/unit/watch.test.ts idle-backoff flake — CI-reproduced, undiagnosed, both-sided timing constraint. Blocks [P0] Stabilize the complete Vitest suite and protected CI merge gate #654's criterion 5.
2. verify:pack-parity gated to ubuntu/22 while carrying Windows-specific path handling that therefore never executes — code anticipating a platform that never tests it.
3. Eval regression (generate over examples/demo-repo) gated to ubuntu/22, though graph generation is the most separator-sensitive behaviour in the repository.

Required precondition for #657

Both the worker and I independently audited the five scalar projection helpers, judged them correct, and then treated the projection category as settled — missing cluster.ts::edgeWeight, a sixth additive site. A fresh factsBetween( / relationsBetween( sweep must be completed before #657 begins. A spot-checked inventory that proved incomplete once must not be inherited by the next slice.

Recommended merge order

#682 → #681 → #680, all after the #654 decision. #682 is mergeable on its own merits as a flakiness/diagnostic improvement and must stay Refs #654. #681 before #680 because it is self-contained, while #680 carries the graph-sequence dependency into #657.

Nothing merged. No auto-merge. Nothing published. #657 not started.

[mohanagy]

Roadmap update — PR #682 merged (test-only); everything else unchanged

PR #682 was squash-merged as a standalone, test-only flakiness and diagnostic fix.

Item	Value
Squash commit on main	3371ada8425efa7f8cabdac781fa227feaea7a6a
PR head merged	af16e41b14a4e63f2dc6b92025c520effc79ecfc
Scope	.gitignore, tests/unit/stdio-server.test.ts — no production source
Exact-head CI	6/6 green

State after the merge

• [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 remains OPEN. Acceptance criteria are unmet. The merge briefly auto-closed it; it was reopened immediately. Cause: the squash commit body contained the phrase "does NOT resolve [P0] Stabilize the complete Vitest suite and protected CI merge gate #654", and GitHub's closing-keyword parser matches resolve #654 without interpreting negation. PR test: fix flaky stdio auto-refresh polling timeout (partial evidence for #654) #682's own body was correct (Refs #654 only). Recorded in detail on [P0] Stabilize the complete Vitest suite and protected CI merge gate #654.
• PR feat(qualification): freeze the independent qualification contract (#655) #681 remains unmerged (draft, 88c4d526, 6/6 green).
• PR feat(graph): PR A — plural relationship queries and explicit topology APIs (#656) #680 remains unmerged (draft, 57b1e453, 6/6 green).
• [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657 has not started.
• No package or release was published. No auto-merge was enabled.
• The graph sequence remains uncompressed: #656 → #657 → #658 → #659.

#654, #655, and #656 are not complete and are not marked as such.

Recommended direction for the next work under #654

Focus on deterministic timing and scheduling assumptions, rather than continuing general worker-contention investigation without new dedicated-runner evidence.

The contention question has largely been answered for the forks-worker class: 0 reproductions across 18 dedicated job executions versus 6 of 6 on the shared local machine. Further local contention analysis is unlikely to yield more, and the confounded local environment cannot settle it.

What is still open is a different and now better-evidenced problem — uncontrolled wall-clock assertions. Three failures this wave belong to that family, including the one merged here and tests/unit/watch.test.ts:478, which must reach an 80 ms backoff rung inside a fixed await delay(190) while also satisfying reconciliations.length <= 5. Constrained from both sides, it cannot be stabilised by widening a timeout, and it broke one of three protected-CI attempts. That is the concrete blocker standing between the suite and a trustworthy merge gate.

[mohanagy]

Branch and release-channel policy (durable)

The roadmap no longer integrates directly into main.

	Stable	Prerelease
Git branch	main	next
npm dist-tag	latest	next
Version form	0.33.0	0.33.0-beta.1

• Roadmap PRs target next. Issue branches are created from next.
• main is stable-only. No roadmap feature PRs land there directly.
• next is the prerelease integration branch. The existing next branch is used; no second long-lived develop/development branch is created.
• Stable releases are promoted through a reviewed next → main PR, then tagged on main and published to npm latest.
• Stable hotfixes land on main and are forward-ported main → next.
• npm prereleases use the next dist-tag; npm stable releases use latest.

Current status under this policy

• PR test: fix flaky stdio auto-refresh polling timeout (partial evidence for #654) #682 remains a completed stable-line, test-only correction on main (3371ada8). It is not revisited.
• [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 remains open and continues to block roadmap PR merges.
• PRs feat(qualification): freeze the independent qualification contract (#655) #681 and feat(graph): PR A — plural relationship queries and explicit topology APIs (#656) #680 are draft, unmerged, and are being retargeted to next.
• [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657 has not started.
• The four-slice graph sequence remains uncompressed: #656 → #657 → #658 → #659.
• No release is permitted between incomplete graph slices. Publishing after only [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657 or [P0][Graph PR C] Account for every normalized graph candidate and retain unresolved facts #658 would ship artifact, integrity, and answerability behavior in an intentionally partial migration state.
• Release engineering for the first beta is tracked in [P0 Release] Establish the protected npm next prerelease channel for v0.33.0-beta.1 #687.

Nothing here marks #654, #655, #656, Phase 0, or the v0.33.0-beta.1 milestone complete. None of them are complete.

Open item blocking the transition

Synchronizing next with main is currently blocked by a repository-policy conflict, not by code. next had zero unique commits and is a strict ancestor of main, so the correct operation is a fast-forward. However:

• a direct fast-forward push is rejected by the protect-next-prerelease ruleset (pull_request required);
• sync PR chore: synchronize next with the current stable baseline #686 is open, green on all six lanes, and MERGEABLE/CLEAN;
• but the ruleset sets allowed_merge_methods: ["squash"], and GitHub rejects a merge commit with Merge commits are not allowed on this repository.

Squashing six historical main commits into one new next commit would give next a SHA that main never receives, permanently breaking shared ancestry between the two channels and causing phantom divergence on every future promotion. That is deliberately not being done. A maintainer decision on merge-method policy for next is required — see the sync PR for options.

[mohanagy]

Prerelease channel infrastructure merged into next

PR #688 squash-merged into next as 2e8a3737956fb6b15a18d682c04dd6a2a5a2e470. Six-job matrix green on that commit.

main is unchanged at 3371ada8425efa7f8cabdac781fa227feaea7a6a. Only next advanced.

Release controls now configured

Control	State
npm-next GitHub environment	created; required reviewer mohanagy; can_admins_bypass: false; three type: tag deployment policies; no secrets or variables
protect-madar-prerelease-tags ruleset	active; target: tag; restricts creation, update, deletion on the three approved prerelease patterns; admin bypass so the maintainer is not locked out
npm Trusted Publishing	bound to publish-next.yml + npm-next, createPackage only, no token
protect-next-prerelease	still active

Constraint discovered during configuration: npm permits exactly one trusted publisher per package. A pre-existing publisher bound to release.yml with no environment was revoked and replaced with the environment-protected binding, on explicit maintainer authorization. Stable latest publication under #676 must therefore solve stable-versus-prerelease coexistence deliberately rather than adding a second binding.

Nothing was released

No package version, no Git tag, no GitHub release, no dist-tag change, no MCP Registry publication. npm latest remains 0.32.1; no next dist-tag exists.

Roadmap state

• [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 remains open. It continues to block roadmap PR merges.
• PR feat(qualification): freeze the independent qualification contract (#655) #681 — open, draft, unmerged, targeting next.
• PR feat(graph): PR A — plural relationship queries and explicit topology APIs (#656) #680 — open, draft, unmerged, targeting next.
• [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657 has not started.
• [P0 Release] Establish the protected npm next prerelease channel for v0.33.0-beta.1 #687 remains open, tracking the first real prerelease as the outstanding evidence for three acceptance criteria that can only be satisfied by an actual publication.

Release prohibition still in force

The graph sequence remains uncompressed:

#656 → #657 → #658 → #659

The approved architecture separates these four slices deliberately, and publication between partial slices is prohibited. Shipping after only #657 or #658 would release artifact, integrity, and answerability behavior in an intentionally incomplete migration state.

Phase 0 is not complete and is not marked complete.