hstack 0.7.0 → 0.16.0

package/template/templates/adr.md

@@ -37,3 +37,10 @@ _Positive, negative, and neutral outcomes. Particularly the trade-offs accepted.
 ## Alternatives Considered
 
 _What was on the table; why each was rejected. One paragraph per alternative._
+
+## Forecloses / Enables
+
+_Against `hstack/context/roadmap.md`: which Next/Later item does this decision make more expensive (foreclose) or cheaper (enable)? One line each. "None" is a valid answer. When the roadmap is missing or stale, write `n/a — roadmap stale/missing` instead of guessing. Advisory — never a merge gate._
+
+- Forecloses:
+- Enables:

package/template/templates/adversarial-review.md

@@ -4,10 +4,10 @@ type: adversarial-review
 status: draft                          # draft | in-progress | findings-open | findings-resolved | superseded
 owner: <git-handle>
 parent-change: <change-spec-id>
-findings-floor: 3                      # 3 default; 5 when change-spec.area in {agent, auth, billing}
+findings-floor: 3                      # AR-06: 3 default; 5 when change-spec.area in {agent, auth, billing}. The area's expected finding count — measured by telemetry, gated by nothing (ADR-0014)
 findings: []                           # array of finding records; see below
-findings-fewer-than-floor: false
-justification-when-fewer: null         # required when findings-fewer-than-floor: true
+findings-fewer-than-floor: false       # true when the review came in under the expectation; must be true when `findings` is empty
+justification-when-fewer: null         # required when findings-fewer-than-floor: true, and non-negotiable when `findings` is empty (AR-01)
 fresh-session-attestation: <session-id; opened <ISO-8601>; no implementer transcript loaded>
 created: <YYYY-MM-DD>
 updated: <YYYY-MM-DD>
@@ -29,7 +29,7 @@ _Fresh-session attestation; what artifacts were loaded; how findings were genera
 
 ## Findings
 
-_One subsection per finding (F-01..F-N). Mandate: at least `findings-floor` findings across categories, or `findings-fewer-than-floor: true` with justification._
+_One subsection per finding (F-01..F-N). The six categories are lenses to sweep, not buckets to fill — file what the sweep found, at the severity it has. Calibration rubric: `hstack/.claude/skills/hstack-adversarial-review/references/finding-categories.md`._
 
 ### F-01
 
@@ -51,4 +51,4 @@ _Append-only record of how each finding was resolved. Written by `owner` in resp
 
 ## Findings Floor Justification
 
-_Populated only when `findings-fewer-than-floor: true`. Explain why fewer than the floor is the honest answer._
+_Populated when `findings-fewer-than-floor: true`, and mandatory when `findings` is empty (AR-01). Reading a change cold and reporting nothing is a claim: enumerate what was looked for in each of the six categories and why each sweep came back clean. "The change is small" is not a defence._

package/template/templates/ci-cd.md

@@ -18,6 +18,20 @@ _Every check in `.github/workflows/hstack-gates.yml` plus pre-existing CI checks
 
 -
 
+## Canonical Commands
+
+_The exact commands `hstack/scripts/run-gates.sh` executes — the verifier runs every one of them and nothing else. The fenced `hstack-gates` block below is the machine-readable half; the prose above it is for humans. One `suite: command` pair per line. Suite keys mirror `verification.test-results`: `unit`, `integration`, `e2e`, `lint`, `typecheck`. Omit a line, or set it to `none`, for a suite this repo does not have — an omitted suite is not run and not scored. `unit` / `integration` / `e2e` are subject to V-05 (a suite that executes zero tests is recorded `not-run`, never `pass`); `lint` and `typecheck` are exempt._
+
+_Extending this set is `/hstack:configure --interview ci-cd`, never an ad-hoc addition at verify time._
+
+```hstack-gates
+unit:        <command>
+integration: <command>
+e2e:         none
+lint:        <command>
+typecheck:   <command>
+```
+
 ## Deploy targets
 
 _Preview, staging, production. What promotes to what. Manual vs automatic._

