hstack 0.7.0 → 0.16.0

package/template/.claude/skills/hstack-kernel-fit-triage/SKILL.md

@@ -1,35 +1,6 @@
 ---
 name: hstack-kernel-fit-triage
-description: |
-  Use this skill when the engineer wants to triage an open kernel-fit finding — either acknowledge it (intent to act, not yet promoted) or dismiss it (won't pursue). The Skill is mechanical per ADR-0001: structured-elicitation loop, proposed-diff preview, Y/n confirmation, direct `Edit` writes, one atomic commit. No subagent invoked. Promotion to an ADR is a separate Skill (`/hstack:kernel-fit-promote`); this Skill never touches ADRs or change-specs. Examples:
-
-  <example>
-  Context: The engineer received a Slack nudge about KF-0001 (KF-P1, Category-A claim with production paths) and wants to acknowledge it for later promotion.
-  user: "/hstack:kernel-fit-triage KF-0001 --action acknowledge"
-  assistant: "I'll read KF-0001, print it in full, show the proposed-diff (status: open → acknowledged; owner: <git-handle>; updated: today; Triage Log entry appended), wait for Y/n, then Edit + commit `kernel-fit(KF-0001): acknowledge`. No reason is required for acknowledge. If you later decide to promote, run `/hstack:kernel-fit-promote KF-0001 --slug <adr-slug>`."
-  <commentary>
-  Acknowledge does not require a `--reason`. It is the "I've seen this, I intend to act, but I'm not promoting yet" state. The Triage Log records the transition. The finding stays at `status: acknowledged` until promote or dismiss happens.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The engineer reviewed KF-0002 and decided the pattern is engineer-error, not a kernel gap.
-  user: "/hstack:kernel-fit-triage KF-0002 --action dismiss --reason \"The two changes flagged actually do have downstream consumers; the change-specs simply omitted the user-stories array because the engineer copied an old template. Not a kernel-flag issue, just stale boilerplate.\""
-  assistant: "I'll verify the reason is ≥50 characters (KF-05), read KF-0002, print the proposed-diff (status: open → dismissed; dismissed-reason: <text>; owner; updated; Triage Log entry), wait for Y/n, then commit `kernel-fit(KF-0002): dismiss`. Dismissal is terminal — re-running on this finding will surface that it's already dismissed and exit no-op."
-  <commentary>
-  Dismissal requires a reason of ≥50 characters per KF-05. The check is mechanical at validation time; the Skill enforces it at step 2. Drive-by dismissals are exactly the failure mode the rule exists to catch. The dismissed-reason is itself audit signal — a high rate of dismissals on a given pattern means either the pattern is poorly tuned or the engineer is gaming the gate.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The engineer tries to dismiss a finding with too-short reason.
-  user: "/hstack:kernel-fit-triage KF-0003 --action dismiss --reason \"not relevant\""
-  assistant: "I'll halt — `dismissed-reason` is 12 characters; KF-05 requires ≥50. Drive-by dismissals defeat the audit signal. Either provide a more substantive reason or leave the finding at `open` (open is a legitimate long-term state when triage is genuinely deferred)."
-  <commentary>
-  Short-reason rejection is a hard halt. The Skill does not negotiate — write a real reason or leave the finding alone. Same shape as the deferral-check in `hstack-tech-debt-wontfix`.
-  </commentary>
-  </example>
-
+description: Use to acknowledge or dismiss an open kernel-fit finding. The second step of the kernel-fit loop — it only flips status and records a rationale; elevating a finding to an ADR is `/hstack:kernel-fit-promote`.
 tools:
   - Read
   - Write
@@ -37,7 +8,7 @@ tools:
   - Grep
   - Glob
   - Bash
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates the finding frontmatter flip and KF-05 (dismissed-reason ≥50 chars when status: dismissed)}}"
+  - "node hstack/scripts/validate-spec.mjs — validates the finding frontmatter flip and KF-05 (dismissed-reason non-null when status: dismissed)"
 ---
 
 ## Purpose
