@hegemonart/get-design-done 1.28.0 → 1.28.5

package/skills/bandit-status/SKILL.md

@@ -9,88 +9,69 @@ tools: Read, Bash
 
 ## Role
 
-You are a deterministic, read-only diagnostic skill. You do not spawn agents and do not modify the bandit posterior. You read `.design/telemetry/posterior.json` (the path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH` constant), aggregate per-`(agent, bin, delegate, tier)` arm state, and emit a single Markdown table summarizing the posterior. The user runs this when they want to inspect bandit decisions without touching the posterior.
-
-Strictly read-only per Phase 27.5 D-11. To reset the posterior, use `/gdd:bandit-reset` from Phase 23.5.
+You are a deterministic, read-only diagnostic skill. You do not spawn agents and do not modify the posterior. You read `.design/telemetry/posterior.json` (path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`), aggregate per-`(agent, bin, delegate, tier)` arm state, and emit a single Markdown table. Read-only per Phase 27.5 D-11 — to reset, use `/gdd:bandit-reset` (Phase 23.5). See `./reference/bandit-integration.md` for setup, interpretation, and convergence guidance.
 
 ## Invocation Contract
 
-- **Input**: none. The skill takes no arguments.
-- **Output**: a Markdown bandit-status table to stdout. No JSON wrapper. The table is the entire output.
+- **Input**: none.
+- **Output**: a Markdown bandit-status table to stdout. The table is the entire output.
 
 ## Procedure
 
 ### 1. Locate the posterior file
 
-Read `.design/telemetry/posterior.json`. If the file does not exist:
-
-- Emit the empty-state message:
-
-  ```
-  ## Bandit Posterior Snapshot
-
-  No posterior data yet — run a few pipeline cycles with `adaptive_mode: full` first.
-
-  No posterior data found at `.design/telemetry/posterior.json`.
+Read `.design/telemetry/posterior.json`. Missing → emit empty-state message:
 
-  Possible reasons:
-  - `adaptive_mode` is `static` or `hedge` (bandit is silent — see `.design/budget.json` `adaptive_mode` setting).
-  - No spawns have fired since Phase 27.5 wiring landed.
-  - Posterior was cleared via `/gdd:bandit-reset`.
+```
+## Bandit Posterior Snapshot
 
-  See `reference/bandit-integration.md` for setup guidance.
-  ```
+No posterior data yet — run a few pipeline cycles with `adaptive_mode: full` first.
 
-- Skip to Section 4 (Record).
+No posterior data found at `.design/telemetry/posterior.json`.
 
-### 2. Parse the posterior
-
-Parse the file as JSON. If parsing fails (truncated/corrupted file), emit:
+Possible reasons:
+- `adaptive_mode` is `static` or `hedge` (bandit silent — see `.design/budget.json`).
+- No spawns have fired since Phase 27.5 wiring landed.
+- Posterior was cleared via `/gdd:bandit-reset`.
 
+See `reference/bandit-integration.md` for setup guidance.
 ```
-## Bandit Posterior Snapshot
 
-Posterior file at `.design/telemetry/posterior.json` exists but is unparseable (truncated or corrupted).
+Skip to Section 4 (Record). Parse failure (truncated/corrupted) → emit `Posterior file exists but is unparseable. Run /gdd:bandit-reset to start fresh, or restore from a backup.`
 
