hstack 0.16.0 → 0.18.0

package/template/.claude/skills/hstack-tech-debt-resolve/SKILL.md

@@ -1,123 +0,0 @@
----
-name: hstack-tech-debt-resolve
-description: Use to start fixing an `open` tech-debt item — walks its Pre-conditions, flips it to `in-progress`, and scaffolds the resolution change-spec. The fix path, as opposed to the wontfix and stale closure paths.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — validates the TD frontmatter flip and the scaffolded change-spec frontmatter"
----
-
-## Purpose
-
-`hstack-tech-debt-resolve` is the canonical entry point for resolving a known tech-debt item. The Skill performs direct mechanical writes in the main session (per ADR-0001, no `spec-author` invocation): flips the TD status `open → in-progress`, sets `resolution-attempted-at`, appends a Resolution Log entry, and scaffolds a resolution change-spec under `hstack/specs/changes/<id>/` with `resolves-tech-debt` pre-populated and the TD's Acceptance section quoted into the change-spec's "Resolves Tech-Debt" section. After this Skill, the engineer continues with the normal workflow (`/hstack:test-plan`, etc.).
-
-This Skill exists because manual frontmatter edits to tech-debt status are forbidden by the kernel. The reciprocal `change-spec.resolves-tech-debt: [<td-id>]` write at scaffold time is enforced by TD-04 and lands atomically with the TD status flip in a single auto-commit.
-
-## When to invoke
-
-Invoke when a tech-debt item is at `status: open`, its Pre-conditions are met, and the engineer wants to begin work on the fix. Re-invoking on a TD already at `in-progress` is a no-op (idempotency): the Skill detects the existing scaffolded change folder via `resolved-by` (set provisionally) and reports its current state.
-
-## Inputs
-
-- `<td-id>` (required, positional): the tech-debt id (e.g., `TD-0042-overage-banner-tailwind-class` or the short `TD-0042`).
-
-Optional:
-
-- `--area <module>`: override the area for the scaffolded change-spec. Default: the TD's `related-modules[0]` if non-empty; otherwise the Skill asks.
-- `--slug <slug>`: override the slug for the resolution change-spec. Default: `resolve-<td-slug-suffix>` (e.g., `resolve-overage-banner-tailwind-class`).
-
-The `--partial` flag is explicitly rejected. Partial resolution is not supported in v1: a change-spec either fully resolves a tech-debt item (listed in `resolves-tech-debt`, satisfying every Acceptance bullet) or it does not. A change that addresses only some of the Acceptance bullets stays off the `resolves-tech-debt` list and the TD remains at `in-progress` for a follow-up change. This is the kernel's "one change-spec, one bounded contract" discipline. An engineer tempted to split a TD into smaller pieces authors multiple TDs via `/hstack:tech-debt-new` instead.
-
-## Preconditions
-
-Before any work:
-
-- Verify `hstack/tech-debt/<td-id>.md` exists and is at `status: open`. If at `in-progress`, the Skill enters idempotent-resume mode (see below). If at `resolved`, `wontfix`, or `archived`, halt with the terminal status named.
-- Verify the engineer is not on `main` (or the configured default branch) if hstack's branch-hygiene rule applies — the resolve flow will create a new branch as part of the scaffold step.
-- Read the TD's Pre-conditions section. For each bullet, classify mechanically when possible:
-  - References to ADR-NNNN: check that the ADR exists at `status: accepted`. If at `proposed` or `deprecated`, halt mechanically.
-  - References to another TD: check that the referenced TD is at `resolved`. If not, halt mechanically.
-  - References to a file or symbol existing: grep-verify. If absent, halt mechanically.
-  - Prose pre-conditions that name no checkable artifact: defer to engineer confirmation in step 2 of orchestration.
-
-Mechanical halts cannot be overridden by engineer confirmation; the upstream artifact must change state first.
-
-## Orchestration steps
-
-1. **Print the TD in full.** Read `hstack/tech-debt/<td-id>.md` and print its Title, Why we took the shortcut, What it costs us, Fix sketch, Pre-conditions, and Acceptance sections to the conversation. The engineer should re-read this before starting; tech-debt context decays.
-
-2. **Walk Pre-conditions for confirmation.** For each Pre-condition bullet, ask "Is this met? (y/n + one-sentence justification)". Mechanical halts have already filtered the un-confirmable cases; remaining bullets require engineer judgment. Record each `(bullet, met, justification)` triple in a transient state file at `hstack/.session-state/td-resolve-<td-id>.yaml` for resumability and for inclusion in the scaffolded change-spec's Open Questions section. Any "no" halts the Skill with the recommended remediation surfaced from the bullet text.
-
-3. **Confirm proceed.** Print: "TD-NNNN is ready to resolve. Pre-conditions confirmed by `<owner>` on `<date>`. Proceed to scaffold the resolution change folder? (Y/n)". Default Yes.
-
-4. **Determine area, slug, and change-id.** If `--area` not provided, use TD's `related-modules[0]`. If `related-modules` is empty, ask the engineer. If `--slug` not provided, default to `resolve-<td-slug-suffix>`. Confirm with engineer. Compute the change-spec id as `<YYYY-MM>-<area>-<slug>`. Verify the area has a current module-spec; verify the derived change folder does not already exist. The id is now known and will be referenced by both writes below.
-
-5. **Preview proposed writes (confirmation gate).** Per the kernel's AI writes / humans confirm contract for mechanical operations, print the proposed diff to the engineer:
-   - TD frontmatter changes: `status: open → in-progress`, `resolution-attempted-at: <today>`, `updated: <today>`.
-   - TD Resolution Log entry to append: `status: open → in-progress on <today> by <owner>. Resolution change-spec: <change-id>.`
-   - New change-spec frontmatter (will be seeded in step 7).
-
-   Ask "Proceed with these writes? (Y/n)". Default Yes. On `n`, halt.
-
-6. **Write the TD (direct write + immediate validation).** Edit `hstack/tech-debt/<td-id>.md`:
-   - Defensive log-header check per the kernel: if `## Resolution Log` is absent, append it before writing the entry.
-   - Edit frontmatter: `status: open → in-progress`, `resolution-attempted-at: <today>`, `updated: <today>`.
-   - Append the Resolution Log entry: `status: open → in-progress on <today> by <owner>. Resolution change-spec: <change-id>.`
-   - Run `node hstack/scripts/validate-spec.mjs <path>` against the file. On validation failure, halt — do NOT proceed to step 7. Unstaged changes can be reverted via `git checkout -- <td-file>`.
-
-7. **Scaffold the resolution change folder.** (Do not call `/hstack:change-new` to avoid duplicate interview prompts.)
-   - Create `hstack/specs/changes/<change-id>/`.
-   - Seed `spec.md` from `hstack/templates/change-spec.md` with frontmatter populated: `id`, `type: change-spec`, `status: draft`, `owner` (from `git config user.name`), `area`, `related-spec: <area>`, `resolves-tech-debt: [<td-id>]`, `created` and `updated` to today, `schema-version: 1`.
-   - Pre-populate the "Resolves Tech-Debt" prose section: a pointer to `../../tech-debt/<td-id>.md` followed by the TD's Acceptance section quoted verbatim under the heading "Acceptance from TD-NNNN".
-   - Pre-populate the Open Questions section with the Pre-conditions confirmation log from step 2 (the `(bullet, met, justification)` triples), so the adversarial-reviewer can later verify the team did not rationalize away an unmet pre-condition.
-   - Pre-populate Problem section opener: "Resolves [<td-id>](../../tech-debt/<td-id>.md): <TD Title>. The TD was introduced by <introduced-by> and has been at `open` since <created>."
-   - Run `node hstack/scripts/validate-spec.mjs <path>` against the seeded change-spec. On validation failure, halt — the TD write from step 6 must be reverted manually via `git checkout -- <td-file>` before re-running the Skill.
-
-8. **Offer branch creation.** Mirror `/hstack:change-new`'s branch hygiene step: offer to create `change/<change-id>` from the current branch. Default Yes.
-
-9. **Auto-commit (single atomic commit).** `git add` both the TD and the new change-spec, commit with message `chore(tech-debt-resolve): scaffold <change-id> resolving <td-id>`. The reciprocal pair (TD `in-progress` ↔ change-spec `resolves-tech-debt: [<td-id>]`) lands in this single commit, preserving the kernel's atomicity rule.
-
-10. **Direct engineer to next step.** Print: "Resolution change scaffolded at `hstack/specs/changes/<change-id>/`. Continue with `/hstack:test-plan <change-id>` when ready. The TD is now at `in-progress` and will be flipped to `resolved` by `/hstack:finalize` after the resolving change is merged."
-
-    From here the change runs the normal per-change workflow unchanged — test-plan → security-review → data-review (when `db` in `surfaces`) → plan → implement → verify → adversarial-review → ship → finalize. Two points in that sequence are tech-debt-specific and are enforced by their own Skills: the `adversarial-reviewer` produces the mandatory Acceptance-satisfied confirmation (AR-07) because `resolves-tech-debt` is non-empty, and `/hstack:ship` checks GT-11 — every referenced TD at `in-progress`, and that confirmation present in the adversarial-review.
-
-## Outputs
-
-- `hstack/tech-debt/<td-id>.md` advanced to `status: in-progress` with `resolution-attempted-at` and an appended Resolution Log entry.
-- `hstack/specs/changes/<change-id>/spec.md` at `status: draft`, with `resolves-tech-debt: [<td-id>]` and the Resolves Tech-Debt section pre-populated.
-- Optional new branch `change/<change-id>`.
-- One commit at scaffold completion (with the TD flip and the change-spec scaffold both included in the same commit so the reciprocal write lands atomically).
-
-## Auto-commit triggers
-
-- One commit at scaffold completion, both files included. Commit message: `chore(tech-debt-resolve): scaffold <change-id> resolving <td-id>`.
-
-## Idempotency contract
-
-- Re-running on a TD already at `in-progress`: the Skill reads the TD's Resolution Log to find the existing resolving change-spec id, verifies the change folder exists, and reports its current state ("Resolution in progress at `<change-id>`; current change-spec status: `<status>`. Continue with `<next-skill>`."). No new scaffold is created.
-- Re-running mid-interview after a halt: the Skill reads `hstack/.session-state/td-resolve-<td-id>.yaml` and resumes at the next un-confirmed Pre-condition.
-- Re-running after the TD's `resolved-by` is set but status is still `in-progress` (an inconsistent state): the Skill halts and surfaces the inconsistency. Reconciliation is manual: either (a) `git checkout HEAD -- hstack/tech-debt/<td-id>.md` to revert to the prior committed state if the inconsistency came from an interrupted finalize, or (b) directly edit the TD frontmatter to set `resolved-by: null` and re-run `node hstack/scripts/validate-spec.mjs <path>`.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The TD does not exist or is at a terminal status (`resolved`, `wontfix`, `archived`). Halt with the status named.
-- A mechanical Pre-condition halts the Skill (ADR not accepted, dependent TD not resolved, named file absent). Cannot be overridden by engineer confirmation.
-- The engineer answers "no" on any prose Pre-condition. The Skill logs the unmet bullet and surfaces the recommended remediation from the bullet text.
-- The TD's `related-modules[0]` is empty and the engineer does not provide `--area`.
-- The area has no current module-spec.
-- The change-spec id (`<YYYY-MM>-<area>-<slug>`) collides with an existing change folder. Ask the engineer for a different slug.
-- The TD's Acceptance section is empty (TD authored without Acceptance, which TD-01 should have caught — flag as a validation gap).
-- `--partial` flag is passed. Halt with the message above.
-
-## Failure modes
-
-- **TD's Acceptance is too vague to satisfy mechanically.** The Skill scaffolds anyway but flags in the change-spec's Open Questions that the adversarial-reviewer will need to interpret. The engineer is reminded that AR-07 makes Acceptance-satisfied a mandatory finding lens.
-- **Pre-condition confirmation session interrupted.** Resumable via the session-state file; engineer continues from the next un-confirmed bullet.
-- **A direct write fails mid-scaffold.** Halt before any commit. Per the new ordering (step 6 writes TD, step 7 writes change-spec, step 9 commits both atomically), no partial commit is possible — the failure leaves both files unstaged for the engineer to inspect or discard via `git checkout -- <file>`.

