hstack 0.16.0 → 0.17.0

package/template/templates/hardening-checklist.md

@@ -1,73 +0,0 @@
----
-id: hardening-checklist
-type: hardening-checklist
-status: drafted                        # drafted | current | needs-refresh | archived
-owner: <git-handle>
-last-quarterly-review: <YYYY-MM-DD>
-layer-count: 10
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
-
-_One section per layer. Each layer enumerates items with: item id, what it asserts, evidence required, not-applicable conditions. This is the artifact `security-review.md` scores against item-by-item. Validator rule HC-01: every layer that appears in a security-review `scores` map must exist as a section here._
-
-## data-at-rest
-
-### Item HC-DAR-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**
-
-## data-in-transit
-
-### Item HC-DIT-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**
-
-## authn
-
-### Item HC-AN-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**
-
-## authz-rls
-
-### Item HC-AZ-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**
-
-## tenant-isolation
-
-### Item HC-TI-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**
-
-## input-validation
-
-### Item HC-IV-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**
-
-## output-encoding
-
-### Item HC-OE-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**
-
-## secrets-handling
-
-### Item HC-SH-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**
-
-## agent-prompt-injection
-
-### Item HC-API-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**
-
-## audit-logging
-
-### Item HC-AL-01: <assertion>
-**Evidence required.**
-**Not-applicable when.**

package/template/templates/incident-runbook.md

@@ -1,57 +0,0 @@
----
-id: incident-runbook
-type: incident-runbook
-status: drafted                        # drafted | current | needs-refresh | archived
-owner: <git-handle>
-git-ignored: true                      # this file MUST be gitignored; sensitive content
-last-quarterly-review: <YYYY-MM-DD>
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
-
-<!--
-WARNING: This file contains sensitive operational content (auth provider details, revocation endpoints,
-customer communication templates, phone tree). It MUST be gitignored. Per architecture amendment A7,
-the file lives locally and is synced to an out-of-band destination configured in hstack/config.yaml as
-`incident-runbook.sync-target`. Auto-commit does not apply to this file. The init Skill must add the
-entry to .gitignore as part of bootstrap.
--->
-
-## Kill switches
-
-_Feature flags and how to flip them, ordered by blast radius. Most-dangerous-first._
-
--
-
-## Revocation flows
-
-_Per third-party: Stripe, Supabase, Pipedream, MCPs. Steps to revoke a session, an OAuth token, an API key._
-
-### Stripe
-
-### Supabase
-
-### Pipedream
-
-### MCPs
-
-## Customer communication
-
-_Copy templates per severity (P0 / P1 / P2). Channels (in-app, email, status page)._
-
-### P0 template
-
-### P1 template
-
-### P2 template
-
-## Escalation contacts
-
-_Owner phone tree. Mark each entry with privacy boundary (work-hours OK / 24-7 OK)._
-
--
-
-## Post-incident
-
-_Runbook for the followup ADR or tech-debt write-up. Pointer to ADR template._

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

