@tyroneross/build-loop 0.36.0 → 0.43.0

package/skills/spec-writing/scripts/check_checklist.py

@@ -9,12 +9,13 @@ and checks whether each required item is answered (not blank, not
 the literal placeholder text, and not omitted entirely).
 
 Exit codes:
-    0 — all required items answered (Items 15 and 17 are conditional on UI files in scope)
+    0 — all required items answered (Items 15 and 17 are conditional on UI files in scope;
+        Item 16 is optional when no high-consequence boundary is identified)
     1 — one or more items missing or unanswered
     2 — verifier error (file not found, parse failure)
 
 Usage:
-    python3 check_checklist.py --plan docs/plans/my-feature.md [--json] [--quiet]
+    python3 check_checklist.py --plan .build-loop/plans/my-feature.md [--json] [--quiet]
 """
 from __future__ import annotations
 
@@ -47,6 +48,11 @@ ITEMS: list[tuple[str, str]] = [
     ("item_15_synthesis_dimensions",   "Item 15 — Synthesis dimensions"),
     ("item_16_risk_reason",            "Item 16 — Risk reason"),
     ("item_17_ui_io_contract",         "Item 17 — UI input/output contract"),
+    ("item_18_dispatch_tier",           "Item 18 — Dispatch tier per work item"),
+    ("item_19_env_var_manifest",        "Item 19 — Env-var manifest"),
+    ("item_20_capability_gap_map",      "Item 20 — Capability gap map"),
+    ("item_21_single_shot_guardrails",  "Item 21 — Single-shot build guardrails"),
+    ("item_22_read_before_edit_map",    "Item 22 — Read-before-edit map"),
 ]
 
 # Values that count as "not answered" — case-insensitive, stripped
@@ -113,7 +119,7 @@ def is_answered(value: str) -> bool:
 
 
 # ---------------------------------------------------------------------------
-# Structural validators for items 9-14
+# Structural validators for higher-order checklist items
 # ---------------------------------------------------------------------------
 
 # ID patterns: U-NN, F-NN, D-NN, S-NN, T-NN, A-NN
@@ -155,6 +161,29 @@ _UI_IO_REQUIRED_TERMS = (
     "state", "modality", "validation", "traceability",
 )
 
+# Items 20-22 — implementation accuracy checks.
+_IMPLEMENTATION_SCOPE_RE = re.compile(
+    r"""
+    (
+      ^##\s+Six-Commit\s+Table\b
+      |\bCommit\s+subject\b
+      |\bFiles\s+owned\b
+      |\bmodifies_api\s*:
+      |\bdispatch_tier\s*:
+    )
+    """,
+    re.IGNORECASE | re.MULTILINE | re.VERBOSE,
+)
+_CAPABILITY_GAP_SECTION_RE = re.compile(
+    r"^##\s+Capability\s+Gap\s+Map\b", re.IGNORECASE | re.MULTILINE)
+_SINGLE_SHOT_GUARDRAILS_SECTION_RE = re.compile(
+    r"^##\s+Single-Shot\s+Build\s+Guardrails\b", re.IGNORECASE | re.MULTILINE)
+_READ_BEFORE_EDIT_SECTION_RE = re.compile(
+    r"^##\s+Read-Before-Edit\s+Map\b", re.IGNORECASE | re.MULTILINE)
+_CAPABILITY_GAP_REQUIRED_TERMS = ("current", "target", "gap", "validation")
+_SINGLE_SHOT_REQUIRED_TERMS = ("guardrail", "prevents", "evidence")
+_READ_BEFORE_EDIT_REQUIRED_TERMS = ("read first", "why", "edit after")
+
 
 def check_item_15_synthesis_dimensions(plan_text: str) -> tuple[str, str | None]:
     """OK if no UI in scope; else require synthesis_dimensions block w/ all keys."""
@@ -194,6 +223,71 @@ def check_item_17_ui_io_contract(plan_text: str) -> tuple[str, str | None]:
     return ("OK", None)
 
 
+def _section_body(section_re: re.Pattern, text: str) -> str | None:
+    """Return the section body after a matched level-2 heading, or None if absent."""
+    m = section_re.search(text)
+    if not m:
+        return None
+    section_start = m.end()
+    next_heading = re.search(r"^##\s+", text[section_start:], re.MULTILINE)
+    return (
+        text[section_start: section_start + next_heading.start()]
+        if next_heading else text[section_start:]
+    )
+
+
+def _accuracy_section_findings(text: str) -> list[dict]:
+    """Warn when implementation plans omit sections that prevent rework."""
+    body_text = CHECKLIST_RE.sub("", text)
+    if not _IMPLEMENTATION_SCOPE_RE.search(body_text):
+        return []
+
+    findings: list[dict] = []
+    section_specs = [
+        (
+            "item_20_capability_gap_map",
+            "Item 20 — Capability gap map",
+            _CAPABILITY_GAP_SECTION_RE,
+            _CAPABILITY_GAP_REQUIRED_TERMS,
+            "Implementation scope detected but no `## Capability Gap Map` section found.",
+        ),
+        (
+            "item_21_single_shot_guardrails",
+            "Item 21 — Single-shot build guardrails",
+            _SINGLE_SHOT_GUARDRAILS_SECTION_RE,
+            _SINGLE_SHOT_REQUIRED_TERMS,
+            "Implementation scope detected but no `## Single-Shot Build Guardrails` section found.",
+        ),
+        (
+            "item_22_read_before_edit_map",
+            "Item 22 — Read-before-edit map",
+            _READ_BEFORE_EDIT_SECTION_RE,
+            _READ_BEFORE_EDIT_REQUIRED_TERMS,
+            "Implementation scope detected but no `## Read-Before-Edit Map` section found.",
+        ),
+    ]
+    for item_id, label, section_re, required_terms, missing_message in section_specs:
+        section = _section_body(section_re, body_text)
+        if section is None:
+            findings.append({
+                "item_id": item_id,
+                "label": label,
+                "status": "warn",
+                "message": missing_message,
+            })
+            continue
+        lower = section.lower()
+        missing_terms = [term for term in required_terms if term not in lower]
+        if missing_terms:
+            findings.append({
+                "item_id": item_id,
+                "label": label,
+                "status": "warn",
+                "message": "Section is present but missing term(s): " + ", ".join(missing_terms),
+            })
+    return findings
+
+
 def _structural_findings(text: str, plan_path: Path) -> list[dict]:
     """
     Run structural checks for higher-order checklist items against the full plan text.
