arkaos 4.12.0 → 4.13.1

package/core/workflow/frontend_gate.py

@@ -3,17 +3,28 @@
 Constitution: ``excellence-mandate`` (NON-NEGOTIABLE, Excellence Reform
 2026-07-05). UI work must load the frontend design skills and judge
 against a named benchmark BEFORE code is written. This gate makes that
-duty mechanical: a Write/Edit/MultiEdit touching a UI file requires an
-``[arka:design] <skills/benchmark>`` marker in the recent assistant
-messages — the same ceremony contract as ``[arka:routing]``
-(flow_enforcer) and ``[arka:dispatch]`` (specialist_enforcer).
+duty mechanical: a Write/Edit/MultiEdit touching a UI file requires the
+STRUCTURED design marker in the recent assistant messages:
+
+    [arka:design] benchmark=<Company> skills=<comma,list> tokens=<path|none>
+
+(the same ceremony contract as ``[arka:routing]`` / ``[arka:dispatch]``,
+upgraded in PR-D2 from the bare ``[arka:design] <anything>`` form — the
+bare form is now a LEGACY marker: tolerated in warn mode with a nudge,
+counted separately in telemetry, treated as missing in hard mode).
 
 Modes via ``hooks.frontendGate`` in ``~/.arkaos/config.json``:
 
     absent / "warn"   → nudge on stderr, allow (rollout default)
-    true / "hard"     → deny UI edits without the marker
+    true / "hard"     → deny UI edits without the structured marker
     false / "off"     → gate disabled
 
+Scope: component/stylesheet suffixes (now including ``.html``), plus a
+WARN-only content heuristic for ``.ts/.js`` files that visibly carry UI
+(className=/styled/@apply/tailwind/cva) — heuristic hits never deny,
+even in hard mode, and carry their own ``ui_scope`` so the telemetry can
+exclude them from the hard-flip decision if they prove FP-heavy.
+
 Bypasses: ``[arka:trivial] <reason>`` marker (same contract as the
 evidence flow — single-file edits under 10 lines) and
 ``ARKA_BYPASS_DESIGN=1`` env (logged for accountability).
@@ -40,18 +51,35 @@ TELEMETRY_PATH = Path.home() / ".arkaos" / "telemetry" / "frontend-gate.jsonl"
 
 ASSISTANT_WINDOW = 20
 
-DESIGN_RE = re.compile(r"\[arka:design\]\s*\S+", re.IGNORECASE)
+# Any [arka:design] marker line; classification into structured vs legacy
+# happens on the tail (order-insensitive key scan, see _classify_marker).
+DESIGN_LINE_RE = re.compile(r"\[arka:design\]([^\n]*)", re.IGNORECASE)
+_BENCHMARK_KEY_RE = re.compile(r"\bbenchmark=\S+", re.IGNORECASE)
+_SKILLS_KEY_RE = re.compile(r"\bskills=\S+", re.IGNORECASE)
+
+MARKER_TEMPLATE = (
+    "[arka:design] benchmark=<Company> skills=<comma,list> tokens=<path|none>"
+)
 
 _GATED_TOOLS = frozenset({"Write", "Edit", "MultiEdit"})
 
-# Component + stylesheet extensions. Plain .ts/.js are excluded: they are
-# ambiguous (stores, utils, configs) and would flood the gate with false
-# positives — the component file is where the visual decision lands.
+# Component + stylesheet extensions. Plain .ts/.js stay out of the suffix
+# set (stores, utils, configs would flood the gate) — they are covered by
+# the WARN-only content heuristic below when they visibly carry UI.
 UI_SUFFIXES = frozenset({
     ".vue", ".tsx", ".jsx", ".svelte", ".astro",
     ".css", ".scss", ".sass", ".less",
+    ".html", ".htm",
 })
 
+_HEURISTIC_SUFFIXES = frozenset({".ts", ".js", ".mjs", ".cjs"})
+_UI_CONTENT_RE = re.compile(
+    r"className=|styled\.|styled\(|@apply\b|\btailwind\b|cva\("
+)
+_UI_FILENAME_RE = re.compile(
+    r"(?:^|/)tailwind\.config\.[cm]?[tj]s$|\.styles?\.[tj]s$|(?:^|/)theme\.[tj]s$"
+)
+
 
 @dataclass
 class Decision:
