First release after v1.0.0. Installer replacement, docs/ai/ lifecycle
rework, and behavioral-eval hardening, plus incremental skill wording
improvements carried over from post-v1 maintenance.
Installer replacement:
- Add one canonical, static package inventory for reusable Claude, reusable
Codex, and Claude bootstrap installation, with LF-normalized SHA-256 content
validation before and after copy. - Add explicit normal install, overlay reinstall (
--force/-Force), and
staged clean reinstall (--clean/-Clean) behavior across Bash and
PowerShell installers. Conflicting flags and managed path type conflicts
fail; overlay preserves and reports extra files. - Add installer behavior tests covering both managed packages, including a
Bash test suite (scripts/test-installers.sh) mirroring the existing
PowerShell coverage. - Fix a Bash installer defect where a successful normal install or
--clean
reinstall printed a success message but exited with status 1, because the
EXITtrap's cleanup check used[ -d "$stage" ] && rm -rf "$stage"as a
bare statement; a false test in that position is exempt fromset -ebut
still sets the trap function's own exit status, which becomes the script's
final exit code. Every Bash wrapper script (install-user.sh,
install-project.sh,install-codex-user.sh,install-codex-project.sh,
install-bootstrap-user.sh) ends by callinginstall-package.shas its
last statement, so this previously caused those default-mode and
--cleaninvocations to report failure to callers despite installing
correctly. Fixed by using explicitif/fiinstead of&&for both the
trap cleanup and the post-replace backup removal. Caught by the new Bash
test suite.
docs/ai/ lifecycle rework:
- Establish the fixed
docs/ai/package withORIENTATION_STATE.json,
manifest-backed freshness and provenance, full and scoped reconciliation,
exact-current reuse, legacy adoption approval, dirty-tree handling, and
no-Git behavior. - Retire automatic generation and mutation of project-local
.claude/skills/codebase-orient/SKILL.mdwithout adding an overlay or
migration subsystem.
Behavioral-eval hardening:
- Extend the existing behavioral-evaluation runner with the authored
no-date-only-churn and source-drift two-pass cases and an optional model
override. - Fix the behavioral-evaluation runner's Codex sandbox isolation:
CODEX_HOME
was left pointing at the real user's.codexdirectory even thoughHOME
andUSERPROFILEwere overridden to a disposable sandbox, and the
disposable.codexdirectory was never created. Both meant Codex could
read real global state during a nominally isolated eval run. Fixed by
pointingCODEX_HOMEat the disposable home and creating that directory
before invocation. A fully empty disposableCODEX_HOMEcannot
authenticate, so the runner now seeds it with a copy of the real
auth.jsononly - no other real Codex state (skills, session history,
config) is copied in. - Validation status for the two named two-pass cases: the isolation and
authentication fix above was confirmed against a realcodex execrun
(the observed failure moved from a missing-directory error, to401 Unauthorized, to a real account usage-limit response, then to a real
completed run once the account quota reset). A full live pass/fail verdict
for either case is still not available: in the completed run, the Codex
session reported itself as read-only despite the case requesting
workspace-write, so pass 1 correctly proposed the package instead of
writing it, per the skill's own dry-run fallback rule, rather than
exercising the intended write-then-rerun-unchanged check. This is recorded
as a known Codex CLI environment limitation, not an Orient skill defect;
unlikev1.0.0, this release does not carry an independent
human-through-agent validation pass.
Orientation skill improvements (canonical + bootstrap):
- Treat existing docs/ai output as hypotheses on re-run: the staleness rule now explicitly applies the docs-as-hypotheses discipline to prior orientation output, preventing stale structural claims from being accepted as discovery input on subsequent passes.
- Add agent-closable vs human-required classification axis to open questions: the orientation-completion-rule now requires each unresolved question to be classified not only by urgency (Blocking / Relevant-but-non-blocking / Background) but also by who can act on it, letting a new agent immediately identify which items it can work on autonomously.
- Surface check script constraints in CHANGE_SURFACES docs-impact guidance: the change-surfaces-mapping-guidance rule now instructs orient to note what file types or patterns scripts/ check scripts enforce, so future agents know about constraints like ASCII-only requirements before writing.
- Add conditional release status section to CODEBASE_MAP: the discovery order now instructs orient to add a Release status section to CODEBASE_MAP.md when a release plan, milestone doc, or version changelog is found, summarizing current version, active milestone, and blockers.
- Clarify that docs/ai files should be committed in target repos: the output files section now states explicitly that these files are authored narrative that improves across sessions and should not be gitignored in target repos.
- Flag release validation records and gate scripts as a hidden-risk surface: the hidden-risk-reporting-rule now includes release validation records and gate scripts in its checklist, and instructs orient to note in CHANGE_SURFACES that file changes after a validated candidate require a re-check before tagging.
Post-v1 maintenance hardening (no installer behavior change at the time):
- Add a deterministic shared-rule drift guard for canonical
skills/codebase-orient/SKILL.mdvs the bootstrap embedded shared-rule snapshot inskills/install-codebase-orient/SKILL.md, including explicit shared-block markers, a validation script, and a GitHub Actions check that now guards those shared blocks against future accidental drift. - Align the bootstrap embedded shared-rule snapshot to canonical wording so future bootstrap-generated project-local skills receive the synchronized shared-rule content.
- Freeze the former
docs/V1_RELEASE_PLAN.mdcontents asdocs/releases/v1.0-validation-record.mdand keepdocs/V1_RELEASE_PLAN.mdas a short compatibility pointer now thatv1.0.0has shipped. - Add an initial local/manual Codex behavioral eval scaffold: an inspectable prompt corpus plus a PowerShell wrapper over a Node runner that uses isolated disposable fixtures, stores traces outside the repo by default, and currently emits evidence summaries for one validated single-case vertical slice with proxy-only invocation evidence from local
codex exec --jsontraces. - Clarify that the reusable canonical skill currently has an explicit tuned framework-probe section for SvelteKit, while other frameworks still rely on the generic discovery order unless later live-fire or eval evidence justifies dedicated tuned probes.