@tyroneross/build-loop 0.36.1 → 0.43.0

package/skills/debugging-memory/references/search.md

@@ -1,140 +1,52 @@
-<!-- PROVENANCE: op=search reference for `build-loop:debugging-memory` (ADR-01 op-routing). Folded from skills/debugging/memory/SKILL.md (former skill name build-loop:debugging-memory-search, v0.1.0) on 2026-07-02, pool-consolidation Inc 5. Drift-check vs upstream retired (native, adapted; no canonical upstream). Former provenance for record: source=claude-code-debugger/skills/debugging-memory/SKILL.md source_hash=5c4ee5ada781107e7def92abeca4d51fc0efc61700f7cf43e948da34f4c0681d -->
+<!-- PROVENANCE: op=search reference for build-loop:debugging-memory. Native core refreshed from @tyroneross/claude-code-debugger v1.9.0 at 74cc2cc96ce7c212a81d41b85143dc1fc9094bc3 on 2026-08-25. -->
 
 <!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
 
-# Debugging Memory Workflow (Native, Sourced)
+# Native Debugging Memory Search
 
-Memory-first debugging. Core principle: **never solve the same bug twice**. Native to build-loop; initially adapted from the debugger workflow lineage. Search local `.build-loop/issues/` first, then use standalone Coding Debugger for cross-project memory only when that plugin is installed.
+Build Loop owns this debugger. It does not require the standalone Coding Debugger package or MCP server. Search and store both use the project's structured `.claude/memory/` root.
 
-> **Op-routing note**: this is the `op: "search"` reference for `build-loop:debugging-memory` — the memory LOOKUP step. Callers invoke `Skill("build-loop:debugging-memory") with input { op: "search", symptom, domain? }`; this file holds the lookup procedure the workflow delegates to (ADR-01).
+## Invoke
 
-## When to Activate
+Before investigating a bug, run:
 
-- Phase 1 Assess: pull recent project incident context for orientation (`list-recent` intent)
-- Phase 4 Review-B Validate: on every criterion failure with an error-like signal — read logs first, synthesize symptom, search memory
-- Phase 5 Iterate: at the start of every Iterate attempt, re-search with the new symptom (failure may have shifted shape after a fix)
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/build-loop-debugger.js" search "<symptom>" \
+  --threshold 0.6 --workdir "$PWD"
+```
 
-## Memory-First Approach
+The command returns JSON with `memory_root`, `debugger_core_version`, and a verdict:
 
-Before investigating any bug, check debugging memory with the symptom description.
+- `KNOWN_FIX`: direct-apply only if the strict gate passes.
+- `LIKELY_MATCH`: use the incident as a hypothesis and run the normal fix loop.
+- `WEAK_SIGNAL`: consider the result, but investigate fresh.
+- `NO_MATCH`: investigate fresh and store the verified result afterward.
 
-The search returns a **verdict** with matching incidents and patterns when structured memory is available. File-backed fallback returns a degraded local verdict with the same action shape.
+## Strict direct-apply gate
 
-**Verdict-based decision tree:**
+All three checks must pass:
 
-1. **KNOWN_FIX**: Apply the documented fix directly only when the strict direct-apply gate (below) passes; otherwise adapt the prior incident as a hypothesis and route to the standard fix flow
-2. **LIKELY_MATCH**: Review the past incident, use it as a starting point — never direct-apply
-3. **WEAK_SIGNAL**: Consider loosely related incidents, but investigate fresh
-4. **NO_MATCH**: Proceed with standard debugging via `build-loop:debug-loop`, then document the solution after
+1. At least one recorded file exists at the same relative path.
+2. Recorded dependency versions match the current project within minor version. Missing version evidence fails this check.
+3. A second signal matches: error class, callsite, or a corroborating log entry.
 
-### Direct-apply gate (KNOWN_FIX only)
+React-hook, performance, and "increase a limit" fixes never direct-apply because they are context-sensitive.
 
-All three must pass — otherwise downgrade to adapted-plan routing and record `direct_apply_blocked_by`:
+## Retrieval depth
 
-1. **file_match**: at least one file in the prior incident's `files_changed` exists in current repo at same relative path
-2. **version_match**: dependency versions in the prior incident match current within minor (semver). If the prior incident's `tags` include a version, compare it to current `package.json`/`requirements.txt`/etc.
-3. **second_signal**: at least one secondary signal — same error class, same callsite line range, or same component layer
+The initial search returns compact matches. Load a full incident only when needed:
 
-Skip direct-apply for any pattern with category `react-hooks`, `performance`, or anything where the fix is "increase value X" — those are context-sensitive.
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/build-loop-debugger.js" detail <INC_ID> --workdir "$PWD"
+```
 