@@ -62,9 +90,19 @@ class Decision:
     mode: str = "warn"
     target_file: str = ""
     marker_found: str | None = None
+    marker_kind: str = "none"   # structured | legacy | trivial | none
+    ui_scope: str = "suffix"    # suffix | heuristic
 
     def to_stderr_message(self) -> str:
-        if self.reason not in ("no-design-marker",):
+        if self.reason == "legacy-marker":
+            head = "[arka:suggest]" if self.allow else "[ARKA:DESIGN]"
+            return (
+                f"{head} Legacy design marker found ({self.marker_found}). "
+                f"The structured form is now required for hard-mode passage: "
+                f"`{MARKER_TEMPLATE}` — name the benchmark company and the "
+                f"skills actually loaded (or skills=degraded:<missing>)."
+            )
+        if self.reason != "no-design-marker":
             return ""
         head = "[arka:suggest]" if self.allow else "[ARKA:DESIGN]"
         verb = "should" if self.allow else "MUST"
@@ -74,7 +112,7 @@ class Decision:
             f"(frontend-design, ui-ux-pro-max, project design system) at "
             f"maximum effort and judge against a named benchmark FIRST "
             f"(constitution `excellence-mandate`). Emit "
-            f"`[arka:design] <skills> benchmark=<name>` before UI edits, "
+            f"`{MARKER_TEMPLATE}` before UI edits, "
             f"or `[arka:trivial] <reason>` for sub-10-line fixes."
         )
 
@@ -100,13 +138,52 @@ def is_ui_file(file_path: str) -> bool:
     return Path(file_path).suffix.lower() in UI_SUFFIXES
 
 
-def _scan(messages: list[str]) -> str | None:
-    """Return the matched evidence marker, or None."""
+def _edit_payloads(tool_name: str, tool_input: dict) -> list[str]:
+    """The text this tool call is about to write, per tool shape."""
+    if tool_name == "Write":
+        return [str(tool_input.get("content", ""))]
+    if tool_name == "Edit":
+        return [str(tool_input.get("new_string", ""))]
+    if tool_name == "MultiEdit":
+        edits = tool_input.get("edits") or []
+        return [str(e.get("new_string", "")) for e in edits if isinstance(e, dict)]
+    return []
+
+
+def is_heuristic_ui_file(
+    file_path: str, tool_name: str, tool_input: dict
+) -> bool:
+    """WARN-only UI detection for .ts/.js: filename or visible UI content."""
+    path = Path(file_path)
+    if path.suffix.lower() not in _HEURISTIC_SUFFIXES:
+        return False
+    if _UI_FILENAME_RE.search(file_path.replace("\\", "/")):
+        return True
+    return any(
+        _UI_CONTENT_RE.search(payload)
+        for payload in _edit_payloads(tool_name, tool_input)
+    )
+
+
+def _classify_marker(messages: list[str]) -> tuple[str | None, str]:
+    """Return (matched_marker, kind) — kind: structured|legacy|trivial|none.
+
+    A structured marker anywhere in the window wins over legacy ones.
+    """
+    legacy: str | None = None
     for message in messages:
-        match = DESIGN_RE.search(message) or TRIVIAL_RE.search(message)
-        if match:
-            return match.group(0)
-    return None
+        for match in DESIGN_LINE_RE.finditer(message):
+            tail = match.group(1)
+            if _BENCHMARK_KEY_RE.search(tail) and _SKILLS_KEY_RE.search(tail):
+                return match.group(0).strip(), "structured"
+            if tail.strip() and legacy is None:
+                legacy = match.group(0).strip()
+        trivial = TRIVIAL_RE.search(message)
+        if trivial:
+            return trivial.group(0), "trivial"
+    if legacy is not None:
+        return legacy, "legacy"
+    return None, "none"
 
 
 def evaluate(
@@ -119,25 +196,41 @@ def evaluate(
 ) -> Decision:
     """Evaluate one tool call against the frontend excellence gate."""
     file_path = str(tool_input.get("file_path", ""))
-    if tool_name not in _GATED_TOOLS or not is_ui_file(file_path):
+    if tool_name not in _GATED_TOOLS:
+        return Decision(allow=True, reason="not-ui-scope", target_file=file_path)
+    if is_ui_file(file_path):
+        ui_scope = "suffix"
+    elif is_heuristic_ui_file(file_path, tool_name, tool_input):
+        ui_scope = "heuristic"
+    else:
         return Decision(allow=True, reason="not-ui-scope", target_file=file_path)
     mode = _mode()
     if mode == "off":
         return Decision(allow=True, reason="flag-off", mode=mode,
-                        target_file=file_path)
+                        target_file=file_path, ui_scope=ui_scope)
     if os.environ.get("ARKA_BYPASS_DESIGN") == "1":
         return Decision(allow=True, reason="env-bypass", mode=mode,
-                        target_file=file_path)
+                        target_file=file_path, ui_scope=ui_scope)
     if messages is None:
         messages = _load_last_assistant_messages(
             transcript_path, ASSISTANT_WINDOW
         )
