bigpowers 2.82.3 → 2.83.0

package/.zcode/skills/diagnose-root/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: diagnose-root
+model: sonnet
+description: "Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use when a bug is confirmed but root cause is unclear, after investigate-bug, or when user mentions root cause analysis."
+---
+
+# Diagnose Root
+
+**Boundary**: Canonical, reusable 4-phase RCA engine. Invoked by `investigate-bug` (as step 2 of the end-to-end flow) and by `fix-bug` (when no bug file exists). Does not write the bug file — that is `investigate-bug`'s responsibility.
+
+Four phases — do not skip. Update the active `specs/bugs/BUG-*.md` file at each phase.
+
+## Phases
+
+1. **Reproduce** — minimal steps; record environment; capture logs.
+2. **Isolate** — narrow to module/function; binary-search commits or config.
+3. **Hypothesize** — list ranked hypotheses with falsification test each.
+4. **Verify** — run falsification; confirm single root cause; link to fix plan.
+
+> **HARD GATE** — Do not propose a fix until phase 4 confirms one root cause with evidence.
+
+## Verify
+
+→ verify: `BUG_FILE=$(ls -t specs/bugs/BUG-*.md 2>/dev/null | head -1); test -n "$BUG_FILE" && grep -cE "Reproduce|Isolate|Hypothesize|Verify" "$BUG_FILE" | awk '{if($1>=4) print "OK"; else print "INCOMPLETE"}' || echo "MISSING"`

package/.zcode/skills/diagnose-stall/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: diagnose-stall
+model: haiku
+description: "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned."
+---
+
+# Diagnose Stall
+
+> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state.
+
+Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode).
+
+## Stall signals
+
+| Signal | Likely cause |
+|--------|----------------|
+| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed |
+| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large |
+| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation |
+| Verify command running >15 min | Missing timeout or waiting on external service |
+| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff |
+
+## Process
+
+1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions.
+2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`.
+3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes.
+4. **Classify stall type:**
+   - **waiting_approval** — tool blocked on user consent
+   - **blocked_dependency** — prior task incomplete or red gate
+   - **agent_exhausted** — max iterations/cycles reached
+   - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed
+   - **external_io** — network, CI, or deploy wait without timeout
+   - **unknown** — escalate with evidence bundle
+5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user).
+6. **Write report** — `specs/verifications/STALL-<timestamp>.md` with classification, evidence, and recommended next skill.
+
+## Integration
+
+| Caller | When to invoke |
+|--------|----------------|
+| `/loop` (Cursor) | After two consecutive ticks with no observable progress |
+| `dispatch-agents` | When a wave exceeds expected duration with zero returns |
+| `execute-plan` | When a step checkpoint is overdue |
+| User | "Why did this stop?" / "Nothing is happening" |
+
+## Verify
+
+→ verify: `test -f specs/state.yaml && echo "OK: diagnose-stall can read session state" || echo "WARN: no state.yaml — diagnostic limited"`
+
+## Handoff
+
+Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml`
+Writes: `specs/verifications/STALL-*.md`

