hstack 0.7.0 → 0.16.0

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

@@ -1,25 +1,6 @@
 ---
 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>
+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
@@ -28,7 +9,7 @@ tools:
   - 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)}}"
+  - "node hstack/scripts/validate-spec.mjs — validates the TD frontmatter flip and TD-06 (wontfix-reason and wontfix-accepted-alternative both non-null)"
 ---
 
 ## Purpose
@@ -45,26 +26,26 @@ Invoke when a tech-debt item at `status: open` will not be fixed and the team ha
 
 ## 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.
+- 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? (one sentence, ≤ 200 characters)". Capture the answer.
+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.** 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.
+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 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.
+   - 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 `{{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>`.
+   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."
 
@@ -88,17 +69,9 @@ 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.
+- **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,26 +1,6 @@
 ---
 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>
-
+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
@@ -33,14 +13,14 @@ tools:
 
 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.
+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, high-severity findings resolved as `justified-in-prose`, candidate test-immutability violations, scope-amendment rate above 30%, module drift, fired kernel-fit patterns).
+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
 
@@ -52,6 +32,8 @@ Run any time. Common cadence:
 
 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.
@@ -89,10 +71,3 @@ Re-running on the same day overwrites the same-day report file. Different window
 - `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.

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

@@ -1,34 +1,6 @@
 ---
 name: hstack-test-plan
-description: |
-  Use this skill when a change-spec is at `status: ready-to-plan` and needs `test-plan.md` produced before the planner can sequence implementation phases. The Skill orchestrates the `test-strategist` subagent. In v1 the output is an LLM-strategized judgment (`scoring-mode: llm-strategized`), not coverage-instrumented or mutation-tested — the Skill enforces this framing on every output. Examples:
-
-  <example>
-  Context: A change-spec adds a new RLS-protected table and a tenant-scoped RPC; it is at ready-to-plan.
-  user: "/hstack:test-plan 2026-06-knowledge-citations"
-  assistant: "I'll invoke test-strategist. Surfaces is [db, api] so tenant-isolation tests are mandatory and non-empty. The plan will name a negative cross-tenant RPC test, declare the fixture strategy, and answer the three challenge prompts before status can advance."
-  <commentary>
-  The Skill is the only authoring path for test-plan.md. It enforces TS-03 (tenant-isolation-tests non-empty when surfaces includes db/api/agent) and TS-02 (three challenge prompts mandatory). v1 framing is enforced on every rationale paragraph.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A change touches a hot-path retrieval endpoint that other services depend on for latency.
-  user: "/hstack:test-plan 2026-05-retrieval-rpc-rewrite"
-  assistant: "I'll invoke test-strategist with performance-budgets-required: true. Each row in the budgets table pairs a numeric threshold with an asserting test; budgets without tests are refused."
-  <commentary>
-  The performance-budget contract is the v1 mitigation for "we said it had to be fast" promises that never get enforced. The Skill verifies every populated budget row has both a numeric threshold and a named asserting test before terminal status.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A small refactor with no behavior change but adjacent to authentication code.
-  user: "/hstack:test-plan 2026-05-auth-helper-rename"
-  assistant: "I'll invoke test-strategist. Even on a refactor, the three challenge prompts run — silent-pass-but-break behavior, invariant without mapped test, untested failure scenario. Refactors near auth are exactly where strategy surfaces hidden risk."
-  <commentary>
-  Refactors are not exempt from the challenge prompts. The v1 honesty clause forbids skipping them. A refactor near auth that ships without these prompts answered is a regression risk that no other artifact will catch.
-  </commentary>
-  </example>
+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
@@ -37,7 +9,7 @@ tools:
   - Glob
   - Bash
   - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates test-plan frontmatter and TS-01..TS-06}}"
+  - "node hstack/scripts/validate-spec.mjs — validates test-plan frontmatter and TS-01..TS-06"
 ---
 
 ## Purpose
@@ -71,6 +43,8 @@ Before any work:
 
 ## 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.
@@ -83,11 +57,11 @@ Before any work:
 
 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 verbatim:
+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."
-   Each answer is at least one paragraph. The Skill verifies `challenge-prompts-answered: 3` in frontmatter.
+   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.
 
@@ -97,7 +71,7 @@ Before any work:
 
 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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` — 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`).
+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
 
@@ -118,9 +92,12 @@ At the terminal-status auto-commit above (`test-plan(<change-id>): passed` or `c
 
 ```json
 {
-  "schema_version": 1,
+  "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>},
@@ -140,6 +117,18 @@ At the terminal-status auto-commit above (`test-plan(<change-id>): passed` or `c
 
 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.
