@hegemonart/get-design-done 1.28.0 → 1.28.5

package/reference/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./schemas/registry.schema.json",
   "version": 1,
-  "generated_at": "2026-04-24T00:00:00.000Z",
+  "generated_at": "2026-05-18T12:47:59.666Z",
   "entries": [
     {
       "name": "codex-tools",
@@ -811,6 +811,174 @@
       "path": "reference/visual-hierarchy-layout.md",
       "type": "heuristic",
       "description": "Z-order, whitespace, grids, F/Z patterns, 24 landing archetypes"
+    },
+    {
+      "name": "adr-format",
+      "path": "reference/adr-format.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "ADR (Architecture Decision Record) format — adapted from mattpocock/skills (MIT). 3-criteria offer gate (hard-to-reverse AND surprising-without-context AND real-tradeoff), 4-state status lifecycle. GDD addition: optional cycle-id + phase-id cross-refs to STATE.md."
+    },
+    {
+      "name": "apply-reflections-procedure",
+      "path": "reference/apply-reflections-procedure.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — apply-reflections procedure extracted from skills/apply-reflections per progressive-disclosure rule. Read by skills/apply-reflections/SKILL.md."
+    },
+    {
+      "name": "architecture-vocabulary",
+      "path": "reference/architecture-vocabulary.md",
+      "type": "principles",
+      "phase": 28.5,
+      "description": "Ousterhout glossary (A Philosophy of Software Design) ported via mattpocock/skills LANGUAGE.md (MIT). 8 core terms (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality) + 3 principles (deletion test, interface-is-test-surface, two-adapters-rule)."
+    },
+    {
+      "name": "cache-policy",
+      "path": "reference/cache-policy.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — cache-policy reference extracted from skills/cache-manager + skills/warm-cache per progressive-disclosure rule (Bucket 3 orchestrator + utility rework)."
+    },
+    {
+      "name": "compare-rubric",
+      "path": "reference/compare-rubric.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — compare-rubric extracted from skills/compare per progressive-disclosure rule. Read by skills/compare/SKILL.md (Bucket 2 design-family rework)."
+    },
+    {
+      "name": "connections-onboarding",
+      "path": "reference/connections-onboarding.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — connections-onboarding procedure extracted from skills/connections per progressive-disclosure rule (Bucket 2 design-family rework). Four-option setup prompt + onboarding flow."
+    },
+    {
+      "name": "context-md-format",
+      "path": "reference/context-md-format.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "CONTEXT.md format — adapted from mattpocock/skills (MIT) CONTEXT-FORMAT.md. DDD-style ubiquitous-language glossary schema, inline-write trigger, multi-context CONTEXT-MAP.md pattern. GDD additions: optional first-seen + aliases on term entries."
+    },
+    {
+      "name": "darkmode-audit-procedure",
+      "path": "reference/darkmode-audit-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — darkmode audit procedure extracted from skills/darkmode per progressive-disclosure rule (Bucket 2 design-family rework)."
+    },
+    {
+      "name": "debug-feedback-loops",
+      "path": "reference/debug-feedback-loops.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Debug feedback-loop discipline — adapted from mattpocock/skills (MIT) engineering/diagnose Phase 1. 10 construction paths in priority order (failing test -> curl -> CLI fixture -> headless browser -> trace replay -> throwaway harness -> fuzz -> bisect harness -> differential loop -> HITL bash), iterate-on-loop sub-discipline, non-determinism reproduction-rate branch."
+    },
+    {
+      "name": "design-procedure",
+      "path": "reference/design-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — design-stage procedure extracted from skills/design per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "discover-procedure",
+      "path": "reference/discover-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — discover-stage procedure extracted from skills/discover per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "explore-procedure",
+      "path": "reference/explore-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — explore-stage procedure extracted from skills/explore per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "health-mcp-detection",
+      "path": "reference/health-mcp-detection.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — health-MCP detection procedure extracted from skills/health per progressive-disclosure rule (D-10). Documents dismissal check, detection via scripts/lib/install/mcp-register.cjs, row rendering for claude/codex/both/neither, fallback for missing mcp-register.cjs."
+    },
+    {
+      "name": "health-skill-length-report",
+      "path": "reference/health-skill-length-report.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — health-skill-length-report contract documenting validate-skill-length.cjs JSON shape + threshold rationale. Read by skills/health/SKILL.md to render the skill-length report subsection."
+    },
+    {
+      "name": "milestone-completeness-rubric",
+      "path": "reference/milestone-completeness-rubric.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — milestone-completeness rubric extracted from skills/turn-closeout per progressive-disclosure rule (Bucket 4 analysis + audit rework). Turn-closeout / new-cycle completeness criteria."
+    },
+    {
+      "name": "peer-cli-protocol",
+      "path": "reference/peer-cli-protocol.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — peer-CLI protocol scaffold extracted from skills/peer-cli-add + skills/peer-cli-customize per progressive-disclosure rule (Bucket 4 analysis + audit rework). ACP + ASP adapter scaffolding patterns, verification ladder, Windows quirk handling."
+    },
+    {
+      "name": "plan-procedure",
+      "path": "reference/plan-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — plan-stage procedure extracted from skills/plan per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "router-rules",
+      "path": "reference/router-rules.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — router-rules reference extracted from skills/router per progressive-disclosure rule (Bucket 3 orchestrator + utility rework). S/M/L/XL bucket assignments + path-selection heuristic."
+    },
+    {
+      "name": "scan-procedure",
+      "path": "reference/scan-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — scan-stage procedure extracted from skills/scan per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "skill-authoring-contract",
+      "path": "reference/skill-authoring-contract.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 skill-authoring contract — adapted from mattpocock/skills (MIT). SKILL.md <=100-line cap (warn >=100, block >=250 in CI), 1024-char description cap, <what>. Use when <triggers>. form (lax-mode default per Phase 33 A/B pending), frontmatter required fields, progressive-disclosure one-level-deep rule. Validator at scripts/validate-skill-length.cjs."
+    },
+    {
+      "name": "start-procedure",
+      "path": "reference/start-procedure.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — start-procedure reference extracted from skills/start per progressive-disclosure rule (Bucket 4 analysis + audit rework)."
+    },
+    {
+      "name": "style-doc-procedure",
+      "path": "reference/style-doc-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — style-doc procedure extracted from skills/style per progressive-disclosure rule (Bucket 2 design-family rework)."
+    },
+    {
+      "name": "threat-modeling",
+      "path": "reference/threat-modeling.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — STRIDE threat-modeling patterns extracted from skills/quality-gate + audit-side scanning per progressive-disclosure rule (Bucket 4 analysis + audit rework). Audit-side threat-model invariants."
+    },
+    {
+      "name": "verify-procedure",
+      "path": "reference/verify-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — verify-stage procedure extracted from skills/verify per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
     }
   ]
 }