@@ -1,63 +0,0 @@
----
-id: KF-<NNNN>-<slug>
-type: kernel-fit-finding
-status: open                           # open | acknowledged | dismissed | promoted | superseded | archived
-owner: null                            # git-handle of the triager; null until first triage
-pattern: <KF-P1 | KF-P2 | KF-P3 | …>   # detector pattern that fired; enumerated in scripts/telemetry/insights/kernel_fit.py
-confidence: medium                     # high | medium | low
-detected-by: kernel-fit-analyst
-detected-via: detector                 # detector | flag — `detector` (default) when the finding came from kernel_fit.py pattern matching; `flag` when the finding originated from a /hstack:flag pin (ADR-0005). For folded-in findings (flag signal merged into an existing detector-finding), `detected-via` remains `detector` because the originating signal was the detector pattern.
-detected-at: <ISO-8601 timestamp>
-evidence-row-count: 0                  # integer; must equal len(evidence-rows) per KF-01
-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                 # 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>
-schema-version: 1
----
-
-## Title
-
-_Short noun phrase naming the kernel-fit gap. Example: "Category-A claim spans production paths — engineer likely meant Category B."_
-
-## Pattern fired
-
-_Name the detector pattern (KF-P1 / KF-P2 / KF-P3 / …) and one paragraph describing what the detector found. Quote the pattern's defining condition from `kernel_fit.py` if helpful._
-
-## Evidence
-
-_Per evidence row, a 2–3 sentence prose summary with at least one inline citation (change-id, ADR-id, TD-id, commit-sha, kernel section). KF-01 requires `len(evidence-rows)` in frontmatter to equal `evidence-row-count`; the prose here must cite each row at least once. No prose without a citation._
-
-1. ...
-2. ...
-
-## Kernel surface implicated
-
-_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
-
-_One paragraph. Name a direction the kernel revision could take — split a flag, add an enum case, add a Skill precondition, amend a section. This is NOT a full ADR — that work is done by `spec-author` if and when the engineer invokes `/hstack:kernel-fit-promote`. Keep this as a sketch, not a specification._
-
-## Counter-explanations (challenge prompt — mandatory)
-
-_Two reasons this finding might NOT warrant a kernel change. If you cannot produce two, the analyst auto-downgrades `confidence` to `low` per KF-03. The challenge defends against false-positives the same way `## Consequences` § "name two consequences that look bad" defends ADRs._
-
-1. ...
-2. ...
-
-## Confidence rationale
-
-_One paragraph defending the `confidence` enum value against the validator rules. `high` requires `evidence-row-count >= 3` AND ≥2 distinct change-specs cited (KF-02). `medium` is the conservative default. `low` carries no notification and is appropriate when evidence is thin or the challenge prompts substantially weaken the finding._
-
-## Triage Log
-
-_Populated by `/hstack:kernel-fit-triage` and `/hstack:kernel-fit-promote` as the finding's status transitions. Section is empty until the first transition out of `open`._
-
-- `status: open → acknowledged` on `<YYYY-MM-DD>` by `<owner>`. Triggered by `/hstack:kernel-fit-triage <id> --action acknowledge`.
-- `status: open → dismissed` on `<YYYY-MM-DD>` by `<owner>`. Reason: `<dismissed-reason>`.
-- `status: acknowledged → promoted` on `<YYYY-MM-DD>` by `<owner>`. Promoted to: `<promoted-to>`. Triggered by `/hstack:kernel-fit-promote <id> --slug <adr-slug>`.
-- `status: open → superseded` on `<YYYY-MM-DD>` by the next `kernel-fit-analyst` run. Superseded by: `<superseded-by>`.

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

