diff --git a/.github/workflows/shared-rule-drift.yml b/.github/workflows/shared-rule-drift.yml new file mode 100644 index 0000000..7eefc41 --- /dev/null +++ b/.github/workflows/shared-rule-drift.yml @@ -0,0 +1,20 @@ +name: shared-rule-drift + +on: + push: + branches: + - main + pull_request: + +permissions: + contents: read + +jobs: + compare-shared-rules: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Validate shared-rule synchronization + shell: pwsh + run: ./scripts/check-shared-rule-drift.ps1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a3b3fb..52a2039 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## Unreleased + +Post-v1 maintenance hardening only. No installer behavior change. No intended change to the canonical reusable orientation behavior beyond maintenance markers. + +- Add a deterministic shared-rule drift guard for canonical `skills/codebase-orient/SKILL.md` vs the bootstrap embedded shared-rule snapshot in `skills/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.md` contents as `docs/releases/v1.0-validation-record.md` and keep `docs/V1_RELEASE_PLAN.md` as a short compatibility pointer now that `v1.0.0` has shipped. + ## 1.0.0 - 2026-05-24 First stable public release of `codebase-orient`. diff --git a/README.md b/README.md index 96f0cea..a73db40 100644 --- a/README.md +++ b/README.md @@ -299,7 +299,7 @@ If you install a project-local skill and want to track only the shared skill fil - [`skills/codebase-orient/SKILL.md`](skills/codebase-orient/SKILL.md): canonical reusable skill behavior - [`skills/install-codebase-orient/SKILL.md`](skills/install-codebase-orient/SKILL.md): Claude Code bootstrap skill behavior and versioned embedded template - [`CHANGELOG.md`](CHANGELOG.md): release history -- [`docs/V1_RELEASE_PLAN.md`](docs/V1_RELEASE_PLAN.md): release criteria, validation record, and current known gaps +- [`docs/releases/v1.0-validation-record.md`](docs/releases/v1.0-validation-record.md): frozen historical validation record for `v1.0.0` - [`scripts/`](scripts/): install and validation helpers Tracked repo-maintenance text in this repo follows an ASCII punctuation convention. The check scripts are: @@ -312,6 +312,12 @@ Tracked repo-maintenance text in this repo follows an ASCII punctuation conventi ./scripts/check-ascii-punctuation.sh ``` +Shared canonical/bootstrap rule blocks can also be validated directly with: + +```powershell +.\scripts\check-shared-rule-drift.ps1 +``` +
Uninstall reference diff --git a/docs/V1_RELEASE_PLAN.md b/docs/V1_RELEASE_PLAN.md index 440f9c9..d42fccd 100644 --- a/docs/V1_RELEASE_PLAN.md +++ b/docs/V1_RELEASE_PLAN.md @@ -1,833 +1,8 @@ -# v1.0 Release Plan - codebase-orient-skill +# v1.0.0 shipped -Current release status: all substantive validation gates are resolved; this document records the validated release basis and final tagged-artifact content for `v1.0.0`. Push, tag, GitHub Release, and public-surface verification are external publication actions recorded in the final execution report and GitHub state | Final target: v1.0.0 | Updated: 2026-05-24 -Last validation: 2026-05-24 (public `v1.0.0-rc.6` at `98589ad3e8b7c79ff33482b749c2935332cab104` passed the WSL2 Ubuntu bash installer matrix and the direct bootstrap runtime contract verification; `rc.6` remains the validated public behavioral basis for final `v1.0.0`, passed independent human-through-agent validation, and is unchanged from the public candidate that was validated; `rc.5` is the prior public agent-delegated onboarding candidate and failed the external validation gate on exact-install integrity; `rc.4` remains the prior published sanitized candidate; the governance hardening pass is complete) -Final release note: relative to public `rc.6`, final `v1.0.0` preserves the runtime-validated behavior and adds release metadata/evidence reconciliation only: the stable `CHANGELOG.md` release entry, the final release-plan evidence/status record, removal of one stale non-behavioral repository-version reference from the bootstrap skill's internal changelog note, and the corresponding bootstrap internal metadata-version increment to `0.2.3`. No bootstrap behavior, embedded template rule, installer behavior, or runtime contract changed after `rc.6` validation. +`v1.0.0` is already released. The former release-plan document is now frozen as a historical validation record: ---- +- See [`docs/releases/v1.0-validation-record.md`](releases/v1.0-validation-record.md). -## A. Current status - -### Release and tag state - -| Tag | Summary | -|-----|---------| -| v1.0.0 | Final stable release record. This document captures the validated source content for `v1.0.0`; push, tag, GitHub Release, and public verification are external publication actions rather than additional source-content changes. | -| v1.0.0-rc.6 | Validated release candidate. Passed independent human-through-agent validation and confirmed the exact-install integrity contract introduced after the `rc.5` failure. | -| v1.0.0-rc.5 | Prior public agent-delegated onboarding candidate. Failed the external validation gate on exact-install integrity before any installed skill file was written. | -| v1.0.0-rc.4 | Published sanitized candidate. Records the pre-public sanitation decision and the corrected manual-install contract that preceded the delegated-install onboarding correction. | -| v1.0.0-rc.3 | Historical pre-public contract-correction candidate. In retained sanitized history, this tag no longer carries the removed disclosures, but it is not the candidate to use for external cold-user validation. | -| v1.0.0-rc.2 | Historical pre-public candidate: README onboarding rewrite + fixed project-local installer `.gitignore` guidance. | -| v1.0.0-rc.1 | Historical pre-public cold-user candidate; README polished; 6/8 live-fire rows satisfied. | -| v0.3.2 | ASCII punctuation normalization + check scripts. | -| v0.3.1 | Install contract cleanup, artifact policy, Codex parity docs. | -| v0.3.0 | Orientation surface mapping and authority-boundary cleanup. | -| v0.2.0 | Dual-runtime skill, bootstrap, no-date-only-churn, invocation reliability. | -| v0.1.x | Initial skill, Codex install scripts, bootstrap skill source. | - -`v1.0.0-rc.1` and `v1.0.0-rc.2` remain historical pre-public candidates. `rc.2` introduced the README onboarding rewrite and project-local installer `.gitignore` correction but carried incomplete README mutation-scope and trust-posture wording. `rc.3` corrected those statements but was then blocked by the pre-public exposure audit because tracked docs and reachable pre-public history still contained private validation identifiers and maintainer-local paths. `rc.4` is the prior published sanitized candidate, and a supplementary Codex delegated-install exploration against public `rc.4` showed that agent-facing onboarding needed one more focused correction before the independent gate could be rerun. `rc.5` then became the first public agent-delegated onboarding candidate, but the independent external validation attempt failed on exact-install integrity. `rc.6` passed the rerun and is the validated basis for final `v1.0.0`. Do not use `rc.1`, `rc.2`, or `rc.3` for external validation, do not treat the `rc.4` exploratory agent run as the independent gate pass, and do not treat the interrupted `rc.5` run as passing evidence. - -### Publication and governance state - -- Public repository publication and the pre-v1 sanitation pass are complete; `v1.0.0-rc.6` is the validated release candidate and final release basis, and all substantive validation gates for `v1.0.0` are now resolved. -- Repository governance hardening is complete: protected main history, protected version tags, secret scanning alerts, push protection, private vulnerability reporting, and immutable future releases are already enabled. -- A concise public `SECURITY.md` is part of the release documentation so the in-repo security-reporting path matches the GitHub repository configuration. - -### What the repo currently supports - -- `codebase-orient` skill: user-level and project-local install for Claude Code and Codex (4 install scripts each in PS1 + sh) -- `install-codebase-orient` bootstrap skill: user-level Claude Code only (2 install scripts: PS1 + sh) -- Orientation output: `docs/ai/CODEBASE_MAP.md`, `CHANGE_SURFACES.md`, `OPEN_QUESTIONS.md` -- Dry-run / report-only mode -- Confidence labels and claim-origin labels -- No-date-only-churn rule -- Cross-file consistency rule -- Hidden-risk reporting -- Source-of-truth drift detection -- CI/deployment precision rule -- CHANGE_SURFACES mapping guidance (auth/operator UX, deployment-sensitive, docs-impact) -- Agent handoff summary block -- Instruction-layer topology mapping -- Project-local specialization (Claude Code only) -- Cheap artifact glob rule, open-question quality rule, orientation completion rule -- ASCII-only punctuation enforcement (check scripts in PS1 and sh) - -### What has been tested - -**Claude Code live-fire (no-wrapper `/codebase-orient`):** -- Normal mode orientation pass -- Dry-run mode -- No-date-only-churn behavior (verified current without rewriting) -- Project-local specialization path (`.claude/skills/codebase-orient/SKILL.md`) - -**Codex testing:** -- Codex skeptical audit completed (drove v0.3.1 contract cleanup) -- Install path contract verified -- Lifecycle differences (no bootstrap, no project-local specialization) documented - -**Install scripts - Windows PowerShell (v0.3.2, 2026-05-22):** -- All 5 install scripts tested: user/project-local for Claude Code and Codex, plus bootstrap user-level -- Installed SKILL.md matched tracked source by SHA-256 for all 5 cases -- Non-force refusal (exit 1 + message) verified for all 5 cases -- Force overwrite verified for all 5 cases -- Overlay semantics verified: injected extra file survived --force for all 5 cases -- Terminal output: no mojibake; ASCII-only rendered correctly -- README cold-reader pass: no release blocker found for Windows consumers -- ASCII punctuation check (PS1 script): exit 0, all tracked files clean -- Disposable clone remained clean after all tests - -**Install scripts - Git Bash / MSYS2 (v0.3.2, 2026-05-22):** -- All 5 install scripts tested: same matrix as PowerShell above -- 18/18 checks PASS: hash match, non-force refusal, --force overlay, extra-file survival -- ASCII punctuation check (sh script): exit 0, all tracked files clean -- Disposable clone remained clean after all tests - -**Install scripts - WSL2 Ubuntu bash on Windows (`v1.0.0-rc.6`, 2026-05-24):** -- All 5 install scripts tested from an exact public `v1.0.0-rc.6` clone at commit `98589ad3e8b7c79ff33482b749c2935332cab104` -- Fresh install, SHA-256 match, non-force refusal, `--force` overlay, and extra-file survival all PASS for all 5 cases -- ASCII punctuation check (sh script): exit 0, all tracked files clean -- Disposable recursive-copy probe PASS: nested marker copied for reusable installer source and bootstrap source -- Classification: WSL2 Ubuntu bash on Windows - validates Linux/bash installer behavior; macOS remains untested. - -**Fresh-clone simulation:** -- A disposable tagged clone was used for both PS and bash runs -- Clone was at the tagged `v0.3.2` baseline before and after -- All temp install targets used fake HOME or temp dirs; real user-level skills were not touched - -### What is intentionally not supported - -- Automatic guaranteed invocation (model-driven; explicit is the reliable path) -- Codex bootstrap installer -- Codex project-local specialization -- Hooks or CI integration -- Marketplace/plugin packaging -- Exact-sync reinstall (overlay semantics only; delete-first workaround documented) -- Source-code edits, refactors, or commits during orientation - ---- - -## B. v1.0 definition - -> "Safe to recommend to another serious developer without the maintainer babysitting install, invocation, or interpretation." - -Concretely, v1.0 means: - -1. A developer who has never used the skill can install it from a fresh clone, invoke it, and get a useful orientation pass - without reading this source repo's internals. -2. The README is complete enough that install failures can be self-diagnosed. -3. The skill description is honest about what works automatically vs what requires explicit invocation. -4. The known limitations are documented clearly enough that a user can decide whether this tool is right for their use case. -5. The canonical skill and bootstrap embedded template stay in sync - no silent drift between them. -6. The maintainer is not embarrassed by any file the user reads during normal use. - ---- - -## C. Architecture and topology - -### Intended topology - -``` -codebase-orient-skill (source repo) - | - |-- skills/codebase-orient/SKILL.md <- canonical source, single source of truth - |-- skills/install-codebase-orient/SKILL.md <- bootstrap skill source, versioned here - | - |-- scripts/install-user.{ps1,sh} -> ~/.claude/skills/codebase-orient/ - |-- scripts/install-project.{ps1,sh} -> /.claude/skills/codebase-orient/ - |-- scripts/install-codex-user.{ps1,sh} -> ~/.agents/skills/codebase-orient/ - |-- scripts/install-codex-project.{ps1,sh} -> /.agents/skills/codebase-orient/ - |-- scripts/install-bootstrap-user.{ps1,sh} -> ~/.claude/skills/install-codebase-orient/ -``` - -**Installed target (user repo after running `/install-codebase-orient`):** - -``` - - |-- .claude/skills/codebase-orient/SKILL.md <- repo-local skill (thin overlay; project-specific paths added here) - |-- docs/ai/CODEBASE_MAP.md <- generated orientation cache (non-canonical) - |-- docs/ai/CHANGE_SURFACES.md <- generated orientation cache (non-canonical) - |-- docs/ai/OPEN_QUESTIONS.md <- generated orientation cache (non-canonical) -``` - -### Layer authority - -| Layer | Authoritative for | Tracked by git | -|-------|-----------------|----------------| -| Source code and project config | Behavior and business logic | Yes | -| `SKILL.md` (canonical, this repo) | Skill behavior and rules | Yes | -| `SKILL.md` (repo-local, installed) | Project-specific discovery paths only | Optional (recommended yes) | -| `docs/ai/` files | Orientation cache for current session/agent | Optional (usually yes, but non-canonical) | -| `CLAUDE.md` / `AGENTS.md` | Project instruction layer | Yes | - -**Rules:** -- Source code and project config are always authoritative over `docs/ai/`. -- Installed `SKILL.md` copies are targets, not forks. The canonical source is `skills/codebase-orient/SKILL.md` in this repo. -- `docs/ai/` files are orientation aids. They must be verified against source before acting on them. -- Project-specific paths belong in the repo-local skill overlay. They do not belong in the canonical skill. - -### What is intentionally avoided - -- Large embedded state bundles in skills -- Generated `docs/ai/` files becoming canonical or ground truth -- Hidden project-specific state inside the repo-local skill overlay -- Sync machinery before it has been earned by real cross-project use -- Hooks or automation as defaults -- Drift between canonical skill and bootstrap embedded template becoming the normal state - ---- - -## D. v1.0 release criteria - -Each criterion must be verifiable before tagging v1.0. - -### README clarity - -- [x] Install instructions are complete for all 5 scenarios: Claude Code user, Claude Code project, Codex user, Codex project, bootstrap user -- [x] Overlay vs exact-sync semantics are documented and accurate -- [x] CWD requirement for project-local installs is documented -- [x] Codex lifecycle note is accurate (no bootstrap, no project-local specialization) -- [x] Auto-invocation reliability is stated honestly (model-driven, not guaranteed; explicit is the reliable path) -- [x] Known limitations section is present and accurate -- [x] Security review note is present and accurate - -### Install script safety - -- [x] All 10 install scripts refuse to overwrite without `-Force` / `--force` -- [x] All scripts use recursive copy and preserve subdirectory structure -- [x] All scripts use ASCII-only output (no mojibake risk) -- [x] No script writes to a path outside its documented target -- [x] Manual copy examples in README match script semantics exactly - -### Claude Code install support - -- [x] User-level install works from fresh clone on Windows (PowerShell) and macOS/Linux (bash) -- [x] Project-local install works from the target repo root -- [x] Installed skill is usable via `/codebase-orient` without editing -- [x] `/codebase-orient` produces useful output on at least 3 different repo types - -### Codex install support - -- [x] User-level install works on at least one test Codex session -- [x] Project-local install works in a target repo -- [x] Skill can be invoked explicitly and produces useful output -- [x] README Codex section is accurate for current Codex behavior - -### Bootstrap skill clarity - -- [x] Bootstrap skill description clearly distinguishes it from the plain `codebase-orient` skill -- [x] Bootstrap skill produces `.claude/skills/codebase-orient/SKILL.md` and `docs/ai/` files -- [x] Bootstrap skill embedded template is consistent with the canonical skill rules (no silent drift) -- [x] Bootstrap skill is Claude Code only - this is documented - -### Project-local artifact policy - -- [x] `.agents/` is in `.gitignore` (no Codex install artifacts tracked in source repo) -- [x] `docs/ai/` is in `.gitignore` (no generated cache tracked in source repo) -- [x] README documents recommended `.gitignore` snippets for target repos - -### Generated docs lifecycle - -- [x] No-date-only-churn rule is enforced in both canonical and bootstrap skills -- [x] Cross-file consistency rule is present in both canonical and bootstrap skills -- [x] Orientation report discipline labels each file as Created/Substantively updated/Verified current/Proposed only/Skipped -- [x] `docs/ai/` files in target repos are understood as non-canonical orientation cache - -### Source-of-truth drift checks - -- [x] Canonical skill and bootstrap embedded template have been compared and confirmed consistent within this release cycle -- [x] Any divergence between them is intentional and documented - -### ASCII punctuation check - -- [x] `scripts/check-ascii-punctuation.ps1` passes with exit 0 on current tracked files -- [x] `scripts/check-ascii-punctuation.sh` passes with exit 0 on current tracked files -- [x] Check scripts are documented in README development notes -- [x] Check has been run and passed before tagging - -### Known limitations documented - -- [x] Monorepo orientation limits documented -- [x] Auto-invocation unreliability documented -- [x] Overlay (not exact-sync) install semantics documented -- [x] Codex-only limitations documented (no bootstrap, no project-local specialization) -- [x] Orientation improves process, not correctness - documented - -### Versioning and changelog hygiene - -- [x] CHANGELOG has no Unreleased entries (all work promoted or deferred) -- [x] All tags point to correct commits -- [x] Bootstrap skill internal version reflects its actual state (currently 0.2.3, independent of repo tag) -- [x] Repo tag scheme (vMAJOR.MINOR.PATCH) is documented or implied clearly - -### Security and trust posture - -- [x] `SKILL.md` does not tell Claude to run arbitrary shell commands -- [x] `SKILL.md` does not tell Claude to modify source code during orientation -- [x] `SKILL.md` does not tell Claude to commit during orientation -- [x] Security review note in README is accurate -- [x] `SECURITY.md` is present and points reporters to GitHub private vulnerability reporting with email fallback -- [x] No install script requests elevated privileges - ---- - -## E. Test matrix - -Run these checks before tagging v1.0. Mark each as pass/fail/skip-with-reason. - -### Install tests - -| Test | Tool | Platform | Notes | -|------|------|----------|-------| -| User-level install (fresh) | Claude Code | Windows PS | install-user.ps1 | -| User-level install (fresh) | Claude Code | macOS/Linux | install-user.sh | -| User-level install (-Force overwrite) | Claude Code | Windows PS | must succeed | -| User-level install (no -Force, existing) | Claude Code | Windows PS | must refuse | -| Project-local install (fresh) | Claude Code | Windows PS | from target repo root | -| Project-local install (fresh) | Claude Code | macOS/Linux | from target repo root | -| User-level install (fresh) | Codex | Windows PS | install-codex-user.ps1 | -| User-level install (fresh) | Codex | macOS/Linux | install-codex-user.sh | -| Project-local install (fresh) | Codex | Windows PS | from target repo root | -| Project-local install (fresh) | Codex | macOS/Linux | from target repo root | -| Bootstrap user-level install | Claude Code | Windows PS | install-bootstrap-user.ps1 | -| Bootstrap user-level install | Claude Code | macOS/Linux | install-bootstrap-user.sh | - -### Post-install correctness - -| Check | Pass condition | -|-------|---------------| -| Installed SKILL.md matches tracked source | diff is clean | -| Recursive copy preserved all files | no files dropped | -| Overlay semantics: extra file in target survives Force | extra file not deleted | -| ASCII punctuation check | exit 0 | -| `git diff --check` | no whitespace errors | - -### Fresh-clone simulation - -| Check | Pass condition | -|-------|---------------| -| Clone repo to a new directory | clean state | -| Run install script without any prior install | completes, no errors | -| Invoke skill in a target repo | produces useful output | -| No prior session context assumed | result is coherent without history | - ---- - -## E1. Completed install validation runs - -Records of actual validation passes. Each row is a real test, not a plan item. - -### v0.3.2 - 2026-05-22 - Windows PowerShell - -- **Clone:** disposable tagged clone -- **Commit basis:** tagged `v0.3.2` baseline -- **Environment:** Windows, PowerShell 5.1 -- **Targets:** all temp dirs under `%TEMP%`; real user skills not touched - -| Case | Script | Result | Evidence | -|------|--------|--------|---------| -| Claude Code user-level | install-user.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | -| Claude Code project-local | install-project.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | -| Codex user-level | install-codex-user.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | -| Codex project-local | install-codex-project.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | -| Bootstrap user-level | install-bootstrap-user.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | -| ASCII punctuation check | check-ascii-punctuation.ps1 | PASS | exit 0, all tracked files clean | -| Terminal output | all scripts | PASS | no mojibake; ASCII rendered correctly | -| README cold-reader | README.md | PASS | no release blocker found for Windows consumers | -| Disposable clone state | git status | PASS | clean before and after all tests | - -### v0.3.2 - 2026-05-22 - Git Bash (MSYS2 bash 5.2, Windows) - -- **Clone:** disposable tagged clone -- **Commit basis:** tagged `v0.3.2` baseline -- **Environment:** Git Bash / MSYS2 bash 5.2.37, Windows -- **Targets:** mktemp -d (fake HOME, project-local temp dirs); real user skills not touched - -| Case | Script | Result | Evidence | -|------|--------|--------|---------| -| Claude Code user-level | install-user.sh | PASS | SHA-256 match (A1), refusal (A2), overlay (A3), force re-hash (A4) | -| Claude Code project-local | install-project.sh | PASS | SHA-256 match (B1), refusal (B2), overlay (B3) | -| Codex user-level | install-codex-user.sh | PASS | SHA-256 match (C1), refusal (C2), overlay (C3) | -| Codex project-local | install-codex-project.sh | PASS | SHA-256 match (D1), refusal (D2), overlay (D3) | -| Bootstrap user-level | install-bootstrap-user.sh | PASS | SHA-256 match (E1), refusal (E2), overlay (E3) | -| ASCII punctuation check | check-ascii-punctuation.sh | PASS | exit 0, all tracked files clean (F1) | -| Disposable clone state | git status | PASS | clean before and after all tests (G1) | -| Total | 18 checks | 18/18 PASS | 0 failures | - -**Historical note:** this Windows Git Bash run did not add a nested fixture file to prove the recursive path by test. That evidence gap was later closed by the 2026-05-24 WSL2 Ubuntu bash disposable recursive-copy probe recorded below. - -### `v1.0.0-rc.6` - 2026-05-24 - WSL2 Ubuntu bash on Windows - -- **Clone:** disposable WSL clone from `https://github.com/Shaelz/codebase-orient-skill.git` -- **Commit basis:** public tag `v1.0.0-rc.6` at `98589ad3e8b7c79ff33482b749c2935332cab104` -- **Environment:** WSL2 Ubuntu 26.04 LTS on Windows; Linux `6.6.114.1-microsoft-standard-WSL2`; bash `5.3.9(1)-release` -- **Targets:** disposable fake HOME and project-local temp dirs under the WSL test root; real WSL user skills not touched - -| Case | Script | Result | Evidence | -|------|--------|--------|---------| -| Claude Code user-level | install-user.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | -| Claude Code project-local | install-project.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | -| Codex user-level | install-codex-user.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | -| Codex project-local | install-codex-project.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | -| Bootstrap user-level | install-bootstrap-user.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | -| ASCII punctuation check | check-ascii-punctuation.sh | PASS | exit 0, all tracked text files clean | -| Recursive copy probe | disposable nested markers | PASS | nested marker copied for reusable installer source and bootstrap source | - -**Classification:** WSL2 Ubuntu bash on Windows - validates Linux/bash installer behavior; macOS remains untested. - -### v0.3.2 - 2026-05-22 - Canonical/bootstrap drift check - -- **Files compared:** `skills/codebase-orient/SKILL.md` vs embedded template in `skills/install-codebase-orient/SKILL.md` -- **Last confirmed sync before this check:** v0.3.0 (two releases prior) -- **Result:** No material unintentional drift. All major behavioral rules represented accurately. See G.3 for full detail. -- **Action taken:** None. No edits to either SKILL.md. - -### `v1.0.0-rc.6` - 2026-05-24 - Direct bootstrap runtime contract verification - -- **Classification:** PASS: PUBLIC RC.6 BOOTSTRAP RUNTIME CONTRACT VERIFIED -- **Target baseline:** clean external target repository; no pre-existing `.claude/skills/codebase-orient/SKILL.md`, no pre-existing `docs/ai/CODEBASE_MAP.md`, `docs/ai/CHANGE_SURFACES.md`, `docs/ai/OPEN_QUESTIONS.md`, no `CLAUDE.md`, and target working tree clean before invocation -- **Public/bootstrap identity verification:** public `v1.0.0-rc.6^{}` peeled to `98589ad3e8b7c79ff33482b749c2935332cab104`; installed user-level Claude Code bootstrap skill matched public `skills/install-codebase-orient/SKILL.md` byte-for-byte; both SHA-256 values were `61df8751528f5d024ccd4013475b28dfb614673e7fc348804d5cbc85b494736f` -- **Invocation:** single normal/default-mode `/install-codebase-orient` run; no dry-run, report-only, no-writes, setup-only, or staged-approval constraint -- **Observed result:** created project-local `.claude/skills/codebase-orient/SKILL.md`; created `docs/ai/CODEBASE_MAP.md`, `docs/ai/CHANGE_SURFACES.md`, and `docs/ai/OPEN_QUESTIONS.md`; did not create or modify `CLAUDE.md` because the bootstrap contract is append-only for that file when it already exists; did not modify application, source, config, or deployment files; no user intervention or non-default staged flow required -- **Formatter note:** no Markdown formatter was available in the target; formatting was skipped per the documented fallback rule and this was not treated as a failure - -### Not yet covered - -- macOS specifically remains untested. WSL2 Ubuntu bash on Windows validated the Linux/bash installer behavior alternative. - ---- - -## F. Live-fire validation matrix - -At least one pass per repo type before v1.0. Record repo type, mode, and outcome. - -| Repo type | Mode | Target | Key signals | -|-----------|------|--------|-------------| -| SvelteKit / frontend | Normal | Claude Code | Routes, server files, adapter, layout, auth surfaces | -| Laravel / PHP backend | Normal | Claude Code | Controllers, models, migrations, middleware, routes | -| Small / simple repo (< 20 files) | Normal | Claude Code | Does not over-read; output proportionate to size | -| Messy / legacy repo | Dry-run | Claude Code | Unknown labels appear; no false confidence | -| Docs-light repo (no README, sparse) | Normal | Claude Code | Unknown labels; no invented claims | -| Repo with existing AGENTS.md / CLAUDE.md | Normal | Codex | Instruction-layer topology mapped; drift detected if present | -| Repo with existing docs/ai | Normal | Claude Code | Refresh vs rewrite decision is correct; no-date-only-churn holds | -| Repo with deployment-sensitive workflows | Normal | Claude Code | Deployment-sensitive change surfaces flagged in CHANGE_SURFACES.md | - -Minimum coverage before v1.0: at least 4 of the 8 rows with a real pass, at least 1 Codex row. - ---- - -## F1. Completed live-fire passes - -Records of actual live-fire orientation passes against real repos with real findings. - -### Claude Code - External SvelteKit frontend repo A - -- **Repo type:** SvelteKit / frontend / product-flow repo -- **Agent/runtime:** Claude Code -- **Invocation:** `/codebase-orient` without a wrapper prompt -- **docs/ai existed:** Yes - recently refreshed before this pass -- **Mode:** Normal - -**Findings:** - -- Skill recognized recently refreshed `docs/ai/` and performed lightweight verification rather than a full rewrite. No-date-only-churn behavior confirmed in practice. -- Found a real cross-file consistency issue: `CODEBASE_MAP.md` still listed uncertainty items already resolved in `OPEN_QUESTIONS.md`. -- Updated project-local `.claude/skills/codebase-orient/SKILL.md` with substantive specialization improvements after the orientation pass. -- A later rerun validated the no-date-only-churn fix: date-only changes to `CHANGE_SURFACES.md` and `OPEN_QUESTIONS.md` were reverted; only substantive changes were committed in that repo. - -**Matrix rows covered:** Row 1 (SvelteKit/frontend/Claude Code), Row 7 (existing docs/ai - refresh vs rewrite correct, no-date-only-churn holds) - -**Evidence confidence:** High. Real repo, real cross-file consistency issue found, substantive changes committed. - ---- - -### Claude Code - External Laravel backend repo A - -- **Repo type:** Laravel / backend / admin / deployment-sensitive repo -- **Agent/runtime:** Claude Code -- **Invocation:** `/codebase-orient` -- **docs/ai existed:** Yes - validated rather than rewritten broadly -- **Mode:** Normal - -**Findings:** - -- Stale claim corrected: migration count 35 -> 32 (verified against source) -- Stale claim corrected: feature test count 40+ -> 38 (verified against source) -- Stale deploy-risk claim corrected: `storage:link` was listed as absent but had been added to `deploy.yml`; corresponding stale reference in `CHANGE_SURFACES.md` also corrected -- `OPEN_QUESTIONS.md` verified current / unchanged; no-date-only-churn held -- All corrections were committed in the target repo - -**Matrix rows covered:** Row 2 (Laravel/PHP backend/Claude Code), Row 8 (deployment-sensitive workflows - deployment surfaces flagged correctly) - -**Evidence confidence:** High. Real stale claims found against real source code, corrections committed. - ---- - -### Codex - codebase-orient-skill (self-orientation, supporting evidence only) - -- **Repo type:** Skill-source repo (self-referential) -- **Agent/runtime:** Codex -- **Invocation:** Explicit natural-language invocation -- **docs/ai existed:** No - created during this pass -- **Mode:** Normal - -**Observations:** - -- Project-local `.agents/skills/codebase-orient/SKILL.md` install confirmed by hash match before the session. -- Codex created the expected `docs/ai/` cache files and displayed skill behavior consistent with the skill definition. -- Driven by real content inspection of this source repo (scripts, SKILL.md files, changelogs). - -**Limitations:** - -- Self-referential repo: the skill was orienting to a repo that describes itself. -- Discovery confound: the skill body appeared later in the session thread, which may have supplemented project-local install pickup. -- Not equivalent to orienting to an unfamiliar external codebase. - -**Classification:** Supporting / limited evidence. This does NOT count as a clean external-repo Codex pass. It establishes that Codex project-local skill installation works and that Codex exhibits skill behavior. It does not satisfy any F matrix row. - -**Matrix rows covered:** None counted. Supporting evidence for Codex install-to-behavior chain only. - ---- - -### Codex - External Laravel backend repo A (deployment-sensitive, external repo) - -- **Repo type:** Laravel / backend / admin / deployment-sensitive repo (same repo, different agent) -- **Agent/runtime:** Codex -- **Invocation:** Explicit natural-language invocation -- **Skill path:** Project-local `.agents/skills/codebase-orient/SKILL.md` -- **docs/ai existed:** Yes - Claude Code orientation cache from a prior Claude Code correction pass -- **Mode:** Normal - -**Observed evidence:** - -- Codex session registry exposed `codebase-orient` at the project-local path. -- The installed skill file was opened and followed explicitly. -- Target repo confirmed as the external Laravel backend repo (not the skill-source repo). -- Codex verified the existing `docs/ai/` cache against source/config/canonical docs: - - `deploy.yml` includes `php artisan storage:link` after `migrate --force` - confirmed correct - - Migration count 32 - confirmed correct - - Feature test count 38 - confirmed correct - - Public routes match `routes/web.php` - confirmed - - Filament/admin/operator surfaces match current source/docs - confirmed - - Instruction-layer topology claims are grounded - confirmed - - CI/deploy summary matches `.github/workflows/deploy.yml` - confirmed - - `OPEN_QUESTIONS.md` remains a correct uncertainty log - confirmed -- Codex found no substantive correction needed. No changes made to `docs/ai/`. -- No date-only churn. No application code modified. -- Final target working tree contained only the untracked `.agents/` install artifact. - -**Cross-agent validation significance:** This pass demonstrates the intended cross-agent lifecycle: Claude Code oriented and corrected, Codex independently verified. The Codex session confirmed the Claude-maintained cache was accurate and held the no-date-only-churn rule (no rewrite triggered despite a full verification pass). - -**Evidence note:** Codex skill pickup relied on project-local install; a distinct UI skill-attachment click event was not independently observable from the terminal/session report. Behavioral evidence (skill followed, real verification performed against real source) is sufficient to classify this as a PASS. The acceptance bar is behavioral, not UI-event-level. - -**Matrix rows covered:** Row 6 (AGENTS.md/CLAUDE.md/Codex - instruction-layer topology mapped, Codex explicit invocation confirmed) - -**Evidence confidence:** High, with the noted UI-attachment observability caveat. - ---- - -### Claude Code -> Codex - External SvelteKit portfolio repo B - -- **Repo type:** SvelteKit / static portfolio / deployment workflow repo -- **Agent/runtime sequence:** Claude Code (orientation and cache creation/refresh) then Codex (verification and substantive update) -- **docs/ai existed at Codex pass:** Yes - created and refreshed by Claude Code in prior passes -- **Mode:** Normal (both passes) - -**Claude Code phase:** - -- Initial Claude Code dry-run found real instruction drift in `README.md` and proposed the orientation layer. -- Claude Code created and refreshed the orientation cache in two prior committed passes. - -**Codex phase:** - -- Codex ran using the project-local installed skill in the external portfolio repo. -- Codex consumed the pre-existing Claude-created `docs/ai/` cache and verified it against source/config. -- Codex found new substantive documentation drift not corrected in the Claude Code passes: - - `README.md` still described the site as single-page despite three prerendered routes. - - `README.md` described deploy as a symlink swap while the actual workflow uses release-directory upload plus rsync publish into `PUBLIC_PATH`. -- Codex substantively refreshed the orientation cache: instruction-layer mapping, docs-impact guidance, deploy smoke-check guidance, and corrected README-drift status. -- No application/source/config/deploy-behavior files changed. -- No date-only churn. No spurious rewrites. - -**Durable target-repo commit:** Documentation-only evidence commit pushed to the target repo (`CLAUDE.md`, `README.md`, and `docs/ai/*` only) - -**Final state:** Temporary `.agents/` Codex install artifact removed after evidence commit was pushed. Working tree clean and aligned with origin. - -**Cross-version wording:** Omitted. Insufficient timeline evidence to determine which version of the skill each agent used; lifecycle wording only. - -**Classification:** PASS - corroborating second external cross-agent orientation-cache lifecycle validation. This strengthens the lifecycle evidence base across a second repo family (SvelteKit portfolio vs Laravel backend). The external Laravel backend repo A already closed the required Codex live-fire preferred validation item recorded in G.5; this pass does not close a new required matrix row. - -**Matrix rows covered:** None additional. Row 1 (SvelteKit/Claude Code) and Row 6 (Codex) are already satisfied by prior passes. Recorded as supplementary run evidence only. - -**Evidence confidence:** High. Substantive drift found by Codex against real source, corrected, and pushed to the target repo. - ---- - -### Codex (user-level skill) - Legacy PHP CMS snapshot (no Git, dry-run) - -- **Repo type:** Unseen legacy PHP flat-file CMS snapshot (`GetSimple CE 3.3.22`); mixed runtime/live-like artifacts; no `.git`; no `docs/ai/` -- **Agent/runtime:** Codex using the user-level installed skill -- **docs/ai existed:** No; none created (dry-run mode, no target files modified) -- **Mode:** Dry-run only - -**Blind discovery (no advance description of target contents given):** - -- Codex classified the folder as a legacy PHP flat-file CMS snapshot, likely a mixed live/deployed working snapshot rather than the canonical source repo. -- Runtime/framework identified: GetSimple CE 3.3.22. -- Meaningful surfaces discovered from source: - - Root `index.php` bootstrap/render flow - - `data/pages/*.xml` content source - - Admin page-save/sitemap workflow - - Active theme `theme/Seascape2-main` - - File-backed visitor counter - - Custom admin/operator pages - - Enabled plugin policy and plugin layer - - Competition results/team roster JSON workflows - - `.htaccess`, writable content/auth, backups/uploads/plugin internals flagged as security/deploy-sensitive surfaces - -**Substantive finding:** - -- `LOCAL_MAINTENANCE.md` states that checked-in `PRETTYURLS` is off. -- `data/other/website.xml` has `1`. -- Runtime code honors the XML value; sitemap output uses pretty URLs. -- Real maintenance-doc vs config contradiction found and documented. - -**Safety-boundary behavior:** - -- Codex correctly recommended keeping this target dry-run only: live-like data, runtime artifacts, uploads, logs, backups, no Git history, possible snapshot/deployed-mirror status. -- Codex recommended locating the canonical maintained source repo before creating `docs/ai/*`. -- A possible canonical maintained source location was suggested by the snapshot context, but it was not confirmed during this dry-run. Finding that source remains optional project follow-up, not a `codebase-orient-skill` v1 requirement. - -**Final files modified:** None. - -**Classification:** PASS - blind dry-run generalization in an unseen no-Git legacy snapshot. Satisfies Row 4 (messy/legacy / dry-run). Note: original matrix plan listed Claude Code as the target agent; Codex was used. Behavioral requirements (unknown labels surfaced, no false confidence, no spurious writes, correct safety-boundary recommendation) were met regardless of which agent executed the run. - -**Evidence confidence:** High for blind dry-run generalization and safety-boundary behavior. The "unseen" precondition was structurally enforced: no advance description, no Git, no docs/ai, no project-local skill install. - ---- - -### Live-fire coverage summary - -| Matrix row | Status | Evidence source | -|------------|--------|-----------------| -| Row 1: SvelteKit/frontend / Claude Code | PASS | External SvelteKit frontend repo A | -| Row 2: Laravel/PHP backend / Claude Code | PASS | External Laravel backend repo A | -| Row 3: Small/simple repo / Claude Code | NOT YET | - | -| Row 4: Messy/legacy / dry-run / Claude Code | PASS (Codex dry-run) | Legacy PHP CMS snapshot (no Git) | -| Row 5: Docs-light repo / Claude Code | NOT YET | - | -| Row 6: AGENTS.md/CLAUDE.md / Codex | PASS | External Laravel backend repo A (Codex, 2026-05-22) | -| Row 7: Existing docs/ai / Claude Code | PASS | External SvelteKit frontend repo A | -| Row 8: Deployment-sensitive / Claude Code | PASS | External Laravel backend repo A | - -**Matrix rows satisfied: 6 / 8.** Minimum count requirement (4) met. Codex row requirement met. -**External live-fire runs recorded: 5.** Claude Code in one external SvelteKit/frontend repo; Claude Code in one external Laravel/backend/deployment-sensitive repo; Codex in that same external Laravel repo; Claude Code -> Codex sequence in one external SvelteKit/static-portfolio/deployment-workflow repo; Codex dry-run in one no-Git legacy PHP CMS snapshot. - -**Publication status for v1.0:** No unresolved validation blocker remains. All live-fire matrix requirements are satisfied, and publication execution is an external GitHub-state action rather than an additional source-content change. - -### Supplementary onboarding evidence - public `rc.4` Codex delegated-install exploration - -- Classification: supplementary evidence only. This was not an independent external-user pass and does not close G.2. -- What it showed: - - A coding agent acting on behalf of a user selected the recommended Codex user-level installation route from the README. - - Existing-install refusal and later overlay refresh behavior worked as documented. - - The agent then blurred together installation, installed-skill discovery/invocation, and immediately running the workflow until explicit invocation was surfaced more clearly. - - After explicit invocation was surfaced, the resulting orientation behavior was useful and matched expectations. -- Product implication: the public onboarding contract needed to treat agent-delegated installation as a first-class path, make overwrite decisions explicit for the agent, and separate installation from invocation more clearly before rerunning the external validation gate. - -### External validation evidence - public `rc.5` human-through-agent attempt - -- Classification: FAIL / BLOCKER. This was a genuine independent external validation attempt and it did not satisfy G.2. -- What happened: - - A new Claude Code session received only a minimal natural-language install request plus the public tagged `rc.5` URL. - - The agent reasonably chose the supported project-local Claude Code route because the request was to install the skill "in this project." - - The failure was installation integrity, not route selection: the agent then began an invalid approximate manual-install path that would have reconstructed installed `SKILL.md` content from fetched non-authoritative material rather than from an exact local tagged source plus the checked-in installer. - - The attempt was interrupted before any installed skill file was written. Only empty install directories were created in the target project, and no tracked target-project change was observed. -- Product implication: agent-delegated installation must require exact tagged source acquisition plus the checked-in installer, and must stop and ask rather than approximate installed instruction files from transformed or partial content. - -### External validation evidence - public `rc.6` human-through-agent rerun - -- Classification: PASS. G.2 is resolved. -- What happened: - - A new Claude Code session received only the minimal natural-language install request plus the public tagged `rc.6` URL. - - The target baseline was clean before the rerun because the empty directories left by the interrupted `rc.5` attempt had already been removed. - - The agent correctly interpreted "in this project" as the supported project-local Claude Code install route. - - The agent followed the exact-install contract: it recognized the need for an exact tagged source, cloned `v1.0.0-rc.6` locally, ran the checked-in project-local installer from the target project context, and did not reconstruct or manually rewrite `SKILL.md`. - - The install completed successfully, produced `.claude/skills/codebase-orient/SKILL.md`, reported `/codebase-orient` as the explicit invocation step, and did not run orientation or create `docs/ai/*` during the install request. - - Existing-install overwrite behavior was not exercised because the target baseline was clean; this does not count against G.2. -- Product implication: the `rc.6` exact-install integrity rule corrected the `rc.5` failure mode and validated the public agent-delegated install contract. - ---- - -## G. v1.0 blockers and pre-v1 tasks - -Based on current evidence. Not speculative. - -### Hard blockers (must complete before v1.0 tag) - -1. ~~**Fresh-clone install validation**~~ - RESOLVED 2026-05-24. Full install matrix tested from disposable tagged/public clones on Windows PowerShell 5.1, Windows Git Bash/MSYS2, and WSL2 Ubuntu bash on Windows. All 5 install scripts PASS on the two Windows environments and on the WSL2 Ubuntu bash Linux/bash validation pass against public `v1.0.0-rc.6`. The Linux/bash alternative in D/J is now satisfied by that WSL2 Ubuntu evidence; macOS specifically remains untested. See E1. - -2. ~~**At least one independent human-through-agent validation pass**~~ - RESOLVED 2026-05-23. An external tester used a new Claude Code session with only a minimal install request plus the public tagged `v1.0.0-rc.6` URL. The agent chose the supported project-local route, obtained the exact tagged source, ran the checked-in installer from the target project context, avoided manual `SKILL.md` reconstruction, installed successfully, reported `/codebase-orient` as the explicit invocation step, and did not run orientation during install. The earlier maintainer README cold-reader pass and the supplementary `rc.4` Codex delegated-install exploration remain supplementary only, and the public `rc.5` attempt remains recorded as the failing pre-fix external run. - - **Validation handoff (send only this setup context):** - - Send the tester only the GitHub repo or release link for `codebase-orient-skill`. - - Tell them to have their coding agent install the appropriate skill for the tool they are already using by following the README. - - Do not explain the repo architecture, which skill to choose, or which install path should win before they attempt the install. - - **Ask the tester to record:** - - tool used by the human and by the coding agent - - OS and shell used - - which install route the agent chose - - whether installation succeeded - - whether the agent knew which skill to install - - whether the agent surfaced any existing-install overwrite decision before changing an existing install - - whether explicit invocation guidance was clear after install - - where they hesitated or needed help - - whether any unexpected files, writes, or errors appeared - - **PASS:** - - The agent correctly selects the reusable `codebase-orient` skill for normal use. - - The agent chooses the appropriate supported install route for the tool in use. - - The agent does not overwrite an existing install without surfacing the decision first. - - Installation succeeds from the README contract without maintainer coaching and without reconstructing installed skill content from fetched, rendered, summarized, or partial source material. - - Explicit invocation guidance is clear after install. - - If orientation is actually run, the agent accurately reports the expected writes. - - **FAIL / feedback-worthy hesitation:** - - The agent chooses the bootstrap skill unintentionally. - - The agent cannot distinguish Claude Code vs Codex install paths. - - The agent overwrites an existing install without first surfacing the decision. - - The agent attempts to reconstruct or approximate installed `SKILL.md` content instead of using an exact tagged source plus the checked-in installer. - - Install, discovery/invocation, and workflow execution are blurred together in a way that confuses the user. - - The tester is blocked by README ambiguity or needs maintainer coaching. - - **Status rule:** - - RESOLVED 2026-05-23 by the public `rc.6` external retest. - - A maintainer-run or exploratory agent simulation remains supplementary evidence only and does not replace the independent external-user-through-agent test. - -3. ~~**Canonical skill vs bootstrap embedded template drift check**~~ - RESOLVED 2026-05-22. Full section-by-section comparison completed. No material unintentional drift found. Details: - - **Accurate in embedded template:** docs/ai non-canonical cache framing, docs-as-hypotheses and source authority rules, instruction-layer topology note, no-date-only-churn rule, orientation report discipline (full label set), agent handoff summary, all 9 confidence claim-origin labels, hidden-risk reporting, source-of-truth drift detection, CI/deployment precision rule, read-depth heuristic (including path-existence and small-file-read subsections), cheap artifact glob rule, open question quality rule, cross-file consistency rule, CHANGE_SURFACES mapping guidance (all three categories), project-local specialization rule with thin-overlay framing. - - **Minor non-material wording differences (no action taken):** two reinforcing sentences in orientation report discipline absent from embedded template; one skip-condition bullet and one token-aware bullet absent; docs-impact inline example phrase absent. None affect behavioral outcomes. - - **Intentionally excluded from embedded template:** SvelteKit/Laravel framework-specific discovery probes (bootstrap handles its own discovery pass; noted in the embedded template sync note at line 182); trigger phrases in when-to-use (handled by frontmatter `description`); bootstrap-specific sections (purpose, trigger phrases, creates table, hard rules, idempotency) are bootstrap-only by design. - - No edits to either SKILL.md were made. Embedded template is fit for v1.0. - -4. ~~**Bootstrap runtime evidence**~~ - RESOLVED 2026-05-24. Direct normal-mode runtime validation was completed against public `v1.0.0-rc.6` in a clean external target repository. The installed user-level Claude Code bootstrap skill matched the public `rc.6` bootstrap source byte-for-byte (`61df8751528f5d024ccd4013475b28dfb614673e7fc348804d5cbc85b494736f` on both sides), a single `/install-codebase-orient` invocation created the expected project-local `.claude/skills/codebase-orient/SKILL.md` plus all three `docs/ai/*` files, did not create or modify `CLAUDE.md` when absent, did not modify application/source/config/deployment files, required no user intervention, and handled missing Markdown formatter support via the documented fallback rule. See E1. - -### Preferred but not hard blockers - -5. ~~**One clean Codex live-fire pass on an external repo**~~ - RESOLVED 2026-05-22. External Codex live-fire pass completed in the external Laravel/backend/deployment-sensitive repo. Codex project-local skill (`.agents/skills/codebase-orient/SKILL.md`) was exposed and followed; existing Claude-maintained `docs/ai/` files were verified against source with no substantive corrections needed; no-date-only-churn held; no application code modified. Cross-agent cache lifecycle (Claude Code orients and corrects, Codex verifies) demonstrated. See F1 for full evidence record. - -6. ~~**Overlay install semantics decision**~~ - RESOLVED 2026-05-22. Overlay semantics are confirmed acceptable for v1.0. The extra-file survival test in the install matrix proves the behavior matches the documented contract (overlay, not exact-sync). Delete-first workaround is documented in README. No exact-sync tooling will be added before v1.0. Decision recorded. - -7. ~~**CHANGELOG promotion**~~ - RESOLVED 2026-05-24. `CHANGELOG.md` already has no Unreleased entries, so no further promotion step remains before tagging `v1.0.0`. - ---- - -## H. Explicit non-goals before v1.0 - -These are not being built. If a future conversation proposes one, check here first. - -- Marketplace / plugin packaging -- Hooks or automation as defaults (not earned yet) -- Full accessibility audit behavior (surfaced in CHANGE_SURFACES, not executed) -- Full deployment verification behavior (noted, not executed) -- Safe-cleanup or refactor execution during orientation -- Skeptical diff-review skill -- Guaranteed automatic invocation (model-driven; cannot guarantee) -- Codex bootstrap installer (no confirmed real user need yet) -- Exact-sync reinstall script (delete-first workaround is sufficient for v1) -- Per-project versioning of installed skill overlays -- Telemetry or usage tracking - ---- - -## I. Known risks - -### Source-of-truth drift: canonical skill vs bootstrap embedded template - -`skills/install-codebase-orient/SKILL.md` contains an embedded template that is supposed to stay in sync with the rules in `skills/codebase-orient/SKILL.md`. There is no automated sync check. Manual drift checks have been done at each release. Risk: a rule change in the canonical skill is not reflected in the bootstrap embedded template, and the bootstrap generates stale project-local skills. - -Mitigation: drift check is a release criterion (see D and G). - -### README / install script mismatch - -The README documents install paths and expected behavior. If a script is changed without updating the README, users follow wrong instructions. Risk is low given the small surface area, but it increases with each new install variant. - -Mitigation: install script test matrix includes manual copy example verification. - -### Agent-delegated install integrity failure - -An agent that reads public repo content through a transformed channel may try to reconstruct an installed skill file manually instead of acquiring the exact tagged source and running the checked-in installer. That would compromise instruction-file integrity even if the chosen install scope is otherwise reasonable. - -Mitigation: README now states the exact-source integrity rule explicitly, and the public `rc.6` retest proved an external agent can follow it. - -### Historical rc drift during validation - -`v1.0.0-rc.1` was tagged before the README onboarding rewrite and the project-local installer `.gitignore` correction. `v1.0.0-rc.2` carried those corrections but had incomplete README mutation-scope and trust-posture wording discovered by a pre-validation contract audit. `v1.0.0-rc.3` corrected those statements in the pre-public lineage, but the original private/pre-rewrite `rc.3` candidate then failed the exposure audit because tracked docs and reachable history still disclosed private validation identifiers and local paths. The retained sanitized `v1.0.0-rc.3` tag is now historical only. `v1.0.0-rc.4` is the prior sanitized candidate, `v1.0.0-rc.5` is historical evidence of the failed exact-install integrity gate, and `v1.0.0-rc.6` is the validated candidate that forms the basis for final `v1.0.0`. Risk: a tester uses an older tag and encounters guidance or release-decision context that has already been superseded. - -Mitigation: keep prior RC tags only if they are sanitized and clearly presented as historical pre-public candidates, and treat `v1.0.0-rc.6` as the validated basis for final `v1.0.0`. Do not use `rc.1`, `rc.2`, or `rc.3` for external validation, do not treat the `rc.4` delegated-install exploration as the gate-closing pass, and do not treat the interrupted `rc.5` run as passing evidence. - -### Over-invocation due to trigger description - -The `codebase-orient` frontmatter `description` is rich with trigger phrases. This is intentional for discovery. Risk: Claude invokes orientation on tiny tasks where the user expected a direct answer, burning tokens unnecessarily. - -Mitigation: "When to skip" section is explicit. User can also explicitly say "no orientation needed." - -### Under-invocation (implicit invocation is model-driven) - -Claude may not invoke the skill automatically even when the trigger description matches. This is a platform behavior, not a bug. Risk: users expect automatic orientation and are surprised when it does not happen. - -Mitigation: README and SKILL.md both document that explicit invocation is the reliable path. - -### Generated docs becoming stale - -`docs/ai/` files in a target repo can lag behind the actual codebase. A session that relies on stale `docs/ai/` without refreshing may produce incorrect orientation claims. - -Mitigation: staleness rule is in the skill; the orientation report discipline distinguishes verified-current from refreshed. - -### Date-only churn returning - -A future model might update `Last refreshed:` without substantive content changes, producing noisy git diffs. This was a real problem before v0.2.0. - -Mitigation: no-date-only-churn rule is in both the canonical skill and bootstrap embedded template. - -### Local overlay artifacts becoming quasi-canonical - -A repo-local `.claude/skills/codebase-orient/SKILL.md` that accumulates heavy project-specific content may start to drift from the canonical skill in ways that are hard to untangle later. Users may treat the local overlay as the primary source. - -Mitigation: the thin-overlay framing is explicit in the skill. Project-specific paths are meant to go at the bottom, clearly marked. The canonical rules are not meant to be overwritten. - -### Scope creep before v1.0 - -Each live-fire pass discovers something useful but tangential. The risk is that pre-v1 tasks accumulate, the bar keeps moving, and v1.0 is never tagged. - -Mitigation: this document defines a fixed bar. If a new finding does not block any criterion in section D, it goes in a future release. - ---- - -## J. Definition of done for v1.0 - -Final checklist. All items must be checkable pass before tagging v1.0. - -- [x] All D-section release criteria verified (README, install scripts, Claude Code, Codex, bootstrap, artifacts, generated docs, drift, ASCII, limitations, versioning, security) -- [x] E-section test matrix: all critical install paths checked (at minimum: Claude Code user-level on Windows PowerShell + a native macOS/Linux bash environment, project-local on one platform, Codex user-level on one platform, bootstrap user-level on one platform) -- [x] F-section live-fire: at least 4 repo types with real passes, at least 1 Codex row -- [x] G-section hard blockers resolved: fresh-clone install validated, independent human-through-agent validation completed, canonical/bootstrap drift check recorded, bootstrap runtime evidence recorded -- [x] G-section overlay decision recorded explicitly -- [x] CHANGELOG has no Unreleased entries -- [x] `scripts/check-ascii-punctuation.ps1` exits 0 on current tracked files -- [x] `git diff --check` is clean -- [x] `git status` is clean with no uncommitted changes - -Publication-execution note: alignment of the local final release commit with `origin/main` immediately before tagging is an execution-time verification recorded during publication, not a tagged-content checkbox. - ---- - -## K. External publication state - -No substantive blocker remains. The live-fire matrix requirements remain fully satisfied, the WSL2 Ubuntu bash Linux/bash validation is complete, the direct bootstrap runtime contract is now verified against public `v1.0.0-rc.6`, and `rc.6` remains the validated release candidate and final release basis. - -**K.1 - External publication procedure** - -This record captures the complete source-content requirements and substantive validation basis for `v1.0.0`. Publication execution is external GitHub state: pushing `main`, creating and pushing the annotated protected `v1.0.0` tag, creating the GitHub Release, and verifying the public sidebar, release, tag, archive, and related public surfaces. The final execution report and GitHub state are authoritative for whether those actions completed. No post-tag source edit is required merely to record successful publication. +This compatibility pointer stays at the old path so existing repository links continue to resolve. +It is not the active roadmap for post-v1 work. diff --git a/docs/releases/v1.0-validation-record.md b/docs/releases/v1.0-validation-record.md new file mode 100644 index 0000000..6800cda --- /dev/null +++ b/docs/releases/v1.0-validation-record.md @@ -0,0 +1,837 @@ +# v1.0.0 Validation Record - codebase-orient-skill + +> Frozen historical validation record for `v1.0.0`. +> This is not the active roadmap for future development. +> Post-v1 work should not mutate the recorded historical pass/fail evidence except to correct factual archival errors. + +Current release status: all substantive validation gates are resolved; this document records the validated release basis and final tagged-artifact content for `v1.0.0`. Push, tag, GitHub Release, and public-surface verification are external publication actions recorded in the final execution report and GitHub state | Final target: v1.0.0 | Updated: 2026-05-24 +Last validation: 2026-05-24 (public `v1.0.0-rc.6` at `98589ad3e8b7c79ff33482b749c2935332cab104` passed the WSL2 Ubuntu bash installer matrix and the direct bootstrap runtime contract verification; `rc.6` remains the validated public behavioral basis for final `v1.0.0`, passed independent human-through-agent validation, and is unchanged from the public candidate that was validated; `rc.5` is the prior public agent-delegated onboarding candidate and failed the external validation gate on exact-install integrity; `rc.4` remains the prior published sanitized candidate; the governance hardening pass is complete) +Final release note: relative to public `rc.6`, final `v1.0.0` preserves the runtime-validated behavior and adds release metadata/evidence reconciliation only: the stable `CHANGELOG.md` release entry, the final release-plan evidence/status record, removal of one stale non-behavioral repository-version reference from the bootstrap skill's internal changelog note, and the corresponding bootstrap internal metadata-version increment to `0.2.3`. No bootstrap behavior, embedded template rule, installer behavior, or runtime contract changed after `rc.6` validation. + +--- + +## A. Current status + +### Release and tag state + +| Tag | Summary | +|-----|---------| +| v1.0.0 | Final stable release record. This document captures the validated source content for `v1.0.0`; push, tag, GitHub Release, and public verification are external publication actions rather than additional source-content changes. | +| v1.0.0-rc.6 | Validated release candidate. Passed independent human-through-agent validation and confirmed the exact-install integrity contract introduced after the `rc.5` failure. | +| v1.0.0-rc.5 | Prior public agent-delegated onboarding candidate. Failed the external validation gate on exact-install integrity before any installed skill file was written. | +| v1.0.0-rc.4 | Published sanitized candidate. Records the pre-public sanitation decision and the corrected manual-install contract that preceded the delegated-install onboarding correction. | +| v1.0.0-rc.3 | Historical pre-public contract-correction candidate. In retained sanitized history, this tag no longer carries the removed disclosures, but it is not the candidate to use for external cold-user validation. | +| v1.0.0-rc.2 | Historical pre-public candidate: README onboarding rewrite + fixed project-local installer `.gitignore` guidance. | +| v1.0.0-rc.1 | Historical pre-public cold-user candidate; README polished; 6/8 live-fire rows satisfied. | +| v0.3.2 | ASCII punctuation normalization + check scripts. | +| v0.3.1 | Install contract cleanup, artifact policy, Codex parity docs. | +| v0.3.0 | Orientation surface mapping and authority-boundary cleanup. | +| v0.2.0 | Dual-runtime skill, bootstrap, no-date-only-churn, invocation reliability. | +| v0.1.x | Initial skill, Codex install scripts, bootstrap skill source. | + +`v1.0.0-rc.1` and `v1.0.0-rc.2` remain historical pre-public candidates. `rc.2` introduced the README onboarding rewrite and project-local installer `.gitignore` correction but carried incomplete README mutation-scope and trust-posture wording. `rc.3` corrected those statements but was then blocked by the pre-public exposure audit because tracked docs and reachable pre-public history still contained private validation identifiers and maintainer-local paths. `rc.4` is the prior published sanitized candidate, and a supplementary Codex delegated-install exploration against public `rc.4` showed that agent-facing onboarding needed one more focused correction before the independent gate could be rerun. `rc.5` then became the first public agent-delegated onboarding candidate, but the independent external validation attempt failed on exact-install integrity. `rc.6` passed the rerun and is the validated basis for final `v1.0.0`. Do not use `rc.1`, `rc.2`, or `rc.3` for external validation, do not treat the `rc.4` exploratory agent run as the independent gate pass, and do not treat the interrupted `rc.5` run as passing evidence. + +### Publication and governance state + +- Public repository publication and the pre-v1 sanitation pass are complete; `v1.0.0-rc.6` is the validated release candidate and final release basis, and all substantive validation gates for `v1.0.0` are now resolved. +- Repository governance hardening is complete: protected main history, protected version tags, secret scanning alerts, push protection, private vulnerability reporting, and immutable future releases are already enabled. +- A concise public `SECURITY.md` is part of the release documentation so the in-repo security-reporting path matches the GitHub repository configuration. + +### What the repo currently supports + +- `codebase-orient` skill: user-level and project-local install for Claude Code and Codex (4 install scripts each in PS1 + sh) +- `install-codebase-orient` bootstrap skill: user-level Claude Code only (2 install scripts: PS1 + sh) +- Orientation output: `docs/ai/CODEBASE_MAP.md`, `CHANGE_SURFACES.md`, `OPEN_QUESTIONS.md` +- Dry-run / report-only mode +- Confidence labels and claim-origin labels +- No-date-only-churn rule +- Cross-file consistency rule +- Hidden-risk reporting +- Source-of-truth drift detection +- CI/deployment precision rule +- CHANGE_SURFACES mapping guidance (auth/operator UX, deployment-sensitive, docs-impact) +- Agent handoff summary block +- Instruction-layer topology mapping +- Project-local specialization (Claude Code only) +- Cheap artifact glob rule, open-question quality rule, orientation completion rule +- ASCII-only punctuation enforcement (check scripts in PS1 and sh) + +### What has been tested + +**Claude Code live-fire (no-wrapper `/codebase-orient`):** +- Normal mode orientation pass +- Dry-run mode +- No-date-only-churn behavior (verified current without rewriting) +- Project-local specialization path (`.claude/skills/codebase-orient/SKILL.md`) + +**Codex testing:** +- Codex skeptical audit completed (drove v0.3.1 contract cleanup) +- Install path contract verified +- Lifecycle differences (no bootstrap, no project-local specialization) documented + +**Install scripts - Windows PowerShell (v0.3.2, 2026-05-22):** +- All 5 install scripts tested: user/project-local for Claude Code and Codex, plus bootstrap user-level +- Installed SKILL.md matched tracked source by SHA-256 for all 5 cases +- Non-force refusal (exit 1 + message) verified for all 5 cases +- Force overwrite verified for all 5 cases +- Overlay semantics verified: injected extra file survived --force for all 5 cases +- Terminal output: no mojibake; ASCII-only rendered correctly +- README cold-reader pass: no release blocker found for Windows consumers +- ASCII punctuation check (PS1 script): exit 0, all tracked files clean +- Disposable clone remained clean after all tests + +**Install scripts - Git Bash / MSYS2 (v0.3.2, 2026-05-22):** +- All 5 install scripts tested: same matrix as PowerShell above +- 18/18 checks PASS: hash match, non-force refusal, --force overlay, extra-file survival +- ASCII punctuation check (sh script): exit 0, all tracked files clean +- Disposable clone remained clean after all tests + +**Install scripts - WSL2 Ubuntu bash on Windows (`v1.0.0-rc.6`, 2026-05-24):** +- All 5 install scripts tested from an exact public `v1.0.0-rc.6` clone at commit `98589ad3e8b7c79ff33482b749c2935332cab104` +- Fresh install, SHA-256 match, non-force refusal, `--force` overlay, and extra-file survival all PASS for all 5 cases +- ASCII punctuation check (sh script): exit 0, all tracked files clean +- Disposable recursive-copy probe PASS: nested marker copied for reusable installer source and bootstrap source +- Classification: WSL2 Ubuntu bash on Windows - validates Linux/bash installer behavior; macOS remains untested. + +**Fresh-clone simulation:** +- A disposable tagged clone was used for both PS and bash runs +- Clone was at the tagged `v0.3.2` baseline before and after +- All temp install targets used fake HOME or temp dirs; real user-level skills were not touched + +### What is intentionally not supported + +- Automatic guaranteed invocation (model-driven; explicit is the reliable path) +- Codex bootstrap installer +- Codex project-local specialization +- Hooks or CI integration +- Marketplace/plugin packaging +- Exact-sync reinstall (overlay semantics only; delete-first workaround documented) +- Source-code edits, refactors, or commits during orientation + +--- + +## B. v1.0 definition + +> "Safe to recommend to another serious developer without the maintainer babysitting install, invocation, or interpretation." + +Concretely, v1.0 means: + +1. A developer who has never used the skill can install it from a fresh clone, invoke it, and get a useful orientation pass - without reading this source repo's internals. +2. The README is complete enough that install failures can be self-diagnosed. +3. The skill description is honest about what works automatically vs what requires explicit invocation. +4. The known limitations are documented clearly enough that a user can decide whether this tool is right for their use case. +5. The canonical skill and bootstrap embedded template stay in sync - no silent drift between them. +6. The maintainer is not embarrassed by any file the user reads during normal use. + +--- + +## C. Architecture and topology + +### Intended topology + +``` +codebase-orient-skill (source repo) + | + |-- skills/codebase-orient/SKILL.md <- canonical source, single source of truth + |-- skills/install-codebase-orient/SKILL.md <- bootstrap skill source, versioned here + | + |-- scripts/install-user.{ps1,sh} -> ~/.claude/skills/codebase-orient/ + |-- scripts/install-project.{ps1,sh} -> /.claude/skills/codebase-orient/ + |-- scripts/install-codex-user.{ps1,sh} -> ~/.agents/skills/codebase-orient/ + |-- scripts/install-codex-project.{ps1,sh} -> /.agents/skills/codebase-orient/ + |-- scripts/install-bootstrap-user.{ps1,sh} -> ~/.claude/skills/install-codebase-orient/ +``` + +**Installed target (user repo after running `/install-codebase-orient`):** + +``` + + |-- .claude/skills/codebase-orient/SKILL.md <- repo-local skill (thin overlay; project-specific paths added here) + |-- docs/ai/CODEBASE_MAP.md <- generated orientation cache (non-canonical) + |-- docs/ai/CHANGE_SURFACES.md <- generated orientation cache (non-canonical) + |-- docs/ai/OPEN_QUESTIONS.md <- generated orientation cache (non-canonical) +``` + +### Layer authority + +| Layer | Authoritative for | Tracked by git | +|-------|-----------------|----------------| +| Source code and project config | Behavior and business logic | Yes | +| `SKILL.md` (canonical, this repo) | Skill behavior and rules | Yes | +| `SKILL.md` (repo-local, installed) | Project-specific discovery paths only | Optional (recommended yes) | +| `docs/ai/` files | Orientation cache for current session/agent | Optional (usually yes, but non-canonical) | +| `CLAUDE.md` / `AGENTS.md` | Project instruction layer | Yes | + +**Rules:** +- Source code and project config are always authoritative over `docs/ai/`. +- Installed `SKILL.md` copies are targets, not forks. The canonical source is `skills/codebase-orient/SKILL.md` in this repo. +- `docs/ai/` files are orientation aids. They must be verified against source before acting on them. +- Project-specific paths belong in the repo-local skill overlay. They do not belong in the canonical skill. + +### What is intentionally avoided + +- Large embedded state bundles in skills +- Generated `docs/ai/` files becoming canonical or ground truth +- Hidden project-specific state inside the repo-local skill overlay +- Sync machinery before it has been earned by real cross-project use +- Hooks or automation as defaults +- Drift between canonical skill and bootstrap embedded template becoming the normal state + +--- + +## D. v1.0 release criteria + +Each criterion must be verifiable before tagging v1.0. + +### README clarity + +- [x] Install instructions are complete for all 5 scenarios: Claude Code user, Claude Code project, Codex user, Codex project, bootstrap user +- [x] Overlay vs exact-sync semantics are documented and accurate +- [x] CWD requirement for project-local installs is documented +- [x] Codex lifecycle note is accurate (no bootstrap, no project-local specialization) +- [x] Auto-invocation reliability is stated honestly (model-driven, not guaranteed; explicit is the reliable path) +- [x] Known limitations section is present and accurate +- [x] Security review note is present and accurate + +### Install script safety + +- [x] All 10 install scripts refuse to overwrite without `-Force` / `--force` +- [x] All scripts use recursive copy and preserve subdirectory structure +- [x] All scripts use ASCII-only output (no mojibake risk) +- [x] No script writes to a path outside its documented target +- [x] Manual copy examples in README match script semantics exactly + +### Claude Code install support + +- [x] User-level install works from fresh clone on Windows (PowerShell) and macOS/Linux (bash) +- [x] Project-local install works from the target repo root +- [x] Installed skill is usable via `/codebase-orient` without editing +- [x] `/codebase-orient` produces useful output on at least 3 different repo types + +### Codex install support + +- [x] User-level install works on at least one test Codex session +- [x] Project-local install works in a target repo +- [x] Skill can be invoked explicitly and produces useful output +- [x] README Codex section is accurate for current Codex behavior + +### Bootstrap skill clarity + +- [x] Bootstrap skill description clearly distinguishes it from the plain `codebase-orient` skill +- [x] Bootstrap skill produces `.claude/skills/codebase-orient/SKILL.md` and `docs/ai/` files +- [x] Bootstrap skill embedded template is consistent with the canonical skill rules (no silent drift) +- [x] Bootstrap skill is Claude Code only - this is documented + +### Project-local artifact policy + +- [x] `.agents/` is in `.gitignore` (no Codex install artifacts tracked in source repo) +- [x] `docs/ai/` is in `.gitignore` (no generated cache tracked in source repo) +- [x] README documents recommended `.gitignore` snippets for target repos + +### Generated docs lifecycle + +- [x] No-date-only-churn rule is enforced in both canonical and bootstrap skills +- [x] Cross-file consistency rule is present in both canonical and bootstrap skills +- [x] Orientation report discipline labels each file as Created/Substantively updated/Verified current/Proposed only/Skipped +- [x] `docs/ai/` files in target repos are understood as non-canonical orientation cache + +### Source-of-truth drift checks + +- [x] Canonical skill and bootstrap embedded template have been compared and confirmed consistent within this release cycle +- [x] Any divergence between them is intentional and documented + +### ASCII punctuation check + +- [x] `scripts/check-ascii-punctuation.ps1` passes with exit 0 on current tracked files +- [x] `scripts/check-ascii-punctuation.sh` passes with exit 0 on current tracked files +- [x] Check scripts are documented in README development notes +- [x] Check has been run and passed before tagging + +### Known limitations documented + +- [x] Monorepo orientation limits documented +- [x] Auto-invocation unreliability documented +- [x] Overlay (not exact-sync) install semantics documented +- [x] Codex-only limitations documented (no bootstrap, no project-local specialization) +- [x] Orientation improves process, not correctness - documented + +### Versioning and changelog hygiene + +- [x] CHANGELOG has no Unreleased entries (all work promoted or deferred) +- [x] All tags point to correct commits +- [x] Bootstrap skill internal version reflects its actual state (currently 0.2.3, independent of repo tag) +- [x] Repo tag scheme (vMAJOR.MINOR.PATCH) is documented or implied clearly + +### Security and trust posture + +- [x] `SKILL.md` does not tell Claude to run arbitrary shell commands +- [x] `SKILL.md` does not tell Claude to modify source code during orientation +- [x] `SKILL.md` does not tell Claude to commit during orientation +- [x] Security review note in README is accurate +- [x] `SECURITY.md` is present and points reporters to GitHub private vulnerability reporting with email fallback +- [x] No install script requests elevated privileges + +--- + +## E. Test matrix + +Run these checks before tagging v1.0. Mark each as pass/fail/skip-with-reason. + +### Install tests + +| Test | Tool | Platform | Notes | +|------|------|----------|-------| +| User-level install (fresh) | Claude Code | Windows PS | install-user.ps1 | +| User-level install (fresh) | Claude Code | macOS/Linux | install-user.sh | +| User-level install (-Force overwrite) | Claude Code | Windows PS | must succeed | +| User-level install (no -Force, existing) | Claude Code | Windows PS | must refuse | +| Project-local install (fresh) | Claude Code | Windows PS | from target repo root | +| Project-local install (fresh) | Claude Code | macOS/Linux | from target repo root | +| User-level install (fresh) | Codex | Windows PS | install-codex-user.ps1 | +| User-level install (fresh) | Codex | macOS/Linux | install-codex-user.sh | +| Project-local install (fresh) | Codex | Windows PS | from target repo root | +| Project-local install (fresh) | Codex | macOS/Linux | from target repo root | +| Bootstrap user-level install | Claude Code | Windows PS | install-bootstrap-user.ps1 | +| Bootstrap user-level install | Claude Code | macOS/Linux | install-bootstrap-user.sh | + +### Post-install correctness + +| Check | Pass condition | +|-------|---------------| +| Installed SKILL.md matches tracked source | diff is clean | +| Recursive copy preserved all files | no files dropped | +| Overlay semantics: extra file in target survives Force | extra file not deleted | +| ASCII punctuation check | exit 0 | +| `git diff --check` | no whitespace errors | + +### Fresh-clone simulation + +| Check | Pass condition | +|-------|---------------| +| Clone repo to a new directory | clean state | +| Run install script without any prior install | completes, no errors | +| Invoke skill in a target repo | produces useful output | +| No prior session context assumed | result is coherent without history | + +--- + +## E1. Completed install validation runs + +Records of actual validation passes. Each row is a real test, not a plan item. + +### v0.3.2 - 2026-05-22 - Windows PowerShell + +- **Clone:** disposable tagged clone +- **Commit basis:** tagged `v0.3.2` baseline +- **Environment:** Windows, PowerShell 5.1 +- **Targets:** all temp dirs under `%TEMP%`; real user skills not touched + +| Case | Script | Result | Evidence | +|------|--------|--------|---------| +| Claude Code user-level | install-user.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | +| Claude Code project-local | install-project.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | +| Codex user-level | install-codex-user.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | +| Codex project-local | install-codex-project.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | +| Bootstrap user-level | install-bootstrap-user.ps1 | PASS | SHA-256 match, refusal, --force overlay, extra-file survived | +| ASCII punctuation check | check-ascii-punctuation.ps1 | PASS | exit 0, all tracked files clean | +| Terminal output | all scripts | PASS | no mojibake; ASCII rendered correctly | +| README cold-reader | README.md | PASS | no release blocker found for Windows consumers | +| Disposable clone state | git status | PASS | clean before and after all tests | + +### v0.3.2 - 2026-05-22 - Git Bash (MSYS2 bash 5.2, Windows) + +- **Clone:** disposable tagged clone +- **Commit basis:** tagged `v0.3.2` baseline +- **Environment:** Git Bash / MSYS2 bash 5.2.37, Windows +- **Targets:** mktemp -d (fake HOME, project-local temp dirs); real user skills not touched + +| Case | Script | Result | Evidence | +|------|--------|--------|---------| +| Claude Code user-level | install-user.sh | PASS | SHA-256 match (A1), refusal (A2), overlay (A3), force re-hash (A4) | +| Claude Code project-local | install-project.sh | PASS | SHA-256 match (B1), refusal (B2), overlay (B3) | +| Codex user-level | install-codex-user.sh | PASS | SHA-256 match (C1), refusal (C2), overlay (C3) | +| Codex project-local | install-codex-project.sh | PASS | SHA-256 match (D1), refusal (D2), overlay (D3) | +| Bootstrap user-level | install-bootstrap-user.sh | PASS | SHA-256 match (E1), refusal (E2), overlay (E3) | +| ASCII punctuation check | check-ascii-punctuation.sh | PASS | exit 0, all tracked files clean (F1) | +| Disposable clone state | git status | PASS | clean before and after all tests (G1) | +| Total | 18 checks | 18/18 PASS | 0 failures | + +**Historical note:** this Windows Git Bash run did not add a nested fixture file to prove the recursive path by test. That evidence gap was later closed by the 2026-05-24 WSL2 Ubuntu bash disposable recursive-copy probe recorded below. + +### `v1.0.0-rc.6` - 2026-05-24 - WSL2 Ubuntu bash on Windows + +- **Clone:** disposable WSL clone from `https://github.com/Shaelz/codebase-orient-skill.git` +- **Commit basis:** public tag `v1.0.0-rc.6` at `98589ad3e8b7c79ff33482b749c2935332cab104` +- **Environment:** WSL2 Ubuntu 26.04 LTS on Windows; Linux `6.6.114.1-microsoft-standard-WSL2`; bash `5.3.9(1)-release` +- **Targets:** disposable fake HOME and project-local temp dirs under the WSL test root; real WSL user skills not touched + +| Case | Script | Result | Evidence | +|------|--------|--------|---------| +| Claude Code user-level | install-user.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | +| Claude Code project-local | install-project.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | +| Codex user-level | install-codex-user.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | +| Codex project-local | install-codex-project.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | +| Bootstrap user-level | install-bootstrap-user.sh | PASS | fresh install, SHA-256 match, refusal, `--force` overlay, extra-file survived | +| ASCII punctuation check | check-ascii-punctuation.sh | PASS | exit 0, all tracked text files clean | +| Recursive copy probe | disposable nested markers | PASS | nested marker copied for reusable installer source and bootstrap source | + +**Classification:** WSL2 Ubuntu bash on Windows - validates Linux/bash installer behavior; macOS remains untested. + +### v0.3.2 - 2026-05-22 - Canonical/bootstrap drift check + +- **Files compared:** `skills/codebase-orient/SKILL.md` vs embedded template in `skills/install-codebase-orient/SKILL.md` +- **Last confirmed sync before this check:** v0.3.0 (two releases prior) +- **Result:** No material unintentional drift. All major behavioral rules represented accurately. See G.3 for full detail. +- **Action taken:** None. No edits to either SKILL.md. + +### `v1.0.0-rc.6` - 2026-05-24 - Direct bootstrap runtime contract verification + +- **Classification:** PASS: PUBLIC RC.6 BOOTSTRAP RUNTIME CONTRACT VERIFIED +- **Target baseline:** clean external target repository; no pre-existing `.claude/skills/codebase-orient/SKILL.md`, no pre-existing `docs/ai/CODEBASE_MAP.md`, `docs/ai/CHANGE_SURFACES.md`, `docs/ai/OPEN_QUESTIONS.md`, no `CLAUDE.md`, and target working tree clean before invocation +- **Public/bootstrap identity verification:** public `v1.0.0-rc.6^{}` peeled to `98589ad3e8b7c79ff33482b749c2935332cab104`; installed user-level Claude Code bootstrap skill matched public `skills/install-codebase-orient/SKILL.md` byte-for-byte; both SHA-256 values were `61df8751528f5d024ccd4013475b28dfb614673e7fc348804d5cbc85b494736f` +- **Invocation:** single normal/default-mode `/install-codebase-orient` run; no dry-run, report-only, no-writes, setup-only, or staged-approval constraint +- **Observed result:** created project-local `.claude/skills/codebase-orient/SKILL.md`; created `docs/ai/CODEBASE_MAP.md`, `docs/ai/CHANGE_SURFACES.md`, and `docs/ai/OPEN_QUESTIONS.md`; did not create or modify `CLAUDE.md` because the bootstrap contract is append-only for that file when it already exists; did not modify application, source, config, or deployment files; no user intervention or non-default staged flow required +- **Formatter note:** no Markdown formatter was available in the target; formatting was skipped per the documented fallback rule and this was not treated as a failure + +### Not yet covered + +- macOS specifically remains untested. WSL2 Ubuntu bash on Windows validated the Linux/bash installer behavior alternative. + +--- + +## F. Live-fire validation matrix + +At least one pass per repo type before v1.0. Record repo type, mode, and outcome. + +| Repo type | Mode | Target | Key signals | +|-----------|------|--------|-------------| +| SvelteKit / frontend | Normal | Claude Code | Routes, server files, adapter, layout, auth surfaces | +| Laravel / PHP backend | Normal | Claude Code | Controllers, models, migrations, middleware, routes | +| Small / simple repo (< 20 files) | Normal | Claude Code | Does not over-read; output proportionate to size | +| Messy / legacy repo | Dry-run | Claude Code | Unknown labels appear; no false confidence | +| Docs-light repo (no README, sparse) | Normal | Claude Code | Unknown labels; no invented claims | +| Repo with existing AGENTS.md / CLAUDE.md | Normal | Codex | Instruction-layer topology mapped; drift detected if present | +| Repo with existing docs/ai | Normal | Claude Code | Refresh vs rewrite decision is correct; no-date-only-churn holds | +| Repo with deployment-sensitive workflows | Normal | Claude Code | Deployment-sensitive change surfaces flagged in CHANGE_SURFACES.md | + +Minimum coverage before v1.0: at least 4 of the 8 rows with a real pass, at least 1 Codex row. + +--- + +## F1. Completed live-fire passes + +Records of actual live-fire orientation passes against real repos with real findings. + +### Claude Code - External SvelteKit frontend repo A + +- **Repo type:** SvelteKit / frontend / product-flow repo +- **Agent/runtime:** Claude Code +- **Invocation:** `/codebase-orient` without a wrapper prompt +- **docs/ai existed:** Yes - recently refreshed before this pass +- **Mode:** Normal + +**Findings:** + +- Skill recognized recently refreshed `docs/ai/` and performed lightweight verification rather than a full rewrite. No-date-only-churn behavior confirmed in practice. +- Found a real cross-file consistency issue: `CODEBASE_MAP.md` still listed uncertainty items already resolved in `OPEN_QUESTIONS.md`. +- Updated project-local `.claude/skills/codebase-orient/SKILL.md` with substantive specialization improvements after the orientation pass. +- A later rerun validated the no-date-only-churn fix: date-only changes to `CHANGE_SURFACES.md` and `OPEN_QUESTIONS.md` were reverted; only substantive changes were committed in that repo. + +**Matrix rows covered:** Row 1 (SvelteKit/frontend/Claude Code), Row 7 (existing docs/ai - refresh vs rewrite correct, no-date-only-churn holds) + +**Evidence confidence:** High. Real repo, real cross-file consistency issue found, substantive changes committed. + +--- + +### Claude Code - External Laravel backend repo A + +- **Repo type:** Laravel / backend / admin / deployment-sensitive repo +- **Agent/runtime:** Claude Code +- **Invocation:** `/codebase-orient` +- **docs/ai existed:** Yes - validated rather than rewritten broadly +- **Mode:** Normal + +**Findings:** + +- Stale claim corrected: migration count 35 -> 32 (verified against source) +- Stale claim corrected: feature test count 40+ -> 38 (verified against source) +- Stale deploy-risk claim corrected: `storage:link` was listed as absent but had been added to `deploy.yml`; corresponding stale reference in `CHANGE_SURFACES.md` also corrected +- `OPEN_QUESTIONS.md` verified current / unchanged; no-date-only-churn held +- All corrections were committed in the target repo + +**Matrix rows covered:** Row 2 (Laravel/PHP backend/Claude Code), Row 8 (deployment-sensitive workflows - deployment surfaces flagged correctly) + +**Evidence confidence:** High. Real stale claims found against real source code, corrections committed. + +--- + +### Codex - codebase-orient-skill (self-orientation, supporting evidence only) + +- **Repo type:** Skill-source repo (self-referential) +- **Agent/runtime:** Codex +- **Invocation:** Explicit natural-language invocation +- **docs/ai existed:** No - created during this pass +- **Mode:** Normal + +**Observations:** + +- Project-local `.agents/skills/codebase-orient/SKILL.md` install confirmed by hash match before the session. +- Codex created the expected `docs/ai/` cache files and displayed skill behavior consistent with the skill definition. +- Driven by real content inspection of this source repo (scripts, SKILL.md files, changelogs). + +**Limitations:** + +- Self-referential repo: the skill was orienting to a repo that describes itself. +- Discovery confound: the skill body appeared later in the session thread, which may have supplemented project-local install pickup. +- Not equivalent to orienting to an unfamiliar external codebase. + +**Classification:** Supporting / limited evidence. This does NOT count as a clean external-repo Codex pass. It establishes that Codex project-local skill installation works and that Codex exhibits skill behavior. It does not satisfy any F matrix row. + +**Matrix rows covered:** None counted. Supporting evidence for Codex install-to-behavior chain only. + +--- + +### Codex - External Laravel backend repo A (deployment-sensitive, external repo) + +- **Repo type:** Laravel / backend / admin / deployment-sensitive repo (same repo, different agent) +- **Agent/runtime:** Codex +- **Invocation:** Explicit natural-language invocation +- **Skill path:** Project-local `.agents/skills/codebase-orient/SKILL.md` +- **docs/ai existed:** Yes - Claude Code orientation cache from a prior Claude Code correction pass +- **Mode:** Normal + +**Observed evidence:** + +- Codex session registry exposed `codebase-orient` at the project-local path. +- The installed skill file was opened and followed explicitly. +- Target repo confirmed as the external Laravel backend repo (not the skill-source repo). +- Codex verified the existing `docs/ai/` cache against source/config/canonical docs: + - `deploy.yml` includes `php artisan storage:link` after `migrate --force` - confirmed correct + - Migration count 32 - confirmed correct + - Feature test count 38 - confirmed correct + - Public routes match `routes/web.php` - confirmed + - Filament/admin/operator surfaces match current source/docs - confirmed + - Instruction-layer topology claims are grounded - confirmed + - CI/deploy summary matches `.github/workflows/deploy.yml` - confirmed + - `OPEN_QUESTIONS.md` remains a correct uncertainty log - confirmed +- Codex found no substantive correction needed. No changes made to `docs/ai/`. +- No date-only churn. No application code modified. +- Final target working tree contained only the untracked `.agents/` install artifact. + +**Cross-agent validation significance:** This pass demonstrates the intended cross-agent lifecycle: Claude Code oriented and corrected, Codex independently verified. The Codex session confirmed the Claude-maintained cache was accurate and held the no-date-only-churn rule (no rewrite triggered despite a full verification pass). + +**Evidence note:** Codex skill pickup relied on project-local install; a distinct UI skill-attachment click event was not independently observable from the terminal/session report. Behavioral evidence (skill followed, real verification performed against real source) is sufficient to classify this as a PASS. The acceptance bar is behavioral, not UI-event-level. + +**Matrix rows covered:** Row 6 (AGENTS.md/CLAUDE.md/Codex - instruction-layer topology mapped, Codex explicit invocation confirmed) + +**Evidence confidence:** High, with the noted UI-attachment observability caveat. + +--- + +### Claude Code -> Codex - External SvelteKit portfolio repo B + +- **Repo type:** SvelteKit / static portfolio / deployment workflow repo +- **Agent/runtime sequence:** Claude Code (orientation and cache creation/refresh) then Codex (verification and substantive update) +- **docs/ai existed at Codex pass:** Yes - created and refreshed by Claude Code in prior passes +- **Mode:** Normal (both passes) + +**Claude Code phase:** + +- Initial Claude Code dry-run found real instruction drift in `README.md` and proposed the orientation layer. +- Claude Code created and refreshed the orientation cache in two prior committed passes. + +**Codex phase:** + +- Codex ran using the project-local installed skill in the external portfolio repo. +- Codex consumed the pre-existing Claude-created `docs/ai/` cache and verified it against source/config. +- Codex found new substantive documentation drift not corrected in the Claude Code passes: + - `README.md` still described the site as single-page despite three prerendered routes. + - `README.md` described deploy as a symlink swap while the actual workflow uses release-directory upload plus rsync publish into `PUBLIC_PATH`. +- Codex substantively refreshed the orientation cache: instruction-layer mapping, docs-impact guidance, deploy smoke-check guidance, and corrected README-drift status. +- No application/source/config/deploy-behavior files changed. +- No date-only churn. No spurious rewrites. + +**Durable target-repo commit:** Documentation-only evidence commit pushed to the target repo (`CLAUDE.md`, `README.md`, and `docs/ai/*` only) + +**Final state:** Temporary `.agents/` Codex install artifact removed after evidence commit was pushed. Working tree clean and aligned with origin. + +**Cross-version wording:** Omitted. Insufficient timeline evidence to determine which version of the skill each agent used; lifecycle wording only. + +**Classification:** PASS - corroborating second external cross-agent orientation-cache lifecycle validation. This strengthens the lifecycle evidence base across a second repo family (SvelteKit portfolio vs Laravel backend). The external Laravel backend repo A already closed the required Codex live-fire preferred validation item recorded in G.5; this pass does not close a new required matrix row. + +**Matrix rows covered:** None additional. Row 1 (SvelteKit/Claude Code) and Row 6 (Codex) are already satisfied by prior passes. Recorded as supplementary run evidence only. + +**Evidence confidence:** High. Substantive drift found by Codex against real source, corrected, and pushed to the target repo. + +--- + +### Codex (user-level skill) - Legacy PHP CMS snapshot (no Git, dry-run) + +- **Repo type:** Unseen legacy PHP flat-file CMS snapshot (`GetSimple CE 3.3.22`); mixed runtime/live-like artifacts; no `.git`; no `docs/ai/` +- **Agent/runtime:** Codex using the user-level installed skill +- **docs/ai existed:** No; none created (dry-run mode, no target files modified) +- **Mode:** Dry-run only + +**Blind discovery (no advance description of target contents given):** + +- Codex classified the folder as a legacy PHP flat-file CMS snapshot, likely a mixed live/deployed working snapshot rather than the canonical source repo. +- Runtime/framework identified: GetSimple CE 3.3.22. +- Meaningful surfaces discovered from source: + - Root `index.php` bootstrap/render flow + - `data/pages/*.xml` content source + - Admin page-save/sitemap workflow + - Active theme `theme/Seascape2-main` + - File-backed visitor counter + - Custom admin/operator pages + - Enabled plugin policy and plugin layer + - Competition results/team roster JSON workflows + - `.htaccess`, writable content/auth, backups/uploads/plugin internals flagged as security/deploy-sensitive surfaces + +**Substantive finding:** + +- `LOCAL_MAINTENANCE.md` states that checked-in `PRETTYURLS` is off. +- `data/other/website.xml` has `1`. +- Runtime code honors the XML value; sitemap output uses pretty URLs. +- Real maintenance-doc vs config contradiction found and documented. + +**Safety-boundary behavior:** + +- Codex correctly recommended keeping this target dry-run only: live-like data, runtime artifacts, uploads, logs, backups, no Git history, possible snapshot/deployed-mirror status. +- Codex recommended locating the canonical maintained source repo before creating `docs/ai/*`. +- A possible canonical maintained source location was suggested by the snapshot context, but it was not confirmed during this dry-run. Finding that source remains optional project follow-up, not a `codebase-orient-skill` v1 requirement. + +**Final files modified:** None. + +**Classification:** PASS - blind dry-run generalization in an unseen no-Git legacy snapshot. Satisfies Row 4 (messy/legacy / dry-run). Note: original matrix plan listed Claude Code as the target agent; Codex was used. Behavioral requirements (unknown labels surfaced, no false confidence, no spurious writes, correct safety-boundary recommendation) were met regardless of which agent executed the run. + +**Evidence confidence:** High for blind dry-run generalization and safety-boundary behavior. The "unseen" precondition was structurally enforced: no advance description, no Git, no docs/ai, no project-local skill install. + +--- + +### Live-fire coverage summary + +| Matrix row | Status | Evidence source | +|------------|--------|-----------------| +| Row 1: SvelteKit/frontend / Claude Code | PASS | External SvelteKit frontend repo A | +| Row 2: Laravel/PHP backend / Claude Code | PASS | External Laravel backend repo A | +| Row 3: Small/simple repo / Claude Code | NOT YET | - | +| Row 4: Messy/legacy / dry-run / Claude Code | PASS (Codex dry-run) | Legacy PHP CMS snapshot (no Git) | +| Row 5: Docs-light repo / Claude Code | NOT YET | - | +| Row 6: AGENTS.md/CLAUDE.md / Codex | PASS | External Laravel backend repo A (Codex, 2026-05-22) | +| Row 7: Existing docs/ai / Claude Code | PASS | External SvelteKit frontend repo A | +| Row 8: Deployment-sensitive / Claude Code | PASS | External Laravel backend repo A | + +**Matrix rows satisfied: 6 / 8.** Minimum count requirement (4) met. Codex row requirement met. +**External live-fire runs recorded: 5.** Claude Code in one external SvelteKit/frontend repo; Claude Code in one external Laravel/backend/deployment-sensitive repo; Codex in that same external Laravel repo; Claude Code -> Codex sequence in one external SvelteKit/static-portfolio/deployment-workflow repo; Codex dry-run in one no-Git legacy PHP CMS snapshot. + +**Publication status for v1.0:** No unresolved validation blocker remains. All live-fire matrix requirements are satisfied, and publication execution is an external GitHub-state action rather than an additional source-content change. + +### Supplementary onboarding evidence - public `rc.4` Codex delegated-install exploration + +- Classification: supplementary evidence only. This was not an independent external-user pass and does not close G.2. +- What it showed: + - A coding agent acting on behalf of a user selected the recommended Codex user-level installation route from the README. + - Existing-install refusal and later overlay refresh behavior worked as documented. + - The agent then blurred together installation, installed-skill discovery/invocation, and immediately running the workflow until explicit invocation was surfaced more clearly. + - After explicit invocation was surfaced, the resulting orientation behavior was useful and matched expectations. +- Product implication: the public onboarding contract needed to treat agent-delegated installation as a first-class path, make overwrite decisions explicit for the agent, and separate installation from invocation more clearly before rerunning the external validation gate. + +### External validation evidence - public `rc.5` human-through-agent attempt + +- Classification: FAIL / BLOCKER. This was a genuine independent external validation attempt and it did not satisfy G.2. +- What happened: + - A new Claude Code session received only a minimal natural-language install request plus the public tagged `rc.5` URL. + - The agent reasonably chose the supported project-local Claude Code route because the request was to install the skill "in this project." + - The failure was installation integrity, not route selection: the agent then began an invalid approximate manual-install path that would have reconstructed installed `SKILL.md` content from fetched non-authoritative material rather than from an exact local tagged source plus the checked-in installer. + - The attempt was interrupted before any installed skill file was written. Only empty install directories were created in the target project, and no tracked target-project change was observed. +- Product implication: agent-delegated installation must require exact tagged source acquisition plus the checked-in installer, and must stop and ask rather than approximate installed instruction files from transformed or partial content. + +### External validation evidence - public `rc.6` human-through-agent rerun + +- Classification: PASS. G.2 is resolved. +- What happened: + - A new Claude Code session received only the minimal natural-language install request plus the public tagged `rc.6` URL. + - The target baseline was clean before the rerun because the empty directories left by the interrupted `rc.5` attempt had already been removed. + - The agent correctly interpreted "in this project" as the supported project-local Claude Code install route. + - The agent followed the exact-install contract: it recognized the need for an exact tagged source, cloned `v1.0.0-rc.6` locally, ran the checked-in project-local installer from the target project context, and did not reconstruct or manually rewrite `SKILL.md`. + - The install completed successfully, produced `.claude/skills/codebase-orient/SKILL.md`, reported `/codebase-orient` as the explicit invocation step, and did not run orientation or create `docs/ai/*` during the install request. + - Existing-install overwrite behavior was not exercised because the target baseline was clean; this does not count against G.2. +- Product implication: the `rc.6` exact-install integrity rule corrected the `rc.5` failure mode and validated the public agent-delegated install contract. + +--- + +## G. v1.0 blockers and pre-v1 tasks + +Based on current evidence. Not speculative. + +### Hard blockers (must complete before v1.0 tag) + +1. ~~**Fresh-clone install validation**~~ - RESOLVED 2026-05-24. Full install matrix tested from disposable tagged/public clones on Windows PowerShell 5.1, Windows Git Bash/MSYS2, and WSL2 Ubuntu bash on Windows. All 5 install scripts PASS on the two Windows environments and on the WSL2 Ubuntu bash Linux/bash validation pass against public `v1.0.0-rc.6`. The Linux/bash alternative in D/J is now satisfied by that WSL2 Ubuntu evidence; macOS specifically remains untested. See E1. + +2. ~~**At least one independent human-through-agent validation pass**~~ - RESOLVED 2026-05-23. An external tester used a new Claude Code session with only a minimal install request plus the public tagged `v1.0.0-rc.6` URL. The agent chose the supported project-local route, obtained the exact tagged source, ran the checked-in installer from the target project context, avoided manual `SKILL.md` reconstruction, installed successfully, reported `/codebase-orient` as the explicit invocation step, and did not run orientation during install. The earlier maintainer README cold-reader pass and the supplementary `rc.4` Codex delegated-install exploration remain supplementary only, and the public `rc.5` attempt remains recorded as the failing pre-fix external run. + + **Validation handoff (send only this setup context):** + - Send the tester only the GitHub repo or release link for `codebase-orient-skill`. + - Tell them to have their coding agent install the appropriate skill for the tool they are already using by following the README. + - Do not explain the repo architecture, which skill to choose, or which install path should win before they attempt the install. + + **Ask the tester to record:** + - tool used by the human and by the coding agent + - OS and shell used + - which install route the agent chose + - whether installation succeeded + - whether the agent knew which skill to install + - whether the agent surfaced any existing-install overwrite decision before changing an existing install + - whether explicit invocation guidance was clear after install + - where they hesitated or needed help + - whether any unexpected files, writes, or errors appeared + + **PASS:** + - The agent correctly selects the reusable `codebase-orient` skill for normal use. + - The agent chooses the appropriate supported install route for the tool in use. + - The agent does not overwrite an existing install without surfacing the decision first. + - Installation succeeds from the README contract without maintainer coaching and without reconstructing installed skill content from fetched, rendered, summarized, or partial source material. + - Explicit invocation guidance is clear after install. + - If orientation is actually run, the agent accurately reports the expected writes. + + **FAIL / feedback-worthy hesitation:** + - The agent chooses the bootstrap skill unintentionally. + - The agent cannot distinguish Claude Code vs Codex install paths. + - The agent overwrites an existing install without first surfacing the decision. + - The agent attempts to reconstruct or approximate installed `SKILL.md` content instead of using an exact tagged source plus the checked-in installer. + - Install, discovery/invocation, and workflow execution are blurred together in a way that confuses the user. + - The tester is blocked by README ambiguity or needs maintainer coaching. + + **Status rule:** + - RESOLVED 2026-05-23 by the public `rc.6` external retest. + - A maintainer-run or exploratory agent simulation remains supplementary evidence only and does not replace the independent external-user-through-agent test. + +3. ~~**Canonical skill vs bootstrap embedded template drift check**~~ - RESOLVED 2026-05-22. Full section-by-section comparison completed. No material unintentional drift found. Details: + + **Accurate in embedded template:** docs/ai non-canonical cache framing, docs-as-hypotheses and source authority rules, instruction-layer topology note, no-date-only-churn rule, orientation report discipline (full label set), agent handoff summary, all 9 confidence claim-origin labels, hidden-risk reporting, source-of-truth drift detection, CI/deployment precision rule, read-depth heuristic (including path-existence and small-file-read subsections), cheap artifact glob rule, open question quality rule, cross-file consistency rule, CHANGE_SURFACES mapping guidance (all three categories), project-local specialization rule with thin-overlay framing. + + **Minor non-material wording differences (no action taken):** two reinforcing sentences in orientation report discipline absent from embedded template; one skip-condition bullet and one token-aware bullet absent; docs-impact inline example phrase absent. None affect behavioral outcomes. + + **Intentionally excluded from embedded template:** SvelteKit/Laravel framework-specific discovery probes (bootstrap handles its own discovery pass; noted in the embedded template sync note at line 182); trigger phrases in when-to-use (handled by frontmatter `description`); bootstrap-specific sections (purpose, trigger phrases, creates table, hard rules, idempotency) are bootstrap-only by design. + + No edits to either SKILL.md were made. Embedded template is fit for v1.0. + +4. ~~**Bootstrap runtime evidence**~~ - RESOLVED 2026-05-24. Direct normal-mode runtime validation was completed against public `v1.0.0-rc.6` in a clean external target repository. The installed user-level Claude Code bootstrap skill matched the public `rc.6` bootstrap source byte-for-byte (`61df8751528f5d024ccd4013475b28dfb614673e7fc348804d5cbc85b494736f` on both sides), a single `/install-codebase-orient` invocation created the expected project-local `.claude/skills/codebase-orient/SKILL.md` plus all three `docs/ai/*` files, did not create or modify `CLAUDE.md` when absent, did not modify application/source/config/deployment files, required no user intervention, and handled missing Markdown formatter support via the documented fallback rule. See E1. + +### Preferred but not hard blockers + +5. ~~**One clean Codex live-fire pass on an external repo**~~ - RESOLVED 2026-05-22. External Codex live-fire pass completed in the external Laravel/backend/deployment-sensitive repo. Codex project-local skill (`.agents/skills/codebase-orient/SKILL.md`) was exposed and followed; existing Claude-maintained `docs/ai/` files were verified against source with no substantive corrections needed; no-date-only-churn held; no application code modified. Cross-agent cache lifecycle (Claude Code orients and corrects, Codex verifies) demonstrated. See F1 for full evidence record. + +6. ~~**Overlay install semantics decision**~~ - RESOLVED 2026-05-22. Overlay semantics are confirmed acceptable for v1.0. The extra-file survival test in the install matrix proves the behavior matches the documented contract (overlay, not exact-sync). Delete-first workaround is documented in README. No exact-sync tooling will be added before v1.0. Decision recorded. + +7. ~~**CHANGELOG promotion**~~ - RESOLVED 2026-05-24. `CHANGELOG.md` already has no Unreleased entries, so no further promotion step remains before tagging `v1.0.0`. + +--- + +## H. Explicit non-goals before v1.0 + +These are not being built. If a future conversation proposes one, check here first. + +- Marketplace / plugin packaging +- Hooks or automation as defaults (not earned yet) +- Full accessibility audit behavior (surfaced in CHANGE_SURFACES, not executed) +- Full deployment verification behavior (noted, not executed) +- Safe-cleanup or refactor execution during orientation +- Skeptical diff-review skill +- Guaranteed automatic invocation (model-driven; cannot guarantee) +- Codex bootstrap installer (no confirmed real user need yet) +- Exact-sync reinstall script (delete-first workaround is sufficient for v1) +- Per-project versioning of installed skill overlays +- Telemetry or usage tracking + +--- + +## I. Known risks + +### Source-of-truth drift: canonical skill vs bootstrap embedded template + +`skills/install-codebase-orient/SKILL.md` contains an embedded template that is supposed to stay in sync with the rules in `skills/codebase-orient/SKILL.md`. There is no automated sync check. Manual drift checks have been done at each release. Risk: a rule change in the canonical skill is not reflected in the bootstrap embedded template, and the bootstrap generates stale project-local skills. + +Mitigation: drift check is a release criterion (see D and G). + +### README / install script mismatch + +The README documents install paths and expected behavior. If a script is changed without updating the README, users follow wrong instructions. Risk is low given the small surface area, but it increases with each new install variant. + +Mitigation: install script test matrix includes manual copy example verification. + +### Agent-delegated install integrity failure + +An agent that reads public repo content through a transformed channel may try to reconstruct an installed skill file manually instead of acquiring the exact tagged source and running the checked-in installer. That would compromise instruction-file integrity even if the chosen install scope is otherwise reasonable. + +Mitigation: README now states the exact-source integrity rule explicitly, and the public `rc.6` retest proved an external agent can follow it. + +### Historical rc drift during validation + +`v1.0.0-rc.1` was tagged before the README onboarding rewrite and the project-local installer `.gitignore` correction. `v1.0.0-rc.2` carried those corrections but had incomplete README mutation-scope and trust-posture wording discovered by a pre-validation contract audit. `v1.0.0-rc.3` corrected those statements in the pre-public lineage, but the original private/pre-rewrite `rc.3` candidate then failed the exposure audit because tracked docs and reachable history still disclosed private validation identifiers and local paths. The retained sanitized `v1.0.0-rc.3` tag is now historical only. `v1.0.0-rc.4` is the prior sanitized candidate, `v1.0.0-rc.5` is historical evidence of the failed exact-install integrity gate, and `v1.0.0-rc.6` is the validated candidate that forms the basis for final `v1.0.0`. Risk: a tester uses an older tag and encounters guidance or release-decision context that has already been superseded. + +Mitigation: keep prior RC tags only if they are sanitized and clearly presented as historical pre-public candidates, and treat `v1.0.0-rc.6` as the validated basis for final `v1.0.0`. Do not use `rc.1`, `rc.2`, or `rc.3` for external validation, do not treat the `rc.4` delegated-install exploration as the gate-closing pass, and do not treat the interrupted `rc.5` run as passing evidence. + +### Over-invocation due to trigger description + +The `codebase-orient` frontmatter `description` is rich with trigger phrases. This is intentional for discovery. Risk: Claude invokes orientation on tiny tasks where the user expected a direct answer, burning tokens unnecessarily. + +Mitigation: "When to skip" section is explicit. User can also explicitly say "no orientation needed." + +### Under-invocation (implicit invocation is model-driven) + +Claude may not invoke the skill automatically even when the trigger description matches. This is a platform behavior, not a bug. Risk: users expect automatic orientation and are surprised when it does not happen. + +Mitigation: README and SKILL.md both document that explicit invocation is the reliable path. + +### Generated docs becoming stale + +`docs/ai/` files in a target repo can lag behind the actual codebase. A session that relies on stale `docs/ai/` without refreshing may produce incorrect orientation claims. + +Mitigation: staleness rule is in the skill; the orientation report discipline distinguishes verified-current from refreshed. + +### Date-only churn returning + +A future model might update `Last refreshed:` without substantive content changes, producing noisy git diffs. This was a real problem before v0.2.0. + +Mitigation: no-date-only-churn rule is in both the canonical skill and bootstrap embedded template. + +### Local overlay artifacts becoming quasi-canonical + +A repo-local `.claude/skills/codebase-orient/SKILL.md` that accumulates heavy project-specific content may start to drift from the canonical skill in ways that are hard to untangle later. Users may treat the local overlay as the primary source. + +Mitigation: the thin-overlay framing is explicit in the skill. Project-specific paths are meant to go at the bottom, clearly marked. The canonical rules are not meant to be overwritten. + +### Scope creep before v1.0 + +Each live-fire pass discovers something useful but tangential. The risk is that pre-v1 tasks accumulate, the bar keeps moving, and v1.0 is never tagged. + +Mitigation: this document defines a fixed bar. If a new finding does not block any criterion in section D, it goes in a future release. + +--- + +## J. Definition of done for v1.0 + +Final checklist. All items must be checkable pass before tagging v1.0. + +- [x] All D-section release criteria verified (README, install scripts, Claude Code, Codex, bootstrap, artifacts, generated docs, drift, ASCII, limitations, versioning, security) +- [x] E-section test matrix: all critical install paths checked (at minimum: Claude Code user-level on Windows PowerShell + a native macOS/Linux bash environment, project-local on one platform, Codex user-level on one platform, bootstrap user-level on one platform) +- [x] F-section live-fire: at least 4 repo types with real passes, at least 1 Codex row +- [x] G-section hard blockers resolved: fresh-clone install validated, independent human-through-agent validation completed, canonical/bootstrap drift check recorded, bootstrap runtime evidence recorded +- [x] G-section overlay decision recorded explicitly +- [x] CHANGELOG has no Unreleased entries +- [x] `scripts/check-ascii-punctuation.ps1` exits 0 on current tracked files +- [x] `git diff --check` is clean +- [x] `git status` is clean with no uncommitted changes + +Publication-execution note: alignment of the local final release commit with `origin/main` immediately before tagging is an execution-time verification recorded during publication, not a tagged-content checkbox. + +--- + +## K. External publication state + +No substantive blocker remains. The live-fire matrix requirements remain fully satisfied, the WSL2 Ubuntu bash Linux/bash validation is complete, the direct bootstrap runtime contract is now verified against public `v1.0.0-rc.6`, and `rc.6` remains the validated release candidate and final release basis. + +**K.1 - External publication procedure** + +This record captures the complete source-content requirements and substantive validation basis for `v1.0.0`. Publication execution is external GitHub state: pushing `main`, creating and pushing the annotated protected `v1.0.0` tag, creating the GitHub Release, and verifying the public sidebar, release, tag, archive, and related public surfaces. The final execution report and GitHub state are authoritative for whether those actions completed. No post-tag source edit is required merely to record successful publication. diff --git a/scripts/check-shared-rule-drift.ps1 b/scripts/check-shared-rule-drift.ps1 new file mode 100644 index 0000000..fdfa7fa --- /dev/null +++ b/scripts/check-shared-rule-drift.ps1 @@ -0,0 +1,441 @@ +#Requires -Version 5.1 +<# +.SYNOPSIS + Compares canonical and bootstrap shared-rule blocks for drift. + +.DESCRIPTION + Extracts explicitly marked shared-rule blocks from: + - skills/codebase-orient/SKILL.md + - skills/install-codebase-orient/SKILL.md + + The check compares only blocks that are intended to stay synchronized. + Bootstrap-only setup text, framework probes, discovery-order structure, + output-doc examples, and other intentionally different sections are + excluded by leaving them outside the shared-rule markers. + +.EXAMPLE + .\scripts\check-shared-rule-drift.ps1 +#> + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$repoRoot = Join-Path $scriptDir '..' +Set-Location $repoRoot + +$canonicalPath = Join-Path $repoRoot 'skills/codebase-orient/SKILL.md' +$bootstrapPath = Join-Path $repoRoot 'skills/install-codebase-orient/SKILL.md' + +$blockIds = @( + 'when-to-use-this-skill', + 'token-aware-use-guidance', + 'normal-mode-vs-dry-run-mode', + 'confidence-labels', + 'docs-as-hypotheses-rule', + 'ci-deployment-precision-rule', + 'read-depth-heuristic', + 'cheap-artifact-glob-rule', + 'open-question-quality-rule', + 'change-surfaces-mapping-guidance', + 'no-date-only-churn-rule', + 'cross-file-consistency-rule', + 'orientation-completion-rule', + 'orientation-report-discipline', + 'project-local-specialization-rule', + 'hidden-risk-reporting-rule', + 'source-of-truth-drift-detection-rule' +) + +$markerPattern = '' + +function Get-LeadingWhitespaceWidth { + param( + [Parameter(Mandatory = $true)] + [string] $Line + ) + + $width = 0 + foreach ($char in $Line.ToCharArray()) { + if ($char -eq ' ') { + $width++ + continue + } + if ($char -eq "`t") { + $width += 4 + continue + } + break + } + + return $width +} + +function Remove-CommonOuterIndentation { + param( + [Parameter(Mandatory = $true)] + [AllowEmptyString()] + [string[]] $Lines + ) + + $nonBlank = @($Lines | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }) + if ($nonBlank.Count -eq 0) { + return ,$Lines + } + + $minIndent = ($nonBlank | ForEach-Object { Get-LeadingWhitespaceWidth -Line $_ } | Measure-Object -Minimum).Minimum + if ($minIndent -le 0) { + return ,$Lines + } + + $normalized = foreach ($line in $Lines) { + if ([string]::IsNullOrWhiteSpace($line)) { + $line.TrimEnd() + continue + } + + $remaining = $minIndent + $index = 0 + while ($remaining -gt 0 -and $index -lt $line.Length) { + if ($line[$index] -eq ' ') { + $remaining-- + $index++ + continue + } + if ($line[$index] -eq "`t") { + if ($remaining -lt 4) { + break + } + $remaining -= 4 + $index++ + continue + } + break + } + $line.Substring($index).TrimEnd() + } + + return ,$normalized +} + +function Remove-CommonBlockquoteWrapper { + param( + [Parameter(Mandatory = $true)] + [AllowEmptyString()] + [string[]] $Lines + ) + + $nonBlank = @($Lines | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }) + if ($nonBlank.Count -eq 0) { + return ,$Lines + } + + $allQuoted = $true + foreach ($line in $nonBlank) { + if ($line -notmatch '^\s*>\s?') { + $allQuoted = $false + break + } + } + + if (-not $allQuoted) { + return ,$Lines + } + + $normalized = foreach ($line in $Lines) { + $line.TrimEnd() -replace '^(\s*)>\s?', '$1' + } + + return ,$normalized +} + +function Normalize-HeadingDepth { + param( + [Parameter(Mandatory = $true)] + [AllowEmptyString()] + [string[]] $Lines + ) + + $headingLevels = @( + $Lines | + ForEach-Object { + if ($_ -match '^\s*(#{1,6})\s+') { + $Matches[1].Length + } + } | + Where-Object { $_ -is [int] } + ) + + $baseHeadingLevel = $null + if ($headingLevels.Count -gt 0) { + $baseHeadingLevel = ($headingLevels | Measure-Object -Minimum).Minimum + } + + $normalized = foreach ($line in $Lines) { + if ($line -match '^(\s*)#{1,6}\s+(.*)$') { + $headingLevel = ($line -replace '^(\s*)(#{1,6})\s+(.*)$', '$2').Length + if ($null -eq $baseHeadingLevel) { + '{0}{1} {2}' -f $Matches[1], ('#' * $headingLevel), $Matches[2].TrimEnd() + } else { + $relativeLevel = $headingLevel - $baseHeadingLevel + 1 + '{0}{1} {2}' -f $Matches[1], ('#' * $relativeLevel), $Matches[2].TrimEnd() + } + } else { + $line.TrimEnd() + } + } + + return ,$normalized +} + +function Trim-OuterBlankLines { + param( + [Parameter(Mandatory = $true)] + [AllowEmptyString()] + [string[]] $Lines + ) + + $start = 0 + $end = $Lines.Count - 1 + + while ($start -le $end -and [string]::IsNullOrWhiteSpace($Lines[$start])) { + $start++ + } + while ($end -ge $start -and [string]::IsNullOrWhiteSpace($Lines[$end])) { + $end-- + } + + if ($start -gt $end) { + return @('') + } + + return ,($Lines[$start..$end]) +} + +function Get-SharedRuleBlockRecords { + param( + [Parameter(Mandatory = $true)] + [string] $Path + ) + + $raw = Get-Content -Raw -Encoding UTF8 $Path + $markerMatches = [regex]::Matches($raw, $markerPattern) + + $records = New-Object System.Collections.Generic.List[object] + $startIds = New-Object System.Collections.Generic.List[string] + $endIds = New-Object System.Collections.Generic.List[string] + $topologyErrors = New-Object System.Collections.Generic.List[string] + $openBlock = $null + + foreach ($match in $markerMatches) { + $markerType = $match.Groups[1].Value + $markerId = $match.Groups[2].Value + + if ($markerType -eq 'start') { + $startIds.Add($markerId) + + if ($null -ne $openBlock) { + $topologyErrors.Add( + "nested start marker in ${Path}: saw start:$markerId before closing start:$($openBlock.Id)" + ) + } + + $openBlock = [pscustomobject]@{ + Id = $markerId + StartMarkerIndex = $match.Index + ContentStartIndex = $match.Index + $match.Length + } + continue + } + + $endIds.Add($markerId) + + if ($null -eq $openBlock) { + $topologyErrors.Add( + "orphan end marker in ${Path}: end:$markerId has no matching start" + ) + continue + } + + if ($openBlock.Id -ne $markerId) { + $topologyErrors.Add( + "mismatched end marker in ${Path}: opened start:$($openBlock.Id) but closed end:$markerId" + ) + $openBlock = $null + continue + } + + $rawContent = $raw.Substring($openBlock.ContentStartIndex, $match.Index - $openBlock.ContentStartIndex) -replace "`r", '' + $lines = $rawContent -split "`n" + $trimmed = Trim-OuterBlankLines -Lines $lines + $deindented = Remove-CommonOuterIndentation -Lines $trimmed + $unquoted = Remove-CommonBlockquoteWrapper -Lines $deindented + $normalizedLines = Normalize-HeadingDepth -Lines $unquoted + + $records.Add([pscustomobject]@{ + Id = $markerId + NormalizedContent = ($normalizedLines -join "`n") + }) + + $openBlock = $null + } + + if ($null -ne $openBlock) { + $topologyErrors.Add( + "unclosed start marker in ${Path}: start:$($openBlock.Id) has no matching end" + ) + } + + if ($startIds.Count -ne $endIds.Count -or $startIds.Count -ne $records.Count) { + $topologyErrors.Add( + "marker topology mismatch in ${Path}: start markers=$($startIds.Count), end markers=$($endIds.Count), complete blocks=$($records.Count)" + ) + } + + return [pscustomobject]@{ + Path = $Path + Records = $records + StartIds = @($startIds) + EndIds = @($endIds) + Errors = @($topologyErrors) + } +} + +function Write-BlockDiff { + param( + [Parameter(Mandatory = $true)] + [string] $BlockId, + [Parameter(Mandatory = $true)] + [string] $CanonicalContent, + [Parameter(Mandatory = $true)] + [string] $BootstrapContent + ) + + $canonicalTemp = New-TemporaryFile + $bootstrapTemp = New-TemporaryFile + try { + Set-Content -LiteralPath $canonicalTemp -Value $CanonicalContent -Encoding UTF8 + Set-Content -LiteralPath $bootstrapTemp -Value $BootstrapContent -Encoding UTF8 + Write-Host "FAIL shared-rule block drift: $BlockId" -ForegroundColor Red + & git diff --no-index -- $canonicalTemp $bootstrapTemp + } finally { + Remove-Item -LiteralPath $canonicalTemp, $bootstrapTemp -ErrorAction SilentlyContinue + } +} + +$canonicalResult = Get-SharedRuleBlockRecords -Path $canonicalPath +$bootstrapResult = Get-SharedRuleBlockRecords -Path $bootstrapPath + +$failed = $false + +foreach ($fileInfo in @( + @{ Label = 'canonical'; Result = $canonicalResult }, + @{ Label = 'bootstrap'; Result = $bootstrapResult } +)) { + foreach ($validationError in $fileInfo.Result.Errors) { + Write-Host "FAIL $validationError" -ForegroundColor Red + $failed = $true + } + + $startUnexpected = @($fileInfo.Result.StartIds | Where-Object { $blockIds -notcontains $_ } | Sort-Object -Unique) + if ($startUnexpected.Count -gt 0) { + Write-Host "FAIL unexpected $($fileInfo.Label) start block ids in $($fileInfo.Result.Path): $($startUnexpected -join ', ')" -ForegroundColor Red + $failed = $true + } + + $endUnexpected = @($fileInfo.Result.EndIds | Where-Object { $blockIds -notcontains $_ } | Sort-Object -Unique) + if ($endUnexpected.Count -gt 0) { + Write-Host "FAIL unexpected $($fileInfo.Label) end block ids in $($fileInfo.Result.Path): $($endUnexpected -join ', ')" -ForegroundColor Red + $failed = $true + } + + $ids = @($fileInfo.Result.Records | ForEach-Object { $_.Id }) + $unexpected = @($ids | Where-Object { $blockIds -notcontains $_ } | Sort-Object -Unique) + if ($unexpected.Count -gt 0) { + Write-Host "FAIL unexpected $($fileInfo.Label) complete block ids in $($fileInfo.Result.Path): $($unexpected -join ', ')" -ForegroundColor Red + $failed = $true + } + + $duplicates = @( + $ids | + Group-Object | + Where-Object { $_.Count -gt 1 } | + Sort-Object Name + ) + if ($duplicates.Count -gt 0) { + $duplicateText = $duplicates | ForEach-Object { '{0} (x{1})' -f $_.Name, $_.Count } + Write-Host "FAIL duplicate $($fileInfo.Label) complete block ids in $($fileInfo.Result.Path): $($duplicateText -join ', ')" -ForegroundColor Red + $failed = $true + } + + $startDuplicates = @( + $fileInfo.Result.StartIds | + Group-Object | + Where-Object { $_.Count -gt 1 } | + Sort-Object Name + ) + if ($startDuplicates.Count -gt 0) { + $duplicateText = $startDuplicates | ForEach-Object { '{0} (x{1})' -f $_.Name, $_.Count } + Write-Host "FAIL duplicate $($fileInfo.Label) start marker ids in $($fileInfo.Result.Path): $($duplicateText -join ', ')" -ForegroundColor Red + $failed = $true + } + + $endDuplicates = @( + $fileInfo.Result.EndIds | + Group-Object | + Where-Object { $_.Count -gt 1 } | + Sort-Object Name + ) + if ($endDuplicates.Count -gt 0) { + $duplicateText = $endDuplicates | ForEach-Object { '{0} (x{1})' -f $_.Name, $_.Count } + Write-Host "FAIL duplicate $($fileInfo.Label) end marker ids in $($fileInfo.Result.Path): $($duplicateText -join ', ')" -ForegroundColor Red + $failed = $true + } +} + +$canonicalMap = @{} +foreach ($record in $canonicalResult.Records) { + if (-not $canonicalMap.ContainsKey($record.Id)) { + $canonicalMap[$record.Id] = $record + } +} + +$bootstrapMap = @{} +foreach ($record in $bootstrapResult.Records) { + if (-not $bootstrapMap.ContainsKey($record.Id)) { + $bootstrapMap[$record.Id] = $record + } +} + +foreach ($blockId in $blockIds) { + if (-not $canonicalMap.ContainsKey($blockId)) { + Write-Host "FAIL missing canonical block: $blockId" -ForegroundColor Red + $failed = $true + } + if (-not $bootstrapMap.ContainsKey($blockId)) { + Write-Host "FAIL missing bootstrap block: $blockId" -ForegroundColor Red + $failed = $true + } +} + +if ($failed) { + exit 1 +} + +foreach ($blockId in $blockIds) { + if ($canonicalMap[$blockId].NormalizedContent -ne $bootstrapMap[$blockId].NormalizedContent) { + $failed = $true + Write-BlockDiff -BlockId $blockId -CanonicalContent $canonicalMap[$blockId].NormalizedContent -BootstrapContent $bootstrapMap[$blockId].NormalizedContent + } else { + Write-Host "PASS shared-rule block: $blockId" + } +} + +if ($failed) { + Write-Host '' + Write-Host 'check-shared-rule-drift: shared-rule drift found. See diff above.' -ForegroundColor Red + exit 1 +} + +Write-Host '' +Write-Host 'check-shared-rule-drift: all shared-rule blocks are synchronized.' diff --git a/skills/codebase-orient/SKILL.md b/skills/codebase-orient/SKILL.md index 0f3b2d4..347ccc5 100644 --- a/skills/codebase-orient/SKILL.md +++ b/skills/codebase-orient/SKILL.md @@ -11,6 +11,7 @@ Orient Claude to the current state of this repo before non-trivial work. Produce > **Customization note:** The `docs/ai/` output location is a convention. Adapt it to your project's documentation structure. + ## When to use this skill ### Use this skill when @@ -32,7 +33,9 @@ Orient Claude to the current state of this repo before non-trivial work. Produce - Making copy-only or string-only changes - The task is scoped tightly to files already verified in the current context - `docs/ai/` was just refreshed and the task is narrow enough not to need a full orientation pass + + ## Token-aware use guidance `docs/ai/` is an orientation cache. A fresh cache reduces repeated repo-discovery token cost across sessions and agent handoffs. @@ -43,6 +46,7 @@ Orient Claude to the current state of this repo before non-trivial work. Produce - **If the agent would spend many tokens rediscovering what `docs/ai/` already captures**: refresh it. Do not save tokens by skipping orientation and then guessing at structure. If broad repo discovery would otherwise be repeated or expensive, refresh the cache instead. + ## Hard rules during orientation @@ -52,6 +56,7 @@ Do not save tokens by skipping orientation and then guessing at structure. If br - Verify claims against source code before writing them. - Mark every meaningful claim with a confidence label. + ## Normal mode vs dry-run mode **Normal mode** (default - use when the user does not specify): @@ -67,7 +72,9 @@ Do not save tokens by skipping orientation and then guessing at structure. If br - Wait for explicit approval before writing If mode is not specified, default to Normal mode. + + ## Confidence labels - **Fact**: directly verified in code or docs @@ -89,6 +96,7 @@ Distinguish how a claim was established: - _unknown_: basis not established; do not present as Fact In final reports and orientation docs, label each non-trivial claim with one of the above origins so readers can judge which claims need re-verification before acting on them. + ## Discovery order @@ -97,12 +105,15 @@ In final reports and orientation docs, label each non-trivial claim with one of Execute in this order: 1. Project instruction files such as `CLAUDE.md`, `AGENTS.md`, and `README.md`, if present - product purpose, agent rules, project conventions. + + **Docs-as-hypotheses rule** - Treat these documents as helpful hypotheses, not authoritative truth. - Extract high-impact factual claims about architecture, routes, deployment, tests, and source-of-truth files. - Verify those claims against source code before relying on them. Focus on claims that would affect future edits; do not audit every sentence. - Do not copy claims from these docs into `CODEBASE_MAP.md` without labeling whether they are _independently verified from source/config_ or _inherited from existing docs_. - If an instruction doc is stale or misleading compared to what the source shows, record the drift in `OPEN_QUESTIONS.md` under the hidden-risk reporting rule and label it as documentation drift. - Map the instruction-layer topology: note which instruction files are present (e.g., `CLAUDE.md`, `AGENTS.md`, `.claude/settings.json`) and at which scope (project-local vs user-level). Record this in `CODEBASE_MAP.md`; it helps future agents know which rules apply. + 2. Project manifest (e.g., `package.json`, `pyproject.toml`, `Cargo.toml`) - deps, scripts, build/test commands 3. Build and config files (e.g., framework config, bundler config) - adapter, build config 4. `scripts/` directory, if present - may contain manually-run tooling not represented in package scripts or CI @@ -136,6 +147,7 @@ Server-side route files (`+page.server.ts`, `+layout.server.ts`, `+server.ts`) a - The standard app shell template is `src/app.html`. - Adapter choice in `svelte.config.js` determines deployment target - confirm before making deployment-related claims. + ## CI/deployment precision rule When reading CI or deployment workflow files, preserve operationally relevant detail. Do not round down specifics into vague summaries. @@ -153,7 +165,9 @@ Capture and report: - whether deployment overwrites in place, stages to a temp path, uses symlinks, or uses versioned release directories Label CI/deployment claims with _independently verified from source/config_ when read directly from the workflow file. Do not summarize these details in ways that lose precision that an operator would need during an incident. + + ## Read-depth heuristic Do not read every large CSS, config, or generated file by default. @@ -182,7 +196,9 @@ Examples where this applies: - command or plugin registries Use a partial read when that is sufficient. Label the resulting claims with the appropriate claim origin (_partial read_, _full source read_). Do not label them as _independently verified from source/config_ if you did not actually read the file. + + ## Cheap artifact glob rule Before leaving an open question about the existence or scope of static assets, scripts, generated outputs, documentation, tests, migrations, or config files, resolve it with a cheap path glob. @@ -199,7 +215,9 @@ Common glob patterns to try: - `dist/**/*` or `build/**/*` Do not deeply read all matched files by default. Use the glob to resolve existence and scope questions cheaply. Follow up with targeted reads only when a specific file's content is needed. + + ## Open question quality rule Do not leave an open question in `OPEN_QUESTIONS.md` if it can be resolved with one cheap path glob or one small-file read. @@ -212,6 +230,7 @@ Leave a question open only when resolving it would require: - deep reads of files that are irrelevant to the current task If a glob or small read can close the question, close it and label the basis. + ## Output files @@ -225,6 +244,7 @@ Add or update `Last refreshed: ` at the top of each file **only when its c Before staging, format all created/updated files if the project has a discoverable formatter that covers Markdown (e.g., Prettier, markdownlint). If a formatter is missing, unavailable, not configured for Markdown, or its invocation would fail, skip formatting, note this clearly in the orientation report, and continue. Do not treat missing formatter support as an orientation failure. + ## CHANGE_SURFACES mapping guidance When populating `docs/ai/CHANGE_SURFACES.md`, include entries for these change types in addition to the standard surfaces (routes, styling, schema, tests, config): @@ -234,7 +254,9 @@ When populating `docs/ai/CHANGE_SURFACES.md`, include entries for these change t - **Docs-impact changes**: for each major subsystem, note which project docs need updating alongside code changes (e.g., "changes to the auth flow should also update `docs/auth.md`") Do not create separate `docs/ai/` files for smoke-check lists or handoff notes - record them inline in `CHANGE_SURFACES.md`. + + ## No-date-only-churn rule Do not rewrite a generated `docs/ai/` file solely to update a date, timestamp, or freshness marker. @@ -243,6 +265,7 @@ Do not rewrite a generated `docs/ai/` file solely to update a date, timestamp, o - Report it as **verified current** in the orientation report - not as "refreshed" or "updated". - Only update the `Last refreshed:` date when file content changes for a substantive reason. - If the project has an existing documented convention requiring date refreshes on every orientation pass, follow that convention - but only if it is explicitly documented in `CLAUDE.md`, `AGENTS.md`, or project docs. + ## Staleness and update rule @@ -250,6 +273,7 @@ The docs/ai files are orientation aids, not ground truth. Always verify against After any structural change, check whether the three docs/ai files need updates. Update only the relevant sections. Do not rewrite the whole map unless the architecture changed significantly. + ## Cross-file consistency rule The three `docs/ai/` files must remain coherent with each other. After any update, verify: @@ -260,7 +284,9 @@ The three `docs/ai/` files must remain coherent with each other. After any updat - **Contradictions**: do not let one file say "unknown" or "unresolved" while another says "resolved" or "confirmed" - unless the distinction is explicitly explained. Apply this as a final consistency pass after refreshing any of the three files. + + ## Orientation completion rule Before finishing orientation, classify every unresolved open question as one of: @@ -281,7 +307,9 @@ Then apply these rules: - the next action is clear For Relevant-but-non-blocking and Background questions: record them in `OPEN_QUESTIONS.md` with their classification and move on. Do not let them block the orientation report. + + ## Orientation report discipline The final orientation report must distinguish between docs that changed and docs that did not. Label each `docs/ai/` file with one of: @@ -304,7 +332,9 @@ When orientation is requested before an agent handoff, append a compact **Handof - **Recommended first action**: what the receiving agent should do first Keep it under 150 words. Do not create a separate `docs/ai/` file for it. + + ## Project-local specialization rule After the first orientation pass, if the repo has important project-specific namespaces, service folders, command groups, admin surfaces, workflow directories, generated-output locations, or deployment conventions that were not in the generic probe list, update the repo-local Claude Code skill at `.claude/skills/codebase-orient/SKILL.md` with those project-specific discovery paths. @@ -329,7 +359,9 @@ Examples of paths that qualify for local specialization: - generated asset conventions If the skill is running in dry-run/report-only mode, report the proposed local specialization but do not write it. + + ## Hidden-risk reporting rule Be concise by default, but go deeper when depth changes the decision. @@ -358,7 +390,9 @@ For each item, report: - Whether action is needed now or can be deferred If a hidden-risk item affects reproducibility, future installs, runtime behavior, or source-of-truth clarity, classify it as Blocking or Relevant but non-blocking, not Background. + + ## Source-of-truth drift detection rule When multiple copies or layers exist, explicitly map them before declaring the system current. @@ -388,3 +422,4 @@ If two copies differ, do not just update the currently active copy. Report the d - update all authoritative/durable copies, or - clearly mark which copy remains stale and what consequence that has. + diff --git a/skills/install-codebase-orient/SKILL.md b/skills/install-codebase-orient/SKILL.md index aed1142..157ab45 100644 --- a/skills/install-codebase-orient/SKILL.md +++ b/skills/install-codebase-orient/SKILL.md @@ -1,6 +1,6 @@ --- name: install-codebase-orient -version: "0.2.3" +version: "0.2.4" description: "Install or refresh a project-local codebase orientation workflow in the current repo. Use when the user asks to set up codebase orientation, create a codebase map, scan the repo properly, make Claude understand this project, prepare this repo for future Claude sessions, bootstrap Claude for this repo, or orient Claude to this codebase." --- @@ -183,118 +183,96 @@ Update only relevant sections. Do not rewrite the whole map unless the architect When creating or refreshing the project-local `codebase-orient` skill, the generated SKILL.md **must** include the following sections in addition to the standard discovery order, output files, and staleness rule: -> **Docs-as-hypotheses rule:** When reading project instruction files (CLAUDE.md, AGENTS.md, README.md), treat their claims as helpful hypotheses, not authoritative truth. Extract high-impact factual claims about architecture, routes, deployment, tests, and source-of-truth files. Verify those claims against source code before writing them to orientation docs. Do not copy claims from instruction docs into CODEBASE_MAP.md without labeling whether they are _independently verified from source/config_ or _inherited from existing docs_. If a doc is stale or misleading compared to source, record the drift in OPEN_QUESTIONS.md and label it as documentation drift. Also map the instruction-layer topology: note which instruction files are present (e.g., `CLAUDE.md`, `AGENTS.md`, `.claude/settings.json`) and at which scope (project-local vs user-level); record this in CODEBASE_MAP.md to help future agents know which rules apply. + +> **Docs-as-hypotheses rule** +> - Treat these documents as helpful hypotheses, not authoritative truth. +> - Extract high-impact factual claims about architecture, routes, deployment, tests, and source-of-truth files. +> - Verify those claims against source code before relying on them. Focus on claims that would affect future edits; do not audit every sentence. +> - Do not copy claims from these docs into `CODEBASE_MAP.md` without labeling whether they are _independently verified from source/config_ or _inherited from existing docs_. +> - If an instruction doc is stale or misleading compared to what the source shows, record the drift in `OPEN_QUESTIONS.md` under the hidden-risk reporting rule and label it as documentation drift. +> - Map the instruction-layer topology: note which instruction files are present (e.g., `CLAUDE.md`, `AGENTS.md`, `.claude/settings.json`) and at which scope (project-local vs user-level). Record this in `CODEBASE_MAP.md`; it helps future agents know which rules apply. + -### Orientation completion rule - -Before finishing orientation, classify every unresolved open question as one of: - -- **Blocking**: must resolve before safe work on the current task -- **Relevant but non-blocking**: useful context, work can proceed without it -- **Background**: not needed for the current task at all - -Then apply these rules: - -1. **Automatically resolve Blocking questions** by reading the minimum necessary files - unless the user explicitly requested dry-run or report-only mode. -2. **Apply docs/ai updates without asking first** when only docs/ai files need to change. Do not prompt for approval on small documentation corrections unless the user asked for it. -3. **Do not stop to prompt the user** for permission to resolve small documentation uncertainties. Use judgment and proceed safely within the hard rules. -4. **Stop and hand off** only when: relevant change surfaces are identified, blocking unknowns are resolved or explicitly marked as non-blocking, docs/ai is current enough for the requested task, and the next action is clear. - -For Relevant-but-non-blocking and Background questions: record them in `OPEN_QUESTIONS.md` with their classification and move on. Do not let them block the orientation report. - -### Normal mode vs dry-run mode - -- **Normal mode** (default): resolve task-relevant uncertainties automatically, apply docs/ai updates without requesting approval, report what changed at the end. -- **Dry-run / report-only mode**: inspect and collect proposed changes, report without writing, wait for explicit approval. Triggered by: "dry-run", "report only", "don't write", "propose changes first", "audit only", "no writes", or similar. -- If mode is not specified, default to Normal mode. + +### When to use this skill -### When to use this skill / when to skip it - -**Use this skill when:** +#### Use this skill when - Entering a new or unfamiliar repo -- Starting a fresh session after meaningful time away +- Starting a fresh session after meaningful time away from the repo - Before broad or multi-file implementation work - Before refactors, cleanups, architecture planning, or agent handoff - After structural changes: routes, schema, auth, deployment, config, or admin surfaces - When `docs/ai/` is missing, stale, incomplete, or internally inconsistent -- When repo structure, change surfaces, deploy targets, auth behavior, or test shape are unclear -- When the agent would otherwise spend significant context rediscovering what `docs/ai/` already captures +- When repo structure, change surfaces, deploy targets, auth behavior, admin routes, commands, or test shape are unclear +- When the agent would otherwise spend significant context rediscovering what is already in or near `docs/ai/` +- Any time the user says "scan", "orient", "understand", "map", "review", "audit", "survey", "familiarize", or "before I start" -**Skip this skill when:** +#### Skip this skill when - Making a tiny, local, known edit to a single file -- Fixing a one-file bug where the relevant file and change are already clear +- Fixing a one-file bug where the relevant file and the change are already clear - Making copy-only or string-only changes +- The task is scoped tightly to files already verified in the current context - `docs/ai/` was just refreshed and the task is narrow enough not to need a full orientation pass + + ### Token-aware use guidance `docs/ai/` is an orientation cache. A fresh cache reduces repeated repo-discovery token cost across sessions and agent handoffs. - **If `docs/ai/` is fresh and complete**: read it as context and proceed. Skip re-running orientation. -- **If `docs/ai/` may be stale or is missing**: run orientation. The upfront token cost amortizes across the work ahead. -- **If the task is tiny and the target file is known**: skip orientation. Use targeted reads instead. +- **If `docs/ai/` may be stale or is missing**: run the skill to refresh the cache. The upfront token cost amortizes across the work ahead. +- **If the task is tiny and the target file is already known**: skip orientation. Use targeted reads instead. +- **If the agent would spend many tokens rediscovering what `docs/ai/` already captures**: refresh it. Do not save tokens by skipping orientation and then guessing at structure. If broad repo discovery would otherwise be repeated or expensive, refresh the cache instead. + -### Confidence labels - -Primary claim labels: - -- **Fact**: directly verified in code or docs -- **Strong inference**: supported by multiple files -- **Weak inference**: plausible but not confirmed -- **Unknown**: needs more inspection before editing - -Distinguish how each claim was established: - -- *independently verified from source/config*: claim checked against the actual source or config file, not taken from docs -- *inherited from existing docs*: claim taken from CLAUDE.md, README, or other documentation without independent verification -- *inherited then verified*: claim originated in docs and was subsequently confirmed against source -- *path existence confirmed*: file found but not read -- *partial read*: portion of the file inspected; may not capture full context -- *full source read*: complete file content inspected -- *inferred from implementation*: deduced from how code behaves, not explicitly stated -- *inferred from comments/tests/fixtures*: sourced from non-authoritative context; treat as Strong inference at best -- *behavior verified by test*: confirmed by passing test execution -- *unknown*: basis not established; do not present as Fact - -In final reports and orientation docs, label each non-trivial claim with one of the above origins. Do not conflate path existence with source verification. - -### Hidden-risk reporting rule - -Be concise by default, but go deeper when depth changes the decision. + +### Normal mode vs dry-run mode -During orientation, actively look for hidden risks that could affect future work, reproducibility, safety, or correctness. +**Normal mode** (default - use when the user does not specify): -If any of the following appear, include a `Potential drift / hidden risk` section in the final report: +- Resolve small task-relevant uncertainties automatically by reading source files +- Apply `docs/ai/` updates without requesting approval +- Report what changed at the end -- source file vs generated file mismatch -- local copy vs packaged copy mismatch -- repo-local config vs global/user config mismatch -- runtime registry vs filesystem source mismatch -- committed source vs ignored runtime artifact mismatch -- docs claiming one thing while code suggests another -- tests passing but coverage not proving the behavior -- path existence without full source read -- behavior inferred from comments, fixtures, or tests rather than implementation -- setup that works in this session but may fail after restart, reinstall, deploy, rebuild, cache clear, or future Claude session +**Dry-run / report-only mode** (use when the user says "dry-run", "report only", "don't write", "propose changes first", "audit only", "no writes", or similar): -For each item, report: Evidence, Risk, Confidence, Recommended action, and whether action is needed now or can be deferred. +- Inspect and collect proposed changes +- Report proposed edits to `docs/ai/` without writing them +- Wait for explicit approval before writing -If a hidden-risk item affects reproducibility, future installs, runtime behavior, or source-of-truth clarity, classify it as Blocking or Relevant but non-blocking, not Background. +If mode is not specified, default to Normal mode. + -### Source-of-truth drift detection rule + +### Confidence labels -When multiple copies or layers exist, explicitly map them before declaring the system current. +- **Fact**: directly verified in code or docs +- **Strong inference**: supported by multiple files +- **Weak inference**: plausible but not confirmed +- **Unknown**: needs more inspection before editing -Check for: editable source files, generated files, packaged archives, runtime/plugin registry copies, global/user-level copies, project-local copies, committed repo files, ignored local files, and cache/session-loaded copies. +Distinguish how a claim was established: -For each layer, identify: what it is used for, whether it is authoritative, whether it is tracked by git, whether it is regenerated from another source, whether it can overwrite another copy, and whether it survives restart, reinstall, clone, deploy, or future session. +- _independently verified from source/config_: claim checked against the actual source or config file, not taken from docs +- _inherited from existing docs_: claim taken from CLAUDE.md, README, or other documentation without independent verification +- _inherited then verified_: claim originated in docs and was subsequently confirmed against source +- _path existence confirmed_: file found but not read +- _partial read_: portion of the file inspected; may not capture full context +- _full source read_: complete file content inspected +- _inferred from implementation_: deduced from how code behaves, not explicitly stated +- _inferred from comments/tests/fixtures_: sourced from non-authoritative context; treat as Strong inference at best +- _behavior verified by test_: confirmed by passing test execution +- _unknown_: basis not established; do not present as Fact -If two copies differ, do not just update the currently active copy. Report the drift and either update all authoritative/durable copies, or clearly mark which copy remains stale and what consequence that has. +In final reports and orientation docs, label each non-trivial claim with one of the above origins so readers can judge which claims need re-verification before acting on them. + + ### CI/deployment precision rule When reading CI or deployment workflow files, preserve operationally relevant detail. Do not round down specifics into vague summaries. @@ -312,13 +290,15 @@ Capture and report: - whether deployment overwrites in place, stages to a temp path, uses symlinks, or uses versioned release directories Label CI/deployment claims with _independently verified from source/config_ when read directly from the workflow file. Do not summarize these details in ways that lose precision that an operator would need during an incident. + + ### Read-depth heuristic Do not read every large CSS, config, or generated file by default. - **Full read**: files that directly affect the requested task (entry points, routing, auth, schema, build config, the file to be edited). -- **Partial read or path-confirmation only**: secondary surfaces such as large style sheets, vendored code, generated output, or config files not relevant to the task. If you only confirm a file's path or read a portion, say so explicitly using the _path existence confirmed_ or _partial read_ labels. +- **Partial read or path-confirmation only**: secondary surfaces such as large style sheets, vendored code, generated output, or config files not relevant to the task. If you only confirm a file's path or read a portion, say so explicitly in the report using the _path existence confirmed_ or partial-read labels defined under Confidence labels. - **Skip**: files that are clearly out of scope (e.g., binary assets, lock files, test snapshots) unless a specific question makes them relevant. When in doubt, prefer confirming existence first and reading fully only if a claim requires it. @@ -341,7 +321,9 @@ Examples where this applies: - command or plugin registries Use a partial read when that is sufficient. Label the resulting claims with the appropriate claim origin (_partial read_, _full source read_). Do not label them as _independently verified from source/config_ if you did not actually read the file. + + ### Cheap artifact glob rule Before leaving an open question about the existence or scope of static assets, scripts, generated outputs, documentation, tests, migrations, or config files, resolve it with a cheap path glob. @@ -358,7 +340,9 @@ Common glob patterns to try: - `dist/**/*` or `build/**/*` Do not deeply read all matched files by default. Use the glob to resolve existence and scope questions cheaply. Follow up with targeted reads only when a specific file's content is needed. + + ### Open question quality rule Do not leave an open question in `OPEN_QUESTIONS.md` if it can be resolved with one cheap path glob or one small-file read. @@ -371,28 +355,21 @@ Leave a question open only when resolving it would require: - deep reads of files that are irrelevant to the current task If a glob or small read can close the question, close it and label the basis. + -### Cross-file consistency rule - -The three `docs/ai/` files must remain coherent with each other. After any update, verify: - -- **Resolved questions**: if `OPEN_QUESTIONS.md` marks a question resolved, remove or update any stale "unknown" or "needs investigation" language in `CODEBASE_MAP.md` and `CHANGE_SURFACES.md` that referred to the same item. -- **New change surfaces**: if a change surface is added to `CHANGE_SURFACES.md`, check whether `CODEBASE_MAP.md` should mention the associated area or file. -- **New map uncertainty**: if a claim in `CODEBASE_MAP.md` becomes uncertain, check whether the corresponding open question exists in `OPEN_QUESTIONS.md`; add or update it if not. -- **Contradictions**: do not let one file say "unknown" or "unresolved" while another says "resolved" or "confirmed" - unless the distinction is explicitly explained. - -Apply this as a final consistency pass after refreshing any of the three files. - + ### CHANGE_SURFACES mapping guidance When populating `docs/ai/CHANGE_SURFACES.md`, include entries for these change types in addition to the standard surfaces (routes, styling, schema, tests, config): - **Auth/admin/operator UX changes**: admin panels, operator dashboards, internal tooling surfaces; note any accessibility requirements or WCAG targets found in source or docs - **Deployment-sensitive changes**: flag files whose changes should prompt a smoke check after deploy; note likely smoke-check entry points (e.g., login page, health endpoint, main route) -- **Docs-impact changes**: for each major subsystem, note which project docs need updating alongside code changes +- **Docs-impact changes**: for each major subsystem, note which project docs need updating alongside code changes (e.g., "changes to the auth flow should also update `docs/auth.md`") Do not create separate `docs/ai/` files for smoke-check lists or handoff notes - record them inline in `CHANGE_SURFACES.md`. + + ### No-date-only-churn rule Do not rewrite a generated `docs/ai/` file solely to update a date, timestamp, or freshness marker. @@ -401,10 +378,48 @@ Do not rewrite a generated `docs/ai/` file solely to update a date, timestamp, o - Report it as **verified current** in the orientation report - not as "refreshed" or "updated". - Only update the `Last refreshed:` date when file content changes for a substantive reason. - If the project has an existing documented convention requiring date refreshes on every orientation pass, follow that convention - but only if it is explicitly documented in `CLAUDE.md`, `AGENTS.md`, or project docs. + + + +### Cross-file consistency rule + +The three `docs/ai/` files must remain coherent with each other. After any update, verify: + +- **Resolved questions**: if `OPEN_QUESTIONS.md` marks a question resolved, remove or update any stale "unknown" or "needs investigation" language in `CODEBASE_MAP.md` and `CHANGE_SURFACES.md` that referred to the same item. +- **New change surfaces**: if a change surface is added to `CHANGE_SURFACES.md`, check whether `CODEBASE_MAP.md` should mention the associated area or file. +- **New map uncertainty**: if a claim in `CODEBASE_MAP.md` becomes uncertain, check whether the corresponding open question exists in `OPEN_QUESTIONS.md`; add or update it if not. +- **Contradictions**: do not let one file say "unknown" or "unresolved" while another says "resolved" or "confirmed" - unless the distinction is explicitly explained. + +Apply this as a final consistency pass after refreshing any of the three files. + + + +### Orientation completion rule + +Before finishing orientation, classify every unresolved open question as one of: +- **Blocking**: must resolve before safe work on the current task (e.g., unknown auth behavior before touching auth, unknown API shape before touching that route) +- **Relevant but non-blocking**: useful context for the task but work can proceed without it +- **Background**: not needed for the current task at all + +Then apply these rules: + +1. **Automatically resolve Blocking questions** by reading the minimum necessary files - unless the user explicitly requested dry-run or report-only mode. +2. **Apply docs/ai updates without asking first** when only docs/ai files need to change. Do not prompt for approval on small documentation corrections unless the user asked for it. +3. **Do not stop to prompt the user** for permission to resolve small documentation uncertainties. Use judgment and proceed safely within the hard rules. +4. **Stop and hand off** only when: + - relevant change surfaces are identified + - blocking unknowns are resolved or explicitly marked as non-blocking + - docs/ai is current enough for the requested task + - the next action is clear + +For Relevant-but-non-blocking and Background questions: record them in `OPEN_QUESTIONS.md` with their classification and move on. Do not let them block the orientation report. + + + ### Orientation report discipline -Label each `docs/ai/` file in the final report with one of: +The final orientation report must distinguish between docs that changed and docs that did not. Label each `docs/ai/` file with one of: - **Created**: file did not exist; was created this pass - **Substantively updated**: content changed; `Last refreshed` date updated @@ -412,7 +427,7 @@ Label each `docs/ai/` file in the final report with one of: - **Proposed only**: dry-run mode; change proposed but not written - **Skipped**: file not inspected this pass; state why -Do not label a file as "updated" or "refreshed" if only its date changed. +Do not label a file as "updated" or "refreshed" if only its date changed. A file with no substantive changes must be reported as **verified current / unchanged**. #### Agent handoff summary @@ -424,7 +439,9 @@ When orientation is requested before an agent handoff, append a compact **Handof - **Recommended first action**: what the receiving agent should do first Keep it under 150 words. Do not create a separate `docs/ai/` file for it. + + ### Project-local specialization rule After the first orientation pass, if the repo has important project-specific namespaces, service folders, command groups, admin surfaces, workflow directories, generated-output locations, or deployment conventions that were not in the generic probe list, update the repo-local Claude Code skill at `.claude/skills/codebase-orient/SKILL.md` with those project-specific discovery paths. @@ -437,10 +454,9 @@ Before writing the local specialization: Do not backport concrete project-specific paths to the public skill unless they are broadly reusable across many projects. -The project-specific paths added here are the thin, customisable layer of the repo-local skill. The canonical rules in the sections above are the stable layer that applies across all repos. Keep these two layers visually separated - project-specific additions belong at the end of the file, clearly marked as project-local. +The project-specific paths added here are the thin, customisable layer of the repo-local skill. The canonical rules above are the stable layer that applies across all repos. Keep them visually separated - project-specific additions belong at the end of the file, clearly marked as project-local. Examples of paths that qualify for local specialization: - - framework-adjacent service namespaces - custom domain workflow folders - admin page or resource directories @@ -450,6 +466,70 @@ Examples of paths that qualify for local specialization: - generated asset conventions If the skill is running in dry-run/report-only mode, report the proposed local specialization but do not write it. + + + +### Hidden-risk reporting rule + +Be concise by default, but go deeper when depth changes the decision. + +During orientation, actively look for hidden risks that could affect future work, reproducibility, safety, or correctness. + +If any of the following appear, include a `Potential drift / hidden risk` section in the final report: + +- source file vs generated file mismatch +- local copy vs packaged copy mismatch +- repo-local config vs global/user config mismatch +- runtime registry vs filesystem source mismatch +- committed source vs ignored runtime artifact mismatch +- docs claiming one thing while code suggests another +- tests passing but coverage not proving the behavior +- path existence without full source read +- behavior inferred from comments, fixtures, or tests rather than implementation +- setup that works in this session but may fail after restart, reinstall, deploy, rebuild, cache clear, or future Claude session + +For each item, report: + +- Evidence +- Risk +- Confidence +- Recommended action +- Whether action is needed now or can be deferred + +If a hidden-risk item affects reproducibility, future installs, runtime behavior, or source-of-truth clarity, classify it as Blocking or Relevant but non-blocking, not Background. + + + +### Source-of-truth drift detection rule + +When multiple copies or layers exist, explicitly map them before declaring the system current. + +Check for: + +- editable source files +- generated files +- packaged archives +- runtime/plugin registry copies +- global/user-level copies +- project-local copies +- committed repo files +- ignored local files +- cache/session-loaded copies + +For each layer, identify: + +- what it is used for +- whether it is authoritative +- whether it is tracked by git +- whether it is regenerated from another source +- whether it can overwrite another copy +- whether it survives restart, reinstall, clone, deploy, or future session + +If two copies differ, do not just update the currently active copy. Report the drift and either: + +- update all authoritative/durable copies, or +- clearly mark which copy remains stale and what consequence that has. + --- @@ -457,6 +537,13 @@ If the skill is running in dry-run/report-only mode, report the proposed local s > **Version scheme note:** The version number in this file's frontmatter tracks the bootstrap skill's own content changes. It is independent from the repository release tag. The repository `CHANGELOG.md` records release history and relevant bootstrap-skill changes. +### 0.2.4 - 2026-05-24 + +- Added explicit shared-rule markers for automated drift validation of the embedded shared-rule snapshot. +- Aligned the embedded shared-rule wording with the canonical `skills/codebase-orient/SKILL.md` shared-rule content. +- Future bootstrap-generated project-local skill content now uses the synchronized shared-rule blocks. +- No installer behavior change. + ### 0.2.3 - 2026-05-24 - Replaced the stale concrete repository-version reference in the version-scheme note with durable repository changelog wording.