docs(openspec): PF-3 align reconcile——doc-source delta 調和至 doc-first(canon v2)

[monkey1sai]

Summary

依歸檔 doc-first-canon-v2 design.md §6a 處方（follow-up openspec-ledger-reconcile，PF-3），在 align-frontend-design-system-reference archive 前調和其 documentation-source-of-truth delta——該 delta 對 main 現行兩條 requirement 帶 RENAMED(v3→v4)＋MODIFIED，其 body 原重申「HTML 只是 design gate 唯一權威輸入、code＋tests/contracts 是現行 runtime behavior truth」＝doc-first canon v2（PR #360/#361/#362）剛翻轉的舊 code-first 權威序；若不先調和，該 change 日後 archive 會把 main 的 doc-first 條文覆蓋回 code-first。

• specs/documentation-source-of-truth/spec.md：以 main 已採納之 doc-first 條文為基底重寫 MODIFIED——兩條 requirement 的全部 scenario 逐字重現（5/5＋2/2，防 archive 靜默 drop，即 canon v2 archive 時被 OpenSpec 攔過的同型坑）；疊加本 change 原有的 HTML-derived derivatives 條款（manifest／route inventory／goldens＝可重建可回溯的 validation artifacts、repo 外 design path 不得成 parallel authority）；剔除 code-first 權威序語句；保留 behavior-truth 誠實半句（「任何文件不得反向覆蓋 runtime 現況陳述，亦不得以文件宣稱 runtime 已完成」）與 v4 改名。
• specs/agent-operability-governance/spec.md：一句 code＋tests 語句加註「（現況證據，非需求權威；需求權威依 doc-first 為 docs/plans 正本）」。
• proposal.md：What Changes 與權責歸屬表兩處同步 doc-first 措辭。

不掛 auto-merge：權威序措辭屬治理面，停等使用者 review（比照 #360 姿態）。

Change Classification

Label	Value
Change lane	G
Behavior contract changed	no
Requirement source	existing contract: openspec/changes/archive/2026-07-20-doc-first-canon-v2/design.md §6a（follow-up openspec-ledger-reconcile 處方：「archive 前 MUST 對已採納 canon v2 調和 align 的 RENAMED(v3→v4)＋MODIFIED body：保留其 behavior-truth 誠實半句、剔除／改寫與 doc-first 對立的權威序語句」）＋ main openspec/specs/documentation-source-of-truth/spec.md（doc-first 現行條文，2026-07-21 使用者 grill-me 場逐項裁決授權「現在 doc-only 調和 align、手法 A」）

AI Coding Governance

Label	Value
Linked issue	無（需求承載於歸檔 change 之 design.md §6a follow-up 處方＋本場使用者裁決，見 Requirement source 欄）
Requirement source	existing contract: openspec/changes/archive/2026-07-20-doc-first-canon-v2/design.md §6a（同上）
CODEOWNERS / owner review	.github/CODEOWNERS 預設規則（* @monkey1sai）涵蓋；改動全數落於 openspec/changes/align-frontend-design-system-reference/，未觸碰 /docs/plans/／/AGENTS.md／/scripts/；owner＝使用者本人，本 PR 不掛 auto-merge、停等使用者 review
GitNexus evidence	Not run: doc-only——git diff main --stat 恰 3 個 .md（proposal.md＋2 spec delta），zero code symbols、zero execution flows；無 shared/exported symbol 修改，detect_changes 無適用面（GitNexus index 現為 stale@713c7a5，與本判定無關）
Browser E2E evidence	Not run: no frontend product route or browser-facing implementation changed（doc-only；不觸碰 web-viewer-sample／governance-service product code）
Agent workflow changed?	no（未觸碰 .claude/workflows/／.github/workflows/／scripts/）
Required checks expected	PR Review Agent（pr-review-agent.yml）；Agent Governance（agent-governance.yml）；CI（ci.yml changed-path classifier；服務層 job 預期 skip）；openspec validate --all --strict＝62 passed/0 failed（本地證據，見下）

驗證證據（2026-07-21 本地實跑）

$ npx openspec validate align-frontend-design-system-reference --strict
Change 'align-frontend-design-system-reference' is valid

$ npx openspec validate --all --strict
Totals: 62 passed, 0 failed (62 items)

Scenario 重現自檢（防 archive 靜默 drop）：以 awk 對 main 逐 requirement 區塊擷取 scenario header 比對——

