hstack 0.7.1 → 0.17.0

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

@@ -1,187 +1,60 @@
 ---
 name: hstack-adversarial-review
-description: |
-  Use this skill only in a fresh Claude Code session — separate from the session that ran the implementer — after verification has landed at `status: passed` and the change is at `ready-for-review`. The Skill orchestrates the `adversarial-reviewer` subagent to produce a quota-driven critique. v1 fresh-session enforcement is honor-system; the Skill emits a clear instruction reminding the engineer that the v2 substrate will verify via session-id comparison. Examples:
-
-  <example>
-  Context: The implementer finished the last phase of a billing change; verification passed; the engineer has opened a fresh session for adversarial review.
-  user: "I've opened a new session. /hstack:adversarial-review 2026-05-billing-overage-warning"
-  assistant: "I'll invoke adversarial-reviewer. Findings floor is 5 because area=billing. I'll load every change artifact and the full diff; no implementer transcripts. Minimum 5 findings or a defended sub-floor justification — 'no issues found' is not a terminal state."
-  <commentary>
-  AR-06 raises the findings floor to 5 for changes in {agent, auth, billing}. The reviewer must spread findings across categories — clustering all findings in one category is a smell unless flagged in Methodology.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A small copy-fix change has been verified and the reviewer can only honestly produce two findings.
-  user: "/hstack:adversarial-review 2026-05-billing-copy-tweak"
-  assistant: "I'll invoke adversarial-reviewer. If I can only honestly produce two findings, I'll set findings-fewer-than-floor: true and write a defended justification in section 4 — enumerate every category considered and explain why each produced no honest finding."
-  <commentary>
-  The sub-floor path is explicit and rare. AR-01 demands `findings` length ≥ `findings-floor` OR `findings-fewer-than-floor: true` plus non-empty `justification-when-fewer`. "The change is small" alone is insufficient.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The adversarial reviewer finds a high-severity tenant-isolation issue the security review missed.
-  user: "/hstack:adversarial-review 2026-06-retrieval-rpc-rewrite"
-  assistant: "I'll invoke adversarial-reviewer with the new pgvector RPC under scrutiny. If a severity:high tenant-isolation finding lands, the resolution must be commit:<hash> or tech-debt:<id> — not justified-in-prose. High-severity security routed to justified-in-prose is a smell and I'll halt."
-  <commentary>
-  Resolution discipline matters: `commit:<hash>` for code fixes, `tech-debt:<id>` for deliberate deferral, `justified-in-prose` only for low-severity findings where in-prose reasoning is genuinely right. High-severity security via justified-in-prose is a halt condition.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — 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 output is structurally biased against "looks good" — the reviewer must produce at least the findings floor across the six categories or defend a smaller count with explicit rationale. In v1, fresh-session separation is honor-system; the Skill's first job is to remind the engineer of that.
-
-## 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`
-- Determine the findings floor: 3 default; 5 when `change-spec.area` is in {agent, auth, billing} per AR-06.
-
-## Orchestration steps
-
-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 produces findings in security, scope-drift, invariant-breach, spec-compliance, data-integrity, and code-quality. Clustering in one category is a smell — when it happens, the subagent flags the clustering in Methodology and explains why the change genuinely lives in one risk dimension. 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`. These findings are filed even when they push the total over the findings-floor.
-
-4. **Findings-floor compliance.** Per AR-01, `findings` length must be ≥ `findings-floor`. If the subagent honestly cannot produce the floor, it sets `findings-fewer-than-floor: true` and writes a defended `justification-when-fewer` enumerating every category considered and why each produced no honest finding. "The change is small" alone is insufficient.
-
-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.
+`/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.
 
-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.
+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.
 
-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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` — 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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` 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. Do NOT invoke `spec-author` and do NOT delegate the write to the `adversarial-reviewer` subagent; per the kernel's Mechanical operations section and ADR-0002, the value to write is fully determined by the adversarial-review postcondition and the change-spec's current status, so the Skill orchestrator writes directly. The `adversarial-reviewer` subagent retains its critique-only lane and writes only `adversarial-review.md`.
-
-## 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": 1,
-  "skill": "hstack-adversarial-review",
-  "change_id": "<change-id>",
-  "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. This is the most directly Goodhart-resistant of the five v1 sidecars — `category_counts` + `severity_counts` + `resolution_mix` jointly surface findings-quota-gaming patterns no single field could detect.
-
-## Idempotency contract
+## When to invoke
 