-Run `/gdd:bandit-reset` to start fresh, or restore from a backup.
-```
+### 2. Parse the posterior
 
-The posterior schema is:
+Schema:
 
 ```json
 {
   "schema_version": "1.0.0",
-  "generated_at": "<ISO timestamp>",
-  "arms": [
-    { "agent": "...", "bin": "...", "tier": "...", "delegate": "...", "alpha": N, "beta": N, "last_used": "...", "count": N }
-  ]
+  "generated_at": "<ISO>",
+  "arms": [{ "agent": "...", "bin": "...", "tier": "...", "delegate": "...", "alpha": N, "beta": N, "last_used": "...", "count": N }]
 }
 ```
 
-The `delegate` field is optional — when absent, the arm is the Phase 23.5 legacy slice (equivalent to `delegate: 'none'`). The status output renders `delegate: '-'` for legacy arms to distinguish them visually from explicit `'none'` arms.
+The `delegate` field is optional — absent = Phase 23.5 legacy slice (rendered as `-` in the table).
 
 ### 3. Render the table
 
-Compute per arm:
-
-- `mean = alpha / (alpha + beta)` (rounded to 3 decimals)
-- `stddev = sqrt(alpha * beta / ((alpha + beta)^2 * (alpha + beta + 1)))` (rounded to 3 decimals)
+Compute per arm: `mean = alpha / (alpha + beta)` (3 decimals), `stddev = sqrt(alpha*beta / ((alpha+beta)^2 * (alpha+beta+1)))` (3 decimals).
 
-Sort arms by `(agent ascending, bin ascending, delegate ascending where '-' sorts first, tier ascending where opus < sonnet < haiku is the canonical tier ordering, last_used descending tiebreaker)`. Group rows by agent for readability.
+Sort by `(agent ASC, bin ASC, delegate ASC where '-' first, tier ASC opus<sonnet<haiku, last_used DESC)`. Group by agent for readability.
 
 Emit:
 
 ```
 ## Bandit Posterior Snapshot
 
-Per-(agent, bin, delegate, tier) posterior state. Read-only — to reset the posterior, use `/gdd:bandit-reset` (Phase 23.5).
+Per-(agent, bin, delegate, tier) posterior state. Read-only — to reset use `/gdd:bandit-reset` (Phase 23.5).
 
 Posterior file: `.design/telemetry/posterior.json` (last updated: <generated_at>)
 Total arms: <count>
 
-| Agent           | Bin    | Delegate | Tier   | Alpha | Beta  | Mean  | Stddev | Count | Last Used            |
-|-----------------|--------|----------|--------|-------|-------|-------|--------|-------|----------------------|
-| <agent>         | <bin>  | <deleg>  | <tier> | <a>   | <b>   | <m>   | <s>    | <c>   | <last_used or '-'>   |
+| Agent | Bin | Delegate | Tier | Alpha | Beta | Mean | Stddev | Count | Last Used |
+|-------|-----|----------|------|-------|------|------|--------|-------|-----------|
+| ...   | ... | ...      | ...  | ...   | ...  | ...  | ...    | ...   | ...       |
 
 > Mean = alpha / (alpha + beta). Stddev = sqrt(alpha*beta / ((alpha+beta)^2 * (alpha+beta+1))).
 > Delegate '-' = Phase 23.5 legacy slice (equivalent to 'none').