-## Progressive Depth Retrieval
+Announce the search and report whether it found a match. Store the verified outcome through the same native command described in `store.md`.
 
-1. **Initial search**: local build-loop incident lookup; if standalone Coding Debugger is available, use its `search` tool for cross-project matches
-2. **Drill down**: read the local issue file or, for Coding Debugger matches, use `detail` with the ID
-3. **Outcome tracking**: for Coding Debugger matches, use `outcome` to record whether the fix worked
+## Lifecycle
 
-## Visibility
+- Phase 1 Assess: search for relevant project incidents.
+- Review-B failure: search the exact current error before changing code.
+- Each Iterate attempt: search again if the symptom changes.
+- Review-F: store every newly resolved, verified incident.
 
-When this skill activates, always announce it to the user:
-
-1. **Before searching**: "Checking debugging memory for similar issues..."
-2. **After search**: "Found X matching incident(s) from past debugging sessions" or "No matching incidents — starting fresh investigation"
-
-## Deep Investigation Mode
-
-For non-trivial issues, escalate to the `build-loop:debug-loop` skill. Trigger is the **verdict category**, not a numeric confidence score:
-
-- **`KNOWN_FIX`** → apply directly, skip the loop
-- **`LIKELY_MATCH`** → enter debug loop (past incidents need verification against current context)
-- **`WEAK_SIGNAL`** → enter debug loop (loosely related, fresh investigation needed)
-- **`NO_MATCH`** → enter debug loop (no prior knowledge)
-
-Also enter the debug loop when:
-- Initial diagnosis feels superficial
-- Previous fix didn't hold
-- User explicitly asks for root-cause analysis
-- Multiple symptoms suggest a shared cause
-
-## Basic Steps (simple, clear-cut issues)
-
-1. **Reproduce** — exact steps, environmental factors, minimal repro
-2. **Isolate** — binary search recent changes, disable components, check logs
-3. **Diagnose** — trace execution, examine state, identify offending code
-4. **Fix** — minimal, targeted, no side effects
-5. **Verify** — original repro, related tests, regression check
-
-## Incident Documentation
-
-After fixing a bug, store via `build-loop:debugging-memory` `{op:"store"}`. Required fields: `symptom`, `root_cause`, `fix`. Optional: `category`, `tags`, `files_changed`, `file`.
-
-## Quality Indicators
-
-The memory system scores incidents on:
-- Root cause analysis depth (30%)
-- Fix documentation completeness (30%)
-- Verification status (20%)
-- Tags and metadata (20%)
-
-Target 75%+ quality score for effective future retrieval.
-
-## Tagging Strategy
-
-- Technology: `react`, `typescript`, `api`, `database`
-- Category: `logic`, `config`, `dependency`, `performance`
-- Symptom type: `crash`, `render`, `timeout`, `validation`
-
-## Pattern Recognition
-
-The memory system extracts patterns when 3+ similar incidents exist. Patterns have higher reliability than individual incidents. When a pattern matches, trust the solution template (90%+ confidence), apply the recommended approach, note caveats.
-
-## Optional Coding Debugger Tools
-
-| Tool | Purpose |
-|------|---------|
-| `search` | Search memory for similar bugs (returns verdict) |
-| `store` | Store a new debugging incident |
-| `detail` | Get full incident or pattern details |
-| `status` | Show memory statistics |
-| `list` | List recent incidents |
-| `patterns` | List known fix patterns |
-| `outcome` | Record whether a fix worked |
-
-Use these only when standalone Coding Debugger is installed. Build-loop does not register these MCP tools itself.
-
-## Review-F Outcome Feedback
-
-Closes the memory-first gate's feedback loop. Both required:
-
-- For each newly resolved Review-B/Iterate failure: invoke `build-loop:debugging-memory` `{op:"store"}` with `{symptom, root_cause, fix, tags: ["build-loop", project, layer], files}`
-- For each Review-B memory gate where standalone Coding Debugger supplied a prior `KNOWN_FIX` or `LIKELY_MATCH`: invoke its `outcome` tool with `{incident_id, result: "worked"|"failed"|"modified", notes}` — this trains the optional verdict classifier
-
-Skipping `outcome` means the optional verdict classifier never improves.
-
-## Subagent Integration
-
-When debugging involves subagents:
-
-1. **Pre-query memory once** through `build-loop:debugging-memory` before spawning agents
-2. **Distribute context** — each agent gets relevant subset
-3. **Aggregate findings** — collect insights from all agents
-4. **Store unified incident** — single `build-loop:debugging-memory` `{op:"store"}` call to document combined diagnosis
-
-Subagents do not inherit Skill or MCP access — pre-load context into their prompt.
-
-## Sibling Skills
-
-- `build-loop:debugging-memory` `{op:"store"}` — write incident after fix
-- `build-loop:debugging-memory` `{op:"assess"}` — parallel domain assessment for multi-domain symptoms
-- `build-loop:debug-loop` — iterative root-cause analysis with causal-tree investigation
-
-*Source: adapted from the debugger workflow lineage and maintained as a build-loop-native skill. Drift-checked by `build-loop:sync-skills`.*
+`.build-loop/issues/` remains the executable/open-issue lane. Do not write resolved debugger history there.