@@ -1,52 +0,0 @@
----
-id: flag-<YYYYMMDD>T<HHMMSS>-<session-id-short>
-type: kernel-fit-flag
-status: pending                          # pending | processed
-session-id: <claude-code-session-uuid>   # FL-01: non-null at pin-time
-session-transcript-path: <abs-path-to-jsonl>  # FL-01: non-null at pin-time
-branch: <current-branch>                 # FL-01: non-null at pin-time
-head: <current-HEAD-sha>                 # FL-01: non-null at pin-time
-workspace: <abs-path-to-cwd>             # FL-01: non-null at pin-time
-timestamp: <ISO-8601 timestamp at pin>   # FL-01: non-null at pin-time
-pre-compaction-message-count: <integer>  # FL-01: non-null at pin-time; analyst uses this to detect truncation between pin and scan
-hint: null                                # one-word string from --hint arg; null when no arg given
-classification: null                      # FL-02: non-null when status: processed; one of friction | missing-guardrail | kernel-vs-practice-mismatch | not-actionable | transcript-truncated
-classification-rationale: null            # FL-02: non-null when status: processed; one-line analyst note
-folded-into: null                         # KF-NNNN-<slug> when the analyst folded the signal into an existing finding
-emitted-as: null                          # KF-NNNN-<slug> when the analyst emitted a fresh finding from this pin
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
-
-<!--
-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 (`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
-  analyst-owned fields (classification, classification-rationale,
-  folded-into, emitted-as) must remain null until processing.
-
-- FL-02: at processing-time (status: processed) `classification` and
-  `classification-rationale` must both be non-null. When the classification
-  produced a finding, exactly one of `folded-into` or `emitted-as` is non-null
-  (never both). When the classification did not produce a finding (closed as
-  `not-actionable` or `transcript-truncated`), both remain null.
-
-Pins are immutable from the engineer's perspective. The only legal writes
-after creation are by the kernel-fit-analyst at processing time, setting the
-four analyst-owned fields and flipping status to processed. The engineer
-cannot edit a pin to add commentary — that would re-open the contamination
-surface the analyst guards against. To add context, re-flag in a follow-up
-turn (a new pin with a different timestamp).
-
-Pins live at hstack/kernel-fit/flags/pending/ before processing and at
-hstack/kernel-fit/flags/processed/ after. The directory is gitignored in
-the consuming repo — see ADR-0005 for the rationale and the trade-off
-(provenance gap unique to this artifact type).
--->

package/template/templates/module-spec.md

@@ -1,49 +0,0 @@
----
-id: <module-key>                       # equals the module key in hstack/config.yaml
-type: module-spec
-status: drafted                        # drafted | current | needs-refresh | archived
-owner: <git-handle>
-paths: []                              # required; canonical module-to-paths mapping (globs)
-last-refreshed: <YYYY-MM-DD>
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
-
-## Purpose
-
-_What this module is responsible for. 2–4 sentences. Author may grep `paths` to verify._
-
-## Public Surface
-
-_Exports, routes, RPCs the module exposes outward. Bullets._
-
--
-
-## Data Owned
-
-_Tables, columns, and indexes this module is the canonical owner of. Bullets._
-
--
-
-## External Dependencies
-
-_Other modules, third-party services, MCPs this module depends on. Bullets._
-
--
-
-## Invariants
-
-_Challenge prompt: what would a careless refactor in this module break that the tests would not catch? Minimum 3 bullets (validator rule MS-03)._
-
--
--
--
-
-## Known Tech-Debt and ADRs
-
-_Pointers._
-
-## Refresh Policy
-
-_What triggers a refresh and what the refresh entails. One paragraph. The 60-day `needs-refresh` cron flags this spec if untouched._

package/template/templates/persona.md

@@ -1,38 +0,0 @@
----
-id: persona-<slug>
-type: persona
-status: drafted                        # drafted | current | needs-refresh | archived
-owner: <git-handle>
-anchored-on: <design-partner-slug>
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
-
-## Role
-
-_Title and seniority._
-
-## Context
-
-_Tools they use today. Team size. KPI they are measured against._
-
-## Jobs-to-be-done
-
-_Bullets._
-
--
-
-## Edge constraints
-
-_Anything unusual: compliance, time zone, locale, accessibility, device class._
-
--
-
-## Anti-pattern
-
-_What this persona explicitly is not. Helps prevent persona drift on future stories._
-
-## Anchored design partner
-
-_Name and contact rhythm. Private — keep this section out of any export. When persona store is in repo, the file housing this section should be in `.gitignore` (see hstack/config.yaml personas-location)._

package/template/templates/plan.md

@@ -1,53 +0,0 @@
----
-id: <parent-change-id>-plan
-type: plan
-status: draft                          # draft | ready | in-progress | completed | archived
-owner: <git-handle>
-parent-change: <change-spec-id>
-steps-completed: []                    # populated by `implementer` as phases finish
-blocked-on: null                       # phase id when an interactive blocker stops progress
-oversized-plan-justification: null     # required when phase count > 12
-created: <YYYY-MM-DD>
-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._
-
-| step-id | summary | depends-on |
-| --- | --- | --- |
-| phase-1- |  | none |
-
-## Per-Phase Detail
-
-_One subsection per phase. 4–8 phases typical. >12 requires `oversized-plan-justification` in frontmatter._
-
-### phase-1-
-
-**Purpose.** _One sentence._
-
-**Files Touched.** _Subset of `change-spec.in-scope`. Bullets._
-
--
-
-**Test Strategy.** _Pointer to the test-plan section(s) this phase satisfies. Format: `test-plan §<section> — <one-line summary>`. The phase lands the tests named in the referenced section; do not restate or invent tests here. If this phase's work is exclusively non-test (e.g., a migration whose tests live in a later phase), state that explicitly and name the downstream phase that closes the loop._
-
-**Risk.** _One sentence on what could go wrong locally._
-
-**Verifier Expectations.** _What `verifier` must observe to mark this phase passed. References both this plan's Test Strategy and the test-plan sections the phase satisfies._
-
-## Cross-Phase Risks
-
-_Challenge prompt: what could go wrong across phase boundaries that no single phase catches? 1–3 bullets._
-
--
-
-## Rollback
-
-_What to do if a partial rollout in production breaks something. 2–4 sentences._

package/template/templates/product-brief.md

@@ -1,56 +0,0 @@
----
-id: product-brief
-type: product-brief
-status: draft                          # draft | current | needs-refresh | archived
-owner: <git-handle>
-technique-used: <brainstorm | forcing-questions | project-brief>
-derived-from: []                       # always empty — product-brief is Phase 1, no upstream
-downstream: [vision, roadmap, personas, glossary]
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
-
-## Underlying Pain
-
-_What the user actually struggles with on a Tuesday morning, in concrete terms. Not "users want X" — "this specific person spends 20 minutes doing Y and misses Z." One paragraph, 4–8 sentences. The forcing-prompt reframes should have moved this away from the founder's first articulation; the result lands here._
-
-## Target User
-
-_A named, specific user (not "users", not "customers") with a workday vignette. Includes role, company-size band, tools they use today, the workflow this product enters. If multiple personas matter for v1, name them all — but each must pass the concreteness floor._
-
-## Value Proposition
-
-_What this product delivers to the named user, in their language. One paragraph. Distinct from features — this is the outcome they buy._
-
-## Smallest Useful Wedge
-
-_The minimum shippable surface that delivers real value to the named user. Forcing-prompt answer: "Would the named user still pay for this if you shipped only the wedge and nothing else?" Yes required; if no, the wedge is too large or the user is wrong._
-
-## Success Criteria
-
-_Concrete, measurable, time-bound. "Maya saves 10 minutes per QBR prep within 4 weeks of activation" not "users love it." At least one criterion; more is better._
-
-## Explicitly NOT
-
-_Two-bullet minimum. The boundaries of the product. What this is NOT, what it does NOT do, what populations it does NOT serve. Required, never optional — over-broad scoping is the #1 product failure mode._
-
--
--
-
-## Open Risks
-
-_The things that could make this product fail. The forcing-prompt "What would you have to believe to be wrong about this?" answer lands here. At least one risk; more is better._
-
-## Forcing-Prompt Answers
-
-_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")._
-
-**What's the smallest useful wedge?**
-_The wedge plus the rationale ("Change-awareness alone, because the rest of the workflow is downstream of it")._
-
-**What would you have to believe to be wrong about this?**
-_The belief plus the falsifiability angle ("That CS reps will trust LLM-generated summaries — wrong if they require human-curated context")._

package/template/templates/security-review.md

@@ -1,63 +0,0 @@
----
-id: <parent-change-id>-security-review
-type: security-review
-status: draft                          # draft | in-progress | passed | concerns-acknowledged | failed | superseded
-owner: <git-handle>
-parent-change: <change-spec-id>
-scoring-mode: llm-scored               # v1; v2 introduces 'executed'
-scores:
-  data-at-rest: not-applicable         # pass | concerns | fail | not-applicable
-  data-in-transit: not-applicable
-  authn: not-applicable
-  authz-rls: not-applicable
-  tenant-isolation: not-applicable
-  input-validation: not-applicable
-  output-encoding: not-applicable
-  secrets-handling: not-applicable
-  agent-prompt-injection: not-applicable
-  audit-logging: not-applicable
-concerns-acknowledged-by: null         # handle required when any score is `concerns`
-threat-model-delta-required: false     # true when surfaces touches agent | auth | api | db
-challenge-prompts-answered: 0          # must equal 3 to pass
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
-
-## Surfaces Touched
-
-_Pointer to change-spec `surfaces`. One sentence per surface._
-
-## Hardening Items Scored
-
-_For every applicable checklist item, a one-paragraph rationale for the score. Bias toward CONCERNS rather than PASS when evidence is thin._
-
-### data-at-rest
-
-### data-in-transit
-
-### authz-rls
-
-### tenant-isolation
-
-### input-validation
-
-### audit-logging
-
-## Threat-Model Delta
-
-_Required when `threat-model-delta-required: true`. One paragraph delta against the current threat-model.md. Refuse to score until this is non-empty when surfaces require it._
-
-## Challenge Prompts
-
-_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.
-
-### (b) Which tenant_isolation guarantee does this change depend on? Cite the line of code that enforces it.
-
-### (c) What part of this change would behave incorrectly under a malicious payload that the test suite does not cover?
-
-## Open Concerns
-
-_When any score is `concerns`: what acknowledgement is required and by whom. Ack must be human-confirmed by `owner` before status: concerns-acknowledged._