@@ -98,32 +79,16 @@ Total arms: <count>
 > Read-only — use `/gdd:bandit-reset` to clear posterior state.
 ```
 
-Format numbers to fixed precision: alpha/beta to 2 decimals, mean/stddev to 3 decimals, count as integer, last_used truncated to the minute precision (`YYYY-MM-DDTHH:MM`).
+Precision: alpha/beta 2 decimals; mean/stddev 3 decimals; count integer; `last_used` truncated to minute (`YYYY-MM-DDTHH:MM`); null `last_used` renders `-`.
 
-When `last_used` is null (arm exists but never selected — possible if the arm was created by `ensureArm` without a subsequent `pull`), render `-` in the Last Used column.
-
-After the table, surface a brief best-arm summary per `(agent, bin)` slice — for each unique `(agent, bin)` pair, identify the arm with the highest `mean` (tie-broken by `count` descending) and display it as the "best-arm" recommendation. This helps the operator answer "why did the bandit pick tier X?" at a glance.
+After the table, surface a per-`(agent, bin)` best-arm summary: for each unique pair, identify highest-mean arm (tie-broken by `count` DESC) — answers "why did the bandit pick tier X?" at a glance.
 
 ### 4. Record
 
-After execution, append one JSONL line to `.design/skill-records.jsonl`:
-
-```json
-{"skill": "gdd-bandit-status", "ts": "<ISO timestamp>", "arms_seen": <count>, "posterior_present": <bool>}
-```
-
-The skill writes ONLY to `.design/skill-records.jsonl` for telemetry purposes. It never touches `.design/telemetry/posterior.json`.
+Append one JSONL line to `.design/skill-records.jsonl`: `{"skill":"gdd-bandit-status","ts":"<ISO>","arms_seen":<count>,"posterior_present":<bool>}`. Skill writes ONLY to skill-records.jsonl (telemetry); never touches the posterior.
 
 ## Cross-references
 
-- `scripts/lib/bandit-router.cjs` (Phase 23.5) — posterior shape, `DEFAULT_POSTERIOR_PATH` constant, `loadPosterior()` helper.
-- `scripts/lib/bandit-router/integration.cjs` (Phase 27.5-01) — production-integration shim.
-- `hooks/budget-enforcer.ts` (Phase 27.5-02) — bandit consultation site.
-- `scripts/lib/session-runner/index.ts` (Phase 27.5-03) — outcome recording site.
-- `scripts/lib/bandit-arbitrage.cjs` (Phase 27.5-04) — automated stale-frontmatter analysis.
-- `reference/bandit-integration.md` (Phase 27.5-06) — operator guide.
-- `/gdd:bandit-reset` (Phase 23.5) — the ONLY surface that mutates the posterior.
-
-## Record
-
-See Section 4 above.
+- `./reference/bandit-integration.md` — operator guide; interpretation patterns.
+- `scripts/lib/bandit-router.cjs` (Phase 23.5) — posterior shape, `DEFAULT_POSTERIOR_PATH`, `loadPosterior()`.
+- `scripts/lib/bandit-router/integration.cjs` (27.5-01), `hooks/budget-enforcer.ts` (27.5-02), `scripts/lib/session-runner/index.ts` (27.5-03), `scripts/lib/bandit-arbitrage.cjs` (27.5-04), `/gdd:bandit-reset` (Phase 23.5) — only surface that mutates the posterior.

package/skills/benchmark/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-benchmark
-description: Harvest and synthesize per-component design benchmarks from 18 design systems. Produces canonical specs at reference/components/<name>.md.
+description: "Harvest and synthesize per-component design benchmarks from 18 design systems and produce canonical component specs at `reference/components/<name>.md`. Use when adding a new component spec, running a benchmark wave, listing corpus coverage, or refreshing a spec after a design-system version bump."
 argument-hint: "<component> | --wave <N> | --list | --refresh <component>"
 tools: Read, Write, Bash, Grep, Glob, Task, WebFetch
 ---
@@ -8,7 +8,9 @@ tools: Read, Write, Bash, Grep, Glob, Task, WebFetch
 # /gdd:benchmark
 
 Harvest per-component design knowledge from 18 design systems and synthesize canonical
-specs at `reference/components/<name>.md`.
+specs at `reference/components/<name>.md`. The 18-source corpus + fallback chain lives in
+`../../connections/design-corpora.md`. Per-skill output discipline + completion-marker
+conventions are at `../../reference/shared-preamble.md#output-contract-reminders`.
 
 ## Invocation Modes
 
@@ -21,49 +23,17 @@ specs at `reference/components/<name>.md`.
 
 ## Single-Component Flow (`/gdd:benchmark <component>`)
 