package/template/templates/coord-message.md

@@ -31,8 +31,9 @@ context, a decision, a heads-up — with `refs` pointing at the committed
 artifacts that carry the authoritative detail. The body summarizes; the refs
 are the source of truth.
 
-Validator rules (enforced by the proposed-diff preview in v1; validate-spec.ts
-is still a {{TODO-SCRIPT}} placeholder):
+Validator rules (`node hstack/scripts/validate-spec.mjs <path>`; CM-02
+immutability is a git-history claim the validator cannot see — it stays with
+the Skill and the reviewer):
 
 - CM-01: at send-time, `from-repo`, `from-branch`, `to-repo`, and `subject`
   are non-null. `status` is `sent` and never changes.

package/template/templates/data-architecture.md

@@ -17,16 +17,13 @@ schema-version: 1
 
 _The load-bearing question. The data-architect refuses to advance past this section until the tenant definition is concrete and ties to a persona in the brief._
 
-**Pattern** — one of:
+**A tenant is a ...**
 
-- **A. Tenant = the customer organization** — single workspace per paying customer; users inside share visibility.
-- **B. Tenant = a sub-team within the customer organization** — multi-workspace per customer.
-- **C. Tenant = the individual user** — workspace-per-user.
-- **D. Custom** — document the pattern explicitly and explain why none of A/B/C fit.
+_One concrete noun from this product's own vocabulary, plus the rule for who is inside one and who is not. Common shapes, offered as examples rather than as a menu: the customer organization (one workspace per paying customer, users inside share visibility); a sub-team within that organization (multi-workspace per customer); the individual user (workspace-per-user). Products whose tenant is a project, a device, a contract, a site, a case or a season are ordinary and none of those three fit them — name yours._
 
 **Rationale**
 
-_One sentence tying the chosen pattern to the persona in `product-brief.md`. Example: "Pattern A because Maya (Director of CS) shares visibility with her 6 reps; sub-team isolation isn't requested by any v1 persona."_
+_One sentence tying the tenant to a persona in `product-brief.md`. Example: "The tenant is the customer organization, because Maya (Director of CS) shares visibility with her 6 reps and no v1 persona asks for sub-team isolation."_
 
 **Tenant identifier**
 

package/template/templates/kernel-fit-finding.md

@@ -12,7 +12,7 @@ evidence-row-count: 0                  # integer; must equal len(evidence-rows)
 evidence-rows: []                      # YAML array of {change|adr|td, signal} dicts; one entry per row counted above
 related-findings: []                   # KF ids — prior or adjacent findings on the same kernel surface
 promoted-to: null                      # `adr:<ADR-NNNN-slug>` | `tech-debt:<TD-NNNN-slug>` | null; reciprocal with the target artifact's `promoted-from-kernel-fit`; required when status: promoted
-dismissed-reason: null                 # ≥50 chars of prose; required when status: dismissed (per KF-05)
+dismissed-reason: null                 # required when status: dismissed (KF-05); says what about the finding is wrong, specifically enough to be re-evaluated later
 superseded-by: null                    # KF id when status: superseded
 created: <YYYY-MM-DD>
 updated: <YYYY-MM-DD>
@@ -36,7 +36,7 @@ _Per evidence row, a 2–3 sentence prose summary with at least one inline citat
 
 ## Kernel surface implicated
 
-_Single-sentence pointer to the kernel section, template, validator rule, or Skill flow that the finding suggests revising. Examples: "`template/CLAUDE.md § Frontmatter contract` — the `internal-tooling` field"; "`template/templates/change-spec.md` frontmatter — `surfaces` enum"; "`/hstack:adversarial-review` precondition check at SKILL.md line 61"._
+_Single-sentence pointer to the kernel section, template, validator rule, or Skill flow that the finding suggests revising. Examples: "`template/KERNEL.md § Frontmatter contract` — the `internal-tooling` field"; "`template/templates/change-spec.md` frontmatter — `surfaces` enum"; "`/hstack:adversarial-review` precondition check at SKILL.md line 61"._
 
 ## Proposed direction
 

