stainless-code
diff --git a/‎.agents/rules/agents-tier-system.md‎
Lines changed: 95 additions & 0 deletions b/‎.agents/rules/agents-tier-system.md‎
Lines changed: 95 additions & 0 deletions
diff --git a/‎.agents/rules/concise-comments.md‎
Lines changed: 54 additions & 0 deletions b/‎.agents/rules/concise-comments.md‎
Lines changed: 54 additions & 0 deletions
diff --git a/‎.agents/rules/docs-governance.md‎
Lines changed: 37 additions & 41 deletions b/‎.agents/rules/docs-governance.md‎
Lines changed: 37 additions & 41 deletions
@@ -0,0 +1,95 @@
+---
+description: Tier system for .agents/ rules and skills — context-targeted attachment via the right Cursor frontmatter mode. Apply when authoring a new rule or skill, or when reviewing an existing one's attachment cost.
+globs:
+  - ".agents/rules/**"
+  - ".agents/skills/**"
+  - ".cursor/rules/**"
+  - ".cursor/skills/**"
+alwaysApply: false
+---
+
+# `.agents/` tier system
+
+Cursor rules support three attachment modes. Each new rule must consciously pick one.
+
+| Mode              | Frontmatter                                           | Cost per turn                               | Use for                                                                       |
+| ----------------- | ----------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------- |
+| **Always-on**     | `alwaysApply: true`                                   | full rule body always loaded                | cross-cutting **practices** — define how we work, not what we build           |
+| **Auto-attached** | `alwaysApply: false` + `globs:`                       | zero unless a matching file is in scope     | technical **patterns** — what we write under `.agents/**`, `src/cli/**`, etc. |
+| **Discoverable**  | `alwaysApply: false` + `description:` only (no globs) | zero unless description matches user intent | intent-driven **workflows** — the user said "do X"                            |
+
+## Tiers in this repo
+
+### Tier 1 — Always-on practices (~10 rules max)
+
+Genuinely cross-cutting. Apply to every turn regardless of file:
+
+- `agents-first-convention` — `.agents/` source-of-truth + `.cursor/` symlinks discipline
+- `codemap` — STOP-before-grep
+- `concise-comments` — sweep your own new comments before reporting
+- `concise-reporting` — extreme concision in agent reports
+- `lessons` — read at session start, append after corrections
+- `no-bypass-hooks` — never `--no-verify` on `git commit`
+- `pr-comment-fact-check` — fires the fact-check skill on PR-comment intent triggers
+- `preserve-comments` — never silently delete TODOs / commented-out code
+- `tracer-bullets` — small end-to-end slices, not horizontal layers
+- `verify-after-each-step` — run the project's checks per milestone, not at commit time
+
+### Tier 2 — Auto-attached technical rules (this rule's tier)
+
+Glob-attached. Each is a thin priming layer (~30–50 lines: top-N principles + `Reference` section pointing at the deep-dive skill).
+
+Skills get a paired Tier-2 rule when they have **always-on principles** that should fire whenever the relevant files are in scope (e.g. when codemap grows a TS-specific style rule, it would attach to `**/*.{ts,tsx}`).
+
+Today's Tier-2 rules:
+
+- `agents-tier-system` (this rule) — auto-attaches when authoring under `.agents/**` or `.cursor/**`.
+- `docs-governance` — primes the docs framework when authoring under `docs/**` or `.agents/**` (paired with [`docs-governance` skill](../skills/docs-governance/SKILL.md)).
+
+### Tier 3 — Discoverable skills (no rule)
+
+Pure intent-triggered. The skill description is detailed enough that Cursor surfaces it on relevant phrases. No always-on cost.
+
+Skills stay rule-less when the work is **explicitly invoked** by the user, not pattern-triggered (e.g. `audit-pr-architecture`, `docs-lifecycle-sweep` in this repo; `improve-codebase-architecture`, `gritql-codemods`, `ubiquitous-language` in larger codebases).
+
+## Authoring guidelines
+
+### Adding a new rule
+
+1. **Decide the tier** before writing.
+2. **Tier 1 needs justification** — does it really apply to every turn? If it only applies in certain files / certain intents, demote to Tier 2 or Tier 3.
+3. **Tier 2 globs** — write the broadest pattern that's still meaningfully scoped. `**/*.ts` is acceptable for TS-wide rules. Filename heuristics (`*recipe*.ts`) are brittle for content-driven concerns and should be a last resort.
+4. **Tier 3 description** — write the description as if Cursor is grepping for trigger phrases. Include the verbs and nouns the user is likely to say ("rename", "delete", "convert", "consolidate") and the symbols / patterns the agent will see in code.
+5. **Pair with a skill** — every Tier-1 / Tier-2 rule should link to a skill in its `Reference` section for the deep dive. The rule is priming; the skill is reference.
+6. **Author the source under `.agents/rules/<name>.md` and symlink from `.cursor/rules/<name>.mdc`** per the [`agents-first-convention`](./agents-first-convention.md) rule.
+
+### Adding a new skill
+
+1. **Decide if it needs a rule.** If the skill has always-on principles (any `NEVER` / `ALWAYS` clauses, any "MUST be used when") — pair it with a Tier-1 or Tier-2 rule.
+2. **If skill-only**, write the description with explicit trigger phrases. Cursor's discovery is description-match-based.
+3. **Author under `.agents/skills/<name>/SKILL.md` and symlink from `.cursor/skills/<name>`** per the [`agents-first-convention`](./agents-first-convention.md) rule.
+
+## Authoring discipline: durability
+
+Rules and skills are **more durable** than the artifacts they describe. They outlive specific files, specific commit hashes, specific code shapes. Authoring them as if they were short-lived is the most common way they go stale.
+
+Three concrete sub-rules:
+
+1. **Don't cite specific audit / plan / research filenames as canonical examples.** Audits and plans are mortal under [`docs-lifecycle-sweep`](../skills/docs-lifecycle-sweep/SKILL.md) (Tier C delete or Tier B slim). The first time the doc janitor retires a file your skill named, the skill's example rots. Use shape placeholders (`<YYYY-MM-DD>-<topic>.md`, `<topic>.md`) and describe the **shape** of what the next reader should look for ("the most recent audit under `docs/audits/`"), not which file does it today. **Reference docs (`README.md`, `architecture.md`, `glossary.md`, `roadmap.md`, `agents.md`) ARE durable** — citing them by name is fine; they live forever per their lifecycle type.
+2. **Don't cite specific commit hashes or PR numbers as the only path to context.** Hashes and PR URLs are stable but opaque. If the context matters, summarise it inline. Hashes are good as **secondary** anchors ("the seed datapoint, commit `<hash>`") not primary ones.
+3. **Don't cite specific source-code line numbers.** Same drift as above; lines move on every edit. Reference symbols by name. (Same hazard as [`docs/README.md` Rule 7](../../docs/README.md) — universal, not codemap-specific.)
+
+When in doubt: if the prose still reads correctly six months from now after every doc you didn't write got rewritten or deleted, the skill is durable. If it reads as a stale snapshot, slim the citations to placeholders.
+
+## Audit prompts
+
+When reviewing an existing rule:
+
+- **Is it Tier 1?** Check: does it apply on every turn? If it only applies to TS files, flip to Tier 2 with a glob.
+- **Is it Tier 2?** Check: are the globs well-scoped? Could broader globs catch content-driven cases? Could narrower globs save context without losing coverage?
+- **Is it skill-only?** Check: does the skill have any "always" / "never" clauses? If yes, it deserves a rule.
+
+## Reference
+
+- File-layout convention: [`agents-first-convention.md`](./agents-first-convention.md).
+- The docs-governance pair this tier system was first applied to in this repo: [`docs-governance.md` rule](./docs-governance.md) (Tier-2 priming) + [`docs-governance` skill](../skills/docs-governance/SKILL.md) (deep reference).
@@ -0,0 +1,54 @@
+---
+description: Sweep your own new comments at the end of every change. Keep what code can't say; cut the rest.
+globs: "**/*.{ts,tsx,css,html,md}"
+alwaysApply: true
+---
+
+# Concise Comments
+
+After you finish a change — before reporting back — re-read the comments **you** authored in that turn. Keep only the ones that carry information the code itself cannot.
+
+## Decision test
+
+For every comment you wrote, ask: **"Could a teammate (human or AI) re-derive this from the code in under 30 seconds?"**
+
+- **Yes** → delete it. The code is the documentation.
+- **No** → keep it, slim to one sentence if possible.
+
+## Keep
+
+- **Why**, not what — design intent, trade-offs, the rejected alternative.
+- **Non-obvious constraints** — SQLite quirks, parser idiosyncrasies, race conditions, ordering requirements.
+- **Cross-references** that save grep time — `mirrors X`, `see NOTE(foo)`, `tracked at docs/roadmap.md § Y`.
+- **Domain → code translations** — schema-column ↔ JS-field aliases, BE / external-API field aliases.
+- **Sentinels and magic values** — `null because oxc-resolver returns null on unresolved`, `0 because SQLite rejects undefined`.
+
+## Cut
+
+- Restating the function/variable name (`/** Site id. */ sid: number`).
+- Restating the next line of code (`// Reset to page 1` above `setPage(1)`).
+- Generic library practice (`// Memoise this` above `useMemo`).
+- Section headers in short files (`// === Helpers ===`).
+- Author / date stamps (git tracks this).
+- Multi-line prose where one clause does the job.
+
+## Reconcile with `preserve-comments`
+
+[`preserve-comments`](./preserve-comments.md) protects **existing** comments — never delete those without asking.
+
+This rule applies only to comments **you authored in the current turn**. You own them; they earn their keep, or you cut them before handing the work back.
+
+If you slim or delete a pre-existing comment, that requires explicit user confirmation per [`preserve-comments`](./preserve-comments.md) Rule 4 — this rule does not override that.
+
+## When to sweep
+
+- **Always before final report** — make it the last thing you do.
+- **After every comment-touching edit during a long session** — don't accumulate noise across turns.
+- **If you find yourself writing 3+ lines of prose for one decision** — stop, ask whether a one-liner with a code reference would do.
+
+## Length budget (rule of thumb)
+
+- **0 lines** — when the code is self-explanatory.
+- **1 line** — default for kept comments.
+- **2–3 lines** — only when context is genuinely irreducible (e.g. a parser-shape gotcha with two failure modes).
+- **>3 lines** — extract to a `docs/` file and link to it.
@@ -1,60 +1,56 @@
 ---