-1. **Check if spec exists** — `Glob("reference/components/<component>.md")`.
-   If found and `--refresh` was not passed, confirm before overwriting.
-
-2. **Harvest** — spawn `component-benchmark-harvester` with:
-   ```
-   Task("component-benchmark-harvester", """
-   <required_reading>
-   @connections/design-corpora.md
-   </required_reading>
-
-   Harvest design-system excerpts for component: <component>
-   Emit raw harvest to: .planning/benchmarks/raw/<component>.md
-   Consume any relevant content from: .planning/research/impeccable-salvage/
-
-   Acceptance: .planning/benchmarks/raw/<component>.md exists with ≥4 source sections.
-   """)
-   ```
-
-3. **Synthesize** — spawn `component-benchmark-synthesizer` with:
-   ```
-   Task("component-benchmark-synthesizer", """
-   <required_reading>
-   @.planning/benchmarks/raw/<component>.md
-   @reference/components/TEMPLATE.md
-   @reference/anti-patterns.md
-   </required_reading>
-
-   Synthesize the raw harvest into a canonical spec.
-   Output: reference/components/<component>.md
-   Update: reference/components/README.md (add entry in correct category)
-
-   Acceptance: spec exists, ≤350 lines, cites ≥4 systems, has TEMPLATE.md sections,
-   WAI-ARIA keyboard contract present, failing-example block present.
-   """)
-   ```
+1. **Check if spec exists** — `Glob("reference/components/<component>.md")`. If found and `--refresh` was not passed, confirm before overwriting.
+
+2. **Harvest** — spawn `component-benchmark-harvester` with required-reading `@connections/design-corpora.md`, target component, raw-output path `.planning/benchmarks/raw/<component>.md`, and a salvage hint to `.planning/research/impeccable-salvage/`. Acceptance: raw harvest exists with ≥4 source sections.
+
+3. **Synthesize** — spawn `component-benchmark-synthesizer` with required-reading `@.planning/benchmarks/raw/<component>.md`, `@reference/components/TEMPLATE.md`, `@reference/anti-patterns.md`. Output: `reference/components/<component>.md`. Also update `reference/components/README.md` (add entry in correct category). Acceptance: spec ≤350 lines, cites ≥4 systems, follows `TEMPLATE.md` sections, has a WAI-ARIA keyboard contract + a failing-example block.
 
 4. **Report** — print spec path, line count, systems cited.
 
 ## Wave Mode (`/gdd:benchmark --wave <N>`)
 
-Read the wave definition from `reference/components/README.md` and run each component
-in the wave sequentially (not parallel — each harvest is network-bound and the raw files
-are large).
+Read the wave definition from `reference/components/README.md` and run each component sequentially (not parallel — each harvest is network-bound and the raw files are large).
 
 | Wave | Components |
 |------|-----------|
@@ -74,27 +44,15 @@ Print progress per component: `[N/total] harvesting <component>…`
 
 ## List Mode (`/gdd:benchmark --list`)
 
-Read `reference/components/README.md` and diff against `reference/components/*.md` files.
-Print a table:
-
-```
-Component        Status   Wave  Lines
-button           ✓        1     248
-input            ✓        1     312
-select-combobox  ✓        1     295
-...
-toast            pending  3     —
-```
+Read `reference/components/README.md` and diff against `reference/components/*.md` files. Print a table with columns: Component, Status, Wave, Lines.
 
 ## Refresh Mode (`/gdd:benchmark --refresh <component>`)
 
-Same as single-component flow but skips the "already exists" guard. Use when a design
-system ships a breaking update to a component's spec.
+Same as single-component flow but skips the "already exists" guard. Use when a design system ships a breaking update to a component's spec.
 
 ## Source List
 
-`connections/design-corpora.md` — 18 design systems with canonical URLs, licensing, and
-fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
+`../../connections/design-corpora.md` — 18 design systems with canonical URLs, licensing, and fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
 
 ## Output Artifacts
 
@@ -103,3 +61,5 @@ fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
 | `.planning/benchmarks/raw/<component>.md` | Raw multi-source harvest (input only) |
 | `reference/components/<component>.md` | Canonical spec (distributed with plugin) |
 | `reference/components/README.md` | Corpus index (updated by synthesizer) |
+
+## BENCHMARK COMPLETE

package/skills/brief/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-brief
-description: "Design intake — captures problem statement, audience, constraints, success metrics, and scope into .design/BRIEF.md (Stage 1 of 5)"
+description: "Stage 1 of 5 design intake that captures problem statement, audience, constraints, success metrics, and scope into .design/BRIEF.md, and bootstraps .design/STATE.md if missing. Use when starting a new design cycle and before /gdd:explore."
 argument-hint: "[--re-brief to redo intake on existing project]"
 tools: Read, Write, AskUserQuestion, mcp__gdd_state__frontmatter_update, mcp__gdd_state__set_status, mcp__gdd_state__update_progress, mcp__gdd_state__get
 ---
