Restructure the repository guidance around agent behavior, project surfaces, and verification routing so future coding agents can choose fast inner-loop checks without losing the PR and release quality gates.
Constraint: AGENTS.md wording is covered by the feature quality contract tests.
Constraint: Release workflow currently builds from tags and is not a substitute for local release verification.
Rejected: Keep the old command inventory with appended guidance | it preserved duplication and left verification budgeting ambiguous.
Confidence: high
Scope-risk: narrow
Directive: Keep future guidance tied to real package scripts and workflow behavior.
Tested: bun test scripts/pr/quality-contract.test.ts
Tested: bun run check:policy
Not-tested: Full bun run verify, documentation-only guidance change.
Online upgrades can strand users on stale desktop UI state or malformed local persistence. This adds a deny-by-default Doctor path that resets only regenerable desktop UI state, reports protected local files with redacted metadata, and keeps protected repair as a dry-run no-op until a reviewed backup-first flow exists.
Constraint: Chat transcripts, model/provider config, Skills, MCP, IM bindings, adapter sessions, OAuth tokens, plugins, and team/session records are user-owned protected state.
Rejected: Automatically rewrite malformed protected JSON | unsafe without schema-specific migrations and backups.
Rejected: Continue relying only on startup migrations | users need an explicit recovery action after a white screen.
Confidence: high
Scope-risk: moderate
Directive: Keep Doctor repair deny-by-default; do not mutate protected state without an explicit reviewed backup-first manual repair flow.
Tested: bun test src/server/__tests__/doctor-service.test.ts
Tested: cd desktop && bun run test src/components/ErrorBoundary.test.tsx src/lib/doctorRepair.test.ts src/__tests__/diagnosticsSettings.test.tsx src/components/layout/StartupErrorView.test.tsx
Tested: cd desktop && bun run lint
Tested: bun run check:server
Tested: bun run verify (failed only existing agent-utils coverage baseline; changed-lines coverage 97.62%)
Not-tested: Packaged desktop manual Doctor click path.
Desktop users can carry provider indexes, managed settings, localStorage state, and native update state from builds that no longer match current readers. This adds startup migrations and recovery paths before server and React state are consumed, plus a persistence upgrade gate so future storage protocol changes ship with old-format fixtures.
Constraint: Existing installs may contain malformed or legacy JSON/localStorage that must not block startup.
Constraint: Local verify should evaluate the current worktree diff rather than unrelated detached-worktree history.
Rejected: Treat invalid persisted state as fatal | reproduces white-screen and startup failure behavior for existing users.
Rejected: Bypass PR policy locally | hides real gate behavior and does not fix detached-worktree false positives.
Confidence: high
Scope-risk: moderate
Directive: Any local JSON, localStorage, or app config shape change must add a migration fixture and keep `bun run check:persistence-upgrade` green.
Tested: bun run check:persistence-upgrade; bun run check:policy; bun run check:desktop; bun run check:server; bun run check:native; bun run verify (9 passed, 1 coverage baseline failure)
Not-tested: Live provider baseline; existing user configs beyond covered fixtures
Contributors and coding agents need one local command that both reports and enforces the quality contract. This change turns the PR gate into the shared verification entrypoint, adds path-selected local lanes, tightens coverage accounting around changed lines, and documents the repair loop in contributor and agent-facing guidance.
Constraint: Ordinary PR verification must stay non-live and runnable without provider credentials
Constraint: Coverage policy updates in this commit require maintainer approval before push/merge
Rejected: Keep quality guidance only in docs | agents need executable scripts and AGENTS.md instructions to follow the loop consistently
Confidence: high
Scope-risk: broad
Directive: Do not bypass `bun run verify` for production changes; fix failed lanes and coverage reports instead of lowering thresholds
Tested: bun run check:policy
Tested: ALLOW_CLI_CORE_CHANGE=1 ALLOW_COVERAGE_BASELINE_CHANGE=1 bun run verify
Not-tested: live provider baseline; no provider credentials were required for this non-live PR gate
The repository now has a measurable PR quality path instead of a loose set of
manual checks. Coverage, quarantine governance, provider smoke, desktop smoke,
and workflow wiring all produce durable reports that contributors and maintainers
can inspect without reconstructing terminal output.
This also fixes the desktop smoke current-runtime path so browser-driven smoke
runs use the desktop default active provider instead of forcing the official
current model, and records that runtime decision as an artifact.
Constraint: Default PR gates must remain non-live and contributor-safe while live model checks stay explicit.
Constraint: Release packaging is still GitHub Actions based, so release preflight must run before the build matrix.
Rejected: Make live provider or desktop smoke mandatory on every PR | secrets, quotas, and model availability are maintainer-controlled.
Rejected: Let PRs lower coverage baselines in the same change | base-branch ratchet comparison must remain authoritative.
Confidence: high
Scope-risk: moderate
Directive: Do not relax coverage or quarantine policy without a maintainer approval label and a fresh quality report.
Tested: ALLOW_CLI_CORE_CHANGE=1 ALLOW_COVERAGE_BASELINE_CHANGE=1 bun run quality:gate --mode pr
Tested: bun run quality:gate --mode baseline --allow-live --only provider-smoke:* --provider-model nvidia-custom:main:nvidia-custom-main --artifacts-dir /tmp/quality-gate-live-smoke
Tested: bun run quality:gate --mode baseline --allow-live --only desktop-smoke:* --provider-model current:current:current-runtime --artifacts-dir /tmp/quality-gate-desktop-smoke-fixed
Tested: git diff --check
Not-tested: Full live release mode with multiple providers in hosted CI; provider credentials and quota remain maintainer-controlled.
AGENTS.md is the operational contract future CodingAgents read before editing this repo. Record when to run PR, targeted, live-baseline, release, docs, and native gates so users do not need to manually enumerate the commands each time.
Constraint: Live baseline depends on local provider and quota state.
Rejected: Leave this only in CONTRIBUTING.md | human-facing docs do not reliably steer future agents.
Confidence: high
Scope-risk: narrow
Directive: Do not claim PR or release readiness without running the corresponding gate or reporting the blocker.
Tested: git diff --check
Tested: bun run quality:gate --mode pr --dry-run
Not-tested: full quality:pr because this is an AGENTS-only guidance change.
The repository uses product-oriented branch prefixes rather than Codex-specific names, so the workspace guidance now records that convention for future local branch creation.
Constraint: Repository guidance should stay compact and only capture durable workflow rules.
Confidence: high
Scope-risk: narrow
Tested: not run; documentation-only change
The recent release automation and docs-workflow fixes are durable repository
rules now, but they only lived in live context and recent commits. This adds
a compact AGENTS.md memory block so future agents follow the remote desktop
release path, use release-notes/vX.Y.Z.md as the GitHub Release source, and
remember the npm lockfile requirement for the docs workflow.
Constraint: AGENTS.md should stay compact and high-signal rather than turning into a changelog
Rejected: Document the full release procedure in detail inside AGENTS.md | too much operational noise for the repo memory layer
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep AGENTS.md limited to durable workflow rules; do not expand it with transient release-specific prose
Tested: git diff --check
Not-tested: No runtime verification required for documentation-only guidance update
- Deleted desktop/src/components/chat/highlightCode.ts (no longer needed)
- Removed all .hljs-* CSS rules from globals.css
- Updated chatBlocks test for react-diff-viewer-continued (doesn't render
diff content in jsdom, so test verifies component mounting instead)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