package/template/templates/kernel-fit-flag.md

@@ -24,8 +24,8 @@ A kernel-fit-flag is a frontmatter-only pin. There is no body. Engineer
 interpretation of the friction is deliberately excluded — the analyst reads
 the transcript window and forms its own classification at processing time.
 
-Validator rules (enforced by the proposed-diff preview in v1; validate-spec.ts
-is still a {{TODO-SCRIPT}} placeholder):
+Validator rules (`node hstack/scripts/validate-spec.mjs <path>`; the pin itself
+lands regardless — see `/hstack:flag` § does NOT halt on):
 
 - FL-01: at pin-time (status: pending) every field marked above as
   "non-null at pin-time" must be populated. `hint` may be null; the four

package/template/templates/plan.md

@@ -12,6 +12,10 @@ updated: <YYYY-MM-DD>
 schema-version: 1
 ---
 
+## Roadmap Alignment
+
+_One line, written by the planner against `hstack/context/roadmap.md`: does this change serve a Now/Next item, and does any phase foreclose a Next/Later item? When the roadmap is missing, not `current`, or `updated` > 90 days ago, write `n/a — roadmap stale/missing (<detail>)`. Advisory — never a gate._
+
 ## Phase Overview
 
 _Table of phases. Three columns max._

package/template/templates/product-brief.md

@@ -5,7 +5,7 @@ status: draft                          # draft | current | needs-refresh | archi
 owner: <git-handle>
 technique-used: <brainstorm | forcing-questions | project-brief>
 derived-from: []                       # always empty — product-brief is Phase 1, no upstream
-downstream: [vision, mvp-scope, personas, glossary]
+downstream: [vision, roadmap, personas, glossary]
 created: <YYYY-MM-DD>
 updated: <YYYY-MM-DD>
 schema-version: 1
@@ -44,7 +44,7 @@ _The things that could make this product fail. The forcing-prompt "What would yo
 
 ## Forcing-Prompt Answers
 
-_Evidence that the three required reframes ran. Logged inline as confirmation the probes were not skipped._
+_Evidence that the three required reframes ran. Logged inline as confirmation the probes were not skipped. The headings below are the canonical wording — record what was actually asked when a reframe was fitted to this product._
 
 **Who specifically pays for this?**
 _The named user / buyer plus the rationale ("Director of CS, because retention is their KPI")._

package/template/templates/roadmap.md

@@ -0,0 +1,41 @@
+---
+id: roadmap
+type: roadmap
+status: drafted                        # drafted | current | needs-refresh | archived
+owner: <git-handle>
+source: local                          # local | rhizome — who owns the truth; when rhizome, local edits are refused and the sync is authoritative
+reviewed-on: <YYYY-MM-DD>              # planner treats the roadmap as stale beyond 90 days
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Now
+
+_What we are committed to shipping. During the MVP phase, Now IS the MVP scope. Each item: one product line, one architectural-implication line. Implications are proposed by app-architect / data-architect and confirmed by the engineer — vague fortune-telling ("might need to scale") is worse than absence._
+
+- <item> — **architectural implication:** <one line>
+
+## Next
+
+_Likely within ~2 quarters. A direction, not a commitment. No dates._
+
+- <item> — **architectural implication:** <one line>
+
+## Later
+
+_Plausible futures. These influence one-way-door decisions ONLY — never day-to-day scoping._
+
+- <item> — **architectural implication:** <one line>
+
+## Not on the path
+
+_Explicit renouncements, with the reason. Absorbs the old "Deferred" list._
+
+- <item> — <why not>
+
+## Success criteria for the current horizon
+
+_Concrete observable indicators that Now is done and Next gets promoted. Bullets._
+
+-

package/template/templates/security-review.md

@@ -50,7 +50,7 @@ _Required when `threat-model-delta-required: true`. One paragraph delta against
 
 ## Challenge Prompts
 