@@ -72,6 +72,17 @@ With `.design/STATE.md` seeded from the template:
 
 Do NOT call `mcp__gdd_state__transition_stage` from brief — explore calls it on entry, keeping the transition atomic with the stage that owns the new state.
 
+## Step 6 — Inline glossary (CONTEXT.md) + ADR pointer
+
+When a fuzzy phrase is resolved or a new domain concept is named during the briefing
+interview: write to `./CONTEXT.md` IMMEDIATELY per `./../../reference/context-md-format.md`
+(H2 heading + body; lazy-create on first term; no batching). Glossary entries compound
+across cycles — token savings + naming consistency.
+
+Project-shaping decisions surfaced in briefing can be promoted to an ADR — see
+`./../../reference/adr-format.md` for the 3-criteria gate (hard-to-reverse AND
+surprising-without-context AND real-tradeoff). Routine choices stay in STATE.md.
+
 ## After Writing
 
 ```

package/skills/cache-manager/SKILL.md

@@ -3,6 +3,7 @@ name: gdd-cache-manager
 description: "Maintains .design/cache-manifest.json for Layer B explicit cache per D-08. Computes deterministic SHA-256 input-hash from (agent-path + sorted-input-file-paths + input-content-hashes). On spawn: lookup key → return cached blob if within TTL, else miss. On completion: write result + TTL. Consulted by hooks/budget-enforcer.js before every Agent spawn."
 user-invocable: false
 tools: Read, Bash, Write
+disable-model-invocation: true
 ---
 
 # gdd-cache-manager
@@ -37,60 +38,7 @@ You are the deterministic cache-key computer and cache-manifest writer for the o
 
 ## Deterministic Input-Hash Algorithm
 
-The canonical reference implementation (the single source of truth; `hooks/budget-enforcer.js` will import the same primitive via a shared helper in Plan 10.1-05 when telemetry lands):
-
-```js
-// Deterministic cache-key primitive (reference implementation)
-// hash = SHA-256(
-//   agent_path + "\n" +
-//   sorted(input_file_paths).join("\n") + "\n" +
-//   sorted(input_file_paths)
-//     .map(p => sha256(readFileSync(p, "utf8")))
-//     .join("\n")
-// )
-const crypto = require('crypto');
-const fs = require('fs');
-
-function sha256Hex(s) {
-  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
-}
-
-function computeInputHash(agentPath, inputFilePaths) {
-  const sortedPaths = [...inputFilePaths].sort();
-  const contentHashes = sortedPaths.map(p => {
-    try { return sha256Hex(fs.readFileSync(p, 'utf8')); }
-    catch { return 'MISSING'; }
-  });
-  const canonical = [
-    agentPath,
-    sortedPaths.join('\n'),
-    contentHashes.join('\n')
-  ].join('\n');
-  return sha256Hex(canonical);
-}
-```
-
-Notes for maintainers:
-
-- **Sorted-unique paths** — ordering must be stable; caller is expected to de-duplicate. If the same path appears twice the hash still matches as long as caller pre-dedupes before invoking.
-- **Missing file** — the string `MISSING` is used in place of the content hash so a missing dependency doesn't silently collide with an empty file (empty file's SHA-256 is `e3b0c44...`). Missing-file hashes naturally miss on the next read because the real file has a different content hash.
-- **Agent-path** — agents changing their own body (role, tools, output contract) invalidate all their cache entries automatically because the agent file's content is not hashed; but the `agent_path` string is concatenated. Upgrading agents between versions naturally busts the cache only when the path changes. Plan 10.1-04 (shared preamble extraction) is expected to slightly adjust agent bodies — consumers should treat the first post-10.1 run as a full cache miss, which is the intended behavior.
-
-## Manifest Shape
-
-See `reference/config-schema.md` §.design/cache-manifest.json Schema (Phase 10.1) for the authoritative schema. Keyed object, flat SHA-256 hex keys. Example:
-
-```json
-{
-  "a3f1e...": {
-    "agent": "design-verifier",
-    "result": "<base64-or-path>",
-    "written_at": "2026-04-18T12:00:00Z",
-    "ttl_seconds": 3600,
-    "expires_at": "2026-04-18T13:00:00Z"
-  }
-}
-```
+The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper) lives in `./reference/cache-policy.md#deterministic-input-hash-algorithm-layer-b` — it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
 
 ## Integration Points
 
