hstack 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.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
 
@@ -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.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hstack",
-  "version": "0.17.0",
+  "version": "0.18.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

@@ -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,7 +41,8 @@ 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
   every test file that existed at the base. For each modified, content-drifted or deleted test,

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

@@ -107,18 +107,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-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 immutability, 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 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).
 
-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
 

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.
 
 ---
 
@@ -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