package/template/.claude/skills/hstack-tech-debt-stale/SKILL.md

@@ -1,86 +0,0 @@
----
-name: hstack-tech-debt-stale
-description: Use to close a tech-debt item whose original claim no longer reproduces — the code was rewritten, a dependency shipped a fix, the system is gone. Stale describes a verified absence; `/hstack:tech-debt-wontfix` describes a choice.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - "node hstack/scripts/validate-spec.mjs — validates the TD status flip and TD-07 (stale requires both verification fields non-null)"
----
-
-## Purpose
-
-`hstack-tech-debt-stale` is the controlled closure path for tech-debt items whose original claim no longer reproduces. The Skill captures the verification evidence in two required fields (`stale-verified-at` and `stale-verification-method`) and flips status `open → stale-no-longer-reproducible` directly in the main session (per ADR-0001, no `spec-author` invocation). Per TD-03, the new status is terminal — no field rewrites are permitted afterwards.
-
-The Skill exists because closing aged-out TDs via `/hstack:tech-debt-wontfix` would corrupt the audit signal `wontfix` carries (deliberate cost-benefit decision to live with the compromise). Stale-no-longer-reproducible is the structurally honest closure for organic decay.
-
-## When to invoke
-
-Invoke when a tech-debt item at `status: open` has a claim that no longer reproduces — typically because:
-
-- The surrounding code was rewritten or removed.
-- A third-party dependency was upgraded and shipped a fix.
-- The bug was fixed incidentally as part of an unrelated change.
-- The system, module, or call path the TD described no longer exists.
-
-Do NOT invoke for deferrals ("we won't get to this") — those go to `/hstack:tech-debt-wontfix`. Do NOT invoke for TDs that are still observably true but the team is choosing not to fix — also `/hstack:tech-debt-wontfix`. The semantic distinction is load-bearing: stale describes an absence, wontfix describes a choice. Misusing `wontfix` for a claim that has aged out corrupts the audit signal that separates deliberate deferral from organic decay — the two statuses answer different retrospective questions, and a corpus that conflates them can answer neither.
-
-## Inputs
-
-- `<td-id>` (required, positional): the tech-debt id.
-
-## Preconditions
-
-- Verify `hstack/tech-debt/<td-id>.md` exists and is at `status: open`. If at `in-progress`, halt — work is already underway; complete or cancel the resolution change-spec first. If at any terminal status (`resolved`, `wontfix`, `stale-no-longer-reproducible`, `archived`), halt with the status named.
-
-## Orchestration steps
-
-1. **Print the TD in full.** Read `hstack/tech-debt/<td-id>.md` and print Title, Why we took the shortcut, What it costs us, Fix sketch, Pre-conditions, Acceptance to the conversation. The engineer should re-read before committing to a stale-no-longer-reproducible closure; the verification step depends on understanding what the original claim actually was.
-
-2. **Ask the verification question.** "What evidence shows this TD's claim no longer reproduces?" The answer has to be checkable by someone who was not in the room — a command that returns nothing, a commit that removed the dependent code, a dependency version that carries the upstream fix, a system that no longer exists. Capture it as written; no length bound.
-
-3. **Semantic check.** Stale means the problem no longer exists and someone else could verify that. The answer has to be a fact about the code, the dependency tree, or the deployed system — not a position on the problem. A sentence that says how the team now feels about the compromise is a wontfix rationale however it is phrased, and a sentence that names a removed call path is a stale verification however casually it is written. When it reads as a preference, halt with: "That reads like a wontfix rationale, not stale-no-longer-reproducible. Stale means the original problem has verifiably gone away — code removed, dependency upgraded, system retired. If the problem is still observably present and the team is choosing not to fix it, use /hstack:tech-debt-wontfix instead." The Skill does not write anything in this case.
-
-4. **Confirm.** Print the captured verification method and ask "Mark TD-NNNN as stale-no-longer-reproducible with this evidence? (Y/n)". Default Yes. Include a one-line summary of what will be written to disk so the engineer sees the proposed-diff before committing (per the kernel's AI writes / humans confirm contract for mechanical operations).
-
-5. **Verify the answer is a fact, not a story.** Read it back against one test: could a third party run, read, or look up what it names and reach the same conclusion? If it names something checkable, it qualifies — one clause or four. If it is an account of why the problem stopped mattering, the problem is still there and this is a wontfix; surface that recommendation rather than writing the stale closure.
-
-6. **Write the stale transition (direct write).** Per the kernel's Mechanical operations section, this Skill performs the writes itself via the `Edit` tool — no `spec-author` invocation. Edit `hstack/tech-debt/<td-id>.md`:
-   - Defensive log-header check per the kernel: if `## Resolution Log` is absent, append it before writing the entry.
-   - Edit frontmatter: `stale-verified-at: <today>`, `stale-verification-method: <answer>`, `status: open → stale-no-longer-reproducible`, `updated: <today>`.
-   - Append to the Resolution Log section: `status: open → stale-no-longer-reproducible on <today> by <owner>. Verification method: <answer>.`
-
-   Run `node hstack/scripts/validate-spec.mjs <path>` against the file. TD-07 (stale-no-longer-reproducible requires both `stale-verified-at` and `stale-verification-method` non-null) must pass. On validation pass, `git add` the file and commit with message `tech-debt(<td-id>): stale-no-longer-reproducible`. The three frontmatter writes plus the log append land in this single auto-commit, preserving atomicity. On validation failure, halt; unstaged changes can be reverted via `git checkout -- <td-file>`.
-
-7. **Confirm completion.** Print: "TD-NNNN is now `stale-no-longer-reproducible`. Per TD-03, no further field rewrites are permitted on this artifact. If the original claim ever reappears, author a new tech-debt via `/hstack:tech-debt-new` rather than re-opening this one."
-
-## Outputs
-
-- `hstack/tech-debt/<td-id>.md` advanced to `status: stale-no-longer-reproducible` with `stale-verified-at` and `stale-verification-method` set, and a Resolution Log entry appended.
-- One commit. Message: `tech-debt(<td-id>): stale-no-longer-reproducible`.
-
-## Auto-commit triggers
-
-- One commit at the status flip. The kernel's auto-commit-at-status-transition rule applies.
-
-## Idempotency contract
-
-- Re-running on a TD already at `stale-no-longer-reproducible`: the Skill reads the existing artifact and produces a no-op aside from informing the engineer the TD is already stale.
-- Re-running mid-interview after a halt: the Skill does not persist session state (the interview is one question; re-asking is cheaper than state-file management).
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The TD does not exist or is at a non-`open` status. Halt with the status named.
-- The verification answer is a preference about the problem rather than a fact about its absence (per step 3). The Skill refuses to write and surfaces the wontfix recommendation.
-- The answer names nothing a third party could check. Halt and surface the wontfix recommendation — a verification that cannot be re-run by someone else is a preference about the problem, not evidence of its absence.
-- The engineer declines confirmation at step 4.
-
-## Failure modes
-
-- **Direct write fails (filesystem, validator, or git).** Halt; the four frontmatter writes plus the Resolution Log append must land in a single auto-commit. Partial writes are not possible if the Skill aborts on validator failure before staging. Concrete recovery: `git checkout -- hstack/tech-debt/<td-id>.md` to revert to the prior committed state.
-- **Stale claim turns out to be reproducible after closure.** Per TD-03 the closed TD is immutable; the engineer authors a new tech-debt via `/hstack:tech-debt-new` describing the reappeared claim. The new TD references the closed one in its Title or Why-we-took-the-shortcut for audit-trail continuity.

package/template/.claude/skills/hstack-tech-debt-wontfix/SKILL.md

@@ -1,77 +0,0 @@
----
-name: hstack-tech-debt-wontfix
-description: Use to close a tech-debt item the team has decided to live with permanently, recording the reason and the accepted alternative. Wontfix describes a choice; `/hstack:tech-debt-stale` describes a claim that no longer reproduces.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — validates the TD frontmatter flip and TD-06 (wontfix-reason and wontfix-accepted-alternative both non-null)"
----
-
-## Purpose
-
-`hstack-tech-debt-wontfix` is the controlled closure path for tech-debt items the team has decided not to fix. The Skill captures the rationale in two required fields (`wontfix-reason` and `wontfix-accepted-alternative`) and flips status `open → wontfix` directly in the main session (per ADR-0001, no `spec-author` invocation). Per TD-03, wontfix is terminal — no field rewrites are permitted afterwards.
-
-## When to invoke
-
-Invoke when a tech-debt item at `status: open` will not be fixed and the team has decided to live with the compromise permanently. Do NOT invoke for deferrals ("we'll get to it later") — those items stay at `open`. The Skill applies a deliberate prose-level friction to refuse deferral-flavored rationales.
-
-## Inputs
-
-- `<td-id>` (required, positional): the tech-debt id.
-
-## Preconditions
-
-- Verify `hstack/tech-debt/<td-id>.md` exists and is at `status: open`. If at `in-progress`, halt — work is already underway. Concrete recovery: locate the resolution change-spec via the TD's Resolution Log (most recent entry names the resolving change-spec id) and either complete that change normally or abandon it by direct frontmatter edit (`git checkout HEAD -- hstack/tech-debt/<td-id>.md` to revert the TD to `open`, then archive the resolution change folder manually). If at any terminal status, halt with the status named.
-
-## Orchestration steps
-
-1. **Print the TD in full.** Read `hstack/tech-debt/<td-id>.md` and print Title, Why we took the shortcut, What it costs us, Fix sketch, Pre-conditions, Acceptance to the conversation. The engineer should re-read before committing to wontfix.
-
-2. **Ask the first question.** "Why won't this tech-debt be fixed?" The answer names the compromise and why living with it is the right call, in a form that survives being read back in a year without the surrounding context. No length bound — the artifact was just printed in full, so the engineer is answering with it on screen.
-
-3. **Deferral check.** Wontfix means the problem is real and we are choosing to live with it. If the answer describes a future in which we fix it, it is a deferral and the item stays `open`. Judge the sentence, not its vocabulary: "we accept the 50ms until the v2 substrate lands next quarter, which removes it as a side effect" is a real acceptance with a date in it, while "the cost-benefit does not favour action" is a deferral with no giveaway words at all. When it reads as a deferral, halt with: "That reads like a deferral, not a wontfix. Wontfix is for compromises we've decided to live with permanently. Leave the TD at `open` if this is a deferral; only re-invoke when the cost-benefit has actually flipped." The Skill does not write anything in this case.
-
-4. **Ask the second question.** "What are we accepting as the alternative to fixing this? (one sentence)". This is the on-record acknowledgement of the cost the team is choosing to live with. Examples: "We accept the manual workaround documented in the runbook", "We accept the 50ms latency overhead until v2 substrate lands", "The surrounding code has been rewritten and the original compromise no longer exists".
-
-5. **Confirm.** Print both answers and ask "Mark TD-NNNN as wontfix with this rationale? (Y/n)". Default Yes.
-
-6. **Write the wontfix transition (direct write).** Per the kernel's Mechanical operations section, this Skill performs the writes itself via the `Edit` tool — no `spec-author` invocation. Edit `hstack/tech-debt/<td-id>.md`:
-   - Defensive log-header check per the kernel: if `## Resolution Log` is absent, append it before writing the entry.
-   - Edit frontmatter: `wontfix-reason: <answer-a>`, `wontfix-accepted-alternative: <answer-b>`, `status: open → wontfix`, `updated: <today>`.
-   - Append to the Resolution Log section: `status: open → wontfix on <today> by <owner>. Reason: <answer-a>. Accepted alternative: <answer-b>.`
-
-   Run `node hstack/scripts/validate-spec.mjs <path>` against the file. TD-06 (wontfix requires both rationale fields non-null) must pass. On validation pass, `git add` the file and commit with message `tech-debt(<td-id>): wontfix`. The four frontmatter writes plus the log append land in this single auto-commit, preserving atomicity. On validation failure, halt; unstaged changes can be reverted via `git checkout -- <td-file>`.
-
-7. **Confirm completion.** Print: "TD-NNNN is now `wontfix`. Per TD-03, no further field rewrites are permitted on this artifact. If the team's decision later reverses, author a new tech-debt via `/hstack:tech-debt-new` rather than re-opening this one."
-
-## Outputs
-
-- `hstack/tech-debt/<td-id>.md` advanced to `status: wontfix` with `wontfix-reason` and `wontfix-accepted-alternative` set, and a Resolution Log entry appended.
-- One commit. Message: `tech-debt(<td-id>): wontfix`.
-
-## Auto-commit triggers
-
-- One commit at the status flip. The kernel's auto-commit-at-status-transition rule applies.
-
-## Idempotency contract
-
-- Re-running on a TD already at `wontfix`: the Skill reads the existing artifact and produces a no-op aside from informing the engineer the TD is already wontfix.
-- Re-running mid-interview after a halt: the Skill does not persist session state (the interview is short enough that re-asking both questions is cheaper than state-file management).
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The TD does not exist or is at a non-`open` status. Halt with status named.
-- The wontfix-reason answer reads as a deferral (per step 3). The Skill refuses to write and surfaces the recommendation.
-- The engineer declines confirmation at step 5.
-
-## Failure modes
-
-- **Direct write fails (filesystem, validator, or git).** Halt; the TD's status flip and the two frontmatter writes must land in a single auto-commit. Partial writes are not possible if the Skill aborts on validator failure before staging.
-- **Deferral disguised as wontfix.** The step-3 judgment is the v1 defense, and it is a judgment rather than a word list because the list it replaced fired on legitimate rationales and missed the paraphrase. The Skill's job is to make the distinction visible, not to pattern-match it.

package/template/.claude/skills/hstack-telemetry/SKILL.md

@@ -1,73 +0,0 @@
----
-name: hstack-telemetry
-description: Use for a retrospective observability report on token economics, workflow shape, quality outcomes, overengineering, and contract drift, derived from artifacts, git history, and transcripts. Read-only; no subagents, no LLM turns.
-tools:
-  - Read
-  - Bash
-  - Glob
----
-
-## Purpose
-
-`hstack-telemetry` produces a retrospective observability report — a markdown file under `hstack/telemetry/reports/` — by parsing on-disk artifacts, git history, and Claude Code transcripts. The Skill is mechanical: it shells out to a Python script, reports the output path, and returns. No subagent is invoked. The kernel's "no parallel tracker" rule is preserved because the report is derivative — re-runnable from source, never authoritative.
-
-The report covers six buckets:
-
-1. **Token economics** — TE-1 cost-score per Skill, TE-2 cache-hit ratio per Skill, TE-3 subagent entry-tax amortization (all three session-scoped), plus TE-4 cost per phase and TE-5 cost per change, summed from the sidecar phase windows (ADR-0009). TE-4/TE-5 supersede TE-1 wherever a sidecar exists, and print a coverage fraction: only five Skills emit sidecars, so their totals are a subset by construction. A phase whose window or transcript cannot be read is reported as *unmeasured*, never as zero.
-2. **Workflow shape** — WS-1 phase duration, WS-2 gate findings density, WS-4 scope-amendment rate, WS-6 halt reasons.
-3. **Quality outcomes** — QO-2 severity × resolution-type mix, QO-3 test-immutability audit, QO-4 verifier observed-vs-promised.
-4. **Overengineering** — OE-1 artifact tokens per diff line, OE-3 subagent invocations × host cost, OE-5 trivial-eligible changes that ran the full gauntlet.
-5. **Contract drift** — module-spec staleness × recent commit activity, ADR supersession lag, tech-debt half-life by exit path.
-6. **Kernel-fit candidates** — KF-P1 Category-A claim spans production paths (post-PR-#5 misclassification), KF-P2 halt-reason cluster, KF-P3 missed-gate recovery. Detection-only rollup; the canonical findings live at `hstack/kernel-fit/findings/` and are produced by `/hstack:kernel-fit-scan`. See ADR-0004.
-
-A watch-list at the report bottom surfaces anomalies (low cache-hit Skills, unmeasured phase sidecars, high-severity findings resolved as `justified-in-prose`, candidate test-immutability violations, scope-amendment rate above 30%, module drift, fired kernel-fit patterns).
-
-## When to invoke
-
-Run any time. Common cadence:
-
-- Weekly for active engineering — catches drift early.
-- After every ~5 shipped changes — surfaces trend lines that single-change inspection misses.
-- Whenever a Skill or subagent has been tuned — confirm the change moved the relevant metric.
-
-The Skill is read-only and idempotent — re-running produces a fresh report at the same path (overwrites the same-day file).
-
-The report is a retrospective lens, never an in-flight signal: no Skill that writes artifacts takes it as input. Old reports stay in git so trend lines can be checked against them; deleting reports to reshape a trend defeats the point. Any v2 "agent-ledger" rebrand of this tool waits on at least three months of real runs showing the data layer is worth promoting.
-
-## Inputs
-
-- `--window <N>` (optional): limit git/transcript history to the last N days. Default 30. `--window 0` means all-history.
-- `--out <path>` (optional): override the report output path. Default `hstack/telemetry/reports/<YYYY-MM-DD>.md`.
-
-## Preconditions
-
-- The consuming repo has been initialized via `/hstack:init` (at minimum: `hstack/` directory exists).
-- Python 3.10+ is available on PATH (the script uses `from __future__ import annotations` and modern typing).
-- The git repository is intact (`.git/` present); the Skill walks `git log --all`.
-
-## Orchestration steps
-
-1. **Locate the script.** The Skill resolves `hstack/scripts/telemetry/report.py` relative to the consuming repo's hstack root. If the script is missing, halt with: "telemetry script not found — re-vendor hstack or run `/hstack:configure`".
-2. **Shell out.** Invoke `python3 hstack/scripts/telemetry/report.py --repo <repo-root> --window <N>`. Capture stdout/stderr.
-3. **Surface the output path.** On success, print the report path and a one-line summary (number of changes, TDs, commits, sessions analyzed — already printed to stderr by the script).
-4. **On failure.** Surface the Python traceback. The script is dependency-light (no PyYAML required); failures typically indicate a corrupted artifact or a git repo issue.
-
-## Outputs
-
-- `hstack/telemetry/reports/<YYYY-MM-DD>.md` — the markdown report.
-- `hstack/telemetry/reports/<YYYY-MM-DD>.json` — the structured twin of the markdown report (same metrics dict, machine-readable). Consumed by the telemetry UI shipped in the hstack source repo (`ui/`, run locally with `HSTACK_REPO=<repo> npm run dev`); carries the same derivative-only guarantee.
-- No frontmatter changes. No commits. The Skill is read-only.
-
-## Auto-commit triggers
-
-None. The Skill is read-only.
-
-## Idempotency contract
-
-Re-running on the same day overwrites the same-day report file. Different windows produce different reports under the same date — last run wins. To preserve a snapshot, copy or rename the file manually.
-
-## Stop conditions
-
-- `hstack/scripts/telemetry/report.py` is missing.
-- Python 3 is not available.
-- The git repository is corrupt or `.git/` is missing.

package/template/.claude/skills/hstack-test-plan/SKILL.md

@@ -1,159 +0,0 @@
----
-name: hstack-test-plan
-description: "Use when a change-spec is at `ready-to-plan` and needs `test-plan.md` before `/hstack:change-plan` can run — the planner refuses to sequence phases without it. Skipped for changes marked `trivial: true`."
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — validates test-plan frontmatter and TS-01..TS-06"
----
-
-## Purpose
-
-`hstack-test-plan` produces `test-plan.md` for a change-spec by orchestrating the `test-strategist` subagent. In hstack v1, the artifact is a structured LLM judgment about test pyramid layering, edge cases, tenant-isolation tests, fixture strategy, and performance budgets, plus three mandatory challenge prompts. It is not a coverage-instrumented or mutation-tested artifact; v2 substrate replaces the strategist's claims with measured coverage runs and benchmark-asserted budgets. This Skill enforces the v1 honesty framing on every output.
-
-The test-plan runs **upstream of the planner**. It is the first per-change artifact authored after the change-spec reaches `ready-to-plan`. The planner reads it; the implementer reads it; the verifier later checks observed tests against both the planner's per-phase Verifier Expectations and the test-plan's pyramid and budgets.
-
-## When to invoke
-
-Invoke when a change-spec reaches `status: ready-to-plan`. The test-plan must reach terminal status (`passed` or `concerns-acknowledged`) before `hstack-change-plan` can run — the planner refuses to start without it. Security-review and data-review can run in parallel with the test-plan; none of those three gate one another.
-
-Trivial changes (`trivial: true` on the change-spec) bypass this Skill per the kernel's trivial-changes carve-out.
-
-## Inputs
-
-- `<change-id>` (required, positional): the change-spec id.
-
-## Preconditions
-
-Before any work:
-
-- Verify the change-spec exists and is at `status: ready-to-plan` or later. If at `draft`, halt — the strategist cannot work against a draft spec.
-- Verify the change-spec is **not** `trivial: true`. If trivial, halt and surface that the test-plan is not required.
-- Verify the change-spec's `Invariants` section has ≥ 3 bullets (SP-04). The strategist maps tests to invariant ids; without invariants, mapping is impossible.
-- Verify `hstack/context/tech-stack.md` and `hstack/context/ci-cd.md` are at `status: current`. The strategist relies on these for framework conventions and canonical command names.
-- When `surfaces` includes `db`: verify `hstack/context/data-architecture.md` is at `status: current`.
-- Verify the relevant module-spec at `status: current`.
-- Determine whether `surfaces` includes `db`, `api`, or `agent`. If yes, the strategist will be required to produce a non-empty `tenant-isolation-tests` array (TS-03).
-- Determine whether the change touches a hot path or high-traffic surface. If yes, set `performance-budgets-required: true` for the subagent's session and require the Budgets table to be populated.
-
-## Orchestration steps
-
-0. **Open the phase window (mechanical, no LLM turn, no commit).** The moment the preconditions above pass and *before* any subagent invocation, run `python3 hstack/scripts/telemetry/session_id.py` and keep its `session_id` and `now` values — they become `session_id` and `phase_opened_at` in the sidecar below (ADR-0009). On failure or a null session id, hold `null` for both and continue.
-
-1. **Invoke `test-strategist`.** Use the Task tool with `subagent_type: test-strategist` and context = [kernel, `hstack/templates/test-plan.md`, change-spec, module-spec, tech-stack, ci-cd, data-architecture when applicable]. The subagent walks the eight sections — Surfaces and Risk Profile, Test Pyramid, Edge Cases, Tenant Isolation Tests, Test Data and Fixture Strategy, Performance and Regression Budgets, Challenge Prompts, Open Concerns.
-
-2. **Pyramid bias.** Per the subagent's contract, bias is unit-for-pure-functions, integration-for-multi-module-behavior, e2e-only-for-user-journeys-that-span-the-stack. The Skill rejects any pyramid where the bulk of behavior coverage lands in e2e — that is the slow-and-flaky failure mode the strategist exists to prevent.
-
-3. **Edge case enumeration.** Minimum three bullets unless the change-spec carries `trivial: true`. Each bullet maps to a named test file and test name. The Skill rejects edge cases that name a test without a path.
-
-4. **Tenant-isolation tests (TS-03 enforcement).** When `surfaces` includes `db`, `api`, or `agent`, the `tenant-isolation-tests` array must be non-empty and every entry must cite a real surface (table, RPC, tool boundary) and a real planned test. The subagent grep-verifies surface identifiers; making them up is forbidden.
-
-5. **Fixture strategy.** The Test Data and Fixture Strategy section must be non-empty before status can advance. `fixture-strategy-declared: true` is required for terminal status (TS-05).
-
-6. **Performance budgets.** When `performance-budgets-required: true`, every row in the Budgets table must pair a numeric threshold with an asserting test. The Skill deletes any unbacked row and surfaces it as a coverage gap rather than letting an unenforceable budget ship.
-
-7. **Three challenge prompts (mandatory).** Per TS-02 and the subagent's contract, the subagent answers all three challenge prompts. The canonical wording:
-   - "What behavior in this change would silently pass the test suite but break in production? Name the test that would catch it, or declare that no such test is planned and justify."
-   - "Which invariant from the change-spec has no corresponding negative or regression test? If every invariant has a mapped test, cite the test for each invariant by id."
-   - "What concurrent, multi-tenant, or failure-mode scenario is not exercised by the planned tests? If none is plausibly relevant, justify why this change has no such scenario."
-   The prompts must be answered; they need not be transcribed. Where a probe fits the change poorly as written, the subagent adapts it so it bites harder and records the adapted question in the heading — the `(a)` / `(b)` / `(c)` prefixes stay, because that is what TS-02 locates the answers by. Each answer is at least one paragraph. The Skill verifies `challenge-prompts-answered: 3` in frontmatter.
-
-8. **Invariant mapping (TS-06).** Every invariant id declared in the change-spec must be referenced at least once in section 3, section 4, or in the (b) challenge prompt. The `invariants-mapped` frontmatter array enumerates the covered ids. The validator fails if any invariant is unmapped.
-
-9. **v1 framing.** Every rationale paragraph uses language like "the planned test asserts X" rather than "we verified X" or "we measured X". The Skill rejects any rationale that asserts coverage-measured evidence — that is v2 substrate territory.
-
-10. **Status transitions.** When every coverage layer is `addressed` or `not-applicable` with justification, every required section is populated, every invariant is mapped, every applicable budget has an asserting test, and all three challenge prompts are answered, the subagent transitions to `status: passed`. When any layer is `partial`, the subagent can only transition to `concerns-acknowledged`, and only when `concerns-acknowledged-by` is non-null (a human handle the owner has explicitly provided) and the Open Concerns section enumerates each partial layer with a tech-debt id. Per TS-04, `passed` is impossible if any layer is `partial`.
-
-11. **Tech-debt for deferred coverage.** When a coverage layer is being deferred rather than addressed, the subagent prompts the engineer to invoke `hstack-tech-debt-new` to create the paper trail. The Skill does not file the tech-debt itself; it surfaces the recommendation.
-
-12. **Validate.** Run `node hstack/scripts/validate-spec.mjs <path>` — TS-01 (parent-change matches), TS-02 (challenge-prompts-answered == 3), TS-03 (tenant-isolation-tests non-empty when surfaces includes db/api/agent), TS-04 (status gating on partial layers), TS-05 (fixture-strategy-declared == true before passed), TS-06 (every invariant id is in `invariants-mapped`).
-
-## Outputs
-
-- `hstack/specs/changes/<change-id>/test-plan.md` at `status: passed` or `concerns-acknowledged`.
-- Optional surfaced recommendation to file tech-debt for any deferred `partial` coverage layer.
-
-## Auto-commit triggers
-
-- Status transition to `in-progress` after the Test Pyramid section lands.
-- Status transition to terminal (`passed` or `concerns-acknowledged`). Commit message: `test-plan(<change-id>): passed` or `concerns-acknowledged`.
-- Edits to the `coverage-layers` map (because TS-04's terminal-gating depends on it).
-- Edits to `tenant-isolation-tests` (because TS-03's gating depends on it).
-- Edits to `concerns-acknowledged-by` (because it gates the partial-layer path).
-
-## Telemetry sidecar
-
-At the terminal-status auto-commit above (`test-plan(<change-id>): passed` or `concerns-acknowledged`), write `hstack/specs/changes/<change-id>/.telemetry/test-plan.json` in the same `git add && git commit` as the canonical write. The sidecar is derivative of git + frontmatter (see `hstack/templates/telemetry-sidecar.md`). Schema:
-
-```json
-{
-  "schema_version": 2,
-  "skill": "hstack-test-plan",
-  "change_id": "<change-id>",
-  "session_id": "<session id from step 0, or null>",
-  "phase_opened_at": "<ISO-8601 from step 0, or null>",
-  "phase_closed_at": "<ISO-8601, now — same write as this sidecar, or null>",
-  "completed_at": "<ISO-8601, when terminal status reached>",
-  "status": "passed | concerns-acknowledged",
-  "coverage_layers": {<mirror of frontmatter coverage-layers map>},
-  "tenant_isolation_tests_count": <int, length of tenant-isolation-tests array>,
-  "tenant_isolation_required": <bool, true when surfaces includes db/api/agent>,
-  "performance_budgets_required": <bool>,
-  "performance_budgets_count": <int, rows in the Budgets table>,
-  "challenge_prompts_answered": <int, frontmatter field; must be 3 at terminal>,
-  "invariants_mapped_count": <int, length of invariants-mapped array>,
-  "invariants_declared_count": <int, count of bullets in change-spec Invariants>,
-  "edge_cases_count": <int, bullets in Edge Cases section>,
-  "test_files_named_count": <int, distinct test file paths referenced>,
-  "fixture_strategy_declared": <bool>,
-  "halt_reasons": [<kernel halt-sentinel enum values, if any>]
-}
-```
-
-Reason this sidecar matters: it makes the test-strategist's rubber-stamp signal cheap. A `passed` test-plan with `tenant_isolation_tests_count: 0` despite `tenant_isolation_required: true`, or `challenge_prompts_answered: 3` paired with zero invariants-mapped diff against declared, are the cases the telemetry layer's WS-2 and QO-1 metrics exist to surface. `.telemetry/` is git-ignored. If the sidecar write fails, log and continue; the canonical commit must still land.
-
-The three phase-window fields (`session_id`, `phase_opened_at`, `phase_closed_at`) come from step 0 and from this write. Their rules — best-effort, unmeasured rather than zero, never a halt — are stated once in `hstack/templates/telemetry-sidecar.md` § The phase window, which is the canonical schema and wins over any Skill.
-
-## Session boundary
-
-`test-plan` is a natural session cut: the auto-commit above left `test-plan.md` on disk, so the conversation holds nothing the next phase needs. The cut-notice format, the kickoff-prompt template and the context-block rules are in `KERNEL.md` § Session boundaries; this Skill's two variables are:
-
-```
-HSTACK-CUT: test-plan complete — cut recommended before change-plan.
-```
-
-and the next command, `/hstack:change-plan <change-id>`.
-
-## Idempotency contract
-
-- Re-running on a terminal test-plan without spec changes: the subagent reads the existing artifact and produces a no-op aside from `updated` timestamps.
-- Re-running after the change-spec's Invariants have been amended: the subagent re-verifies `invariants-mapped` covers every id and adds new entries where needed; halts if an amended invariant has no mappable test.
-- Re-running mid-authoring after a halt: the subagent reads the partial file and resumes at the next un-confirmed section or un-answered challenge prompt.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- Change-spec at `draft` rather than `ready-to-plan`. Halt.
-- Change-spec carries `trivial: true`. Halt and inform — test-plan is not required.
-- Change-spec `Invariants` empty or fewer than three bullets. Halt; the strategist cannot map tests to invariants that do not exist.
-- `tech-stack.md`, `ci-cd.md`, or (when applicable) `data-architecture.md` at `needs-refresh` or absent. Halt.
-- `surfaces` includes `db`/`api`/`agent` but the change-spec does not name a tenant-isolation invariant. Halt and ask the engineer to amend via `spec-author`.
-- A performance budget is being declared but the consuming repo has no test pattern that can assert it. Halt; file tech-debt for the missing test infrastructure or drop the budget.
-- A coverage layer would be marked `addressed` without concrete test file paths. The Skill rejects and the subagent bias-falls to `partial`.
-- `concerns-acknowledged-by` would be written without the owner's explicit acknowledgement. Halt.
-- The test-plan would name more than fifteen test files — halt and ask whether the change-spec should split per the kernel's multi-module rule.
-
-## Failure modes
-
-- **Module-spec missing or `needs-refresh`.** Halt; refresh via `hstack-module-spec` first.
-- **Change-spec Invariants are present but generic ("no regressions").** Halt; the strategist cannot map tests to non-specific invariants. Ask the engineer to amend via `spec-author`.
-- **Validator fails TS-02 (fewer than three challenge prompts answered).** Halt; the subagent re-runs the missing prompt.
-- **Validator fails TS-03 (empty tenant-isolation-tests on a db/api/agent surface).** Halt; the subagent re-walks every new tenant-scoped surface and names a negative test.
-- **Validator fails TS-06 (an invariant is unmapped).** Halt; the subagent either adds a test for the unmapped invariant, surfaces it in the (b) challenge prompt with a defended rationale, or escalates to amend the invariant via `spec-author`.
-- **v1 framing slips in a rationale.** The Skill detects "verified by test execution" or "measured coverage" language and halts; the subagent re-words.

package/template/.claude/skills/hstack-ui-brief/SKILL.md

@@ -1,81 +0,0 @@
----
-name: hstack-ui-brief
-description: Use when a change-spec with `ui` in `surfaces` is at `ready-to-plan` or later and needs `ui-brief.md` drafted before Figma work and before `/hstack:change-plan` runs.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-MCP: Figma MCP — optional; enables richer reuse hints when present, falls back to URL-only references when absent}}"
-  - "node hstack/scripts/validate-spec.mjs — validates ui-brief frontmatter and UI-01/UI-02"
----
-
-## Purpose
-
-`hstack-ui-brief` produces `ui-brief.md` for a change touching the `ui` surface by orchestrating the `ui-ux-briefer` subagent. It is the upstream artifact for the cofounder's Figma work and a co-input for the implementer alongside `figma-handoff.md`. It is conditional on `surfaces` including `ui` and halts otherwise.
-
-## When to invoke
-
-Invoke after the change-spec reaches `status: ready-to-plan` and before `hstack-change-plan` runs, when the change-spec's `surfaces` includes `ui`. Re-invoke when the spec changes shape in ways the existing brief no longer reflects.
-
-## Inputs
-
-- `<change-id>` (required, positional): the change-spec id.
-
-## Preconditions
-
-Before any work:
-
-- Verify the change-spec exists at `hstack/specs/changes/<id>/spec.md` and is at `status: ready-to-plan` or later.
-- Verify `surfaces` includes `ui`. If not, halt with the surface-conditional message.
-- Verify the configured design-system resources are reachable per their declared source in `hstack/config.yaml` (`design-system.components.source`, `tokens.source`, `brand-guidelines.source`). For each resource the brief will need: `in-repo` paths must resolve; `figma-mcp` / `notion-mcp` sources require the corresponding MCP to be wired and reachable (UI-surface changes are high-stakes — graceful degradation is not safe here); `submodule` / `npm` / `external-other` must fetch. A resource at `source: none` is treated as "not yet captured" — halt if the brief genuinely needs it, otherwise proceed against the resources that ARE configured.
-- Verify the `design-system-version` declared in `hstack/config.yaml` is current and is what the brief will reference. Halt on drift.
-- Read the change-spec's `user-stories` array; verify each story is reachable in the configured store and read it. Halt if any linked story or its persona is missing. An empty `user-stories` is acceptable when the change is Category A (`internal-tooling: true`) — e.g., an internal dev dashboard — or Category B (`enables` non-empty) — e.g., a design-system primitive whose user-facing consumer is the downstream change. In the Category-B case, surface the upstream/downstream context: the brief still describes layout/copy for THIS change's UI, but the user-value story lives in the downstream spec named in `enables`.
-
-## Orchestration steps
-
-1. **Invoke `ui-ux-briefer`.** Use the Task tool with `subagent_type: ui-ux-briefer` and context = [kernel, `hstack/templates/ui-brief.md`, change-spec, linked stories, referenced personas, design-system components / tokens / brand-guidelines at the configured paths]. The subagent walks the six sections — Goal, Layouts and States, Reused Components, New Components, Copy, Accessibility Notes — with confirmation gates.
-
-2. **Exercise the new-component challenge.** Per the `ui-ux-briefer` contract, every entry in `new-components` carries a justification paragraph in section 4, elicited via the challenge "Why is this new and not a reuse?" The Skill does not bypass this.
-
-3. **Token-gap surfacing.** When the brief requires a value not in the design system's current token set, `ui-ux-briefer` names the gap and notes that a tech-debt item should be filed via `hstack-tech-debt-new` before implementation begins. The Skill does not file the tech-debt itself; it surfaces the recommendation and waits for the engineer to act.
-
-4. **Validate.** Run `node hstack/scripts/validate-spec.mjs <path>` against the in-progress brief — UI-01 (every `new-components` entry has a section-4 justification paragraph), UI-02 (`design-system-version` matches config).
-
-5. **Transition.** When every section is confirmed and the validator passes, `ui-ux-briefer` advances status from `draft` to `drafted`. Auto-commit fires.
-
-## Outputs
-
-- `hstack/specs/changes/<change-id>/ui-brief.md` at `status: drafted`.
-- Optional surfaced recommendation to author a tech-debt item for any design-token gap.
-
-## Auto-commit triggers
-
-- Status transition to `draft` after the first section confirms.
-- Status transition to `drafted` at the end. Commit message: `ui-brief(<change-id>): drafted`.
-- Edits to `new-components` array (because UI-01 enforcement depends on it).
-
-## Idempotency contract
-
-- Re-running on an existing `drafted` brief without changes: the subagent reads the existing instance as the proposal layer; identical re-confirmation is a no-op.
-- Re-running after a halt mid-brief: `ui-ux-briefer` reads the partial file and resumes at the next un-confirmed section.
-- Re-running after the change-spec's `surfaces` has been amended to drop `ui`: halt with the surface-conditional message; the existing brief is archived only on explicit engineer action.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The change-spec's `surfaces` does not include `ui`.
-- The configured design system docs are unreachable.
-- `design-system-version` in config has drifted from what the brief would target.
-- A new component's justification cannot be articulated under the challenge prompt — the signal that an existing component should be reused.
-- The brief requires a new design-system token and no tech-debt item exists or is filed concurrently.
-
-## Failure modes
-
-- **Linked story unreachable.** Halt; reconcile via `hstack-story-draft` or fix the change-spec's `user-stories` array.
-- **Figma MCP absent.** Degraded mode — `ui-ux-briefer` produces the brief without frame-content hints, flags in the conversation, continues.
-- **Validator fails UI-01 because a `new-components` entry has no body justification.** Halt; the subagent re-runs the challenge prompt for that component.