@@ -51,7 +22,7 @@ This Skill does not promote findings to ADRs. Promotion is a separate Skill (`/h
 Invoke when a finding is at `status: open` and the engineer wants to:
 
 - **Acknowledge** (`--action acknowledge`): record intent to act on the finding without committing to an ADR yet. Useful when the finding is real but the team needs more thinking time, or when the right kernel-change shape is unclear.
-- **Dismiss** (`--action dismiss --reason <text>`): close the finding without pursuing a kernel change. The reason is mandatory (≥50 characters per KF-05) and becomes part of the audit trail.
+- **Dismiss** (`--action dismiss --reason <text>`): close the finding without pursuing a kernel change. The reason is mandatory (KF-05) and becomes part of the audit trail.
 
 For findings already at `acknowledged`, re-invoking with `--action acknowledge` is a no-op; re-invoking with `--action dismiss --reason <text>` is permitted (acknowledged → dismissed is a valid transition when the engineer reconsiders). Findings at terminal status (`dismissed`, `promoted`, `superseded`, `archived`) are immutable from this Skill's perspective — the Skill halts.
 
@@ -59,25 +30,25 @@ For findings already at `acknowledged`, re-invoking with `--action acknowledge`
 
 - `<finding-id>` (required, positional): the finding id, e.g. `KF-0001-category-a-claim-spans-production` or the short form `KF-0001` (the Skill resolves the latter to the matching file via glob).
 - `--action <acknowledge | dismiss>` (required): the triage action.
-- `--reason <text>` (required when `--action dismiss`; forbidden when `--action acknowledge`): the dismissal rationale. Must be ≥50 characters per KF-05.
+- `--reason <text>` (required when `--action dismiss`; forbidden when `--action acknowledge`): the dismissal rationale. It has to say what about the finding is wrong or not worth acting on, specifically enough that a reader six months from now can tell whether the dismissal still holds. "Not relevant" gives them nothing to check; "the kernel gives a norm here, not a bound" gives them everything, in forty-one characters. Length is not the test and is not checked (ADR-0014).
 
 ## Preconditions
 
 - `hstack/kernel-fit/findings/<finding-id>*.md` exists. If missing, halt.
 - The finding is at `status: open` (or `acknowledged` when transitioning to `dismissed`). If at any other status, halt with the current status named and the explanation that the status is terminal.
 - `--action` is one of `acknowledge | dismiss` (controlled enum).
-- When `--action dismiss`, `--reason` is non-empty and ≥50 characters.
+- When `--action dismiss`, `--reason` is non-empty and re-evaluable by a later reader per the Inputs section. When it is not — the reason restates the finding, or asserts a preference with no referent — say so and ask for the specific claim; do not write the dismissal.
 - When `--action acknowledge`, `--reason` is absent (the Skill rejects redundant reasons to keep the audit signal clean — acknowledge reasons live in the next promote / dismiss invocation if needed).
 
 ## Orchestration steps
 
 1. **Resolve the finding file.** Glob `hstack/kernel-fit/findings/<finding-id>*.md`. If zero matches, halt. If multiple matches (shouldn't happen with the immutable-id rule, but defense in depth), halt and ask the engineer to disambiguate.
 
-2. **Validate inputs against preconditions.** Walk the precondition checks above. On any failure, halt with the named reason. For the `--reason` length check (`dismiss`), surface the actual character count in the halt message so the engineer can size their next attempt.
+2. **Validate inputs against preconditions.** Walk the precondition checks above. On any failure, halt with the named reason. When the failure is the `--reason` (`dismiss`), quote the reason back and name what is missing from it — the claim it makes, or the referent it lacks — so the engineer knows what to write rather than how long to write.
 
 3. **Print the finding in full.** Read the resolved file and print its full body to the conversation. The engineer should re-read before committing to the triage action.
 
-4. **Compose the frontmatter edit.** Compute the exact frontmatter changes:
+4. **Compose the frontmatter edit.** These fields, and only these, are triage's to write — `pattern`, `evidence-rows`, `evidence-row-count` and `confidence` are the analyst's domain and are never edited here. Compute the exact frontmatter changes:
 
    For `--action acknowledge`:
    - `status: open → acknowledged`
@@ -102,15 +73,15 @@ For findings already at `acknowledged`, re-invoking with `--action acknowledge`
    - `status: <prev> → dismissed` on <today> by <owner>. Reason: <dismissed-reason>.
    ```
 
-   Defensive Triage Log check: if `## Triage Log` is not present in the file (legacy findings authored before the template included this section), append `\n## Triage Log\n` to the end of the file first.
+   Defensive log-header check per the kernel: if `## Triage Log` is absent, append it before writing the entry.
 
-6. **Print the proposed diff.** Show the engineer the exact frontmatter changes and the exact Triage Log entry that will land. This is the kernel's mechanical-operations confirmation gate — until `validate-spec.ts` ships, the proposed-diff preview is the only contract check between the `Edit` and the commit.
+6. **Print the proposed diff.** Show the engineer the exact frontmatter changes and the exact Triage Log entry that will land. This is the kernel's mechanical-operations confirmation gate: the engineer sees what will land before it lands. The validator run in step 7 is the mechanical half of the same check.
 
 7. **Confirm.** Print "Apply triage to <finding-id>? (Y/n)". Default Yes. On `n`, abort without writing.
 
 8. **Edit + validate + commit.** On `Y`:
    - `Edit` the file: frontmatter changes + Triage Log append.
-   - Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the file. KF-01 through KF-05 must pass; specifically KF-05 (`dismissed-reason` non-null and ≥50 chars when `status: dismissed`) gates dismissal.
+   - Run `node hstack/scripts/validate-spec.mjs <path>` against the file. KF-01 through KF-05 must pass; specifically KF-05 (`dismissed-reason` non-null when `status: dismissed`) gates dismissal.
    - On validation pass: `git add` the file and commit with message `kernel-fit(<finding-id>): <action>` (e.g. `kernel-fit(KF-0001): acknowledge`).
    - On validation failure: halt; revert via `git checkout -- <finding-file>`. Report the failing rule to the engineer.
 
@@ -138,7 +109,7 @@ Beyond the kernel's general stop conditions:
 
 - The finding does not exist or is at a terminal-from-triage status (`dismissed`, `promoted`, `superseded`, `archived`). Halt with the status named.
 - `--action` is missing or not in the enum. Halt with usage.
-- `--action dismiss` without `--reason`, or with `--reason` <50 characters. Halt with the actual length count.
+- `--action dismiss` without `--reason`, or with a `--reason` that restates the finding instead of answering it. Halt, quote it back, and name what is missing.
 - `--action acknowledge` with `--reason` present. Halt — acknowledge does not take a reason.
 - The engineer declines confirmation at step 7. Abort cleanly.
 - Validator fails at step 8 — halt with the failing rule; revert the unstaged edit.
@@ -146,14 +117,5 @@ Beyond the kernel's general stop conditions:
 ## Failure modes
 
 - **Edit fails (filesystem, validator, git).** The frontmatter flip and the Triage Log append must land together in a single auto-commit. If `Edit` succeeds but `git add` or `git commit` fails, the working tree carries the unstaged change — revert via `git checkout -- <finding-file>` and re-invoke.
-- **Drive-by dismissal attempt.** The ≥50-character check at step 2 is the v1 defense. Short reasons fail before any write occurs.
+- **Drive-by dismissal attempt.** The re-evaluability judgment at step 2 is the v1 defense: the reason is read against the finding the Skill just resolved, and one that gives a later reader nothing to check is quoted back before any write occurs.
 - **Stale finding (post-scan supersession in flight).** If a concurrent `/hstack:kernel-fit-scan` has just superseded the finding the engineer is triaging, the post-edit validator would catch the inconsistent state (superseded finding cannot be re-triaged). Halt and let the engineer re-fetch the working tree.
-
-## Anti-patterns
-
-- Never invoke a subagent for triage. The action's value is fully determined by `--action` and `--reason`; the kernel's Mechanical operations section requires direct Skill writes for cases like this (saving ~25k subagent-context tokens per call).
-- Never accept a dismissal reason shorter than 50 characters. The audit signal depends on substantive rationales — drive-bys defeat the loop.
-- Never edit a finding's `pattern`, `evidence-rows`, `confidence`, or `evidence-row-count` fields. Those are the analyst's domain; triage only flips `status`, sets `owner` / `updated`, and writes `dismissed-reason` (when dismissing).
-- Never edit a `promoted` finding's `promoted-to` field. That is owned by `/hstack:kernel-fit-promote` and is reciprocally bound to the target ADR.
-- Never re-open a `dismissed` or `superseded` finding. If the kernel-fit pattern recurs with new evidence, the next `/hstack:kernel-fit-scan` will produce a new finding with a new id — that's the right path.
-- Never invoke `spec-author` for the triage action. Per ADR-0001, the Skill writes directly.

package/template/.claude/skills/hstack-module-spec/SKILL.md

@@ -1,25 +1,6 @@
 ---
 name: hstack-module-spec
-description: |
-  Use this skill when an engineer needs a baseline `hstack/specs/<module>/spec.md` reverse-engineered for an existing module on a brownfield repo. Module-specs are foundational: every change-spec validates that `area` references an existing module-spec at `status: current`, and every per-change downstream subagent loads the relevant module-spec at session start. Examples:
-
-  <example>
-  Context: The team has just finished `hstack-init` and the engineer wants to produce a module-spec for the billing module before any change work begins there.
-  user: "Run /hstack:module-spec billing."
-  assistant: "I'll invoke spec-author with the billing paths from hstack/config.yaml, pack the module via RepoMix, and walk the seven module-spec sections through an interview."
-  <commentary>
-  Module-specs are the only artifact the `spec-author` reverse-engineers from existing code rather than authoring fresh. The Skill is run once per critical module on adoption; thereafter the spec is refreshed via `hstack-configure --interview` or by re-running this Skill when the cron flags it `needs-refresh`.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A 60-day refresh cron has flagged `hstack/specs/orchestrator/spec.md` as `needs-refresh` because the orchestrator module has been heavily modified.
-  user: "Refresh the orchestrator module-spec."
-  assistant: "I'll re-run /hstack:module-spec orchestrator. The existing spec is the proposal layer; spec-author walks each section, confirming or correcting against the current code."
-  <commentary>
-  Refresh mode is idempotent — when the existing module-spec is read in as the proposal layer, sections that remain accurate produce a no-op confirmation and the timestamp updates without churning the body.
-  </commentary>
-  </example>
+description: Use to reverse-engineer or refresh the baseline `hstack/specs/<module>/spec.md` for one module. Required before any change-spec whose `area` names that module can validate.
 tools:
   - Read
   - Write
@@ -29,12 +10,12 @@ tools:
   - Bash
   - Task
   - "{{TODO-TOOL: RepoMix — packs the module slice (paths from hstack/config.yaml) into a single context bundle for spec-author}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates module-spec frontmatter and MS-01/MS-02/MS-03}}"
+  - "node hstack/scripts/validate-spec.mjs — validates module-spec frontmatter and MS-01/MS-02/MS-03"
 ---
 
 ## Purpose
 
-`hstack-module-spec` produces a baseline `hstack/specs/<module>/spec.md` for one named module by orchestrating the `spec-author` subagent against a packed module slice. It is the one Skill where `spec-author` is permitted to grep the code in service of authorship — the module-spec is the system's anchor between its `area` controlled enum and the actual codebase, and a module-spec disconnected from real paths is worthless.
+`hstack-module-spec` produces a baseline `hstack/specs/<module>/spec.md` for one named module by orchestrating the `spec-author` subagent against a packed module slice. It is the one Skill where `spec-author` is permitted to grep the code in service of authorship — reading it, never modifying it. The module-spec is the system's anchor between its `area` controlled enum and the actual codebase, and a module-spec disconnected from real paths is worthless.
 
 ## When to invoke
 
@@ -62,13 +43,13 @@ Before any work:
 
 3. **Exercise the Invariants challenge prompt.** Per the `spec-author` contract and MS-03, the Invariants section requires a minimum of three bullets, elicited via the challenge "What would a careless refactor in this module break that the tests would not catch?" The Skill does not bypass this even on refresh.
 
-4. **Validate.** After each confirmed field write, the subagent runs `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the in-progress file. The Skill verifies MS-01 (paths non-empty and resolve), MS-02 (no overlap with other module-specs' paths — important to surface mis-aligned module-to-paths mapping), MS-03 (Invariants ≥ 3 bullets).
+4. **Validate.** After each confirmed field write, the subagent runs `node hstack/scripts/validate-spec.mjs <path>` against the in-progress file. The Skill verifies MS-01 (paths non-empty and resolve), MS-02 (no overlap with other module-specs' paths — important to surface mis-aligned module-to-paths mapping), MS-03 (Invariants ≥ 3 bullets).
 
 5. **Transition to `status: current`.** When every section is confirmed and the validator passes, `spec-author` advances status from `drafted` to `current` and updates `last-refreshed` to today. Auto-commit fires.
 
 ## Outputs
 
-- `hstack/specs/<module>/spec.md` at `status: current`, with frontmatter including the module's `paths` array mirrored from `hstack/config.yaml`.
+- `hstack/specs/<module>/spec.md` at `status: current`, with frontmatter including the module's `paths` array mirrored from `hstack/config.yaml`. The Skill mirrors those globs; it never edits, substitutes, or invents them — `paths` are config's to change.
 
 ## Auto-commit triggers
 
@@ -95,11 +76,3 @@ Beyond the kernel's general stop conditions:
 - **RepoMix unavailable.** Degraded mode — flag in the conversation, fall back to direct grep, continue.
 - **Existing module-spec frontmatter does not match config's paths.** Halt; the engineer reconciles before the refresh can proceed.
 - **Validator failure on a partial write.** `spec-author` halts at the field; the Skill surfaces the validator's message and waits.
-
-## Anti-patterns
-
-- Never invent paths. The module's `paths` come from `hstack/config.yaml`; the Skill never edits them and never substitutes.
-- Never skip the Invariants challenge. Three-or-more bullets is a hard validator rule, not a heuristic.
-- Never run this Skill against a module that does not appear in the config. The right move is to add the module to config first.
-- Never overwrite an existing `current` module-spec without explicit refresh-or-re-author confirmation from the engineer.
-- Never write code. `spec-author` is the only subagent invoked, and it reads code without modifying it.

package/template/.claude/skills/hstack-product-discovery/SKILL.md

@@ -1,25 +1,6 @@
 ---
 name: hstack-product-discovery
-description: |
-  Use this skill when the engineer wants to produce or refresh `hstack/context/product/product-brief.md` — the durable thinking artifact that captures the project's product reasoning. The Skill is Phase 1 of `/hstack:greenfield-init` (elicit mode), an optional enrichment phase of `/hstack:brownfield-init` when source docs are thin (extract mode), or a standalone atom for retroactive brief authoring. It invokes the `product-discovery` subagent in one of three engineer-chosen techniques (Brainstorm, Forcing-Questions, Project-Brief), produces a single synthesis at `hstack/context/product/product-brief.md`, and auto-routes to `product-manager` for downstream context-doc refresh. Examples:
-
-  <example>
-  Context: Phase 1 of greenfield-init opens. The engineer types `/hstack:product-discovery` directly.
-  user: "/hstack:product-discovery"
-  assistant: "Pick a technique: [1] Brainstorm — facilitated ideation; [2] Forcing-Questions — reframe-driven probing (Gstack-style); [3] Project-Brief — structured walk. Default mode is elicit (no source docs). The brief lives at hstack/context/product/product-brief.md and is parkable any time."
-  <commentary>
-  The technique choice is the engineer's, not the agent's. Each technique's script is in hstack/templates/discovery/<technique>.md. Mid-technique switching is allowed but halts to confirm — mixing technique outputs produces an incoherent brief.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A brownfield repo's brief never landed during init; /hstack:help flagged the missing artifact.
-  user: "/hstack:product-discovery --mode extract"
-  assistant: "Extract mode. I'll read existing vision.md, README, and any product docs you point me at, propose the brief sections from what I find, and walk you through confirm-or-revise. The three required forcing prompts still run — extract mode does not bypass blind-spot probes."
-  <commentary>
-  Extract+confirm mode is how brownfield enrichment works. The unification of modes is load-bearing: the brief produced is the same artifact whether elicited or extracted, so downstream phases load it identically.
-  </commentary>
-  </example>
+description: Use to produce or refresh `hstack/context/product/product-brief.md` through one of three discovery techniques. Greenfield Phase 1, optional brownfield enrichment when source docs are thin, or standalone retroactive authoring.
 tools:
   - Read
   - Write
@@ -28,7 +9,7 @@ tools:
   - Glob
   - Bash
   - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — frontmatter validator}}"
+  - "node hstack/scripts/validate-spec.mjs — frontmatter validator"
 ---
 
 ## Purpose
@@ -49,7 +30,7 @@ tools:
 ## Preconditions
 
 - `hstack/config.yaml` exists and `init-status` is at least `minimal-complete` — the atom does not run standalone until config exists.
-- `hstack/CLAUDE.md` and `hstack/templates/product-brief.md` are present.
+- `hstack/KERNEL.md` and `hstack/templates/product-brief.md` are present.
 - `hstack/templates/discovery/{brainstorm,forcing-questions,project-brief}.md` are present.
 - In extract mode, at least one source document must be reachable; otherwise halt and ask the engineer to either supply source pointers or fall back to elicit mode.
 
@@ -60,13 +41,13 @@ tools:
 3. **Invoke `product-discovery` subagent.** Via the Task tool with `subagent_type: product-discovery`. Pass mode, technique, optional section, and the canonical session-start context (kernel, template, technique script, source docs in extract mode).
 4. **Walk sections.** The subagent runs the chosen technique's script and walks the brief sections with confirmation gates. Each confirmed section writes to disk and auto-commits.
 5. **Run forcing prompts.** The three required reframes (Who pays? What's the wedge? What would falsify this?) fire before terminal state regardless of technique.
-6. **Auto-route at terminal state.** When the brief reaches `status: current`, the Skill prints the auto-route message (with alternative-path commands) and hands off to `product-manager` via the Task tool with `subagent_type: product-manager` to refresh `vision.md`, `mvp-scope.md`, `personas/`, `glossary.md`. If the engineer types `skip-routing`, the Skill commits the brief and exits cleanly — downstream Skills will halt on missing context docs.
+6. **Auto-route at terminal state.** When the brief reaches `status: current`, the Skill prints the auto-route message (with alternative-path commands) and hands off to `product-manager` via the Task tool with `subagent_type: product-manager` to refresh `vision.md`, `roadmap.md`, `personas/`, `glossary.md`. If the engineer types `skip-routing`, the Skill commits the brief and exits cleanly — downstream Skills will halt on missing context docs.
 
 ## Outputs
 
 - `hstack/context/product/product-brief.md` at `status: current`.
 - `hstack/.session-state/<session-id>.yaml` (transient).
-- Via auto-route: `vision.md`, `mvp-scope.md`, `personas/*`, `glossary.md` refreshed (unless skip-routing).
+- Via auto-route: `vision.md`, `roadmap.md`, `personas/*`, `glossary.md` refreshed (unless skip-routing).
 
 ## Auto-commit triggers
 
@@ -92,10 +73,3 @@ tools:
 
 - **Subagent unreachable.** Persist session state; retry later.
 - **Auto-route partial failure.** If `product-manager` succeeds on vision but fails on personas (e.g., Notion MCP unreachable), the partial state is on disk; re-running auto-route via `/hstack:configure personas --from-brief` recovers.
-
-## Anti-patterns
-
-- Never write to `vision.md`, `mvp-scope.md`, `personas/`, `glossary.md` from this Skill directly. Those refreshes belong to `product-manager` via the auto-route.
-- Never bypass the three required forcing prompts, even in Project-Brief mode (the lightest touch).
-- Never silently switch techniques mid-session.
-- Never advance the brief to `current` while the Explicitly NOT section has fewer than two bullets.

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

@@ -1,25 +1,6 @@
 ---
 name: hstack-research
-description: |
-  Use this skill when the engineer needs grounded research across one of five modes (API lookups, competitive scans, documentation, security CVEs, AI-native best practices) and wants a transient research session committed to `hstack/research/sessions/`. The Skill orchestrates the `researcher` subagent. A `--promote <session-id>` sub-mode elevates an existing session into an ADR (routes through `hstack-adr-new`), a tech-debt item (routes through `hstack-tech-debt-new`), or a durable note under `hstack/research/promoted/` (written by the researcher directly). Examples:
-
-  <example>
-  Context: The engineer is about to introduce a new HubSpot integration and needs to confirm current rate-limit and webhook signature behavior.
-  user: "/hstack:research HubSpot CRM v3 webhook signature verification and current rate limits."
-  assistant: "I'll invoke researcher in API-lookup mode. Canonical-source bias on HubSpot's docs over secondary tutorials; recency window pinned to the last 12 months. Session lands at hstack/research/sessions/<date>-hubspot-webhooks.md."
-  <commentary>
-  Mode classification drives source bias. API-lookup mode weights vendor docs over tutorials because tutorials are the most common cause of wrong-API integrations. Sessions are transient artifacts; the engineer chooses whether to promote.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A research session reached a decision point; the engineer wants to promote it to an ADR.
-  user: "/hstack:research --promote 2026-05-orchestration-patterns"
-  assistant: "I'll route through /hstack:adr-new with --from-research 2026-05-orchestration-patterns. spec-author will receive the session findings as the Context section seed and walk the remaining Nygard sections via interview."
-  <commentary>
-  Promotion routing preserves the conversational interview pattern. The researcher does not write ADRs or tech-debt directly; it hands off via the appropriate Skill so the templates' challenge prompts are exercised.
-  </commentary>
-  </example>
+description: Use when a decision needs grounded external information — API behavior, competitive scans, canonical docs, security CVEs, AI-native patterns — written to a transient research session. `--promote` elevates a session to an ADR, tech-debt, or durable note.
 tools:
   - Read
   - Write
@@ -32,7 +13,7 @@ tools:
   - WebFetch
   - "{{TODO-MCP: Notion MCP — optional; useful when research must include prior team decisions in Notion}}"
   - "{{TODO-MCP: GitHub MCP — optional; useful for searching issues and PRs on third-party SDK repos}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates research session frontmatter}}"
+  - "node hstack/scripts/validate-spec.mjs — validates research session frontmatter"
   - "{{TODO-SCRIPT: hstack/scripts/garbage-collect-research.sh — clears sessions past their garbage-collect-after date; promoted sessions exempt}}"
 ---
 
@@ -68,7 +49,7 @@ Before any work:
 
 ### Default mode
 
-1. **Invoke `researcher`.** Use the Task tool with `subagent_type: researcher` and context = [kernel, query, mode-relevant context docs per the researcher's contract — tech-stack for API/documentation modes, vision/mvp-scope for competitive/AI-native modes, threat-model/hardening-checklist for security-CVE mode]. The subagent classifies the query, applies the mode's source bias, and writes findings incrementally.
+1. **Invoke `researcher`.** Use the Task tool with `subagent_type: researcher` and context = [kernel, query, mode-relevant context docs per the researcher's contract — tech-stack for API/documentation modes, vision/roadmap for competitive/AI-native modes, threat-model/hardening-checklist for security-CVE mode]. The subagent classifies the query, applies the mode's source bias, and writes findings incrementally.
 
 2. **Source discipline.** Per the `researcher` contract:
    - API-lookup: canonical vendor docs over tutorials; 12-month recency window.
@@ -132,14 +113,3 @@ Beyond the kernel's general stop conditions:
 - **WebSearch / WebFetch rate-limited or unavailable.** Surface the limitation; the researcher proceeds with cached or partial results, naming confidence as `low` for affected findings.
 - **A vendor's docs have moved and the canonical URL no longer resolves.** Note the broken canonical source explicitly; do not silently switch to a tutorial.
 - **Promote-to-ADR or promote-to-tech-debt halts inside `spec-author`'s interview.** The session's `promoted-to` field is not written until the destination artifact is at terminal state. Resume by re-running the destination Skill directly.
-
-## Anti-patterns
-
-- Never paraphrase vendor marketing as fact.
-- Never assign `high` confidence to a single-source claim.
-- Never invent a CVE id or a version number.
-- Never advocate for an option beyond what the evidence supports — present options with pros / cons / source-backing; the engineer decides.
-- Never promote unilaterally. Promotion is engineer-driven via the explicit flag.
-- Never write ADRs or tech-debt items directly from this Skill. Route via `hstack-adr-new` / `hstack-tech-debt-new`. The exception is `--target note`, which the researcher writes directly because durable notes are free-form.
-- Never silently drop a contradiction between sources.
-- Never load implementer transcripts or per-change artifacts for context bleed; research is upstream of implementation.

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

@@ -1,25 +1,6 @@
 ---
 name: hstack-scaffold
-description: |
-  Use this skill as Phase 6 of `/hstack:greenfield-init` to bootstrap the consuming repository from empty to bootable. The Skill generates a **bootstrap change-spec** from `hstack/templates/bootstrap.md` (a change-spec variant with `area: bootstrap`, `surfaces: [infra]`), enumerates `in-scope` explicitly from the upstream artifacts (Module Map from app-architecture, Migration Sketches from data-architecture, stack ADRs from Phase 4), runs `data-review` and `security-review` in `--mode foundational` against the proposed posture, then drives the implementer through the planner's phased execution to produce the actual source files, migrations, CI config, and module shells. This is the only Skill (besides `/hstack:greenfield-init` which composes it) that ends with executable code landing in the consuming repo as part of init. Examples:
-
-  <example>
-  Context: Phases 1–5 of greenfield-init are complete; all context artifacts and stack ADRs are at terminal status.
-  user: "/hstack:scaffold"
-  assistant: "Generating bootstrap change-spec at hstack/specs/changes/<YYYY-MM>-bootstrap/spec.md. in-scope enumerated from app-architecture Section 1 (module shells) + data-architecture Section 5 (migration files) + standard infra files (package.json, tsconfig, CI workflow). Running foundational-mode security-review and data-review against the proposed posture. Then planner phases → implementer phase-by-phase → verifier. At terminal state the repo is bootable; build and test commands exit 0."
-  <commentary>
-  Scaffold's distinct property: it scores against a proposed posture (no diff yet) using --mode foundational on security-reviewer and data-specialist. After the bootstrap ships, those reviewers go back to per-change diff-scoring mode.
-  </commentary>
-  </example>
-
-  <example>
-  Context: Scaffold was started two days ago; phase-3 (module shells) landed but phase-4 (CI workflow) hit a verifier failure.
-  user: "/hstack:scaffold"
-  assistant: "Resuming the bootstrap change-spec. plan.md shows phase-3 complete; phase-4 had verifier discrepancies. Re-running /hstack:verify on phase-4 outputs to identify what failed; then either re-implementing phase-4 (if the implementer's output was incorrect) or revising the plan (if the expectation was wrong)."
-  <commentary>
-  Scaffold inherits the standard per-change idempotency contract because bootstrap IS a change-spec. The planner and implementer's existing resume semantics apply unchanged.
-  </commentary>
-  </example>
+description: Use as greenfield Phase 6 to bootstrap an empty repository from the terminal context artifacts to bootable source, via a generated bootstrap change-spec. Greenfield only; the only init path that lands executable code.
 tools:
   - Read
   - Write
@@ -38,7 +19,7 @@ tools:
   - "{{TODO-SKILL: /hstack:adversarial-review — runs in a fresh session for the bootstrap}}"
   - "{{TODO-SKILL: /hstack:ship — final scorecard; bootstrap ships with a PR like any change}}"
   - "{{TODO-SKILL: /hstack:finalize — post-merge cleanup}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — frontmatter validator}}"
+  - "node hstack/scripts/validate-spec.mjs — frontmatter validator"
 ---
 
 ## Purpose
@@ -130,11 +111,3 @@ Scaffold inherits the standard per-change idempotency contract because bootstrap
 - **Foundational-mode reviewer halts.** Foundational mode is honor-system in v1 — the reviewer is asked to score a proposed posture, not a diff. If the reviewer cannot honestly score (e.g., the threat-model is too thin), the reviewer halts with `HSTACK-HALT: reason=upstream-non-terminal` and routes the engineer back to `/hstack:configure threat-model`.
 - **Implementer scope-lock fires on a path NOT in the enumerated in-scope.** This is a scaffold-spec gap, not an implementer bug. The Skill halts; the engineer revises `in-scope` (mechanical edit by the engineer per the kernel's scope-amendment path) and re-runs `/hstack:implement` for the affected phase.
 - **CI runs from `ci-cd.md` haven't been authored yet for fresh projects.** The bootstrap change-spec's test-plan must define the canonical commands; otherwise verifier has nothing to run. The Skill checks this at preconditions.
-
-## Anti-patterns
-
-- Never run scaffold against a non-empty repo. Scaffold is greenfield-only; mixing modes produces incoherent in-scope enumeration.
-- Never set `in-scope: ["."]`. Explicit file enumeration is the contract; the implementer's scope-lock does meaningful work only against an explicit list.
-- Never skip foundational-mode security-review / data-review to "save time." Those gates are the v1 substrate for getting hardening and RLS posture right from line zero.
-- Never bypass adversarial-review for the bootstrap. Bootstrap inherits the fresh-session contract from the kernel; ship without it is forbidden.
-- Never flip `init-status: complete` while the bootstrap change-spec is below `shipped`.

package/template/.claude/skills/hstack-security-review/SKILL.md

@@ -1,34 +1,6 @@
 ---
 name: hstack-security-review
-description: |
-  Use this skill when a change-spec is at `status: ready-to-plan` or later and needs `security-review.md` produced before the implementer can start. The Skill orchestrates the `security-reviewer` subagent. In v1 the output is an LLM-scored structured judgment (`scoring-mode: llm-scored`), not an executable test result — the Skill enforces this framing on every output. Examples:
-
-  <example>
-  Context: A change-spec introduces a new public-schema table with RLS and is at ready-to-plan.
-  user: "/hstack:security-review 2026-05-billing-overage-warning"
-  assistant: "I'll invoke security-reviewer. Surfaces is [ui, db], so the threat-model-delta section is mandatory. Scoring biases toward CONCERNS over PASS when evidence is thin; the three challenge prompts run regardless of what surfaces declares."
-  <commentary>
-  The Skill is the only authoring path for security-review.md. It enforces SR-03 (threat-model-delta required when surfaces touches agent/auth/api/db) and SR-02 (three challenge prompts mandatory). v1 framing is enforced on every rationale.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A change touches the agent surface — new orchestrator prompt and a new tool boundary — and the threat-model.md has not been touched in eight weeks.
-  user: "/hstack:security-review 2026-06-playbook-runner-prompt"
-  assistant: "I'll invoke security-reviewer. The threat-model-delta is mandatory because surfaces includes agent; I'll halt if the delta can't be produced from the current threat-model. Findings will frame as structured judgment, not verified by test execution."
-  <commentary>
-  Agent-surface changes are exactly where the v1 honesty clause matters most. The Skill ensures the subagent does not claim test-backed evidence for prompt-injection resistance — that is v2 substrate work.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A change is a small refactor with no declared security-sensitive surface, but the diff touches authentication-adjacent code.
-  user: "/hstack:security-review 2026-05-auth-helper-rename"
-  assistant: "I'll invoke security-reviewer. Even on a refactor, the three challenge prompts run — attack vector not covered by checklist, tenant-isolation citation, malicious-payload behavior — to surface anything the surface declaration may have missed."
-  <commentary>
-  Refactors near auth are exactly the place where the surface declaration may understate the risk. The challenge-prompt machinery is the v1 mitigation for humans missing what's missing.
-  </commentary>
-  </example>
+description: Use when a change-spec is at `ready-to-plan` or later and needs `security-review.md` before implementation. Runs independently of `/hstack:change-plan` and `/hstack:data-review`.
 tools:
   - Read
   - Write
@@ -38,7 +10,7 @@ tools:
   - Bash
   - Task
   - "{{TODO-SCRIPT: hstack/scripts/score-security-review.ts — computes overall status from the scores map}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates security-review frontmatter and SR-01..SR-05}}"
+  - "node hstack/scripts/validate-spec.mjs — validates security-review frontmatter and SR-01..SR-05"
   - "{{TODO-MCP: Supabase MCP — optional in v1 for live RLS introspection; v2 substrate will hard-fail when unreachable for db-surface changes}}"
 ---
 
@@ -71,11 +43,11 @@ Before any work:
 
 2. **Threat-model delta.** When `threat-model-delta-required: true`, the subagent writes section 3 with a non-empty delta against the current threat-model.md. SR-03 enforces this at validation.
 
-3. **Three challenge prompts (mandatory).** Per SR-02 and the subagent's contract, the subagent answers all three challenge prompts verbatim:
+3. **Three challenge prompts (mandatory).** Per SR-02 and the subagent's contract, the subagent answers all three challenge prompts. The canonical wording:
    - "What attack vector did the In-Scope diff create that is NOT covered by the hardening checklist? If none, justify."
    - "Which tenant_isolation guarantee does this change depend on? Cite the line of code that enforces it."
    - "What part of this change would behave incorrectly under a malicious payload that the test suite does not cover?"
-   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 SR-02 locates the answers by. Each answer is at least one paragraph. The Skill verifies `challenge-prompts-answered: 3` in frontmatter.
 
 4. **Scoring discipline.** Per the subagent's contract, scoring biases toward CONCERNS when evidence is thin. The Skill does not override this bias. Tenant-isolation citations reference real lines of code; the subagent greps to verify.
 
@@ -85,7 +57,7 @@ Before any work:
 
 7. **Tech-debt for deferred concerns.** When a CONCERNS finding is being deferred rather than fixed, 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.
 
-8. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` and `{{TODO-SCRIPT: hstack/scripts/score-security-review.ts}}` — SR-01 through SR-05.
+8. **Validate.** Run `node hstack/scripts/validate-spec.mjs <path>` and `{{TODO-SCRIPT: hstack/scripts/score-security-review.ts}}` — SR-01 through SR-05.
 
 ## Outputs
 
@@ -121,13 +93,3 @@ Beyond the kernel's general stop conditions:
 - **Tenant-isolation citation cannot be produced because the In-Scope diff drops tenant context.** Halt and surface — the change introduces a tenant-isolation bug.
 - **Validator fails SR-02 (fewer than 3 challenge prompts answered).** Halt; the subagent re-runs the missing prompt.
 - **v1 framing slips in a rationale.** The Skill detects "verified by test" language in any rationale paragraph and halts; the subagent re-words.
-
-## Anti-patterns
-
-- Never produce a PASS when evidence is thin. Default to CONCERNS and let the human acknowledge.
-- Never skip or paraphrase a challenge prompt. The three are verbatim and mandatory.
-- Never claim test-backed evidence in v1. The honesty clause is load-bearing.
-- Never write `concerns-acknowledged-by` without the owner's explicit acknowledgement.
-- Never silently fall back to `data-architecture.md` when the live-schema MCP is unreachable on a db-surface change — flag the degradation in the rationale and (in v1) continue if the change is low-stakes, halt if high-stakes.
-- Never fabricate line numbers in tenant_isolation citations.
-- Never file tech-debt from this Skill; surface the recommendation for the engineer to invoke `hstack-tech-debt-new`.