@@ -168,15 +157,3 @@ Beyond the kernel's general stop conditions:
 - **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.
-
-## Anti-patterns
-
-- Never plan a behavior coverage strategy that depends primarily on e2e. The pyramid bias is load-bearing.
-- Never write a performance budget without a paired asserting test. Budgets without tests are wishes.
-- Never mark a coverage layer `addressed` without concrete test file paths.
-- Never claim coverage-measured or mutation-tested evidence in v1. The honesty clause is load-bearing.
-- Never skip or paraphrase a challenge prompt. The three are verbatim and mandatory.
-- Never produce a test-plan whose `tenant-isolation-tests` array is empty when surfaces includes db/api/agent.
-- Never fabricate test file paths, factory module names, or surface identifiers.
-- Never write `concerns-acknowledged-by` without the owner's confirmed acknowledgement.
-- Never file tech-debt from this Skill; surface the recommendation for the engineer to invoke `hstack-tech-debt-new`.

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

@@ -1,25 +1,6 @@
 ---
 name: hstack-ui-brief
-description: |
-  Use this skill when a change-spec at `ready-to-plan` or later has `ui` in its surfaces and needs `ui-brief.md` drafted before the cofounder produces Figma frames and before `hstack-change-plan` runs. The Skill orchestrates the `ui-ux-briefer` subagent against the configured design system docs. Examples:
-
-  <example>
-  Context: The billing-overage change-spec is at ready-to-plan with surfaces: [ui, db]; the cofounder is about to start Figma work and needs the brief first.
-  user: "/hstack:ui-brief 2026-05-billing-overage-warning"
-  assistant: "I'll invoke ui-ux-briefer with the design system docs, the change-spec, the linked story, and the growth-marketer persona. Reused components first; any new component carries a justification per UI-01."
-  <commentary>
-  The Skill is the only entry point for ui-brief production. It enforces the reuse-bias by relying on the subagent's challenge prompt and the validator's UI-01 rule. Skipping the Skill and letting the cofounder freelance in Figma erodes the design system.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A change-spec without `ui` in surfaces is mistakenly passed to this Skill.
-  user: "/hstack:ui-brief 2026-05-internal-cron-rebuild"
-  assistant: "I'll halt — surfaces on that change-spec is [api, infra], no ui. The ui-brief is conditional and is not produced for changes without ui surfaces."
-  <commentary>
-  The surface-conditional gate is hard. Producing a ui-brief for a non-ui change inflates the artifact count and slows the merge without value.
-  </commentary>
-  </example>
+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
@@ -29,7 +10,7 @@ tools:
   - Bash
   - Task
   - "{{TODO-MCP: Figma MCP — optional; enables richer reuse hints when present, falls back to URL-only references when absent}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates ui-brief frontmatter and UI-01/UI-02}}"
+  - "node hstack/scripts/validate-spec.mjs — validates ui-brief frontmatter and UI-01/UI-02"
 ---
 
 ## Purpose
@@ -62,7 +43,7 @@ Before any work:
 
 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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the in-progress brief — UI-01 (every `new-components` entry has a section-4 justification paragraph), UI-02 (`design-system-version` matches config).
+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.
 
@@ -98,11 +79,3 @@ Beyond the kernel's general stop conditions:
 - **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.
-
-## Anti-patterns
-
-- Never invent a new component when composition of existing primitives would work. The challenge prompt exists to force this discipline.
-- Never paste design-token values inline. Use named tokens; gaps are flagged for tech-debt.
-- Never produce a ui-brief for a non-ui change. The conditional is hard.
-- Never write Figma frame URLs in the ui-brief — that is `figma-handoff.md`'s domain (the cofounder's deliverable).
-- Never silently brief against a stale design-system version.

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