package/skills/debugging-memory/references/store.md

@@ -1,145 +1,51 @@
-<!-- PROVENANCE: op=store reference for `build-loop:debugging-memory` (ADR-01 op-routing). Folded from skills/debugging/store/SKILL.md (former skill name build-loop:debugging-store, v0.1.0) on 2026-07-02, pool-consolidation Inc 5. Drift-check vs upstream retired (native, adapted; no canonical upstream). Former provenance for record: source=claude-code-debugger/skills/debugging-memory/SKILL.md §Incident-Documentation source_hash=5c4ee5ada781107e7def92abeca4d51fc0efc61700f7cf43e948da34f4c0681d -->
+<!-- PROVENANCE: op=store reference for build-loop:debugging-memory. Native core refreshed from @tyroneross/claude-code-debugger v1.9.0 at 74cc2cc96ce7c212a81d41b85143dc1fc9094bc3 on 2026-08-25. -->
 
 <!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
 
-# Debugging Incident Storage
+# Native Debugging Incident Storage
 
-Persist a fixed bug to debugging memory so future builds can recognize recurrence. Native to build-loop; initially adapted from the §"Incident Documentation" workflow in the debugger lineage.
+Persist verified fixes to the same `.claude/memory/` store searched by Build Loop's native debugger.
 
-> **Divergence note**: the standalone debugger does not ship a discrete `store` SKILL.md. Build-loop keeps storage as a native skill because Review-F needs deterministic local persistence even when no MCP server exists.
+## Required payload
 
-## When to Activate
+Create a temporary JSON file with:
 