-description: Always follow the docs governance in docs/README.md when touching files under docs/. Specifically: cite Rules by number, update File Ownership and Single Source of Truth tables when adding/removing docs, fold new content into existing files unless it passes the Existence Test.
-alwaysApply: true
+description: Repo-wide docs framework primer. Use when authoring or editing any docs/, plans/, research/, or other doc-bearing surface in the repo. Defines surface tiers (repo-wide / per-tooling-area), the 5 lifecycle types, the existence test, anchor-preservation discipline, and the delete-and-lift plan lifecycle. Skill at `.agents/skills/docs-governance/SKILL.md` carries the full reference.
+globs: "docs/**, .agents/**"
+alwaysApply: false
 ---
 
-# Docs Governance
+# Docs governance
 
-`docs/README.md` is the source of truth for how the docs folder is organized and edited. Read it first whenever you touch anything under `docs/`.
+Before authoring or editing any doc in this repo, **read the [`docs-governance` skill](../skills/docs-governance/SKILL.md)** for the full reference. This rule is the priming layer.
 
-## Quick checklist
+The canonical Rules (1–9) live in [`docs/README.md`](../../docs/README.md) — cite them by number; never restate them.
 
-When you change a doc, these checks must pass before the PR ships:
+## Surface tiers (which subset of governance applies)
 