package/.zcode/skills/dispatch-agents/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: dispatch-agents
+model: sonnet
+description: "Dispatch multiple subagents in parallel on independent tasks. No waiting between them — all run concurrently. Use when tasks are truly decoupled and speed matters. Distinct from delegate-task (concurrent here, no inter-task review gate)."
+---
+
+# story: e09s04
+# story: e45s38
+<!-- story: e45s11 -->
+
+
+# story: e45s30
+
+# Dispatch Agents
+> **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents.
+
+
+Run multiple subagents in parallel on independent tasks. Use when tasks are genuinely decoupled — no agent needs the output of another to start.
+
+**Distinct from `delegate-task`:** This skill maximizes throughput via concurrency. There is no sequential review gate between tasks. Use `delegate-task` instead when a single task needs careful two-stage oversight before proceeding.
+
+## When to use
+
+- Tasks that can run simultaneously without shared state
+- Large plans that can be broken into parallel workstreams
+- Exploration: gather information from multiple parts of the codebase at once
+
+## When NOT to use
+
+- Task B depends on Task A's output
+- You need to review Task A before Task B can start safely
+- The tasks share a file and concurrent edits would conflict
+
+## Process
+
+### 1. Confirm independence
+
+Before dispatching, verify each task pair is truly independent:
+- No shared files being written
+- No shared state (DB migrations, config files)
+- No ordering dependency between outcomes
+
+If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead.
+
+## Subagent depth tiers (e45s30)
+
+Map `effort:` frontmatter and story `risk:` to prompt depth — do not send `minimal_decisive` agents a `full_maturity` brief.
+
+| Tier | When | Brief shape | Token budget |
+|------|------|-------------|----------------|
+| `full_maturity` | `effort: heavy`, `risk: P0`, security-sensitive diffs | Full `task_brief` + CONVENTIONS excerpts + threat model if present | Full envelope |
+| `standard` | `effort: standard`, `risk: P1`–`P2` | Standard `task_brief` fields below | Default |
+| `minimal_decisive` | `effort: light`, `risk: P3`, read-only exploration | `goal` + `verify` + `in_scope` only | ≤15 lines |
+
+Record `depth: <tier>` in the Agent tool description when dispatching.
+
+### 2. Write typed task briefs (Orca message protocol)
+
+Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else.
+
+Every inter-agent message uses a **typed envelope** — no freeform prose between waves:
+
+| `type` | When | Required fields |
+|--------|------|-----------------|
+| `task_brief` | Dispatch | `task_id`, `goal`, `in_scope`, `out_of_bounds`, `verify`, `prior_decisions` |
+| `checkpoint` | Mid-wave progress | `task_id`, `status` (`running`\|`blocked`), `comment` (one line) |
+| `result` | Agent return | `task_id`, `exit` (`pass`\|`fail`), `summary`, `verify_output` |
+| `circuit_open` | 3 consecutive failures | `task_id`, `failures` (3), `escalate_to` (`user`) |
+
+Example `task_brief` (each agent starts cold — brief size directly controls token cost and hallucination risk):
+
+```yaml
+type: task_brief
+task_id: agent-1
+goal: [one sentence — what success looks like]
+in_scope: [explicit file or module list]
+out_of_bounds: [what NOT to touch]
+verify: [runnable command]
+prior_decisions: [relevant entries from specs/state.yaml — omit if none]
+```
+
+Emit **`checkpoint`** comments when an agent is slow or blocked — one line, no stack traces. Parent reads checkpoints before spawning follow-ups.
+
+Do not include the full conversation, full file contents, or decisions unrelated to this agent's task.
+
+### 3. Circuit breaker + iterative retrieval (max 3 cycles)
+
+Track **consecutive failures per `task_id`**. On the **3rd consecutive `result.exit: fail`** for the same task, emit `type: circuit_open` and **stop dispatching** that task — escalate to user with the three failure summaries. Reset counter on any `pass`.
+
+After each wave completes:
+1. **Dispatch** — run parallel agents with typed `task_brief` envelopes.
+2. **Evaluate** — read `result` messages; list gaps vs goal; honor open circuits.
+3. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total).
+
+Stop when gaps empty, circuit opens, or cycle 3 reached — escalate to user. If agents go silent without returning, invoke `diagnose-stall` before spawning another wave.
+
+### 4. Dispatch in parallel
+
+Spawn all agents in a single message using multiple Agent tool calls. Each agent gets its own complete brief.
+
+```
+Agent 1: brief for task A
+Agent 2: brief for task B
+Agent 3: brief for task C
+```
+
+### 5. Collect and review results
+
+When all agents return: review each result, run verify commands, check diffs for scope violations.
+
+### 6. Integrate
+
+Merge accepted results. Resolve conflicts manually; note in summary.
+
+Report: which tasks succeeded, which need revision, overall verify status.
+
+## Verify
+→ verify: `grep -q 'circuit_open' skills/dispatch-agents/SKILL.md && grep -q 'task_brief' skills/dispatch-agents/SKILL.md && echo OK || echo FAIL`

package/.zcode/skills/edit-document/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: edit-document
+model: sonnet
+description: "Edit and improve documents by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, restructure, or improve any document — including specs/ files, articles, READMEs, or technical writing."
+---
+
+# Edit Document
+
+**Distinct from `write-document`:** Use this skill when the document already exists and needs restructuring, clarity, or prose improvements. Use `write-document` to create a document from scratch.
+
+> **HARD GATE** — Document edits must preserve intent and accuracy. Do NOT remove or contradict existing content without understanding why it was written. Check git history for context.
+
+## Process
+
+1. First, divide the document into sections based on its headings. Think about the main points made in each section.
+
+Consider that information is a directed acyclic graph, and that pieces of information can depend on other pieces of information. Make sure that the order of the sections and their contents respects these dependencies.
+
+Confirm the sections with the user.
+
+2. For each section:
+
+2a. Rewrite the section to improve clarity, coherence, and flow. Use maximum 240 characters per paragraph.