@@ -115,6 +63,4 @@ Per D-09:
 
 ## TTL Semantics
 
-- Default `ttl_seconds` = `.design/budget.json.cache_ttl_seconds` = 3600s (1 hour) per D-10.
-- `expires_at` is computed at write time and stored; readers do not recompute.
-- Lazy cleanup: stale entries are not actively deleted on read (overhead for no benefit in normal operation). A separate reaper is optional and out of v1 scope.
+Default `ttl_seconds` = `.design/budget.json.cache_ttl_seconds` = 3600s (1 hour) per D-10. `expires_at` is computed at write time and stored; readers do not recompute. Stale entries are lazily cleaned on read (no eager reaper in v1). Full TTL discussion: `./reference/cache-policy.md#ttl-semantics-layer-b`.

package/skills/check-update/SKILL.md

@@ -7,91 +7,69 @@ tools: Read, Write, Bash, Task
 
 # /gdd:check-update
 
-**Role:** Manual entry point for the plugin-update checker. The SessionStart hook (`hooks/update-check.sh`) already runs on its own 24h cadence and writes `.design/update-cache.json` + `.design/update-available.md`. This command lets the user inspect / force / dismiss / enrich that state on demand.
+**Role:** Manual entry point for the plugin-update checker. The SessionStart hook (`hooks/update-check.sh`) already runs on its own 24h cadence and writes `.design/update-cache.json` + `.design/update-available.md`. This command lets the user inspect / force / dismiss / enrich that state on demand. See `./reference/heuristics.md` §"Version-cadence" for the off-cadence / preview-suffix handling background.
 
 ## Flags
 
 | Flag | Effect |
-|---|---|
-| *(none)* | Print cached state (latest_tag, delta, is_newer). If the cache is older than 24h, trigger `--refresh` implicitly. |
+|------|--------|
+| *(none)* | Print cached state. If cache is older than 24h, trigger `--refresh` implicitly. |
 | `--refresh` | Invoke `hooks/update-check.sh --refresh` — bypasses the 24h TTL and re-fetches immediately. |
 | `--dismiss` | Write `update_dismissed: "<latest_tag>"` to `.design/config.json` atomically and delete `.design/update-available.md`. Sticky until a newer release ships. |
 | `--prompt` | Spawn `design-update-checker` agent (Haiku) to produce a 3–5-line "what this release changes for you" summary. Does not alter the banner or cache. |
 
-Flags can be combined: `--refresh --prompt` is valid (re-fetch, then enrich). `--dismiss` is the only flag that mutates `.design/config.json`.
+Flags combine: `--refresh --prompt` is valid (re-fetch, then enrich). `--dismiss` is the only flag that mutates `.design/config.json`.
 
 ## Steps
 
-1. **Parse flags.** Detect `--refresh`, `--dismiss`, `--prompt` in `$ARGUMENTS`. Any unknown flag: print `Unknown flag: <flag>` and exit.
+1. **Parse flags.** Detect `--refresh`, `--dismiss`, `--prompt` in `$ARGUMENTS`. Unknown flag → `Unknown flag: <flag>` and exit.
+
+2. **`--refresh` path** (if set):
 
-2. **--refresh path** (if `--refresh` in flags):
-    Run the hot-path hook with the refresh flag:
     ```bash
     bash "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/hooks/update-check.sh" --refresh
     ```
-    This re-fetches `/releases/latest`, rewrites `.design/update-cache.json`, and re-renders `.design/update-available.md` subject to the same state/dismissal gates.
 