-- **Rule 1 — One source of truth.** No prose duplicated across files. Cross-reference by relative path instead.
-- **Rule 2 — Shipped items leave the roadmap.** When a backlog item lands, move its description to its canonical home (architecture / why-codemap / README) and remove it from `roadmap.md`.
-- **Rule 3 — Plans get their own file.** Don't embed plans in `roadmap.md`. Create `docs/plans/<feature-name>.md` and link from the roadmap entry.
-- **Rule 4 — Tables stay current.** When you add or delete a doc, update the **File Ownership** and **Single Source of Truth** tables in `docs/README.md` in the same PR.
-- **Rule 5 — Relative cross-references.** `[architecture.md § Section](./architecture.md#section)` — never absolute paths or repo URLs for in-tree docs.
-- **Rule 6 — No inventory counts in narrative.** Don't hardcode counts of files / symbols / recipes. Use qualitative descriptors or a `codemap query` example. Decision values (cache TTLs, `SCHEMA_VERSION`) are fine.
-- **Rule 7 — No line-number references.** Cite by function name, section heading, or `codemap query` lookup. Methodology tables in `benchmark.md` are exempt.
-- **Rule 8 — Close research notes.** When a `research/` scan's adopt items ship, slim it to a "What shipped" appendix linking to canonical homes. Rejected items keep a `Status: Rejected (date) — <reason>` header.
-- **Rule 9 — New term ⇒ glossary.** Every PR that introduces a new domain noun (table name, recipe id, parser name, schema column) updates `docs/glossary.md` in the same PR. Disambiguations (e.g. `FileRow` TS shape vs `files` SQLite table) take priority.
+| Tier                            | Substrate                                               | Examples                                                                                                                                           |
+| ------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **B** — repo-wide cross-cutting | `docs/` at repo root                                    | `docs/architecture.md`, `docs/glossary.md`, `docs/roadmap.md`, `docs/agents.md`, `docs/plans/`, `docs/research/`, future `docs/audits/`            |
+| **0** — per-tooling-area        | `.agents/`, `.cursor/`, `scripts/`, `templates/agents/` | Governed by [`agents-first-convention`](./agents-first-convention.md) + [`agents-tier-system`](./agents-tier-system.md); no per-area README needed |
 
