hstack 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to hstack are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows [SemVer](https://semver.org/).
 
+## [0.19.0] - 2026-09-19
+
+Changing an existing test stops needing permission and starts needing a label (ADR-0017). The authorization phrase is abolished; disclosure replaces it. This is the last per-change confirmation gate that survived the light pivot, and it is removed for the reason ADR-0015 removed the others — its cost was paid on every change and its protection was never once observed working.
+
+### Changed
+
+- **§ Test immutability is gone as a top-level law** and becomes four paragraphs inside § Tests. Three carve-outs and five prohibitions become one prohibition: changing a test so a red suite goes green when the code under test is what is wrong. Changing a test because the intended behaviour moved is stated, in the kernel, to be normal work — no phrase, no halt, no permission to request.
+- **Disclosure replaces authorization.** A commit that modifies or deletes a test file that existed at the merge-base tags each file with exactly one of `behavior-change`, `refactor`, `obsolete`. There is no fourth tag: if the honest word would be *it was failing*, that is the forbidden move and not a disclosure. The PR description repeats the list in plain language under **Tests changed** — the commit body is for the audit, that section is for the human, who reads the description and not the diff.
+- **The four canonical authorization phrases are removed from the corpus.** `Ok to change test <name>` and its siblings were kept verbatim by ADR-0013 and again by ADR-0014, both times on the argument that the wording *is* the mechanism. The argument was sound and the mechanism was never exercised: `REC-0003` measured 265 candidate violations over 90 days, the watch-list repeated verbatim for seven weeks, and no human ever reviewed a row.
+- **The escalation clause is a disclosure, not a halt.** An agent that cannot tell whether the test or the code is wrong makes the most plausible change and names the doubt in the PR description as an open question. Halting was the previous answer and it put the owner in the loop at a moment he is generally not in it.
+- **Still hard, for one stated reason — they hide from the diff.** Bulk snapshot updates (`vitest -u`, `--updateSnapshot`, any equivalent, including in hooks) and silent neutralization (`.skip`, `test.todo`, a deleted case, a `.toBe()` broadened to `.toContain()`, a timeout raised to mask a bug). A hidden edit cannot be disclosed, which is the whole argument for keeping these two where everything else was relaxed.
+- **The enforcement points follow the rule.** The adversarial reviewer and `/hstack-adversarial-review` keep a mandatory audit and check for the disclosure tag instead of the authorization echo; `/hstack-wrap` writes the **Tests changed** section rather than blocking the PR; the test strategist may now change an existing test instead of being told existing tests are read-only always; `/hstack-test-audit` keeps its own read-only posture, re-justified on the grounds that an audit which rewrites what it audits is worthless.
+- **The two places the disclosure is physically produced now say so.** The PR-description template (`hstack-wrap/references/pr-description.md`) gains a **Tests changed** heading before **Review findings**, because a step that requires a section the template never offers is a step that will be skipped. And `/hstack-commit` step 4 names the tag in its body guidance — it is the one moment where a staged test file and a commit body exist at the same time.
+- **QO-3's labels change and its field name does not.** `qo_3_test_immutability_audit` is produced by the telemetry sidecar outside this repo, so renaming it here would break the contract. Until that sidecar counts undisclosed edits instead of unphrased ones, the metric reads empty rather than wrong — and there is no audit signal in the interval. Named in ADR-0017 as a consequence, not a detail.
+
+### Added
+
+- **`adr/ADR-0017-disclosure-replaces-authorization-on-tests.md`** — supersedes ADR-0013 and ADR-0014 on the single arbitration where each declined to touch this rule; the rest of both stands. It records the two consequences that look bad: the net is now weaker in exactly the case it was built for, because a tag can be typed by the model where the old phrase could not; and the decision is made on the cost side with the benefit side still unmeasured, since hstack has never detected one unauthorized test edit — equally consistent with *it never happened* and with *we cannot see it*.
+
+## [0.18.0] - 2026-09-18
+
+Code quality gets a mechanical half and a judgment half, with a hard line between them (ADR-0016). The first consumer's audit found the prose rules ignored at scale and the one lint rule at `error` respected everywhere; this release draws the conclusion.
+
+### Added
+
+- **`templates/eslint-clean-code.mjs`** — a flat-config the consumer imports from `hstack/templates/`, so `hstack update` can move it. Every rule at `error`: function and file size, complexity, nesting depth, parameter count, `no-explicit-any`, `no-non-null-assertion`, `no-floating-promises`, `only-throw-error`, `no-empty` catch, console outside the named logger, `process.env` outside the named config module, `@supabase/supabase-js` outside the named client module, `import/no-cycle`. Thresholds and module paths are options. The ratchet is ESLint's own suppressions file: freeze the existing violations once with `--suppress-all`; from then on only new ones fail.
+- **`hstack/supabase-unread-error`**, a custom rule inside that file. Supabase returns `{ data, error }` and never throws; the rule fails an awaited query whose result is discarded, destructured without `error`, or read through `.data` alone. `.throwOnError()` satisfies it. The audit counted 64 unchecked server-side writes in one repo, one of them answered with `{ ok: true }`.
+- **`templates/code-standards.md`** — the living doc for the rules that need judgment: search before writing, one function one responsibility, a component does not talk to the network, a file's name says what it holds, names describe behaviour, a returned error is a handled error, replace rather than add beside, delete what nothing imports, constants in one place. Each rule carries a `Seen here` line the consumer fills from its own code. Installed at `hstack/context/code-standards.md`, read on the trigger *application code → code-standards*.
+- **`/hstack-wrap` step 2** reads the diff against `code-standards.md`, rule by rule, and fixes what it finds before `/review` runs. Step 9 now says the fast lane — typecheck, lint, critical tests — runs locally and is green before the commit; CI is the paid backstop, not the first run, and a lint finding is fixed, never suppressed.
+
+### Changed
+
+- **The kernel** names `code-standards.md` among the living docs with its read trigger, states that lint is at `error` with a ratchet and that a `warn` is not a rule, and that the fast lane runs locally before the push. Five sentences, ~80 words.
+- **The adversarial reviewer's code-quality lens is `code-standards.md`.** A finding names the rule it breaks. The rubric's filler clause — which until now listed *"anything a formatter or a linter would have said"* — is rewritten: what the linter already fails on is filler only when the linter is wired, and an unread error on a write path escalates to `data-integrity`.
+
 ## [0.17.0] - 2026-08-22
 
 The pivot is subtractive (ADR-0015). Four months of hstack v1 produced a workflow whose per-change ceremony made every change roughly ten times slower, and no MVP. The diagnosis is not that the rules were wrong — it is that pre-PMF, the dominant risk is never shipping, not shipping bugs, and a rule that costs something on every single change has to earn it against that. So the question asked of every piece was the same: **does it change what an agent does on an ordinary change, without charging ceremony per change?** What survived was kept *in place*, with its v0.16 wording where the rule survived. What did not was removed, not replaced — this release designs almost nothing new.

package/README.md

@@ -95,8 +95,9 @@ macOS and Linux only. Windows is hard-failed at `hstack init` — the dir-level
 Open a fresh Claude Code session in the consuming repo. There is no init interview in the light version: the kernel is loaded by the import line, and the living docs get written when there is something true to write in them.
 
 1. **Write the two architecture docs** when the shape of the product is settled enough to be worth recording — `/hstack-data-architecture` (tenancy, entities, RLS posture, RAG layout) and `/hstack-app-architecture` (module map with its exposure column, LLM call sites, deterministic-vs-LLM split, state ownership, surfaces). Both run in extract mode against a live schema or the source tree, and ask when extraction is not enough.
-2. **Fill the rest by hand or in the PR that needs them**, from `hstack/templates/`: `tech-stack.md`, `infrastructure.md` — whose § Deploy Pipeline is what `/hstack-promote` reads — `roadmap.md`, `invariants.md`, `review-miss.md`.
-3. **Then just work.** The per-change loop below is the whole of it.
+2. **Fill the rest by hand or in the PR that needs them**, from `hstack/templates/`: `tech-stack.md`, `infrastructure.md` — whose § Deploy Pipeline is what `/hstack-promote` reads — `roadmap.md`, `invariants.md`, `review-miss.md`, and `code-standards.md` with its `Seen here` lines.
+3. **Wire the linter.** Import `hstack/templates/eslint-clean-code.mjs` from the repo's `eslint.config.mjs` (the file's header shows the call), run `npx eslint --suppress-all` once to freeze the existing violations, and commit `eslint-suppressions.json`. From then on only new violations fail `lint`, and the frozen count only goes down.
+4. **Then just work.** The per-change loop below is the whole of it.
 
 ## The change loop
 