-    marker = _scan(messages)
-    if marker is not None:
+    marker, kind = _classify_marker(messages)
+    if kind in ("structured", "trivial"):
         return Decision(allow=True, reason="design-evidence", mode=mode,
-                        target_file=file_path, marker_found=marker)
-    return Decision(allow=(mode != "hard"), reason="no-design-marker",
-                    mode=mode, target_file=file_path)
+                        target_file=file_path, marker_found=marker,
+                        marker_kind=kind, ui_scope=ui_scope)
+    # Heuristic scope is WARN-only by design: it never denies, even in
+    # hard mode — its telemetry (ui_scope=heuristic) informs whether it
+    # ever graduates to denying scope.
+    deniable = mode == "hard" and ui_scope == "suffix"
+    if kind == "legacy":
+        return Decision(allow=not deniable, reason="legacy-marker", mode=mode,
+                        target_file=file_path, marker_found=marker,
+                        marker_kind=kind, ui_scope=ui_scope)
+    return Decision(allow=not deniable, reason="no-design-marker",
+                    mode=mode, target_file=file_path, marker_kind=kind,
+                    ui_scope=ui_scope)
 
 
 def record_telemetry(session_id: str, tool: str, decision: Decision) -> None:

package/core/workflow/frontend_gate_telemetry.py

