Codectx v0.2: deterministic repository context packets

[greygoody]

Public MVP

Promote Codectx from an early bounded-session foundation into a reproducible repository context compiler for humans and coding tools.

Implemented

• deterministic HUD and JSON packet;
• explicit focus and four-way change classification;
• public justfile command discovery with definition hashes;
• review and durable handoff surfaces;
• external records retained as external_claim with unknown freshness;
• preserved codectx-legacy runtime and truthful v0.2 compatibility forwarding;
• focus example, generated-state ignores, Rust contract tests, CLI tests, CI, and implementation-status documentation;
• committed fixture demonstrating expected, supporting, and unexpected changes;
• command-discovery, hidden-command, attention, and handoff byte-equality assertions.

Explicit v0.2 policies

• the default .codectx/focus.toml may be absent;
• an explicitly supplied missing --focus PATH is an error at both CLI and core-builder boundaries;
• implemented historical commands invoked through codectx forward to codectx-legacy when both binaries are installed;
• codectx check maps explicitly to legacy ok;
• unimplemented legacy commands, including events, are not advertised;
• legacy subcommand help is forwarded before the new global help surface;
• .codectx/handoffs/latest.json is the primary managed handoff, while --output PATH remains available for explicit integrations.

Boundary

Codectx renders context. Runseal owns obligation meaning, evidence validity, resolution, and regression. This PR does not add closure evaluation, proof authority, orchestration, indexing, a daemon, or a database.

Accepted proof

GitHub Actions run #43 passed on accepted head c2a51580a068aa087948fd11ca26ac10f5acf0e6:

• cargo fmt --all --check;
• cargo clippy --workspace --all-targets -- -D warnings;
• cargo test --workspace;
• cargo run -p codectx-cli --bin codectx -- --help;
• bash scripts/demo.sh.

Independent local validation also passed just check, built both binaries, verified root help excludes events, and verified both codectx ok --help and codectx check --help reach legacy ok help.

Reviewer journey

clone
→ build both binaries
→ copy the example focus
→ run the plain HUD
→ inspect JSON and review output
→ run the committed three-way classification fixture
→ observe external claims without authority leakage
→ verify the default handoff is byte-identical to JSON
→ verify truthful legacy forwarding and help behavior

Repository decision

This is the single canonical public context-packet promotion. Duplicate draft PR #7 was closed after its useful presentation work was incorporated here.

Release decision

The blocking compatibility review was resolved on the accepted head. This PR is approved for merge. Tag the resulting public release commit as v0.2.0 after merge.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[greygoody]

Blocking release-review finding on the current head:

The v0.2 compatibility surface is broader than the preserved legacy binary actually supports.

• context_main.rs advertises and forwards events and check.
• The preserved codectx-legacy command enum implements ok but does not implement events or check.
• The wrapper checks for any --help before legacy dispatch, so commands such as codectx ok --help show the new context-compiler help rather than the legacy subcommand help.
• README currently cites codectx events as a supported forwarding example.

Please make the compatibility contract truthful before merge:

1. Dispatch recognized legacy commands before handling global help, so legacy subcommand help reaches codectx-legacy.
2. Either map check explicitly to legacy ok, or stop advertising check.
3. Remove events from the public compatibility list and README unless the event command is actually promoted in this release.
4. Add CLI integration coverage for forwarded legacy help and the check/ok decision.
5. Re-run the complete accepted proof on the resulting head.

The context-packet implementation itself reviewed coherently: packet authority boundaries, explicit missing-focus behavior, deterministic projections, external-claim handling, fixture coverage, and generated-state hygiene are all consistent. I am withholding merge only for the published compatibility mismatch above.