-- Phase 4 Review-F Report: for each Review-B/Iterate failure newly resolved this build, store the incident
-- After any `build-loop:debug-loop` run that produced a verified fix
-- User asks "save this fix", "remember this bug"
-
-## Native Path — Build-Loop Incident Note
-
-Write one incident note per resolved failure:
-
-```bash
-mkdir -p .build-loop/issues
-```
-
-Path:
-
-```text
-.build-loop/issues/YYYY-MM-DD-<short-slug>.md
-```
-
-Template:
-
-```markdown
-# <one-line symptom>
-
-**Symptom**: <error string, failing command, or observed behavior>
-**Root cause**: <technical cause plus first controllable system cause>
-**Fix**: <what changed and why>
-**Verification**: <commands, tests, or observed proof>
-**Files**: <paths touched>
-**Tags**: build-loop, <project>, <layer>, <framework>, <symptom-type>
-**RCA framework**: <5 Whys | causal tree | fishbone | Kepner-Tregoe | differential diagnosis | falsification>
-```
-
-**Required**: `symptom`, `root_cause`, `fix`, `verification`. Everything else improves future retrieval.
-
-## Optional Mirror — Coding Debugger MCP
-
-If standalone Coding Debugger is installed and available, mirror the same incident:
-
-```
-mcp__plugin_coding_debugger__store({
-  symptom: "user-facing description (≤200 chars, preserves error type/file/key phrase)",
-  root_cause: "technical explanation of why",
-  fix: "what was changed",
-  category: "logic|config|dependency|performance|react-hooks",
-  tags: ["build-loop", "<project>", "<layer>", "<framework>", "<symptom-type>"],
-  files_changed: ["path/to/file1.ts", "path/to/file2.ts"],
-  file: "path/to/primary/problematic/file.ts"
-})
-```
-
-Mirror failure is not a build failure. Report it as "local incident stored; Coding Debugger mirror unavailable."
-
-## Tag Discipline
-
-Always include:
-- `"build-loop"` — distinguishes build-orchestrator origins from manual `/build-loop:debug` runs
-- Project name (lowercase, slugified)
-- Layer (`frontend`, `backend`, `database`, `infra`, `external`)
-
-Add as relevant:
-- Technology: `react`, `typescript`, `python`, `api`, `prisma`
-- Category: `logic`, `config`, `dependency`, `performance`
-- Symptom type: `crash`, `render`, `timeout`, `validation`
-
-## Quality Score Targets
-
-The memory system scores stored incidents:
-- Root cause depth (30%)
-- Fix documentation completeness (30%)
-- Verification status (20%)
-- Tags and metadata (20%)
-
-Target 75%+. Score below 75% means future searches won't surface this incident reliably — pad the description and tags before storing.
-
-## JSON Compatibility Fallback
-
-If a downstream process requires JSON, write a compatibility copy after the native note:
-
-**Step 1: Generate incident ID**
-```
-INC_<CATEGORY>_YYYYMMDD_HHMMSS_xxxx
-```
-where `xxxx` is 4 random alphanumeric characters. Example: `INC_API_20260403_143052_a7b2`.
-
-**Step 2: Ensure directory exists**
-```bash
-mkdir -p .build-loop/debugging/incidents
-```
-
-**Step 3: Write the JSON**
 ```json
 {
-  "incident_id": "INC_API_20260403_143052_a7b2",
-  "timestamp": 1735654252000,
-  "symptom": "User-facing description of the bug",
+  "symptom": "Exact user-visible failure or error",
   "root_cause": {
-    "description": "Technical explanation",
-    "file": "path/to/problematic/file.ts",
-    "category": "logic|config|dependency|performance|react-hooks",
-    "confidence": 0.85
-  },
-  "fix": {
-    "approach": "What was done",
-    "changes": [
-      { "file": "path/to/file.ts", "lines_changed": 10, "change_type": "modify|add|delete", "summary": "..." }
-    ]
+    "description": "Technical cause and first controllable cause",
+    "category": "logic",
+    "confidence": 0.95
   },
-  "verification": {
-    "status": "verified|unverified",
-    "regression_tests_passed": true,
-    "success_criteria_met": true
-  },
-  "tags": ["build-loop", "project-name", "layer", "category"],
-  "files_changed": ["list/of/all/files.ts"],
-  "quality_score": 0.75
+  "fix": "What changed and why",
+  "verification": "verified",
+  "tags": ["build-loop", "project", "backend", "typescript"],
+  "files_changed": ["path/to/file.ts"]
 }
 ```
 