• Workflow v3 …（→v4）：main 5 scenario（讀者尋找開發流程／讀者尋找需求、現況或操作原型／workflow 與設計文件或 runtime truth 不一致／code 行為與設計正本衝突（doc-first 判 gap）／誠實鐵律與 doc-first 非矛盾壓測）→ delta 5/5 header 逐字重現。
• workflow v3 … cross-reference（→v4）：main 2 scenario（active consumer 指向被刪舊正本／設計文件與原型保持可發現）→ delta 2/2 header 逐字重現。

殘餘 code-first 掃描：grep -rn "design gate 唯一權威輸入|是現行 runtime behavior truth|SHALL 裁決現行 behavior 與 runtime truth|裁決 current behavior|HTML 只描述目標" openspec/changes/align-frontend-design-system-reference/ → 僅餘 proposal.md 權責歸屬表一列，已改寫為「需求權威正本（doc-first），亦為 design gate 唯一權威輸入」。

邊界聲明

• doc-only：不改任何 runtime code、public API、event、schema、後端凍結面（app.py／governanceProxy.ts／conversion_authority.py）。
• 不觸碰手寫正本面（兩份 .dc.html＋docs-plans-README.md＋ai-bim-governance.css）——本 PR 只改 openspec/changes/ 下的提案 delta，符合 design-canon-change-control R-A1（AI 以獨立 PR 提案、不原地編輯正本）。
• align change 的其餘 delta（unified-governance-console、demo-fast-mvp-orchestration）與 tasks.md 未動：它們不含 doc-first 對立語句，非 PF-3 範圍。

🤖 Generated with Claude Code

https://claude.ai/code/session_01WixYKeCVPNH9pVoxXgaiKB

[coderabbitai]

Warning

Review limit reached

@monkey1sai, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 2 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 34a73092-6823-41b8-97cb-084f951f1b4c

📥 Commits

Reviewing files that changed from the base of the PR and between 0b3ad5d and 55e4ff8.

📒 Files selected for processing (3)

• openspec/changes/align-frontend-design-system-reference/proposal.md
• openspec/changes/align-frontend-design-system-reference/specs/agent-operability-governance/spec.md
• openspec/changes/align-frontend-design-system-reference/specs/documentation-source-of-truth/spec.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch openspec/pf3-align-reconcile

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This is a doc-only PR (PF-3 follow-up openspec-ledger-reconcile) that reconciles the in-flight align-frontend-design-system-reference change's delta with the doc-first authority ordering that main already adopted via canon v2 (PRs #360/#361/#362). Without this reconciliation, archiving the align change would silently revert main's documentation-source-of-truth spec back from doc-first to the retired code-first authority ordering. The changes rewrite the two MODIFIED requirement bodies (and their scenarios) to doc-first wording, preserve the honest behavior-truth carve-out, and synchronize the sibling agent-operability spec line and proposal wording.

Changes:

• Rewrote the two MODIFIED requirements in documentation-source-of-truth to doc-first (docs/plans HTML canon = sole requirement authority; code+tests = runtime evidence, not requirement authority), faithfully reproducing all existing scenario headers (5/5 + 2/2) plus align's HTML-derived-derivatives clauses, and removing code-first authority statements.
• Annotated the agent-operability-governance spec's "code+tests/contracts" clause to clarify it is runtime evidence, not requirement authority.
• Updated two proposal.md lines (What Changes + ownership table) to doc-first phrasing.

I verified against the current main spec that the RENAMED FROM (v3) headers still exist and the MODIFIED headers match the RENAMED TO (v4) targets, that scenario headers are reproduced verbatim, and that no residual code-first authority phrases remain in the change directory. I found no objective defects to comment on.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
openspec/changes/align-frontend-design-system-reference/specs/documentation-source-of-truth/spec.md	Rewrites both MODIFIED requirement bodies + scenarios to doc-first, reproducing existing scenarios and layering align's derivative clauses.
openspec/changes/align-frontend-design-system-reference/specs/agent-operability-governance/spec.md	Annotates the code+tests clause as runtime evidence rather than requirement authority.
openspec/changes/align-frontend-design-system-reference/proposal.md	Syncs What Changes and ownership-table wording to doc-first.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9137fa63fa

ℹ️ 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".

[chatgpt-codex-connector]

Update v3 cross-references before archiving

When this active OpenSpec change is archived, this replacement makes the cross-reference requirement speak in terms of workflow v4, but the same capability's current spec still contains normative cross-references to the old Workflow v3... requirement in R-B1/R-B3/R-C2b. Because this delta only modifies these two requirements, archive will leave those stale references pointing at a renamed requirement; add MODIFIED deltas for the dependent requirements or keep the name stable until all references are updated.

Useful? React with 👍 / 👎.