hstack 0.7.1 → 0.17.0

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

@@ -1,158 +0,0 @@
----
-name: hstack-tech-debt-resolve
-description: |
-  Use this skill when the engineer wants to start work on resolving a known tech-debt item. The Skill is the canonical entry point into the resolution flow: it prints the tech-debt's full body, walks each Pre-condition for engineer confirmation (a structured-elicitation loop per the kernel's Mechanical operations section), halts on any unmet pre-condition, and on confirmation performs direct mechanical writes (per ADR-0001, no spec-author invocation): flips the tech-debt to `in-progress`, scaffolds a resolution change folder with `resolves-tech-debt` pre-populated and the Acceptance section quoted into Target Behavior. Both halves of the reciprocal pair (TD ↔ change-spec) land in a single atomic commit. Examples:
-
-  <example>
-  Context: The team agreed to live with a hardcoded Tailwind class until the design token system exposed `--warning-yellow-300`. The token landed yesterday; now the team wants to fix TD-0042.
-  user: "/hstack:tech-debt-resolve TD-0042-overage-banner-tailwind-class"
-  assistant: "I'll print TD-0042 in full, walk each Pre-condition for your confirmation (the design token bullet should now be met), then flip the TD to in-progress and scaffold the resolution change-spec with the Acceptance section quoted into Target Behavior. After the scaffold, continue with /hstack:test-plan."
-  <commentary>
-  The Skill is the only authoring path that flips a tech-debt out of `open`. The kernel forbids manual frontmatter edits to tech-debt status. Pre-conditions are prose in v1 and require engineer confirmation; the Skill logs that confirmation into the scaffolded change-spec's Open Questions section so the adversarial-reviewer can later verify the team didn't rationalize away an unmet pre-condition.
-  </commentary>
-  </example>
-
-  <example>
-  Context: An engineer attempts to start resolving a tech-debt whose Pre-conditions reference an ADR that has not been accepted.
-  user: "/hstack:tech-debt-resolve TD-0019-event-ordering-fallback"
-  assistant: "I'll halt — TD-0019's Pre-conditions name 'ADR-0034 must be accepted before we pick a strategy', and ADR-0034 is at `proposed`. Resolve that first via /hstack:adr-new or by advancing ADR-0034 to `accepted`."
-  <commentary>
-  Some pre-conditions are mechanically checkable (ADR exists at `accepted`, file exists, related TD at `resolved`). The Skill checks those mechanically and halts on failure. Prose pre-conditions still require engineer confirmation. Mechanical halts cannot be overridden by engineer confirmation — the upstream artifact must actually change state first.
-  </commentary>
-  </example>
-
-  <example>
-  Context: An engineer wants to resolve a tech-debt but only partially — the change addresses 2 of 3 Acceptance bullets.
-  user: "/hstack:tech-debt-resolve TD-0027-rls-cleanup --partial"
-  assistant: "I'll halt — partial resolution is not supported in v1. Either author a new tech-debt via /hstack:tech-debt-new for the portion this change will fix and leave TD-0027 at `open`, or expand the change's scope to satisfy all Acceptance bullets."
-  <commentary>
-  Per the kernel's tech-debt resolution rules, a change-spec either fully resolves a TD or it doesn't. Partial work creates audit ambiguity ("did this fix it?") and breaks the AR-07 Acceptance-satisfied finding lens. The Skill refuses --partial flags and forces the engineer to make the split explicit.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — 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 — v1 does not support partial resolution.
-
-## 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 Resolution Log check.** If `## Resolution Log` is not present in the file (legacy TDs authored before the template included this section), append `\n## Resolution Log\n` to the end of the file first.
-   - 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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` 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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` 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."
-
-## 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 `validate-spec.ts`. Do not invoke `spec-author` for this reconciliation — the kernel forbids it for reciprocal-back-reference writes.
-
-## 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>`.
-
-## Anti-patterns
-
-- Never invoke `spec-author` for the TD status flip. Per the kernel's Mechanical operations section (ADR-0001), this Skill performs the flip directly via the `Edit` tool. The kernel's "spec-author is the only subagent permitted to write" rule applies to subagents; this Skill runs in the main session.
-- Never accept blanket "all pre-conditions are met" confirmations. Each bullet must be individually confirmed with a one-sentence justification.
-- Never silently downgrade a mechanical halt to a soft warning. Mechanical halts represent upstream state that must actually change.
-- Never scaffold without quoting the TD's Acceptance into the change-spec's Resolves Tech-Debt section. The quote is what AR-07 checks against.
-- Never accept `--partial`. Direct the engineer to split the TD via `/hstack:tech-debt-new` instead.
-- Never proceed when the TD is at a terminal status. Resolved is resolved; wontfix is final.

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