-## Document Lifecycle (full text in `docs/README.md`)
+(Tier C — per-feature governance — and Tier A — per-shared-component — don't apply yet; see [`docs-governance` § Doc-bearing surface tiers](../skills/docs-governance/SKILL.md#doc-bearing-surface-tiers) for when they would.)
 
-Four doc types: **Reference** (lives forever), **Roadmap** (single file, items move in/out), **Plan** (created on commit, deleted on ship), **Research** (created for evaluations, closed per § Closing research).
+## Five lifecycle types (universal)
 
-Backlogs / frameworks / decisions don't get their own file — they fold into one of the four.
+| Type          | Folder                                                | Closing                                                             |
+| ------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
+| **Reference** | root (`architecture.md`, `glossary.md`, etc.)         | Lives forever; kept current                                         |
+| **Roadmap**   | root (`roadmap.md`, single file)                      | Lives forever                                                       |
+| **Plan**      | `plans/<name>.md`                                     | **Delete + lift** when work ships (no "Slim & keep in plans/")      |
+| **Audit**     | `audit.md` (single) OR `audits/<topic>.md` (multi)    | Substrate variants — see skill                                      |
+| **Research**  | `research/<tool>.md` OR `research/<topic>-YYYY-MM.md` | Adopted (lift + delete) / Rejected (keep with status header) / Open |
 
-### Existence test (apply on every doc-touching PR)
+## Top three disciplines
 
-A file earns its place if it meets at least one of:
-
-1. Source code or another doc cites it (grep finds the path).
-2. It documents durable policy or framework unavailable elsewhere.
-3. It tracks open work.
-4. It carries unique historical context that `git log` + `architecture.md` cannot reconstruct.
-
-If none → fold any salvageable content into roadmap / architecture / glossary, fix cross-refs, **delete the file**.
+1. **Anchor preservation** — slim READMEs keep cited rule numbers and section anchors. Grep before any slim: `rg "Rule [0-9]+" docs/` and `rg "<doc-path>(#[a-z-]+)?"`.
+2. **Anti-bloat meta-rule** — don't add a rule until there's content that needs it. Same for ownership-table rows.
+3. **Repo-level vs in-source** — repo-wide tool evaluations + adoption (fallow, future plugins) live in `.agents/`, not as permanent `docs/research/` files. A `docs/research/` file may motivate the adoption, but the rule + skill earn the permanent home.
 
-### Top-level cap
+## Existence test (apply on every doc-touching PR)
 
-Adding a new top-level doc requires:
-
-1. The topic doesn't fit any existing root-level doc.
-2. The new file passes the existence test on day one.
-3. **File Ownership** table in `docs/README.md` updated in the same PR.
-
-When in doubt, default to absorbing into the closest existing root-level file.
+A file earns its place if it meets at least one of:
 
-## Why this exists
+1. Source code cites it (JSDoc, error message, comment grep-anchor)
+2. It documents durable policy unavailable elsewhere
+3. It tracks open work (audit findings, plan, roadmap items, evaluation)
+4. It carries unique historical context that `git log` + reference docs can't reconstruct
 
-- Avoids the slow rot that hits any docs folder where any contributor (human or agent) can drop a new top-level file at any time.
-- Gives reviewers cite-able rule numbers ("violates Rule 4") instead of vague "this should go elsewhere" feedback.
-- Keeps `git log` legible by making doc files have predictable lifecycles.
+If none → fold + delete.
 
 ## Reference
 
-- [`docs/README.md`](../../docs/README.md) — full text of all rules, the lifecycle, and the existence test.
-- Adapted from PaySpace `analytics/docs/README.md` governance pattern.
+- Full reference: [`.agents/skills/docs-governance/SKILL.md`](../skills/docs-governance/SKILL.md)
+- Doc janitor (operational sweep — apply the spec mechanically, classify Tier A / B / C, delete dead weight): [`.agents/skills/docs-lifecycle-sweep/SKILL.md`](../skills/docs-lifecycle-sweep/SKILL.md). Fire on intent ("clean up stale docs", "compact audits") or proactively after closing a Plan / Audit / Research file.
+- Audit framework: [`.agents/skills/audit-pr-architecture/SKILL.md`](../skills/audit-pr-architecture/SKILL.md). Fire on intent ("audit this PR's architecture", "structural review of #N") or proactively when a PR moves ≥5 files between top-level `src/` modules.
+- Canonical Rules: [`docs/README.md`](../../docs/README.md) — Rules 1–9 cited from across `docs/` and `.agents/`. Don't renumber without a coordinated re-grep + edit pass.
+- File-layout: [`agents-first-convention`](./agents-first-convention.md)
+- Rules vs skills tier system: [`agents-tier-system`](./agents-tier-system.md)