@@ -1,34 +1,6 @@
 ---
 name: hstack-verify
-description: |
-  Use this skill after the implementer has completed every phase of the plan and the engineer wants `verification.md` produced from test, lint, and typecheck outcomes. The Skill orchestrates the `verifier` subagent — a mechanical role that runs the canonical commands from `ci-cd.md`, captures the output, and compares observed outcomes against each phase's Verifier Expectations. Examples:
-
-  <example>
-  Context: The implementer just finished phase-5 of the billing-overage plan and the engineer wants verification before adversarial review.
-  user: "/hstack:verify 2026-05-billing-overage-warning"
-  assistant: "I'll invoke verifier. It will run the canonical test/lint/typecheck commands from ci-cd.md, capture stdout/stderr to a pointer file, and write phase-coverage mirroring plan.steps-completed."
-  <commentary>
-  The verifier is mechanical and conservative. Any `failed` test result blocks status `passed` (V-02); discrepancies between predicted and observed test behavior land in section 4 with recommended actions.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The test suite passed locally but the verifier observes that a Playwright test the plan promised actually skipped.
-  user: "/hstack:verify 2026-06-knowledge-citations"
-  assistant: "I'll invoke verifier. If a phase's Verifier Expectations name a test that skipped or is absent, the Discrepancies section captures it and the Skill refuses to mark status passed."
-  <commentary>
-  Discrepancies between predicted and observed behavior are exactly what section 4 exists to capture. Marking `passed` over a discrepancy would defeat the purpose of the gate.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The integration suite is gated by `RUN_INTEGRATION=1` and the engineer ran `npm test` without setting it; the runner reported `Tests: 0 passed, 0 failed`.
-  user: "/hstack:verify 2026-06-knowledge-citations"
-  assistant: "I'll invoke verifier. Per V-05, an integration suite that executed zero tests is recorded as `not-run`, not `pass` — zero failures is not evidence of correctness when there were zero assertions to fail. The Skill halts at `status: ran` with a high-severity Discrepancy naming the suspected reason (env-gated, all-skipped, empty-collection, or filter-collapse)."
-  <commentary>
-  V-05 closes the verifier false-positive where a suite gated by an unset env var would silently pass on the absence of failures. The remediation is either supplying the missing env / fixture and re-running, or amending the plan's Verifier Expectations via scope amendment so the zero-test state is intentional and recorded.
-  </commentary>
-  </example>
+description: Use after `plan.steps-completed` covers every phase in the plan body and the change needs `verification.md` from the canonical test, lint, and typecheck runs. A partial verification run is meaningless.
 tools:
   - Read
   - Write
@@ -37,8 +9,8 @@ tools:
   - Glob
   - Bash
   - Task
-  - "{{TODO-SCRIPT: hstack/scripts/run-gates.sh — runs the consuming repo's test/lint/typecheck suite and captures output, including an observed-test-count per suite for V-05}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates verification.md frontmatter and V-01/V-02/V-05}}"
+  - "hstack/scripts/run-gates.sh — runs the consuming repo's test/lint/typecheck suite and captures output, including an observed-test-count per suite for V-05"
+  - "node hstack/scripts/validate-spec.mjs — validates verification.md frontmatter and V-01/V-02/V-05"
 ---
 
 ## Purpose
@@ -65,13 +37,15 @@ Before any work:
 
 ## Orchestration steps
 
-1. **Invoke `verifier`.** Use the Task tool with `subagent_type: verifier` and context = [kernel, `hstack/templates/verification.md`, change-spec, plan, test-plan, ci-cd]. The subagent runs the canonical commands declared in `ci-cd.md` (or orchestrates `{{TODO-SCRIPT: hstack/scripts/run-gates.sh}}`).
+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.
 