-Write to `.build-loop/debugging/incidents/<incident_id>.json`. Flag `debugger JSON compatibility copy written` in Review-F only if another workflow requested JSON.
+Then run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/build-loop-debugger.js" store \
+  --input /path/to/incident.json --workdir "$PWD"
+```
+
+The command validates and writes `.claude/memory/incidents/<incident-id>.json`, then updates the JSONL and keyword indexes in the same memory root. Delete the temporary input after a successful store.
 
-## After Storing
+## Quality requirements
 
-1. Confirm the local note path.
-2. If standalone Coding Debugger supplied the prior incident, invoke `outcome({incident_id, result: "worked"|"failed"|"modified", notes})` to train its verdict classifier.
-3. If the note lacks verification, enrich it before ending Review-F.
+- Preserve the exact symptom and error class.
+- Explain the root cause, not only the failing line.
+- Record the implemented fix and changed files.
+- Use `verified` only when the reproduction and relevant regression tests pass.
+- Include `build-loop`, project, layer, technology, and symptom tags when applicable.
 
-## Sibling Skills
+Target a quality score of at least 75%. Do not store speculative diagnoses as verified incidents.
 
-- `build-loop:debugging-memory` `{op:"search"}` (references/search.md) — search memory before debugging
-- `build-loop:debugging-memory` `{op:"assess"}` (references/assess.md) — parallel domain assessment
-- `build-loop:debug-loop` — full iterative debugging that produces the incident this op stores
+## After storing
 
-*Source: adapted from the debugger incident-documentation workflow and maintained as a build-loop-native skill. Drift-checked by `build-loop:sync-skills`.*
+1. Confirm `file_path` exists in the JSON response.
+2. Search the symptom again and confirm the new incident is discoverable.
+3. Keep `.build-loop/issues/` for unresolved/executable work; resolved history belongs only in the structured debugger store.

package/skills/debugging-memory/references/subagent-integration.md

@@ -64,7 +64,7 @@ Skill("build-loop:debugging-memory") with input { op: "search", symptom: "<sympt
 - Low/no match (<40%): Investigate fresh, document afterward
 
 **After fixing a bug:**
-Write an incident note to `.build-loop/issues/INC_YYYYMMDD_HHMMSS_xxxx.md`
+Return the verified incident fields to the parent. The parent invokes `build-loop:debugging-memory` with `{ op: "store", ... }`, which writes `.claude/memory/incidents/<incident-id>.json`.
 
 This ensures fixes are remembered for future similar issues.
 ```

