Reliable candidate validation and commit coverage

Context

CLI 5.1.1 rejects a valid staged CLAUDE mirror before composing its live AGENTS target. Disposable Harness update probes stopped first at an irrelevant archived Oxlint configuration, then at the live generated backoffice configuration. Both stopped before installation, patching, lint, or publication. Successful commit commands also lose their diagnostics. The reported commit coverage and update validation issues include broader gaps; this delivery covers the remaining reusable CLI requirements of #200, #201, #219, and #220.

Evidence: research report. External raw evidence lives in /Users/stefan/Documents/Codex/2026-09-21/hi-quickfix-audit/evidence. Base: 7e147b3300c391db979b87e20c4159a5a03d12cb.

Non-Goals

• Repair existing consumer lint debt, alter Effect rules, or claim consumer CI already enforces repository cleanliness.
• Resolve #199, #215, or #217.
• Run hosted CI, change repository-wide CI settings, or publish a release.
• Run arbitrary dependency lifecycle scripts or weaken containment and freshness checks.

Requirements and Outcomes

OUT-001: Validate the final candidate tree

Compose live inputs, staged overrides, selected live manifests, and explicit removals before validating retained links. Valid root/nested mirrors may resolve live authored guidance. Required absent targets, escapes, cycles, unsupported entries, and changed consulted inputs remain failures before publication. No authored proof is manufactured.

OUT-002: Validate affected update surfaces faithfully

Derive installation and lint requirements from actual planned managed changes. Guidance-only reconciliation must not install or lint unrelated packages. Installation topology and lint targets are distinct. Generation freshness reads actual producer inputs and discovery topology without hashing unrelated migration payloads or historical backups. Explicitly referenced inputs remain required regardless of pruning.

Official generated backoffice Vitest overrides must validate with their original matching and rule precedence. Only the exact generated declarative merge pattern is supported; arbitrary callbacks remain unsupported. Controlled Effect patch preparation remains supported. Selected install or config failures retain phase and useful stderr. Provide a documented fresh-cache retry without changing frozen lockfiles. Apply progress represents an actual publication attempt.

OUT-003: Make commit coverage explicit and observable

Preserve command stdout/stderr on success and failure. Add compatible explicit command execution semantics for file, owner, and repository checks. Root-only changes, deletions, and cross-owner renames cannot silently select zero coverage. Deleted names never become file arguments. Aggregate commands execute unchanged. Declared repository authority subsumes corresponding subordinate checks; identical invocations execute once. Preserve arbitrary consumer scripts and legacy contract readability. Generated Oxlint defaults enforce zero warnings. Unresolved authority gives an actionable coverage failure.

OUT-004: Deliver reviewable proof and honest closeout

Retain regression and built-runtime evidence, document the authoritative consumer CI lint/format gate, and produce one issue-linked PR with hosted CI suppressed. Issue closeout distinguishes branch implementation, main merge, published CLI availability, and existing consumer debt.

Acceptance Criteria

• AC-001: Root/nested staged mirrors resolve live targets; staged replacements win and removals apply last. Invalid final links fail without live writes. Covers: OUT-001.
• AC-002: Unreferenced archives, migration payloads, and nested fixture installs cannot block a guidance-only update. Required references remain closed, bounded, witnessed, and validated. Covers: OUT-002.
• AC-003: Generated backoffice configuration passes closure; real pinned Oxlint confirms file matching and override precedence; unrelated executable configuration remains rejected. Covers: OUT-002.
• AC-004: Affected config/dependency changes validate their consuming scopes using owning installation roots. Prepared Effect configuration works; concrete install/config errors survive into diagnostics. A blocked update emits no apply-completed event. Covers: OUT-002.
• AC-005: Generated and migrated commit contracts cover root changes, deletion-only commits, cross-owner renames, nested owners, and distinct lint/format authority. Aggregate commands receive no guessed arguments. Covers: OUT-003.
• AC-006: Successful diagnostics appear once on their original streams, empty success is quiet, failures retain exit behavior, and generated warning diagnostics cause nonzero lint exit. Covers: OUT-003.
• AC-007: Runbook identifies authoritative repository CI lint/format checks and custom-command limitations without asserting project-owned CI was changed. Covers: OUT-004.
• AC-008: Original Harness and Collective checkouts remain unchanged. One PR links all four issues; every pushed HEAD uses [skip ci]; provider readback verifies CI suppression and actual issue state. Covers: OUT-004.

Constraints

All product implementation uses scoped workers in isolated worktrees. Preserve managed ownership and cache identity. Use Bun 1.3.5 for baseline-compatible validation where available. Baseline frozen install already fails; an isolated no-save dependency install and explicit Effect preparation establish test tooling without changing tracked manifests or lockfiles. Local results must state this limitation.

Dependency Readiness

No Stack Required. Current remote main is the immutable base above. No unmerged dependency is assumed.

Branch/Base Intent

Implementation branch team/stefan/cli-update-quick-fixes starts from that main commit. Worktree /Users/stefan/Documents/Codex/2026-09-21/hi-quickfix-audit/harness; consumer worktree is its sibling collective. All commits retain conventional commit syntax and [skip ci].

Accepted Technical Decisions

• Candidate composition is the single authority for link validation; do not validate a partial overlay as a repository.
• Select validation effects from reconciliation actions. Root installation does not imply root lint. Unknown required relationships fail with a concrete reason.
• Keep generation content inputs separate from discovery topology witnesses. Do not raise closure limits to accommodate unrelated data.
• Add a narrow generated Vitest merge grammar rather than general JavaScript evaluation.
• Keep quality command strings; optional per-command execution metadata distinguishes files, owner, and repository. Only explicit repository authority suppresses subordinate checks. Configuration and evidence must preserve this metadata.
• Generated commands have strict warning policy; arbitrary existing script bodies remain user-owned. Missing declared coverage fails with instructions.
• Use existing GitHub issue identities. Internal execution tasks use uniform planning-only identities; no unrelated Linear projection.
• [skip ci] suppresses current push/pull_request workflows. Skipped required checks are not green checks.

Accepted Testing Decisions

RED then GREEN at public process and candidate-result seams. Test real symlinks in temporary repositories, explicit required archive imports, mutation and negative closure, generated preset semantics, staged Git status including deletions/renames, deterministic output, and unchanged aggregate commands. Build the CLI normally to regenerate runtime identities. Repeat supported update/check scenarios only in isolated consumers, reporting setup blockers separately.

Verification Seams

runCandidateLintPreview, candidate closure resolution, generation snapshot revalidation, runUpdate result/progress, generated commit-gate process, scaffold output/schema decoding, built hi update and hi check, GitHub PR/run/issue readback.

Delivery map

Decision Log