Add optional Codex startup routing

[arjitj2]

Closes #88

What changed

Codex can use the bundled startup hook to enter Pstack for engineering work. Its native /hooks trust and enable controls own the opt-in. Startup, resume, clear, and compaction reuse one shared routing instruction, with lightweight handling for trivial requests and explicit user overrides.

Routing-only setup leaves model assignments and spending permissions untouched. Adds regression tests, a clean-session verification recipe, and package version 1.10.0.

Verification

• Bun tests, strict typecheck, static invariants, and plugin validation pass. All 742 Bun tests and 8 hook tests pass; documentation and maintenance checks also pass.
• Exact candidate 62e855d160fc5c95e99fb4e9553162499f8630e4, version 1.10.0, installed in separate Codex and Claude Code profiles. All 213 packaged files match the candidate, excluding generated dependencies.
• Changed behavior passes from both affected parent CLIs; observed evidence below.
• Evidence names the candidate, action, and observed result below.

Observed on macOS after authenticating both dedicated profiles:

• Codex CLI 0.158.0: reviewed the installed hook in /hooks, trusted it, and later disabled it using native controls. Independent hooks/list reads confirmed trusted/enabled and trusted/disabled states for the exact candidate definition.
• A clean fixture had no global or ancestor Pstack routing mandate. The same plain engineering prompt did not load Pstack when untrusted or disabled; with the hook trusted and enabled, the parent read the installed poteto-mode/SKILL.md. Native transcripts show the exact shared instruction as developer context only in enabled runs. The enabled run was stopped after the routing observation; this verifies routing, not completion of the fixture feature.
• Pure question, trivial edit, and explicit “skip poteto-mode” cases stayed lightweight. Explicit $pstack:poteto-mode still caused native skill injection while the hook was disabled.
• Actual CLI resume, /clear, and /compact actions re-delivered the exact shared instruction. The transcript records a new developer message after the compaction event, independently of the pre-compaction message.
• Routing-only setup read the installed setup skill, directed the user to native /hooks, and ran no provider probes or model writes. Before/after hashes of the personal model files matched; dedicated-profile model files remained absent.
• Claude Code 2.1.282, authenticated subscription after reset: a plain engineering request invoked the actual Skill tool with pstack:poteto-mode and received the installed skill content. A pure question invoked no skill. Real startup, /clear, and resumed /compact CLI actions each emitted the exact shared context with hook exit code 0. The routing run was stopped after the skill invocation/expansion; it verifies selection, not full fixture feature completion. Plugin listing reports the dedicated cache; live initialization reports the local marketplace source tree. Both match the exact candidate; runtime cache selection is not claimed.
• All 213 packaged files were previously compared byte-for-byte with both dedicated installations, excluding generated dependencies. No packaged changes occurred during this follow-up. Windows execution remains unverified.

The updated head merges documentation-only changes from main. Its packaged tree is byte-identical to the candidate exercised above; both dedicated installations were compared again against all 213 files. The startup-routing recipe records the reproducible checks. Native transcripts and hook events were checked independently of model self-reports.

Original and updated-head CI passed (run). Copilot review was requested and returned a quota-limit notice; it provided no findings or approval.

Documentation impact

Updated README.md, setup-pstack/SKILL.md, the shared routing instruction, UPSTREAM.md, the verification map, and CHANGELOG.md. The routing preference uses host controls; no second preference file or AGENTS.md mandate is added.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.