@@ -115,7 +116,7 @@ The nine Skills:
 
 | Skill | What it is for |
 | --- | --- |
-| `/hstack-wrap` | The end of a change: runs `/review` and `/security-review`, audits test immutability, updates the living docs the diff invalidated, writes the PR description. |
+| `/hstack-wrap` | The end of a change: runs `/review` and `/security-review`, audits test disclosure, updates the living docs the diff invalidated, writes the PR description. |
 | `/hstack-promote` | The release: pending production migrations, a smoke test on the unpromoted build, then promotion. Commands live in `infrastructure.md` § Deploy Pipeline. |
 | `/hstack-commit` | The one Commitizen format humans and agents both write. |
 | `/hstack-adversarial-review` | The deep pass on a sensitive surface, from a session that never saw the change being written. Findings land as a PR comment. |
@@ -143,10 +144,11 @@ hstack/
     roadmap.md             # Now / Next / Later — advisory, never a gate
     invariants.md          # the business rules a test names
     review-miss.md         # what a review missed, so the next one re-checks it
+    code-standards.md      # the rules that need judgment; the linter owns the rest
     ...                    # frozen and dated: threat-model, product-brief, vision, personas, incident-runbook
   adr/                     # one-way doors only
   tech-debt/               # one file per item; deleted in the PR that fixes it
-  templates/               # the eight canonical templates
+  templates/               # the nine canonical templates + eslint-clean-code.mjs
 .claude/
   skills/hstack-*/SKILL.md # nine Skills
   agents/                  # four subagents
@@ -166,6 +168,7 @@ Authoritative, in the repo:
 - [`template/KERNEL.md`](./template/KERNEL.md) — the kernel. Authority over every Skill, subagent, and template.
 - [`template/templates/`](./template/templates/) — the canonical structure of every artifact type.
 - [`adr/ADR-0015-the-light-pivot.md`](./adr/ADR-0015-the-light-pivot.md) — why the pivot is subtractive, and what it costs.
+- [`adr/ADR-0016-the-linter-enforces-the-doc-judges.md`](./adr/ADR-0016-the-linter-enforces-the-doc-judges.md) — code quality split into a lint config at `error` and a judgment doc, and why prose alone did not hold.
 - [`CHANGELOG.md`](./CHANGELOG.md) — the release history, including the full v0.16.0 lineage.
 
 Historical companions, describing the frozen full version rather than `main`:
@@ -175,6 +178,6 @@ Historical companions, describing the frozen full version rather than `main`:
 
 ## Status
 
-hstack v0.17.0 — the kernel at ~1,700 words, nine Skills, four subagents, eight templates. The `v0.16.0` tag holds the complete version: ~34 Skills, ~16 subagents, the validator, the merge gates, the coord and telemetry trees.
+hstack v0.18.0 — the kernel at ~1,800 words, nine Skills, four subagents, nine templates and a lint config. The `v0.16.0` tag holds the complete version: ~34 Skills, ~16 subagents, the validator, the merge gates, the coord and telemetry trees.
 
-Next milestone: the first real use of the light version, upgrading moso-app from 0.7.1 to 0.17.
+Next milestone: wiring the linter and `code-standards.md` into moso-app after its dead-code cleanup, and watching whether the ratchet count goes down.

package/VERSION