-2. **Capture output.** The subagent writes captured stdout/stderr to a pointer file at `hstack/specs/changes/<change-id>/test-output.txt` and references it from `verification.artifacts.test-output`.
+1. **Invoke `verifier`.** Use the Task tool with `subagent_type: verifier` and context = [kernel, `hstack/templates/verification.md`, change-spec, plan, test-plan, ci-cd]. The subagent runs `hstack/scripts/run-gates.sh --change <change-id> --json`, which executes the canonical commands declared in `ci-cd.md` § Canonical Commands — every one of them, and nothing else. Extending the canonical command set is `hstack-configure --interview ci-cd`, not an ad-hoc addition here.
+
+2. **Capture output.** `run-gates.sh` writes the captured stdout/stderr to `hstack/specs/changes/<change-id>/test-output.txt`; the subagent references that path from `verification.artifacts.test-output`.
 
 3. **Phase coverage mapping.** For each phase in `plan.steps-completed`, the subagent emits an entry in `phase-coverage` with a PASS / FAIL value computed from whether the phase's Verifier Expectations are met. Per V-01, `phase-coverage` keys must equal `plan.steps-completed`.
 
-4. **Test-results map.** The subagent writes the top-level `test-results` map covering `unit`, `integration`, `e2e`, `lint`, `typecheck`. Per V-02, any `failed` value blocks `status: passed`. Per V-05, before mapping `unit`, `integration`, or `e2e` to `pass`, the subagent confirms the runner's observed-test-count for that suite is greater than zero — a suite gated by an unset env var, all-skipped, empty-collection, or filter-collapsed to zero tests is recorded as `not-run` with a high-severity Discrepancy, not as `pass` on the absence of failures.
+4. **Test-results map.** The subagent writes the top-level `test-results` map covering `unit`, `integration`, `e2e`, `lint`, `typecheck`. Per V-02, any `failed` value blocks `status: passed`. Per V-05, before mapping `unit`, `integration`, or `e2e` to `pass`, the subagent confirms the runner's observed-test-count for that suite is greater than zero — a suite gated by an unset env var, all-skipped, empty-collection, or filter-collapsed to zero tests is recorded as `not-run` with a high-severity Discrepancy, not as `pass` on the absence of failures. The Skill propagates the zero-tests-ran signal from the runner output into the subagent's context so the rule is enforceable rather than inferred.
 
 5. **Test-plan coverage check.** The subagent walks the test-plan's Edge Cases bullets, Tenant Isolation Tests array, and Performance Budgets table, and confirms each observed in the test run. `test-plan-coverage` frontmatter map captures the three subsections. Per V-03, any tenant-isolation test absent or skipped blocks `status: passed` and is escalated to adversarial-review via Discrepancies. Per V-04, any performance-budget assertion that did not execute or that observed values outside the declared budget blocks `status: passed`.
 
@@ -79,9 +53,9 @@ Before any work:
 
 7. **Status transition.** When every `phase-coverage` entry is PASS, every `test-results` entry is `pass`, every `test-plan-coverage` value is `all-observed` / `all-within-budget` / `not-applicable`, the subagent advances status to `passed`. When any test result is `failed`, when a tenant-isolation test is missing, or when a performance-budget regressed or did not execute, status moves to `ran` (not `passed`) and the Skill halts.
 
