feat(#2845): require provenance for UI-SPEC component inventories (#3745)

* test(#2845): failing-first suite for UI-SPEC inventory provenance

Binds two shared formats before either exists, so the suite is RED against
next: the gsd-ui-checker dimension roster (asserted independently on twelve
surfaces, eight English and four translated) and the provenance-line grammar
the UI-SPEC template emits and Dimension 7 consumes.

Every parity assertion is paired with a synthetic mutation case, so the guard's
failure branch executes rather than only reading a correct tree: limit-1 (a
surface still declaring 6), limit (7), limit+1 (8), a dropped dimension, a
label that drifts on one surface only, a non-contiguous roster, a duplicated
number, and a surface that stops declaring a count at all. A seeded fast-check
property renders the roster under formatting noise (CRLF, padding, interleaved
sections) and asserts the parse round-trips and is strictly sensitive to a
dropped heading.

Assertions are on parsed typed records, never raw substrings.

* docs: normalize design-a-ui-phase how-to to American English

House style for docs/ is American English (CLAUDE.md). This file carried
colour/initialisation/initialise/artefact throughout. Spelling only — no
content change; kept separate from the #2845 feature commit so the
release-notes classifier and the hotfix cherry-pick filter see it for what
it is.

* feat(#2845): require provenance for UI-SPEC component inventories

A UI-SPEC's component inventory was treated downstream as a closed allowlist
while the document recorded nothing about whether the list had been enumerated
from the installed design system or recalled from memory. A recalled inventory
is indistinguishable from an enumerated one, so an executor complying with the
spec builds against a fraction of what the package offers, and every gate stays
green because they assert semantics rather than composition.

The UI-SPEC template gains a Component Inventory slot carrying one of two
provenance lines: the command that enumerated the list, the count it returned,
the resolved package@version and the date; or a Could not enumerate record with
a real reason. gsd-ui-researcher gains an enumeration ladder and must record
the line rather than write the list from recall.

gsd-ui-checker gains Dimension 7. An inventory with no provenance line, a count
with no command, an empty could-not-enumerate reason, or a line still carrying
the template's unfilled placeholders BLOCKs; a partial line, a line placed below
its table, or an honest negative record FLAGs; a complete line passes, and so
does a spec carrying no inventory at all, which keeps every UI-SPEC predating
the dimension validating unchanged. Whatever the verdict, an unsourced inventory
is reported as a non-exhaustive list of known-good components rather than a
closed allowlist, so the executor is never blocked from a component the spec
merely failed to mention. The checker never runs the recorded command.

The dimension count moved on all thirteen surfaces that assert it, across five
languages. Also corrects the claim in the English, Korean and Portuguese how-tos
that this checker applies a scored six-pillar rubric — that rubric belongs to
/gsd-ui-review's retroactive audit.

* chore(#2845): backfill changeset pr number to 3745

---------

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-21 11:59:56 -04:00
committed by GitHub
parent 2b42b28687
commit 4918c62d76
18 changed files with 902 additions and 37 deletions

View File

@@ -253,20 +253,21 @@
**要件:**
- REQ-UI-01: システムは既存のデザインシステムの状態を検出しなければならない(shadcn の components.json、Tailwind 設定、トークン)
- REQ-UI-02: システムは未回答のデザインコントラクトの質問のみを行わなければならない
- REQ-UI-03: システムは6つの次元(コピーライティング、ビジュアル、カラー、タイポグラフィ、スペーシング、レジストリセーフティ)に対してバリデーションしなければならない
- REQ-UI-03: システムは7つの次元(コピーライティング、ビジュアル、カラー、タイポグラフィ、スペーシング、レジストリセーフティ、インベントリプロビナンス)に対してバリデーションしなければならない
- REQ-UI-04: バリデーションが BLOCKED を返した場合、システムはリビジョンループに入らなければならない(最大2回の反復)
- REQ-UI-05: `components.json` のない React/Next.js/Vite プロジェクトに対して、システムは shadcn の初期化を提案しなければならない
- REQ-UI-06: システムはサードパーティの shadcn レジストリに対してレジストリセーフティゲートを適用しなければならない
**生成物:** `{padded_phase}-UI-SPEC.md` — エグゼキューターが参照するデザインコントラクト
**6つのバリデーション次元:**
**7つのバリデーション次元:**
1. **コピーライティング** — CTA ラベル、空状態、エラーメッセージ
2. **ビジュアル** — フォーカルポイント、視覚的階層構造、アイコンのアクセシビリティ
3. **カラー** — アクセントカラーの使用規律、60/30/10 準拠
4. **タイポグラフィ** — フォントサイズ/ウェイトの制約遵守
5. **スペーシング** — グリッド配置、トークンの一貫性
6. **レジストリセーフティ** — サードパーティコンポーネントの検査要件
7. **インベントリプロビナンス** — コンポーネントインベントリがインストール済みのデザインシステムから列挙されたものであり、記憶に頼っていないこと
**shadcn 連携:**
- React/Next.js/Vite プロジェクトで `components.json` が欠落していることを検出

View File

@@ -35,7 +35,7 @@
コマンドは 2 つのステージで実行されます。
1. **`gsd-ui-researcher`** — `CONTEXT.md`、`RESEARCH.md`、`REQUIREMENTS.md` を読み込んで既存の決定事項を確認し、デザインシステムの状態(shadcn の `components.json`、Tailwind 設定、既存トークン)を検出し、スペーシング・カラー・タイポグラフィ・コピーライティング・レジストリ安全性の 5 つの領域で未回答のデザイン問題のみを確認します。
2. **`gsd-ui-checker`** — 生成された `UI-SPEC.md` を 6 つの側面で検証します。問題が発見された場合、指摘された項目のみを対象に研究者が再実行されるリビジョンループが起動します(最大 2 回のイテレーション)。
2. **`gsd-ui-checker`** — 生成された `UI-SPEC.md` を 7 つの側面で検証します。問題が発見された場合、指摘された項目のみを対象に研究者が再実行されるリビジョンループが起動します(最大 2 回のイテレーション)。
**出力:** `.planning/phases/{phase-dir}/` 内の `{padded_phase}-UI-SPEC.md`。