@@ -1,113 +0,0 @@
----
-name: hstack-tech-debt-stale
-description: |
-  Use this skill when a tech-debt item's original claim no longer reproduces because the surrounding code was rewritten, a dependency was upgraded, the bug was fixed incidentally as part of unrelated work, or the system the TD described no longer exists. This is distinct from `/hstack:tech-debt-wontfix`: wontfix says "the problem is still real but we choose to live with it"; stale-no-longer-reproducible says "the problem no longer exists, verifiably." The Skill runs a one-question structured-elicitation loop (a per-kernel Mechanical operations pattern), captures the verification evidence into the TD's frontmatter, and performs direct mechanical writes (per ADR-0001, no spec-author invocation): writes `stale-verified-at` and `stale-verification-method`, flips status `open → stale-no-longer-reproducible`, appends a Resolution Log entry, all in a single atomic commit. The new status is terminal — per TD-03, no field rewrites are permitted afterwards. Examples:
-
-  <example>
-  Context: TD-0042 captured a workaround needed because a Tiptap plugin had a known bug. The team upgraded Tiptap last week and the bug is fixed upstream; the workaround is still in the codebase but the underlying claim no longer holds.
-  user: "/hstack:tech-debt-stale TD-0042-tiptap-paste-workaround"
-  assistant: "I'll ask one question: what evidence shows the original claim no longer reproduces? On confirmation, the Skill writes stale-verified-at and stale-verification-method directly (per ADR-0001, no spec-author invocation), flips status to stale-no-longer-reproducible, and commits atomically. The new status is terminal."
-  <commentary>
-  Stale-no-longer-reproducible is the controlled exit for organic-decay closures. The kernel requires the verification evidence because "we don't reproduce it anymore" without an artefact is the kind of silent backlog-clearing that lets real debt slip through unaudited. Future engineers reading the TD see the explicit verification rather than just an unexplained closure.
-  </commentary>
-  </example>
-
-  <example>
-  Context: An engineer wants to use this Skill on a TD whose original problem IS still real but they no longer want to fix it.
-  user: "/hstack:tech-debt-stale TD-0017-prompt-template-string-concat"
-  assistant: "Wait — this is wontfix territory, not stale. Stale-no-longer-reproducible means the problem has verifiably gone away. If the prompt-template string-concat is still in the codebase and still has the original issue, the team is choosing to live with it (wontfix), not observing that it no longer exists (stale). I'll halt and direct you to /hstack:tech-debt-wontfix instead, OR you can show me evidence the string-concat code was actually removed and I'll proceed with stale."
-  <commentary>
-  The Skill applies a deliberate semantic check at the verification step. Misusing stale for a deferral-flavored closure corrupts the audit signal that distinguishes deliberate-deferral (wontfix) from organic-decay (stale). The engineer's verification evidence must describe an absence, not a preference.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — 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.
-
-## 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? Be specific — a grep result that returns nothing, a git log showing the dependent code was removed, a dependency upgrade that fixes the issue upstream, etc. (one sentence, ≤ 300 characters)". Capture the answer.
-
-3. **Semantic check.** If the answer reads like a deferral or a preference rather than an absence ("we don't care anymore", "not worth it", "moved on", "low priority", "not blocking us"), 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 length.** If the answer exceeds 300 characters, ask for a tighter version — stale verification methods are short, specific, and load-bearing. If the engineer cannot tighten below 300 chars without losing evidence, the verification probably isn't structural enough to qualify as stale; consider whether wontfix is the right path.
-
-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 Resolution Log check.** If `## Resolution Log` is not present in the file (legacy TDs authored before the template included this section), append `\n## Resolution Log\n` to the end of the file first.
-   - 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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the file. TD-07 (stale-no-longer-reproducible requires both `stale-verified-at` and `stale-verification-method` non-null) must pass once the validator ships; until then, the proposed-diff preview in step 4 is the v1 substitute per the kernel's AI writes / humans confirm clause. On validation pass (or v1 proposed-diff acknowledgement), `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 reads as a deferral or preference (per step 3). The Skill refuses to write and surfaces the wontfix recommendation.
-- The answer exceeds 300 characters and the engineer cannot tighten it without losing evidence. Halt and surface the wontfix recommendation — overly long stale verifications usually indicate the claim isn't actually absent.
-- 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.
-
-## Anti-patterns
-
-- Never accept a stale verification that reads as a deferral. The check is mandatory and is the v1 defense against misusing stale to clear backlog without an actual claim-absence verification.
-- Never write `status: stale-no-longer-reproducible` without both `stale-verified-at` and `stale-verification-method` non-null. TD-07 enforces this at validation (once the validator ships); the Skill's structured-elicitation loop enforces it at write time.
-- Never invoke `spec-author` for this transition. Per the kernel's Mechanical operations section (ADR-0001), this Skill performs the writes directly. The status flip, two field writes, and Resolution Log append land atomically in a single Skill-driven commit.
-- Never re-open a stale-no-longer-reproducible TD. Per TD-03, the status is terminal — author a new TD instead if the claim reappears.
-- Never use this Skill as a faster path to `wontfix`. The semantic distinction (absence vs choice) is load-bearing for audit signal honesty. If the engineer is tempted to bypass `wontfix`'s two-question discipline by routing through stale, the Skill's semantic check (step 3) is the v1 defense.

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