-8. **Change-spec advance (mechanical, only on `passed`, Skill-orchestrator write per ADR-0002).** When and only when the subagent returned with `verification.md` at `status: passed`, read `hstack/specs/changes/<change-id>/spec.md` and inspect its `status` frontmatter. If `status: ready-for-implementation`, print a proposed-diff preview of the change-spec edit (`status: ready-for-implementation → ready-for-review`; `updated: <today>`) and prompt "Proceed with this change-spec advance? (Y/n)". Default Yes. On confirmation, perform the edit via the `Edit` tool, run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the change-spec, then `git add` and commit with message `change-spec(<change-id>): ready-for-review`. This is a separate commit from the `verification(<change-id>): passed` commit — one commit per status transition, matching the finalize precedent. If the change-spec is already at `ready-for-review` or any downstream status, this step is a no-op (idempotent on re-runs). When verification status is `ran` or `failed`, this step does not run — the change-spec remains at `ready-for-implementation` until a subsequent re-run lands `passed`. Do NOT invoke `spec-author` for this write; per the kernel's Mechanical operations section, the value to write is fully determined by the verification postcondition and the change-spec's current status, so the Skill writes directly.
+8. **Change-spec advance (mechanical, only on `passed`, Skill-orchestrator write per ADR-0002).** When and only when the subagent returned with `verification.md` at `status: passed`, read `hstack/specs/changes/<change-id>/spec.md` and inspect its `status` frontmatter. If `status: ready-for-implementation`, print a proposed-diff preview of the change-spec edit (`status: ready-for-implementation → ready-for-review`; `updated: <today>`) and prompt "Proceed with this change-spec advance? (Y/n)". Default Yes. On confirmation, perform the edit via the `Edit` tool, run `node hstack/scripts/validate-spec.mjs <path>` against the change-spec, then `git add` and commit with message `change-spec(<change-id>): ready-for-review`. This is a separate commit from the `verification(<change-id>): passed` commit — one commit per status transition, matching the finalize precedent. If the change-spec is already at `ready-for-review` or any downstream status, this step is a no-op (idempotent on re-runs). When verification status is `ran` or `failed`, this step does not run — the change-spec remains at `ready-for-implementation` until a subsequent re-run lands `passed`.
 
-9. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` — V-01, V-02, V-03, V-04, V-05.
+9. **Validate.** Run `node hstack/scripts/validate-spec.mjs <path>` — V-01, V-02, V-03, V-04, V-05.
 
 ## Outputs
 
@@ -101,9 +75,12 @@ At the change-spec advance commit (only when verification status is `passed`), w
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "hstack-verify",
   "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>",
   "ran_at": "<ISO-8601, when canonical commands started>",
   "test_suite_runtime_s": <float seconds, wall clock across canonical commands>,
   "phase_coverage": {<mirror of verification.md frontmatter>},
@@ -115,6 +92,18 @@ At the change-spec advance commit (only when verification status is `passed`), w
 
 When verification ends at `ran` or `failed`, the sidecar still lands with `status` reflecting the canonical artifact status; the change-spec advance commit does not happen, so the sidecar piggybacks on the `verification(<change-id>): ran` (or `failed`) commit instead. `.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
+
+`verify` is a natural session cut: the auto-commit above left `verification.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: verify complete — cut recommended before adversarial-review.
+```
+
+and the next command, `/hstack:adversarial-review <change-id>`.
+
 ## Idempotency contract
 
 - Re-running on a `passed` verification: the subagent re-runs the canonical commands; identical outcomes produce a no-op aside from `updated` timestamps; different outcomes (newly failing test on a flake) update the artifact accordingly.
@@ -137,14 +126,3 @@ Beyond the kernel's general stop conditions:
 - **Environment misconfiguration prevents a canonical command from running.** Halt before invoking the subagent; surface the issue and the resolution.
 - **A test file the plan promised does not exist.** Halt; this is a discrepancy between plan and reality — surface as a Discrepancy and refuse `status: passed`.
 - **The subagent's test runner produces a runtime error (not a test failure).** Surface in Discrepancies; do not record as a PASS or FAIL on the affected suite.
-
-## Anti-patterns
-
-- Never invent a PASS. If tests are not green, status is `ran` or `failed`, not `passed`.
-- Never record a suite as `pass` on the absence of failures alone (V-05). A suite that ran zero tests — gated by an unset env var, all `.skip` / `.todo`, empty collection, or filter-collapsed — is `not-run`, not `pass`. The Skill propagates the zero-tests-ran signal from the runner output into the subagent context so the rule is enforceable rather than inferred.
-- Never skip a canonical command. The consuming repo's commands in `ci-cd.md` are mandatory.
-- Never silently drop a discrepancy. Even benign discrepancies get a one-line note.
-- Never score security or data. Stay in the mechanical-verification lane.
-- Never modify code or tests to make verification pass. That requires a new `hstack-implement` invocation.
-- Never claim phase coverage for phases not in `plan.steps-completed`.
-- Never run any command not declared in `ci-cd.md`. Extending the canonical command set requires `hstack-configure --interview ci-cd`.