@@ -1 +1 @@
-0.17.0
+0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hstack",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "A spec-driven engineering workflow that ships as Claude Code Skills and subagents.",
   "keywords": [
     "claude-code",

package/template/.claude/agents/adversarial-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: adversarial-reviewer
 model: opus
-description: "Use to critique a PR cold, from a session that never saw it being written — the six lenses, the mandatory test-immutability audit, an empty result that has to be defended. Surfaces findings; never resolves them."
+description: "Use to critique a PR cold, from a session that never saw it being written — the six lenses, the mandatory test-disclosure audit, an empty result that has to be defended. Surfaces findings; never resolves them."
 tools:
   - Read
   - Grep
@@ -30,8 +30,9 @@ implementation conversation.
 
 ## Reads
 
-What the Skill hands over, plus — on demand, when a category is unfamiliar or a finding feels
-thin — `references/finding-categories.md` alongside the Skill.
+What the Skill hands over, and `hstack/context/code-standards.md` when it exists — the
+code-quality lens is that file, rule by rule. On demand, when a category is unfamiliar or a
+finding feels thin, `references/finding-categories.md` alongside the Skill.
 
 ## Writes
 
@@ -40,13 +41,15 @@ Nothing. Findings are returned to the Skill, which posts them on the PR.
 ## Behavior rules
 
 - **Sweep six lenses**: security, scope-drift, invariant-breach, intent-compliance, data-integrity,
-  code-quality. They are lenses to look through, not buckets to fill — a change carrying all its
+  code-quality — the last one against `code-standards.md`, a finding naming the rule it breaks.
+  They are lenses to look through, not buckets to fill — a change carrying all its
   risk in one dimension produces findings in one category, and that is the honest answer.
-- **The test-immutability audit is mandatory** (protocol: `KERNEL.md` § Test immutability). Diff
+- **The test-disclosure audit is mandatory** (protocol: `KERNEL.md` § Tests). Diff
   every test file that existed at the base. For each modified, content-drifted or deleted test,
-  look for its canonical authorization echo in the commit messages or the PR description. Missing
-  echo: a finding under intent-compliance at `high` minimum, `critical` for a bulk snapshot update.
-  This one is not subject to your judgment about whether it is worth filing.
+  look for its disclosure tag — `behavior-change`, `refactor` or `obsolete` — in a commit body, and
+  its plain-language line under **Tests changed** in the PR description. Missing disclosure: a
+  finding under intent-compliance at `high` minimum, `critical` for a bulk snapshot update or a
+  silent neutralization. This one is not subject to your judgment about whether it is worth filing.
 - **Intent is what the PR says it does.** The description names the perimeter, the shortcuts and
   the docs it updated; the diff either matches or it does not.
 - **Severity is about the consequence, not the likelihood.** Cross-tenant leakage and irreversible

package/template/.claude/agents/test-strategist.md

@@ -1,7 +1,7 @@
 ---
 name: test-strategist
 model: opus
-description: "Use during a test audit of one module: map its business rules against the existing tests and return the gaps, then write the tests the engineer chose to add. Existing tests stay read-only."
+description: "Use during a test audit of one module: map its business rules against the existing tests and return the gaps, then write the tests the engineer chose to add. Existing tests stay read-only during the audit itself."
 ---
 
 ## Role
@@ -18,8 +18,7 @@ the right argument.
 ## When to invoke
 
 When `/hstack-test-audit <module>` needs the module's rules mapped against its tests, or needs the
-chosen gaps closed. Not to modify existing tests — that route is the kernel's authorization
-protocol, in the engineer's session, never here.
+chosen gaps closed.
 
 ## Reads
 
@@ -32,11 +31,12 @@ New test files, and `hstack/context/invariants.md`. Nothing else.
 
 ## Behavior rules
 
-- **Existing tests are read-only, always** (protocol: `KERNEL.md` § Test immutability). When
-  closing a gap would mean changing an assertion, deleting a test or updating a snapshot, halt and
-  hand the engineer the routes: authorize the change under the canonical phrase, or write a new
-  test that supersedes the old one, or leave the gap named in the PR description. Never author an
-  authorization phrase on the engineer's behalf.
+- **Existing tests stay read-only here** — not because they are frozen. Changing one is ordinary
+  work when the intended behaviour moved, disclosed with its tag (`KERNEL.md` § Tests). It is that
+  an audit which rewrites the tests it is auditing has audited nothing. Name the change the gap
+  needs and leave it to the engineer's normal flow; a new test superseding the old one is often
+  better anyway, since it keeps the old expectation legible. What is never done, here or in the
+  engineer's session, is bending a test so a red suite goes green when the code is what is wrong.
 - **Pyramid bias.** Unit for pure functions and reducers; integration for behaviour that crosses
   modules or the database; end-to-end for user-visible journeys. Refuse a strategy that rests
   primarily on end-to-end tests — slow and flaky is how a suite stops being run.
@@ -52,7 +52,6 @@ New test files, and `hstack/context/invariants.md`. Nothing else.
 
 ## Stop conditions
 
-- Closing a gap requires touching an existing test.
 - The module has no identifiable business rule — report that rather than propose tests.
 - A rule surfaced contradicts one already in `invariants.md`. Surface both; the engineer decides.
 - A performance budget is wanted but the repo has no way to assert one. Say so; do not write a

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

@@ -31,11 +31,11 @@ honor-system, as the kernel says; a sentence is the whole protocol.
    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
+3. **The test-disclosure 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`.
+   or deletion without its disclosure — a `behavior-change` / `refactor` / `obsolete` tag in a
+   commit body, repeated under **Tests changed** in the PR description — is a finding at `high`
+   minimum. A bulk snapshot update or a silent neutralization 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.

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

@@ -74,13 +74,14 @@ feature, the shortcuts taken, the living docs updated.
 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.
+test-file modification without its disclosure tag** (`KERNEL.md` § Tests); 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
+**Severity.** Undisclosed test changes: `high` minimum, `critical` for a bulk snapshot update or a
+silent neutralization. A
 stale living doc: `high`, because the next session will read it and believe it. Everything else:
 judgment.
 
@@ -107,18 +108,27 @@ sequence to trigger. Irreversible data loss is `critical`. Recoverable inconsist
 
 ## 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`.
+**What it means.** The change works and will cost more than it should to live with. The rubric is
+`hstack/context/code-standards.md`: a finding here names the rule it breaks, and a rule the file
+does not hold is not a finding. The easiest category to pad, which is why the rule number is
+required.
+
+**Real findings look like.** A second implementation of something the repo already had — a
+client, a parser, a retry — written beside the first instead of found (rule 2). A function that
+orchestrates and also does the steps, so the next phase starts at a comment (rule 3). A component
+that fetches or decodes a protocol (rule 4). A file whose name stopped describing its contents in
+this diff (rule 5). A `get*` that writes (rule 6). A result carrying `error` that nothing reads,
+or a `catch` that continues with no justification (rule 7). A new path wired beside the old one
+with the old one still reachable (rule 8). Code this diff orphaned and left in place (rule 9).
+
+**Filler looks like.** Naming preferences that do not make a name lie. Suggested comments.
+Requests to extract a function used once. Anything the repo's linter already fails on — size,
+`any`, console, `process.env` — when the linter is wired; when it is not, one finding says so
+instead of listing what it would have caught.
+
+**Severity.** `low` or `medium`. Rule 7 escalates on a write path: an unread error after an
+`update` or `delete` is `data-integrity`, not `code-quality`. Any other `high` here is usually
+mis-categorized — look again at `invariant-breach` or `data-integrity`.
 
 ---
 

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

@@ -27,7 +27,7 @@ Optional `--push`: push after committing — still subject to per-invocation con
    - `<type>(<scope>): <summary>`, where `<type>` is one of `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `style`, `perf`, `ci`.
    - `<scope>` names the area actually touched — never an invented or aspirational one. When the change spans unrelated areas, no single honest scope exists: propose splitting it into several commits.
    - `<summary>` ≤ 72 characters, imperative present ("add", not "added"), no trailing period.
-   - Body, when it earns its place: the why, not the what.
+   - Body, when it earns its place: the why, not the what. A staged test file that existed at the merge-base is declared there, one line per file, tagged `behavior-change`, `refactor` or `obsolete` (kernel § Tests).
    - **Never "Generated with Claude Code" or any similar attribution.**
    - Footer: conventional-commits footers only (`BREAKING CHANGE:`, `Refs: <issue>`).
 

package/template/.claude/skills/hstack-test-audit/SKILL.md

@@ -26,8 +26,9 @@ question at plan time, and this Skill is never a phase of a change.
    `data-architecture.md` when the module touches the database. Write each rule as *decides X;
    wrong in silence if Y*. A module whose code decides nothing has no gap to close — say so and
    stop rather than write tests for the sake of coverage.
-2. **Map the existing tests onto the rules.** Existing test files are read-only here
-   (kernel § Test immutability); this step reads them, it never edits them.
+2. **Map the existing tests onto the rules.** Existing test files are read-only here — an audit
+   that rewrites the tests it is auditing has audited nothing; this step reads them, never edits
+   them.
 3. **Name the gaps** — rules with no test, and tests asserting something no rule needs.
 4. **Interview the edges.** A handful of questions, not a script: *what does the user notice if
    this breaks in silence?* — plus concurrency, retries, and the cross-tenant case when the module
@@ -38,9 +39,10 @@ question at plan time, and this Skill is never a phase of a change.
 6. **The engineer picks the gaps to close now.** A module with twenty uncovered rules would make
    an unreviewable PR. Close the chosen ones; name the rest in the PR description so the next
    audit starts there.
-7. **Write the tests.** New test files need no authorization — "new" means the path did not exist
-   at session start. If closing a gap requires editing or deleting an existing test, halt and ask;
-   nothing in this Skill authorizes that.
+7. **Write the tests.** New test files only — "new" means the path did not exist at session start.
+   When closing a gap means editing or deleting an existing test, name that change in the output
+   rather than make it here; the engineer makes it in the normal flow, where it is ordinary work
+   carrying its disclosure line (kernel § Tests).
 8. **Record the invariants.** Every rule the audit surfaced goes into `hstack/context/invariants.md`
    in this PR — **including the gaps left open**. The memory is the cheap half; write it whether or
    not the test was written.
@@ -51,13 +53,12 @@ and the gap list. Steps 4 and 6 are questions for the engineer and happen here,
 ## Output
 
 New test files, an `invariants.md` diff, and a summary for the PR description naming the gaps left
-open. Nothing else.
+open and the existing tests that need changing. Nothing else.
 
 ## Stop conditions
 
 Beyond the kernel's:
 
-- Closing a gap would require touching an existing test. Halt (§ Test immutability).
 - The module cannot be located, or spans so much of the repo that "one module" is not what is
   being audited. Ask which one.
 - An invariant the audit surfaces contradicts one already in `invariants.md`. Surface both; the

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

@@ -1,6 +1,6 @@
 ---
 name: hstack-wrap
-description: Use at the end of a change, before the PR — runs /review and /security-review on the branch diff, audits test immutability, updates the living docs the diff invalidated, and writes the PR description.
+description: Use at the end of a change, before the PR — reads the diff against code-standards, runs /review and /security-review, audits test disclosure, updates the living docs the diff invalidated, writes the PR description.
 ---
 
 ## Purpose
@@ -21,19 +21,21 @@ None. The diff under review is everything that will land in the PR — committed
 
 1. **Read `hstack/context/review-miss.md`** when it exists. A category a review has already missed once gets re-checked explicitly in the pass below; that is the whole reason the file exists.
 
-2. **Run `/review`, then `/security-review`** on that diff. Fix what is fixable inside the announced perimeter. Everything else is declared in the PR description — the finding, and why it was not fixed. A finding is never dropped silently, and an empty result is reported as what it is: the reviewer found nothing.
+2. **Read the diff against `hstack/context/code-standards.md`**, rule by rule, when the file exists. This is the pass the linter cannot make: a second implementation of something that already existed, a component talking to the network, an orchestrating function that also does the steps, a legacy path left wired, a returned error nobody reads. Fix what is found — the fix is usually the extraction or the deletion the rule names — and when a rule's `Seen here` line is empty and this diff is the first example, fill it in this PR. What survives on purpose is a tech-debt file, not silence.
 
-3. **Audit test immutability.** Diff the test files that already existed at the merge-base. An edit or a deletion without the canonical authorization echoed in this conversation is a blocking finding — halt, and do not open the PR (kernel § Test immutability).
+3. **Run `/review`, then `/security-review`** on that diff. Fix what is fixable inside the announced perimeter. Everything else is declared in the PR description — the finding, and why it was not fixed. A finding is never dropped silently, and an empty result is reported as what it is: the reviewer found nothing.
 
-4. **Ask each living doc whether this diff invalidated it**, and update it in this PR when it did (kernel § Context docs). When an entry point changed status — live, routable, off — the exposure column of the Module Map in `app-architecture.md` moves with it.
+4. **Audit test disclosure.** Diff the test files that already existed at the merge-base. Each one modified or deleted carries its tag — `behavior-change`, `refactor` or `obsolete` — in a commit body, and its plain-language line under a **Tests changed** heading in the PR description; writing that section is part of this step (kernel § Tests). An undisclosed edit is fixed here by disclosing it, not by halting. The one exception: if the honest tag would be *it was failing*, halt and fix the code instead.
 
-5. **Name the conscious shortcuts.** A shortcut that survives the merge becomes a file under `hstack/tech-debt/`, from the template, written in this PR and named in its description.
+5. **Ask each living doc whether this diff invalidated it**, and update it in this PR when it did (kernel § Context docs). When an entry point changed status — live, routable, off — the exposure column of the Module Map in `app-architecture.md` moves with it.
 
-6. **Sensitive surface?** If the diff touches one (kernel § Review), the PR says so in its first line and asks for the deep pass in a fresh session — `/hstack-adversarial-review`.
+6. **Name the conscious shortcuts.** A shortcut that survives the merge becomes a file under `hstack/tech-debt/`, from the template, written in this PR and named in its description.
 
-7. **Write the PR description** from `references/pr-description.md`: intention, perimeter, decisions, shortcuts and tech-debt, the review findings split into what was fixed and what was declared, and the Notion feature it serves when there is one. When the consumer has a `.github/pull_request_template.md`, that rendered file is the one you fill — the reference file is the seed it was copied from, not a second authority.
+7. **Sensitive surface?** If the diff touches one (kernel § Review), the PR says so in its first line and asks for the deep pass in a fresh session — `/hstack-adversarial-review`.
 
-8. **Commit, then push and open the PR.** Commit in the `hstack-commit` format. Run the repo's fast lane locally first — a red PR costs a full round trip; if the repo names no fast-lane command, say so in the PR rather than inventing one. Push and `gh pr create` only after explicit confirmation in the conversation.
+8. **Write the PR description** from `references/pr-description.md`: intention, perimeter, decisions, shortcuts and tech-debt, the review findings split into what was fixed and what was declared, and the Notion feature it serves when there is one. When the consumer has a `.github/pull_request_template.md`, that rendered file is the one you fill — the reference file is the seed it was copied from, not a second authority.
+
+9. **Run the fast lane locally, then commit, push and open the PR.** Typecheck, lint and the critical tests run here, on this machine, and are green before the commit — a red PR costs a paid CI round trip for something a local run would have caught in a minute. Lint is at `error`: fix the finding, never add a suppression or a disable comment to get past it (kernel § Stop conditions). If the repo names no fast-lane command, say so in the PR rather than inventing one. Commit in the `hstack-commit` format. Push and `gh pr create` only after explicit confirmation in the conversation.
 
 ## Output
 
@@ -43,6 +45,6 @@ One open PR against the default branch, carrying the code, the living-doc update
 
 Beyond the kernel's:
 
-- A pre-existing test was modified or deleted without authorization.
+- A pre-existing test was changed to turn a red suite green when the code is what is wrong.
 - A hook or a check was bypassed to get here.
 - A living doc is invalidated and you cannot update it. Say "stale" in the PR description; never invent the content.

package/template/.claude/skills/hstack-wrap/references/pr-description.md

@@ -33,6 +33,13 @@
 <!-- Conscious shortcuts that survive the merge, each with its hstack/tech-debt/TD-NNNN-<slug>.md
      file. "None" is a real answer when it is true. -->
 
+## Tests changed
+
+<!-- Every test that existed at the merge-base and was modified or deleted here, one line each,
+     in plain language, tagged behavior-change / refactor / obsolete as in the commit body. A PR
+     that touches a test and has no such list is incomplete. Where it was unclear whether the
+     test or the code was wrong, say so here as an open question. -->
+
 ## Review findings
 
 <!-- /review and /security-review, in full. These are LLM judgments, not evidence: an empty list

package/template/KERNEL.md

@@ -16,11 +16,11 @@ The human's job is intent, testing the app, and reading the PR description with
 
 ## Context docs
 
-Living docs, at `hstack/context/`, are the agent's memory between sessions: `data-architecture.md` (tenancy, entities, RLS, RAG) · `app-architecture.md` (module map, state ownership, surface boundaries) · `tech-stack.md` (pinned versions are pinned on purpose — never bump one unrequested) · `infrastructure.md` (where things run, why the couplings, the gotchas) · `roadmap.md` (Now / Next / Later — **advisory only, never a gate**) · `invariants.md` · `review-miss.md`.
+Living docs, at `hstack/context/`, are the agent's memory between sessions: `data-architecture.md` (tenancy, entities, RLS, RAG) · `app-architecture.md` (module map, state ownership, surface boundaries) · `tech-stack.md` (pinned versions are pinned on purpose — never bump one unrequested) · `infrastructure.md` (where things run, why the couplings, the gotchas) · `roadmap.md` (Now / Next / Later — **advisory only, never a gate**) · `code-standards.md` (the rules that need judgment; the linter owns the rest) · `invariants.md` · `review-miss.md`.
 
 The **exposure map** is a column of the Module Map in `app-architecture.md`. Its atom is an entry point — page route, API route, server action, job, webhook — at `live`, `routable` (the URL responds, nothing links to it, it is fully exposed) or `off`. Updated in the PR that changes exposure, verified at `/hstack-promote`.
 
-Read triggers: db / RLS / migration → data-architecture; env / deploy / dependencies → infrastructure; user reachability → app-architecture; always → tech-stack.
+Read triggers: db / RLS / migration → data-architecture; env / deploy / dependencies → infrastructure; user reachability → app-architecture; application code → code-standards; always → tech-stack.
 
 **Non-negotiable: the agent updates a living doc in the same PR that invalidates it.** Committed state is the only authoritative view of another session — Luke's, a parallel worktree — so that PR is the coordination channel, and there is no other. Missing or stale is said in the PR, never invented.
 
@@ -56,7 +56,7 @@ Branch (never the default branch, one per change) → announce the perimeter →
 
 One PR, one intention — a change spanning unrelated modules splits into several. One change, one session — once the PR is open the next starts fresh, and what it needs lives in the PR description or a living doc, never in the conversation.
 
-Two CI lanes: the fast one — typecheck, lint, critical tests — blocks the merge, the slow one is advisory. A hotfix still goes through PR + CI; it skips preview and the train, never the checks.
+Two CI lanes: the fast one — typecheck, lint, critical tests — blocks the merge, the slow one is advisory. The fast lane runs locally and is green before the push; CI is the backstop, not the first run. Lint is at `error` with a suppressions ratchet — the frozen count only goes down, and a `warn` is not a rule. A hotfix still goes through PR + CI; it skips preview and the train, never the checks.
 
 ---
 
@@ -64,27 +64,27 @@ Two CI lanes: the fast one — typecheck, lint, critical tests — blocks the me
 
 Tests are mandatory on critical paths and on every business invariant a change touches. At plan time, one question: *does this code decide something that would be wrong silently?* If it does, a test names the invariant. `/hstack-test-audit` is on demand, never a per-change phase.
 
----
+**Changing an existing test is normal work.** A product before product-market fit changes its intended behaviour several times a week, and the tests move with it. No authorization phrase, no halt, no permission to request.
 
-## Test immutability
+**The one forbidden move** is changing a test so that a red suite goes green when the code under test is what is wrong. Before editing an existing test, one question: *is the test wrong, or is the code wrong?* Fix whichever one is wrong — never the other one.
 
-Once a test file exists in the working tree (committed or staged), **no agent may edit or delete it without per-test, per-conversation human authorization.** This rule exists because the dominant failure mode of LLM-driven implementation is the model editing an assertion or deleting a test to make the suite go green, rather than fixing the code under test.
+**When it cannot tell**, the agent makes the most plausible change and names the doubt in the PR description as an open question, never silently and never by halting. An unresolved doubt is information the reviewer needs, not a reason to stop working.
 
-**What counts as a test.** Files matching the repo's test patterns (e.g. `*.test.ts`, `*.spec.ts`, `__tests__/**/*`, `e2e/**/*`, `*_test.go`), snapshot files (`__snapshots__/*`), and assertion-bearing fixtures — factories and seed data encoding expected outputs.
+**Disclosure replaces authorization.** Any commit that modifies or deletes a test file that existed at the merge-base says so in its body, one line per file, tagged with exactly one word:
 
-**Authorization protocol.** Halt before editing. Surface (a) the test file and test name, (b) why it must change — what it asserts vs. what is now correct, with evidence, (c) the proposed diff, (d) the alternatives, starting with fixing the code under test. Then wait for the canonical phrase — `Ok to change test <name>` or `Ok to delete test <name>`, `<name>` being the file path or a uniquely-identifying test name. The agent echoes it back verbatim before acting; nothing else is an authorization.
+- `behavior-change` — the intended behaviour moved and the test followed it.
+- `refactor` — same assertions, moved or renamed or rewired (imports, mocks, fixtures).
+- `obsolete` — the subject of the test no longer exists.
 
-**Carve-outs.** New tests need no authorization — "new" means the path did not exist at session start. A content-preserving move is permitted, surfaced in the commit message so the review can verify nothing drifted.
+There is no fourth tag. If the honest word would be *it was failing*, that is the forbidden move, not a disclosure.
 
-**Forbidden no matter what.**
+The PR description repeats the same list in plain language, under a **Tests changed** heading. The commit body is for the audit; that section is for the human, who reads the description and not the diff. A PR that touches a test and has no such section is incomplete.
+
+**What counts as a test.** Files matching the repo's test patterns (e.g. `*.test.ts`, `*.spec.ts`, `__tests__/**/*`, `e2e/**/*`, `*_test.go`), snapshot files (`__snapshots__/*`), and assertion-bearing fixtures — factories and seed data encoding expected outputs.
 
-- Blanket authorizations ("go ahead and fix any failing tests", "update whatever snapshots need it"). Authorizations are per-test, per-conversation. The agent refuses blanket scope.
-- Bulk snapshot updates via `--update-snapshots`, `jest --updateSnapshot`, `vitest -u`, or any equivalent flag, including in pre-commit hooks.
-- Relaxing an assertion without authorization (e.g., tightening a regex to a substring match, broadening a `.toBe()` to `.toContain()`, increasing a timeout to mask a real bug).
-- Deleting a `.skip` annotation, replacing a `test()` call with `test.todo()`, or otherwise neutralizing a test without authorization. Neutralization is a form of deletion.
-- Editing a test as part of "cleaning up" a phase without an explicit authorization for that test, even if the edit is cosmetic.
+**Two things stay hard, because they hide from the diff.** Bulk snapshot updates via `--update-snapshots`, `jest --updateSnapshot`, `vitest -u` or any equivalent flag, including in hooks — a mass edit nobody reads is not a disclosure. And neutralizing a test silently: adding `.skip`, replacing `test()` with `test.todo()`, deleting a case, or loosening an assertion (a `.toBe()` broadened to `.toContain()`, a timeout raised to mask a real bug) are edits like any other and carry their disclosure line.
 
-Authorization is single-use: it covers the test and the change discussed in the current conversation, and never carries across sessions. An unauthorized test edit is a blocking review finding.
+An undisclosed test edit is a review finding. A disclosed one is just work.
 
 ---
 
@@ -108,7 +108,7 @@ CI backstops, wired once: secret scanning, and a grep that fails the build on `s
 
 ## Review
 
-Every PR: `/hstack-wrap` runs `/review` and `/security-review` before the push, and their findings go in the PR description.
+Every PR: `/hstack-wrap` reads the diff against `code-standards.md`, then runs `/review` and `/security-review`, before the push; what it could not fix goes in the PR description.
 
 **Sensitive surfaces** — agent or tool boundaries, auth, RLS, schema and migrations, pgvector, payments and credits — additionally get a deep review in a fresh session. The session that authored the change and the session that reviews it are separate Claude Code sessions: the author's working memory, scratchpad, and conversation are not loaded into the reviewer's session. This is honor-system.
 
@@ -136,7 +136,7 @@ One-way doors only: fixable in one PR, then no ADR. Nygard, one page, no frontma
 
 ## Templates
 
-Templates live at `hstack/templates/`; fill them, do not invent structure. They are `tech-debt.md`, `adr.md`, `story.md`, and the living-doc templates — data-architecture, app-architecture, tech-stack, infrastructure, roadmap. The PR description has its own, `.github/pull_request_template.md`, rendered by GitHub.
+Templates live at `hstack/templates/`; fill them, do not invent structure. They are `tech-debt.md`, `adr.md`, `story.md`, the living-doc templates — data-architecture, app-architecture, tech-stack, infrastructure, roadmap, code-standards — and `eslint-clean-code.mjs`, the lint config the consumer imports rather than copies. The PR description has its own, `.github/pull_request_template.md`, rendered by GitHub.
 
 ---
 

package/template/templates/code-standards.md

@@ -0,0 +1,107 @@
+---
+id: code-standards
+type: code-standards
+updated: <YYYY-MM-DD>
+---
+
+_The rules that need judgment. Size, typing, unread errors, console and `process.env` are the
+linter's job (`hstack/templates/eslint-clean-code.mjs`, at `error`, with a suppressions ratchet);
+nothing here repeats what it already fails. Read this file before writing application code;
+`/hstack-wrap` reads the diff against it before the PR. Each rule carries one example from this
+repo — the observed failure it exists for — so a reader knows the rule is about here, not about a
+book. Fill the `Seen here` lines from the codebase; leave a rule's line empty when it has not
+happened yet, and add the example in the PR where it does._
+
+## 1. Where things live
+
+_The one sanctioned path for each cross-cutting concern. A second one is a finding._
+
+| Concern | Module | What it gives you |
+| --- | --- | --- |
+| Logging | `<lib/observability/logger>` | structured, redacted, tenant-tagged |
+| Configuration | `<lib/env>` | every variable validated once at boot |
+| Database client | `<lib/supabase/{server,client,admin}>` | the RLS posture chosen for you |
+| Errors | `<lib/errors>` | `AppError` with `code` and `cause`; the boundary handler |
+| Retry / sleep / chunk | `<lib/retry>` | abort-aware, already tested |
+| Shared UI primitives | `<components/ui>` | — |
+
+## 2. Before writing, search
+
+Before adding a helper, a client, a wrapper, a parser or a formatter, grep for one that exists.
+If it exists, use it. If it is almost right, fix it in place and move the callers. Never write a
+second one beside the first — the copies drift, and the drift is a bug nobody planned.
+
+Seen here: _<e.g. seven `sleep` definitions; three copies of the same vendor client, one with
+retry and two without>_
+
+## 3. One function, one responsibility, one level of abstraction
+
+A function either orchestrates — calls named steps in order — or is one step. When a reader needs
+a comment to find where the next phase starts, the function is two functions and the comment is
+the name of the second. Extract until each name says what its body does.
+
+Seen here: _<e.g. a stream handler that gates, fetches, builds the prompt, persists, retries and
+reports cost, in one body>_
+
+## 4. A React component does not talk to the network
+
+Fetching, streaming, protocol decoding and retry live in a hook or a service module. The
+component receives data and callbacks, and renders. A component that parses a response body is
+a service wearing a template.
+
+Seen here: _<e.g. a chat component parsing server-sent events by hand inside a mutation>_
+
+## 5. A file's name says what it contains, and it contains one thing
+
+If the folder or the file cannot be named after its single responsibility, it has more than one.
+One vendor client per file. No `helpers.ts` past two hundred lines. No file that is a barrel
+(`index.ts`) and an implementation at the same time.
+
+Seen here: _<e.g. a file named after one OAuth broker holding six vendor APIs>_
+
+## 6. Names describe behaviour, not category
+
+`get*` reads and has no side effect. `is*` / `has*` return a boolean. A name that needs its
+docblock to be understood is the wrong name. One word per concept across the codebase — pick one
+of the synonyms and use it everywhere. No `v2`, `new`, `old`, `legacy` in a name: the name says
+what it is, git says how old.
+
+Seen here: _<e.g. `getX` that creates and connects; card / job / task for one entity>_
+
+## 7. A returned error is a handled error
+
+Errors travel one way: thrown (with `cause`) from where they happen, caught once at the boundary
+— the route, the job, the server action — where a single handler logs them and shapes the
+response. In between, code neither logs-and-rethrows nor catches-and-continues. A `catch` either
+handles, rethrows with `cause`, or carries a one-line justification for swallowing. A client
+that returns `{ data, error }` instead of throwing has `error` read on every call. A write is
+never followed by `ok: true` without its result being checked.
+
+Seen here: _<e.g. an update whose result was never read, answered with `{ ok: true }`>_
+
+## 8. Replace, do not add beside
+
+A new implementation of an existing thing ships in the PR that deletes the old one, with every
+import moved. No parallel folder, no second system left wired "for now", no legacy path still
+reachable from a live route.
+
+Seen here: _<e.g. two component trees for one screen; three agent loops each with its own cost
+tracker>_
+
+## 9. Delete what nothing imports
+
+An unused file, export or dependency is removed in the PR that orphaned it, not recorded as
+debt. Dead code is read by the next agent as live.
+
+Seen here: _<e.g. whole component folders no route reaches>_
+
+## 10. Constants live in one place
+
+Table names, status strings, limits, timeouts and model ids are imported from a constants module,
+never retyped as literals at the call site. A rename is one edit.
+
+Seen here: _<e.g. one table name typed by hand in a hundred places>_
+
+**Drift challenge answered**
+
+_"Which rule above has the repo violated since this file was last updated, and where?"_

package/template/templates/eslint-clean-code.mjs

@@ -0,0 +1,322 @@
+/**
+ * hstack — clean-code ESLint reference config.
+ *
+ * The mechanical half of `hstack/context/code-standards.md`: everything a
+ * linter can measure lives here, at `error`, so `lint` fails instead of
+ * warning. A `warn` is a message an agent learns to scroll past; an `error`
+ * is a message it has to act on. Nothing here is a style preference — each
+ * rule maps to a way agent-written code has actually gone wrong.
+ *
+ * Usage, from the consumer's `eslint.config.mjs`:
+ *
+ *   import { defineConfig } from 'eslint/config'
+ *   import { cleanCode } from './hstack/templates/eslint-clean-code.mjs'
+ *
+ *   export default defineConfig([
+ *     ...yourFrameworkConfig,          // e.g. eslint-config-next, which registers
+ *                                      // the @typescript-eslint and import plugins
+ *     ...cleanCode({
+ *       typescript: true,              // rules that need @typescript-eslint registered
+ *       imports: true,                 // rules that need eslint-plugin-import registered
+ *       supabase: true,                // the unread-`error` rule (see below)
+ *       modules: {
+ *         logger: 'lib/observability/logger',
+ *         config: 'lib/env',
+ *         dbClient: 'lib/supabase',
+ *       },
+ *     }),
+ *   ])
+ *
+ * The ratchet. Turning these on against an existing codebase fails `lint`
+ * hundreds of times at once. Freeze the current violations once —
+ *
+ *   npx eslint --suppress-all
+ *
+ * — which writes `eslint-suppressions.json`. From then on only *new*
+ * violations fail; touching a file that carries old ones is the moment to
+ * pay them down (`npx eslint --prune-suppressions` drops the entries that no
+ * longer apply). Commit the suppressions file. The count only goes down.
+ *
+ * This file is framework-owned: `hstack update` overwrites it. Adjust
+ * thresholds through the `thresholds` option, not by editing here.
+ */
+
+const DEFAULT_FILES = ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}']
+const DEFAULT_TEST_FILES = [
+  '**/*.test.{ts,tsx,js,jsx}',
+  '**/*.spec.{ts,tsx,js,jsx}',
+  '**/__tests__/**',
+  '**/e2e/**',
+]
+const DEFAULT_SCRIPT_FILES = ['scripts/**']
+
+const DEFAULT_THRESHOLDS = {
+  /** Lines per function, blank lines and comments excluded. */
+  functionLines: 60,
+  /** Lines per file, blank lines and comments excluded. */
+  fileLines: 400,
+  /** Independent paths through a function (if / for / && / ?: each add one). */
+  complexity: 15,
+  /** Nested blocks. Four is already a function that wants splitting. */
+  depth: 4,
+  /** Positional parameters. Past three, pass a named object. */
+  params: 3,
+  /** Nested callbacks. */
+  callbacks: 3,
+}
+
+/**
+ * Supabase returns `{ data, error }` and never throws. Code that takes `data`
+ * and ignores `error` reads as correct and fails silently — an RLS denial
+ * becomes an HTTP 200 that lies. This rule flags an awaited query-builder
+ * chain (`.from(…)`, `.rpc(…)`, `.storage.from(…)`) whose result is
+ * discarded, destructured without `error`, or read through `.data` only.
+ * Chaining `.throwOnError()` turns the result into an exception and satisfies
+ * the rule.
+ */
+const supabaseUnreadErrorRule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require the `error` half of a Supabase `{ data, error }` result to be read.',
+    },
+    schema: [],
+    messages: {
+      unreadError:
+        'The Supabase client never throws; it returns `{ data, error }`. Read `error` here ' +
+        '(or chain `.throwOnError()`). An unread error is a silent failure.',
+      discardedResult:
+        'The result of this Supabase call is discarded, so a failed write goes unnoticed. ' +
+        'Read `error` (or chain `.throwOnError()`).',
+    },
+  },
+  create(context) {
+    const QUERY_ROOTS = new Set(['from', 'rpc'])
+
+    /** Walks a call chain and reports whether it starts a Supabase query and whether it throws on error. */
+    function describeChain(node) {
+      let startsQuery = false
+      let throwsOnError = false
+      let current = node
+      while (current) {
+        if (current.type === 'CallExpression') {
+          const callee = current.callee
+          if (callee.type === 'MemberExpression' && callee.property.type === 'Identifier') {
+            if (QUERY_ROOTS.has(callee.property.name)) startsQuery = true
+            if (callee.property.name === 'throwOnError') throwsOnError = true
+          }
+          current = callee
+        } else if (current.type === 'MemberExpression') {
+          current = current.object
+        } else {
+          break
+        }
+      }
+      return { startsQuery, throwsOnError }
+    }
+
+    function patternReadsError(pattern) {
+      return pattern.properties.some(
+        (property) =>
+          property.type === 'RestElement' ||
+          (property.key && property.key.type === 'Identifier' && property.key.name === 'error'),
+      )
+    }
+
+    return {
+      AwaitExpression(node) {
+        const { startsQuery, throwsOnError } = describeChain(node.argument)
+        if (!startsQuery || throwsOnError) return
+
+        const parent = node.parent
+        if (parent.type === 'ExpressionStatement') {
+          context.report({ node, messageId: 'discardedResult' })
+          return
+        }
+        if (parent.type === 'VariableDeclarator' && parent.id.type === 'ObjectPattern') {
+          if (!patternReadsError(parent.id)) {
+            context.report({ node, messageId: 'unreadError' })
+          }
+          return
+        }
+        if (
+          parent.type === 'MemberExpression' &&
+          parent.object === node &&
+          parent.property.type === 'Identifier' &&
+          parent.property.name === 'data'
+        ) {
+          context.report({ node, messageId: 'unreadError' })
+        }
+      },
+    }
+  },
+}
+
+export const hstackPlugin = {
+  meta: { name: 'hstack', version: '1.0.0' },
+  rules: {
+    'supabase-unread-error': supabaseUnreadErrorRule,
+  },
+}
+
+/**
+ * @param {object} [options]
+ * @param {string[]} [options.files]        Files the rules apply to.
+ * @param {string[]} [options.testFiles]    Files where size rules are relaxed.
+ * @param {string[]} [options.scriptFiles]  Operator CLIs, where stdout is the interface.
+ * @param {boolean}  [options.typescript]   Emit rules that need `@typescript-eslint` registered. Default true.
+ * @param {boolean}  [options.imports]      Emit rules that need `eslint-plugin-import` registered. Default false.
+ * @param {boolean}  [options.supabase]     Emit the unread-`error` rule. Default false.
+ * @param {Partial<typeof DEFAULT_THRESHOLDS>} [options.thresholds]
+ * @param {object}   [options.modules]      Where the one sanctioned path for each concern lives; used in messages.
+ * @param {string}   [options.modules.logger]    e.g. 'lib/observability/logger'
+ * @param {string}   [options.modules.config]    e.g. 'lib/env'
+ * @param {string}   [options.modules.dbClient]  e.g. 'lib/supabase'
+ * @returns {object[]} Flat-config objects to spread into `defineConfig([...])`.
+ */
+export function cleanCode(options = {}) {
+  const files = options.files ?? DEFAULT_FILES
+  const testFiles = options.testFiles ?? DEFAULT_TEST_FILES
+  const scriptFiles = options.scriptFiles ?? DEFAULT_SCRIPT_FILES
+  const typescript = options.typescript ?? true
+  const imports = options.imports ?? false
+  const supabase = options.supabase ?? false
+  const t = { ...DEFAULT_THRESHOLDS, ...(options.thresholds ?? {}) }
+  const modules = options.modules ?? {}
+
+  const loggerHint = modules.logger ? ` Use ${modules.logger}.` : ' Use the repo logger.'
+  const configHint = modules.config
+    ? ` Read it through ${modules.config}, which validates every variable once at boot.`
+    : ' Read it through the one config module that validates every variable at boot.'
+  const dbClientHint = modules.dbClient
+    ? ` Get a client from ${modules.dbClient}; a client built elsewhere can bypass RLS.`
+    : ' Get a client from the one sanctioned module; a client built elsewhere can bypass RLS.'
+
+  const sizeAndShape = {
+    'max-lines-per-function': [
+      'error',
+      { max: t.functionLines, skipBlankLines: true, skipComments: true, IIFEs: true },
+    ],
+    'max-lines': ['error', { max: t.fileLines, skipBlankLines: true, skipComments: true }],
+    complexity: ['error', t.complexity],
+    'max-depth': ['error', t.depth],
+    'max-params': ['error', t.params],
+    'max-nested-callbacks': ['error', t.callbacks],
+  }
+
+  const errorsAreHandled = {
+    'no-empty': ['error', { allowEmptyCatch: false }],
+    'prefer-promise-reject-errors': 'error',
+    'no-throw-literal': 'error',
+  }
+
+  // `no-console` carries no custom message; when the consumer names a logger,
+  // the restricted-global form says where to go instead.
+  const consoleRules = modules.logger
+    ? {
+        'no-console': 'off',
+        'no-restricted-globals': [
+          'error',
+          { name: 'console', message: `Do not log through console.${loggerHint}` },
+        ],
+      }
+    : { 'no-console': ['error', { allow: [] }] }
+  const consoleOff = { 'no-console': 'off', 'no-restricted-globals': 'off' }
+
+  const onePathPerConcern = {
+    ...consoleRules,
+    'no-restricted-syntax': [
+      'error',
+      {
+        selector: "MemberExpression[object.name='process'][property.name='env']",
+        message: `Do not read process.env here.${configHint}`,
+      },
+    ],
+    'no-restricted-imports': [
+      'error',
+      {
+        paths: [
+          {
+            name: '@supabase/supabase-js',
+            message: `Do not import @supabase/supabase-js directly.${dbClientHint}`,
+          },
+        ],
+      },
+    ],
+  }
+
+  const deadCode = {
+    // The core rule is replaced by its type-aware twin when TypeScript is on.
+    'no-unused-vars': typescript ? 'off' : 'error',
+    'no-duplicate-imports': 'error',
+    'no-unreachable': 'error',
+    'no-useless-return': 'error',
+  }
+
+  const typescriptRules = typescript
+    ? {
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' },
+        ],
+        '@typescript-eslint/no-explicit-any': 'error',
+        '@typescript-eslint/no-non-null-assertion': 'error',
+        '@typescript-eslint/consistent-type-imports': [
+          'error',
+          { prefer: 'type-imports', fixStyle: 'inline-type-imports' },
+        ],
+        // Type-aware: needs `parserOptions.projectService` (or `project`) set by the consumer.
+        '@typescript-eslint/no-floating-promises': 'error',
+        '@typescript-eslint/only-throw-error': 'error',
+      }
+    : {}
+
+  const importRules = imports ? { 'import/no-cycle': ['error', { maxDepth: Infinity }] } : {}
+
+  const supabaseRules = supabase ? { 'hstack/supabase-unread-error': 'error' } : {}
+
+  const configs = [
+    {
+      name: 'hstack/clean-code',
+      files,
+      ...(supabase ? { plugins: { hstack: hstackPlugin } } : {}),
+      rules: {
+        ...sizeAndShape,
+        ...errorsAreHandled,
+        ...onePathPerConcern,
+        ...deadCode,
+        ...typescriptRules,
+        ...importRules,
+        ...supabaseRules,
+      },
+    },
+    {
+      // A long test is a normal test, and a test file reads the environment to
+      // decide what it can run against.
+      name: 'hstack/clean-code/tests',
+      files: testFiles,
+      rules: {
+        'max-lines-per-function': 'off',
+        'max-lines': 'off',
+        'max-nested-callbacks': 'off',
+        'no-restricted-syntax': 'off',
+        ...(typescript ? { '@typescript-eslint/no-non-null-assertion': 'off' } : {}),
+      },
+    },
+    {
+      // Operator-run CLIs: stdout is the interface, and the process reads its
+      // own environment.
+      name: 'hstack/clean-code/scripts',
+      files: scriptFiles,
+      rules: {
+        ...consoleOff,
+        'no-restricted-syntax': 'off',
+      },
+    },
+  ]
+
+  return configs
+}
+
+export default cleanCode