hstack 0.16.0 → 0.17.0

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

@@ -1,166 +1,60 @@
 ---
 name: hstack-adversarial-review
-description: Use only in a fresh Claude Code session — separate from the one that ran the implementer — once `verification.md` is at `passed` and the change is at `ready-for-review`. Orchestrates the `adversarial-reviewer`, which reads the change cold.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — validates adversarial-review frontmatter and AR-01..AR-06"
-  - "{{TODO-OTHER: fresh-session-attestation — in v1, the subagent self-attests the session is fresh; v2 substrate captures and compares Claude Code session ids automatically}}"
+description: "Use in a fresh session — never the one that wrote the change — to review a PR that touches a sensitive surface. Findings land as a PR comment; the author is the one who fixes them."
 ---
 
 ## Purpose
 
-`hstack-adversarial-review` produces `adversarial-review.md` by orchestrating the `adversarial-reviewer` subagent in a Claude Code session separate from the one that ran the implementer. The subagent reads the change cold, and "no problems" is a claim it has to defend rather than a default it may fall into. In v1, fresh-session separation is honor-system; the Skill's first job is to remind the engineer of that.
+`/hstack-adversarial-review <pr-number>` reads an open PR cold and reports what is wrong, missing,
+drifted or weakened. It orchestrates the `adversarial-reviewer` subagent and posts the findings on
+the PR. It writes no file and changes no code.
 
-Per ADR-0014 the review is not scored on its finding count. `findings-floor` stays in frontmatter as the area's expectation and lands in the telemetry sidecar, but nothing gates on it; the one count the artifact must argue for is zero (AR-01).
+Reviews are judgments, not evidence (kernel § Review). An empty findings list means the reviewer
+found nothing, not that nothing is there — which is why an empty result is defended rather than
+returned.
 
 ## When to invoke
 