package/reference/registry.schema.json

@@ -45,7 +45,7 @@
             ]
           },
           "tier": { "enum": ["L0", "L1", "L2"] },
-          "phase": { "type": "integer", "description": "Phase that introduced this entry" },
+          "phase": { "type": "number", "description": "Phase that introduced this entry. Numbers are allowed (e.g., 19.6, 27.5, 27.6, 27.7, 28.5) — decimal phases are valid per the long-standing precedent established by Phases 19.6 / 27.5 / 27.6 / 27.7 / 28.5." },
           "description": { "type": "string" },
           "registered_at": { "type": "string", "format": "date-time" }
         },

package/reference/router-rules.md

@@ -0,0 +1,84 @@
+---
+name: router-rules
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [router, path-selection, complexity-class, model-tier, runtime-resolution, cost-estimation]
+last_updated: 2026-05-18
+---
+
+# Router Path-Selection + Runtime Resolution Rules
+
+Extracted from `skills/router/SKILL.md` per Phase 28.5 D-10 (extract-then-link, never delete
+content). The router SKILL keeps its invocation contract, output schema versioning table,
+integration point, and failure modes. The path-selection heuristic tables, the cost
+estimation algorithm, and the runtime-aware model resolution computation contract live
+here so the SKILL stays under the 100-line cap.
+
+## Path Selection Heuristic
+
+The router emits both `path` (legacy 3-tier enum) and `complexity_class` (Phase 25 4-tier enum). The canonical mapping is:
+
+| complexity_class | path | Behavior |
+|------------------|------|----------|
+| `S` | `fast` (short-circuited) | Skip router itself, skip cache-manager, skip telemetry write. Deterministic no-op decision. |
+| `M` | `fast` | Single Haiku + no checkers. |
+| `L` | `quick` | Sonnet mappers + Haiku verify. |
+| `XL` | `full` | Opus planners + full quality gates. Recommends worktree-isolation default + mandatory inter-stage checkpoint + reflector auto-spawn. |
+
+Bucket assignment:
+
+| Signal | complexity_class | path |
+|--------|------------------|------|
+| Command is `/gdd:help`, `/gdd:stats`, `/gdd:note`, `/gdd:health`, single-Haiku skill | `S` | `fast` (short-circuited — see below) |
+| Command is `/gdd:scan`, `/gdd:brief`, `/gdd:sketch`, `/gdd:spike`, `/gdd:fast` | `M` | `fast` |
+| Command spawns exactly one agent (no orchestration), not in S list | `M` | `fast` |
+| Command is `/gdd:explore`, `/gdd:discover`, standalone `/gdd:verify`, standalone `/gdd:plan` | `L` | `quick` |
+| Command spawns parallel mappers but no planners/auditors (`/gdd:discover` in `--auto` mode) | `L` | `quick` |
+| Command is `/gdd:next`, `/gdd:do`, `/gdd:autonomous`, end-to-end Brief→Verify, anything spawning planners + auditors + verifiers in series | `XL` | `full` |
+| Command spawns planners, auditors, verifiers, or integration-checkers (`/gdd:plan`, `/gdd:verify`, `/gdd:audit`) and is not standalone | `XL` | `full` |
+| `--dry-run` flag present on any command | downgrade one tier (XL→L→M→S; `path` follows the mapping table) |
+
+### S-class short-circuit
+
+When `complexity_class` would be `S`, the router itself **does not run** for that invocation — the deterministic skip list is encoded in the `/gdd:*` SKILL.md entry of the matching command. The budget-enforcer hook treats "no router decision payload + matching command name" as the S-class signal and skips enforcement entirely (no telemetry row, no cache lookup, no event emission). When the router *is* invoked explicitly (e.g., debugging) it still emits `complexity_class: "S"` in the JSON for observability, but the runtime path is the no-op.
+
+## Cost Estimation Algorithm
+
+```
+total = 0
+for each agent in planned spawn graph:
+  tier = resolve_tier(agent)   # budget.json tier_overrides > agent frontmatter default-tier
+  (in_tok, out_tok) = token_range_from_size_budget(agent.size_budget)  # from reference/model-prices.md
+  (in_rate, out_rate) = price_from_tier(tier)
+  total += (in_tok / 1e6) * in_rate + (out_tok / 1e6) * out_rate
+return total
+```
+
+## Runtime-aware model resolution
+
+The router emits `resolved_models` alongside `model_tier_overrides` so downstream consumers (budget-enforcer cost computation, Phase 22 cost telemetry, Phase 23.5 bandit posterior store) can read the **concrete model ID** for the active runtime without re-deriving it from the tier name. The resolution is per-agent and additive — `model_tier_overrides` keeps its `opus|sonnet|haiku` enum for back-compat across all 14 runtimes, and `resolved_models` runs the runtime-specific translation on top of it.
+
+Computation contract (per D-07):
+
+```
+runtime = runtimeDetect.detect() ?? 'claude'
+for each agent in planned spawn graph:
+  tier = resolve_tier(agent)                          # same merge as model_tier_overrides
+  resolved_models[agent] = tierResolver.resolve(runtime, tier)
+                                                       # → concrete model string OR null
+```
+
+Implementation surfaces (Phase 26 / Wave A):
+
+- `scripts/lib/runtime-detect.cjs` — `detect() → runtime-id | null`. Reads the same `*_CONFIG_DIR` / `*_HOME` env-vars Phase 24's installer uses (single source of truth in `scripts/lib/install/runtimes.cjs`). Returns `null` when no recognized runtime env-var is set; the router falls back to `'claude'` so the resolver always has a runtime ID to work with.
+- `scripts/lib/tier-resolver.cjs` — `resolve(runtime, tier, opts?) → model | null`. Translates `opus|sonnet|haiku` to the concrete model the runtime understands using the `./runtime-models.md` mapping (Phase 26 / Wave A). Fallback chain (D-04): runtime-specific entry → `claude` row default with `tier_resolution_fallback` event → `null` with `tier_resolution_failed` event. Never throws; `null` is a valid output the consumer must handle.
+
+Per-agent emission rules:
+
+- One key per agent in the planned spawn graph (same key set the cost-estimation loop iterates over). Keys MUST match agent names exactly so consumers can join `resolved_models` against `model_tier_overrides` and the spawn graph by name.
+- Value is the concrete model string returned by `tier-resolver.resolve(runtime, tier)`.
+- When the resolver returns `null` (missing tier-map row, missing tier, garbage input), the value is JSON `null` — NOT omitted, NOT the empty string. Consumers (budget-enforcer, telemetry) MUST handle `null`: typically by skipping the cost row for that spawn and emitting their own diagnostic event, never by crashing.
+- When `complexity_class` is `S` and the router itself short-circuits (see **S-class short-circuit** above), no payload is emitted at all and `resolved_models` does not exist for that invocation — the budget-enforcer's "no router decision payload" branch already handles this case.
+
+Back-compat assertion: a router invocation in a Claude runtime (or any environment where `runtime-detect.detect()` returns `null` and the router falls back to `'claude'`) produces `resolved_models` values that are the canonical Anthropic model IDs (`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`) for the corresponding tiers. Pre-Phase-26 consumers that ignore `resolved_models` see the same `model_tier_overrides` they always saw (Plan 26-09 owns the runtime fixture diff that asserts this).