@@ -1,104 +0,0 @@
----
-name: hstack-tech-debt-wontfix
-description: |
-  Use this skill when a tech-debt item is being closed without a fix because the team has decided the cost of resolving exceeds the cost of living with it. The Skill runs a brief two-question interview (a structured-elicitation loop per the kernel's Mechanical operations section), captures the rationale into the TD's frontmatter, and performs direct mechanical writes (per ADR-0001, no spec-author invocation): writes `wontfix-reason` and `wontfix-accepted-alternative`, flips status `open → wontfix`, appends a Resolution Log entry, all in a single atomic commit. Wontfix is a terminal status — per TD-03, no field rewrites are permitted afterwards. Examples:
-
-  <example>
-  Context: TD-0017 captured a deliberate compromise that no longer matters — the surrounding code has been rewritten and the original compromise no longer exists.
-  user: "/hstack:tech-debt-wontfix TD-0017-prompt-template-string-concat"
-  assistant: "I'll ask two questions: (a) why won't this be fixed; (b) what we're accepting as the alternative. Both answers are required and become non-null wontfix-reason and wontfix-accepted-alternative frontmatter fields (TD-06). On confirmation, the Skill writes both fields and flips status to wontfix directly (per ADR-0001, no spec-author invocation) in a single auto-commit. Wontfix is terminal — no further edits."
-  <commentary>
-  Wontfix is the controlled escape valve for tech-debt that no longer warrants a fix. The kernel requires both fields because "we don't care anymore" without a recorded alternative is the kind of decision that comes back to bite the team six months later. Future engineers reading the TD see the explicit reasoning rather than a silent closure.
-  </commentary>
-  </example>
-
-  <example>
-  Context: An engineer wants to wontfix a tech-debt because they don't want to deal with it right now, not because the cost-benefit has actually flipped.
-  user: "/hstack:tech-debt-wontfix TD-0042-overage-banner-tailwind-class"
-  assistant: "I'll ask the two questions. If your answer to (a) is 'we don't have time' or 'we'll get to it later', I'll halt and surface that the right path is to leave the TD at `open` and re-prioritize, not to mark it wontfix. Wontfix is for compromises we've decided to live with permanently, not for deferrals."
-  <commentary>
-  The Skill applies a deliberate friction at the prose level: if the wontfix-reason reads like a deferral ("later", "not a priority", "we don't have bandwidth"), the Skill halts and asks the engineer to either commit to a real wontfix reason or leave the TD at `open`. Deferrals belong in the backlog, not in the wontfix log.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — 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). Do not invoke `spec-author` for the rollback — the kernel forbids it for status flips. 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? (one sentence, ≤ 200 characters)". Capture the answer.
-
-3. **Deferral check.** If the answer contains deferral indicators ("later", "not a priority", "no time", "we'll come back", "next quarter", "after X ships"), 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 Resolution Log check.** If `## Resolution Log` is not present in the file (legacy TDs authored before the template included this section), append `\n## Resolution Log\n` to the end of the file first.
-   - 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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` 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.
-- Either answer exceeds 200 characters. Ask for a tighter version — wontfix rationales are short and load-bearing.
-- 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 prose-level check in step 3 is the v1 defense. v2 substrate could add LLM-graded rationale assessment, but v1 trusts the engineer's willingness to be honest with themselves.
-
-## Anti-patterns
-
-- Never accept a wontfix-reason that reads as a deferral. The check is mandatory and is the only friction protecting against backlog amnesia.
-- Never write `status: wontfix` without both rationale fields non-null. TD-06 enforces this at validation.
-- Never re-open a wontfix TD. Per TD-03, wontfix is terminal — author a new TD instead.
-- Never invoke `spec-author` for the wontfix transition. Per the kernel's Mechanical operations section (ADR-0001), this Skill performs the writes directly. The three writes (status, wontfix-reason, wontfix-accepted-alternative) plus the Resolution Log append land atomically in a single Skill-driven commit.

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

@@ -1,98 +0,0 @@
----
-name: hstack-telemetry
-description: |
-  Use this skill when the engineer wants a retrospective observability report — token economics, workflow shape, quality outcomes, overengineering detection, and contract drift — generated from on-disk artifacts, git history, and Claude Code transcripts. Read-only across every source; no subagents invoked, no LLM turns, safe to run any time.
-
-  <example>
-  Context: The engineer wants a weekly health check on the hstack workflow.
-  user: "/hstack:telemetry"
-  assistant: "I'll run the telemetry report against this repo with a 30-day window. Output lands at `hstack/telemetry/reports/<today>.md`. No subagents, no LLM turns — pure derivation from frontmatter + git + transcripts."
-  <commentary>
-  Default mode. The Skill shells out to `python hstack/scripts/telemetry/report.py` and reports the output path. The kernel's "no parallel tracker" rule is preserved because the report is derivative — re-runnable from source, never authoritative.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The engineer wants a deeper history window than the default 30 days.
-  user: "/hstack:telemetry --window 90"
-  assistant: "I'll run the report with a 90-day window. Larger windows surface more contract-drift signal (TD half-life, module-spec staleness) at the cost of slower transcript walks."
-  <commentary>
-  The Skill passes `--window <N>` through to the underlying script. A window of 0 means all-history; use sparingly on repos with months of transcript data.
-  </commentary>
-  </example>
-
-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.
-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, 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).
-
-## 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.
-
-## Anti-patterns
-
-- Never claim the telemetry report is authoritative. It is derivative of frontmatter, git, and transcripts — re-runnable from source. The kernel's "no parallel tracker" rule applies.
-- Never use the report as an input to a Skill that writes artifacts. It is a retrospective lens, not an in-flight signal.
-- Never delete reports to manipulate trend lines. Old reports are git-tracked and can be referenced for retrospective comparison.
-- Never propose a v2 "agent-ledger" rebrand of this tool without first running it for at least 3 months and finding the data layer worth promoting.