-Invoke after `verification.md` reaches `status: passed`, in a **fresh Claude Code session**. The Skill opens with a clear instruction to the engineer naming the requirement. If the engineer reports they are in the same session as the implementer, halt and ask them to start a new session.
-
-## Inputs
-
-- `<change-id>` (required, positional): the change-spec id.
-
-## Preconditions
-
-Before any work:
-
-- **Fresh-session attestation.** The Skill's first action is to print: "This Skill must run in a Claude Code session separate from the one that ran `hstack-implement`. The kernel's authoring-and-review-never-share-a-session principle is honor-system in v1; v2 substrate will verify via session-id comparison. Confirm you are in a fresh session before I proceed." Halt until the engineer confirms.
-- Verify the change-spec exists and is at `status: ready-for-review`.
-- Verify every required upstream artifact is at terminal status:
-  - test-plan at `passed` or `concerns-acknowledged`
-  - plan at `completed`
-  - security-review at `passed` or `concerns-acknowledged`
-  - data-review at `passed` or `concerns-acknowledged` when applicable
-  - ui-brief at `drafted` and figma-handoff at `ready` when applicable
-  - verification at `passed`
-- Set `findings-floor`: 3 default; 5 when `change-spec.area` is in {agent, auth, billing} per AR-06. It is recorded, not enforced.
-
-## 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. **Open with the fresh-session reminder.** Print the message verbatim; wait for the engineer's confirmation.
-
-2. **Invoke `adversarial-reviewer`.** Use the Task tool with `subagent_type: adversarial-reviewer` and context = [kernel, `hstack/templates/adversarial-review.md`, change-spec, plan, test-plan, ui-brief and figma-handoff when present, security-review, data-review when present, verification, full diff, module-spec, threat-model, hardening-checklist, data-architecture, tech-stack]. Explicitly NOT included: any implementer conversation transcript or scratchpad.
-
-3. **Findings generation across six categories.** The subagent sweeps security, scope-drift, invariant-breach, spec-compliance, data-integrity, and code-quality and reports what the sweep found — the categories are lenses, not buckets, and a change whose risk genuinely lives in one dimension produces findings in one category. `references/finding-categories.md`, alongside this file, is the calibration rubric (what each category means, what a real finding looks like, what filler looks like); the subagent reads it on demand, not on every run. Test-plan adherence is a first-class lens: missing edge-case tests surface as spec-compliance findings; missing tenant-isolation tests surface as data-integrity findings; unmet performance budgets surface as code-quality or data-integrity findings depending on cause; unmapped invariants in `verification.test-plan-coverage` surface as spec-compliance findings. **Test-immutability audit:** the subagent diffs every pre-existing test file against the branch base; any modification, deletion, or snapshot update without a matching `Ok to change/delete/update/refresh ...` authorization echo in a commit message is a mandatory finding under spec-compliance at minimum `severity: high`. Bulk snapshot-update flags visible in the diff or in CI logs escalate to `severity: critical`. This audit is mandatory and is not subject to the subagent's judgment about whether the finding is worth filing.
-
-4. **The empty result is the one the artifact defends.** Per AR-01, a review that reaches `findings-open` or `findings-resolved` with an empty `findings` array must set `findings-fewer-than-floor: true` and write a defended `justification-when-fewer` plus a filled Findings Floor Justification section, enumerating what was looked for and why each sweep came back clean. "The change is small" alone is insufficient. Any count above zero passes AR-01; `findings_count` against `findings_floor` is reported to telemetry and read in aggregate, never as a per-review gate.
-
-5. **Resolution discipline.** Each finding's `resolution` is one of:
-   - `commit:<hash>` — must reference an existing commit on the change's branch (AR-04).
-   - `tech-debt:<id>` — must reference an existing tech-debt artifact at `open` or `in-progress` (AR-05). When the engineer chooses this path, they invoke `hstack-tech-debt-new` to create the tech-debt artifact before this review terminates.
-   - `justified-in-prose` — reserved for low-severity findings only. High-severity findings routed to `justified-in-prose` halt the Skill.
-
-6. **Fresh-session attestation in frontmatter.** The subagent writes `fresh-session-attestation: "session <id>; opened <timestamp>; no prior implementer context loaded"`. v1 records this as honor-system text; v2 substrate captures the actual session id from Claude Code's session file.
-
-7. **Findings-open is non-terminal.** The subagent does not advance `status: findings-resolved` until every finding has `status: resolved` and a `resolution` value.
-
-8. **Owner response loop.** For each finding, the engineer (the change owner) responds with a resolution. The Resolution Log section records each response. The Skill walks the engineer through every finding sequentially.
-
-9. **Validate.** Run `node hstack/scripts/validate-spec.mjs <path>` — AR-01 through AR-06.
-
-10. **Change-spec advance (mechanical, only on `findings-resolved`, Skill-orchestrator write per ADR-0002).** When and only when the subagent returned with `adversarial-review.md` at `status: findings-resolved`, read `hstack/specs/changes/<change-id>/spec.md` and inspect its `status` frontmatter. If `status: ready-for-review`, print a proposed-diff preview of the change-spec edit (`status: ready-for-review → ready-to-ship`; `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-to-ship`. This is a separate commit from the adversarial-review transition commits, matching the verify and finalize precedents. If the change-spec is already at `ready-to-ship` or any downstream status (`shipped`, `archived`), this step is a no-op (idempotent on re-runs). When adversarial-review status is `findings-open` or `in-progress`, this step does not run — the change-spec remains at `ready-for-review` until every finding is resolved. The `adversarial-reviewer` subagent retains its critique-only lane and writes only `adversarial-review.md`; the cross-artifact advance is the Skill orchestrator's own write, per ADR-0002.
-
-## Outputs
-
-- `hstack/specs/changes/<change-id>/adversarial-review.md` at `status: findings-resolved`.
-- When `adversarial-review.md` lands at `findings-resolved` and the change-spec was at `ready-for-review`: an edit to `hstack/specs/changes/<change-id>/spec.md` advancing `status: ready-for-review → ready-to-ship` and bumping `updated:` (per ADR-0002, written by the Skill orchestrator).
-- Optional new tech-debt artifacts produced via `hstack-tech-debt-new` invocations when findings route to `tech-debt:<id>`.
-- Optional new commits on the change's branch when findings route to `commit:<hash>` and the implementer is re-invoked (separately, via `hstack-implement`) to make the fix.
-
-## Auto-commit triggers
-
-- Status transition to `in-progress` after Methodology lands.
-- Status transition to `findings-open` after all findings are written.
-- Status transition to `findings-resolved` when every finding has `status: resolved`.
-- Edits to the `findings` array.
-- Edits to any finding's `resolution`.
-- **Change-spec status transition `ready-for-review` → `ready-to-ship`** (per ADR-0002, Skill-orchestrator write). When `adversarial-review.md` reaches `findings-resolved`, the Skill orchestrator performs the change-spec advance directly via `Edit` (orchestration step 10), in a separate auto-commit with message `change-spec(<change-id>): ready-to-ship`. The change-spec becomes eligible for `hstack-ship` only after this commit lands. `hstack-ship` itself remains read-only across artifact statuses — it reads the already-written `ready-to-ship` and computes the merge-readiness scorecard. The `adversarial-reviewer` subagent does not write this transition; it stays in its critique-only lane.
-
-## Telemetry sidecar
-
-At the change-spec advance commit (only when adversarial-review status is `findings-resolved`), write `hstack/specs/changes/<change-id>/.telemetry/adversarial-review.json` in the same `git add && git commit` as the change-spec advance. The sidecar is derivative of git + frontmatter (see `hstack/templates/telemetry-sidecar.md`). Schema:
-
-```json
-{
-  "schema_version": 2,
-  "skill": "hstack-adversarial-review",
-  "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>",
-  "reviewed_at": "<ISO-8601, when status reached findings-resolved>",
-  "findings_floor": <int, 3 or 5 per AR-06>,
-  "findings_count": <int, length of frontmatter findings array>,
-  "findings_fewer_than_floor": <bool>,
-  "category_counts": {
-    "security": <int>,
-    "scope-drift": <int>,
-    "invariant-breach": <int>,
-    "spec-compliance": <int>,
-    "data-integrity": <int>,
-    "code-quality": <int>
-  },
-  "severity_counts": {
-    "critical": <int>,
-    "high": <int>,
-    "medium": <int>,
-    "low": <int>
-  },
-  "resolution_mix": {
-    "commit": <int>,
-    "tech-debt": <int>,
-    "justified-in-prose": <int>
-  },
-  "fresh_session_attestation": "<verbatim copy of frontmatter field>",
-  "halt_reasons": [<kernel halt-sentinel enum values, if any>]
-}
-```
-
-When the review ends at `findings-open` or `in-progress` (no change-spec advance), the sidecar still lands with the same shape on whichever transition commit terminates the current run; `findings_fewer_than_floor` reflects the current value. `.telemetry/` is git-ignored. If the sidecar write fails, log and continue; the canonical commit must still land. Since ADR-0014 removed the quota this sidecar stopped being a fraud detector and became a description: `findings_count` against `findings_floor`, `category_counts`, `severity_counts` and `resolution_mix` describe what reviews are finding, and shifts in the joint distribution are the instrument for judging whether the judgment-based framing reads changes better or worse than the count did.
-
-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
-
-`adversarial-review` is a natural session cut: the auto-commit above left `adversarial-review.md` at its terminal status 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: adversarial-review complete — cut recommended before ship.
-```
-
-and the next command, `/hstack:ship <change-id>`.
-
-## Idempotency contract
-
-- Re-running on a `findings-resolved` review: the subagent reads the existing artifact and produces a no-op aside from `updated` timestamps, unless new code or artifacts have landed since the prior run (in which case new findings may be generated and the status drops back to `findings-open`).
-- Re-running mid-resolution after a halt: the subagent reads the partial artifact and resumes with the first finding still at `status: open`.
-- The change-spec advance step (step 10) is idempotent: a re-run against a change-spec already at `ready-to-ship` (or `shipped`, `archived`) produces a no-op for that step. The Skill does not re-advance and does not regress.
+On a PR touching one of the sensitive surfaces the kernel § Review names. Every PR already gets
+`/review` and `/security-review` through `/wrap`; this is the deep pass on top, and its whole value
+is that the session running it never saw the change being written.
+
+**In a fresh session.** State it in one sentence before starting — "this session has not seen the
+implementation conversation" — and if that is not true, stop and open a new one. This is
+honor-system, as the kernel says; a sentence is the whole protocol.
+
+## Steps
+
+1. **Load the change.** `gh pr view <n>` for the description, `gh pr diff <n>` for the diff, plus
+   the base commit so pre-existing files can be diffed. Read the living docs the diff touches,
+   `hstack/context/invariants.md`, and the frozen `threat-model.md`. Do not load, ask for, or
+   reconstruct the conversation that produced the change.
+2. **Invoke `adversarial-reviewer`** with that material. The subagent sweeps six lenses and returns
+   findings; it does not resolve them and does not touch the code.
+3. **The test-immutability audit is mandatory** and is not subject to anyone's judgment about
+   whether it is worth filing. Every test file that existed at the base is diffed; a modification
+   or deletion without its canonical authorization echo — `Ok to change test <name>` /
+   `Ok to delete test <name>`, in a commit message or the PR description — is a finding at `high`
+   minimum. A bulk snapshot update is `critical`.
+4. **Post the findings** with `gh pr comment <n>`, or as a GitHub review when they are anchored to
+   lines. Each finding carries a severity, a category, the evidence in the diff, and what would
+   resolve it.
+5. **Resolution belongs to the author**: a corrective commit on the branch, or a tech-debt file
+   written in the same PR (kernel § Tech-debt). The reviewer never pushes the fix.
+
+## Output
+
+One PR comment. No artifact, no status, no file in the repo.
 
 ## Stop conditions
 
-Beyond the kernel's general stop conditions:
-
-- Engineer has not confirmed they are in a fresh Claude Code session.
-- A required upstream artifact is non-terminal.
-- A high-severity security or tenant-isolation finding would route to `justified-in-prose`. Halt.
-- A `commit:<hash>` resolution would reference a commit not on the change's branch.
-- A `tech-debt:<id>` resolution would reference a non-existent tech-debt artifact (the engineer must invoke `hstack-tech-debt-new` first).
-- The review found nothing and the empty-result defence cannot be written honestly. Halt and surface; a defence nobody believes is worse than an open review.
-- The diff includes changes outside `change-spec.in-scope` that CI did not catch — surface a scope-drift finding and halt the CI gap as a separate concern.
-- An implementer transcript or scratchpad is visible in the session.
-
-## Failure modes
+Beyond the kernel's:
 
-- **Engineer claims fresh session but conversation shows prior implementer transcripts.** Halt; ask the engineer to truly start a new session.
-- **The review comes back empty and the defence feels thin.** Walk the six categories against `references/finding-categories.md` once more; if the sweep is still clean, the empty result is defended explicitly and on the record, not waved through.
-- **A finding routes to `tech-debt:<id>` but the engineer hasn't created the tech-debt artifact.** The Skill prompts to invoke `hstack-tech-debt-new`; the review does not terminate until the artifact exists.
-- **A commit hash named in `resolution` does not exist on the change's branch.** Halt — the engineer either re-references the correct commit or the resolution is reconsidered.
+- The session has seen the implementation conversation. Halt and ask for a fresh one.
+- The PR cannot be read, or its diff is unavailable.
+- A living doc the review depends on is missing or stale. Say so in the findings; never invent its
+  content (kernel § Context docs).
+- The sweep came back empty and the defence cannot be written honestly. Halt and surface it — a
+  defence nobody believes is worse than an open review.
+- A high-severity finding is waved away without a fix or a tech-debt file. Do not silently retract:
+  restate it with the evidence, and leave it in the comment.

package/template/.claude/skills/hstack-adversarial-review/references/finding-categories.md

@@ -1,157 +1,134 @@
 # The six finding categories — a calibration rubric
 
-Reference file for `hstack-adversarial-review` and the `adversarial-reviewer`
-subagent. Read it when a category is unfamiliar, when a finding feels thin and
-you want to know whether it is real, or when calibrating severity against
-precedent. It is **not** a checklist: nothing here says how many findings a
-review should produce, and a review that lands entirely in one category is a
-correct outcome when the change carries its risk in one dimension (ADR-0014).
-
-The `category` value in a finding record is a controlled enum — the six names
-below, exactly — and AR-02 rejects anything else.
+Reference file for `hstack-adversarial-review` and the `adversarial-reviewer` subagent. Read it
+when a category is unfamiliar, when a finding feels thin and you want to know whether it is real,
+or when calibrating a severity. It is **not** a checklist: nothing here says how many findings a
+review should produce, and a review landing entirely in one category is the correct outcome when
+the change carries its risk in one dimension (ADR-0014).
 
 ---
 
 ## security
 
-**What it means.** The change creates or widens a path an attacker can use, or
-weakens a control that was closing one. Distinct from `data-integrity`: this is
-about an adversary, not about accidental corruption.
+**What it means.** The change creates or widens a path an attacker can use, or weakens a control
+that was closing one. Distinct from `data-integrity`: this is about an adversary, not about
+accidental corruption.
 
-**Real findings look like.** A new endpoint that reads a user-supplied id and
-queries by it without re-deriving the caller's scope. A prompt that
-concatenates retrieved document text into a system message. A secret moved from
-an env read to a literal. An auth check that runs after the side effect. A
-dependency bump that pulls a package with a known CVE the security-review did
-not see because the lockfile changed outside `in-scope`.
+**Real findings look like.** A new endpoint that reads a user-supplied id and queries by it without
+re-deriving the caller's scope. A prompt that concatenates retrieved document text into a system
+message. A secret moved from an env read to a literal. An auth check that runs after the side
+effect. A dependency bump that pulls a package with a known CVE.
 
-**Filler looks like.** "Consider adding rate limiting" on a change that touches
-no network surface. Restating a hardening-checklist item the security-review
-already scored `pass`, with no evidence from the diff that the score is wrong.
+**Filler looks like.** "Consider adding rate limiting" on a change that touches no network surface.
+Restating an item of the kernel's security checklist with no evidence from the diff that it was
+missed.
 
-**Severity.** Anything exploitable by a non-authenticated caller, or that
-crosses a tenant boundary, is `critical` or `high` — never `medium` because it
-is unlikely. Likelihood belongs in the severity rationale, not in the level.
+**Severity.** Anything exploitable by an unauthenticated caller, or that crosses a tenant boundary,
+is `critical` or `high` — never `medium` because it is unlikely. Likelihood belongs in the severity
+rationale, not in the level.
 
 ---
 
 ## scope-drift
 
-**What it means.** The diff touches things `change-spec.in-scope` does not
-name, or the change quietly grew a second purpose.
+**What it means.** The diff touches things the PR description's announced perimeter does not name
+(kernel § Scope rules), or the change quietly grew a second purpose.
 
-**Real findings look like.** A refactor of a shared util that no phase in
-`plan.md` asked for. A migration that alters a table outside the change's
-module. A "while I was in there" rename that makes the diff unreviewable. A new
-dependency added to satisfy a convenience the spec never asked for.
+**Real findings look like.** A refactor of a shared util nothing in the change asked for. A
+migration altering a table outside the change's module. A "while I was in there" rename that makes
+the diff unreviewable. A new dependency satisfying a convenience nobody asked for.
 
-**Filler looks like.** Flagging a file the change-spec's globs do cover on a
-literal reading. Flagging generated files, lockfiles, or formatter output that
-the repo's conventions produce automatically.
+**Filler looks like.** Flagging a file the announced perimeter does cover. Flagging generated
+files, lockfiles or formatter output the repo's conventions produce automatically.
 
-**Severity.** Usually `medium`. It escalates when the drift lands in a module
-with its own module-spec invariants, because then it is also `invariant-breach`
-and CI's scope gate did not catch it.
+**Severity.** Usually `medium`. It escalates when the drift lands on a path `invariants.md` covers,
+because then it is also `invariant-breach`.
 
 ---
 
 ## invariant-breach
 
-**What it means.** Something the change-spec or the relevant module-spec
-declares as always-true is no longer always-true after this diff.
+**What it means.** Something `hstack/context/invariants.md` or a living doc declares as always-true
+is no longer always-true after this diff.
 
-**Real findings look like.** A module-spec that says "no direct SQL outside this
-module" and a new query in an adjacent file. A change-spec invariant about
-ordering that the new code path can violate under concurrency. An invariant
-that is still true but is now enforced by convention where it used to be
-enforced by a type or a constraint.
+**Real findings look like.** An invariant about ordering that the new code path can violate under
+concurrency. An invariant still true but now enforced by convention where it used to be enforced by
+a type or a database constraint. A boundary a living doc describes — "no direct SQL outside this
+module" — and a new query in an adjacent file.
 
-**Filler looks like.** Paraphrasing an invariant back and calling it a risk.
-Naming an invariant the diff does not touch.
+**Filler looks like.** Paraphrasing an invariant back and calling it a risk. Naming an invariant the
+diff does not touch.
 
-**Severity.** `high` by default — an invariant that can break silently is worse
-than a bug that throws. Drop to `medium` only when the breach is caught by an
-existing test that will fail loudly.
+**Severity.** `high` by default — an invariant that breaks silently is worse than a bug that throws.
+Drop to `medium` only when an existing test fails loudly on the breach.
 
 ---
 
-## spec-compliance
+## intent-compliance
 
-**What it means.** The diff and the artifacts disagree. This is the category
-with the widest surface and the one most often under-used.
+**What it means.** The diff and what the PR says it does disagree. The widest category and the one
+most often under-used. The PR description is the contract here: it names the perimeter, the Notion
+feature, the shortcuts taken, the living docs updated.
 
-**Real findings look like.** An acceptance criterion in the change-spec with no
-corresponding behaviour in the diff. An edge case the `test-plan` promised and
-the diff did not land. A tenant-isolation test named in the test-plan and
-absent from the branch. An invariant in the change-spec that
-`verification.test-plan-coverage` maps to no observed test. Behaviour the
-implementation added that no artifact anticipated — undeclared scope is a
-compliance gap in the other direction. **Any test-file modification without its
-canonical authorization echo** (see `KERNEL.md` § Test immutability); this one
-is mandatory and never subject to judgment about whether it is worth filing.
-When `resolves-tech-debt` is non-empty, any Acceptance bullet the diff leaves
-`partial` or `not-satisfied` (AR-07).
+**Real findings look like.** Behaviour the description promises and the diff does not land.
+Behaviour the diff adds that no line of the description anticipated — undeclared scope is a
+compliance gap in the other direction. A living doc the change invalidated and left untouched
+(kernel § Context docs). A conscious shortcut visible in the code and named nowhere. **Any
+test-file modification without its canonical authorization echo** (`KERNEL.md` § Test immutability);
+this one is mandatory and never subject to judgment about whether it is worth filing.
 
-**Filler looks like.** "The spec could have been clearer." Style disagreements
-with the plan's phase decomposition.
+**Filler looks like.** "The description could have been clearer." Style disagreements with how the
+work was sequenced.
 
-**Severity.** Unauthorized test changes: `high` minimum, `critical` for bulk
-snapshot updates. Unmet Acceptance bullets: `high`, `critical` once the change
-is at `ready-to-ship`. Everything else: judgment.
+**Severity.** Unauthorized test changes: `high` minimum, `critical` for a bulk snapshot update. A
+stale living doc: `high`, because the next session will read it and believe it. Everything else:
+judgment.
 
 ---
 
 ## data-integrity
 
-**What it means.** Data can end up wrong, lost, or visible to the wrong tenant
-without anybody attacking anything.
+**What it means.** Data can end up wrong, lost, or visible to the wrong tenant without anybody
+attacking anything.
 
-**Real findings look like.** A migration that adds a NOT NULL column without a
-default or a backfill. A destructive DDL with no stated rollback. An RLS policy
-whose predicate does not match the tenancy model in `data-architecture.md`. A
-tenant-scoped RPC missing its `tenant_id` filter. A write path that is
-not idempotent under retry. A pgvector retrieval that filters after the
-similarity search rather than inside it.
+**Real findings look like.** A migration adding a NOT NULL column with no default and no backfill.
+A destructive DDL with no stated rollback. An RLS policy whose predicate does not match the tenancy
+model in `data-architecture.md`. A tenant-scoped RPC missing its tenant filter. A write path that
+is not idempotent under retry. A pgvector retrieval filtering after the similarity search rather
+than inside it.
 
-**Filler looks like.** Speculating about scale on a table with a bounded row
-count. Recommending an index with no query to justify it.
+**Filler looks like.** Speculating about scale on a table with a bounded row count. Recommending an
+index with no query to justify it.
 
-**Severity.** Cross-tenant leakage is `critical` — always, including when the
-leak needs an unlikely sequence to trigger. Irreversible data loss is
-`critical`. Recoverable inconsistency is `high`.
+**Severity.** Cross-tenant leakage is `critical` — always, including when the leak needs an unlikely
+sequence to trigger. Irreversible data loss is `critical`. Recoverable inconsistency is `high`.
 
 ---
 
 ## code-quality
 
-**What it means.** The change works and will cost more than it should to live
-with. The weakest category and the easiest to pad, which is why it is worth
-being strict about what belongs here.
+**What it means.** The change works and will cost more than it should to live with. The weakest
+category and the easiest to pad, which is why it is worth being strict about what belongs here.
 
-**Real findings look like.** A third copy of logic that already exists twice,
-where the copies have started to disagree. Error handling that swallows a
-failure the caller needs. A function whose behaviour depends on call order with
-nothing that documents or enforces it. A performance budget in the test-plan
-that the implementation cannot meet as written.
+**Real findings look like.** A third copy of logic that already exists twice, where the copies have
+started to disagree. Error handling that swallows a failure the caller needs. A function whose
+behaviour depends on call order with nothing that documents or enforces it.
 
-**Filler looks like.** Naming preferences. Suggested comments. Requests to
-extract a function that is used once. Anything a formatter or a linter would
-have said, since `run-gates.sh` already ran.
+**Filler looks like.** Naming preferences. Suggested comments. Requests to extract a function used
+once. Anything a formatter or a linter would have said.
 
-**Severity.** `low` or `medium`. A `code-quality` finding at `high` is usually
-mis-categorized — look again at whether it is really `invariant-breach` or
-`data-integrity`.
+**Severity.** `low` or `medium`. A `code-quality` finding at `high` is usually mis-categorized —
+look again at whether it is really `invariant-breach` or `data-integrity`.
 
 ---
 
-## Resolution routing
+## Resolution
 
-Independent of category:
+Independent of category, a finding names what would resolve it:
 
-- `commit:<hash>` — fixed on the branch. The hash must exist there (AR-04).
-- `tech-debt:<id>` — acknowledged and deferred, against a tech-debt artifact
-  that exists at `open` or `in-progress` at write time (AR-05).
-- `justified-in-prose` — the finding is real and the right answer is to explain
-  why nothing changes. Reserved for `low` severity. A `high`-severity finding
-  routed here is a halt, and a security or tenant-isolation finding routed here
-  is a halt with escalation.
+- **A corrective commit on the branch** — the author fixes it before the merge.
+- **A tech-debt file in the same PR** — the finding is real and is being lived with, on the record
+  and grep-able by `related-modules` (kernel § Tech-debt).
+- **An argument in the comment thread** — the finding is real and the right answer is to explain
+  why nothing changes. Fine for a `low`; a `high` answered this way stays open, and a security or
+  tenant-isolation finding answered this way is escalated, not closed.

package/template/.claude/skills/hstack-app-architecture/SKILL.md

@@ -1,82 +1,57 @@
 ---
 name: hstack-app-architecture
-description: Use to produce or refresh `hstack/context/app-architecture.md` — module map, agent orchestration, deterministic-vs-LLM split, state ownership, surface boundaries. Greenfield Phase 3, the brownfield app-architecture step, or a standalone section refresh.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — frontmatter validator"
+description: "Use when the application architecture really moves — modules, LLM call sites, state ownership, surfaces, or what a user can reach — to write or refresh `hstack/context/app-architecture.md`, exposure map included."
 ---
 
 ## Purpose
 
-`hstack-app-architecture` is the atom that produces or refreshes `hstack/context/app-architecture.md` via the `app-architect` subagent. The artifact captures the internal architecture in five sections; subsequent module-spec authoring and per-change-spec `surfaces` declarations depend on it.
+`/hstack-app-architecture` writes or refreshes `hstack/context/app-architecture.md`: the module map
+with its exposure column, the agent orchestration model, the deterministic-vs-LLM split, the
+state-ownership map, the surface boundaries. It is what the next session reads to know what exists
+and what a user can reach.
 
-## When to invoke
-
-- Phase 3 of `/hstack:greenfield-init` (elicit mode).
-- Delegated by `/hstack:brownfield-init` mini-session 5b (extract mode).
-- Standalone via `/hstack:app-architecture [--mode extract|elicit] [--section <name>]` for refresh or single-section edits.
-- Routed-into-from-downstream when `/hstack:stack-decide` finds a stack constraint that contradicts the architecture (rare).
+It is not how the doc stays current day to day — a change that adds a route updates the map in its
+own PR, which is the kernel's rule and costs nothing. This Skill is for the moves that rule cannot
+absorb: the first write, a module boundary that no longer matches the code, an exposure map that
+has drifted away from the real routes.
 
 ## Inputs
 
-- `--mode extract | elicit` — defaults: `extract` if a `src/`, `app/`, or `lib/` tree exists in the consuming repo; `elicit` if the repo is empty (greenfield).
-- `--section <name>` — one of `modules | orchestration | split | state | surfaces`. Fast-jumps but re-runs end-of-atom coherence.
-
-## Preconditions
-
-- `hstack/config.yaml` at `init-status: minimal-complete` or later.
-- `hstack/context/product/product-brief.md` and `hstack/context/data-architecture.md` both at `status: current`. App architecture is downstream of both. If either is at non-terminal status, halt with `HSTACK-HALT: reason=upstream-non-terminal`.
-- `hstack/templates/app-architecture.md` and `hstack/templates/module-spec.md` present.
-- In extract mode, a source tree (`src/`, `app/`, or `lib/`) is reachable; otherwise halt.
-
-## Orchestration steps
-
-1. **Detect mode + entry.** Read disk state. If artifact at `current` and no `--section` and no `--force`: print summary, exit no-op.
-2. **Invoke `app-architect` subagent.** Via the Task tool with `subagent_type: app-architect`. Pass mode, optional section, the canonical session-start context. Explicitly DO NOT pass `tech-stack.md` — the architecture is stack-agnostic.
-3. **Walk sections.** The subagent walks all five sections in order in fresh-start mode. Section 3 (Deterministic-vs-LLM Split) is walked per-flow with per-step confirmation; this is the only section with finer-than-section confirmation gates because per-step declarations are too consequential to batch.
-4. **Run drift challenge prompts.** Each section ends with a drift challenge. A real drift halts with `HSTACK-HALT: reason=upstream-drift` and offers (a) revise this section, (b) re-enter the upstream atom (typically `/hstack:data-architecture --section entities` for state-ownership gaps), (c) log as ADR.
-5. **End-of-atom coherence check.** Even on section-targeted entry, the subagent re-runs all five drift challenges before terminal commit.
-6. **Terminal-state side effects (one atomic commit).** When the artifact reaches `status: current`, the Skill performs three mechanical writes in a single commit:
-   - The completed `app-architecture.md`.
-   - One `hstack/specs/<module>/spec.md` stub per module from Section 1 (header sections only, `status: draft`, body note pointing to `/hstack:module-spec`).
-   - `hstack/config.yaml` updated to set the `surfaces` enum to match Section 5.
-   The proposed-diff preview runs before this commit lands per the kernel's mechanical-operations rule.
-
-## Outputs
-
-- `hstack/context/app-architecture.md` at `status: current`.
-- One `hstack/specs/<module>/spec.md` per module at `status: draft`.
-- `hstack/config.yaml` with updated `surfaces` enum.
-- `hstack/.session-state/<session-id>.yaml` (transient).
-
-## Auto-commit triggers
-
-- Each confirmed section writes immediately and auto-commits.
-- Per-flow row in Section 3 commits individually (not full-section batch).
-- Terminal-state side effects (artifact + stubs + config) land in one atomic commit.
-
-## Idempotency contract
-
-- Artifact at `current` + no `--section` + no `--force`: print summary, exit no-op.
-- Artifact at `draft` or partial: resume at next non-confirmed section.
-- Artifact at `needs-refresh`: walk all sections in confirm-or-revise mode.
-- Module-spec stubs at `status: draft`: the atom does NOT overwrite stubs on re-run; if Section 1 added a module on refresh, the new stub lands additively; if Section 1 removed a module, the orphan stub is flagged for engineer review (the engineer either deletes it or routes the deletion through `/hstack:tech-debt-stale`).
+`--section modules | orchestration | split | state | surfaces`, optional — refreshes one section.
+
+## Steps
+
+1. **Extract or elicit.** Extract when a source tree exists; elicit when the repo is empty.
+2. **Invoke `app-architect`** with the material. It reads the tree, drafts each section and
+   challenges it. The questions and the confirmations happen here, in this session — a subagent
+   cannot interview.
+3. **Fill the exposure column in extract mode.** Entry points are enumerable: `app/**/page.tsx` and
+   `app/**/route.ts` for the App Router, files carrying `'use server'` for server actions, plus the
+   job and webhook registrations. Enumerate them, attach each to the module it serves, and ask the
+   engineer for a status per entry point — `live`, `routable` or `off`, as the kernel defines them.
+   A module reached only through another module's entry point names that one instead; a module no
+   live entry point reaches is `dormant`, which is derived and never a fourth status.
+4. **One line the map carries, not this Skill's to restate:** it grades the **product** severity of
+   a finding, never its security severity. Every routable entry point is covered by the kernel's
+   security checklist whatever the map says.
+5. **Each section ends with its drift challenge**, and the answer stays in the doc as evidence the
+   probe ran. A challenge that surfaces a real contradiction stops the section: the engineer
+   revises it, files an ADR, or writes a tech-debt file.
+6. **A section-targeted refresh re-reads the other four challenges** before the PR — a module
+   renamed in Section 1 and left standing in Section 4 is the failure this catches.
+
+## Output
+
+`hstack/context/app-architecture.md`, updated in the PR that changes it. Nothing else: no module
+spec stubs, no config file, no status.
 
 ## Stop conditions
 
-- Product-brief or data-architecture at non-terminal status.
-- A module in Section 1 has no trace to brief or data-architecture entities.
-- A Section 3 flow step has no declared mechanism or no measurable-property rationale.
-- A drift challenge surfaces an unresolved contradiction.
-- Extract mode invoked but no source tree reachable.
-
-## Failure modes
+Beyond the kernel's:
 
-- **Subagent unreachable.** Persist session state; retry later.
-- **Terminal-state side-effect commit fails partway** (e.g., one stub fails validator). The atom rolls back the in-progress write and halts with the validator error; the engineer fixes or routes through `/hstack:configure`. The artifact stays at `current` only when ALL three side effects land successfully.
+- Extract mode was asked for and no source tree is reachable.
+- An entry point's status is a guess. Ask; a wrong `off` is how a live surface stops being reviewed.
+- A step of a flow has no declared mechanism, or a rationale that names no property anyone could
+  disagree with.
+- A drift challenge surfaces a contradiction with `data-architecture.md` — typically a state class
+  with nowhere to live. Surface it; the engineer decides whether the data doc moves.