-_All three required. Each answer must be at least one paragraph._
+_All three required. Each answer must be at least one paragraph. The questions below are the canonical wording — adapt one to the change under review when the adaptation probes harder, and record what was actually asked in the heading. Keep the `(a)` / `(b)` / `(c)` prefixes: SR-02 locates the answers by them._
 
 ### (a) What attack vector did the In-Scope diff create that is NOT covered by the hardening checklist? If none, justify.
 

package/template/templates/telemetry-sidecar.md

@@ -1,6 +1,8 @@
 # Telemetry sidecar — schema and discipline
 
-This document describes the JSON sidecar files three hstack Skills emit alongside their canonical artifact writes, to make per-change telemetry attribution cheap. Sidecars are **derivative** of git + frontmatter — re-runnable from source, never authoritative. The kernel's "no parallel tracker" rule is preserved by this derivative property.
+This document describes the JSON sidecar files five hstack Skills emit alongside their canonical artifact writes, to make per-change telemetry attribution cheap. Sidecars are **derivative** of git + frontmatter + transcripts — re-runnable from source, never authoritative. The kernel's "no parallel tracker" rule is preserved by this derivative property.
+
+This file is the canonical schema and the only place the field rules are stated. The five emitting Skills reference it: each carries its own JSON schema block (its Skill-specific payload) and the executable step that opens the phase window, and points here for everything else. Per ADR-0012 they do not restate the rules below.
 
 ## Where sidecars live
 
@@ -27,12 +29,40 @@ The `.telemetry/` directory is **git-ignored** at the consuming-repo level. Side
 
 The other 22 Skills do **not** emit sidecars in v1. Their data is reconstructible from git + frontmatter + transcripts; the five emissions above target the highest-signal events across the change lifecycle: test discipline up front (`test-plan`), per-phase scope-locked execution (`implement`), promised-vs-observed (`verify`), gate-firing critique (`adversarial-review`), lifecycle close (`finalize`).
 
+## The phase window — every sidecar, every Skill (schema_version 2)
+
+Every sidecar carries three fields on top of its Skill-specific payload. They exist so the telemetry parser can answer "what did this phase cost?" — see ADR-0009.
+
+```json
+{
+  "session_id": "062b8fe8-649f-4d73-b4fb-b0a28a800552",
+  "phase_opened_at": "2026-08-15T09:12:44Z",
+  "phase_closed_at": "2026-08-15T11:03:07Z"
+}
+```
+
+Field rules — one statement, applying identically to all five Skills:
+
+- `session_id` — the active Claude Code session, resolved by `hstack/scripts/telemetry/session_id.py` (the most recently modified `*.jsonl` under `~/.claude/projects/<encoded-cwd>/`). One shared resolver, not a per-Skill heuristic. Unresolvable → `null`.
+- `phase_opened_at` — stamped when the Skill's preconditions pass, **before any subagent invocation**. Same script call as `session_id`, so both come from one read. The script is read-only, takes milliseconds, and never halts; if it fails or reports `"session_id": null`, the Skill holds `null` for both and continues.
+- `phase_closed_at` — stamped at the Skill's terminal state, in the same write that lands the sidecar.
+- All three are **best-effort by contract**. Any of them `null`, unparseable, or inverted makes the phase *unmeasured*: `parsers/transcripts.py:phase_usage` returns `null`, and TE-4/TE-5 print `unmeasured`. **Never zero** — a phase whose window cannot be honoured still spent tokens, and a zero would fold it into the averages as if it were free.
+- A sidecar write failure never blocks the canonical commit, and the window is never a halt condition. Measurement never gates the workflow.
+- ISO-8601, UTC, second precision, `Z` suffix — the format `session_id.py` emits.
+
+Sidecars at `schema_version: 1` (written before ADR-0009) carry no window and read as unmeasured. Nothing migrates them: the transcript timestamps they would need were never recorded.
+
+The window measures *what the session spent while the phase was open* — not what the phase required. A detour taken between `phase_opened_at` and `phase_closed_at` is counted, and subagent spend lands in its host's window (`isSidechain: false` throughout the transcripts). Narrow, not exact.
+
 ## Schema — `test-plan.json`
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "hstack-test-plan",
+  "session_id": "<session id, or null>",
+  "phase_opened_at": "<ISO-8601 at precondition pass, or null>",
+  "phase_closed_at": "<ISO-8601 at terminal state, or null>",
   "change_id": "2026-05-billing-overage-warning",
   "completed_at": "2026-05-22T11:14:00Z",
   "status": "passed",
