@hegemonart/get-design-done 1.28.0 → 1.28.5

package/reference/discover-procedure.md

@@ -0,0 +1,204 @@
+---
+name: discover-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [discover, procedure, extracted, pipeline-stage, connection-probe, design-context-builder]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/discover/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing workflow stays in `../skills/discover/SKILL.md`; this file holds the
+detail the agent reaches for when executing a specific step (state integration, three
+connection probes, design-context-builder + design-context-checker agent prompts, lazy gate
+prompt, auto-mode CSS detection).
+
+# Discover Procedure
+
+Detailed procedure for the get-design-done `discover` Stage 1.5 orchestrator. Companion to
+`../skills/discover/SKILL.md`. Read this file when executing a specific discover step.
+
+---
+
+## State Integration
+
+1. Read `.design/STATE.md`.
+   - If missing: create minimal skeleton from `reference/STATE-TEMPLATE.md` with stage=discover, status=in_progress, task_progress=0/1, and log warning: "STATE.md not found — created fresh. If this is a resumed session, run /get-design-done:scan first."
+   - If present and stage==discover and status==in_progress: RESUME — continue existing interview; do not reset.
+   - Otherwise: normal transition — set frontmatter stage=discover, <position> stage=discover, status=in_progress, task_progress=0/1.
+2. **Probe connection availability** — ToolSearch runs FIRST because MCP tools may be in the deferred tool set. This is the canonical probe pattern (spec lives in `connections/connections.md`; copied inline because SKILL.md has no include mechanism — if the probe pattern changes, update all stages that copied it). See §Connection Probes below.
+3. Update last_checkpoint. Write STATE.md.
+
+---
+
+## Connection Probes
+
+### A — Figma probe (variant-agnostic)
+
+```
+A1. ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
+A2. Parse tool names matching /^mcp__([^_]*figma[^_]*)__(get_metadata|use_figma)$/i
+    into read-capable and write-capable prefix sets.
+A3. Empty read set -> figma: not_configured (skip all Figma paths)
+    One or more matches -> pick prefix via tiebreaker:
+      (1) both-sets > reads-only,
+      (2) `figma` > others,
+      (3) non-`figma-desktop` > desktop,
+      (4) alphabetical.
+A4. Call {prefix}get_metadata:
+      Success -> figma: available (prefix=mcp__<prefix>__, writes=<true|false>)
+      Error   -> figma: unavailable
+```
+
+### B — Refero probe (ToolSearch presence is sufficient — no tool call needed)
+
+```
+B1. ToolSearch({ query: "refero", max_results: 5 })
+B2. Empty result  -> refero: not_configured
+    Non-empty     -> refero: available
+```
+
+### C — Pinterest probe (ToolSearch-only, same pattern as Refero)
+
+```
+C1. ToolSearch({ query: "mcp-pinterest", max_results: 5 })
+C2. Empty result  -> pinterest: not_configured
+    Non-empty     -> pinterest: available
+```
+
+No live `pinterest_search` call at probe time — ToolSearch presence is sufficient. The synthesizer makes the actual search calls.
+
+After all probes (A, B, C), update `.design/STATE.md` `<connections>` with the results and continue. Downstream stages (design-context-builder) read `<connections>` from STATE.md rather than re-probing.
+
+---
+
+## Auto Mode
+
+Auto Mode CSS detection (when `auto_mode: true` is passed to the builder):
+
+  1. If tailwind.config.{js,cjs,mjs,ts} exists -> Tailwind-only project
+     - Skip CSS file grep
+     - Parse tailwind.config for color palette, spacing scale, font families
+     - Use tailwind.config values as the baseline style signal
+  2. Else -> fall through to existing CSS file grep logic
+
+---
+
+## Step 1 — Spawn design-context-builder
+
+```
+Task("design-context-builder", """
+<required_reading>
+@.design/STATE.md
+@reference/audit-scoring.md
+@reference/anti-patterns.md
+</required_reading>
+
+You are the design-context-builder agent. Auto-detect existing design system
+state via grep/glob before asking questions. Interview the user ONLY for areas
+where auto-detect returned no confident answer. Write .design/DESIGN-CONTEXT.md.
+
+Baseline audit directory detection (ordered fallback chain):
+  1. If src/ exists -> use src/
+  2. Elif app/ exists -> use app/ (Next.js App Router)
+  3. Elif pages/ exists -> use pages/ (Next.js Pages Router)
+  4. Elif lib/ exists -> use lib/ (library-only projects)
+  5. Else -> flag "layout unknown", skip baseline, note in DESIGN-CONTEXT.md
+
+Common gray areas to probe during discovery (Area 7):
+  1. font-change risk — switching type families when existing UI has body copy in a specific family. Ask: "Is the current body font intentional or inherited? OK to change?"
+  2. token-layer introduction risk — adding CSS custom properties to a codebase that uses direct values. Ask: "Do you want design tokens (--primary, --surface) or inline values (hex, rgb)?"
+  3. Component rebuild vs restyle — when to keep existing component, when to rebuild from scratch. Ask: "For <component>, restyle in place or rebuild?"
+
+Context:
+  auto_mode: <true|false>
+
+Output file: .design/DESIGN-CONTEXT.md
+Emit `## CONTEXT COMPLETE` when done.
+""")
+```
+
+Wait for `## CONTEXT COMPLETE`. Update STATE.md task_progress = 0.5.
+
+---
+
+## Step 1.75 — Lazy gate: should design-context-checker run? (Plan 10.1-04, D-21)
+
+Spawn the cheap Haiku gate before the full context-checker:
+
+    Task("design-context-checker-gate", """
+    <required_reading>
+    @.design/STATE.md
+    </required_reading>
+
+    You are the design-context-checker-gate.
+
+    Context:
+      diff_files: <git diff --name-only HEAD~1..HEAD>
+      diff_body: (not needed — single-file heuristic)
+      baseline_sha: <HEAD~1>
+
+    Apply the heuristic (DESIGN-CONTEXT.md in diff_files?). Emit JSON + `## GATE COMPLETE`.
+    """)
+
+Wait for `## GATE COMPLETE`. Parse JSON:
+
+- `spawn: false` -> append `lazy_skipped: true` telemetry row for `design-context-checker`, skip Step 2, set STATE.md `<position>` as if checker passed (rationale: DESIGN-CONTEXT.md didn't change, last validation still holds), emit `design-context-checker skipped — <rationale>`.
+- `spawn: true` -> proceed to Step 2 as currently written.
+
+**Note:** On first-run discover, the builder just wrote DESIGN-CONTEXT.md so the gate returns `spawn: true`. The gate meaningfully short-circuits only on re-runs where the builder made no changes.
+
+**Parallel synthesizer note:** discover does not spawn parallel researchers in v1, so `skills/synthesize/` is not wired here. If future variants spawn N parallel interviewers/auto-detectors, wire synthesize between dispatch and collate as in `skills/map/` Step 3.5.
+
+---
+
+## Step 2 — Spawn design-context-checker
+
+```
+Task("design-context-checker", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+</required_reading>
+
+You are the design-context-checker agent. Validate DESIGN-CONTEXT.md across
+6 dimensions. Return APPROVED or BLOCKED with per-dimension verdicts.
+
+Emit `## CONTEXT CHECK COMPLETE` when done.
+""")
+```
+
+Wait for `## CONTEXT CHECK COMPLETE`.
+
+---
+
+## Step 3 — Handle checker verdict
+
+If APPROVED: proceed to state update.
+If BLOCKED: present dimensions that BLOCKED to user, offer fix-and-retry loop (re-spawn builder with specific fix instructions). Do not proceed to planning.
+
+---
+
+## State Update (exit)
+
+1. Set <position> status=completed, task_progress=1/1.
+2. Set <timestamps> discover_completed_at=<ISO 8601 now>.
+3. Update last_checkpoint. Write STATE.md.
+
+---
+
+## After Writing
+
+```
+=== Discovery complete ===
+Saved: .design/DESIGN-CONTEXT.md
+
+Baseline score: [N]/100 ([grade])
+Key issues: [top issue 1], [top issue 2], [top issue 3]
+
+Next: /get-design-done:plan
+  -> Decomposes your context into executable design tasks.
+==========================
+```
+
+Do not proceed to planning automatically unless `--auto` was passed.