-3. **Read cache.** After any optional refresh, read `.design/update-cache.json`. If it does not exist:
-    - Print: `No cache. Network may be unreachable or the hook has not run yet. Try /gdd:check-update --refresh.`
-    - Exit.
+    This re-fetches `/releases/latest`, rewrites `.design/update-cache.json`, and re-renders `.design/update-available.md` subject to state/dismissal gates.
 
-<!-- markdownlint-disable MD025 -->
+3. **Read cache.** After any optional refresh, read `.design/update-cache.json`. If missing: print `No cache. Network may be unreachable or the hook has not run yet. Try /gdd:check-update --refresh.` and exit.
 
-4. **Dismiss path** (if `--dismiss` in flags):
-    Compute new config contents and write atomically. The python heredoc receives CONFIG_PATH and LATEST_TAG via the ENVIRONMENT (env-prefix form — `KEY=VALUE python3 <<PY`), NOT via trailing argv. Passing `python3 -c '...' KEY=VALUE` makes Python treat the assignments as `sys.argv`, which the old draft did incorrectly; env-prefix form is the portable fix.
+4. **`--dismiss` path** (if set): Compute new config contents and write atomically via the env-prefix Python heredoc pattern below. The pattern is load-bearing — passing variables as trailing `KEY=VALUE` argv treats them as `sys.argv`, not `os.environ`. Use env-prefix form only.
 
     ```bash
     CONFIG_PATH=".design/config.json"
     LATEST_TAG="$(grep -E '"latest_tag"' .design/update-cache.json | head -n1 | sed -E 's/.*"latest_tag"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')"
     [ -n "$LATEST_TAG" ] || { echo 'No latest_tag in cache — nothing to dismiss.'; exit 0; }
-
     mkdir -p .design
-
-    # Env-prefix form: CONFIG_PATH and LATEST_TAG are placed into the child process env,
-    # then python3 reads them via os.environ. Heredoc body is flat at column 0 (required —
-    # any leading indentation breaks Python parsing in a heredoc).
     CONFIG_PATH="$CONFIG_PATH" LATEST_TAG="$LATEST_TAG" python3 <<'PY'
-import json, os, sys, tempfile
-
-config_path = os.environ['CONFIG_PATH']
-latest_tag = os.environ['LATEST_TAG']
-
-# Load existing config if present; otherwise start fresh. Preserve every unknown key.
-try:
-    with open(config_path, 'r', encoding='utf-8') as f:
-        data = json.load(f)
-    if not isinstance(data, dict):
-        data = {}
-except (FileNotFoundError, json.JSONDecodeError):
-    data = {}
-
-# Set ONLY the dismissal key — every other pre-existing key is preserved verbatim.
-data['update_dismissed'] = latest_tag
-
-# Atomic write: write to tmp on the SAME filesystem, then os.replace() (POSIX rename(2)).
-target_dir = os.path.dirname(config_path) or '.'
-fd, tmp_path = tempfile.mkstemp(prefix='config.', suffix='.tmp', dir=target_dir)
-try:
-    with os.fdopen(fd, 'w', encoding='utf-8') as f:
-        json.dump(data, f, indent=2)
-        f.write('\n')
-    os.replace(tmp_path, config_path)  # atomic on same filesystem
-except Exception as exc:
+    import json, os, sys, tempfile
+    config_path = os.environ['CONFIG_PATH']
+    latest_tag = os.environ['LATEST_TAG']
     try:
-        os.unlink(tmp_path)
-    except OSError:
-        pass
-    sys.exit(1)
-PY
-
-    # Remove the rendered banner (user dismissed — stop showing it until a newer release ships).
+        with open(config_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+        if not isinstance(data, dict): data = {}
+    except (FileNotFoundError, json.JSONDecodeError): data = {}
+    data['update_dismissed'] = latest_tag
+    target_dir = os.path.dirname(config_path) or '.'
+    fd, tmp_path = tempfile.mkstemp(prefix='config.', suffix='.tmp', dir=target_dir)
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            json.dump(data, f, indent=2); f.write('\n')
+        os.replace(tmp_path, config_path)
+    except Exception:
+        try: os.unlink(tmp_path)
+        except OSError: pass
+        sys.exit(1)
+    PY
     rm -f .design/update-available.md
     echo "Dismissed $LATEST_TAG. The nudge will return when a newer release ships."
     ```
 
