Repository navigation
docs(agents): 治理審計 P1 — 結構收斂（薄鏡像納管 + skill 白名單 + workflow 殘留清理） - #275
Merged
Merged
Conversation
- 兩份 gitignored 腐敗 CLAUDE.md（streaming/viewer）重寫薄鏡像並 un-ignore 納管 - gitnexus×6 + repo-health skill 檔入版控白名單（修 MUST 規則指向未版控檔的結構風險） - 移除 10 個一次性 workflow 殘留（零引用、綁死已消失 worktree；git 歷史可回復） - coordinator CLAUDE.md 獨有內容併回 AGENTS.md 後薄化 - 四工具職責表下放 github-workflow.md 單一權威版（AGENTS.md 217→207） - repo-boundary 補 governance-service §3.7 / kit-manager §3.8 + mermaid 節點 - sub-repo-verify 補 governance-service 段；viewer AGENTS verify 描述修正 - spec-to-done 兩版 adapter 同步（codex 版同源 stale + 維運段） Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CAswRmGWDHkrTUSmsq1vZy
monkey1sai
enabled auto-merge (squash)
July 2, 2026 05:18
Contributor
📝 WalkthroughWalkthroughAdds six new GitNexus SKILL.md documentation files and a new repo-health SKILL.md. Restructures root and sub-repo AGENTS.md/CLAUDE.md governance contracts, updates gitignore whitelisting for tracked skill directories, extends repo-boundary and verification docs, and removes multiple ChangesGitNexus and Repo-Health Skills
Governance Docs and Workflow Removal
Sub-repo Boundary Documentation
Estimated code review effort: 3 (Moderate) | ~30 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 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 |
Contributor
There was a problem hiding this comment.
Pull request overview
This is a docs-and-agent-assets-only PR implementing the "P1 structural convergence" phase of the 2026-07-02 agent-governance audit (P0 was #274). It contains no runtime or code-symbol changes. The goal is to make the repo's agent-facing governance docs consistent and tracked: converge two stale, gitignored sub-repo CLAUDE.md files into thin mirror entries, bring GitNexus/repo-health skill files under version control, remove one-off residual workflows, and add the missing governance-service/kit-manager boundary documentation.
Changes:
- Rewrite
bim-streaming-server/CLAUDE.mdandweb-viewer-sample/CLAUDE.mdas thin mirror entries (and stop ignoringCLAUDE.mdin both sub-repos); fold uniquebim-review-coordinatorcontent into itsAGENTS.md. - Whitelist GitNexus CLI skills +
repo-healthskill in root.gitignore(both.claudeand.codex); delete 10 unreferenced one-off workflows; dedup the four-tool table intogithub-workflow.md. - Add
governance-service(§3.7) andkit-manager(§3.8) boundary sections, diagram nodes, and verify commands; correct theweb-viewernpm run verifydescription and the GitNexus tool names (impact/detect_changes).
Reviewed changes
Copilot reviewed 38 out of 39 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
web-viewer-sample/CLAUDE.md |
New thin mirror entry pointing to sibling AGENTS.md and repo-boundary §3.6 |
web-viewer-sample/AGENTS.md |
Corrects stale npm run verify to build && test && test:struct-log (matches package.json) |
web-viewer-sample/.gitignore |
Un-ignores /CLAUDE.md |
docs/agents/sub-repo-verify-commands.md |
Adds governance-service host-native Python312 verify section |
docs/agents/repo-boundary-detail.md |
Adds governance-service/kit-manager nodes, tree entries, §3.7/§3.8 |
docs/agents/github-workflow.md |
Single authoritative four-tool table + anti-patterns |
CLAUDE.md |
Dedups pipeline/rebuild detail to pointers; fixes gitnexus_impact→impact |
bim-streaming-server/CLAUDE.md |
New thin mirror entry |
bim-streaming-server/.gitignore |
Un-ignores /CLAUDE.md |
bim-review-coordinator/CLAUDE.md |
Thinned to mirror entry |
bim-review-coordinator/AGENTS.md |
Absorbs collaboration-retirement note, ifc-cache carve-out, authority table |
AGENTS.md |
Removes duplicated four-tool table, points to github-workflow.md |
.gitignore |
Whitelists gitnexus/repo-health skills (.claude + .codex) |
.codex/skills/spec-to-done/SKILL.md |
Syncs branch-protection narrative; cites .gitignore line numbers (now stale) |
.codex/skills/repo-health/SKILL.md |
New tracked skill (references non-existent plans path) |
.codex/skills/gitnexus/*/SKILL.md |
New tracked GitNexus CLI skill docs |
.claude/skills/spec-to-done/SKILL.md |
Adds cross-host helper-consistency note |
.claude/skills/repo-health/SKILL.md |
New tracked skill (references non-existent plans path) |
.claude/skills/gitnexus/*/SKILL.md |
New tracked GitNexus CLI skill docs |
.claude/workflows/*.js (10 files) |
Deletes one-off residual workflows (no active references) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| | 面向 | 抓什麼 | 性質 | | ||
| |---|---|---| | ||
| | **進度差異** | `docs/plans/開發軌跡與執行計畫.md` 的 A1–A10／M0–M8「計畫自報 vs 獨立查證」並列，標出計畫高估/低報 | 唯讀評估，**不納入「要修哪幾項」** | |
|
|
||
| | 面向 | 抓什麼 | 性質 | | ||
| |---|---|---| | ||
| | **進度差異** | `docs/plans/開發軌跡與執行計畫.md` 的 A1–A10／M0–M8「計畫自報 vs 獨立查證」並列，標出計畫高估/低報 | 唯讀評估，**不納入「要修哪幾項」** | |
| 4. GitNexus detect-changes 在 linked worktree 看不到 staged(已知坑)→ implementer fallback `git diff --name-only --cached` 並記 `detectVerdict='fallback'`,PR body 揭露;完全失敗記 `fail`,同 run 3 次 → held。 | ||
| 5. pr-review-agent 兩種非內容故障:`missing_openspec`(P6 前置 a 預防)與`report generation failed`(工具整體故障,非 required check,由 ship-item 判斷層次處置)。 | ||
| 6. 本組檔案已 whitelist tracked(`.gitignore:37` `!.claude/skills/spec-to-done/`、`:42` `!.claude/workflows/`、`:55` `!.codex/skills/spec-to-done/`;含 SKILL.md、std-*.js、ship-item、本目錄 `ensure-host-native-ports-free.ps1`),隨 PR 進 git/CI。純動 `.claude/**` / `.codex/**` 的 PR 可能被 pr-review-agent paths-ignore 跳過 review(#202);main 無 branch protection 故此 check 非 required。 | ||
| 6. 本組檔案已 whitelist tracked(`.gitignore:37` `!.claude/skills/spec-to-done/`、`:42` `!.claude/workflows/`、`:55` `!.codex/skills/spec-to-done/`;含 SKILL.md、std-*.js、ship-item、本目錄 `ensure-host-native-ports-free.ps1`),隨 PR 進 git/CI。pr-review-agent 對所有 PR 都會跑(#202 的 paths-ignore 已移除,`pr-review-agent.yml` 現無 paths 過濾),且是 main branch protection 的 required check(11 項之一;2026-07-02 以 gh api 親查)——`.claude/**` / `.codex/**` 變更同樣受 review 與 AI Coding Governance body-evidence 表約束。 |
Contributor
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
…spec 執行紀錄 pr-review-agent 對 .codex/skills 路徑是 hard blocker（pr-review-agent.ps1:343）； 依「不由 agent 自行放寬 review gate」原則縮 PR 範圍：.claude 側 7 檔納管照舊， .codex 側 git rm --cached + 還原 gitignore 白名單、工作樹鏡像保留。 spec 補執行紀錄（同時消 missing_openspec blocker）。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CAswRmGWDHkrTUSmsq1vZy
Contributor
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
Contributor
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
Contributor
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
.claude/skills/gitnexus/gitnexus-guide/SKILL.md (1)
97-123: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winKeep the trace contract and schema list aligned.
tracesays class-rooted paths can traverseHAS_METHOD, but the Graph Schema section never lists that edge type. That makes the reference internally inconsistent and will mislead anyone writing Cypher against the documented schema. Please addHAS_METHODto the edge list, or remove it from the trace description if it is intentionally unsupported.Suggested patch
- **Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS + **Edges (via CodeRelation.type):** CALLS, HAS_METHOD, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/gitnexus/gitnexus-guide/SKILL.md around lines 97 - 123, The `trace` documentation and the Graph Schema edge list are inconsistent: `trace` mentions traversing `HAS_METHOD`, but the schema section omits that edge type. Update the `trace` description and the Graph Schema block in `SKILL.md` so they match by either adding `HAS_METHOD` to the documented `CodeRelation.type` edges or removing it from `trace` if it is not actually supported.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/gitnexus/gitnexus-cli/SKILL.md:
- Around line 8-10: The recovery path in SKILL.md uses mutable runtime installs,
which makes `gitnexus analyze` non-reproducible. Update the fallback flow
referenced in the `node .gitnexus/run.cjs` and `npx gitnexus analyze` guidance
so it uses a pinned GitNexus version or a checked-in bootstrap instead of
floating `gitnexus@latest`/unversioned `npx`. Keep the existing runner-selection
guidance intact, but make the regeneration instructions deterministic for
fresh-clone and missing-runner recovery.
In @.claude/skills/repo-health/SKILL.md:
- Around line 3-9: The skill header and description in SKILL.md still say “four
dimensions,” but the workflow and body cover a fifth read-only progress
evaluation, so update the headline/description to match the actual contract.
Reword the `description`, title text, and the opening `# repo-health` summary so
they consistently say “4 個衛生面向 + 1 個進度面向,” keeping the rest of the skill content
aligned with the `/repo-health` flow.
In `@bim-review-coordinator/AGENTS.md`:
- Around line 7-11: The role summary still describes bim-review-coordinator as a
“Session / Collaboration Control Plane,” but the deprecation note in AGENTS.md
says the collaboration Socket.IO handlers have been removed. Update the
top-level description to reflect only the surviving session responsibilities in
the same document, keeping it aligned with the archive/retirement note and
avoiding any mention of collaboration control-plane behavior.
In `@docs/agents/sub-repo-verify-commands.md`:
- Around line 90-98: This section still reads like a generic index entry, so
mark it explicitly as a runbook/working note in the governance-service section
of docs/agents/sub-repo-verify-commands.md. Update the header or nearby prose
around the governance-service block to include a clear runbook marker, using the
existing governance-service and evidence-path text as the anchor, so readers
understand it is operational guidance rather than source-of-truth behavior.
---
Nitpick comments:
In @.claude/skills/gitnexus/gitnexus-guide/SKILL.md:
- Around line 97-123: The `trace` documentation and the Graph Schema edge list
are inconsistent: `trace` mentions traversing `HAS_METHOD`, but the schema
section omits that edge type. Update the `trace` description and the Graph
Schema block in `SKILL.md` so they match by either adding `HAS_METHOD` to the
documented `CodeRelation.type` edges or removing it from `trace` if it is not
actually supported.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 33fbd073-dfd3-4517-9d50-fc887703b7eb
📒 Files selected for processing (32)
.claude/skills/gitnexus/gitnexus-cli/SKILL.md.claude/skills/gitnexus/gitnexus-debugging/SKILL.md.claude/skills/gitnexus/gitnexus-exploring/SKILL.md.claude/skills/gitnexus/gitnexus-guide/SKILL.md.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md.claude/skills/repo-health/SKILL.md.claude/skills/spec-to-done/SKILL.md.claude/workflows/bim-frontend-redesign-plan.js.claude/workflows/fe-redesign-alignment-audit.js.claude/workflows/fu1-adversarial-verify.js.claude/workflows/fu2-adversarial-verify.js.claude/workflows/fu34-adversarial-verify.js.claude/workflows/fullsystem-adversarial-verify.js.claude/workflows/plan-next-spec-to-done.js.claude/workflows/repo-wide-adversarial-round-1.js.claude/workflows/spec-to-done-design.js.claude/workflows/ui-blueprint-a-vs-b-decision.js.gitignoreAGENTS.mdCLAUDE.mdbim-review-coordinator/AGENTS.mdbim-review-coordinator/CLAUDE.mdbim-streaming-server/.gitignorebim-streaming-server/CLAUDE.mddocs/agents/github-workflow.mddocs/agents/repo-boundary-detail.mddocs/agents/sub-repo-verify-commands.mddocs/superpowers/specs/2026-07-02-agent-governance-doc-alignment.mdweb-viewer-sample/.gitignoreweb-viewer-sample/AGENTS.mdweb-viewer-sample/CLAUDE.md
💤 Files with no reviewable changes (10)
- .claude/workflows/fu34-adversarial-verify.js
- .claude/workflows/repo-wide-adversarial-round-1.js
- .claude/workflows/fu1-adversarial-verify.js
- .claude/workflows/spec-to-done-design.js
- .claude/workflows/plan-next-spec-to-done.js
- .claude/workflows/ui-blueprint-a-vs-b-decision.js
- .claude/workflows/fe-redesign-alignment-audit.js
- .claude/workflows/fullsystem-adversarial-verify.js
- .claude/workflows/fu2-adversarial-verify.js
- .claude/workflows/bim-frontend-redesign-plan.js
Comment on lines
+8
to
+10
| Commands below use `node .gitnexus/run.cjs <command>` — the project-local runner `gitnexus analyze` drops next to the index. It auto-selects an available runner at call time (global `gitnexus`, else `pnpm dlx`, else `npx`), so no package-manager assumption and no global install is required. | ||
|
|
||
| > **Not analyzed yet, or `node .gitnexus/run.cjs` reports `Cannot find module`** (the gitignored runner is absent — e.g. a fresh clone or `git clean`)? (Re)generate it with `npx gitnexus analyze` from the project root. On **npm 11.x**, if `npx` crashes during install (`node.target is null`), install once with `npm i -g gitnexus` (then `gitnexus analyze`) or use `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939). |
Contributor
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- file: .claude/skills/gitnexus/gitnexus-cli/SKILL.md ---'
cat -n .claude/skills/gitnexus/gitnexus-cli/SKILL.md | sed -n '1,80p'
printf '%s\n' '\n--- search for related bootstrap/version guidance ---'
rg -n --hidden --glob '.claude/**' --glob '!**/node_modules/**' \
'gitnexus analyze|gitnexus@latest|npx gitnexus|pnpm .*dlx gitnexus|pinned-version|version' \
.claudeRepository: monkey1sai/AI-BIM-governance
Length of output: 50387
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- gitnexus references and version pins ---'
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'gitnexus(`@latest`)?|npx gitnexus|pnpm .*dlx gitnexus|npm i -g gitnexus|gitnexus analyze|version:' \
.claude package.json pnpm-lock.yaml package-lock.json yarn.lock 2>/dev/null | sed -n '1,220p'
printf '%s\n' '\n--- nearby gitnexus skill docs ---'
for f in \
.claude/skills/gitnexus/gitnexus-cli/SKILL.md \
.claude/skills/gitnexus/gitnexus-guide/SKILL.md \
.claude/skills/gitnexus/README.md
do
if [ -f "$f" ]; then
echo "### $f"
cat -n "$f" | sed -n '1,140p'
fi
doneRepository: monkey1sai/AI-BIM-governance
Length of output: 23078
Pin the recovery install path
npx gitnexus analyze and pnpm ... dlx gitnexus@latest analyze still pull mutable upstream packages at runtime. Pin the GitNexus version here, or route the fallback through a checked-in bootstrap, so recovery stays reproducible and doesn’t depend on floating releases.
🧰 Tools
🪛 SkillSpector (2.3.7)
[warning] 10: [RP1] null: npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.
Remediation: Pin the version: npx @scope/server@1.2.3
(MCP Rug Pull (RP1))
[warning] 22: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.
Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.
(Memory Poisoning (MP2))
[warning] 46: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.
Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.
(Memory Poisoning (MP2))
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/gitnexus/gitnexus-cli/SKILL.md around lines 8 - 10, The
recovery path in SKILL.md uses mutable runtime installs, which makes `gitnexus
analyze` non-reproducible. Update the fallback flow referenced in the `node
.gitnexus/run.cjs` and `npx gitnexus analyze` guidance so it uses a pinned
GitNexus version or a checked-in bootstrap instead of floating
`gitnexus@latest`/unversioned `npx`. Keep the existing runner-selection guidance
intact, but make the regeneration instructions deterministic for fresh-clone and
missing-runner recovery.
Source: Linters/SAST tools
Comment on lines
+3
to
+9
| description: Use when the user wants to check or clean up the AI-BIM-governance repo's health — version/dependency drift across services, branch/worktree/temp cleanup, .claude asset hygiene, and doc/config sync. Scans read-only across four dimensions, reports, then fixes only what the user confirms. | ||
| argument-hint: "（選填）只想看某面向：version / cleanup / assets / docs" | ||
| --- | ||
|
|
||
| # repo-health — AI-BIM repo 四面向健檢 | ||
|
|
||
| 對 `AI-BIM-governance` 跑唯讀健檢，回報問題，**只修使用者確認的項目**。 |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Align the headline with the actual 5-step contract.
The front matter and title advertise “four dimensions,” but the body already includes a fifth, read-only progress evaluation, and the /repo-health workflow scans all five. Please reword this to “4 個衛生面向 + 1 個進度面向” so the skill contract matches the implementation.
🧰 Tools
🪛 SkillSpector (2.3.7)
[error] 15: [PE3] Credential Access: Code accesses credential files (SSH keys, AWS credentials, etc.). This could indicate credential theft attempts.
Remediation: Remove references to credential paths. Use environment variables or secrets managers. For docs, use placeholder paths (e.g., /path/to/config). Never load .env or token files in production code paths.
(Privilege Escalation (PE3))
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/repo-health/SKILL.md around lines 3 - 9, The skill header and
description in SKILL.md still say “four dimensions,” but the workflow and body
cover a fifth read-only progress evaluation, so update the headline/description
to match the actual contract. Reword the `description`, title text, and the
opening `# repo-health` summary so they consistently say “4 個衛生面向 + 1 個進度面向,”
keeping the rest of the skill content aligned with the `/repo-health` flow.
Comment on lines
+7
to
+11
| `bim-review-coordinator` 是外部 IFC-ready intake、metadata-only callback outbox 與 Session / Collaboration Control Plane。它負責建立 review session、協調 viewer 與 streaming server 的連線資訊、廣播 presence 等基本 session 事件，並保存最小 local shadow metadata。 | ||
|
|
||
| 服務埠口：`127.0.0.1:8004` | ||
| 服務埠口：`127.0.0.1:8004`（含 Socket.IO） | ||
|
|
||
| > **退役狀態（2026-05-21，change `remove-conflict-review-from-fast-mvp`）**：`highlightRequest` / `selectionUpdate` / `annotationCreate` 等 collaboration Socket.IO event handlers 已自本 service 移除（`src/socket/reviewNamespace.ts`）；`getReviewIssues` / `createAnnotation` / `/api/model-versions/:id/review-bootstrap` 也已刪。`/api/review-sessions/:id/events` 與 `/lifecycle-events` 仍保留；lifecycle endpoint 排除 collaboration event 的 wording 保留作 archive compatibility（舊 event log 仍可能含這些 type）——不要把這些已刪 handler 當 regression 加回來。 |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Drop the stale collaboration label from the role summary.
Line 11 already says the collaboration Socket.IO handlers were removed, so line 7 should not still describe this service as a "Session / Collaboration Control Plane". Please narrow it to the surviving session surface so the mirror stays aligned with the deprecation note.
Proposed wording
-`bim-review-coordinator` 是外部 IFC-ready intake、metadata-only callback outbox 與 Session / Collaboration Control Plane。
+`bim-review-coordinator` 是外部 IFC-ready intake、metadata-only callback outbox 與 Session Control Plane。📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| `bim-review-coordinator` 是外部 IFC-ready intake、metadata-only callback outbox 與 Session / Collaboration Control Plane。它負責建立 review session、協調 viewer 與 streaming server 的連線資訊、廣播 presence 等基本 session 事件，並保存最小 local shadow metadata。 | |
| 服務埠口：`127.0.0.1:8004` | |
| 服務埠口：`127.0.0.1:8004`（含 Socket.IO） | |
| > **退役狀態（2026-05-21，change `remove-conflict-review-from-fast-mvp`）**：`highlightRequest` / `selectionUpdate` / `annotationCreate` 等 collaboration Socket.IO event handlers 已自本 service 移除（`src/socket/reviewNamespace.ts`）；`getReviewIssues` / `createAnnotation` / `/api/model-versions/:id/review-bootstrap` 也已刪。`/api/review-sessions/:id/events` 與 `/lifecycle-events` 仍保留；lifecycle endpoint 排除 collaboration event 的 wording 保留作 archive compatibility（舊 event log 仍可能含這些 type）——不要把這些已刪 handler 當 regression 加回來。 | |
| `bim-review-coordinator` 是外部 IFC-ready intake、metadata-only callback outbox 與 Session Control Plane。它負責建立 review session、協調 viewer 與 streaming server 的連線資訊、廣播 presence 等基本 session 事件，並保存最小 local shadow metadata。 | |
| 服務埠口：`127.0.0.1:8004`（含 Socket.IO） | |
| > **退役狀態（2026-05-21，change `remove-conflict-review-from-fast-mvp`）**：`highlightRequest` / `selectionUpdate` / `annotationCreate` 等 collaboration Socket.IO event handlers 已自本 service 移除（`src/socket/reviewNamespace.ts`）；`getReviewIssues` / `createAnnotation` / `/api/model-versions/:id/review-bootstrap` 也已刪。`/api/review-sessions/:id/events` 與 `/lifecycle-events` 仍保留；lifecycle endpoint 排除 collaboration event 的 wording 保留作 archive compatibility（舊 event log 仍可能含這些 type）——不要把這些已刪 handler 當 regression 加回來。 |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@bim-review-coordinator/AGENTS.md` around lines 7 - 11, The role summary still
describes bim-review-coordinator as a “Session / Collaboration Control Plane,”
but the deprecation note in AGENTS.md says the collaboration Socket.IO handlers
have been removed. Update the top-level description to reflect only the
surviving session responsibilities in the same document, keeping it aligned with
the archive/retirement note and avoiding any mention of collaboration
control-plane behavior.
Comment on lines
+90
to
+98
| ## governance-service (Python host-native, port 49102) | ||
|
|
||
| ```powershell | ||
| cd governance-service | ||
| & "C:\Program Files\Python312\python.exe" -m pytest tests/ -v | ||
| & "C:\Program Files\Python312\python.exe" scripts/run_governance_evidence.py | ||
| ``` | ||
|
|
||
| 須走 host-native `C:\Program Files\Python312\python.exe`（具 ifcopenshell 0.8.5 + ifctester）；勿用 WSL / Docker（本服務 CPU-only，無 GPU 需求）。真實 IFC evidence 落 `docs/evidence/governance-rule-run-pass/`。 |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Mark this file as a runbook.
docs/**/*.md must explicitly declare the document nature, but this section still reads like a generic index page. Please add a clear runbook/working note marker so readers do not treat it as source-of-truth behavior.
Suggested header tweak
-# Sub-repo 驗證入口
+# Runbook: Sub-repo 驗證入口🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/agents/sub-repo-verify-commands.md` around lines 90 - 98, This section
still reads like a generic index entry, so mark it explicitly as a
runbook/working note in the governance-service section of
docs/agents/sub-repo-verify-commands.md. Update the header or nearby prose
around the governance-service block to include a clear runbook marker, using the
existing governance-service and evidence-path text as the anchor, so readers
understand it is operational guidance rather than source-of-truth behavior.
Source: Coding guidelines
This was referenced Jul 2, 2026
monkey1sai
added a commit
that referenced
this pull request
Jul 2, 2026
* feat(pr-review-agent): generated_tooling_path 只擋新增、放行已追蹤鏡像檔修改 解「.codex 373 檔被追蹤(#212)卻永遠改不動」結構矛盾(#275 撞過, adapter 同步 diff 因此遺失)。使用者 2026-07-02 拍板放寬。 - 新增 Test-PrReviewPathExistsAtBase: git cat-file -e 查 merge-base 是否已追蹤;Base/Head 缺失一律 false (fail-closed) - guard 分支: tracked 修改降 generated_tooling_path_modified warning; 新增路徑或無 base 可判定維持 hard blocker - Test 3c: tracked 修改=warning / 新增=blocker / 無 base=全 blocker 驗證: pwsh scripts/tests/test-pr-review-agent.ps1 baseline 與改後全綠。 spec: docs/superpowers/specs/2026-07-02-pr-review-agent-tracked-tooling-mirror-modify.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CiKNHW9BqXbP7p674tWUwa * fix(pr-review-agent): ExistsAtBase 改 ls-tree,修 CI PowerShell 5.1 NativeCommandError cat-file -e 對不存在路徑寫 stderr,CI 用 powershell.exe 5.1 (EAP=Stop) 會包成 NativeCommandError 拋出 → Test 3c 在 CI 紅、本機 pwsh 7 綠。 ls-tree --name-only 對不存在路徑靜默回空(exit 0、無 stderr),語意等價。 驗證: 本機 powershell.exe 5.1 與 pwsh 7 各跑 scripts/tests/test-pr-review-agent.ps1 全綠。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CiKNHW9BqXbP7p674tWUwa --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This was referenced Jul 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
摘要
治理審計 P1（結構收斂）：formal spec 見
docs/superpowers/specs/2026-07-02-agent-governance-doc-alignment.md（P0 = #274 已 merge）。純文件與 agent 資產收斂，無 runtime / code symbol 變更。變更清單
bim-streaming-server/CLAUDE.md（142 行，含 8 處已刪服務_bim-control/_s3_storage引用與 101 行 GitNexus 樣板）與web-viewer-sample/CLAUDE.md（149 行，同類問題）重寫為薄鏡像入口（各 ~13 行、指向 sibling AGENTS.md 與 repo-boundary §3.5/§3.6），並自兩個 sub.gitignore移除/CLAUDE.md忽略規則——根因是這兩檔從不進 PR review 才腐敗至此。.gitignore，.claude 與 .codex 兩側）：修復「CLAUDE.md/AGENTS.md 的 MUST 級 GitNexus 規則指向從未進 git 的檔案」結構風險（新 clone /.claude重建即消失）。-aware新版與活管線（std-*、ship-item、fu-generic、repo-health-scan、routing.json）全數保留。git 歷史可回復。github-workflow.md單一權威版（AGENTS.md 217→207 行）；CLAUDE.md 修正舊工具名（gitnexus_impact→impact）、rebuild 詳規改指路、§2 表與 AGENTS.md 集合一致（124→123 行，兩檔均在預算內；「目標行數」需 GitNexus embedded block 支援單檔寫入才可再壓，本 PR 不動自動區塊）。AI Coding Governance
Frontend Verification
npm run verify語意已在 AGENTS.md 修正為 build && test && test:struct-log）Deploy Path Verification
🤖 Generated with Claude Code
https://claude.ai/code/session_01CAswRmGWDHkrTUSmsq1vZy
Summary by CodeRabbit
New Features
Documentation
Chores