@@ -61,8 +91,11 @@ Field rules:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "hstack-implement",
+  "session_id": "062b8fe8-649f-4d73-b4fb-b0a28a800552",
+  "phase_opened_at": "2026-05-22T13:58:12Z",
+  "phase_closed_at": "2026-05-22T14:18:42Z",
   "change_id": "2026-05-billing-overage-warning",
   "phase_id": "phase-3-component",
   "started_at": "2026-05-22T14:00:00Z",
@@ -77,19 +110,22 @@ Field rules:
 
 Field rules:
 
-- `started_at`, `completed_at` — ISO-8601. The implementer records them from session timestamps.
+- `started_at`, `completed_at` — ISO-8601. The implementer records them from session timestamps. They describe the phase; `phase_opened_at` / `phase_closed_at` bound the *measurement window* and come from the shared resolver. They will usually be within seconds of each other; when they disagree, the window fields are the ones the parser reads.
 - `files_touched_count` — count of distinct files modified by the phase's commit. Computed mechanically; not a judgment.
 - `tests_written_count` — count of test files newly created in the phase (kernel test-immutability rule allows new tests without authorization).
 - `scope_amendment_emitted` — `true` only when the implementer halted and surfaced a scope-amendment request during this phase.
-- `halt_reasons` — array of enum values from the kernel halt sentinel (see CLAUDE.md § Halt sentinel).
+- `halt_reasons` — array of enum values from the kernel halt sentinel (see KERNEL.md § Halt sentinel).
 - `test_immutability_authorizations` — array of canonical authorization phrases echoed during this phase (e.g., `"Ok to change test foo"`).
 
 ## Schema — `verify.json`
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "hstack-verify",
+  "session_id": "062b8fe8-649f-4d73-b4fb-b0a28a800552",
+  "phase_opened_at": "2026-05-22T15:19:41Z",
+  "phase_closed_at": "2026-05-22T15:32:00Z",
   "change_id": "2026-05-billing-overage-warning",
   "ran_at": "2026-05-22T15:32:00Z",
   "test_suite_runtime_s": 187.4,
@@ -114,8 +150,11 @@ Field rules:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "hstack-adversarial-review",
+  "session_id": "9f41c0aa-2f5e-4c31-9a77-6d0b1b0e2c14",
+  "phase_opened_at": "2026-05-22T16:40:03Z",
+  "phase_closed_at": "2026-05-22T16:42:00Z",
   "change_id": "2026-05-billing-overage-warning",
   "reviewed_at": "2026-05-22T16:42:00Z",
   "findings_floor": 5,
@@ -138,17 +177,20 @@ Field rules:
 
 Field rules:
 
