升级 Trellis 并完成项目审查（07-26-trellis-upgrade-project-audit）

.trellis/spec/hyb-oa/project-governance.md

@@ -51,11 +51,92 @@ rollback and future self-maintenance.
 
 ## Current Local Commands
 
+- `python3 -m compileall -q .trellis/scripts .codex/hooks`
 - `python3 ./.trellis/scripts/task.py validate <task>`
 - `node scripts/qa/check-trellis-governance.mjs`
 - `git diff --check`
 - `bash scripts/check-minimal.sh`
 
+## Scenario: Trellis Project Upgrade Compatibility
+
+### 1. Scope / Trigger
+
+- Trigger: upgrading the project Trellis version, applying migrations, or
+  refreshing managed platform assets.
+- Purpose: prevent a template update from silently breaking the project's
+  actual Python runtime or enabling an AI platform that is not in scope.
+
+### 2. Signatures
+
+- Version check: `trellis --version` and `.trellis/.version`.
+- Runtime check:
+  `python3 -m compileall -q .trellis/scripts .codex/hooks`.
+- Project preview: `trellis update --dry-run` using the target CLI version.
+- Task smoke tests: `task.py validate`, `task.py current --source --json` and
+  `task.py list --json`.
+
+### 3. Contracts
+
+- Run compile checks with the same `python3` executable used by project
+  Trellis commands; compatibility with a newer developer interpreter is not
+  sufficient.
+- Project-enabled platforms are authoritative. A local-only settings directory
+  such as `.claude/` must not cause an out-of-scope managed platform bundle to
+  enter the upgrade diff.
+- Temporarily isolating a local-only platform directory is allowed only when
+  its exact contents are restored after update and the final diff confirms no
+  managed assets for that platform were added.
+- Preserve intentional local overlays through explicit merge; do not use
+  `--force` to erase `workflow.md`, `config.yaml`, `.gitignore` or `AGENTS.md`.
+- Treat dry-run output and manifest cleanliness as evidence, but do not assume
+  a dry-run is write-free; inspect `git status` before and after it.
+
+### 4. Validation & Error Matrix
+
+- Runtime compile failure -> stop the upgrade and fix or revert the incompatible
+  managed script before running task commands.
+- Unexpected platform assets in dry-run or final diff -> stop, correct platform
+  discovery, and rerun the preview.
+- `.new` conflict files remain -> upgrade is incomplete; merge or discard each
+  one deliberately.
+- Post-upgrade dry-run changes manifest again -> investigate template hash drift
+  before commit.
+- Only documented project overlays remain modified -> acceptable after task and
+  governance gates pass.
+
+### 5. Good/Base/Bad Cases
+
+- Good: isolate a local-only `.claude/`, update Codex assets, restore the local
+  setting, compile with project Python, then verify a stable dry-run.
+- Base: update a project with no local platform ambiguity and run the same
+  compile, task and governance checks.
+- Bad: accept generated Claude assets because `.claude/settings.local.json`
+  happened to exist, or validate Python code only with a newer interpreter.
+
+### 6. Tests Required
+
+- Assert CLI and project versions match the intended target.
+- Compile every Python file under `.trellis/scripts` and `.codex/hooks`.
+- Exercise task validate/current/list and run Trellis governance.
+- Confirm no `.new`, backup, bytecode or out-of-scope platform assets are
+  tracked; finish with `git diff --check`.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```text
+trellis update reports success -> commit immediately
+```
+
+#### Correct
+
+```text
+preview platform scope -> conservative update/migrate -> merge overlays
+-> compile with project Python -> smoke-test task runtime -> stable dry-run
+-> governance and project gates -> commit
+```
+
 ## Legacy Issue CSV
 
 - Do not delete, bulk rewrite or move historical `issues/*.csv` files.