-- 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 findings floor cannot honestly be met and the sub-floor justification cannot be defended.
-- 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
-
-- **Engineer claims fresh session but conversation shows prior implementer transcripts.** Halt; ask the engineer to truly start a new session.
-- **Reviewer cannot produce honest findings to meet the floor and the sub-floor justification feels thin.** Re-prompt for each category; if still under floor, the engineer must defend the sub-floor explicitly.
-- **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.
-
-## Anti-patterns
+Beyond the kernel's:
 
-- Never return "no issues found" without a defended sub-floor justification.
-- Never run in the same Claude Code session as `hstack-implement`. Honor-system in v1; CI-verified in v2.
-- Never cluster all findings in one category without flagging in Methodology.
-- Never use `justified-in-prose` for a high-severity finding.
-- Never propose code changes directly — the reviewer surfaces findings; the owner or implementer (via `hstack-implement`) resolves them.
-- Never invent a tech-debt id. The artifact must exist or be authored before the review terminates.
-- Never accept a `commit:<hash>` that does not exist on the change's branch.
-- Never advance status to `findings-resolved` while any finding has `status: open`.
-- Never load implementer transcripts. If visible, halt.
+- 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

@@ -0,0 +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 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.
+
+**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 an item of the kernel's security checklist with no evidence from the diff that it was
+missed.
+
+**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 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 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 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 on a path `invariants.md` covers,
+because then it is also `invariant-breach`.
+
+---
+
+## invariant-breach
+
+**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.** 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.
+
+**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.
+
+---
+
+## intent-compliance
+
+**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.** 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 description could have been clearer." Style disagreements with how the
+work was sequenced.
+
+**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.
+
+**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.
+
+**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.
+
+**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 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`.
+
+---
+
+## Resolution
+
+Independent of category, a finding names what would resolve it:
+
+- **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,109 +1,57 @@
 ---
 name: hstack-app-architecture
-description: |
-  Use this skill when the engineer wants to produce or refresh `hstack/context/app-architecture.md` — the five-section internal-architecture design (Module Map, Agent Orchestration, Deterministic-vs-LLM Split, State Ownership, Surface Boundaries). The Skill is Phase 3 of `/hstack:greenfield-init`, the app-architecture step of `/hstack:brownfield-init`, or a standalone atom for refreshing a single section. At terminal state the atom auto-scaffolds `hstack/specs/<module>/spec.md` stubs at `status: draft` for each declared module and updates `hstack/config.yaml`'s `surfaces` enum to match Section 5. Examples:
-
-  <example>
-  Context: Phase 3 of greenfield-init opens after data-architecture is current.
-  user: "/hstack:app-architecture"
-  assistant: "Loading product-brief, data-architecture, vision, mvp-scope. Stack-agnostic interview — I won't ask about frameworks here; that's Phase 4. Section 3 (Deterministic-vs-LLM Split) is the load-bearing AI-native decision: per user-facing flow, what's code and what's prompt, with rationale tied to a measurable property."
-  <commentary>
-  Internal architecture is stack-agnostic by design. Section 3 is where AI-native teams most often get architecture wrong by leaving the LLM/code split implicit. The atom forces per-step declaration.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A brownfield repo's modules have evolved; the engineer wants the artifact refreshed against current code.
-  user: "/hstack:app-architecture --mode extract"
-  assistant: "Extract mode. Scanning src/, app/, lib/ via Glob; reading exports and dependencies. Proposing the Module Map from code-evidence. The drift challenge runs at the end of Section 1: does any module own state a persona never interacts with?"
-  <commentary>
-  Extract mode reads code-evidence to propose modules; the engineer confirms or revises. The orphan-module challenge catches modules that have grown beyond their persona-named purpose.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — 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
-
-- **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.
-
-## Anti-patterns
+Beyond the kernel's:
 
-- Never name frameworks, ORMs, hosting providers, or specific runtimes in the artifact body or frontmatter. Stack-agnostic is load-bearing for portability across Phase 4 stack decisions.
-- Never write authored content into module-spec stubs. Headers + `status: draft` + body note only.
-- Never let Section 3's per-step declaration collapse to "the AI handles it end-to-end." Each step is named with mechanism + measurable-property rationale.
-- Never bypass the end-of-atom coherence check on section-targeted re-entry.
-- Never write surfaces into `hstack/config.yaml` outside the terminal-state atomic commit.
+- 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.