package/.zcode/skills/elaborate-spec/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: elaborate-spec
+model: opus
+description: "Refine a rough idea into a clear, detailed specification through dialogue. Does not produce code. Use when user has a vague idea, wants to think through a feature before planning, or needs to turn \"I want X\" into a concrete spec."
+---
+
+# Elaborate Spec
+
+Turn a rough idea into a clear specification through focused dialogue. No code is written during this skill — the output is shared understanding and a refined problem statement.
+
+> **HARD GATE** — Do NOT proceed with planning or implementation until the problem space is clearly understood. Success criteria, actors, and scope must be explicit before drafting a plan.
+
+## Process
+
+### 1. Listen first
+
+Let the user describe their idea in their own words. Do not interrupt or redirect. Take notes on:
+- The core problem they're trying to solve
+- Who is affected (actors)
+- What success looks like to them
+- Any constraints they've already identified
+
+### 2. Ask clarifying questions
+
+Ask one question at a time. Work through these areas:
+
+**Problem clarity**
+- What is the current behavior (or lack of behavior) that prompted this?
+- Who experiences this problem? How often?
+- What's the cost of not solving it?
+
+**Solution boundaries**
+- What is explicitly IN scope?
+- What is explicitly OUT of scope?
+- Are there existing solutions (internal or external) this replaces or integrates with?
+
+**Success criteria**
+- How will you know this is done?
+- What does the happy path look like end-to-end?
+- What are the key failure modes to handle?
+
+**Constraints**
+- Any performance requirements?
+- Any compatibility constraints (existing APIs, data formats)?
+- Any non-negotiable implementation decisions already made?
+
+### 2.5. Multiple Interpretations (HARD GATE)
+
+> **HARD GATE** — If the request admits ≥2 valid interpretations, do NOT guess. You must list them and ask the user to choose before proceeding. Proceeding with unresolved ambiguity is a failure of integrity.
+
+Present the options clearly:
+> "I see two ways to read this:
+> 1. [Interpretation A] — my recommendation because [reason]
+> 2. [Interpretation B]
+> Which is closer to what you mean?"
+
+### 3. Surface hidden assumptions
+
+Once the user has answered the main questions, probe for assumptions:
+- "You mentioned X — does that mean Y is also true?"
+- "What happens when Z fails?"
+- "Is this for internal users, external users, or both?"
+
+### 4. Synthesize and confirm
+
+Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md):
+- The problem (feeds into §1 Business narrative)
+- The solution and main flow (feeds into §5)
+- The key constraints and alternative flows (feeds into §6)
+- The success criteria (feeds into §17 Gherkin)
+- What's out of scope (feeds into §18)
+
+Ask: "Is this an accurate summary? Anything missing or wrong?"
+
+### 5. Write specs/planning-context.yaml
+
+After the user confirms the summary in step 4, persist the key decisions:
+
+```yaml
+# specs/planning-context.yaml — written by elaborate-spec; consumed by scope-work and slice-tasks
+feature_name: "<from step 1>"
+problem_statement: "<one paragraph>"
+constraints:
+  - "<constraint 1>"
+out_of_scope:
+  - "<excluded item 1>"
+key_decisions:
+  - decision: "<what was decided>"
+    rationale: "<why>"
+```
+
+If `specs/planning-context.yaml` already exists, ask: `"Planning context from a prior session exists. Update it? [Y/n]"`. Overwrite on Y; leave unchanged on N.
+
+### 6. Suggest next skill
+
+Once the spec is clear, recommend the next step:
+- If domain model needs work → `model-domain`
+- If ready to plan → `plan-release` (creates epic capsules with `epic.yaml` + story `.md` + `-tasks.yaml`) then `plan-work` per story
+- If a spike is needed first → `spike-prototype`
+- If architecture decisions are needed → `deepen-architecture` or `grill-me`
+- If the plan depends on a specific library or API → `grill-me` in docs mode