-- `findings_floor` is `3` by default, `5` when `change-spec.area` is in `{agent, auth, billing}` per AR-06.
-- `findings_count` < `findings_floor` is permitted only when `findings_fewer_than_floor: true` (with a defended justification in the canonical artifact's Findings Floor Justification section). Aggregating across changes: a rising `findings_fewer_than_floor: true` rate means either the floors are wrong or the reviewer is gaming the escape hatch.
-- `category_counts` clustering — e.g., 5 of 5 findings in `code-quality` — is the quota-gaming smell the kernel's "spread findings across categories" guidance is designed to detect. The telemetry layer surfaces it via OE-7.
+- `findings_floor` is `3` by default, `5` when `change-spec.area` is in `{agent, auth, billing}` per AR-06. Since ADR-0014 it is the area's *expected* finding count and gates nothing — it is carried here so `findings_count` has a denominator to be read against.
+- `findings_count` below `findings_floor` is an ordinary outcome, not a violation. The one count the canonical artifact must argue for is zero: AR-01 requires `findings_fewer_than_floor: true` with a defended justification when `findings` is empty. Aggregating across changes: the `findings_count / findings_floor` distribution is the primary read, and a rate of empty reviews that climbs while `severity_counts` stays flat is the signal worth acting on.
+- `category_counts` clustering — e.g., 5 of 5 findings in `code-quality` — is a description of where a change carried its risk, not a smell in itself. It is worth reading against the change's `surfaces`: a `db`-surface change with every finding in `code-quality` is a review that did not look where the risk was. Surfaced via OE-7.
 - `severity_counts.high + critical` paired with `resolution_mix.justified-in-prose > 0` is a high-severity-in-prose smell flagged by QO-2. The Skill's stop condition should have caught it before terminal status; sidecar presence indicates a bypass.
 
 ## Schema — `finalize.json`
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "hstack-finalize",
+  "session_id": "c7d2e5b1-88a4-4f0d-b3ce-51a9f7d6e8b2",
+  "phase_opened_at": "2026-05-23T10:11:26Z",
+  "phase_closed_at": "2026-05-23T10:14:00Z",
   "change_id": "2026-05-billing-overage-warning",
   "shipped_at": "2026-05-23T10:14:00Z",
   "merge_commit_sha": "abc1234567890",
@@ -169,8 +211,9 @@ Per the kernel § Mechanical operations § Discipline preserved:
 
 - **Atomic with the canonical commit.** Each sidecar is written and `git add`-ed in the same commit as the canonical artifact write. No separate commit. The sidecar piggybacks on a commit that was happening anyway — zero new LLM turns, zero new confirmation gates.
 - **Idempotency.** Re-running a Skill on a phase that already landed produces a no-op on the sidecar (file already present, content unchanged aside from `schema_version` bumps if any).
-- **Derivative property.** Every value in every sidecar is reconstructible from git + frontmatter + transcripts. The sidecar is a cache, not a source. Deleting a sidecar is harmless — the next `/hstack:telemetry` run will compute the same metrics from the slower path.
-- **Schema versioning.** `schema_version: 1` in v1. Bumping to `2` requires either a backward-compatible additive change (new optional field) or a migration in `scripts/telemetry/parsers/`.
+- **Derivative property.** Every value in every sidecar is reconstructible from git + frontmatter + transcripts. The sidecar is a cache, not a source. Deleting a sidecar is harmless — the next `/hstack:telemetry` run will compute the same metrics from the slower path. The phase window is the one field group with a shelf life: it points at a transcript that `cleanupPeriodDays` will eventually sweep (365 days on some machines, 30 by default), after which the phase reads as unmeasured. Deleting the sidecar loses the window for good, since nothing else records it.
+- **Schema versioning.** `schema_version: 2` since ADR-0009 (the phase window). The bump is additive: every v1 field keeps its name and meaning, and a v1 sidecar still parses — it simply reports as unmeasured. No migration exists or is planned.
+- **No local identifiers in git.** `session_id` is a local machine identifier. `.telemetry/` is gitignored in the consuming repo, so it never lands in history — but the discipline now depends on that gitignore line holding. A consumer that commits `.telemetry/` publishes its session ids.
 
 ## What sidecars are NOT
 

package/template/templates/test-plan.md

@@ -106,7 +106,7 @@ _Required when `performance-budgets-required: true`. For each hot path the chang
 
 ## Challenge Prompts
 
-_All three required. Each answer must be at least one paragraph. These exist because the v1 mitigation for "humans miss what's missing" is to force the strategist to name gaps the planner and the implementer will not._
+_All three required. Each answer must be at least one paragraph. These exist because the v1 mitigation for "humans miss what's missing" is to force the strategist to name gaps the planner and the implementer will not. The questions below are the canonical wording — adapt one to the change when the adaptation probes harder, and record what was actually asked in the heading. Keep the `(a)` / `(b)` / `(c)` prefixes: TS-02 locates the answers by them._
 
 ### (a) 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.