[Epic] Phase 0 — Stabilize trust foundations and qualification gates

[mohanagy]

Parent: #648

Outcome

Create a trustworthy engineering foundation before adding new product capabilities.

Phase 0 must eliminate known silent semantic loss, establish reliable protected test gates, remove qualification-repository contamination from production behavior, and create a small independent evaluator that can stop unsafe changes.

Why this phase comes first

At v0.32.1:

• distinct graph relationships can overwrite each other;
• dangling graph candidates can disappear without a durable terminal record;
• production ranking and claim generation contain exact status-page qualification knowledge;
• the broad local test suite has exhibited worker-start and timeout failures under the audited environment;
• the public production benchmark has no valid Native-vs-Madar comparison.

Building ranking, framework, indexing, or host features on this base would make an unqualified system more complex without making it more trustworthy.

Ordered child issues

Immediate parallel starters

• [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.

#654 blocks every roadmap merge until the complete suite is reliable. #655 establishes the independent evaluation contract used by later semantic and product gates.

Strict graph-integrity sequence

• [P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 — PR A: introduce plural relationship queries and explicit topology APIs.
• [P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2 #657 — PR B: add deterministic semantic multigraph storage and artifact v2.
• [P0][Graph PR C] Account for every normalized graph candidate and retain unresolved facts #658 — PR C: account for every normalized graph candidate and retain unresolved facts.
• [P0][Graph PR D] Cap answerability from graph-integrity state #659 — PR D: cap answerability from graph-integrity state.

The implementation order is strictly:

#656 → #657 → #658 → #659

#656 may be implemented while #654 is investigated, but no graph PR may merge until #654 is resolved and all stated gates pass. Agents must stop after their assigned PR slice.

Qualification independence and Tier 1 gate

• [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.

#660 depends on the frozen qualification contract and graph answerability foundation. #661 closes Phase 0 by turning the independent truth, graph invariants, false-readiness cases, and benchmark-independence rules into a protected pull-request gate.

Dependency summary

#654 ───────────────────────────────┐
#655 ───────────────┐               │
                    │               │
#656 → #657 → #658 → #659 → #660 → #661
                    │
                    └── every merge also requires #654

Characterization/evaluator work may run in parallel where it does not modify production semantics. The graph storage and answerability sequence itself is not parallelizable.

Non-negotiable architecture decisions

• The canonical relationship is a deterministic semantic fact.
• A fact has one or more separately identified evidence occurrences.
• Topology operates on unique endpoint pairs.
• Semantic queries operate on facts.
• Evidence/provenance queries operate on occurrences.
• Missing, unresolved, rejected, or conflicting candidates remain durably accounted for outside traversable topology.
• No internal caller may select an arbitrary fact from a parallel set.
• Artifact v2 must be impossible for v0.32.1 to silently down-read.
• Evidence occurrences must not multiply topology, centrality, communities, bridges, or traversal steps.

Phase-wide non-goals

• Retrieval redesign or new ranking model.
• compileContext architecture work.
• SPI/legacy consolidation.
• Incremental indexing.
• MCP profile/default changes.
• New frameworks or languages.
• Broad CLI cleanup.
• New product claims.
• Publishing a release while the four graph-integrity slices are incomplete.

Phase exit criteria

Phase 0 is complete only when:

• the full protected suite completes reliably on supported Node/OS lanes;
• every valid fact admitted at the graph boundary survives or follows a documented merge policy;
• no normalized graph candidate disappears without a terminal state;
• parallel facts round-trip deterministically;
• old artifact compatibility and old-reader rejection are proven;
• invalid, incompatible, or unaccounted graph state cannot produce ready;
• no qualification-repository path, symbol, phrase, or equivalent special rule remains in production retrieval/context logic without an approved generic justification;
• Tier 1 independent tests cover graph preservation, false readiness, critical retrieval facts, Pack compatibility, and forbidden benchmark knowledge;
• build, typecheck, package parity, Registry validation, release verification, and exact-head protected CI pass.

Completion rule

Do not close this phase because implementation PRs merely exist. Close it only after every linked child issue is complete, every checkbox above is updated, and the complete Phase 0 protected gate is green.

[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.

[mohanagy]

Phase 0 test-gate decomposition

The remaining #654 work is now tracked through two parallel, non-overlapping P0 issues:

• [P0] Replace uncontrolled wall-clock assertions in watch and refresh tests with deterministic scheduling #689 — deterministic watcher/refresh/backoff timing tests.
• [P0] Make ordinary Vitest commands fail on absorbed worker-start failures #690 — authoritative guarded Vitest commands that fail on absorbed worker-start signatures.

Both target next and block #654 completion. After both land, #654 still requires final repeated protected qualification before #681/#680 may merge or #657 may begin.

[mohanagy]

#654's two child issues now have reviewed PRs awaiting maintainer decision

Both non-overlapping children of #654 are implemented, reviewed, and stable. Neither is merged.

Child	PR	Head	Six-lane CI	Raw signatures (per lane)	CodeRabbit
#689 — deterministic watcher timing	#692	82ab558c	green	0 / 0	1 × P2, fixed
#690 — guarded ordinary Vitest commands	#691	0995b3cf	green	0 / 0	1 × P2, fixed

Raw-log counts were re-derived at every head rather than carried forward, each time with an injected-sample control proving the search was live and the logs readable. Job conclusions were never treated as evidence on their own — that distinction is what #690 exists to enforce.

What each PR establishes

#689 proved the failing contract was contradictory, not merely tight: the 80 ms rung becomes unreachable at roughly 130 ms of reconciliation cost, while benign filesystem activity pushes the reconciliation count past its ceiling in the same window. No timeout change could satisfy both. The fix extracts the existing inline backoff rule into a pure function — expression-identical, so watcher pacing is unchanged — and replaces the brittle assertions with an event barrier plus a per-transition oracle that validates every emitted interval against the policy, including the resets that noise correctly triggers.

#690 makes npm run test:run and npm run test:coverage fail on an absorbed forks-worker start failure even when Vitest exits zero with a green summary, through one canonical cross-platform runner that imports its signature list from the scanner merged in #688 rather than duplicating it.

Two findings worth recording beyond these PRs

The Windows lane earned its place. Twice it caught a defect that inspection and local runs did not, and both times the production code was correct while a test carried a POSIX-only assumption — first a signal-name assertion, then an observable-delivery count. On Windows child.kill() terminates via TerminateProcess, so neither has an observable equivalent.

New issue candidate — package API surface. package.json has no exports map and declaration: true is set, so every symbol in every compiled module is deep-importable by consumers; dist/src/infrastructure/watch.js and its .d.ts both ship. This is pre-existing and module-wide, not introduced by #689, which is why it was scoped out of that PR rather than absorbed. Adding an exports map is a package-compatibility change that could break existing deep importers and needs its own analysis.

Remaining sequence

Merge order is deliberately not parallel: #690 first, then #689 rebased onto the updated next and revalidated through the guarded commands — so #690's runner becomes the gate its sibling is measured by. #689 is ready for review but cannot be called ready for merge until that revalidation passes.

Final closure qualification for #654 has not begun. #657 has not started, and the graph sequence #656 → #657 → #658 → #659 remains uncompressed. PRs #681 and #680 remain open, draft, and unmerged. No package, tag, GitHub release, or npm dist-tag changed; main is unchanged.

Phase 0 is not complete. #654 remains open.

[mohanagy]

#690 complete and merged; #689 rebased and revalidated. Parent stays open.

#691 merged into next as 19c0cf8aca2a8888954304e3516b4a2c3d00dd25. main unchanged at 3371ada8. Post-merge CI on next: six lanes green, raw logs 0/0, guarded runner present in all 12 job logs. #690 is closed as completed, with every acceptance criterion mapped to evidence.

#692 rebased onto the merged next — clean, no conflicts, semantic patch byte-identical, new head df5df05c. Six lanes green with guarded = 2 per lane, confirming both test:run and test:coverage ran through the newly merged wrapper. Raw logs 0/0, control-verified.

The guard caught the symptom in the wild

The local guarded runs on the rebased branch failed, and that is the headline for this issue rather than a problem with the pull request:

npm run test:run       → EXIT=1, scan FAILED, log retained
npm run test:coverage  → EXIT=1, scan FAILED, log retained

The retained log contains 13 Failed to start forks worker and 13 Timeout waiting for worker to respond occurrences across 13 unrelated files. Before #690 merged, this run would have been reported as an ordinary Vitest result with those failures buried in the log. The guard refused, reported the child failure and the signature as independent causes, and retained the diagnostic.

This is the first real-world detection, on the exact class of failure this issue exists to eliminate. It also re-confirms the local/dedicated-runner distinction with the detector active: the identical commit is 0/0 clean across all six CI lanes while the contended host produced 13 occurrences.

The failure is environmental, not caused by #689: zero of that branch's own tests failed, watch.test.ts absorbed a worker-start failure and still passed, and the four failing files were compare-native-agent (the long-standing offender here), release-hygiene, release-pipeline, and run-guarded-vitest — none touched by the branch. The host carried well over a hundred concurrent Node processes.

Remaining criteria for this issue

• Root cause of local worker-start starvation is still unproven. [P0] Make ordinary Vitest commands fail on absorbed worker-start failures #690 detects the symptom; it does not explain it. The contention correlation is now very strong — 13 occurrences under heavy local load, 0 across six isolated CI lanes on the same commit — but correlation under uncontrolled load is not a mechanism.
• [P0] Replace uncontrolled wall-clock assertions in watch and refresh tests with deterministic scheduling #689 is not merged. It is ready for review at df5df05c and qualified through the guarded contract in CI, but its local complete-suite evidence is inconclusive on a contended host.
• A clean-host complete-suite run is still owed, or an explicit maintainer decision to accept the six clean CI lanes as sufficient.
• The separately scoped package exports-map candidate remains open and deliberately unaddressed.

Nothing was published: no tag, no GitHub release, no npm dist-tag change. latest remains 0.32.1 and no next dist-tag exists. PRs #681 and #680 remain open, draft and unmerged. #657 has not started.

#654 remains open.

[mohanagy]

Phase 0 qualification update: issue #695 has been added for the Windows Node 22 workspace.test.ts timeout found in protected matrix attempt 3. It is a separate fixed wall-clock integration-test failure with zero canonical worker signatures.

The live #693 macOS 26 ARM64 run remains useful for its host-boundary question, but #654 cannot complete until #695 is resolved and three clean exact-commit six-lane matrices exist. PRs #681 and #680 remain unmerged, and #657 remains unstarted.

[mohanagy]

Phase 0 test-gate stream complete — protected complete-suite merge gate established

Merged next : 6b6b3d8459ace1c26cc7d05abb27dc8cf3f72c08
main        : 3371ada8425efa7f8cabdac781fa227feaea7a6a (unchanged)

#654 is complete. The protected full-suite merge gate is established on supported isolated environments — protected CI runners and freshly provisioned same-OS/architecture VMs. Three consecutive exact-commit six-lane matrices on the merged next commit (31748654971, 31749252628, 31749780064) returned 18/18 green lanes with zero canonical worker-start and handshake signatures, every lane's raw log inspected and every positive control passing.

Closed in this stream:

Issue	Correction	PR
#654	parent — protected complete-suite merge gate	—
#693	qualification boundary and fresh-VM evidence	#694 (diagnostics-only, closed unmerged)
#695	Windows worktree aggregate timeout → phase-aware assertions	#696
#690	guarded commands, absorbed worker errors made authoritative	#691
#689	deterministic watcher/backoff timing	#692

The developer workstation remains unsuitable for qualification. It reproducibly emits worker-start signatures across four orders of magnitude of system load, including at idle, and the exact mechanism is unknown. The CPU-contention hypothesis was tested and rejected. This is documented rather than solved, and #654 closed on its own alternative acceptance path — a documented local-resource distinction plus repeatedly clean protected CI — not on a claimed root cause for that host.

What this unblocks, and what it does not

PR #681 and PR #680 may now enter final rebase and revalidation review. Neither has been merged. Neither was touched in this work — both remain open drafts based on next.

Issue #657 remains unstarted and may not begin yet. It still requires:

• feat(graph): PR A — plural relationship queries and explicit topology APIs (#656) #680 / [P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 merged;
• the mandatory post-[P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 plural-query and projection audit.

The graph sequence remains separate and sequential:

#656 → #657 → #658 → #659

Phase 0 is not complete, and the beta is not ready to publish. Beta publication remains blocked by the incomplete Phase 0 graph work. Release state is unchanged: npm latest is 0.32.1, no next dist-tag exists, no v0.33.0* tag exists, and no new GitHub prerelease was created.

Separately tracked, non-blocking

• Bound synchronous workspace Git discovery commands with an explicit process policy #697 — bound synchronous workspace Git discovery with an explicit process policy and error contract. Production follow-up; deliberately excluded from test(workspace): replace aggregate worktree timeout with phase-aware assertions #696, which was test-only.
• [P1] Decide and enforce the cross-platform coverage-mode qualification policy #698 — decide and enforce the cross-platform coverage-mode policy. Coverage mode currently runs on Ubuntu Node 22 only; Windows and macOS have no coverage lane. No evidence of a coverage-specific defect on those platforms.
• [P2] Remove or safely reap per-worker Madar Vitest home directories #699 — remove or safely reap per-worker Madar Vitest home directories.

The next orchestration turn covers: rebase and revalidate #681 → review and merge #681 → rebase and revalidate #680 → review and merge #680 → run the mandatory plural-projection audit → decide whether #657 may begin.