fix(setup): honor provider roots and calibrate agent workflows

[xinyiklin]

Summary

Custom Codex and Claude configuration directories could be ignored by shared-skill setup, and relocated Claude directories could produce unreadable links while verification reported success. Setup now honors the selected provider roots, checks real link targets, and rejects obstructed roots before acquisition.

The accompanying guidance makes Codex desktop the primary entry while retaining Claude's native loading, separates contract changes from mechanical maintenance, and requires fresh independent review for ordinary implementation. PR guidance adds a 500-line target and a 1,000-line split-or-reviewer-exception gate.

Scope

• Installer and nine disposable provider-root regression groups.
• Root guidance, canonical project starters, both Git contracts and PR templates, runtime smoke guide, and calibration receipt.
• Existing project-owned sibling guidance is not synchronized. Workflow source and generated adapter formats remain unchanged.
• The user separately authorized restoring the existing reviewed Impeccable 4.0.2 installation with a recoverable 4.0.4 backup. This cleared local skill drift without changing the manifest or executing upstream code; that machine operation is not a repository payload.

PR size

• Counted additions + deletions against main: 903 (867 additions, 36 deletions).
• Exclusions: none.
• Above 500 rationale: this is one setup calibration across installer behavior, failure-boundary tests, shared guidance, and its canonical starter copies. Keeping the policy and consumer documentation with the behavior lets reviewers assess consistency without a partially updated setup contract. The 301-line test addition covers nine distinct failure/preservation groups; the receipt records acquisition evidence and verification limits.
• Above 1,000 exception: not required.

Verification

• Full Node 24.19.0 regression suite: 92 passed, zero failures or skips after skill restoration.
• node scripts/init-workspace.mjs --check: passed, including all eight shared skills and both providers' workflow adapters.
• Python 3.12 tomllib: parsed both adversarial generated-adapter fixtures.
• Root/starter policy sections and PR templates match; guidance paths, imports, byte budgets, continuity budget, syntax, and whitespace checks passed.
• Implementer inspected the full diff. Fresh independent mb_verifier review of exact head 45b77cf0c9d0d71741786f0132ad1a22cf9bde5e found no unresolved implementation or guidance findings and independently verified both restoration hashes and the complete workspace check.
• Claude runtime loading, broader Codex nested/profile/worktree scenarios, and upstream executable cleanup behavior were not exercised. Static installation/source checks do not prove those behaviors.
• Initial Linux/macOS CI passed. Windows exposed an overly specific rejection-message assertion; the test now accepts both valid platform diagnostics while retaining nonzero-exit, no-acquisition, and preservation checks. The bounded fix received independent review. Final PR CI and post-merge CI passed on Linux, Windows, and macOS. Each PR job ran 87 passing tests and explicitly skipped five installed-roster checks because shared skills are absent in CI; all five passed in the 92-test local run.

Risk and follow-up

• Separate versioned Product Brief and Delivery Plan approval gates were not run. Execution followed direct session authorization; the calibration receipt records this process deviation. Independent review was performed and is not waived.
• Retain the reviewed Impeccable pin until a fresh source review supports an upgrade recommendation. Latest reviewed cleanup source still has the intermediate-symlink containment issue; no file loss was observed.
• Runtime provider smoke scenarios remain a documented follow-up, with no claim of universal provider loading support.

Publication

• Base: main.
• Squash-merged as 55d9b10dead624119638c603b40d5dc939e79175 after exact-head review and green cross-platform CI. Local main was fast-forwarded, is clean and synchronized, and its tree matches reviewed head 45b77cf0c9d0d71741786f0132ad1a22cf9bde5e. The post-merge workspace check passed.
• Release/deployment: none.