package/skills/decision-queue/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: decision-queue
+description: "Turn pending decisions — Operations Center tasks with status needs_input, a backlog of open questions, anything blocked on the user's judgment — into one interactive page the user answers inline and Claude reads back later. Not for a one-off static report with no response capture; use a plain Artifact instead. Each decision gets a card carrying the choice, why it needs the user, its impact, the options, and a recommendation. Triggers: 'show me the decisions waiting on me', 'what needs my input', 'make a decision queue', 'launch a ui for these open questions'. Not for a judgement call you already made and applied while work continued — that never blocks and belongs in `silent-assumptions`."
+user-invocable: false
+companion_assets:
+  - assets/template.html — tested, working page (styling, save/response plumbing, self-publish logic). Copy and adapt; never regenerate from scratch.
+  - scripts/regen_template_constants.py — regenerates the HEAD_HTML / SAVE_BAR_HTML self-publish constants from the authored markup. Run it after ANY CSS or save-bar edit; never hand-sync the two copies.
+  - references/example-large-queue-batching.md — second worked example (2026-08-26, PersonalLLMWiki planner backlog): the large-queue variant, where items are classified into a few claims and ruled as batches instead of one card per item. Read it before building for a queue of 50+ items.
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Decision Queue
+
+Build an interactive Artifact that lists every pending decision as a card —
+decision, why it needs the user, impact, options, recommendation, a response
+control, and a save button — so the user can answer at their own pace and
+Claude can read the answers back on request. Built once (2026-08-25) for
+Operations Center's `needs_input` queue; the pattern generalizes to any set
+of open questions the user names.
+
+## When to use
+
+- User asks what's waiting on their input, across Operations Center, a
+  backlog, or any other queue of blocked decisions.
+- User wants to *answer* those decisions somewhere durable, not just read
+  a report — the defining feature over a plain summary is the save/respond
+  loop.
+- Do not use this for a single decision (just ask) or for content with no
+  response to capture (use a plain Artifact via `artifact-design`).
+
+## Two shapes, chosen by queue size
+
+**One card per decision** is the default and everything below describes it. It
+works while the decisions are few and genuinely distinct.
+
+**Batch-claim triage** is the variant for a large queue. Above roughly fifty
+items, a page of one card per item reproduces the overwhelm that made the user
+ask for a page. Classify the items into a few classes instead, give each class
+one falsifiable claim plus the counted evidence for it, and let one ruling
+close the whole class with a drill-in for auditing and per-item override.
+
+The test between them is one question: **can you write a single sentence that
+is true of thirty of these items?** If yes, build the batch variant and read
+`references/example-large-queue-batching.md` first — it carries the pyramid
+structure the claims need, the classification trap that cost a rebuild, the
+flat-control CSS the user requires, and a save round-trip test worth copying.
+If no, you do not have batches; build one card per decision.
+
+## Workflow
+
+1. **Gather the decisions.** For Operations Center: `mcp__operations-center__list_tasks`
+   filtered to `status: needs_input`. The result is often too large for the
+   tool response and gets saved to a file — read it with Python/jq, don't
+   try to fit it inline. **Landmine:** `get_task` takes the FULL task id;
+   the short 8-char ids shown in the Operations Center startup-hook digest
+   are prefixes and `get_task` returns `null` for them. Use `list_tasks`
+   and filter by prefix match instead.
+
+2. **Synthesize each item**, one card's worth of fields:
+
+   | Field | What it answers | Note |
+   |---|---|---|
+   | `decision` | What action is on the table | Full sentence, not a summary of the situation |
+   | `why` | Why THIS needs the user, not an agent | If the source record has no explicit reason, infer from spec/classification and set `whyInferred: true` — the template renders an "inferred" disclaimer, so the honesty marker is never lost |
+   | `impact` | What actually changes — app, user, team | Concrete; cite real numbers from the source record when they exist |
+   | `options` | 2–4 real choices, lettered A/B/C… | Include the honest cost of "defer"/"reject", not a straw man |
+   | `recommendation` | Which option and why | Name the actual tradeoff, don't just restate the option |
+
+   Write in full sentences with clear predicates — this is a decision
+   record the user acts on, not a bullet fragment.
+
+3. **Load `artifact-design`** (required — even though the template supplies
+   a working visual treatment, the design-pass discipline still governs
+   copy calibration: eyebrow/title/lede text, card language, and whether
+   this dataset actually warrants the dashboard treatment over something
+   lighter).
+
+4. **Copy `assets/template.html`** to the scratchpad — never hand-roll the
+   self-publish plumbing from scratch; see "The one rule that matters"
+   below for why that's expensive to get right. Strip the leading `<!-- -->`
+   authoring comment block (it must not ship). Edit only the CONTENT ZONE:
+
+   ```js
+   window.__META__ = { eyebrow, title, lede, summaryCells, footer };
+   window.__ITEMS__ = [ { id, num, opened, touched, repo, classChip,
+     typeLabel, priority, title, decision, why, whyInferred, impact,
+     options, recommendation, selected: null, comment: "", respondedAt: null }, ... ];
+   ```
+
+   Leave everything inside `<script id="app-script">` untouched.
+
+5. **Verify before publishing** — cheap and catches real bugs:
+
+   ```bash
+   node --check <extracted app-data + app-script>   # syntax
+   # render META + ITEMS through the real cardHtml/renderBody functions
+   # (see git history of this skill's authoring session for the exact
+   # extraction snippet) and confirm it returns non-empty HTML with no
+   # thrown exception
+   grep -n "document.head.innerHTML\|getElementById(\"save-bar-shell\").outerHTML" *.html
+   # any match OUTSIDE an explanatory comment is the landmine below — fix it
+   ```
+
+6. **Publish** with `Artifact({ file_path, capabilities: {artifact: {}}, title, description, favicon })`.
+   The `artifact` capability is what lets the page save its own responses —
+   without it the save button has nothing to call. Load `artifact-capabilities`
+   if this is a fresh session that hasn't already loaded it.
+
+7. **Read answers back** on request: `Artifact({ action: "read", url })`.
+   The saved HTML contains the string `window.__ITEMS__` **twice** — once
+   as the real, live `<script id="app-data">` content, and once more as a
+   JS string literal inside `buildDocument()`'s own source (which the
+   self-publish logic captures verbatim so the republished page stays
+   functional). Parse the **first** occurrence, at the top of the file,
+   not whichever regex match comes back first if your extraction spans
+   the whole document carelessly.
+
+## The one rule that matters: never capture the live DOM for self-publish
+
+The template's `HEAD_HTML` and `SAVE_BAR_HTML` are **hardcoded JS string
+constants**, not `document.head.innerHTML` or `.outerHTML` reads. This is
+not a style preference — it was a real, shipped, user-visible bug
+(2026-08-26): the claude.ai artifact viewer injects its own bootstrap
+script into `<head>` before the page's own script runs. Capturing
+`document.head.innerHTML` at load time sweeps that injected script up
+alongside the page's own `<title>`/`<link>`/`<style>` and bakes it into
+whatever gets saved. On the next load the viewer injects a **second**,
+fresh copy of its own bootstrap on top of the stale one — two competing
+runtime copies collide, and the page's `<style>` tag stops taking effect
+at all (confirmed: totally unstyled, unreadable page after one save/reload
+cycle).
+
+The fix that held: write `HEAD_HTML` and `SAVE_BAR_HTML` as literal
+template-literal strings in the script, generated once from the actual
+authored markup and never read from the DOM again. The **only** DOM read
+that is safe in `buildDocument()` is
+`document.getElementById("app-script").outerHTML` — capturing the script's
+own tag, which the platform never modifies, so the running script can
+re-embed itself verbatim in the next version (the "quine" trick that keeps
+the page functional after every save without duplicating the render logic
+as a second string).
+
+If you edit the template's CSS or the save-bar markup, the change must land in
+**two** places — the literal markup, and the `HEAD_HTML`/`SAVE_BAR_HTML`
+constants inside `app-script`. **Do not sync them by hand. Run:**
+
+```bash
+python3 skills/decision-queue/scripts/regen_template_constants.py          # rewrite
+python3 skills/decision-queue/scripts/regen_template_constants.py --check  # CI mode
+```
+
+This section used to say "regenerate with a small script" and ship no script.
+What followed was predictable: `SAVE_BAR_HTML` sat as an empty string against
+382 characters of real markup, so `buildDocument()` emitted a page with no Save
+button, no status line and no counter — savable exactly once, then broken. Four
+static checks passed the whole time, because none of them ran `buildDocument()`
+and looked at the output. Found and fixed 2026-08-30.
+
+`tests/test_decision_queue_template.py` now fails on any drift, and
+`tests/test_decision_queue_render.py` runs the real script under Node and
+asserts on what it renders.
+
+## Every interpolation is escaped — keep it that way
+
+The card and header markup is built with the `h` tagged template. It escapes every
+`${...}` it interpolates. To insert markup you built yourself, wrap it: `${raw(cells)}`.
+
+```js
+h`<h2 class="card-title">${item.title}</h2>`        // escaped — the default
+h`<div class="queue">${raw(items.map(cardHtml).join(""))}</div>`  // deliberate HTML
+```
+
+This is not style. Item fields come from Operations Center tasks, backlog items, and
+peer-authored rally records — text an agent wrote, not text you wrote. Before
+2026-08-30 the template called `escapeHtml()` at 5 of ~23 interpolation sites, so every
+field added after the first few defaulted to unescaped: `item.title`, `item.decision`,
+`item.why`, `item.impact`, `item.recommendation`, `meta.lede`, and `meta.footer` all
+reached `innerHTML` raw. Rendering one crafted title through that version produced 14
+live `<img onerror>` elements in the reader's page.
+
+`h` inverts the default so the unsafe path is the one you have to type on purpose.
+When you add a field to a card, interpolate it and stop — do not reach for `raw()`
+unless the value really is markup you constructed.
+
+The same rule covers the data element: `buildDocument()` embeds items through
+`safeJsonForScript()`, not bare `JSON.stringify()`, because `JSON.stringify` does not
+escape `<` — an item containing `</script>` would close the data element early and the
+rest of the document would parse as markup.
+
+`scripts/test_decision_queue_template_escaping.py` renders a hostile item through the
+real file and fails if anything executes. It runs in CI. If you restructure the
+`<script id="app-script">` block, update that test's extraction with it.
+
+## Other things the template already handles (don't re-solve these)
+
+- **Batched save, not per-keystroke.** Radio/textarea changes update an
+  in-memory `items` array; nothing publishes until the Save button fires.
+  One `publish()` call per Save click, covering every card at once.
+- **Conflict handling.** A `conflict` rejection means someone else (another
+  tab, the user themself) already published — the view reloads to the
+  winner automatically. No retry, no merge logic needed.
+- **Read-only detection.** `not_writer` / `not_granted` / `not_declared` /
+  `capability_disabled` all collapse to one read-only state: the Save
+  button disables itself and says why, rather than pretending to save.
+- **A standing "no longer relevant" response.** `optionsFor()` appends a `×`
+  option to every card automatically. Do not author your own — the point is that
+  a decision which stopped being a question can be closed without pretending one
+  of the real options was chosen.
+- **Staleness chip.** A card whose `touched` date is 14+ days old renders an
+  "Untouched N days" chip. This requires `opened`/`touched` to be **ISO dates**
+  (`2026-08-30`), not prose like "3 weeks ago" — a non-date is ignored, never
+  guessed at.
+- **Draft persistence.** Selections and comments mirror to `localStorage` on
+  every change and clear on a successful publish, so closing the tab mid-queue
+  no longer loses typed work. A restored draft never overwrites an answer that
+  already round-tripped through publish, and the status line says how many cards
+  were restored. Every storage access sits in try/catch — the viewer can throw
+  on storage during thumbnail capture or with site data blocked.
+- **Filter to unanswered.** A save-bar checkbox hides answered cards through a
+  body class. View-only; it never mutates an item.
+- **Radio-group semantics.** Options sit in a `fieldset` with a `legend` naming
+  the decision, so a screen reader announces each choice with its question
+  attached. `#save-status` carries `role="status" aria-live="polite"`.
+
+## The decision-surface family — one core, several variants
+
+Four skills share one job: put a set of calls in front of the user and capture a
+ruling. They differ only in the KIND of call, so they share a core rather than
+forking one — the variant registry (`scripts/decision_surface.py`), the
+interactive page and its save/self-publish plumbing
+(`skills/decision-queue/assets/template.html`), and the durable writer
+(`scripts/write_decision/__main__.py`). **Adding a variant is a registry entry,
+never a fork of the core.**
+
+**Choose by the question the user is actually asking, never by name.** An agent
+that picks on name alone reaches for the one it already knows and rebuilds
+something that exists.
+
+| Member | Answers | Layer | Does work stop? |
+|---|---|---|---|
+| [`silent-assumptions`](../silent-assumptions/SKILL.md) | "What did you decide without me?" | surface | No — work continued under your default |
+| [`decision-queue`](../decision-queue/SKILL.md) | "What is waiting on me?" | surface | Yes — work has stopped |
+| [`auto-decision-capture`](../auto-decision-capture/SKILL.md) | "What did we already settle, and where is it written down?" | capture | No — fires passively |
+| [`auto-finding-capture`](../auto-finding-capture/SKILL.md) | "What concrete issues has anyone surfaced?" | capture | No — fires passively |
+
+`python3 scripts/decision_surface.py` prints this table (`--json` for machines).
+The registry is the one place a member is declared; this table is its prose
+mirror and must match it.
+
+**You are here: `decision-queue`.** Reach for `silent-assumptions` instead when the call was ALREADY MADE and applied and work never stopped — that surface exists to reverse a default after the fact, and it must never block.