universal-dev-standards 6.7.5 → 6.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/uds.js +19 -2
- package/bundled/ai/standards/acceptance-criteria-traceability.ai.yaml +14 -2
- package/bundled/ai/standards/adr-standards.ai.yaml +14 -2
- package/bundled/ai/standards/ai-instruction-standards.ai.yaml +6 -6
- package/bundled/ai/standards/code-review.ai.yaml +13 -3
- package/bundled/ai/standards/commit-message.ai.yaml +8 -4
- package/bundled/ai/standards/deferred-item-exit.ai.yaml +225 -0
- package/bundled/ai/standards/feature-discovery-standards.ai.yaml +14 -2
- package/bundled/ai/standards/governance-layer.ai.yaml +128 -2
- package/bundled/ai/standards/logging.ai.yaml +2 -2
- package/bundled/ai/standards/retrospective-standards.ai.yaml +14 -2
- package/bundled/ai/standards/reverse-engineering-standards.ai.yaml +73 -2
- package/bundled/ai/standards/security-standards.ai.yaml +2 -2
- package/bundled/ai/standards/spec-driven-development.ai.yaml +14 -2
- package/bundled/ai/standards/tech-debt-standards.ai.yaml +87 -3
- package/bundled/ai/standards/turn-completion-integrity.ai.yaml +131 -0
- package/bundled/core/acceptance-criteria-traceability.md +5 -2
- package/bundled/core/adr-standards.md +26 -2
- package/bundled/core/ai-instruction-standards.md +9 -7
- package/bundled/core/code-review-checklist.md +5 -2
- package/bundled/core/context-aware-loading.md +1 -1
- package/bundled/core/deferred-item-exit.md +254 -0
- package/bundled/core/feature-discovery-standards.md +5 -1
- package/bundled/core/governance-layer.md +114 -2
- package/bundled/core/retrospective-standards.md +4 -2
- package/bundled/core/reverse-engineering-standards.md +81 -2
- package/bundled/core/spec-driven-development.md +8 -2
- package/bundled/core/tech-debt-standards.md +67 -8
- package/bundled/core/turn-completion-integrity.md +196 -0
- package/bundled/hooks/check-dangerous-cmd.mjs +60 -0
- package/bundled/hooks/check-logging-standard.mjs +59 -0
- package/bundled/hooks/check-turn-completion.mjs +233 -0
- package/bundled/hooks/inject-standards.mjs +183 -0
- package/bundled/hooks/telemetry-wrapper.mjs +77 -0
- package/bundled/hooks/turn-completion/detect.mjs +99 -0
- package/bundled/hooks/turn-completion/locales/en.mjs +159 -0
- package/bundled/hooks/turn-completion/locales/zh-TW.mjs +166 -0
- package/bundled/hooks/validate-commit-msg.mjs +104 -0
- package/bundled/locales/zh-CN/CHANGELOG.md +65 -3
- package/bundled/locales/zh-CN/CLAUDE.md +1 -1
- package/bundled/locales/zh-CN/README.md +7 -7
- package/bundled/locales/zh-CN/SECURITY.md +1 -1
- package/bundled/locales/zh-CN/core/adr-standards.md +1 -1
- package/bundled/locales/zh-CN/core/ai-instruction-standards.md +10 -8
- package/bundled/locales/zh-CN/core/governance-layer.md +118 -6
- package/bundled/locales/zh-CN/core/retrospective-standards.md +1 -1
- package/bundled/locales/zh-CN/core/tech-debt-standards.md +71 -4
- package/bundled/locales/zh-CN/core/turn-completion-integrity.md +190 -0
- package/bundled/locales/zh-CN/docs/CHEATSHEET.md +27 -6
- package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +29 -68
- package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +172 -24
- package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +1 -2
- package/bundled/locales/zh-CN/integrations/google-antigravity/{INSTRUCTIONS.md → AGENTS.md} +1 -1
- package/bundled/locales/zh-CN/integrations/google-antigravity/README.md +3 -3
- package/bundled/locales/zh-CN/skills/agents/README.md +1 -1
- package/bundled/locales/zh-CN/skills/atdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/bdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/brainstorm-assistant/SKILL.md +22 -12
- package/bundled/locales/zh-CN/skills/brainstorm-assistant/guide.md +12 -9
- package/bundled/locales/zh-CN/skills/code-review-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/commands/brainstorm.md +17 -13
- package/bundled/locales/zh-CN/skills/commands/config.md +0 -1
- package/bundled/locales/zh-CN/skills/commands/init.md +1 -2
- package/bundled/locales/zh-CN/skills/commit-standards/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/contract-test-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/dev-methodology/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/observability-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/project-structure-guide/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/release-standards/SKILL.md +3 -0
- package/bundled/locales/zh-CN/skills/requirement-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/reverse-engineer/SKILL.md +3 -0
- package/bundled/locales/zh-CN/skills/reverse-engineer/tdd-analysis.md +13 -23
- package/bundled/locales/zh-CN/skills/runbook-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/slo-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/tdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/workflows/README.md +2 -11
- package/bundled/locales/zh-TW/CHANGELOG.md +65 -3
- package/bundled/locales/zh-TW/CLAUDE.md +1 -1
- package/bundled/locales/zh-TW/README.md +7 -7
- package/bundled/locales/zh-TW/SECURITY.md +1 -1
- package/bundled/locales/zh-TW/core/acceptance-criteria-traceability.md +2 -0
- package/bundled/locales/zh-TW/core/adr-standards.md +26 -5
- package/bundled/locales/zh-TW/core/ai-instruction-standards.md +10 -8
- package/bundled/locales/zh-TW/core/code-review-checklist.md +2 -0
- package/bundled/locales/zh-TW/core/container-image-standards.md +2 -2
- package/bundled/locales/zh-TW/core/contract-testing-standards.md +2 -2
- package/bundled/locales/zh-TW/core/cross-flow-regression.md +8 -7
- package/bundled/locales/zh-TW/core/data-contract.md +2 -2
- package/bundled/locales/zh-TW/core/data-migration-testing.md +2 -2
- package/bundled/locales/zh-TW/core/data-pipeline.md +2 -2
- package/bundled/locales/zh-TW/core/deferred-item-exit.md +251 -0
- package/bundled/locales/zh-TW/core/documentation-writing-standards.md +228 -3
- package/bundled/locales/zh-TW/core/full-coverage-testing.md +15 -2
- package/bundled/locales/zh-TW/core/governance-layer.md +118 -5
- package/bundled/locales/zh-TW/core/iac-design-principles.md +2 -2
- package/bundled/locales/zh-TW/core/incident-response.md +2 -2
- package/bundled/locales/zh-TW/core/model-provenance.md +4 -2
- package/bundled/locales/zh-TW/core/pii-classification.md +42 -6
- package/bundled/locales/zh-TW/core/prd-standards.md +4 -2
- package/bundled/locales/zh-TW/core/product-metrics-standards.md +4 -2
- package/bundled/locales/zh-TW/core/release-readiness-gate.md +2 -2
- package/bundled/locales/zh-TW/core/resource-cost-boundary.md +2 -2
- package/bundled/locales/zh-TW/core/retrospective-standards.md +5 -3
- package/bundled/locales/zh-TW/core/reverse-engineering-standards.md +83 -5
- package/bundled/locales/zh-TW/core/runbook.md +2 -2
- package/bundled/locales/zh-TW/core/schema-evolution.md +2 -2
- package/bundled/locales/zh-TW/core/secret-management-standards.md +2 -2
- package/bundled/locales/zh-TW/core/slo-sli.md +2 -2
- package/bundled/locales/zh-TW/core/spec-driven-development.md +2 -0
- package/bundled/locales/zh-TW/core/tech-debt-standards.md +71 -4
- package/bundled/locales/zh-TW/core/turn-completion-integrity.md +190 -0
- package/bundled/locales/zh-TW/core/user-journey-testing.md +2 -2
- package/bundled/locales/zh-TW/core/user-story-mapping.md +2 -2
- package/bundled/locales/zh-TW/core/verification-oracle.md +2 -2
- package/bundled/locales/zh-TW/docs/CHEATSHEET.md +27 -6
- package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +29 -68
- package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +172 -24
- package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +1 -2
- package/bundled/locales/zh-TW/integrations/google-antigravity/{INSTRUCTIONS.md → AGENTS.md} +1 -1
- package/bundled/locales/zh-TW/integrations/google-antigravity/README.md +3 -3
- package/bundled/locales/zh-TW/skills/adr-assistant/SKILL.md +1 -1
- package/bundled/locales/zh-TW/skills/agents/README.md +1 -1
- package/bundled/locales/zh-TW/skills/atdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/bdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/brainstorm-assistant/SKILL.md +22 -12
- package/bundled/locales/zh-TW/skills/brainstorm-assistant/guide.md +12 -9
- package/bundled/locales/zh-TW/skills/code-review-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/commands/brainstorm.md +17 -13
- package/bundled/locales/zh-TW/skills/commands/config.md +0 -1
- package/bundled/locales/zh-TW/skills/commands/init.md +1 -2
- package/bundled/locales/zh-TW/skills/commit-standards/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md +2 -1
- package/bundled/locales/zh-TW/skills/dev-methodology/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +1 -1
- package/bundled/locales/zh-TW/skills/knowledge-graph/guide.md +2 -2
- package/bundled/locales/zh-TW/skills/migration-assistant/SKILL.md +1 -1
- package/bundled/locales/zh-TW/skills/observability-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/project-discovery/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/release-standards/SKILL.md +3 -0
- package/bundled/locales/zh-TW/skills/requirement-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/reverse-engineer/SKILL.md +3 -0
- package/bundled/locales/zh-TW/skills/reverse-engineer/tdd-analysis.md +13 -23
- package/bundled/locales/zh-TW/skills/runbook-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/slo-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/tdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/workflows/README.md +2 -11
- package/bundled/skills/agents/README.md +1 -1
- package/bundled/skills/atdd-assistant/SKILL.md +2 -0
- package/bundled/skills/bdd-assistant/SKILL.md +2 -0
- package/bundled/skills/brainstorm-assistant/SKILL.md +31 -13
- package/bundled/skills/brainstorm-assistant/guide.md +9 -6
- package/bundled/skills/code-review-assistant/SKILL.md +1 -0
- package/bundled/skills/commands/brainstorm.md +12 -9
- package/bundled/skills/commands/config.md +0 -1
- package/bundled/skills/commands/init.md +2 -3
- package/bundled/skills/commit-standards/SKILL.md +2 -0
- package/bundled/skills/contract-test-assistant/SKILL.md +1 -0
- package/bundled/skills/dev-methodology/SKILL.md +4 -0
- package/bundled/skills/observability-assistant/SKILL.md +1 -0
- package/bundled/skills/project-discovery/SKILL.md +1 -0
- package/bundled/skills/project-structure-guide/SKILL.md +1 -0
- package/bundled/skills/release-standards/SKILL.md +3 -0
- package/bundled/skills/requirement-assistant/SKILL.md +2 -0
- package/bundled/skills/reverse-engineer/SKILL.md +3 -0
- package/bundled/skills/reverse-engineer/tdd-analysis.md +16 -23
- package/bundled/skills/runbook-assistant/SKILL.md +1 -0
- package/bundled/skills/slo-assistant/SKILL.md +1 -0
- package/bundled/skills/tdd-assistant/SKILL.md +2 -0
- package/bundled/skills/workflows/README.md +2 -11
- package/bundled/templates/.ai-context.yaml.template +194 -0
- package/bundled/templates/CLAUDE.md.template +145 -0
- package/bundled/templates/DESIGN.md +237 -0
- package/bundled/templates/SKILL-BRIEF-TEMPLATE.md +57 -0
- package/bundled/templates/SKILL-CANDIDATES.md +39 -0
- package/bundled/templates/gates/check-error-exit.mjs +309 -0
- package/bundled/templates/mcp-config.json +10 -0
- package/bundled/templates/methodology-template.yaml +209 -0
- package/bundled/templates/migration-template.md +408 -0
- package/bundled/templates/requirement-checklist.md +410 -0
- package/bundled/templates/requirement-document-template.md +591 -0
- package/bundled/templates/requirement-template.md +881 -0
- package/bundled/templates/reverse-spec-template.md +409 -0
- package/bundled/templates/test-case-template.md +74 -0
- package/bundled/templates/test-plan-template.md +74 -0
- package/package.json +9 -5
- package/src/commands/audit.js +82 -0
- package/src/commands/check.js +66 -10
- package/src/commands/init.js +161 -16
- package/src/commands/lint.js +96 -0
- package/src/commands/quickstart.js +16 -13
- package/src/commands/update.js +286 -14
- package/src/compilers/claude-code-compiler.js +4 -1
- package/src/config/ai-agent-paths.js +62 -17
- package/src/core/constants.js +42 -11
- package/src/core/manifest.js +201 -3
- package/src/core/paths.js +2 -2
- package/src/i18n/messages.js +9 -32
- package/src/installers/hooks-installer.js +167 -75
- package/src/installers/integration-installer.js +9 -5
- package/src/prompts/init.js +14 -14
- package/src/reconciler/actual-state-scanner.js +14 -3
- package/src/utils/detector.js +21 -1
- package/src/utils/effect-boundary.js +1093 -0
- package/src/utils/hasher.js +229 -9
- package/src/utils/hook-stats.js +1 -1
- package/src/utils/integration-generator.js +100 -4
- package/src/utils/reference-sync.js +4 -1
- package/src/utils/skills-installer.js +17 -3
- package/src/utils/spec-linter.js +35 -76
- package/src/utils/yaml-generator.js +51 -9
- package/standards-registry.json +31 -8
- package/src/commands/sync.js +0 -133
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../../core/governance-layer.md
|
|
3
|
-
source_version: 1.
|
|
4
|
-
translation_version: 1.
|
|
5
|
-
last_synced: 2026-
|
|
3
|
+
source_version: 1.1.0
|
|
4
|
+
translation_version: 1.1.0
|
|
5
|
+
last_synced: 2026-08-20
|
|
6
|
+
source_hash: 15ca18717240
|
|
6
7
|
status: current
|
|
7
8
|
---
|
|
8
9
|
|
|
@@ -10,8 +11,8 @@ status: current
|
|
|
10
11
|
|
|
11
12
|
> **語言**: [English](../../../core/governance-layer.md) | 繁體中文
|
|
12
13
|
|
|
13
|
-
**版本**: 1.
|
|
14
|
-
**最後更新**: 2026-
|
|
14
|
+
**版本**: 1.1.0
|
|
15
|
+
**最後更新**: 2026-08-20
|
|
15
16
|
**適用範圍**: 所有具有多 Agent 或多角色 AI 工作流程的軟體專案
|
|
16
17
|
**範疇**: universal
|
|
17
18
|
**產業標準**: 無(UDS 原創)
|
|
@@ -130,9 +131,79 @@ Vision(方向)→ Mission(邊界 + 紅線)→ Goals(可量測的 KPI
|
|
|
130
131
|
| `signatory` | 接受風險的人員或角色 |
|
|
131
132
|
| `gates_bypassed` | 列舉所有繞過的人工閘門 |
|
|
132
133
|
| `risks_accepted` | 明確描述已接受的風險 |
|
|
134
|
+
| `review_by` | 本次接受失效、必須重新做一次判斷的日期 |
|
|
133
135
|
|
|
134
136
|
若無有效的風險接受條款,pipeline **必須拒絕啟動(fail-closed)**。
|
|
135
137
|
|
|
138
|
+
### 接受到期
|
|
139
|
+
|
|
140
|
+
`review_by` 已過的條款**不是有效條款**。pipeline 必須 fail closed,與完全沒有條款時一模一樣。
|
|
141
|
+
|
|
142
|
+
`date` 記錄的是「何時接受了這個風險」,不是「何時該重新判斷」。沒有 `review_by`,簽過一次的接受就永遠有效——當初支持它的條件可能已經改變、簽署人可能已經離開專案,而條款裡每一個欄位讀起來仍然完全正確。
|
|
143
|
+
|
|
144
|
+
到期時,必須施用且只能施用下列三種處置之一,與[技術債標準 → 到期處置](tech-debt-standards.md#到期處置)所定義的三種相同:
|
|
145
|
+
|
|
146
|
+
| 處置 | 意義 |
|
|
147
|
+
|------|------|
|
|
148
|
+
| **重新接受** | 由當下的簽署人重新簽署,並給出新的 `review_by` |
|
|
149
|
+
| **撤銷** | 移除該繞過,恢復人工閘門 |
|
|
150
|
+
| **延期** | 新的 `review_by` **與**書面理由,一起記下 |
|
|
151
|
+
|
|
152
|
+
**禁止自動延長 `review_by`。** 那會把一道 fail-closed 的閘門變成 fail-open,而所有欄位看起來都還是對的——失效之所以隱形,正是因為條款仍然驗證得過。
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 待裁決事項
|
|
157
|
+
|
|
158
|
+
「還沒決定」是一種治理狀態,不是治理的缺席。規格裡的未決問題、提出但未批准的紅線、沒有 owner 的 KPI——每一項都是有人被期待要做的決定,而每一項對「只讀已做成決定」的檢查都是隱形的。
|
|
159
|
+
|
|
160
|
+
待裁決事項與已接受風險**同級受治理**:它們帶時鐘,而且必須可被列舉。
|
|
161
|
+
|
|
162
|
+
**規則 GOV-PD-001(必要)**——專案必須宣告待裁決事項**記在哪裡**,以及**什麼標記代表一項待裁決**:一個固定的 token(狀態值、標籤、字面標記字串),不得是自由書寫的散文。列舉不該取決於讀者猜中當初用了哪些字。三份分別寫「TBD」「待拍板」「待確認」的文件,是三份無法被列舉的文件;一個宣告過的標記讓三份都找得到。
|
|
163
|
+
|
|
164
|
+
**規則 GOV-PD-002(必要)**——列舉待裁決事項時,必須同時回報總數**與**無法解析的來源份數(見[匯總報告](#匯總報告))。「查無待裁決事項」在不知道走訪集合有多大時,不帶任何資訊。
|
|
165
|
+
|
|
166
|
+
**規則 GOV-PD-003(必要)**——每一項待裁決事項都帶一個**裁決期限日期**。到期時適用與逾期技術債相同的三種處置——**做出決定**、**撤回這個問題**、或**延期並寫明理由**。禁止自動延期。
|
|
167
|
+
|
|
168
|
+
**規則 GOV-PD-004(必要)**——若沒有任何東西在排程上列舉待裁決事項,專案必須帶一份**無人看管宣告**,寫明負責人、複查頻率與最後複查日期——與技術債登記表被要求的兩態規則相同。沒有被列舉是可接受的;沒有被列舉又沒有宣告則不可接受。
|
|
169
|
+
|
|
170
|
+
> 一項沒有日期的待裁決事項,在行為上與「決定不做」完全相同。差別只在於待裁決的形式讓人以為還有人會去看它。
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## 匯總報告
|
|
175
|
+
|
|
176
|
+
每一份治理報告——合規摘要、閘門報告、KPI 匯總、紅線掃描——都是對某個集合提出的宣稱。這個宣稱的價值,恰好等於它對「自己判不了什麼」的交代的價值。
|
|
177
|
+
|
|
178
|
+
**規則 GOV-RPT-001(必要)**——報告必須印出三個數字,不能只印兩個:**通過**、**失敗**、**判不了**(無法解析的檔案、缺欄位、來源不可達、不支援的格式)。
|
|
179
|
+
|
|
180
|
+
**規則 GOV-RPT-002(必要)**——「判不了」**不得**併入「通過」,也**不得**省略。一份解析不了的檔案不是一份乾淨的檔案。只印「N 項檢查通過」的報告,不論 N 是多少都不合規。
|
|
181
|
+
|
|
182
|
+
**規則 GOV-RPT-003(必要)**——報告必須寫出自己的**分母**以及分母是怎麼推導出來的。範圍來自硬編碼清單的報告,是一份關於那份清單的報告,不是關於這個專案的報告:清單之外的東西全部腐壞,它照樣是綠的。要用「走訪並排除」推導集合,不要用列舉——見[類別層級修正](class-level-fix.md)。
|
|
183
|
+
|
|
184
|
+
**規則 GOV-RPT-004(必要)**——正向與負向計數分開回報;絕不合併成單一的合規分數。**一個「什麼都不做」與「把工作做完」得分相同的指標,量的不是那份工作。**「11 項中通過 5 項」與「檢查器從未啟動」產生同一個數字,而單一分數分不出這兩者。
|
|
185
|
+
|
|
186
|
+
**規則 GOV-RPT-005(建議)**——當報告的正確性取決於它自己的工具能運作時,加一隻金絲雀:一個輸入已知會失敗、因此**必須**失敗的檢查。若金絲雀通過了,整份報告不可信,必須整份回報為「判不了」,而不是綠燈。
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## 新鮮度指標
|
|
191
|
+
|
|
192
|
+
**規則 GOV-FRESH-001(必要)**——任何新鮮度/停滯指標都必須指名它讀的是下列哪一個時鐘:
|
|
193
|
+
|
|
194
|
+
| 時鐘 | 回答的問題 | 可以從哪裡讀 |
|
|
195
|
+
|------|-----------|-------------|
|
|
196
|
+
| **編輯時間** | 這份產物上次被改動是多久以前? | 檔案 mtime、最後動到它的 commit、「最後更新」欄位 |
|
|
197
|
+
| **對帳時間** | 這份產物上次與它宣稱在描述的真實來源做比對是多久以前? | 那次比對被記下的日期——沒有別的東西能提供它 |
|
|
198
|
+
|
|
199
|
+
**規則 GOV-FRESH-002(必要)**——兩者**不得**共用同一個欄位或同一個欄位標題。它們回答不同的問題,而同一份產物可以在其中一個上滿分、在另一個上任意地舊:一份今天剛編輯、內容從未與現實對過的文件,以編輯時間算是零天,以對帳時間算是無上限。
|
|
200
|
+
|
|
201
|
+
**規則 GOV-FRESH-003(必要)**——只有編輯時間可取得時,報告必須把該欄標示為編輯時間,**並且**把對帳時間回報為「判不了」(GOV-RPT-001)——絕不能標成新鮮,也絕不能省略不提。
|
|
202
|
+
|
|
203
|
+
**規則 GOV-FRESH-004(建議)**——對帳時間只有在「由執行該比對的東西自己記下」時才有意義。事後由人手動填入的日期是一項斷言,不是一次量測;請如實標示。
|
|
204
|
+
|
|
205
|
+
> 這是「單軸裝多維」的失敗:一個欄位,被兩個不同的問題讀取。這個欄位永遠不會被抓到是錯的,因為從來沒有人問過它在回答哪一個問題。
|
|
206
|
+
|
|
136
207
|
---
|
|
137
208
|
|
|
138
209
|
## 治理檔案結構
|
|
@@ -156,4 +227,46 @@ governance/
|
|
|
156
227
|
- [ ] Goals 清單存在,每個 KPI 均含:id、metric_name、threshold、measurement_method
|
|
157
228
|
- [ ] 沒有任何 KPI 使用模糊詞彙(「改善」、「提升」、「更好」)
|
|
158
229
|
- [ ] 若 `gate.mode = trace_only`,`mission.md` 中存在風險接受條款
|
|
230
|
+
- [ ] 每一份風險接受條款都有 `review_by` 日期,且沒有任何一份已經過期
|
|
231
|
+
- [ ] 專案已宣告待裁決事項記在哪裡、以及哪一個固定標記代表一項待裁決
|
|
232
|
+
- [ ] 每一項待裁決事項都有裁決期限日期
|
|
233
|
+
- [ ] 待裁決事項要麼被某個會執行的東西列舉,要麼被無人看管宣告涵蓋
|
|
234
|
+
- [ ] 每一份治理報告都分開印出「通過/失敗/**判不了**」,並寫出分母與分母的推導方式
|
|
235
|
+
- [ ] 沒有任何報告把正向與負向計數合併成單一分數
|
|
236
|
+
- [ ] 每一個新鮮度指標都指名自己讀的是編輯時間或對帳時間,且兩者不共用欄位
|
|
159
237
|
- [ ] 所有 AI 評估器以 0.4/0.3/0.3 權重評分,且任一軸 < 0.3 即不通過
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## 執行現實
|
|
242
|
+
|
|
243
|
+
> **本標準對它的任何一條規則都不提供檢查器——不只是 1.1.0 新增的那些,也包括自 1.0.0 起就在裡面的那條 fail-closed 風險接受要求。這是已知代價,寫在這裡,而不是留給採用者自己撞到。**
|
|
244
|
+
>
|
|
245
|
+
> 2026-08-20 實測:`review_by`、`risks_accepted`、`gates_bypassed` **沒有出現在任何程式裡**——UDS CLI 沒有,任何消費端也沒有。那句寫著 pipeline「必須拒絕啟動」的條款,在它被寫下來的三個半月裡,**從來沒有讓任何一條 pipeline 拒絕啟動過**。把這件事講明白不是外加的但書,它就是本節自己的規則套用在本節身上;而本節的初稿只列出新規則為未執行,那會讓人以為舊的那條有在執行。
|
|
246
|
+
>
|
|
247
|
+
> UDS 定義的是這些要求,它不提供執行這些要求的程式。想要它們被執行的採用者必須自己寫那支列舉器、那支三態計數報告器、那個對帳日期記錄器——而多數人不會寫。那正是本標準所描述的失敗,現在同樣適用於本標準自己。
|
|
248
|
+
>
|
|
249
|
+
> 所以最低標準**不是**「去把工具做出來」,而是:**任何被記載為待裁決、已接受、或新鮮的東西,要麼指向一個會執行的檢查,要麼明白說出沒有東西在看它。** 宣告「無人看管」是合規的。無人看管卻不宣告,才是這些規則真正禁止的唯一結果,因為只有它會讓讀者對「有沒有東西在看」產生誤解。
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## 版本歷史
|
|
254
|
+
|
|
255
|
+
| 版本 | 日期 | 變更 |
|
|
256
|
+
|------|------|------|
|
|
257
|
+
| 1.1.0 | 2026-08-20 | 新增:風險接受條款的 `review_by` 欄位 + 接受到期的三種處置與禁止自動延期;待裁決事項(GOV-PD-001..004);匯總報告(GOV-RPT-001..005——通過/失敗/判不了、分母推導、不得合併成單一分數、金絲雀);新鮮度指標(GOV-FRESH-001..004——編輯時間與對帳時間不得共用欄位);執行現實說明;合規檢查清單擴充 |
|
|
258
|
+
| 1.0.0 | 2026-05-07 | 初始版本:Vision/Mission/Goals 三層架構、紅線格式、評估器整合、風險接受條款、合規檢查清單 |
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## 相關標準
|
|
263
|
+
|
|
264
|
+
- [技術債標準](tech-debt-standards.md) — 「到期處置」定義了本標準沿用的三種處置
|
|
265
|
+
- [類別層級修正](class-level-fix.md) — 以走訪並排除而非列舉推導集合(GOV-RPT-003)
|
|
266
|
+
- [驗證證據](verification-evidence.md) — 為何綠燈必須被證明來自一個真的在運作的檢查(GOV-RPT-005)
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## 授權
|
|
271
|
+
|
|
272
|
+
本標準以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 釋出。
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
source: ../../../core/model-provenance.md
|
|
3
3
|
source_version: 1.0.0
|
|
4
4
|
translation_version: 1.0.0
|
|
5
|
-
last_synced: 2026-
|
|
6
|
-
source_hash:
|
|
5
|
+
last_synced: 2026-07-23
|
|
6
|
+
source_hash: 59e471405e7e
|
|
7
7
|
status: current
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -15,6 +15,8 @@ status: current
|
|
|
15
15
|
> **AI 最佳化版本**: `ai/standards/model-provenance.ai.yaml`
|
|
16
16
|
> **規格**: XSPEC-255 (cross-project/specs/XSPEC-255-model-provenance-policy.md)
|
|
17
17
|
|
|
18
|
+
**Scope**: universal
|
|
19
|
+
|
|
18
20
|
## 概述
|
|
19
21
|
|
|
20
22
|
模型選擇不只是「成本 × 品質」——還有 **第三軸:模型的*來源*是否被客戶接受**(地緣政治 /
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../../core/pii-classification.md
|
|
3
|
-
source_version: 1.
|
|
4
|
-
translation_version: 1.
|
|
5
|
-
last_synced: 2026-
|
|
6
|
-
source_hash:
|
|
7
|
-
status:
|
|
3
|
+
source_version: 1.1.0
|
|
4
|
+
translation_version: 1.1.0
|
|
5
|
+
last_synced: 2026-07-23
|
|
6
|
+
source_hash: 16bf07c4e383
|
|
7
|
+
status: current
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# PII 分類與處理標準
|
|
11
11
|
|
|
12
12
|
> **Language**: [English](../../../core/pii-classification.md) | 繁體中文
|
|
13
13
|
|
|
14
|
-
> **版本**: 1.
|
|
14
|
+
> **版本**: 1.1.0 | **狀態**: Active | **更新日期**: 2026-06-19
|
|
15
15
|
> **AI 最佳化版本**: `ai/standards/pii-classification.ai.yaml`
|
|
16
16
|
> **規格**: XSPEC-066(cross-project/specs/XSPEC-066-uds-compliance-audit-pack.md)
|
|
17
17
|
|
|
@@ -90,6 +90,41 @@ TIER-1 或 TIER-2 PII 的跨國境傳輸 MUST 遵循適用的傳輸機制。EU
|
|
|
90
90
|
- **`database-standards`**——資料字典欄位帶有 PII 等級與 REQ-002 的文件化目的/
|
|
91
91
|
法律依據。
|
|
92
92
|
|
|
93
|
+
## PII 發現與交接契約
|
|
94
|
+
|
|
95
|
+
上述整合僅指出了消費方,但交接需要明確定義的**觸發點、介面、負責人與狀態**——
|
|
96
|
+
否則「驅動遮罩規則」只是一種主張,而非契約。本節沿用 `data-contract` REQ-005
|
|
97
|
+
的消費方註冊模型,以及 `agent-communication-protocol` §3 的結構化交接形式。
|
|
98
|
+
|
|
99
|
+
### 觸發點——分類何時啟動
|
|
100
|
+
|
|
101
|
+
| 時機 | 發生的事 |
|
|
102
|
+
|------|----------|
|
|
103
|
+
| 新功能設計 | REQ-006 PII 衝擊評估**須於**實作前為每個新 PII 欄位分類 |
|
|
104
|
+
| PR/掃描時 | 帶有 PII 但無等級標記的欄位為**阻擋(blocking)**發現(CI) |
|
|
105
|
+
| 資料字典變更 | `database-standards` 欄位新增/移除 PII 等級 → 重新通知消費方 |
|
|
106
|
+
|
|
107
|
+
### 介面——傳遞的內容
|
|
108
|
+
|
|
109
|
+
生產方產出物是每個欄位的**PII 分類登錄(registry)**項目:
|
|
110
|
+
`{ field, tier (TIER-1/2/3), purpose, legal_basis, masking_rule, retention }`。
|
|
111
|
+
消費方依此註冊(依 `data-contract` REQ-005),並於變更時收到通知。
|
|
112
|
+
|
|
113
|
+
### 負責人與已註冊消費方
|
|
114
|
+
|
|
115
|
+
| 角色 | 職責 |
|
|
116
|
+
|------|------|
|
|
117
|
+
| 資料負責人/功能作者 | **產出**分類結果(REQ-001/REQ-006) |
|
|
118
|
+
| `logging-standards`(消費方) | 對非正式環境中的 TIER-1/2 套用 `masking_rule` 並記錄日誌 |
|
|
119
|
+
| `audit-trail`(消費方) | 記錄必備的存取/匯出/刪除事件 |
|
|
120
|
+
| `security-standards`(消費方) | 對 TIER-1 強制執行靜態/傳輸中加密 |
|
|
121
|
+
| 隱私/合規負責人 | 於任何新增 TIER-1 欄位或分類變更時**收到通知** |
|
|
122
|
+
|
|
123
|
+
### 狀態轉換
|
|
124
|
+
|
|
125
|
+
`Found(已發現)→ Classified(已分類,已指定等級)→ Handled(已處理:遮罩/加密/已設定保留期)→ Verified(已驗證:消費方確認規則已套用)`。
|
|
126
|
+
停留在 `Found`(有 PII 但無等級)狀態的欄位**將阻擋發布**(REQ-001 + 上述 PR 時觸發規則)。
|
|
127
|
+
|
|
93
128
|
## 相關規格
|
|
94
129
|
|
|
95
130
|
- XSPEC-066 — UDS 合規與稽核標準包(本標準來源)
|
|
@@ -99,4 +134,5 @@ TIER-1 或 TIER-2 PII 的跨國境傳輸 MUST 遵循適用的傳輸機制。EU
|
|
|
99
134
|
|
|
100
135
|
| 版本 | 日期 | 變更 |
|
|
101
136
|
|------|------|------|
|
|
137
|
+
| v1.1.0 | 2026-06-19 | 新增:PII 發現與交接契約(觸發點/介面/負責人/狀態),使宣稱與 logging-standards/audit-trail 的交接成為明確契約而非空談(XSPEC-292 T16) |
|
|
102
138
|
| v1.0.0 | 2026-06-17 | 初版——REQ-001~006:PII 等級、資料最小化、非正式環境遮罩、保留/刪除、跨境傳輸、PIA(XSPEC-066) |
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
source: ../../../core/prd-standards.md
|
|
3
3
|
source_version: 1.0.0
|
|
4
4
|
translation_version: 1.0.0
|
|
5
|
-
last_synced: 2026-
|
|
6
|
-
source_hash:
|
|
5
|
+
last_synced: 2026-07-23
|
|
6
|
+
source_hash: 73615684c1be
|
|
7
7
|
status: current
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -15,6 +15,8 @@ status: current
|
|
|
15
15
|
> **AI 最佳化版本**: `ai/standards/prd-standards.ai.yaml`
|
|
16
16
|
> **規格**: XSPEC-069(cross-project/specs/XSPEC-069-uds-product-layer-pack.md)
|
|
17
17
|
|
|
18
|
+
**Scope**: universal
|
|
19
|
+
|
|
18
20
|
## 概觀
|
|
19
21
|
|
|
20
22
|
本標準定義**產品需求文件(PRD)**的結構、內容要求與生命週期治理。涵蓋五大必備
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
source: ../../../core/product-metrics-standards.md
|
|
3
3
|
source_version: 1.0.0
|
|
4
4
|
translation_version: 1.0.0
|
|
5
|
-
last_synced: 2026-
|
|
6
|
-
source_hash:
|
|
5
|
+
last_synced: 2026-07-23
|
|
6
|
+
source_hash: 111babd0b39d
|
|
7
7
|
status: current
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -15,6 +15,8 @@ status: current
|
|
|
15
15
|
> **AI 最佳化版本**: `ai/standards/product-metrics-standards.ai.yaml`
|
|
16
16
|
> **規格**: XSPEC-069(cross-project/specs/XSPEC-069-uds-product-layer-pack.md)
|
|
17
17
|
|
|
18
|
+
**Scope**: universal
|
|
19
|
+
|
|
18
20
|
## 概觀
|
|
19
21
|
|
|
20
22
|
本標準定義團隊如何**選擇、結構化與治理產品指標**。涵蓋框架選用矩陣(成長型用
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../../core/retrospective-standards.md
|
|
3
|
-
source_version: 1.
|
|
4
|
-
translation_version: 1.
|
|
5
|
-
last_synced: 2026-
|
|
3
|
+
source_version: 1.1.0
|
|
4
|
+
translation_version: 1.1.0
|
|
5
|
+
last_synced: 2026-08-24
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -90,6 +90,8 @@ Open ──► In Progress ──► Done
|
|
|
90
90
|
└──► Cancelled(附原因)
|
|
91
91
|
```
|
|
92
92
|
|
|
93
|
+
> Retrospective 記下的**延後項目**(`Action Items`、`Previous Action Items Review` 中仍為 Open 的列、附理由 Cancelled 的項目)適用 [deferred-item-exit](deferred-item-exit.md)。
|
|
94
|
+
|
|
93
95
|
### 追蹤規則
|
|
94
96
|
|
|
95
97
|
1. 在每次回顧的**開頭**檢視所有未完成的行動項目。
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../../core/reverse-engineering-standards.md
|
|
3
|
-
source_version: 1.
|
|
4
|
-
translation_version: 1.
|
|
5
|
-
last_synced: 2026-
|
|
3
|
+
source_version: 1.3.0
|
|
4
|
+
translation_version: 1.3.0
|
|
5
|
+
last_synced: 2026-08-20
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# 反向工程標準
|
|
10
10
|
|
|
11
|
-
**版本**: 1.
|
|
12
|
-
**最後更新**: 2026-
|
|
11
|
+
**版本**: 1.3.0
|
|
12
|
+
**最後更新**: 2026-08-20
|
|
13
13
|
**適用範圍**: 所有需要將程式碼轉換為規格文件的專案
|
|
14
14
|
|
|
15
15
|
> **語言**: [English](../../../core/reverse-engineering-standards.md) | [繁體中文](reverse-engineering-standards.md)
|
|
@@ -58,10 +58,13 @@ status: current
|
|
|
58
58
|
| **程式碼掃描** | 分析程式碼結構、API、資料模型 | 技術清單 | [已確認] |
|
|
59
59
|
| **測試分析** | 解析現有測試以取得驗收條件 | 草擬驗收條件 | [已確認]/[推論] |
|
|
60
60
|
| **隱含規則掃描** | 掃描非 HTTP 持久化寫入路徑中未文件化的規則 | 隱含規則清單 + 三問解答 | [已確認]/[推論]/[未知] |
|
|
61
|
+
| **授權範圍擷取** | 擷取每一個以操作者自身身分為界的查詢述詞 | 自我限縮述詞清單 + 必要的負向測試 | [已確認]/[推論]/[未知] |
|
|
61
62
|
| **缺口識別** | 列出需要人類輸入的未知項目 | 缺口分析文件 | [未知] 項目 |
|
|
62
63
|
| **規格生成** | 生成草擬規格 | 草擬 SPEC-XXX.md | 混合確定性 |
|
|
63
64
|
| **人類審查** | 利害關係人驗證與填補缺口 | 已驗證的規格 | [已確認] |
|
|
64
65
|
|
|
66
|
+
> **註(v1.3.0)**:**授權範圍擷取** 階段與隱含規則掃描並行——詳見下方[授權範圍擷取(自我指涉的查詢述詞)](#授權範圍擷取自我指涉的查詢述詞)。隱含規則掃描處理的是「因為跑在請求路徑**之外**而隱形」的規則;本階段處理的是「坐在一條被完整操作過的請求路徑**之上**卻仍然隱形」的規則:一個以操作者自身身分為界的 `WHERE` 述詞。它讀起來就像眾多過濾條件之一,而一次把它丟掉的重寫,會回傳形狀完全正確的資料——屬於所有人的資料。
|
|
67
|
+
>
|
|
65
68
|
> **註(v1.2.0)**:在程式碼掃描/測試分析之後、缺口識別之前,插入一個 **隱含規則掃描** 階段——詳見下方[隱含規則掃描(非 HTTP 持久化規則)](#隱含規則掃描非-http-持久化規則)。標準程式碼掃描只提取 HTTP 入口點與資料模型,但持久化欄位的值經常由**非 HTTP 路徑**(cron、佇列、計算欄、trigger、ORM hook)寫入,其業務規則從未被文件化——這是跨語言重寫或跨 DB 遷移時遺漏邏輯的最高發來源。
|
|
66
69
|
|
|
67
70
|
---
|
|
@@ -105,6 +108,80 @@ pre-flight(規劃期)。任何三問未獲解答的非 HTTP 寫入欄位會
|
|
|
105
108
|
|
|
106
109
|
---
|
|
107
110
|
|
|
111
|
+
## 授權範圍擷取(自我指涉的查詢述詞)
|
|
112
|
+
|
|
113
|
+
> **工作流程位置**:與隱含規則掃描並行——在程式碼掃描/測試分析之後、缺口識別之前。
|
|
114
|
+
|
|
115
|
+
**自我指涉述詞**是一個以「誰在問」為界限來限縮結果集的查詢條件:`WHERE tenant_id = :current_user_tenant`、`WHERE owner = :uid`、`WHERE dept_id = (SELECT dept_id FROM member WHERE account = :uid)`。它就是那一行把「列出帳號」變成「列出**你的**帳號」的條件。
|
|
116
|
+
|
|
117
|
+
本階段要回答的問題很窄、也很機械:
|
|
118
|
+
|
|
119
|
+
> **舊碼裡每一個以操作者自身身分為界的查詢述詞,新碼有沒有等價的述詞?**
|
|
120
|
+
|
|
121
|
+
不是「回傳的形狀一不一樣」,也不是「有沒有回傳資料」。是**等價的述詞**:同一個欄位,綁定到同一個「自己」的定義。
|
|
122
|
+
|
|
123
|
+
### 為什麼它需要自己的階段
|
|
124
|
+
|
|
125
|
+
授權不是一個被漏掉的關注點——任何像樣的測試分類法都已經點名跨租戶存取是該測的東西。這個關注點不會消失,**它是不會被想起來**。有三個性質讓這個特定缺陷能穿過每一道本該擋住它的閘門:
|
|
126
|
+
|
|
127
|
+
1. **那條安全關鍵的程式碼看起來像個過濾條件。** 界限住在 `WHERE` 子句裡,不在請求/回應契約裡。負責移植「取得所有帳號」的人看到的是一個 `SELECT` 和一個 `JOIN`;租戶述詞讀起來就是眾多條件之一。
|
|
128
|
+
2. **基於形狀的斷言看不見範圍。** 一個以某個有效管理員身分呼叫該 endpoint、斷言 `200` 加非空清單的測試,在「範圍限縮正確」與「範圍限縮被整條刪掉」兩種情況下**完全一樣地通過**。契約測試、對等快照、response DTO 比對在此結構上全是盲的:兩種情況下回應都是良構的,它只是屬於所有人。
|
|
129
|
+
3. **有一個共用的 resolver,不等於這個 call site 有在用它。** 已經被燒過一次的程式庫通常會長出一支共用的範圍解析工具。一個新的或被忽略的 call site 可以從頭重寫這個查詢而從未呼叫它——此時那支工具的存在反而具有主動誤導性,因為它讀起來像是覆蓋。
|
|
130
|
+
|
|
131
|
+
### 清單來源(derive,機械化)
|
|
132
|
+
|
|
133
|
+
掃描舊系統的資料存取層來列舉候選述詞——不要靠回憶。模式依技術棧調整;目標是任何「右手邊解析成**呼叫者自己的值**」的條件:
|
|
134
|
+
|
|
135
|
+
| 訊號 | 範例 |
|
|
136
|
+
|------|------|
|
|
137
|
+
| **直接自我綁定** | `WHERE <col> = :currentUser` / `:uid` / `$operatorId` / `session.user_id` |
|
|
138
|
+
| **租戶/組織/擁有者欄位** | `tenant_id`、`org_id`、`master_account`、`owner_id`、`dept_id`、`company_id` 與呼叫者導出的值比較 |
|
|
139
|
+
| **解析呼叫者範圍的子查詢** | `WHERE dept_id = (SELECT dept_id FROM member WHERE account = :uid)` |
|
|
140
|
+
| **依角色分支的查詢建構** | 依 `role`/`account_type` 分支,而**每個分支**套用不同範圍——要列舉每一個分支,不是只列 happy path 走到的那個 |
|
|
141
|
+
| **在 SQL 之外套用的範圍** | ORM global scope、query builder mixin、repository 基底類別、row-level security 政策、注入過濾條件的 middleware |
|
|
142
|
+
|
|
143
|
+
最後一列很重要:一個述詞可以由 `SELECT` 語句從未提及的東西來執行。只 grep SQL 會回報一個**比實際更小**的集合,而在這裡,更小的集合讀起來恰好就像更安全的集合。
|
|
144
|
+
|
|
145
|
+
### 逐項記錄
|
|
146
|
+
|
|
147
|
+
對每個候選項記錄——`[已確認]` 必須附 `file:line` 引用:
|
|
148
|
+
|
|
149
|
+
| 欄位 | 內容 |
|
|
150
|
+
|------|------|
|
|
151
|
+
| **位置** | 舊碼中的 `file:line` |
|
|
152
|
+
| **述詞** | 條件的原文 |
|
|
153
|
+
| **自我綁定** | 它解析到哪一個呼叫者導出的值,以及那個值是怎麼取得的 |
|
|
154
|
+
| **觸發分支** | 哪一個角色/參數/程式路徑會走到這個述詞 |
|
|
155
|
+
| **確定性** | `[已確認]`/`[推論]`/`[未知]` |
|
|
156
|
+
|
|
157
|
+
每個 `[未知]`——你無法從程式碼判定的範圍——都交給缺口識別由人類處理。絕不臆測,也絕不假設它不存在。
|
|
158
|
+
|
|
159
|
+
### Oracle(detect)——述詞等價性,逐 call site
|
|
160
|
+
|
|
161
|
+
對每個記錄下來的述詞,在移植後的程式碼中驗證:
|
|
162
|
+
|
|
163
|
+
1. **存在字面上的等價物**——同一個欄位,綁定到同一個「自己」的定義。一個「剛好對現有資料回傳相同列」的不同欄位不是等價物,它是一個帶到期日的巧合。
|
|
164
|
+
2. **每一個分支都被涵蓋。** 若舊碼依角色套用不同範圍,每個分支都需要各自被驗證過的等價物。把五個角色分支塌縮成一個粗糙的「這是不是管理員?」檢查,等於用一個權限取代了一道界限。
|
|
165
|
+
3. **這個 call site 有呼叫共用 resolver。** 若新系統把範圍限縮集中在某支工具裡,要確認**這一個** call site 真的有呼叫它。那支工具存在於程式庫別處,不構成關於這個 endpoint 的證據。
|
|
166
|
+
|
|
167
|
+
### 必要的負向測試
|
|
168
|
+
|
|
169
|
+
**規則 RE-AUTH-001(必要)**——每一個已確認的自我限縮述詞都必須被一個**負向測試**鎖住:由操作者 **A** 發出請求,斷言的是操作者 **B** 的紀錄**不存在**於回應中。A 與 B 都是有效、已認證、且有權使用該 endpoint 的操作者。
|
|
170
|
+
|
|
171
|
+
斷言的對象必須是**不存在**。斷言 `200`、斷言清單非空、斷言回應 schema 相符的測試,都不構成充分證據,且**不得**被計為該述詞的覆蓋——因為把範圍限縮子句刪掉之後,它們每一個都照樣通過。
|
|
172
|
+
|
|
173
|
+
在信任這個測試之前,有一個好用的自我檢查:**在一份暫存副本裡把範圍限縮述詞刪掉,重跑一次。** 如果測試還是通過,那它就不是在測範圍,不管它的名字怎麼寫。
|
|
174
|
+
|
|
175
|
+
### Gate 時機
|
|
176
|
+
|
|
177
|
+
擷取為 pre-flight(規劃期);負向測試為 pre-UAT。
|
|
178
|
+
|
|
179
|
+
**規則 RE-AUTH-002(必要)**——任何「移植後等價物未經驗證」或「沒有負向測試」的自我限縮述詞,一律標為 `not_implemented` 並 **block cutover**。一道未經驗證的授權界限是已知遺漏風險,不是可接受的缺口——它的失敗模式是跨租戶資料外洩,而且它會以綠燈出貨。
|
|
180
|
+
|
|
181
|
+
> **來歷。** 本階段源自一次真實的 PHP → C# 遷移:一個以租戶為界的帳號列表 endpoint 在重寫過程中弄丟了它的隔離述詞。移植版把「依角色限縮範圍」換成粗糙的「這個帳號是不是任何一個已啟用的管理員?」檢查,於是不論是誰在問,它都回傳資料庫裡的每一個帳號。它出貨了、通過了所有既有測試(那個方法一個測試都沒有),最後是客戶回報「我看到了不該看到的帳號資訊」才被發現。
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
108
185
|
## 核心原則
|
|
109
186
|
|
|
110
187
|
### 1. 確定性框架
|
|
@@ -446,6 +523,7 @@ Feature: 購物車
|
|
|
446
523
|
|
|
447
524
|
| 版本 | 日期 | 變更內容 |
|
|
448
525
|
|------|------|----------|
|
|
526
|
+
| 1.3.0 | 2026-08-20 | 新增:授權範圍擷取階段(自我指涉的查詢述詞)——derive 訊號含 SQL 之外的範圍執行點、逐項記錄附 `file:line`、涵蓋每個角色分支與逐 call site resolver 使用的述詞等價性 oracle、規則 RE-AUTH-001(必要負向測試,斷言另一操作者的紀錄「不存在」)與 RE-AUTH-002(未驗證述詞 block cutover)(issue [#166](https://github.com/AsiaOstrich/universal-dev-standards/issues/166)) |
|
|
449
527
|
| 1.2.0 | 2026-06-27 | 新增:隱含規則掃描階段(非 HTTP 持久化寫入路徑擷取)——4 類 derive 清單 + 三問 oracle + 非 HTTP Devil's Advocate + PHP type-juggling 補述 + 確定性/`file:line`(XSPEC-284 R4/AC-8) |
|
|
450
528
|
| 1.1.0 | 2026-06-18 | 新增:失敗處理與升級章節——解析失敗/高未知比例/被推翻推論的升級 + 規則 RE-FAIL-001(XSPEC-292 T7) |
|
|
451
529
|
| 1.0.0 | 2026-01-19 | 初始發布 |
|
|
@@ -45,6 +45,8 @@ SDD 在不同的成熟度層級運作:規格優先(完成後丟棄)、規
|
|
|
45
45
|
| **AC YAML Sidecar** | 建議在 AC 超過 3 條時使用 .ac.yaml(機器可讀 AC) |
|
|
46
46
|
| **AI Agent 行為** | 可選章節,用於在規格中定義 Agent 角色、規則、品質檢查、限制 |
|
|
47
47
|
|
|
48
|
+
> 規格記下的**延後項目**(未納入/不在本版的條目、open questions、仍待確認的 assumptions)適用 [deferred-item-exit](deferred-item-exit.md)。
|
|
49
|
+
|
|
48
50
|
## AC 格式
|
|
49
51
|
|
|
50
52
|
UDS 支援兩種 AC 記法。**GWT 為預設與首選**(Forward Derivation/BDD 場景生成依賴它)。**EARS**(Easy Approach to Requirements Syntax,IBM Rational)為可選補充,對事件/狀態/恆常/異常需求表達更精準。
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../../core/tech-debt-standards.md
|
|
3
|
-
source_version: 1.
|
|
4
|
-
translation_version: 1.
|
|
5
|
-
last_synced: 2026-
|
|
3
|
+
source_version: 1.1.0
|
|
4
|
+
translation_version: 1.1.0
|
|
5
|
+
last_synced: 2026-08-20
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# 技術債管理標準
|
|
10
10
|
|
|
11
|
-
> 版本: 1.
|
|
11
|
+
> 版本: 1.1.0 | 最後更新: 2026-08-20
|
|
12
12
|
|
|
13
13
|
## 概述
|
|
14
14
|
|
|
@@ -48,6 +48,73 @@ status: current
|
|
|
48
48
|
| 10 | **Created Date** | 登記日期 |
|
|
49
49
|
| 11 | **Target Resolution Date** | 計劃解決日期 |
|
|
50
50
|
|
|
51
|
+
### 登記表儲存選項
|
|
52
|
+
|
|
53
|
+
登記表可存放於下列任一位置,但每個選項**只有在同時滿足右欄的到期檢查條件時才合法**:
|
|
54
|
+
|
|
55
|
+
| 選項 | 適用對象 | 到期檢查條件 |
|
|
56
|
+
|------|---------|-------------|
|
|
57
|
+
| `docs/tech-debt-registry.md` | 小型團隊 | 有一支 repo 檢查會解析該表格,並在有列超過 Target Resolution Date 時失敗——**或**該檔帶有「無人看管宣告」 |
|
|
58
|
+
| Issue tracker(GitHub Issues、Jira) | 較大團隊 | 有一個排程查詢實際會**執行**並發出告警;沒有人打開的儲存查詢不算檢查——**或**帶有「無人看管宣告」 |
|
|
59
|
+
| 專用試算表 | 非技術利害關係人 | 僅當該表以明訂頻率匯出到某個會被檢查讀取的位置時才合法——**或**帶有「無人看管宣告」 |
|
|
60
|
+
|
|
61
|
+
> **這一欄為什麼必須加。** 一份沒有任何程式讀得到的登記表,滿足本節其餘每一條要求:11 個欄位齊全、有 Owner、有 Target Resolution Date。它沒有任何地方是錯的——直到日期過了,然後什麼都沒發生。試算表選項**刻意不移除**(試算表常是出錢的人唯一會打開的格式);不再合法的是「任何一種儲存方式成為日期無聲過期的地方」。
|
|
62
|
+
|
|
63
|
+
### 到期處置
|
|
64
|
+
|
|
65
|
+
一個過了卻沒有任何後果的 **Target Resolution Date**,與根本沒有日期無從分辨。本小節定義「日期到了」是什麼意思。
|
|
66
|
+
|
|
67
|
+
#### 三種合法處置
|
|
68
|
+
|
|
69
|
+
項目到達 Target Resolution Date 時,必須發生且只能發生下列三者之一,並且必須留下痕跡:
|
|
70
|
+
|
|
71
|
+
| 處置 | 意義 | 必留痕跡 |
|
|
72
|
+
|------|------|---------|
|
|
73
|
+
| **做掉(Resolve)** | 把事情做完 | 關閉登記項 + `Tech-Debt: TD-NNN resolved` commit footer |
|
|
74
|
+
| **撤銷(Withdraw)** | 決定不做,並刪掉這筆記載 | 標記為撤銷,附理由與日期。它不再被計為技術債,因為它已經不是了 |
|
|
75
|
+
| **延期(Extend)** | 設定新的 Target Resolution Date | 新日期**與**書面理由必須一起記下;先前的日期保持可見(用附加,不要覆蓋) |
|
|
76
|
+
|
|
77
|
+
沒有第四種處置。「仍然開著、日期過了、沒有人看」不是本標準允許的狀態——那正是本小節存在要指名的失敗。
|
|
78
|
+
|
|
79
|
+
**規則 TD-EXP-001(必要)**——項目超過 Target Resolution Date 而三種處置皆未施用,該登記表即不合規。到期是一個發現,不是中性的背景狀態。
|
|
80
|
+
|
|
81
|
+
**規則 TD-EXP-002(必要,禁止事項)**——到期**不得**被實作成**自動延期**或**自動關閉**。
|
|
82
|
+
|
|
83
|
+
- 自動延期使日期變得不可證偽:它永遠不會被錯過,所以它從未量到任何東西。
|
|
84
|
+
- 自動關閉在沒有任何人做出決定的情況下刪掉了那筆記載。
|
|
85
|
+
|
|
86
|
+
兩者都讓時鐘停止,且都不留下「時鐘停了」的痕跡。一個唯一的消費者是「把它往後推的排程」的日期,只是裝飾。
|
|
87
|
+
|
|
88
|
+
**規則 TD-EXP-003(必要)**——延期時理由必須記在新日期旁邊。只改日期不是延期,那是一次蓋了時間戳的刪除。
|
|
89
|
+
|
|
90
|
+
**規則 TD-EXP-004(建議)**——被延期三次以上、期間沒有記錄任何進度的項目,應重新分流為**撤銷**候選。反覆延期是「沒有人打算做這件事」的證據;老實記下這件事,比第四個日期對下一位讀者更有用。
|
|
91
|
+
|
|
92
|
+
#### 無人看管宣告
|
|
93
|
+
|
|
94
|
+
不是每個團隊都有能力跑一支檢查。**沒有自動到期檢查的登記表仍然合規——但前提是它把這件事寫出來。**
|
|
95
|
+
|
|
96
|
+
「無人看管宣告」是寫在登記表內部、可見且帶日期的一段陳述:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
無人看管——沒有任何自動檢查在讀這份登記表的到期項目。
|
|
100
|
+
由 <負責人> 以 <頻率> 人工複查。最後複查日期:<日期>。
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
**規則 TD-EXP-005(必要)**——登記表必須處於下列兩種狀態之一,且必須讓讀者看得到它處於哪一種:
|
|
104
|
+
|
|
105
|
+
1. **已受檢(Checked)**——有一支具名、跑得起來的檢查在讀這份登記表,並在項目超過 Target Resolution Date 時失敗。
|
|
106
|
+
2. **無人看管(Unattended)**——沒有這樣的檢查,但帶有無人看管宣告,且宣告中寫明負責人、複查頻率與最後複查日期。
|
|
107
|
+
|
|
108
|
+
兩種狀態都不處於的登記表即為不合規。這份宣告不是形式:它就是「知道沒有東西在看的讀者」與「以為有東西在看的讀者」之間的全部差別。
|
|
109
|
+
|
|
110
|
+
**規則 TD-EXP-006(必要)**——無人看管宣告裡的「最後複查日期」本身,受該宣告自己所寫的頻率約束。最後複查日期比自己宣告的頻率還舊的宣告,本身就是一個到期項目,三種處置同樣適用於它。
|
|
111
|
+
|
|
112
|
+
> **本標準不提供任何檢查器,這是已知代價——寫在這裡,而不是留給採用者自己撞到。**
|
|
113
|
+
>
|
|
114
|
+
> UDS 定義的是要求,它不提供一支執行該要求的程式。想要**已受檢**狀態的採用者必須自己寫那支檢查,而多數團隊不會寫——那正是上面描述的失敗模式,現在同樣適用於本小節自己。
|
|
115
|
+
>
|
|
116
|
+
> 所以這裡的最低標準**不是**「去建一支檢查器」,而是**「絕不讓一份登記表在無聲中變成無人看管」**。宣告 `無人看管` 只要一段文字,而且完全合規。無人看管**卻不宣告**才是本標準真正禁止的唯一結果,因為只有它會讓讀者對「有沒有東西在看」產生誤解。
|
|
117
|
+
|
|
51
118
|
## 3. 預算分配
|
|
52
119
|
|
|
53
120
|
| 團隊狀態 | 預算 | 說明 |
|