package/.zcode/skills/enforce-first/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: enforce-first
+model: haiku
+description: "Apply the F.I.R.S.T test quality rubric (per CONVENTIONS.md §Tests) to a test suite or individual tests. Use when develop-tdd is writing tests, when test quality needs to be checked, or when user mentions F.I.R.S.T or \"test quality\"."
+---
+
+# Enforce FIRST
+> **HARD GATE** — **HARD GATE** — Before shipping, ALL enforcement checks must pass: lint, typecheck, tests, coverage gates. Do NOT disable or skip checks to get to green.
+
+
+Apply the F.I.R.S.T rubric per CONVENTIONS.md §Tests to evaluate and improve tests.
+
+This skill is typically invoked internally by `develop-tdd` during the test-writing phase. It can also be run standalone on an existing test suite.
+
+## Modes
+
+- Default: full F.I.R.S.T audit (all 5 criteria)
+- --quick: Check Fast, Independent, and Self-Validating criteria only (per CONVENTIONS.md §Tests). Used by build-epic step 6 as a mechanical gate after audit-code. Skips Repeatable and Timely which require contextual judgment.
+
+## The F.I.R.S.T Rubric
+
+See CONVENTIONS.md §Tests for the canonical F.I.R.S.T rubric definition, checklists, and fix patterns.
+
+## Applying the rubric
+
+For each failing criterion:
+1. Identify which tests violate it
+2. Describe the fix
+3. Apply the fix
+4. Re-run the suite to confirm it still passes
+
+Report: "F.I.R.S.T audit complete. X criteria passed, Y fixed."