-    D-14 atomic-write invariant: `os.replace()` (POSIX `rename(2)`) is atomic on the same filesystem — an interrupted write leaves the original config intact. The `json.load → set single key → json.dump` round-trip guarantees every unknown top-level key (e.g. `model_profile`, `parallelism`) is preserved verbatim.
+    D-14 atomic-write invariant: `os.replace()` (POSIX `rename(2)`) is atomic on the same filesystem. The `json.load → set single key → json.dump` round-trip preserves every unknown top-level key (e.g. `model_profile`, `parallelism`) verbatim.
+
+5. **Print default state** (always, unless exited early):
 
-5. **Print default state** (always, unless the skill exited early):
     ```
     ━━━ /gdd:check-update ━━━
     Current:   v<X.Y.Z>
@@ -101,35 +79,20 @@ PY
     Dismissed: <tag or "no">
     ━━━━━━━━━━━━━━━━━━━━━━━━━━
     ```
-    Parse these fields from `.design/update-cache.json` using `grep + sed` (no jq dependency). Read dismissal from `.design/config.json` via the same pattern as hooks/update-check.sh:
-    ```bash
-    [ -f .design/config.json ] && grep -E '"update_dismissed"' .design/config.json | sed -E 's/.*"update_dismissed"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/'
-    ```
-
-6. **--prompt path** (if `--prompt` in flags):
-    Spawn the `design-update-checker` agent via the Task tool. Pass as context:
-    - `current_tag` — from `.design/update-cache.json`
-    - `latest_tag` — from `.design/update-cache.json`
-    - `delta` — from `.design/update-cache.json`
-    - `release_body` — the `changelog_excerpt` from the cache (may be pre-truncated to 500 chars; that's fine — the agent knows)
 
-    Display the agent's inline response verbatim below the state banner. The agent ends with `## UPDATE-CHECKER COMPLETE` — the skill's own completion marker (below) is the final line.
+    Parse fields from `.design/update-cache.json` via `grep + sed` (no jq dep). Read dismissal from `.design/config.json` via the same pattern as `hooks/update-check.sh`.
 
-## Defaults
-
-- No flags → behave as: `--refresh (only if cache >24h old) → print state`. Silent no-op if cache is fresh and there is no newer version.
+6. **`--prompt` path** (if set): Spawn `design-update-checker` via Task tool with context `{current_tag, latest_tag, delta, release_body}`. Display response verbatim below the banner. Agent ends with `## UPDATE-CHECKER COMPLETE`.
 
 ## Do Not
 
-- Do not fetch from GitHub in this skill directly — always go through `hooks/update-check.sh --refresh` so the caching + state-guard + dismissal logic stays in one place.
-- Do not modify `.design/update-available.md` except to delete it on `--dismiss`. The hot-path hook is the only writer of that banner (D-06).
-- Do not rewrite `.design/config.json` wholesale — the atomic python rewrite preserves every unknown key (D-14).
-- Do not pass variables to the python heredoc via trailing `KEY=VALUE` argv — that assigns to `sys.argv`, not `os.environ`. Use env-prefix form only.
+- Do not fetch from GitHub directly — always go through `hooks/update-check.sh --refresh` so caching + state-guard + dismissal logic stays in one place.
+- Do not modify `.design/update-available.md` except to delete on `--dismiss`.
+- Do not rewrite `.design/config.json` wholesale — the atomic Python rewrite preserves every unknown key (D-14).
+- Do not pass variables to the Python heredoc via trailing `KEY=VALUE` argv — env-prefix form only.
 
 ## Completion marker
 
-Last line of output:
-
 ```
 ## CHECK-UPDATE COMPLETE
 ```