@hegemonart/get-design-done 1.59.4 → 1.59.6

package/SKILL.md

@@ -27,7 +27,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `plan` | `get-design-done:plan` | Stage 3 of 5 - decompose into tasks → DESIGN-PLAN.md |
 | `design` | `get-design-done:design` | Stage 4 of 5 - execute tasks → DESIGN-SUMMARY.md |
 | `verify` | `get-design-done:verify` | Stage 5 of 5 - score + audit → DESIGN-VERIFICATION.md |
-| `handoff <path>` | inline | Skip scan/discover/plan; initialize from Claude Design bundle; route to verify |
+| `handoff <path>` | `get-design-done:gdd-handoff` | Skip scan/discover/plan; initialize from Claude Design bundle; route to verify |
 | `map` | `get-design-done:gdd-map` | Parallel codebase mapping - spawns 5 mappers → `.design/map/*.md` + `.design/DESIGN-MAP.md` |
 | `next` | `get-design-done:gdd-next` | Route to the next pipeline stage based on STATE.md |
 | `help` | `get-design-done:gdd-help` | List all commands with one-line descriptions |
@@ -207,7 +207,7 @@ If `$ARGUMENTS` is a stage or command name - invoke it directly, no state check:
 /gdd:plan      → Skill("get-design-done:plan")          # stage 3-of-5
 /gdd:design    → Skill("get-design-done:design")        # stage 4-of-5
 /gdd:verify    → Skill("get-design-done:verify")        # stage 5-of-5