package/.zcode/skills/evolve-skill/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: evolve-skill
+model: opus
+description: "Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose plan-work change, edit skill via craft-skill, re-run benchmark, record ADR. Use when a skill underperforms on benchmark or stocktake finds systemic gap."
+---
+
+# story: e23s03
+
+# story: e09s01
+# story: e09s05
+
+# Evolve Skill
+
+> **HARD GATE** — No skill change ships without benchmark score ≥ pre-change baseline. Learning is measured and versioned — never implicit.
+
+## Loop
+
+1. **Regression gate** — Run `bash scripts/run-verification-gates.sh` to catch mechanical regressions (compliance, sync pipeline, size budget) before spending time on benchmark evals. If golden suite fails, fix regressions first — they are pre-requisites for any capability improvement.
+2. **Establish baseline** — Run `run-benchmark <skill> --baseline`. If no definition exists at `specs/benchmarks/<skill>.yaml`, create one following `specs/benchmarks/SCHEMA.md` first. Save report path in `state.yaml`. If `specs/benchmarks/reports/BASELINE-<skill>.yaml` already exists, skip this step.
+
+3. **Identify gap** — Read the baseline report (`specs/benchmarks/reports/BASELINE-<skill>.yaml`). Find scenarios with `result: FAIL` or low `pass_at_k`. This is the measurable gap.
+
+4. **`plan-work`** — Write a minimal change proposal targeting the failing scenarios. Include verify commands.
+
+5. **Edit** via `craft-skill` / direct SKILL.md edit; run `bash scripts/sync-skills.sh`.
+
+6. **Re-run benchmark** — `run-benchmark <skill>`. Compare new `pass_at_k` against baseline.
+   - **IMPROVED or STABLE** → advance to step 6.
+   - **REGRESSION** (`new pass_at_k < baseline`) → revert the change and loop back to step 3.
+
+7. **Record decision** — Write `specs/adr/NNNN-evolve-<skill>.md` with before/after `pass_at_k` scores. Update `session-state`.
+
+## Verify
+
+→ verify: `grep -c 'run-benchmark\|pass_at_k\|BASELINE-' skills/evolve-skill/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+
+See [REFERENCE.md](REFERENCE.md) for ADR template.
+
+
+<!-- story: e31s07 -->
+
+---
+
+# Evolve Skill — ADR snippet
+
+```markdown
+## ADR-XXXX: Evolve &lt;skill-name&gt;
+
+**Status:** Accepted
+**Benchmark:** before X% / after Y%
+**Change:** one-sentence summary
+**Evidence:** path/to/benchmark-report.md
+```
+
+Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path.

package/.zcode/skills/execute-plan/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: execute-plan
+model: haiku
+description: "Batch-execute tasks from the active epic capsule sequentially, with a human checkpoint after each step. Use when user has an approved plan and wants step-by-step oversight."
+---
+
+# Execute Plan
+
+Execute tasks from the **active epic** (`specs/epics/eNN-slug/epic.yaml` story `tasks[]`) one at a time, showing evidence after each step before proceeding.
+
+> **HARD GATE** — Do NOT proceed if on `main` or `master`. Run `kickoff-branch` first.
+>
+> **HARD GATE** — Active epic must exist with runnable `verify` on each task. If missing, run `plan-release` then `plan-work` or `build-epic`.
+
+## Process
+
+### 1. Read the plan
+
+Read `specs/state.yaml` (`active_epic`, `active_story`) and the matching `specs/epics/*/epic.yaml`. Parse `depends-on` in task descriptions for execution waves.
+
+> **CONTEXT ISOLATION** — Spawn each skill with a **fresh context window**. Pass decisions only through `specs/state.yaml` `handoff` — never rely on prior chat history.
+
+Confirm with the user: step count, skip/reorder, stop-after step.
+
+### 2. Execute step by step
+
+For each task in the active story:
+
+**a. Announce** — task `desc` and `verify` command.
+
+**b. Execute** — code or `delegate-task` / `dispatch-agents` for waves.
+
+**c. Run verify** — must be green before advancing.
+
+**d. Log** — non-obvious decisions in `specs/state.yaml` under `decisions[]` or `handoff` block.
+
+**e. Checkpoint** — ask to proceed unless autonomous mode requested.
+
+**f. Story UAT** — after last task, run manual verification script from story notes or `verify-work`.
+
+On verify failure: fix and re-run; never advance on red.
+
+Update `specs/execution-status.yaml` when a story/epic completes (`bash scripts/sync-status-from-epics.sh` or direct edit).
+
+### 3. Blockers
+
+Report blocker; ask skip/adapt/stop; update epic capsule if plan changes.
+
+### 4. Final report
+
+Suggest: `verify-work` → `run-evals` → `audit-code` → `simulate-agents` → `commit-message` → `release-branch`
+
+## Rules
+
+- **Loop until behavioral correctness is verified**: if a verify command passes but the observed behavior is still wrong, return to step 1 and run the execution cycle again.
+
+
+
+<!-- story: e02s03 -->
+<!-- story: e05s02 -->
+<!-- story: e08s01 -->

package/.zcode/skills/extract-design/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: extract-design
+model: sonnet
+description: "Extract a Google DESIGN.md file from an HTML prototype (claude.ai/design or any styled page) using Puppeteer, producing machine-readable tokens and AI-generated prose. Use when the user has an HTML prototype and wants a DESIGN.md to anchor their project's visual identity, or when seed-conventions has just scaffolded a new project."
+---
+
+# Extract DESIGN.md from HTML
+
+> **HARD GATE** — Do NOT write DESIGN.md without Puppeteer dual-pass extraction. Tokens from static HTML (Cheerio, regex, string scanning) are invalid — they miss cascade, custom properties, and Tailwind resolution.
+>
+> **HARD GATE** — Do NOT claim certainty where evidence is thin. Low-confidence color roles, component classifications, and prose assertions MUST be flagged with `<!-- AGENT NOTE: uncertain — validate during grill-me. Evidence: [what was observed] -->`.
+>
+> **HARD GATE** — Do NOT ship DESIGN.md without running `npx @google/design.md lint`. Unvalidated output is unverified output. If lint is unavailable (offline), flag prominently in terminal and in DESIGN.md prose.
+
+## Quick Start
+
+```bash
+# First run — extract from HTML prototype
+node extract-design/scripts/extract.js --source ./prototype.html
+
+# From a published URL
+node extract-design/scripts/extract.js --source https://my-prototype.example.com
+
+# With a custom name
+node extract-design/scripts/extract.js --source ./proto.html --name "My Design System"
+
+# Update — re-extract from new HTML, diff against existing
+node extract-design/scripts/extract.js --source ./proto-v2.html
+
+# Lint-only — validate existing DESIGN.md without re-extraction
+node extract-design/scripts/extract.js --lint-only
+```
+
+## Flow
+
+1. **Launch Puppeteer** — dual-pass (light + dark) with retry + timeout. CI flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`.
+2. **Collect styles** — `page.evaluate()` collects computed styles from every element. Returns raw JSON to Node.js. Browser = sensor; Node = brain.
+3. **Classify tokens** — modular pipeline: colors (Material 3 roles), typography (scale detection), spacing (tolerance GCD), rounded (clustering), components (visual signature + pseudo-state variants).
+4. **Generate prose** — AI heuristics produce all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with agent notes.
+5. **Write + validate** — serialize to `specs/tech-architecture/DESIGN_LATEST.md`, run `npx @google/design.md lint`, report to terminal.
+6. **Handoff** — writes `handoff.next_skill: grill-me` to `specs/state.yaml` with uncertain decisions context.
+
+## Inputs
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--source <file\|url>` | First run: yes. Update: optional | HTML prototype path or URL |
+| `--name <string>` | No | Design system name (defaults to `<title>` or directory name) |
+| `--lint-only` | No | Validate existing DESIGN.md without re-extraction |
+
+## Output
+
+- `specs/tech-architecture/DESIGN_LATEST.md` — replaces `DESIGN_PLAN_LATEST.md` as the canonical design artifact
+- Terminal summary: token counts, component count, lint result, uncertain decisions
+- Structured JSON log to stderr: extraction events, timing, counts
+- `specs/state.yaml` → `handoff.next_skill: grill-me` with context
+
+## Error Tiers
+
+| Tier | Condition | Response |
+|------|-----------|----------|
+| Fatal | No Chrome, page load timeout after retries | Exit non-zero, suggest fixes |
+| Degraded | Zero colors, zero typography, SPA shell | Write DESIGN.md with degradation warning |
+| Warned | Lint errors, uncertain decisions | Write DESIGN.md, flag in terminal, hand off to grill-me |
+
+## Dependencies
+
+- **Puppeteer** (Chrome binary) — wrapped behind `BrowserExtractor` interface for testability
+- **`@google/design.md`** (soft, via `npx`) — wrapped behind `DesignValidator` interface. Warns and skips if offline.
+
+## verify
+
+```bash
+node extract-design/tests/test-extraction.js
+```
+
+See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.
+
+---
+
+# Extract Design — Reference
+
+## Extraction Algorithms
+
+### Color Classification
+1. Collect unique computed `background-color`, `color`, `border-color` from every DOM element.
+2. Count frequency and context (text vs. bg vs. border vs. button).
+3. Classify using Material 3 roles: surface = largest-area bg, on-surface = most-used text, tertiary = highest-saturation on CTAs, error = reddish.
+4. Surface container levels: luminance-ordered. Hard-cap at 3 unless data supports 5.
+5. Low-confidence → `<!-- AGENT NOTE -->` in Colors prose.
+
+### Typography Classification
+1. Collect unique (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) tuples.
+2. Cluster by fontSize (±2px) → type scale.
+3. Detect heading hierarchy from HTML tag + computed size.
+4. Name levels: display-lg, headline-lg/md/sm, title-lg, body-lg/md/sm, label-lg/md/sm.
+5. Parse `<link>` and `@font-face`; warn if computed font differs from declared.
+
+### Spacing Classification
+1. Collect unique padding, margin, gap values. Filter: ignore values < 3 occurrences.
+2. Compute tolerance-based GCD (0.5px tolerance).
+3. Declare base unit. Detect half-step if gcd/2 values present ≥3 times.
+4. Map: unit×1 → sm, ×2 → md, ×4 → lg, ×8 → xl.
+
+### Rounded Classification
+1. Collect unique border-radius values. Cluster (1px tolerance).
+2. Name: none (0), sm (smallest), md (median), lg (large), xl (largest), full (9999px).
+
+### Component Detection
+- Button: w<300px, h<64px, bg+radius set, short text. cursor:pointer is bonus.
+- Card: bg+radius+padding set, larger area.
+- Input: `<input>` or `<textarea>` tag.
+- Pseudo-state variants: force :hover, :active, :focus for high-confidence components.
+
+### Prose Generation
+Generates all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with `<!-- AGENT NOTE: Generated from visual analysis. Grill-me should validate. -->`.
+
+## Material 3 Token Conventions
+Colors: primary, on-primary, secondary, tertiary, error, surface, on-surface, surface-container-*, outline, background, on-background.
+Typography: display-lg/md/sm, headline-lg/md/sm, title-lg/md/sm, body-lg/md/sm, label-lg/md/sm.
+Rounded: none, xs, sm, md, lg, xl, full.
+
+## CI Compatibility
+Chrome flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`
+
+## Defensive Code
+Retry with backoff (3 attempts, 1s/2s/4s), Timeout (30s page load, 10s pseudo-state), Graceful degradation (Tier 2 on empty extraction).
+
+## Known Risks
+- DESIGN.md spec is alpha. Skill pins to current spec.
+- Puppeteer is heavy (~300MB Chrome). Document requirement clearly.
+- Prose quality depends on AI heuristics. grill-me is the validation gate.