Phase 4: compatibility shim policy and engine repository archival checklist

[solomonneas]

Parent: #352

Phase: 4

Define and execute the compatibility and archival policy for GraphTrail and MiseLedger product surfaces.

Status: executed 2026-07-21

Policy of record: docs/phase-4a-compatibility-and-archive.md.

The acceptance criteria originally filed here assumed a sunset clock that no longer exists. PR #422 (merged 2026-07-21) waived the v0.27.0 plus 90-day dual gate by maintainer decision: both mirrors were the maintainer's own MIT code under the same owner, with zero forks, zero known reverse dependencies, and clone traffic tracing to the maintainer's own fleet and CI. PR #424 (merged 2026-07-21) recorded the executed archival.

Two corrections to the original framing:

1. There is no 90-day or two-minor-release window. It was waived before it ever ran.
2. graphtrail, graphtrail-mcp, miseledger, and sessionfind are not time-boxed compatibility shims. Per the merged compatibility contract they are the managed engine set that brigade setup installs, shipped with no scheduled removal date.

Acceptance criteria

• Maintainer decision on the compatibility window recorded and merged (docs(phase-4a): compress the compatibility window by maintainer decision #422).
• graphtrail, graphtrail-mcp, miseledger, and sessionfind ship in the managed engine set with no scheduled removal date.
• brigade search sync, brigade search context, and brigade search impact retained as aliases for the brigade code equivalents.
• Deprecation and replacement guidance documented, including the sessionfind to miseledger sessions command mapping.
• Migration instructions published on both mirrors as ordinary commits before archival (graphtrail feat: add security fix command #44, miseledger feat: add security fix command #44).
• Both mirror master branches ancestry-verified as never rewritten or force-pushed.
• Product and documentation links updated to the Brigade release path.
• GraphTrail crate post-archival status documented (## GraphTrail crates.io policy).
• escoffier-labs/graphtrail archived 2026-07-21 (docs(phase-4a): record executed archival of both standalone mirrors #424).
• escoffier-labs/miseledger archived 2026-07-21 (docs(phase-4a): record executed archival of both standalone mirrors #424).
• Remaining issues transferred or closed with links. One straggler: escoffier-labs/miseledger#43, "perf(search): project filter bypasses bounded FTS candidate plan", filed 2026-07-21 and still open. The repository is archived, so the issue cannot be closed, commented on, or transferred without a temporary unarchive. The code it describes now lives in engines/evidence-ledger.
• Remove remaining cargo install guidance from engines/code-graph/README.md (lines 43, 50, and 52). Two of the three point at https://github.com/escoffier-labs/graphtrail, which is archived. The historical announcement drafts under engines/code-graph/content/announcements/ are a record of a past release and should be left alone.
• Resolve the crates.io deprecation directive. The policy says to mark the crate deprecated and maintenance-frozen, but crates.io exposes no deprecation flag, and the only way to change a crate's description or README is to publish, which the same policy forbids. Pick one: a description-only release as a documented exception, a banner in the crate README shipped by that same release, or amend the policy line to say the crate is frozen at 0.4.0 with deprecation communicated off-registry.

crates.io state verified 2026-07-27: graphtrail at 0.4.0, two published versions, unyanked, as the policy requires.

[solomonneas]

Body corrected 2026-07-27. The original acceptance criteria described a two-minor-release / 90-day compatibility window that #422 waived on 2026-07-21, before it ever started running, and #424 recorded the executed archival the same day. The criteria have been restated against docs/phase-4a-compatibility-and-archive.md as the policy of record, with executed items checked and three genuine remainders left open: the escoffier-labs/miseledger#43 straggler, cargo install guidance still live in engines/code-graph/README.md, and the unexecutable crates.io deprecation directive. No policy changed here; this only stops the issue from contradicting the merged record.

[solomonneas]

Scope narrowing for the 0.26.0 release train (verified 2026-08-03 on ad5ae46f)

Keeping this open through 0.26.0 by design, but one of the three remaining checklist items is closer to done than it reads.

The cargo install item is effectively finished. rg "cargo install" engines/code-graph/README.md now returns nothing. Lines 43, 50, and 52 as filed no longer carry install guidance. The only surviving reference to the archived escoffier-labs/graphtrail in that README is a CI badge on line 26:

<img src="https://shieldcn.dev/github/ci/escoffier-labs/graphtrail.svg?branch=master&workflow=ci.yml" alt="CI status">

That badge points at an archived repository, so it will render the last CI state before archival forever. Suggest narrowing this checklist item to "replace or drop the stale CI badge on line 26" rather than the original three-line removal, which is already done.

The two genuinely open items are both external-state problems, not code:

1. The miseledger#43 straggler needs a temporary unarchive to close or transfer. That is a maintainer action with no code change.
2. The crates.io deprecation directive is a policy contradiction that needs a decision, not an implementation. The three options in the issue body are still the right menu.

Neither blocks 0.26.0. Both are the reason to keep this open rather than work to do inside the release.