docs: 收斂 agent governance 決策入口 - #318
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (18)
📝 WalkthroughWalkthroughThis PR is a documentation-only update revising AGENTS.md and docs/agents/*.md governance rules: it restructures source-of-truth priority into agent-instruction vs runtime-truth axes, tightens PR evidence labeling tied to a validation script, defines a GitNexus unavailable gate, refines deploy Phase-3 blocker remediation, and corrects MinIO/conversion status claims in plan documents. ChangesAgent governance and evidence rules
Estimated code review effort: 2 (Simple) | ~12 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
There was a problem hiding this comment.
Pull request overview
This is a documentation-only governance cleanup that reconciles several contradictions across the repo's agent-facing docs so that agents stop needing manual intervention. It splits the previously conflated "agent instruction priority" vs "runtime/product behavior truth" ladders, adds a MinIO/conversion "current decision ledger" to prevent stale snapshots from overwriting current state, aligns the PR verification labels with the machine-checked truth in check-pr-body-evidence.ps1, adds a GitNexus-unavailable gate and a Codex model/effort lane map, tightens the deploy PID-stop safety boundary, and de-weights historical verification evidence. No runtime code is touched.
Changes:
- Introduces two explicit priority tracks (agent-instruction vs runtime-behavior) and a
§1.1current-decision ledger; corrects MinIO/conversion status wording to match implemented endpoints. - Aligns Frontend Verification labels/tables with the 7 machine-required labels and documents an approved backend-freeze exception for the A1 for-ifc-ready rule-run proxy.
- Adds a GitNexus-unavailable gate, a Codex model/effort lane routing table, tighter deploy PID-ownership rules, a verification-evidence index/tiers, and artifact-URL opacity notes.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
AGENTS.md |
Splits source-of-truth into two ladders, tightens deploy PID-stop and .env echo rules, updates PR labels and .codex/skills blocker wording |
docs/AGENTS.md |
Reframes docs/ as non-runtime authority; updates owns/not-owns and wiki/OpenSpec wording |
docs/agents/advanced-agent-reasoning-contract.md |
Renames worker→worker/reviewer extraction, rewrites source-of-truth priority into two tracks |
docs/agents/codex-loop-workflows.md |
Adds Codex model/effort lane routing section; renumbers later sections; wraps schemas in code fences |
docs/agents/gitnexus-usage.md |
Adds a GitNexus-unavailable gate with allowed conditions and decisions |
docs/agents/github-workflow.md |
Points Frontend Verification labels to the machine-checked 7-label set |
docs/agents/product-operability-and-script-contract.md |
Drops non-required labels from the verification table; tightens deploy PID-ownership rule |
docs/agents/sub-repo-verify-commands.md |
Aligns acceptance labels to machine truth; tightens deploy PID-ownership rule |
docs/contracts/conversion-api.md |
Fixes stale AGENTS.md §1.A/§10/§11 reference to root AGENTS.md §1 |
docs/contracts/review-session-api.md |
Adds artifact-URL opacity note |
docs/verification/README.md |
New evidence index with tiers and superseded/archival guidance |
docs/runbooks/one-click-deploy-smoke.md |
Adds repo-root safety guard and env-file backup before cleanup |
docs/plans/docs-plans-README.md |
Adds §1.1 current-decision ledger; updates MinIO/conversion role-table wording |
docs/plans/ai-bim-governance-前端對齊DS-保留後端-實作手冊.md |
Adds approved backend-freeze exceptions table |
docs/plans/ai-bim-governance-互動實作規格與標準對齊.md |
Updates data-storage current status to match implemented endpoints |
docs/plans/ai-bim-governance-design-system-對齊矩陣.md |
Corrects #minio over/under-claim wording |
docs/plans/審批報告-docs-plans-SaaS改版-2026-07-06.md |
Points inherited honesty framework to the new current decision |
docs/superpowers/specs/2026-06-23-a1a3-design-system-alignment-design.md |
Adds superseded note deprecating the A3 clash implementation plan |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 22b8990c41
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Remove-Item -LiteralPath .\web-viewer-sample\node_modules -Recurse -Force -ErrorAction SilentlyContinue | ||
| Remove-Item -LiteralPath .\.env.web-plane.host-kit -Force -ErrorAction SilentlyContinue | ||
| if (Test-Path -LiteralPath .\.env.web-plane.host-kit) { | ||
| Copy-Item -LiteralPath .\.env.web-plane.host-kit -Destination ".\.env.web-plane.host-kit.bak-$(Get-Date -Format yyyyMMddHHmmss)" -Force |
There was a problem hiding this comment.
When this smoke cleanup runs on a machine with a real .env.web-plane.host-kit, this line copies the private env file to .env.web-plane.host-kit.bak-<timestamp> under the repository root. That backup name is not ignored by the current .gitignore patterns (e.g. *.bak only covers names ending exactly in .bak), while the file can contain MinIO credentials, so operators following the runbook can accidentally leave and commit secrets. Please back it up outside the repo or use an ignored path/name before deleting the original.
Useful? React with 👍 / 👎.
|
|
||
| | 主題 | 現行裁決 | Superseded / 禁用說法 | | ||
| |---|---|---| | ||
| | MinIO `#minio` | `#minio` 已接 coordinator `GET /api/minio/objects?prefix=&delimiter=/`，是真 MinIO raw-folder 逐層唯讀瀏覽；`GET /api/governance/files/tree` local_fs 仍是 A1 v2 另一選檔來源。 | 禁寫「只剩 local_fs 兩層樹」、「真 MinIO 三層待接」。三層「專案/種類/版本」只是 watcher 解析語意，不是 bucket 結構宣稱。 | |
There was a problem hiding this comment.
This new ledger makes GET /api/minio/objects the current #minio truth and forbids the old “local_fs only / true MinIO pending” wording, but the active implementation-discipline doc still says MinioDataPage only uses GET /api/governance/files/tree and that true S3/MinIO is NOT BUILT (docs/plans/ai-bim-governance-實作紀律與技術債防線.md lines 101, 162, and 224). Agents are told to use both files for implementation checks, so leaving the old active HOW guidance unmarked can make a later UI pass block or undo the MinIO path this row is trying to canonicalize. Please update that doc or mark those sections superseded in the same decision change.
Useful? React with 👍 / 👎.
摘要
本 PR 是 docs-only governance cleanup，收斂本 repo 中容易讓 agent 反覆人工干預的文件矛盾：source-of-truth ladder、Codex workflow/model lane、Frontend Verification labels、GitNexus unavailable gate、MinIO/轉檔 current decision、A1/A3 狀態粒度、歷史 verification evidence 降權與 deploy PID-stop 安全邊界。
AI Coding Governance
gitnexus detect-changes --repo AI-BIM-governance --scope staged=> low risk, 0 affected processes; symbol mapping showed index drift, so raw staged file list also checked驗證
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\tests\test-agent-governance-check.ps1powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\tests\test-pr-body-evidence.ps1powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\tests\test-pr-review-agent.ps1git diff --cached --checkgitnexus detect-changes --repo AI-BIM-governance --scope staged備註
.env。.gitignoredirty state 未納入本 branch。Summary by CodeRabbit