package/reference/explore-procedure.md

@@ -0,0 +1,267 @@
+---
+name: explore-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [explore, procedure, extracted, pipeline-stage, connection-probe, design-interview, i18n]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/explore/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing workflow stays in `../skills/explore/SKILL.md`; this file holds the
+detail the agent reaches for when executing a specific step (six connection probes, 21st.dev
+prior-art check, inventory scan grep, design interview protocol, i18n probe, decision
+recording).
+
+# Explore Procedure
+
+Detailed procedure for the get-design-done `explore` Stage 2 orchestrator. Companion to
+`../skills/explore/SKILL.md`. Read this file when executing a specific step; the SKILL.md
+keeps the load-bearing workflow + decision tree, this file holds the deep methodology.
+
+---
+
+## Stage entry
+
+All STATE.md persistence in this skill goes through `gdd-state` MCP tools — no direct edits. The skill writes to `.design/STATE.md` (connections, decisions, progress, checkpoint) via those tools, and to plain design docs (DESIGN.md / DESIGN-DEBT.md / DESIGN-CONTEXT.md) via `Write`.
+
+1. Call `mcp__gdd_state__transition_stage` with `to: "explore"`.
+   - On success: proceed to probes.
+   - On gate failure: emit blockers to the user (do not advance). Each blocker is a line in the `error.context.blockers` array; print them verbatim.
+2. Call `mcp__gdd_state__get` with no arguments — snapshot the parsed state into a local `state` variable for downstream steps.
+
+---
+
+## Step 1 — Connection probe
+
+Probe connection availability (the batched write lands at the end of this step — see "Commit probe results" below):
+
+**A — Figma probe (variant-agnostic):**
+```
+ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
+Parse tool names matching /^mcp__([^_]*figma[^_]*)__(get_metadata|use_figma)$/i
+  into read-capable and write-capable prefix sets.
+Empty read set -> figma: not_configured
+One+ matches  -> pick prefix via tiebreaker:
+                (1) both-sets > reads-only,
+                (2) `figma` > others,
+                (3) non-`figma-desktop` > desktop,
+                (4) alphabetical.
+Then call {prefix}get_metadata:
+  success -> figma: available (prefix=mcp__<prefix>__, writes=<true|false>)
+  error   -> figma: unavailable
+```
+
+**B — Refero probe:**
+```
+ToolSearch({ query: "refero", max_results: 5 })
+Empty -> refero: not_configured
+Non-empty -> refero: available
+```
+
+**C — 21st.dev probe:**
+```
+ToolSearch({ query: "mcp__21st", max_results: 5 })
+Empty -> 21st-dev: not_configured
+Non-empty -> 21st-dev: available
+```
+
+**D — Magic Patterns probe:**
+```
+ToolSearch({ query: "mcp__magic_patterns", max_results: 5 })
+Empty -> magic-patterns: not_configured
+Non-empty -> magic-patterns: available
+```
+
+**E — paper.design probe:**
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+Empty -> paper-design: not_configured
+Non-empty -> call mcp__paper-design__get_selection; success -> available; error -> unavailable
+```
+
+**F — pencil.dev probe (file-based):**
+```bash
+find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null | head -1
+Empty -> pencil-dev: not_configured
+Found -> pencil-dev: available
+```
+
+## Commit probe results
+
+After all probes complete, commit results in a single call:
+
+`mcp__gdd_state__probe_connections` with `probe_results` = an array of `{ name, status }` entries — one per probed connection. Example:
+
+```json
+{
+  "probe_results": [
+    { "name": "figma", "status": "available" },
+    { "name": "refero", "status": "not_configured" },
+    { "name": "preview", "status": "unavailable" }
+  ]
+}
+```
+
+Unspecified connections keep their existing value. Do NOT issue multiple `probe_connections` calls — the tool is designed for a single batch write per stage.
+
+## Step 1.5 — 21st.dev Prior-Art Check (when 21st-dev: available)
+
+If `state.connections.21st-dev === "not_configured"` (from the snapshot captured at stage entry): skip this step entirely.
+
+When the explore stage identifies any greenfield component in scope (component name from BRIEF.md or user request that does not yet have an implementation file):
+
+1. `21st_magic_component_search(component_name, limit: 3)`
+2. Evaluate top result:
+   - **fit >= 80%**: add `<prior-art>` block to DESIGN.md:
+     ```xml
+     <prior-art source="21st.dev" component="<name>" fit="<score>%" id="<component_id>">
+       Recommendation: adopt — do not build custom. Confirm with design-executor.
+     </prior-art>
+     ```
+   - **fit < 80%**: note top candidate in DESIGN.md as a reference, proceed with custom build:
+     ```xml
+     <prior-art source="21st.dev" component="<name>" fit="<score>%" id="<component_id>">
+       Low fit — noted for reference. Building custom component.
+     </prior-art>
+     ```
+3. If `svgl_get_brand_logo` is available and explore scope includes brand logo assets: call `svgl_get_brand_logo(brand_name)` for each required brand asset; add SVG results to `.design/assets/` and note in DESIGN.md.
+
+If no greenfield components in scope: skip this step.
+
+---
+
+## Step 2 — Inventory scan (unless `--skip-scan`)
+
+**Map pre-check:** If `.design/map/` exists and all 5 files (`tokens.md`, `components.md`, `visual-hierarchy.md`, `a11y.md`, `motion.md`) are present AND fresher than `src/` (mtime), consume them as the inventory source and skip the grep pass. Otherwise proceed with grep below and, after Step 4, suggest running `/gdd:map` for richer parallel-scanned data on the next cycle.
+
+**Parallelism decision (before any multi-agent spawn):**
+1. Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
+2. Apply rules from `reference/parallelism-rules.md` (hard -> soft).
+3. Record the verdict via `mcp__gdd_state__set_status` with a short status label (e.g., `status: "explore_parallel"` or `"explore_serial"`) carrying the stage/verdict/reason/agents payload.
+4. If verdict is `parallel`, dispatch via multiple `Task()` calls in one response; if `serial`, spawn sequentially.
+
+Run the canonical scan grep/glob inventory (preserves PLAT-01/02 POSIX ERE patterns from Phase 1):
+
+- **Component detection** — `Glob` for `**/*.{tsx,jsx,vue,svelte}`; count exports, identify shared UI primitives.
+- **Color extraction** — `Grep` for hex (`#[0-9a-fA-F]{3,8}`), `rgb(`, `hsl(`, Tailwind arbitrary color classes; dedupe.
+- **Typography scan** — Grep font-family declarations, Tailwind `font-*`, `text-*` size classes; identify type scale.
+- **Motion scan** — Grep `transition`, `animate-`, `@keyframes`, `framer-motion` imports.
+- **Token detection** — Check for `tailwind.config.{js,cjs,mjs,ts}`, CSS custom properties (`--*`), design-token JSON.
+- **Layout detection** — Ordered fallback: `src/` -> `app/` -> `pages/` -> `lib/` -> unknown.
+
+Write findings to:
+- `.design/DESIGN.md` — current design system inventory + baseline score
+- `.design/DESIGN-DEBT.md` — prioritized debt roadmap
+
+Record scan progress: call `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` to reflect the scan pass.
+
+### Step 2.x — i18n readiness probe (informational)
+
+Phase 28 D-04 probe — 3-state classification, **informational only**. NO gate, NO blocking, NO required-action. Output appears as a single line in the explore report.
+
+Classification logic (matches `./reference/i18n.md` §Explore Integration Spec):
+
+```txt
+1. Read package.json (dependencies + devDependencies).
+
+2. Check against library matrix:
+     react-intl, next-intl, i18next, vue-i18n, formatjs, lingui
+   >=1 library found in deps or devDeps -> state = "framework-managed"
+                                          -> STOP, emit line, exit probe.
+
+3. Else (no library):
+     grep -RE "Intl\.(DateTimeFormat|NumberFormat|PluralRules|RelativeTimeFormat|ListFormat|Collator|Segmenter)" src/
+   >=1 match -> state = "partial"
+              -> emit line, exit probe.
+
+4. Else: state = "none"
+         -> emit line, exit probe.
+```
+
+Output line in explore report (single informational line, per D-04):
+
+```txt
+Localization readiness: framework-managed | partial | none
+```
+
+(Exactly one of the three values, single line.) A consumer downstream (a planning agent, a roadmap reviewer, the user) can act on the signal if a gap is meaningful for the project, but the probe itself never forces a step — surface signal, do not bolt on a new pillar (D-07 orthogonal-lens discipline).
+
+## Step 2.5 — Detect prior sketches and project-local conventions
+
+**Sketches**: If `.design/sketches/` exists, list all sketch slugs — group by those with `WINNER.md` (completed wrap-ups) vs without (pending). Call `mcp__gdd_state__set_status` with a brief note (e.g., `status: "explore_sketches_present"`) so downstream stages see the history. Include the inventory in DESIGN.md under a "Prior Explorations" section.
+
+**Project-local skills**: Read any `./.claude/skills/design-*-conventions.md` files if present. Include their content in DESIGN-CONTEXT.md under a `<project_conventions>` section — these are codified decisions from prior `/gdd:sketch-wrap-up` runs or manual edits, and they override defaults.
+
+**Global skills**: If `~/.claude/gdd/global-skills/` exists and contains `.md` files (other than README.md), read them and prepend their content to the `<project_conventions>` section under a `<global_conventions>` sub-block. Global skills represent cross-project personal conventions. They inform but do not override project-local decisions — when a project-local D-XX decision conflicts with a global skill, the project-local decision wins.
+
+---
+
+## Step 3 — Design interview (unless `--skip-interview`)
+
+**Run this inline — do NOT spawn `design-discussant` as a subagent.** Subagent UI tools (`AskUserQuestion`) only render the native picker when called from the top-level skill context; spawning a Task() degrades the interview to plain markdown in chat (broken in Claude Desktop).
+
+### 3.a — Pre-load context
+
+Read in this order:
+1. `state.decisions` from the snapshot captured at stage entry — existing D-XX entries (do NOT re-ask anything covered). If the snapshot is stale, refresh by calling `mcp__gdd_state__get`.
+2. `.design/BRIEF.md` — problem statement, audience, constraints
+3. `.design/DESIGN.md` — auto-detected inventory from Step 2
+4. `.design/DESIGN-CONTEXT.md` if it exists — `<gray_areas>` block lists unresolved topics
+5. `./.claude/skills/design-*-conventions.md` if any — locked project conventions, treat as authoritative
+
+If `state.connections` shows `figma: available`, read the resolved `prefix=` from the same entry and call `{prefix}get_variable_defs`, then draft tentative D-XX entries (mark `(tentative — confirm with user)`) before asking.
+
+### 3.b — Identify question set
+
+Build the list of areas needing input. Skip any area already answered by an existing D-XX or covered by a project convention. Default coverage:
+
+- Cycle goal / outcome that matters most
+- Audience and primary use context
+- Brand direction (only if no tokens detected in DESIGN.md)
+- Color primitives (only if no palette detected)
+- Typography scale (only if no type system detected)
+- Spacing scale (only if no spacing tokens detected)
+- Motion preferences (only if no motion patterns detected)
+- Any `<gray_areas>` from DESIGN-CONTEXT.md
+
+### 3.c — Ask, one question at a time
+
+For each area, call `AskUserQuestion` with a single focused question. Provide 4 concrete options plus "Other" / "Skip" where it helps. Do not batch questions into one call. Do not print the question as markdown — always go through the tool.
+
+Reject generic answers ("modern", "clean", "professional"). If the answer is vague, ask one follow-up before recording.
+
+### 3.d — Record after each answer
+
+After each confirmed answer:
+1. Call `mcp__gdd_state__add_decision` with the decision payload. The tool assigns the next `D-NN` id and persists atomically. Format the summary as:
+   ```
+   [Category] Decision summary — short rationale
+   ```
+2. Append one JSON line to `.design/learnings/question-quality.jsonl` (create if absent):
+   ```json
+   {"ts":"<iso>","question_id":"Q-NN","question_text":"<verbatim>","answer_summary":"<one sentence>","quality":"high|medium|low|skipped","evidence":"<why>","cycle":"<active-cycle-slug>"}
+   ```
+   Quality classification: `skipped` if user picked Skip / "doesn't matter"; `low` if < 10 words and not a specific value; `medium` if hedged ("maybe", "I think", "not sure"); `high` otherwise.
+3. `add_decision` commits incrementally — the decision survives a crash mid-interview without an explicit save step.
+
+### 3.e — Produce DESIGN-CONTEXT.md
+
+When all questions are answered, write `.design/DESIGN-CONTEXT.md` summarizing the locked decisions, remaining gray areas, and any Figma-sourced tentatives that were confirmed or rejected. Set frontmatter `status: complete`.
+
+---
+
+## Step 4 — Close out explore
+
+- If the synthesizer (or equivalent mapper batch) ran in Step 2, call `mcp__gdd_state__update_progress` with `task_progress: "<mappers-completed>/<mappers-total>"` and `status: "explore_mappers_done"` before advancing.
+- Call `mcp__gdd_state__checkpoint` — bumps `frontmatter.last_checkpoint` + appends a timestamp entry.
+- Stage advance to `plan` happens at the next stage's entry (the plan skill will transition from its own entry step); do not edit frontmatter directly from this skill.
+
+## After Writing
+
+```
+=== Explore complete ===
+Saved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md
+Next: @get-design-done plan
+=========================
+```

package/reference/health-mcp-detection.md

@@ -0,0 +1,44 @@
+---
+name: health-mcp-detection
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [health, mcp, detection, gdd-mcp, registration-nudge]
+last_updated: 2026-05-18
+---
+
+# Health MCP-Registration Detection Procedure
+
+Extracted from `skills/health/SKILL.md` per Phase 28.5 D-10 (extract-then-link, never delete content).
+This file documents the canonical procedure for inspecting whether `gdd-mcp` (Phase 27.7+) is
+registered with any installed harness and rendering a one-line status row after the health
+table. The procedure is non-blocking by design: any failure path renders `unknown` rather
+than crashing the skill.
+
+## Dismissal check
+
+1. Read `.design/config.json` (if present). Parse JSON inside a try/catch.
+2. If `config.mcp_nudge === false`, SKIP this step entirely (render nothing).
+3. On parse failure: default to `mcp_nudge=true` (show the row) — fail-safe per threat T-27.7-04-05.
+
+## Detection
+
+1. Read `.claude/settings.local.json` (or equivalent harness settings file) and inspect its `mcpServers` object — alternatively run `claude mcp list` / `codex mcp list` if a CLI is available (see fallback below).
+2. Preferred invocation via the install-lib: call `detectMcpRegistration()` from `scripts/lib/install/mcp-register.cjs`. Returns `{harnesses: [{harness, present, registered}], summary}`.
+
+## Row rendering
+
+Based on the detection result, render exactly ONE of these row strings:
+
+- When `claude` and `codex` both present + both registered:
+  `MCP server: registered with claude+codex`
+- When only one harness is present and registered:
+  `MCP server: registered with claude` (or `MCP server: registered with codex`)
+- When at least one harness is present but `gdd-mcp` is NOT in its registered list:
+  `MCP server: not registered  (run: npx @hegemonart/get-design-done --register-mcp; dismiss: .design/config.json#mcp_nudge=false)`
+- When neither harness CLI is found on PATH:
+  `MCP server: unknown (claude/codex CLI not found)`
+
+## Fallback (if `mcp-register.cjs` not yet shipped)
+
+Skip this step silently with status `MCP server: unknown`. This step is non-blocking — failures here MUST NOT crash the SKILL.

package/reference/health-skill-length-report.md

@@ -0,0 +1,69 @@
+# Health skill — skill-length report subsection
+
+Phase 28.5-11 / D-11 reference. Read by `skills/health/SKILL.md` to render the
+"Skill-length report" subsection after the standard health checks.
+
+## JSON shape (from `validate-skill-length.cjs --quiet --json`)
+
+```jsonc
+{
+  "summary": {
+    "total":    70,   // number of SKILL.md files under skills/
+    "clean":    70,   // skills with 0 errors and 0 warnings
+    "warnings": 0,    // skills with >=100 lines but <250 (D-01 warn band)
+    "blockers": 0     // skills with any block-level error (>=250 lines,
+                      //   missing frontmatter field, description out of
+                      //   range, disable-model-invocation non-whitelisted)
+  },
+  "skills": [
+    {
+      "name": "...",           // skill folder name (matches skills/<name>/SKILL.md)
+      "path": "...",           // absolute path to the file on disk
+      "lines": 0,              // wc -l semantics
+      "descriptionLength": 0,  // length of frontmatter.description string
+      "hasRequiredFields": true,
+      "level": "clean",        // "clean" | "warn" | "block"
+      "errors": [{ "code": "...", "message": "..." }],
+      "warnings": [{ "code": "...", "message": "..." }],
+      "reasons": ["..."]       // human-readable summary lines
+    }
+  ]
+}
+```
+
+## Render contract
+
+The health skill prints two lines after the existing checks table:
+
+```
+Skill-length: <total> total | <clean> clean | <warnings> warn (>=100) | <blockers> block (>=250)
+  All skills within contract.
+```
+
+If `summary.blockers > 0`, replace the second line with one indented row per
+blocker entry (skills where `level === "block"`):
+
+```
+Skill-length: 70 total | 67 clean | 2 warn (>=100) | 1 block (>=250)
+  - <name> (<lines> lines)
+```
+
+## Thresholds (D-01)
+
+- `warn >=100` — skill flagged as advisory; CI emits `::warning::` annotation
+  but does not fail the build.
+- `block >=250` — skill flagged as blocker; CI emits `::error::` and fails
+  the build via exit code 2.
+
+## Strict description-format (D-02)
+
+`STRICT_DESCRIPTION=1` / `--strict-description` is OFF by default. Phase 33
+will graduate the strict `<what>. Use when <triggers>.` regex from advisory
+to hard-block based on A/B evidence at
+`.design/research/description-format-ab.md`.
+
+## Cross-link from health
+
+- `skills/health/SKILL.md` — emits the report after the main checks table.
+- `scripts/validate-skill-length.cjs` — provides the JSON.
+- `tests/phase-28.5-baseline.test.cjs` — locks the post-rework distribution.

package/reference/heuristics.md

@@ -269,3 +269,87 @@ For each NNG heuristic (H-01 through H-10), rate 0–4:
 - 75–89: Good, minor issues
 - 60–74: Acceptable, improvement needed
 - <60: Significant UX problems, redesign required
+
+---
+
+## Dependency-cycle detection
+
+Algorithm consumed by `skills/analyze-dependencies/SKILL.md` Analysis 4. Detects cycles
+in the `@`-reference graph (File A → File B → File A) by DFS with path-tracking.
+
+**Input:** adjacency map `{from: [to, ...]}` built from `.design/intel/graph.json#edges`.
+
+**Algorithm:**
+
+```text
+visited = {}; path = []; cycles = []
+function dfs(node):
+  if node in path:
+    cycle_start = path.index(node)
+    cycles.append(path[cycle_start:] + [node])
+    return
+  if node in visited: return
+  visited.add(node); path.append(node)
+  for neighbor in adjacency[node]: dfs(neighbor)
+  path.pop()
+```
+
+**Bias notes:** the DFS visits each node at most once per traversal, so duplicate cycles
+across multiple entry points are deduped by the `visited` guard. The `path.index(node)`
+slice captures only the cycle suffix; nodes before the entry point are not part of the
+cycle. Pre-existing acyclic chains stay invisible — only back-edges surface.
+
+---
+
+## Version-cadence
+
+Reference for `skills/check-update/SKILL.md` and `skills/complete-cycle/SKILL.md` when
+comparing versions across releases.
+
+**Delta classification** (consumer of `.design/update-cache.json#delta`):
+
+| Delta | Meaning | When |
+|-------|---------|------|
+| `major` | Breaking change | `current.major < latest.major` |
+| `minor` | New features | Major same; `current.minor < latest.minor` |
+| `patch` | Bug fixes only | Major + minor same; `current.patch < latest.patch` |
+| `off-cadence` | Insertion-style version (`.5`, `.6`, `.7`) | Listed in `OFF_CADENCE_VERSIONS` in `tests/semver-compare.test.cjs` |
+| `none` | Same version | All segments equal |
+
+**Off-cadence handling:** versions like `v1.14.5`, `v1.27.5`, `v1.28.5` slot between regular
+minor bumps. They register via `OFF_CADENCE_VERSIONS.add('<version>')` in
+`tests/semver-compare.test.cjs`. The semver-compare test treats them as if they had a
+canonical predecessor (`v1.28.5` after `v1.28.0`, not `v1.28.4`).
+
+**Preview-suffix trap:** model IDs with `-preview` (`gpt-5-preview` vs `gpt-5`) drift — today's
+preview is tomorrow's GA. Tooling MUST store the parent name in `provider_model_id` and treat
+the suffix as decorative. See `./peer-cli-protocol.md` for the peer-CLI-side context.
+
+---
+
+## Optimization rules
+
+Reference catalog for `skills/optimize/SKILL.md`. Four deterministic rules; rule-based
+analysis applied in order. Each rule inspects per-agent aggregates from
+`.design/agent-metrics.json` and emits zero or more rows to the recommendations table.
+
+**R1 — Low cache hit rate.**
+- *Condition:* `total_spawns >= --min-spawns` AND `cache_hit_rate < 0.20`.
+- *Emit:* `"Consider batching tasks for agent {agent} — cache hit rate is {rate*100}%. Investigate cache-aligned ordering (see reference/shared-preamble.md) and whether input paths can be normalized."`
+- *Proposed action:* Batch similar tasks; confirm shared-preamble import ordering.
+
+**R2 — Expensive and rarely lazy-skipped.**
+- *Condition:* `total_cost_usd > 0.50` AND `lazy_skip_rate < 0.10`.
+- *Emit:* `"Agent {agent} is expensive (${cost}) and rarely skipped ({rate*100}% lazy-skip). Consider adding a lazy gate heuristic at agents/{agent}-gate.md (see plan 10.1-04 pattern)."`
+- *Proposed action:* Add lazy-gate agent.
+
+**R3 — Tier override churn.**
+- *Condition:* Multiple telemetry rows show recorded `tier` differing from frontmatter `default-tier` (e.g., frontmatter `opus` but measured rows consistently `haiku` from budget.json override or soft-threshold downgrade).
+- *Emit:* `"Tier override churn detected for {agent}: frontmatter says {frontmatter-tier} but measured tier is {measured-tier} in {N} of last {M} rows. Consider updating frontmatter default-tier or removing the budget.json override."`
+- *Proposed action:* Update frontmatter default-tier OR prune budget.json `tier_overrides` entry.
+
+**R4 — Typical duration drift.**
+- *Condition:* Measured `typical_duration_seconds` (computed as avg wall-clock between paired spawn/complete rows; fall back to frontmatter when pairing unavailable) differs from frontmatter `typical-duration-seconds` by more than 50%.
+- *Emit:* `"Typical duration for {agent} has drifted: frontmatter {old}s vs measured {new}s ({delta_pct}% drift). Update frontmatter typical-duration-seconds: {new}."`
+- *Proposed action:* Edit `agents/{agent}.md` frontmatter.
+- *Note:* v1 only computes wall-clock duration when telemetry ledger carries both spawn AND complete rows with matching correlation IDs. If unavailable, R4 flags "insufficient data" rather than emitting a false proposal. Phase 11 reflector can add a PostToolUse writer.