@@ -202,9 +296,10 @@ def _structural_findings(text: str, plan_path: Path) -> list[dict]:
     These supplement — they do not replace — the checklist block checks.
     """
     findings = []
+    body_text = CHECKLIST_RE.sub("", text)  # strip the <!-- checklist --> block
 
     # Item 9: P0 lines must have at least one T- reference
-    p0_lines = [ln for ln in text.splitlines() if _P0_LINE_RE.search(ln)]
+    p0_lines = [ln for ln in body_text.splitlines() if _P0_LINE_RE.search(ln)]
     if p0_lines:
         p0_without_test = [ln for ln in p0_lines if not _T_ID_RE.search(ln)]
         if p0_without_test:
@@ -220,9 +315,9 @@ def _structural_findings(text: str, plan_path: Path) -> list[dict]:
         else:
             # Also verify at least one full trace chain appears (U-, F-, T-)
             has_chain = (
-                bool(_ID_RE.search(text))
-                and bool(re.search(r"\bU-\d+\b", text))
-                and bool(re.search(r"\bF-\d+\b", text))
+                bool(_ID_RE.search(body_text))
+                and bool(re.search(r"\bU-\d+\b", body_text))
+                and bool(re.search(r"\bF-\d+\b", body_text))
             )
             if not has_chain:
                 findings.append({
@@ -236,7 +331,7 @@ def _structural_findings(text: str, plan_path: Path) -> list[dict]:
                 })
 
     # Item 10: ## Spec Object (JSON) section must exist
-    if not _JSON_SPEC_SECTION_RE.search(text):
+    if not _JSON_SPEC_SECTION_RE.search(body_text):
         findings.append({
             "item_id": "item_10_json_spec_object",
             "label": "Item 10 — JSON spec object",
@@ -248,12 +343,15 @@ def _structural_findings(text: str, plan_path: Path) -> list[dict]:
         })
 
     # Item 11: Open Questions entries must carry blocking-test: annotation
-    oq_match = _OPEN_Q_SECTION_RE.search(text)
+    oq_match = _OPEN_Q_SECTION_RE.search(body_text)
     if oq_match:
         # Extract the Open Questions section (up to the next ## heading)
         oq_start = oq_match.end()
-        next_heading = re.search(r"^##\s+", text[oq_start:], re.MULTILINE)
-        oq_body = text[oq_start: oq_start + next_heading.start()] if next_heading else text[oq_start:]
+        next_heading = re.search(r"^##\s+", body_text[oq_start:], re.MULTILINE)
+        oq_body = (
+            body_text[oq_start: oq_start + next_heading.start()]
+            if next_heading else body_text[oq_start:]
+        )
         # Count question lines (non-empty, non-heading lines)
         q_lines = [ln.strip() for ln in oq_body.splitlines()
                    if ln.strip() and not ln.strip().startswith("#")]
@@ -270,8 +368,8 @@ def _structural_findings(text: str, plan_path: Path) -> list[dict]:
             })
 
     # Item 12: Low-reversibility decision mentions must have ADR link
-    low_rev_lines = [ln for ln in text.splitlines() if _LOW_REV_RE.search(ln)]
-    adr_headings_exist = bool(_ADR_HEADING_RE.search(text))
+    low_rev_lines = [ln for ln in body_text.splitlines() if _LOW_REV_RE.search(ln)]
+    adr_headings_exist = bool(_ADR_HEADING_RE.search(body_text))
     if low_rev_lines and not adr_headings_exist:
         findings.append({
             "item_id": "item_12_low_reversibility_adrs",
@@ -284,7 +382,6 @@ def _structural_findings(text: str, plan_path: Path) -> list[dict]:
         })
 
     # Item 13: Analytical lens line must appear in the plan body (outside the checklist block)
-    body_text = CHECKLIST_RE.sub("", text)  # strip the <!-- checklist --> block
     if not _LENS_LINE_RE.search(body_text):
         findings.append({
             "item_id": "item_13_analytical_lens",
@@ -306,7 +403,7 @@ def _structural_findings(text: str, plan_path: Path) -> list[dict]:
             "status": "warn",
             "message": (
                 f"Sibling handoff file '{handoff_path.name}' not found. "
-                "Generate docs/plans/<slug>.handoff.md alongside the plan."
+                "Generate .build-loop/plans/<slug>.handoff.md alongside the plan."
             ),
         })
 
@@ -330,6 +427,8 @@ def _structural_findings(text: str, plan_path: Path) -> list[dict]:
             "message": msg_17,
         })
 
+    findings.extend(_accuracy_section_findings(text))
+
     return findings
 
 

package/skills/ui-design/SKILL.md

@@ -22,8 +22,10 @@ Use this skill when `uiTarget != null` and the work is not copy-only:
 4. Run a Calm Precision core-consideration pass before selecting style: name the principles most relevant to the surface, the perceptual foundation behind each one, and the concrete implication for this build.
 5. Load project-local visual evidence: current screens, screenshots, tokens, components, selected mockups, and existing `.build-loop/app-contract/ui.md`.
 6. Select only the guidance sources needed for the surface from `references/ui-guidance-sources.md`.
-7. Choose the design direction from product fit: user job, workflow frequency, data shape, information density, platform, accessibility risk, error cost, and the Calm Precision core-consideration pass.
-8. Have `design-contract-specialist` write the decision to `.build-loop/app-contract/ui.md`.
+7. Derive colour from the engine, never by hand — load `references/color-engine.md` before writing any hex, generating a palette, or accepting an inherited one (including a mode brief's). Check for the Groundwork colour engine first (`$GROUNDWORK_ROOT` env var, else the checkout path `references/color-engine.md` names) — when it's present, use it as documented there. When it's absent, `references/color-engine.md`'s own "No Groundwork checkout" fallback section is the design route instead of hand-picking hex values: it distills the same rules (one accent, two stops, contrast verified per role) into a checkout-free procedure. Either way, declare in `.build-loop/app-contract/ui.md` which path produced the palette — engine or fallback. A palette is a relationship vector, not a list of colours: contrast is solved per role and verified in both the light and dark twin. One accent, status hues reserved, colour only where it encodes state.
+8. Choose the design direction from product fit: user job, workflow frequency, data shape, information density, platform, accessibility risk, error cost, and the Calm Precision core-consideration pass.
+9. Have `design-contract-specialist` write the decision to `.build-loop/app-contract/ui.md`.
+10. When the work updates, compares, or audits a renderable UI design, invoke headless IBR as the primary visual verifier when installed. Follow `../../references/ibr-ui-verification-policy.md`; record the platform fallback when IBR is unavailable.
 
 ## Design Layers
 
@@ -34,7 +36,7 @@ Think in layers, not competing design systems:
 3. **Calm Precision core considerations** — the baseline rules and perceptual-science foundations that every design direction must satisfy or explicitly except.
 4. **Project surface** — existing tokens, components, brand, screenshots, and selected mockups.
 5. **Structure or style mode** — recent design structures such as Conversational Command Surface, Bento Operating Dashboard, Pipeline Wizard, Outcome Ledger, Pyramid Detail, Glass Workspace, Warm Craft, Data Narrative, native mobile, or AI Artifact Canvas.
-6. **Validation evidence** — `ui-validator`, design-rule scanner, browser/simulator screenshots, and contract traceability.
+6. **Validation evidence** — IBR comparison/scan evidence when installed, then `ui-validator`, design-rule scanner, browser/simulator screenshots, and contract traceability.
 
 Calm Precision is not just one optional theme or reference. It is a core design gate. Every non-trivial UI decision should be checked against the relevant Calm Precision principles before selecting structure, style mode, token treatment, motion, or interaction behavior. A Glass, Warm Craft, Aurora, Data Narrative, or native mobile direction can change surface treatment, density, and mood, but it must not override Calm Precision's hierarchy, accessibility, motion, interaction, and real-data rules unless the app contract records an explicit exception.
 
@@ -66,7 +68,7 @@ Implementers should read the app contract and UI input/output contract, not the
 
 ## Guardrails
 
-- Do not route to IBR unless the user explicitly asks for IBR, Interface Built Right, or an IBR-specific artifact.
+- Route every renderable UI design update, comparison, or audit through the automatic IBR policy in `../../references/ibr-ui-verification-policy.md`. Interactive IBR viewers and persistent sessions remain explicit-only.
 - Do not force recent structures. They are options, not requirements.
 - Do not treat Calm Precision as a citation, theme, or surface style. Use it as the shared baseline and decision gate under the selected mode.
 - Do not load broad vault/research folders into implementation prompts. Select one to three relevant sources and synthesize them.

package/skills/ui-design/references/color-engine.md

@@ -0,0 +1,132 @@
+# Colour: use the engine, don't pick hexes
+
+Short version: **choosing a palette by choosing colours is the wrong move.** Groundwork
+owns a colour engine that derives palettes from a *relationship vector* and verifies every
+role's contrast mathematically. Build-loop routes colour decisions there instead of
+duplicating the theory. This file is the pointer plus the handful of rules that matter
+when you are mid-build and don't want to leave the loop.
+
+Canonical docs (if you have the checkout): `$GROUNDWORK_ROOT/designer/color/README.md`
+Engine: `designer/color/relationships.py` · Elicitation: `designer/decide/color_dimensions.py`
+
+## Checkout detection
+
+The engine lives in a separate Groundwork checkout, not inside build-loop. Resolve it before running anything below, in order:
+
+1. `$GROUNDWORK_ROOT` env var, if set — use it directly.
+2. Else, a sibling checkout next to your other repos (commonly `groundwork` alongside build-loop) — use it only if `designer/color/relationships.py` actually exists under it.
+3. Else, no checkout is available — skip "The 60-second path" below and go straight to "No Groundwork checkout" further down. Do not fall through to hand-picked hex values; that is exactly the mistake this file exists to prevent.
+
+Whichever branch resolves, declare it in `.build-loop/app-contract/ui.md` (`palette_source: engine` or `palette_source: fallback (no groundwork checkout)`).
+
+## The one idea
+
+A palette is a vector of relationships — contrast targets, chroma structure, hue deltas —
+not a list of colours. Fix the relationships, rotate the anchor hue, and you get an
+infinite family of equally valid systems. `preview.py --sweep-hue 12` demonstrates it:
+same vector, twelve hues, all passing.
+
+**So the hue is the least load-bearing decision in the palette.** What carries the design:
+one accent, two stops (light + dark), contrast verified per role, status hues untouched.
+If a build is stuck arguing indigo vs teal, that argument is not the blocker.
+
+## When to reach for it
+
+- Any new product surface that needs a palette.
+- Any time you are about to type a hex into a component, mockup, or token file.
+- Any inherited palette you have not verified (mode briefs, design docs, an existing app).
+
+## The 60-second path
+
+```bash
+GW="$GROUNDWORK_ROOT"   # resolved above — only reached when the checkout was found
+
+# Verify a palette you already have — returns solved replacements, same hue + chroma
+PYTHONPATH=$GW python3 -m designer.color.combos ingest \
+  --name <slug> --surface '#0b0b0f' --text '#f4f4f5' --accent '#818cf8'
+
+# Or generate: both twins from one vector (light 0.985 / dark 0.16)
+PYTHONPATH=$GW python3 -m designer.color.preview --sweep-hue 6 \
+  --params '{"energy":"balanced","contrast_feel":"crisp","accent_intensity":"clear",
+             "harmony":"analogous","anchor_hue":277,"surface_L":0.16}' > /tmp/p.html
+```
+
+Use the returned `surface / on_surface / muted / accent / on_accent` roles verbatim.
+
+## Rules worth memorising
+
+1. **One accent.** Status hues are reserved — success/green, warning/amber, error/red. An
+   accent that collides with one destroys the signal: if the brand accent *is* the success
+   green, "success" stops meaning anything. Check the status set before choosing an anchor.
+2. **Two stops, always.** An accent can clear AA on near-black and fail badly on white.
+   Solve both twins from the same vector; never invert one and assume.
+3. **`clipped: true` is not a choice.** It means sRGB cannot render that chroma, so it will
+   render duller than the brief promises. Lower `energy` or `accent_intensity` instead.
+4. **The accent is the anchor rotated by the harmony delta**, not the anchor. Default
+   split-complementary turns a cool 250° anchor into an orange accent. Want the accent in
+   the anchor family? `harmony: analogous`.
+5. **Colour encodes state, not decoration.** An accent-coloured kicker or eyebrow carries
+   no meaning — drop it. Recorded owner preference, not a style opinion.
+6. **Never claim a preference that wasn't elicited.** If `designer.decide.profile show`
+   is empty, there is no recorded colour taste — say so rather than inferring one.
+7. **Label polarity matches the mode.** `on_accent_prefer` defaults to `auto` → a light
+   label on a dark surface. Left to ratio alone the solver picks a near-black label for a
+   dark-mode accent: it passes 4.5:1 and reads as inverted, because every other foreground
+   on that surface is light. Buying the right polarity may trade fill contrast down to
+   `accent_contrast_floor` (3.0) — legal, since a fill is a non-text component under WCAG
+   1.4.11. The result flags `accent_contrast_relaxed: true`.
+8. **Look at the render, not only the report.** Contrast is a scalar and scores
+   white-on-indigo and black-on-indigo identically, so `all_contrast_targets_met: true` is
+   a floor, not a verdict. Measure every ratio you show with `contrast_hex()` against the
+   hexes actually rendered — never copy a row between options, never round from memory.
+
+## No Groundwork checkout
+
+Reached only when "Checkout detection" above found neither `$GROUNDWORK_ROOT` nor a sibling checkout. Do not hand-pick hex values — apply the same relationship-vector rules manually instead, and declare the fallback in the app contract (`palette_source: fallback (no groundwork checkout)`), not just the resulting hexes:
+
+1. **One accent, status hues reserved.** Same as rule 1 above: pick a single accent hue; never let it collide with success/warning/error.
+2. **Two stops, always.** Same as rule 2 above: solve a light surface and a dark surface from the same accent; don't invert one and assume the other passes.
+3. **Verify contrast per role with a script, not by eye or memory.** Without the engine's `contrast_hex()` you still owe every foreground/background pairing a real number: WCAG relative luminance and contrast ratio, text ≥4.5:1, large text/non-text UI components ≥3:1 (WCAG 1.4.11). Compute it, don't estimate it:
+
+   ```python
+   def _lin(c):
+       c /= 255
+       return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+   def luminance(hex_color):
+       r, g, b = (int(hex_color[i:i + 2], 16) for i in (1, 3, 5))
+       return 0.2126 * _lin(r) + 0.7152 * _lin(g) + 0.0722 * _lin(b)
+
+   def contrast(hex_a, hex_b):
+       l1, l2 = sorted((luminance(hex_a), luminance(hex_b)), reverse=True)
+       return (l1 + 0.05) / (l2 + 0.05)
+   ```
+
+4. **Colour encodes state, not decoration.** Same as rule 5 above — no accent-coloured kickers or eyebrows without a status meaning.
+5. **Never claim an unelicited preference.** If there's no recorded colour taste for this project (no mode brief, no existing tokens), pick one sensible neutral+accent pair, verify it with the script above, and say plainly it's a fallback default, not a recorded preference.
+
+This produces a *valid* palette, not an *equivalent* one — it skips the OKLCH relationship-vector math, the sweep-hue family, and taste-profile accumulation the real engine gives you. Record that gap in the app contract rather than treating the fallback as parity with the engine.
+
+## Feeding what you learn back
+
+Palette decisions made during a build should not evaporate when the run ends:
+
+```bash
+# Record an accepted system (or a new relationship pattern you invented)
+PYTHONPATH=$GW python3 -m designer.color.combos add --name <slug> \
+  --params '<vector>' --intent "<where it fits>" --source mine
+
+# Fold elicited dimensions into the cross-project taste profile
+PYTHONPATH=$GW python3 -m designer.decide.profile record-dims '{"contrast_feel":"crisp"}'
+```
+
+This is the mechanism that lets the system accumulate favourites and new vector
+arrangements over time. Skipping it is why the profile stays empty and every project
+re-asks settled questions.
+
+## Known trap
+
+The flow that most often breaks the rule is **mockup authoring**, because typing a hex
+into HTML feels like design work. It isn't — it's guessing with extra steps, and a mode
+brief's hexes were authored for *that brief's* context, not the surface you're building.
+Validate or regenerate before use.

package/skills/ui-design/references/design-preferences-from-owned-apps.md

@@ -7,7 +7,7 @@
 > Sourced from `.build-loop/design-evidence/*.md` (8 apps scanned 2026-05-26). Every claim in this file traces to a specific evidence file. The evidence files are the ground truth — when this doc and an evidence file disagree, the evidence file wins.
 >
 > **Primary preferred references** (per intent.md): Sample Voice iOS, Sample Timer (iPad primary), Sample Reader, Sample Product App.
-> **Secondary / directional** (note what works AND what user dislikes): Secrets Vault macOS, Sample Decision App, Sample Offline iOS, Sample Onboarding App.
+> **Secondary / directional** (note what works AND what user dislikes): Sample Secrets App (macOS), Sample Decision App, Sample Offline iOS, Sample Onboarding App.
 
 ---
 
@@ -16,7 +16,7 @@
 **Universal non-negotiable:** *"Visual hierarchy is one-glance recoverable"* (alt doc §2.12) + Calm Precision's *"Title (14-16px bold) → Description (12-14px) → Metadata (11-12px muted)"*.
 
 **What works (primary apps):**
-- **Secrets Vault** — verbatim CP 6.4.1 implementation in `VaultTypography.swift` (evidence: `secrets-vault-macos.md`). Token comment in source code: *"L1: Title 15px medium high contrast → L2: Description 13px regular medium contrast → L3: Metadata 11px regular low contrast."* This is the textbook reference.
+- **Sample Secrets App** — verbatim CP 6.4.1 implementation in a dedicated typography token file (evidence: `sample-secrets-app.md`). Three named tiers (title/description/metadata) map directly to size + contrast rung. This is the textbook reference.
 - **Sample Timer App** — `TextRole` enum (`Theme.swift:689-721` per `sample-timer.md`) ladders seven named roles (display/title/headline/subheadline/body/caption/micro) with explicit baseSize + defaultWeight per rung. Tokens cite role purpose: *"display: 30pt — single largest element on a screen."*
 - **Sample Voice App** — nine named typography tokens (`Theme.swift:31-35,70-75` per `sample-voice-ios.md`) including `fontTabular` (10pt mono-equivalent for numerics) — a use-case that single-purpose token sets miss.
 
@@ -34,7 +34,7 @@
 **What works (primary apps):**
 - **Sample Product App** — strictest single-accent enforcement in inventory: `--primary === --accent === --ring === #f0b65e` (`index.css:18,22,26` per `sample-product.md`). The entire palette is warm-monochromatic; the only "second color" is `--success: #7bc67e` (muted sage) and `--destructive: #e06356` (warm red-orange, not pure red — palette discipline holds even on error).
 - **Sample Reader** — explicit semantic separation: `--color-error-bg` and `--color-error-border` exist for tinted alert containers, but they are tokens distinct from `--status-error` (the foreground text color). Container surfaces are gated to reading flow where text-color-only would underread (`sample-reader.md` cites the divergence with rationale).
-- **Secrets Vault** — three-tier text contrast (`textPrimary / textSecondary / textMuted` = stone-900 / stone-600 / stone-400 in light; stone-100 / stone-300 / stone-450 in dark, per `secrets-vault-macos.md`). Each tier maps directly to L1/L2/L3 of the typography ladder — text size + text contrast move together.
+- **Sample Secrets App** — three-tier text contrast (primary/secondary/muted = stone-900 / stone-600 / stone-400 in light; stone-100 / stone-300 / stone-450 in dark, per `sample-secrets-app.md`). Each tier maps directly to L1/L2/L3 of the typography ladder — text size + text contrast move together.
 
 **Anti-pattern (secondary apps):**
 - **Sample Decision App theme-toggle pattern** — three switchable themes (F default, A "Case File," B "Conversation") via `[data-theme="A"|"B"]` on `<html>` (evidence: `sample-decision-app.md`). Each theme owns the same 6 token names but different brand colors. *Works for*: keeping semantic meaning constant across visual presentation. *Fails for*: brand identity — a brand that can become blue or terracotta or red is brand-fungible. Likely user-dislike: the existence of the toggle dilutes the canonical voice (Theme F).
@@ -86,7 +86,7 @@
 **What works (primary apps):**
 - **Sample Decision App** — `@media (prefers-reduced-motion: reduce)` overrides all animations to 0.01ms at the globals level (`app/globals.css:65-71` per `sample-decision-app.md`). Single CSS rule covers the whole app.
 - **Sample Voice App** — `@Environment(\.accessibilityReduceMotion)` honored on HomeView; first-time onboarding animation gated to once per AppStorage flag (`HomeView.swift:16,47` per `sample-voice-ios.md`).
-- **Secrets Vault** — stagger animation capped at 400ms total (`60ms × N items, max 400ms`) — prevents the long-list "wave" anti-pattern (per project CLAUDE.md cited in `secrets-vault-macos.md`).
+- **Sample Secrets App** — stagger animation capped at 400ms total (`60ms × N items, max 400ms`) — prevents the long-list "wave" anti-pattern (per its project guidance, cited in `sample-secrets-app.md`).
 - **Sample Onboarding App** — StatusBanner's `phase label itself stays visible briefly after a stage transition so the user sees the most recent phase without flicker` (verbatim from `StatusBanner.swift` per `sample-onboarding-app.md`). Anti-flicker is a documented design decision, encoded in code comments.
 
 **Preference recorded:** **`prefers-reduced-motion` / `accessibilityReduceMotion` must be respected by default, not opt-in. Stagger animations have a total-time cap, not just a per-item interval. Anti-flicker behavior is a first-class design concern, not an afterthought.**
@@ -98,7 +98,7 @@
 **Universal non-negotiable:** *"When something fails, explain what happened, preserve context, give a next step"* (alt doc §1.5 Recover) + *"Resilient to imperfect input"* (alt doc §2.9).
 
 **What works (primary apps):**
-- **Secrets Vault** — explicit three-part error pattern named in project CLAUDE.md (cited `secrets-vault-macos.md`): *"Errors: what → why → fix pattern."* Plus voice rule: *"Verb+Object labels, contextual loading ('Deriving encryption key…')"* — loading messages name the actual operation.
+- **Sample Secrets App** — explicit three-part error pattern named in its project guidance (cited `sample-secrets-app.md`): what happened, why, and how to fix it. Loading states use verb+object labels naming the actual operation in progress (e.g. a key-derivation step), not a generic "Loading…".
 - **Sample Offline iOS** — *"Errors surface inline (red footnote) without removing cached rows — offline still shows the last good list"* (`CampsListView.swift` code comment per `sample-offline-ios.md`). On error, the cache is preserved — graceful degradation in action.
 - **Sample Voice App** — `Haptics.impact(.light)` paired with state change on every CTA tap (`HomeView.swift:81` per `sample-voice-ios.md`) — action feedback via haptic + visible state, not just one or the other.
 
@@ -122,12 +122,12 @@
 
 A new app in this ecosystem should, in priority order:
 
-1. **Token files first** — `Theme/Colors`, `Theme/Typography` (or `index.css`-equivalent for web) before the first view is written. Use Sample Voice App / Sample Timer App / Secrets Vault as templates.
+1. **Token files first** — `Theme/Colors`, `Theme/Typography` (or `index.css`-equivalent for web) before the first view is written. Use Sample Voice App / Sample Timer App / Sample Secrets App as templates.
 2. **One accent. Single. Don't theme-toggle.** Sample Product App is the strictest example.
-3. **Three-line text hierarchy** baked into the typography enum. Secrets Vault's `VaultTypography.title/.description/.metadata` is the textbook.
+3. **Three-line text hierarchy** baked into the typography enum. Sample Secrets App's title/description/metadata tier naming is the textbook.
 4. **Touch targets at the component layer.** Sample Product App's `.btn-primary` is the example.
 5. **`prefers-reduced-motion` / `accessibilityReduceMotion` from day one.** The sample decision app's single-CSS-rule approach is the cheapest implementation.
-6. **Errors are calm, informative, non-destructive.** The sample offline app's offline-preserves-cache + Secrets Vault's what→why→fix pattern combine into a single rule.
+6. **Errors are calm, informative, non-destructive.** The sample offline app's offline-preserves-cache + Sample Secrets App's what→why→fix pattern combine into a single rule.
 7. **Multi-form-factor via viewport-scale tokens, not forked themes.** Sample Timer App's `\.viewportScale` is the reference; the multi-pattern framework draft (`design-patterns-multi.md`) is where this becomes formal if/when prototyped.
 
 When deviating: name the deviation in the token file's comments, the way Sample Timer App flags off-grid spacing and Sample Reader flags tinted error containers. The discipline is the comment.

package/skills/ui-design/references/ui-guidance-sources.md

@@ -192,7 +192,7 @@ High-signal sources:
 - `interface-built-right/templates/patterns/`
 - `interface-built-right/src/ui-guidance/`
 
-Use only when the user explicitly asks for IBR or when a selected IBR artifact is passed to the specialist as evidence. Do not make IBR the default build route.
+Use IBR automatically as the verifier for renderable UI design updates, comparisons, and audits under `../../../references/ibr-ui-verification-policy.md`. IBR does not own design direction; pass its evidence to the specialist and keep viewer/dashboard surfaces explicit-only.
 
 ## Mockup Gallery
 

package/skills/ui-design/references/universal-design-principles.alt.md

@@ -39,7 +39,7 @@ These ten apply to every artifact produced or reviewed.
     - *Cited precedent:* Sample Product App uses a single accent (`--primary === --accent === --ring === #f0b65e`) and warm-monochromatic palette discipline — strictest single-accent in inventory. See `sample-product.md`. Counter-pattern: the sample decision app's three-theme toggle (`[data-theme="A"|"B"]`) preserves semantic meaning across visual presentation but dilutes brand voice — see `sample-decision-app.md`.
 11. **Content fits its container, or the container fits the content.** Clipping, truncation without recovery, awkward wraps, and overflow are design failures. Decide which side flexes (fixed container with overflow recovery, or fluid container that grows). Critical content never shrinks below its reading threshold to fit.
 12. **Visual hierarchy is one-glance recoverable.** A user reading at speed knows what is most important, what is next, what is supporting — from position, size, weight, contrast, and spacing alone. If color is removed, the hierarchy still holds.
-    - *Cited precedent:* Secrets Vault's `VaultTypography.title/.description/.metadata` (15/13/11pt) maps role names directly to L1/L2/L3 — see `.build-loop/design-evidence/secrets-vault-macos.md`. Anti-pattern: the sample onboarding app's inline pixel sizes across one view (12/13/14/15/16/18/20/34) — see `sample-onboarding-app.md`.
+    - *Cited precedent:* Sample Secrets App's title/description/metadata tier naming (15/13/11pt) maps role names directly to L1/L2/L3 — see `.build-loop/design-evidence/sample-secrets-app.md`. Anti-pattern: the sample onboarding app's inline pixel sizes across one view (12/13/14/15/16/18/20/34) — see `sample-onboarding-app.md`.
 13. **Fit form to information.** Prose, bullets, table, chart, diagram, checklist, form, callout, or slide rhythm chosen for the reading task — not the template.
 14. **Native primitives over visual fakes.** Use the medium's semantic structures: UI components, slide placeholders, document styles, table geometry, chart objects, alt text, headings, source notes. Don't fake them with glyphs, manual spacing, or screenshots.
 15. **Verify the rendered artifact.** Inspect the real output surface before declaring done. Screenshots for UI; rendered pages for docs and decks; live render for charts.
@@ -48,7 +48,7 @@ These ten apply to every artifact produced or reviewed.
 
 - **Interaction targets match input precision.** Touch needs more area than mouse; mouse more than keyboard focus; watch, remote, and voice each have their own envelope. The principle: a target the user can hit on the first try, comfortably, with the device in hand. Specific minimums live in platform skills (`accessibility-review`, platform HIGs).
 - **Motion serves comprehension, not decoration.** Animate when it explains origin, destination, or state change. Duration short enough not to delay, long enough to be perceived. Respects reduced-motion preferences.
-  - *Cited precedent:* The sample decision app's single CSS rule overrides all animations to 0.01ms under `prefers-reduced-motion` (`app/globals.css:65-71`) — see `sample-decision-app.md`. Secrets Vault caps stagger at 400ms total (60ms × N items) — see `secrets-vault-macos.md`. The sample onboarding app documents anti-flicker behavior in code comments — see `sample-onboarding-app.md`.
+  - *Cited precedent:* The sample decision app's single CSS rule overrides all animations to 0.01ms under `prefers-reduced-motion` (`app/globals.css:65-71`) — see `sample-decision-app.md`. Sample Secrets App caps stagger at 400ms total (60ms × N items) — see `sample-secrets-app.md`. The sample onboarding app documents anti-flicker behavior in code comments — see `sample-onboarding-app.md`.
 - **Multi-form-factor via viewport-scale tokens.** When one codebase ships across iPhone, iPad, Mac, and Watch, scale a single hierarchy by a runtime env var rather than forking themes per platform.
   - *Cited precedent:* Sample Timer App's `\.viewportScale` env (1.0× iPhone → 1.5× iPad → live-window-resize Mac → separate watch palette + AOD dim variants); see `sample-timer.md`. Formalized as Pattern 1 / Pattern 4 in the multi-pattern framework draft at `skills/ui-design/references/design-patterns-multi.md`.
 

package/plugin-artifacts/codex/.codex-plugin/plugin.json

@@ -1,41 +0,0 @@
-{
-  "name": "build-loop",
-  "version": "0.36.0",
-  "description": "Multi-phase build orchestration with native debugging: assess, plan, execute, review, iterate. Plan-verify gate on Phase 2. Optional UI design gates. Native debug-loop, debugging-memory, and logging-tracer skills provide root-cause investigation without a bundled MCP server. Orchestrator owns when-to-fire; bundled skills own procedural detail; bridges are optional escalation hops to supporting plugins for extended capability.",
-  "author": {
-    "name": "Tyrone Ross",
-    "url": "https://github.com/tyroneross"
-  },
-  "homepage": "https://github.com/tyroneross/build-loop#readme",
-  "repository": "https://github.com/tyroneross/build-loop",
-  "license": "Apache-2.0",
-  "keywords": [
-    "development",
-    "orchestration",
-    "evaluation",
-    "iteration",
-    "build",
-    "tdd",
-    "fact-checking",
-    "code-quality",
-    "ui-validation",
-    "accessibility",
-    "design-rules",
-    "debug-loop",
-    "debugging",
-    "causal-tree",
-    "incident-memory"
-  ],
-  "skills": "./skills",
-  "interface": {
-    "displayName": "Build Loop",
-    "shortDescription": "Multi-phase build orchestration with review gates, UI validation, debugging, and a Codex subagent adapter.",
-    "longDescription": "Multi-phase build orchestration with native debugging: assess, plan, execute, review, iterate. Plan-verify gate on Phase 2. Optional UI design gates. Native debug-loop, debugging-memory, and logging-tracer skills provide root-cause investigation without a bundled MCP server. Orchestrator owns when-to-fire; bundled skills own procedural detail; bridges are optional escalation hops to supporting plugins for extended capability.",
-    "developerName": "Ross Labs",
-    "category": "Coding",
-    "capabilities": [
-      "Read",
-      "Write"
-    ]
-  }
-}