-/gdd:handoff   → [Handoff Routing] (inline — see ## Handoff Routing above)
+/gdd:handoff   → Skill("get-design-done:gdd-handoff")
 /gdd:map       → Skill("get-design-done:gdd-map")       # parallel codebase mapping
 /gdd:next      → Skill("get-design-done:gdd-next")
 /gdd:help      → Skill("get-design-done:gdd-help")

package/docs/i18n/README.de.md

@@ -4,6 +4,8 @@
 
 [English](../../README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · **Deutsch**
 
+> Hinweis: Diese Übersetzung kann hinter der englischen Version zurückliegen. Die maßgebliche Version ist [README.md](../../README.md) (translation may lag behind English; see README.md for the canonical version).
+
 **Eine Design-Quality-Pipeline für AI-Coding-Agenten: Brief → Explore → Plan → Implementierung → Verifikation.**
 
 **Get Design Done hält AI-generierte UI an deinen Brief, dein Design-System, deine Referenzen und deine Quality Gates gebunden. Funktioniert mit Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy und Cline.**

package/docs/i18n/README.fr.md

@@ -4,6 +4,8 @@
 
 [English](../../README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · **Français** · [Italiano](README.it.md) · [Deutsch](README.de.md)
 
+> Remarque : cette traduction peut être en retard sur la version anglaise. La version de référence est [README.md](../../README.md) (translation may lag behind English; see README.md for the canonical version).
+
 **Un pipeline de qualité design pour agents de code IA : brief → exploration → plan → implémentation → vérification.**
 
 **Get Design Done garde l'UI générée par IA liée à votre brief, votre design system, vos références et vos quality gates. Fonctionne avec Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy et Cline.**

package/docs/i18n/README.it.md

@@ -4,6 +4,8 @@
 
 [English](../../README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · **Italiano** · [Deutsch](README.de.md)
 
+> Nota: questa traduzione può essere in ritardo rispetto alla versione inglese. La versione di riferimento è [README.md](../../README.md) (translation may lag behind English; see README.md for the canonical version).
+
 **Una pipeline di qualità del design per agenti di coding IA: brief → esplorazione → piano → implementazione → verifica.**
 
 **Get Design Done mantiene l'UI generata dall'IA allineata al tuo brief, al tuo design system, ai tuoi riferimenti e ai tuoi quality gate. Funziona con Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy e Cline.**

package/docs/i18n/README.ja.md

@@ -4,6 +4,8 @@
 
 [English](../../README.md) · [简体中文](README.zh-CN.md) · **日本語** · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
 
+> 注記: この翻訳は英語版より遅れている場合があります。正式な版は [README.md](../../README.md) です (translation may lag behind English; see README.md for the canonical version)。
+
 **AI コーディングエージェントのためのデザイン品質パイプライン: ブリーフ → 探索 → 計画 → 実装 → 検証。**
 
 **Get Design Done は、AI が生成した UI をあなたのブリーフ、デザインシステム、リファレンス、品質ゲートに結びつけたまま進めます。Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、Qwen Code、CodeBuddy、Cline で動作します。**

package/docs/i18n/README.ko.md

@@ -4,6 +4,8 @@
 
 [English](../../README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · **한국어** · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
 
+> 참고: 이 번역은 영어 버전보다 늦을 수 있습니다. 기준이 되는 버전은 [README.md](../../README.md) 입니다 (translation may lag behind English; see README.md for the canonical version).
+
 **AI 코딩 에이전트를 위한 디자인 품질 파이프라인: 브리프 → 탐색 → 계획 → 구현 → 검증.**
 
 **Get Design Done은 AI가 생성한 UI가 브리프, 디자인 시스템, 레퍼런스, 품질 게이트에 계속 묶여 있도록 합니다. Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline에서 동작합니다.**

package/docs/i18n/README.zh-CN.md

@@ -4,6 +4,8 @@
 
 [English](../../README.md) · **简体中文** · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
 
+> 说明:此翻译可能落后于英文版本。规范版本以 [README.md](../../README.md) 为准 (translation may lag behind English; see README.md for the canonical version)。
+
 **面向 AI 编码智能体的设计质量流水线:简报 → 探索 → 规划 → 实现 → 验证。**
 
 **Get Design Done 让 AI 生成的 UI 始终贴住你的简报、设计系统、参考资料与质量闸门。支持 Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、Qwen Code、CodeBuddy 与 Cline。**

package/hooks/budget-enforcer.ts

@@ -191,6 +191,21 @@ const tierResolver = nodeRequire(
   '../scripts/lib/tier-resolver.cjs',
 ) as TierResolverModule;
 
+// Phase 59.5 P1: runtime-models parser for the BYOK/unverified provenance
+// guard. We read the parsed runtime rows to learn a runtime's `status`
+// ("verified" | "byok" | "unverified"). The parser is pure + never invoked
+// for its model-resolution side here; only to classify the runtime so an
+// unverified row never drives a HARD budget cap. Soft-imported defensively:
+// any parser failure degrades to the built-in verified allowlist below.
+interface RuntimeModelsParserModule {
+  parseRuntimeModels(opts?: { cwd?: string }): {
+    runtimes: Array<{ id: string; status?: string }>;
+  };
+}
+const runtimeModelsParser = nodeRequire(
+  '../scripts/lib/install/parse-runtime-models.cjs',
+) as RuntimeModelsParserModule;
+
 // Plan 33.6-03 (SC#6, D-08, D-12): OpenRouter tier-resolver adapter. When the
 // user opts in (`.design/config.json#openrouter_enabled: true` OR
 // `OPENROUTER_API_KEY` present), the hook consults this adapter FIRST for a
@@ -506,6 +521,75 @@ export function loadBudget(): ResolvedBudget {
   }
 }
 
+// ── runtime provenance status (Phase 59.5 P1) ───────────────────────────────
+
+/**
+ * Phase 59.5 P1: provenance confidence of a runtime's tier→model row, as
+ * documented in reference/runtime-models.md and enumerated by
+ * reference/schemas/runtime-models.schema.json#status.
+ */
+export type RuntimeStatus = 'verified' | 'byok' | 'unverified';
+
+/**
+ * Built-in verified allowlist: the 4 runtimes whose tier maps are confirmed
+ * against runtime-author docs (the runtime-models.md banner: "4 of 14 ...
+ * verified (claude, codex, gemini, qwen)"). Used as the fallback classifier
+ * when the parsed row carries no structured `status` field yet (the markdown
+ * JSON blocks do not emit `status` at the time of this plan; the schema is
+ * ready, the parser wiring is a deferred follow-up). Once a row DOES carry
+ * `status`, the parsed value takes precedence over this allowlist.
+ */
+const VERIFIED_RUNTIME_IDS: ReadonlySet<string> = new Set([
+  'claude',
+  'codex',
+  'gemini',
+  'qwen',
+]);
+
+/** Per-process memo of runtime-id → parsed `status` (null until first read). */
+let _runtimeStatusMap: Map<string, RuntimeStatus> | null = null;
+
+function isRuntimeStatus(v: unknown): v is RuntimeStatus {
+  return v === 'verified' || v === 'byok' || v === 'unverified';
+}
+
+/**
+ * Resolve a runtime's provenance status. Reads the parsed runtime-models
+ * doc once per process; if a row carries a structured `status` it wins,
+ * otherwise the built-in verified allowlist decides (verified vs unverified).
+ * Fail-open: any parser error → allowlist-only classification. Never throws.
+ *
+ * @param runtimeId runtime id (e.g. 'claude', 'cline'); falsy → 'unverified'.
+ */
+export function runtimeStatus(runtimeId: string | null | undefined): RuntimeStatus {
+  if (typeof runtimeId !== 'string' || runtimeId.length === 0) {
+    return 'unverified';
+  }
+  if (_runtimeStatusMap === null) {
+    _runtimeStatusMap = new Map();
+    try {
+      const parsed = runtimeModelsParser.parseRuntimeModels({ cwd: process.cwd() });
+      const rows = Array.isArray(parsed?.runtimes) ? parsed.runtimes : [];
+      for (const row of rows) {
+        if (row && typeof row.id === 'string' && isRuntimeStatus(row.status)) {
+          _runtimeStatusMap.set(row.id, row.status);
+        }
+      }
+    } catch {
+      // Fail open: parser error degrades to the verified allowlist below.
+    }
+  }
+  const parsedStatus = _runtimeStatusMap.get(runtimeId);
+  if (parsedStatus !== undefined) return parsedStatus;
+  return VERIFIED_RUNTIME_IDS.has(runtimeId) ? 'verified' : 'unverified';
+}
+
+/** True when the runtime row must NOT drive a HARD budget cap (P1 guard). */
+export function isUnverifiedRuntime(runtimeId: string | null | undefined): boolean {
+  const s = runtimeStatus(runtimeId);
+  return s === 'byok' || s === 'unverified';
+}
+
 // ── cumulative phase spend (WR-02) ──────────────────────────────────────────
 
 /**
@@ -1138,7 +1222,40 @@ export async function main(): Promise<void> {
   // no router decision is supplied, behavior is identical to pre-25.
   const perSpawnCap = resolvePerSpawnCap(budget, complexityClass);
 
-  if (budget.enforcement_mode === 'enforce') {
+  // ── Phase 59.5 P1: BYOK/unverified provenance guard ────────────────────────
+  //
+  // Resolve the runtime id (router-supplied `runtime`, else env detection,
+  // else 'claude', same precedence the cost-recording block uses below) so we
+  // can consult its runtime-models provenance `status` BEFORE the hard-cap
+  // branches. When the runtime row is byok/unverified the resolved per-runtime
+  // model is best-effort (the user's actual provider may diverge from the
+  // Anthropic-default fill), so an estimated cost computed against it must NOT
+  // hard-block the user. We degrade enforce-mode to advisory ('warn') for THIS
+  // spawn only: the per-spawn + per-phase 100% caps stop blocking and surface a
+  // stderr warning instead, while the 80% auto-downgrade still applies (a tier
+  // downgrade is non-blocking and strictly cheaper, so it is safe to keep).
+  // Verified runtimes (claude/codex/gemini/qwen) are unaffected (full hard
+  // enforcement). The project-level cap above is intentionally NOT degraded: it
+  // is governed by total ledger spend, not a per-runtime resolved model.
+  const guardRuntimeId =
+    (typeof routerDecision?.runtime === 'string' && routerDecision.runtime.length > 0
+      ? routerDecision.runtime
+      : runtimeDetect.detect()) ?? 'claude';
+  const runtimeIsUnverified = isUnverifiedRuntime(guardRuntimeId);
+  const effectiveEnforcementMode: ResolvedBudget['enforcement_mode'] =
+    budget.enforcement_mode === 'enforce' && runtimeIsUnverified
+      ? 'warn'
+      : budget.enforcement_mode;
+  if (budget.enforcement_mode === 'enforce' && runtimeIsUnverified) {
+    process.stderr.write(
+      `gdd-budget-enforcer WARN: runtime '${guardRuntimeId}' has provenance status ` +
+        `'${runtimeStatus(guardRuntimeId)}' (BYOK/unverified tier→model row); ` +
+        `hard budget caps degraded to advisory for this spawn so an unverified ` +
+        `cost estimate never hard-blocks you.\n`,
+    );
+  }
+
+  if (effectiveEnforcementMode === 'enforce') {
     // Branch C: 100% per-spawn cap hard block (class-specific or per_task).
     if (estCost >= perSpawnCap) {
       writeTelemetry({
@@ -1202,12 +1319,24 @@ export async function main(): Promise<void> {
       toolInput._tier_override = 'haiku';
       toolInput._tier_downgraded = true;
     }
-  } else if (budget.enforcement_mode === 'warn') {
+  } else if (effectiveEnforcementMode === 'warn') {
     if (estCost >= perSpawnCap) {
       process.stderr.write(
         `gdd-budget-enforcer WARN: per-spawn cap will be exceeded ($${estCost.toFixed(4)} >= $${perSpawnCap})\n`,
       );
     }
+    // Phase 59.5 P1: when enforce was degraded to advisory for a byok/unverified
+    // runtime, also surface the per-phase breach that the hard branch above
+    // would otherwise have reported (it is skipped for unverified runtimes).
+    if (
+      budget.enforcement_mode === 'enforce' &&
+      phaseSpend + estCost >= budget.per_phase_cap_usd
+    ) {
+      process.stderr.write(
+        `gdd-budget-enforcer WARN: per-phase cap will be exceeded for ${phase} ` +
+          `($${(phaseSpend + estCost).toFixed(4)} >= $${budget.per_phase_cap_usd.toFixed(2)})\n`,
+      );
+    }
   }
   // enforcement_mode === 'log': telemetry only.
 
@@ -1230,11 +1359,9 @@ export async function main(): Promise<void> {
     toolInput._tier_override ?? toolInput._default_tier ?? 'sonnet';
   // Runtime tag: prefer the router's explicit `runtime` (D-08) field;
   // fall back to env-var detection; default to 'claude' since the .ts
-  // hook itself only runs inside Claude Code.
-  const runtimeId =
-    (typeof routerDecision?.runtime === 'string' && routerDecision.runtime.length > 0
-      ? routerDecision.runtime
-      : runtimeDetect.detect()) ?? 'claude';
+  // hook itself only runs inside Claude Code. Reuse the id already resolved
+  // for the Phase 59.5 P1 provenance guard above (single resolution source).
+  const runtimeId = guardRuntimeId;
 
   // ── Plan 27.5-02 — bandit consultation ────────────────────────────────────
   //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.59.4",
+  "version": "1.59.6",
   "description": "A design-quality pipeline for AI coding agents: brief, explore, plan, design, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/runtime-models.md

@@ -10,7 +10,7 @@ Single canonical map from Anthropic tier names (`opus|sonnet|haiku`) and runtime
 >
 > Unverified: kilo, copilot, cursor, windsurf, antigravity, augment, trae, codebuddy, cline, opencode.
 >
-> The schema (`reference/schemas/runtime-models.schema.json`) explicitly accepts the placeholder marker so the file ships shape-valid; the unverified-ness is a content gap, not a structural defect.
+> **Provenance status field.** Each row below is annotated with a structured `status` in its section heading: `verified` (confirmed against runtime-author docs), `byok` (BYOK / multi-provider, where the user-configured model may diverge from the Anthropic-default fill), or `unverified` (placeholder fill pending researcher confirmation). The schema (`reference/schemas/runtime-models.schema.json`) accepts an optional `status` enum of exactly these three values, so verified rows MAY omit it and remain shape-valid. The `hooks/budget-enforcer.ts` guard consults this status (or its built-in verified allowlist) so a `byok`/`unverified` row never drives a HARD budget cap: it degrades to advisory enforcement for that spawn. This makes the unverified-ness machine-readable, not just a content gap in prose.
 
 This file is parsed by `scripts/lib/install/parse-runtime-models.cjs` and consumed by:
 
@@ -36,7 +36,7 @@ This file is parsed by `scripts/lib/install/parse-runtime-models.cjs` and consum
 
 ---
 
-## claude - Claude Code
+## claude - Claude Code (status: verified)
 
 Anthropic's first-party runtime. Public tier docs at https://docs.anthropic.com/en/docs/about-claude/models. Seed picks per CONTEXT.md D-02.
 
@@ -66,7 +66,7 @@ Anthropic's first-party runtime. Public tier docs at https://docs.anthropic.com/
 
 ---
 
-## codex - OpenAI Codex CLI
+## codex - OpenAI Codex CLI (status: verified)
 
 OpenAI's Codex CLI runtime. Public tier docs at https://platform.openai.com/docs/models. Seed picks per CONTEXT.md D-02.
 
@@ -96,7 +96,7 @@ OpenAI's Codex CLI runtime. Public tier docs at https://platform.openai.com/docs
 
 ---
 
-## gemini - Gemini CLI
+## gemini - Gemini CLI (status: verified)
 
 Google's Gemini CLI runtime. Public tier docs at https://ai.google.dev/gemini-api/docs/models. Seed picks per CONTEXT.md D-02.
 
@@ -126,7 +126,7 @@ Google's Gemini CLI runtime. Public tier docs at https://ai.google.dev/gemini-ap
 
 ---
 
-## qwen - Qwen Code
+## qwen - Qwen Code (status: verified)
 
 Alibaba's Qwen Code runtime. Public tier docs at https://github.com/QwenLM/qwen-code. Seed picks per CONTEXT.md D-02.
 
@@ -156,7 +156,7 @@ Alibaba's Qwen Code runtime. Public tier docs at https://github.com/QwenLM/qwen-
 
 ---
 
-## kilo - Kilo Code
+## kilo - Kilo Code (status: byok)
 
 Kilo Code adapter - multi-provider, Anthropic-default fill until runtime-author docs confirm. Researcher fill needed (CONTEXT.md D-02).
 
@@ -186,7 +186,7 @@ Kilo Code adapter - multi-provider, Anthropic-default fill until runtime-author
 
 ---
 
-## copilot - GitHub Copilot CLI
+## copilot - GitHub Copilot CLI (status: byok)
 
 GitHub Copilot CLI - multi-provider routing under the hood. Researcher fill needed (CONTEXT.md D-02).
 
@@ -216,7 +216,7 @@ GitHub Copilot CLI - multi-provider routing under the hood. Researcher fill need
 
 ---
 
-## cursor - Cursor
+## cursor - Cursor (status: byok)
 
 Cursor IDE/CLI - multi-provider routing. Researcher fill needed (CONTEXT.md D-02).
 
@@ -246,7 +246,7 @@ Cursor IDE/CLI - multi-provider routing. Researcher fill needed (CONTEXT.md D-02
 
 ---
 
-## windsurf - Windsurf
+## windsurf - Windsurf (status: byok)
 
 Windsurf (formerly Codeium) - multi-provider Cascade router. Researcher fill needed (CONTEXT.md D-02).
 
@@ -276,7 +276,7 @@ Windsurf (formerly Codeium) - multi-provider Cascade router. Researcher fill nee
 
 ---
 
-## antigravity - Antigravity
+## antigravity - Antigravity (status: unverified)
 
 Antigravity - Google's agentic coding platform. Researcher fill needed (CONTEXT.md D-02).
 
@@ -306,7 +306,7 @@ Antigravity - Google's agentic coding platform. Researcher fill needed (CONTEXT.
 
 ---
 
-## augment - Augment
+## augment - Augment (status: byok)
 
 Augment Code - multi-provider agentic IDE. Researcher fill needed (CONTEXT.md D-02).
 
@@ -336,7 +336,7 @@ Augment Code - multi-provider agentic IDE. Researcher fill needed (CONTEXT.md D-
 
 ---
 
-## trae - Trae
+## trae - Trae (status: unverified)
 
 Trae - single-model session runtime per CONTEXT.md D-02 example. `single_tier: true` annotates the row. Researcher fill needed.
 
@@ -367,7 +367,7 @@ Trae - single-model session runtime per CONTEXT.md D-02 example. `single_tier: t
 
 ---
 
-## codebuddy - CodeBuddy
+## codebuddy - CodeBuddy (status: byok)
 
 CodeBuddy (Tencent) - multi-provider routing. Researcher fill needed (CONTEXT.md D-02).
 
@@ -397,7 +397,7 @@ CodeBuddy (Tencent) - multi-provider routing. Researcher fill needed (CONTEXT.md
 
 ---
 
-## cline - Cline
+## cline - Cline (status: byok)
 
 Cline (formerly Claude Dev) - multi-provider VS Code agent. Researcher fill needed (CONTEXT.md D-02).
 
@@ -427,7 +427,7 @@ Cline (formerly Claude Dev) - multi-provider VS Code agent. Researcher fill need
 
 ---
 
-## opencode - OpenCode
+## opencode - OpenCode (status: byok)
 
 OpenCode - open-source AI coding agent, BYOK multi-provider. Researcher fill needed (CONTEXT.md D-02).
 

package/reference/schemas/generated.d.ts

@@ -1042,6 +1042,10 @@ export interface RuntimeEntry {
    * When true, the runtime exposes a single model that maps to all three tiers (D-02). Downstream consumers (router, budget-enforcer) may render a UI affordance noting tier-selection has no cost effect for this runtime.
    */
   single_tier?: boolean;
+  /**
+   * Provenance confidence of this runtime's tier map. 'verified' = confirmed against runtime-author docs (claude, codex, gemini, qwen). 'byok' = BYOK / multi-provider runtime whose user-configured model may diverge from the Anthropic-default fill. 'unverified' = placeholder fill pending researcher confirmation. Optional: rows omitting this field are treated as unverified-unless-stated by consumers, and verified rows MAY omit it. The budget-enforcer guard reads this (or its built-in verified allowlist) so a byok/unverified row never drives a HARD budget cap (degrades to advisory).
+   */
+  status?: 'verified' | 'byok' | 'unverified';
   /**
    * Map of canonical Anthropic tier names (D-03) to the runtime's concrete model identifier. All three keys are required even when single_tier=true (assign the same model three times).
    */

package/reference/schemas/runtime-models.schema.json

@@ -47,6 +47,11 @@
           "type": "boolean",
           "description": "When true, the runtime exposes a single model that maps to all three tiers (D-02). Downstream consumers (router, budget-enforcer) may render a UI affordance noting tier-selection has no cost effect for this runtime."
         },
+        "status": {
+          "type": "string",
+          "enum": ["verified", "byok", "unverified"],
+          "description": "Provenance confidence of this runtime's tier map. 'verified' = confirmed against runtime-author docs (claude, codex, gemini, qwen). 'byok' = BYOK / multi-provider runtime whose user-configured model may diverge from the Anthropic-default fill. 'unverified' = placeholder fill pending researcher confirmation. Optional: rows omitting this field are treated as unverified-unless-stated by consumers, and verified rows MAY omit it. The budget-enforcer guard reads this (or its built-in verified allowlist) so a byok/unverified row never drives a HARD budget cap (degrades to advisory)."
+        },
         "tier_to_model": {
           "type": "object",
           "additionalProperties": false,

package/reference/skill-graph.md

@@ -9,7 +9,7 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 95. Composition edges: 19 composes_with, 6 next_skills.
+Skills: 96. Composition edges: 20 composes_with, 7 next_skills.
 
 ```mermaid
 flowchart TD
@@ -78,6 +78,7 @@ flowchart TD
     n_fast["fast"]
     n_figma_extract["figma-extract"]
     n_graphify["graphify"]
+    n_handoff["handoff"]
     n_health["health"]
     n_help["help"]
     n_instinct["instinct"]
@@ -138,6 +139,8 @@ flowchart TD
   n_explore --> n_list_assumptions
   n_explore --> n_sketch
   n_explore -.-> n_plan
+  n_handoff --> n_verify
+  n_handoff -.-> n_verify
   n_new_cycle --> n_brief
   n_new_project --> n_brief
   n_new_project -.-> n_brief

package/scripts/lib/bandit-router/integration.cjs

@@ -35,6 +35,12 @@
 
 const banditRouter = require('../bandit-router.cjs');
 const adaptiveModeLib = require('../adaptive-mode.cjs');
+// Phase 56 (CAL-01) per-agent risk calibration. recordOutcome feeds the same
+// {agent, status} signal it gives the bandit into this table so calibration
+// learns from the post-spawn outcome too. Lazy-tolerant: the call is wrapped in
+// its own best-effort try/catch (D-04) so a calibration write can never break
+// the bandit path.
+const calibration = require('../risk/calibration.cjs');
 
 const DELEGATE_NONE = banditRouter.DELEGATE_NONE; // 'none'
 const VALID_DELEGATES = banditRouter.DEFAULT_DELEGATES; // ['none','gemini','codex','cursor','copilot','qwen']
@@ -299,6 +305,38 @@ function recordOutcome(input) {
     }
   }
 
+  // CAL-01: also fold the same outcome into the per-agent risk calibration
+  // table so the calibration layer (compute-risk feedback) learns from the
+  // identical post-spawn signal the bandit just saw. Independent best-effort
+  // try/catch (D-04): a calibration write failure must NEVER throw into or
+  // break the bandit path above. The bandit signal carries no emitted risk
+  // score, so `risk` degrades to 0 via normalizeRecord; status drives the
+  // correctness axis (completed → applied-correct, anything else → not-correct).
+  // Writes to calibration.DEFAULT_CALIBRATION_PATH ('.design/telemetry/
+  // calibration.json') under baseDir — the module's own canonical location.
+  try {
+    calibration.updateCalibration(
+      input.agent,
+      {
+        accepted: true,
+        post_apply_correct: input.status === 'completed',
+      },
+      { root: input.baseDir, baseDir: input.baseDir },
+    );
+  } catch (err) {
+    if (process.env.GDD_BANDIT_DEBUG === '1') {
+      try {
+        process.stderr.write(
+          '[bandit-integration] recordOutcome calibration swallowed: ' +
+            (err && err.message ? err.message : String(err)) +
+            '\n',
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+
   return undefined;
 }
 

package/scripts/lib/install/installer.cjs

@@ -334,6 +334,58 @@ function listSourceSkills(skillsRoot) {
     });
 }
 
+/**
+ * Enumerate co-located sibling `*.md` reference files for a skill.
+ *
+ * A skill source directory may ship reference files next to SKILL.md
+ * (e.g. `<name>-procedure.md`, `<name>-rules.md`, `cache-policy.md`).
+ * SKILL.md references these via relative links; if they are not installed
+ * the links resolve to nothing. This returns the top-level sibling `.md`
+ * files only (NOT SKILL.md itself, NOT files in nested subdirectories).
+ *
+ * Best-effort: any fs error yields an empty list (never throws). A single
+ * unreadable skill dir must not crash the whole install.
+ *
+ * @param {string} skillSrcDir  absolute path to `<skillsRoot>/<name>`
+ * @returns {string[]} basenames of sibling `.md` files (excluding SKILL.md)
+ */
+function listSiblingRefFiles(skillSrcDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(skillSrcDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((ent) => {
+      if (!ent.isFile()) return false;
+      if (ent.name === 'SKILL.md') return false;
+      return ent.name.toLowerCase().endsWith('.md');
+    })
+    .map((ent) => ent.name);
+}
+
+/**
+ * Wrap a passthrough sibling reference file's content with a plugin
+ * fingerprint header so foreign-file protection + uninstall can recognize
+ * it as plugin-owned. Idempotent: re-wrapping a file that already carries
+ * the fingerprint returns it unchanged.
+ *
+ * The fingerprint matches `merge.cjs#GDD_ADAPTER_FINGERPRINT`, the same
+ * marker every SKILL converter injects via `shared.ensureAdapterHeader`,
+ * so `isPluginOwned` treats the sibling as owned.
+ *
+ * @param {string} raw  source sibling file content
+ * @returns {string}
+ */
+function fingerprintSiblingRef(raw) {
+  const text = typeof raw === 'string' ? raw : '';
+  if (isPluginOwned(text)) return text;
+  const header =
+    '<!-- gdd: auto-generated from Claude SKILL.md. Reference adapter -->\n\n';
+  return header + text;
+}
+
 /**
  * Install all artifacts for a `multi-artifact` runtime.
  *
@@ -395,6 +447,48 @@ function installMultiArtifact(runtime, configDir, dryRun, opts) {
         action: writeResult.action,
         ...(writeResult.reason ? { reason: writeResult.reason } : {}),
       });
+
+      // Batch H6: carry co-located sibling `*.md` reference files alongside
+      // SKILL.md. The skills layout only stages SKILL.md per skill, so
+      // reference siblings (e.g. `<name>-procedure.md`) are otherwise lost.
+      // Scoped to cursor (the audited flat-layout runtime); other runtimes
+      // keep their prior single-SKILL.md behavior. Siblings are passthrough
+      // copies fingerprinted so foreign-file protection + uninstall treat
+      // them as plugin-owned. Broader skillsKind-runtime carry is deferred
+      // (see converters/cursor.cjs KNOWN LIMITATION).
+      if (kind.kind === 'skills' && runtime.id === 'cursor' && item.srcPath) {
+        const skillSrcDir = path.dirname(item.srcPath);
+        const skillDestDir = path.dirname(destPath);
+        for (const sibling of listSiblingRefFiles(skillSrcDir)) {
+          let rawSibling;
+          try {
+            rawSibling = fs.readFileSync(
+              path.join(skillSrcDir, sibling),
+              'utf8',
+            );
+          } catch (err) {
+            perFile.push({
+              kind: 'skill-ref',
+              path: path.join(skillDestDir, sibling),
+              action: 'skipped-foreign',
+              reason: `Could not read sibling ${sibling}: ${err.message}`,
+            });
+            continue;
+          }
+          const siblingDest = path.join(skillDestDir, sibling);
+          const siblingWrite = writeFingerprinted(
+            siblingDest,
+            fingerprintSiblingRef(rawSibling),
+            dryRun,
+          );
+          perFile.push({
+            kind: 'skill-ref',
+            path: siblingDest,
+            action: siblingWrite.action,
+            ...(siblingWrite.reason ? { reason: siblingWrite.reason } : {}),
+          });
+        }
+      }
     }
   }
 
@@ -489,7 +583,45 @@ function uninstallMultiArtifact(runtime, configDir, dryRun, opts) {
 
       // If we removed a SKILL.md, remember to trim its now-empty parent.
       if (kind.kind === 'skills') {
-        skillDirsToTrim.push(path.dirname(destPath));
+        const skillDestDir = path.dirname(destPath);
+        skillDirsToTrim.push(skillDestDir);
+
+        // Batch H6: symmetric cleanup for the sibling reference files the
+        // cursor install carries alongside SKILL.md. Remove only the
+        // plugin-owned siblings so a now-empty dir can be trimmed below;
+        // user-authored siblings are left in place (foreign-file discipline).
+        if (runtime.id === 'cursor') {
+          for (const sibling of listSiblingRefFiles(skillDestDir)) {
+            const siblingPath = path.join(skillDestDir, sibling);
+            let siblingContent;
+            try {
+              siblingContent = fs.readFileSync(siblingPath, 'utf8');
+            } catch (err) {
+              perFile.push({
+                kind: 'skill-ref',
+                path: siblingPath,
+                action: 'skipped-foreign',
+                reason: `Could not read sibling ${sibling}: ${err.message}`,
+              });
+              continue;
+            }
+            if (!isPluginOwned(siblingContent)) {
+              perFile.push({
+                kind: 'skill-ref',
+                path: siblingPath,
+                action: 'skipped-foreign',
+                reason: `Existing ${sibling} was not authored by this plugin; not removing.`,
+              });
+              continue;
+            }
+            if (!dryRun) fs.unlinkSync(siblingPath);
+            perFile.push({
+              kind: 'skill-ref',
+              path: siblingPath,
+              action: 'removed',
+            });
+          }
+        }
       }
     }
   }