fix: stabilize Codex paths and close the relationship-origin vocabulary

[levifig]

Change

docs/changes/20260719-path-stability-and-origin-hygiene/

Bounded hotfix shaped from Codex's post-ship review of intent-exploration-foundation (PR #122), addressing both HIGH/MEDIUM code defects and the help-surface LOWs before the next large Change.

What & Why

U1 — Relationship-origin registry. Doctor rejected origins that the new Intent/Exploration writers produced ('intent-create', 'legacy-conversion', 'exploration-create'), leaving a healthy schema-12 database permanently warning on ten rows while the recommended repair matched zero of them. One registry in internal/state/relationship_origin.go now feeds the writers, the doctor invariant, and repair. All writers normalize to the closed mechanism vocabulary (imported/manual/command); a source-literal AST scan enforces it — and immediately exposed five more writers inlining 'system' in run.go/finding.go, the same defect class, now also normalized. state repair relationship-origin reclassifies exactly the four named legacy origins backup-first (idempotent, foreign origins surfaced but never rewritten) and preserves the backup path when a post-backup step fails.

U2 — Codex stable-path rendering. The installer resolved the loaf PATH entry through EvalSymlinks into the versioned Homebrew Cellar target, so every release invalidated the rendered AGENTS.md guidance, SessionStart hook, and all execpolicy prefixes, stranding running Codex tasks. Rendering now uses the un-canonicalized PATH entrypoint (stable across upgrades); EvalSymlinks is retained for validation only, with forbidden-root checks enforced in both symlink directions. This amends Decision 19 of journal-reliability-foundation, recorded in the Change and journal.

U3 — Help-surface parity. state migrate dispatch and help now derive from one registry, making an unlisted source structurally impossible (bidirectional parity test plus a behavioral dispatch probe per source). All six sources are listed; bare migrate --help and the leaf helps (conversation handle add, exploration conversation add) exit 0; agent-help and the generated CLI reference were brought in line.

Review focus

• The Decision 19 amendment: confirm the rendered-vs-validated split drops no security property (H1). The render path is additionally checked against forbidden roots — a deliberate tightening.
• Decision 4's boundary: repair reclassifies only the four named legacy values; confirm nothing can launder a foreign origin into 'command'.
• The 'system' normalization in run.go/finding.go exceeds the three writers named at shaping; the Change's Decisions record the amendment and rationale.

Verification

• go vet ./..., go test ./... -count=1 (all packages), npm run typecheck, npm run build — all green; artifacts synchronized and committed.
• loaf change check — no violations, executable.
• Capability evidence regenerated via the sanctioned u8 smoke writers against the rebuilt binary; diffs are hash/timestamp/marker only.
• Doctor-clean-after-writer tests cover Intent create, Exploration create, and legacy conversion; the repair fixture proves dry-run disclosure, apply, idempotency, and foreign-origin preservation; the upgrade-survival test proves rendered Codex files stay valid after a symlink retarget.

Migration / breaking changes

Existing databases with the legacy origins run loaf state repair relationship-origin --dry-run then --apply (backup-first). The real-database run, the Codex repin via loaf install --upgrade, and the journal closure entries are Definition of Done steps executed with the release, per the Change's sequencing.

Deferred

• Cross-context Exploration dogfood → INTENT-20260719-retain-one-real-cross-context-exploration…, gating the shaping of change-native-execution-migration.
• Handoff/research artifact authority and structural journal-staleness semantics → terminal guidance sweep.
• Codex execpolicy rules-caching question (last open fog entry) → isolated CODEX_HOME runtime smoke with the DoD evidence.

[levifig]

Response to the adversarial review (verdict FAIL, seven findings) — addressed in 8007bab:

Fixed:

1. Bare repair invocation — state repair relationship-origin --dry-run/--apply without --origin is now valid as reclassification-only mode (your preferred direction): it reclassifies the four registry-named legacy origins and reports foreign origins, touching no missing-origin rows. The backfill still requires an explicit --origin imported|manual, because inventing missing provenance is an operator judgment while reclassifying named legacy values is not. The Observable Workflow commands now run as written (Runner-level end-to-end test added); the old rejection regression test was replaced with bare-mode assertions plus an invalid-value rejection test. Decision 4 records the mode split.
2. Legacy-only doctor-clean fixture — TestRepairRelationshipOriginsLegacyOnlyFixtureIsDoctorCleanAfterApply seeds all four legacy origins and asserts zero diagnostics after apply. The mixed fixture (with mystery-import) is retained for foreign-origin preservation.
3. Fail-closed parity scan — an origin bind the scanner cannot classify (local variable, field, unresolved identifier) is now a test failure naming the position; mutation-verified.

Documented rather than changed:
4. H1 trust boundary — Decision 1 now states it explicitly: rendered policy trusts wherever the entrypoint points at execution time; validation gates install/upgrade time (entrypoint and canonical target both checked against forbidden roots); a post-install symlink retarget is out of scope by design, exactly as a post-install Cellar-binary replacement was under the old pin. Both models trust a user-writable Homebrew prefix — the amendment trades a version-frozen path for continuity without widening what prefix write access already allows.
7. Scope items — justified in a new Adjacent-surface notes subsection: bare migrate --help fails the identical discover-from-live-help rule the Problem names and was flagged in this Change's own review round; the smoke-evidence regeneration is the sanctioned response to the by-design hash-drift gate (same as installed-distribution-authority), diffs limited to hash/timestamp/marker.

Already sequenced (5, 6): the real-state repin, database repair, closures, and runtime smoke are release-time Definition of Done steps per the Change's Sequencing section — your sandbox couldn't reach the live DB or GitHub to see that context. V1's gates (go vet, go test ./..., typecheck, loaf build, loaf change check) all ran green locally before this push.