@@ -0,0 +1,129 @@
+"""Frontend-gate telemetry summarizer (Excellence Reform PR-D2).
+
+Reads ``~/.arkaos/telemetry/frontend-gate.jsonl`` (the JSONL stream the
+PreToolUse frontend gate appends on every gated decision) and produces
+the evidence artifact for the WARN→hard flip decision: counts by
+reason / marker_kind / mode / ui_scope, plus the would-have-denied rate
+(suffix-scope events that hard mode would deny today).
+
+Mirrors ``core.governance.specialist_telemetry`` so periods,
+malformed-line tolerance, and zero-division safety behave the same way
+across telemetry surfaces. Read-only.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+DEFAULT_PATH: Path = (
+    Path.home() / ".arkaos" / "telemetry" / "frontend-gate.jsonl"
+)
+_VALID_PERIODS: frozenset[str] = frozenset({"today", "week", "month", "all"})
+
+# Reasons hard mode denies on suffix scope — the flip's FP surface.
+_WOULD_DENY_REASONS = frozenset({"no-design-marker", "legacy-marker"})
+
+
+@dataclass(frozen=True)
+class FrontendGateSummary:
+    """Aggregated frontend-gate telemetry over a time slice."""
+
+    period: str
+    total_events: int
+    by_reason: list[tuple[str, int]] = field(default_factory=list)
+    by_marker_kind: list[tuple[str, int]] = field(default_factory=list)
+    by_mode: list[tuple[str, int]] = field(default_factory=list)
+    by_ui_scope: list[tuple[str, int]] = field(default_factory=list)
+    would_deny_events: int = 0
+    would_deny_rate: float = 0.0
+    corrupt_line_count: int = 0
+
+
+def summarise(period: str, *, path: Path | None = None) -> FrontendGateSummary:
+    if period not in _VALID_PERIODS:
+        raise ValueError(f"invalid period: {period!r}")
+    src = path or DEFAULT_PATH
+    cutoff = _period_cutoff(period)
+    entries, corrupt = _read_jsonl(src, cutoff)
+    return _build_summary(period, entries, corrupt)
+
+
+def _period_cutoff(period: str, now: datetime | None = None) -> datetime | None:
+    ref = now or datetime.now(timezone.utc)
+    if period == "today":
+        return ref.replace(hour=0, minute=0, second=0, microsecond=0)
+    if period == "week":
+        return ref - timedelta(days=7)
+    if period == "month":
+        return ref - timedelta(days=30)
+    return None
+
+
+def _read_jsonl(
+    src: Path, cutoff: datetime | None
+) -> tuple[list[dict[str, Any]], int]:
+    if not src.exists():
+        return [], 0
+    entries: list[dict[str, Any]] = []
+    corrupt = 0
+    try:
+        with src.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    corrupt += 1
+                    continue
+                if cutoff is not None:
+                    ts_raw = entry.get("ts", "")
+                    try:
+                        ts = datetime.fromisoformat(ts_raw)
+                    except (TypeError, ValueError):
+                        corrupt += 1
+                        continue
+                    if ts < cutoff:
+                        continue
+                entries.append(entry)
+    except OSError:
+        return entries, corrupt
+    return entries, corrupt
+
+
+def _build_summary(
+    period: str, entries: list[dict[str, Any]], corrupt: int
+) -> FrontendGateSummary:
+    # Only gated UI events matter for the flip; not-ui-scope is noise.
+    gated = [e for e in entries if e.get("reason") != "not-ui-scope"]
+    total = len(gated)
+    reason_counter: Counter[str] = Counter()
+    kind_counter: Counter[str] = Counter()
+    mode_counter: Counter[str] = Counter()
+    scope_counter: Counter[str] = Counter()
+    would_deny = 0
+    for e in gated:
+        reason = str(e.get("reason", "unknown"))
+        reason_counter[reason] += 1
+        kind_counter[str(e.get("marker_kind", "unknown"))] += 1
+        mode_counter[str(e.get("mode", "unknown"))] += 1
+        scope = str(e.get("ui_scope", "suffix"))
+        scope_counter[scope] += 1
+        if reason in _WOULD_DENY_REASONS and scope == "suffix":
+            would_deny += 1
+    return FrontendGateSummary(
+        period=period,
+        total_events=total,
+        by_reason=reason_counter.most_common(),
+        by_marker_kind=kind_counter.most_common(),
+        by_mode=mode_counter.most_common(),
+        by_ui_scope=scope_counter.most_common(),
+        would_deny_events=would_deny,
+        would_deny_rate=(would_deny / total) if total else 0.0,
+        corrupt_line_count=corrupt,
+    )

package/core/workflow/frontend_gate_telemetry_cli.py

@@ -0,0 +1,53 @@
+"""CLI front-end for frontend-gate telemetry (WARN→hard flip evidence).
+
+Usage:
+    python -m core.workflow.frontend_gate_telemetry_cli today
+    python -m core.workflow.frontend_gate_telemetry_cli week
+    python -m core.workflow.frontend_gate_telemetry_cli month
+    python -m core.workflow.frontend_gate_telemetry_cli all
+"""
+
+from __future__ import annotations
+
+import sys
+
+from core.workflow.frontend_gate_telemetry import summarise
+
+
+def _format_human(summary) -> str:
+    pct = f"{summary.would_deny_rate * 100:.1f}%"
+    lines = [
+        f"Frontend Gate Telemetry — {summary.period}",
+        f"  Gated UI events:   {summary.total_events}",
+        f"  Would-have-denied: {summary.would_deny_events} ({pct}) "
+        f"[suffix scope, hard-flip evidence]",
+    ]
+    for label, pairs in (
+        ("By reason", summary.by_reason),
+        ("By marker kind", summary.by_marker_kind),
+        ("By mode", summary.by_mode),
+        ("By UI scope", summary.by_ui_scope),
+    ):
+        if pairs:
+            lines.append(f"  {label}:")
+            for key, count in pairs:
+                lines.append(f"    - {key}: {count}")
+    if summary.corrupt_line_count:
+        lines.append(f"  Corrupt lines:     {summary.corrupt_line_count}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = argv if argv is not None else sys.argv[1:]
+    period = args[0] if args else "today"
+    try:
+        summary = summarise(period)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(_format_human(summary))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/departments/brand/agents/ux-designer.yaml

@@ -3,7 +3,7 @@ name: Sofia D.
 role: UX/UI Designer
 department: brand
 tier: 2
-model: sonnet
+model: opus
 
 behavioral_dna:
   disc:

package/departments/brand/agents/visual-designer.yaml

@@ -3,7 +3,7 @@ name: Isabel
 role: Visual Designer
 department: brand
 tier: 2
-model: sonnet
+model: opus
 
 behavioral_dna:
   disc:

package/departments/brand/references/uiux-knowledge-and-tools.md

@@ -134,3 +134,76 @@ write material findings back to `[[Area 02 - Design]]`:
 - Microinteractions (trigger→rules→feedback→loops/modes)
 - Color theory & typography science (OKLCH, harmony, modular scale)
 - Gestalt & visual hierarchy (F/Z scanning, proximity, contrast)
+
+---
+
+## 8. Anti-Default Doctrine (NON-NEGOTIABLE — excellence-mandate)
+
+AI-generated design clusters around three default looks. Producing any of
+them WITHOUT a brief that explicitly asks for it is a constitution
+violation (`excellence-mandate`: "no default-looking output"):
+
+1. **Cream + serif + terracotta** — warm cream background (≈ `#F4F1EA`),
+   high-contrast serif display, terracotta accent.
+2. **Dark + acid accent** — near-black background with a single bright
+   acid-green or vermilion accent.
+3. **Broadsheet** — hairline rules, zero border-radius, dense
+   newspaper-like columns.
+
+These are defaults, not choices. Where the brief pins a direction, the
+brief wins — including when it asks for one of these. Where an axis is
+free, never spend it on a default.
+
+**Token-plan-then-critique loop** (before writing any code or asset):
+
+- **Color**: palette as 4–6 NAMED hex values (name = role, not "blue").
+- **Type**: faces for 2+ roles — characterful display used with restraint,
+  complementary body, utility for captions/data when needed.
+- **Layout**: one-sentence concept + ASCII wireframe to compare options.
+- **Signature**: the ONE element this design will be remembered by.
+  Spend your boldness there; keep everything else quiet and disciplined.
+
+Then critique the plan BEFORE building: *"would this exact design appear
+for any other brief?"* If yes, revise and state what changed and why.
+Quality floor, never announced: responsive to mobile, visible keyboard
+focus, `prefers-reduced-motion` respected, WCAG AA contrast.
+
+## 9. Design Marker Contract (`[arka:design]`)
+
+Every UI/design-producing turn MUST emit the structured marker on its own
+line BEFORE the first file edit:
+
+```
+[arka:design] benchmark=<Company> skills=<comma,list> tokens=<path|none>
+```
+
+- `benchmark=` — named reference company (Linear, Stripe, Vercel, Notion,
+  Airbnb…). Pick it FIRST and state what its design lead would reject in
+  your plan.
+- `skills=` — the design skills ACTUALLY loaded this session via the
+  Skill tool (e.g. `frontend-design,ui-ux-pro-max,gsap-core`). If a
+  plugin is not installed, be honest: `skills=degraded:<missing-name>`
+  and fall back to §3 + §8 of this reference. Never claim a load that
+  did not happen; never silently proceed as if it had.
+- `tokens=` — path of the project design-system source
+  (`design-system.yaml`, tokens file), or `none` + one-line justification.
+
+A bare `[arka:design] <token>` is a LEGACY marker: tolerated in WARN mode,
+counted separately in telemetry, and treated as missing once the frontend
+gate goes hard.
+
+## 10. Aesthetic Directions Catalog (optional, curated)
+
+When a project has NO design system yet and the brief leaves the visual
+axis free, seed a direction from the curated TypeUI catalog
+(`npx typeui.sh pull <slug>` — MIT, bergside/awesome-design-skills):
+
+`editorial` · `brutalism` · `neobrutalism` · `bento` · `expressive` ·
+`dramatic` — anti-default directions; `shadcn` · `mono` — clean baselines.
+
+Catalog tokens are a SEED for the project's own token system, never the
+final design system. Motion is absent from the catalog — that is GSAP's
+job: load `gsap-core` + `gsap-timeline` for any animation work,
+`gsap-scrolltrigger`/`gsap-plugins` as the work demands, `gsap-react` on
+React, and treat `gsap-performance` as the review bar
+(`npx skills add https://github.com/greensock/gsap-skills` when absent).

package/departments/brand/skills/colors/SKILL.md

@@ -20,11 +20,84 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 # Colors — `/brand colors <mood>`
 
 > **Agent:** Isabel (Visual Designer) | **Framework:** Color Theory + Accessibility
+> **Squad reference:** `departments/brand/references/uiux-knowledge-and-tools.md` (§3 tokens, §8 anti-default, §9 marker)
 
-## What It Does
+## Load design intelligence (MANDATORY — excellence-mandate)
 
-Color palette design: primary, secondary, accent, neutrals with contrast ratios.
+Do this BEFORE proposing a single hex value, in this order, and record
+what actually loaded:
+
+1. **`Skill(frontend-design)`** — Anthropic's anti-default doctrine: the
+   three AI-default looks, token-plan-then-critique, signature discipline.
+2. **`Skill(ui-ux-pro-max)`** — curated design data: 161 palettes,
+   57 font pairings, 99 UX guidelines; use its palette data as
+   comparative evidence, never as a menu to copy from.
+3. **Read the project design system** — `design-system.yaml`, token
+   files, or the brandbook; §3 of the squad reference is the in-repo
+   fallback when the Obsidian note is unreachable.
+
+### Graceful degradation (honest, never silent)
+
+If a plugin skill is NOT installed: say so explicitly, fall back to §3 +
+§8 of the squad reference, and emit the marker with
+`skills=degraded:<missing-name>`. Never claim a load that did not
+happen; never proceed as if it had.
+
+## Benchmark first
+
+NAME the reference company (Linear, Stripe, Vercel, Notion, Airbnb…)
+whose color craft this brand should be judged against, and write one
+line on what that company's design lead would reject in your current
+direction. No named benchmark, no palette.
+
+## Anti-default check
+
+Before finalizing: which of the three AI-default looks (§8 — cream +
+serif + terracotta; dark + acid accent; broadsheet) is this palette
+drifting toward? Self-test: *"would this exact palette appear for any
+other brief?"* If yes, revise and state what changed and why.
+
+## Design marker (before any file edit)
+
+```
+[arka:design] benchmark=<Company> skills=<comma,list> tokens=<path|none>
+```
+
+Emit on its own line BEFORE the first Write/Edit. Full contract: §9 of
+the squad reference.
+
+## Workflow
+
+1. **KB + brief** — search the vault for existing brand/palette notes;
+   extract the mood words from the brief and the subject's own world
+   (its materials, environments, vernacular — that is where
+   non-default color comes from).
+2. **Anchor** — pick the anchor hue from the subject, not from fashion.
+   State the reasoning in one sentence.
+3. **Build the palette as 4–6 NAMED roles** (name = function, never
+   "blue"): `surface` (canvas), `ink` (text), `primary` (identity),
+   `accent` (signal, ≤ 10–15% usage), plus optional `positive`/`danger`
+   semantics. Derive tints/shades in OKLCH so lightness steps are
+   perceptually even; give each role a hex.
+4. **WCAG pairs table** — for every text-bearing combination, compute
+   the contrast ratio and mark AA/AAA for body and large text. Any pair
+   below AA is redesigned, not footnoted.
+5. **Dark-mode variants** — restate every role for dark surfaces (do
+   not naive-invert; re-pick lightness in OKLCH).
+6. **Usage guidelines** — the 60/25/15 composition ratio (§3), do/don't
+   examples, and which role carries the signature element.
+7. **Critique pass** — rerun the anti-default self-test against the
+   named benchmark before delivering.
 
 ## Output
 
-Color palette with hex codes, usage guidelines, and WCAG contrast checks
+A palette block ready for token systems (DTCG-shaped: role → hex +
+OKLCH), the WCAG pairs table, dark-mode variants, and usage guidelines
+— saved to Obsidian under the project's Brand path and referenced by
+`tokens=` in the design marker of any implementation that follows.
+
+| Deliverable | Format |
+|---|---|
+| Palette (4–6 named roles) | hex + OKLCH per role, light + dark |
+| Contrast evidence | WCAG pairs table (AA/AAA per combination) |
+| Usage guide | 60/25/15 ratio, do/don't, signature carrier |