the-grimoire-cli 0.3.2 → 0.5.0

package/.agents/standards/clean-code.md

@@ -1,121 +1,121 @@
----
-updated: 2026-05-31
-status: canonical
-description: 'The canonical code-quality standard: minimize complexity, with limits, type-safety, and performance rules.'
----
-
-# Standards — clean code
-
-The one goal: **minimize complexity** — the cognitive load to understand and safely change the code
-(Ousterhout, *A Philosophy of Software Design*). Every rule below serves that goal; when two rules
-seem to conflict, pick the option a reader understands faster. Supporting canon: KISS, YAGNI,
-DRY-on-the-third-repetition, information hiding, SOLID.
-
-> Language-agnostic core. TypeScript specifics: `standards/typescript.md`. Always-on summary:
-> `rules/05-code-quality.md`. Mechanical enforcement: `templates/lint/`.
-
-## When to read
-
-Any change under `src/` (or the project's source root), and when reviewing another agent's output.
-
-## Limits
-
-Guardrails, not goals — a function at 49 lines is not "good" because it fits. Projects may override
-in `local/`. Enforced by `templates/lint/` where the stack supports it.
-
-| Constraint | Limit | Past it |
-|---|---|---|
-| Function length | ≤ 50 lines | extract a helper |
-| Parameters | ≤ 4 | pass an options object |
-| Nesting depth | ≤ 3 | guard clauses / extract |
-| Cyclomatic complexity | ≤ 10 | split the branch logic |
-| File length | soft 200 / hard 300 | split by responsibility |
-
-## Readability
-
-- Guard clauses and early returns over nested `if`/`else`.
-- No dense one-liners that trade clarity for brevity.
-- No magic numbers or strings — name them (`const MAX_RETRIES = 3`).
-- Names come from the domain, not the implementation; match the surrounding code.
-- Comments explain **why** (constraints, workarounds, invariants), never **what**. Delete comments
-  that restate the code.
-
-## The ladder (climb before you write)
-
-YAGNI as a reflex, not a slogan. Before writing code, stop at the **first rung that holds**:
-
-1. **Does this need to exist?** Speculative need → skip it, say so in one line.
-2. **Stdlib does it?** Use it.
-3. **Native platform feature covers it?** DB constraint over app code, CSS over JS, `<input type="date">` over a picker lib.
-4. **Already-installed dependency solves it?** Use it — never add a new dep for what a few lines do.
-5. **One line?** One line.
-6. **Only then:** the minimum code that works.
-
-Two rungs work → take the higher one and move on; the ladder is a reflex, not a research project.
-No interface with one implementation, no factory for one product, no config for a value that never
-changes, no scaffolding "for later". Deletion over addition; the shortest working diff wins.
-
-**Never simplify away** (lazy, not negligent): input validation at trust boundaries, error handling
-that prevents data loss, security measures, accessibility basics, or anything explicitly requested.
-Picking the flimsier algorithm to save a line is not laziness — it's a bug.
-
-## Function & module design
-
-- One responsibility per function; extract when it grows a second.
-- Command/query separation: a function either does something or returns something, not both.
-- No boolean flag parameters — they hide two functions in one. Split, or pass an enum/options object.
-- Prefer pure functions; isolate and minimize side effects.
-- Default to immutability; do not mutate inputs.
-- Deep modules: a simple interface over meaningful work. A wrapper that only forwards calls adds
-  complexity without hiding any.
-
-## Type safety (a quality gate, not decoration)
-
-- No `any`. Use `unknown` and narrow, or a real type.
-- Explicit return types on exported functions.
-- No unjustified non-null assertions (`!`); narrow instead, or comment the invariant.
-- Exhaustive `switch` over unions (compile-time `never` check).
-- No floating promises — `await`, return, or explicitly `void`.
-
-## Performance (measured, never premature)
-
-Premature optimization is still banned (YAGNI). But do not ship known-quadratic or chatty code:
-
-- No N+1 queries / calls — batch.
-- Hoist invariant work out of loops.
-- No synchronous I/O on a hot path or the UI thread.
-- Stream or paginate large data; do not load it all into memory.
-- Memoize only at a profiled hotspot, with the evidence noted.
-- Avoid O(n²) on inputs that are large in production.
-
-## Suppression policy
-
-- `eslint-disable`, `@ts-ignore`/`@ts-expect-error`, and `any` require an inline comment naming the
-  exact constraint and a follow-up. No silent suppression.
-- Disabling a rule to make CI green **without an equivalent guard** is tech debt — record it; open an
-  ADR (`codex/decisions/`) if it is structural.
-- A **deliberate shortcut** (a ladder rung taken with a known ceiling — global lock, O(n²) scan, naive
-  heuristic) gets a `ponytail:` comment naming the ceiling and the upgrade path:
-  `// ponytail: global lock, per-account locks if throughput matters`. This reads the simplification as
-  intent, not ignorance, and the marker is harvestable into a debt ledger (see `stack/README.md`).
-- Never weaken a protection (CSP, a boundary/regression test) without an equal-or-stronger replacement.
-
-## Cleanup
-
-- No commented-out code — delete it; git remembers.
-- No unused exports, variables, or imports.
-- Remove one-off scripts (migrations, generators, debug harnesses) after use.
-
-## Review checklist (the verifier refutes against this)
-
-- [ ] Climbed the ladder — no code that stdlib/native/an existing dep already does; no speculative
-      abstraction; deliberate shortcuts carry a `ponytail:` ceiling+upgrade comment; no guardrail
-      (validation, data-loss, security, a11y) simplified away.
-- [ ] Within limits (length, params, nesting, complexity, file size).
-- [ ] Reads top-to-bottom; guard clauses; no magic values; why-comments only.
-- [ ] One responsibility per unit; no boolean-flag params; side effects isolated.
-- [ ] No `any`; exported return types; exhaustive switches; no floating promises.
-- [ ] No N+1, no sync I/O on hot paths, no needless O(n²); memoization is evidence-backed.
-- [ ] No unjustified suppression; no weakened guard.
-- [ ] No commented-out or dead code; one-off scripts removed.
-- [ ] `verify` green (typecheck + lint + test + build); nothing mislabeled PASS.
+---
+updated: 2026-05-31
+status: canonical
+description: 'The canonical code-quality standard: minimize complexity, with limits, type-safety, and performance rules.'
+---
+
+# Standards — clean code
+
+The one goal: **minimize complexity** — the cognitive load to understand and safely change the code
+(Ousterhout, *A Philosophy of Software Design*). Every rule below serves that goal; when two rules
+seem to conflict, pick the option a reader understands faster. Supporting canon: KISS, YAGNI,
+DRY-on-the-third-repetition, information hiding, SOLID.
+
+> Language-agnostic core. TypeScript specifics: `standards/typescript.md`. Always-on summary:
+> `rules/05-code-quality.md`. Mechanical enforcement: `templates/lint/`.
+
+## When to read
+
+Any change under `src/` (or the project's source root), and when reviewing another agent's output.
+
+## Limits
+
+Guardrails, not goals — a function at 49 lines is not "good" because it fits. Projects may override
+in `local/`. Enforced by `templates/lint/` where the stack supports it.
+
+| Constraint | Limit | Past it |
+|---|---|---|
+| Function length | ≤ 50 lines | extract a helper |
+| Parameters | ≤ 4 | pass an options object |
+| Nesting depth | ≤ 3 | guard clauses / extract |
+| Cyclomatic complexity | ≤ 10 | split the branch logic |
+| File length | soft 200 / hard 300 | split by responsibility |
+
+## Readability
+
+- Guard clauses and early returns over nested `if`/`else`.
+- No dense one-liners that trade clarity for brevity.
+- No magic numbers or strings — name them (`const MAX_RETRIES = 3`).
+- Names come from the domain, not the implementation; match the surrounding code.
+- Comments explain **why** (constraints, workarounds, invariants), never **what**. Delete comments
+  that restate the code.
+
+## The ladder (climb before you write)
+
+YAGNI as a reflex, not a slogan. Before writing code, stop at the **first rung that holds**:
+
+1. **Does this need to exist?** Speculative need → skip it, say so in one line.
+2. **Stdlib does it?** Use it.
+3. **Native platform feature covers it?** DB constraint over app code, CSS over JS, `<input type="date">` over a picker lib.
+4. **Already-installed dependency solves it?** Use it — never add a new dep for what a few lines do.
+5. **One line?** One line.
+6. **Only then:** the minimum code that works.
+
+Two rungs work → take the higher one and move on; the ladder is a reflex, not a research project.
+No interface with one implementation, no factory for one product, no config for a value that never
+changes, no scaffolding "for later". Deletion over addition; the shortest working diff wins.
+
+**Never simplify away** (lazy, not negligent): input validation at trust boundaries, error handling
+that prevents data loss, security measures, accessibility basics, or anything explicitly requested.
+Picking the flimsier algorithm to save a line is not laziness — it's a bug.
+
+## Function & module design
+
+- One responsibility per function; extract when it grows a second.
+- Command/query separation: a function either does something or returns something, not both.
+- No boolean flag parameters — they hide two functions in one. Split, or pass an enum/options object.
+- Prefer pure functions; isolate and minimize side effects.
+- Default to immutability; do not mutate inputs.
+- Deep modules: a simple interface over meaningful work. A wrapper that only forwards calls adds
+  complexity without hiding any.
+
+## Type safety (a quality gate, not decoration)
+
+- No `any`. Use `unknown` and narrow, or a real type.
+- Explicit return types on exported functions.
+- No unjustified non-null assertions (`!`); narrow instead, or comment the invariant.
+- Exhaustive `switch` over unions (compile-time `never` check).
+- No floating promises — `await`, return, or explicitly `void`.
+
+## Performance (measured, never premature)
+
+Premature optimization is still banned (YAGNI). But do not ship known-quadratic or chatty code:
+
+- No N+1 queries / calls — batch.
+- Hoist invariant work out of loops.
+- No synchronous I/O on a hot path or the UI thread.
+- Stream or paginate large data; do not load it all into memory.
+- Memoize only at a profiled hotspot, with the evidence noted.
+- Avoid O(n²) on inputs that are large in production.
+
+## Suppression policy
+
+- `eslint-disable`, `@ts-ignore`/`@ts-expect-error`, and `any` require an inline comment naming the
+  exact constraint and a follow-up. No silent suppression.
+- Disabling a rule to make CI green **without an equivalent guard** is tech debt — record it; open an
+  ADR (`codex/decisions/`) if it is structural.
+- A **deliberate shortcut** (a ladder rung taken with a known ceiling — global lock, O(n²) scan, naive
+  heuristic) gets a `ponytail:` comment naming the ceiling and the upgrade path:
+  `// ponytail: global lock, per-account locks if throughput matters`. This reads the simplification as
+  intent, not ignorance, and the marker is harvestable into a debt ledger (see `stack/README.md`).
+- Never weaken a protection (CSP, a boundary/regression test) without an equal-or-stronger replacement.
+
+## Cleanup
+
+- No commented-out code — delete it; git remembers.
+- No unused exports, variables, or imports.
+- Remove one-off scripts (migrations, generators, debug harnesses) after use.
+
+## Review checklist (the verifier refutes against this)
+
+- [ ] Climbed the ladder — no code that stdlib/native/an existing dep already does; no speculative
+      abstraction; deliberate shortcuts carry a `ponytail:` ceiling+upgrade comment; no guardrail
+      (validation, data-loss, security, a11y) simplified away.
+- [ ] Within limits (length, params, nesting, complexity, file size).
+- [ ] Reads top-to-bottom; guard clauses; no magic values; why-comments only.
+- [ ] One responsibility per unit; no boolean-flag params; side effects isolated.
+- [ ] No `any`; exported return types; exhaustive switches; no floating promises.
+- [ ] No N+1, no sync I/O on hot paths, no needless O(n²); memoization is evidence-backed.
+- [ ] No unjustified suppression; no weakened guard.
+- [ ] No commented-out or dead code; one-off scripts removed.
+- [ ] `verify` green (typecheck + lint + test + build); nothing mislabeled PASS.

package/.agents/standards/codex.md

@@ -1,69 +1,69 @@
----
-updated: 2026-06-06
-status: canonical
-description: "The codex — the project's knowledge/resource root at the repo root: read-first rule, provenance discipline, secrets boundary, and how it relates to the base contract."
----
-
-# Standards — codex
-
-`codex/` is the project's **knowledge and resource root** — what the system is, what it must do, why
-it's built that way, and the raw materials and evidence behind those claims. It lives at the **repo
-root** (not under `.agents/`), is **project-owned**, and `grimoire sync` never touches it; the base
-contract holds only a *pointer* to it (`codex/INDEX.md`). It is tracked in git — knowledge is durable
-— **except** raw secret-bearing or huge resources, which are gitignored with a tracked manifest.
-
-codex subsumes what used to scatter across `docs/`: requirements, decisions, domain knowledge,
-evidence, resources, runbooks. It is the rebuild's **source of truth**.
-
-## Read-first rule
-
-Any domain reference starts at `codex/INDEX.md`, then the relevant subfolder's `INDEX.md` (the
-signpost). New work reads the matching INDEX **before** acting — a fresh session must not start blind
-to recorded project knowledge. Every codex folder keeps its own `INDEX.md`.
-
-## Structure
-
-Canonical folders, each with an `INDEX.md` + short `README.md`:
-
-| Folder | Holds |
-|---|---|
-| `domain/` | What the system **is** — glossary, context, business rules, capabilities. |
-| `requirements/` | What it must **do** — IDed, versioned (`standards/requirements.md`). |
-| `decisions/` | **Why** — ADRs, one per decision. |
-| `evidence/` | Investigation / reverse-engineering / extraction outputs, each fact sourced. |
-| `resources/` | Raw materials — datasets, vendor specs, dumps, snapshots (+ a manifest). |
-| `reference/` | Confirmed-value tables, API/IPC catalogs, big contracts the code reads back. |
-| `runbooks/` | The on-call answer to "production is broken." |
-
-The structure is **extensible**: add a folder when a new kind of knowledge appears; give it an
-`INDEX.md` and list it in `codex/INDEX.md`. Keep entry/INDEX files lean
-(`rules/35-context-economy.md`).
-
-## Provenance discipline
-
-The knowledge base is the rebuild's source of truth, so it carries no unsourced guesses.
-
-- Every recorded fact cites its **source** (file + offset/record) and a **CONFIRMED | INFERRED** tag.
-- Unsupported claims are **removed or demoted** to "not recovered" — silence is not a finding.
-- `INFERRED` is a lead, not a contract: confirm it from a source before code relies on it.
-- **Pre-existing docs are not trusted until audited** to this standard. An audited doc carries
-  `audited: <date>`; an un-audited one is treated as unverified.
-
-## Secrets / leak boundary
-
-- Real secrets / PHI **never** go in tracked knowledge docs. They live in a **gitignored inventory**
-  recording each secret's **source + purpose** (for rotate/revoke), not the value in any tracked file.
-- **The chat is the leak boundary**: never echo a secret or PHI into chat or agent output. Record a
-  location + purpose, not the value.
-- **Re-audit tracked content before connecting or pushing** a repo — confirm no secret/PHI slipped
-  into a tracked doc. See `rules/50-security.md` + `standards/launch-security-checklist.md`.
-
-## Relationship to the base
-
-- **Requirements (what)** → `codex/requirements/`; **decisions (why)** → `codex/decisions/`. Both are
-  cited by the task contract (`rules/10-working-process.md`) and checked by the verifier
-  (`rules/30-verification.md`).
-- **Ground-truth values** → `codex/reference/`; an ADR that changes one sets
-  `updates-confirmed-values: yes` and updates the table in the **same PR**.
-- The base governs *how to work*; codex holds *what this project knows*. Base loads first, `local/`
-  wins — codex is project-owned knowledge, not a base override.
+---
+updated: 2026-06-06
+status: canonical
+description: "The codex — the project's knowledge/resource root at the repo root: read-first rule, provenance discipline, secrets boundary, and how it relates to the base contract."
+---
+
+# Standards — codex
+
+`codex/` is the project's **knowledge and resource root** — what the system is, what it must do, why
+it's built that way, and the raw materials and evidence behind those claims. It lives at the **repo
+root** (not under `.agents/`), is **project-owned**, and `grimoire sync` never touches it; the base
+contract holds only a *pointer* to it (`codex/INDEX.md`). It is tracked in git — knowledge is durable
+— **except** raw secret-bearing or huge resources, which are gitignored with a tracked manifest.
+
+codex subsumes what used to scatter across `docs/`: requirements, decisions, domain knowledge,
+evidence, resources, runbooks. It is the rebuild's **source of truth**.
+
+## Read-first rule
+
+Any domain reference starts at `codex/INDEX.md`, then the relevant subfolder's `INDEX.md` (the
+signpost). New work reads the matching INDEX **before** acting — a fresh session must not start blind
+to recorded project knowledge. Every codex folder keeps its own `INDEX.md`.
+
+## Structure
+
+Canonical folders, each with an `INDEX.md` + short `README.md`:
+
+| Folder | Holds |
+|---|---|
+| `domain/` | What the system **is** — glossary, context, business rules, capabilities. |
+| `requirements/` | What it must **do** — IDed, versioned (`standards/requirements.md`). |
+| `decisions/` | **Why** — ADRs, one per decision. |
+| `evidence/` | Investigation / reverse-engineering / extraction outputs, each fact sourced. |
+| `resources/` | Raw materials — datasets, vendor specs, dumps, snapshots (+ a manifest). |
+| `reference/` | Confirmed-value tables, API/IPC catalogs, big contracts the code reads back. |
+| `runbooks/` | The on-call answer to "production is broken." |
+
+The structure is **extensible**: add a folder when a new kind of knowledge appears; give it an
+`INDEX.md` and list it in `codex/INDEX.md`. Keep entry/INDEX files lean
+(`rules/35-context-economy.md`).
+
+## Provenance discipline
+
+The knowledge base is the rebuild's source of truth, so it carries no unsourced guesses.
+
+- Every recorded fact cites its **source** (file + offset/record) and a **CONFIRMED | INFERRED** tag.
+- Unsupported claims are **removed or demoted** to "not recovered" — silence is not a finding.
+- `INFERRED` is a lead, not a contract: confirm it from a source before code relies on it.
+- **Pre-existing docs are not trusted until audited** to this standard. An audited doc carries
+  `audited: <date>`; an un-audited one is treated as unverified.
+
+## Secrets / leak boundary
+
+- Real secrets / PHI **never** go in tracked knowledge docs. They live in a **gitignored inventory**
+  recording each secret's **source + purpose** (for rotate/revoke), not the value in any tracked file.
+- **The chat is the leak boundary**: never echo a secret or PHI into chat or agent output. Record a
+  location + purpose, not the value.
+- **Re-audit tracked content before connecting or pushing** a repo — confirm no secret/PHI slipped
+  into a tracked doc. See `rules/50-security.md` + `standards/launch-security-checklist.md`.
+
+## Relationship to the base
+
+- **Requirements (what)** → `codex/requirements/`; **decisions (why)** → `codex/decisions/`. Both are
+  cited by the task contract (`rules/10-working-process.md`) and checked by the verifier
+  (`rules/30-verification.md`).
+- **Ground-truth values** → `codex/reference/`; an ADR that changes one sets
+  `updates-confirmed-values: yes` and updates the table in the **same PR**.
+- The base governs *how to work*; codex holds *what this project knows*. Base loads first, `local/`
+  wins — codex is project-owned knowledge, not a base override.

package/.agents/standards/error-codes.md

@@ -1,41 +1,41 @@
----
-updated: 2026-05-31
-status: canonical
-description: Every error carries a stable code so logs, tests, and UIs switch on it, not on message strings.
----
-
-# Standards — error-code catalog
-
-Every thrown/returned error carries a stable **code** so logs, tests, and UIs can switch on it
-without string-matching messages.
-
-## Convention
-
-- Code shape: `DOMAIN_REASON` in CONSTANT_CASE — e.g. `AUTH_TOKEN_EXPIRED`, `SYNC_CONFLICT`,
-  `VALIDATION_REQUIRED_FIELD`.
-- One catalog file per project (e.g. `src/errors/catalog.ts`) — the single source of truth.
-- Error objects expose `{ code, message, cause? }`. `message` is human-facing; `code` is the contract.
-- A lint/check script validates that every code used exists in the catalog and that the catalog has
-  no duplicates. Wire it into the `verify` script as a gate (`lint:error-codes`): register the code **before** implementing; the build fails on an unregistered or duplicate code.
-
-## What the template ships
-
-- This convention.
-- A scaffold check script stub (`stack/` profiles reference it). **The project fills the catalog** —
-  the template does not ship project-specific codes.
-
-## Example (TypeScript)
-
-```ts
-export const ERROR_CODES = {
-  AUTH_TOKEN_EXPIRED: "AUTH_TOKEN_EXPIRED",
-  VALIDATION_REQUIRED_FIELD: "VALIDATION_REQUIRED_FIELD",
-} as const;
-export type ErrorCode = keyof typeof ERROR_CODES;
-
-export class AppError extends Error {
-  constructor(public code: ErrorCode, message: string, public cause?: unknown) {
-    super(message);
-  }
-}
-```
+---
+updated: 2026-05-31
+status: canonical
+description: Every error carries a stable code so logs, tests, and UIs switch on it, not on message strings.
+---
+
+# Standards — error-code catalog
+
+Every thrown/returned error carries a stable **code** so logs, tests, and UIs can switch on it
+without string-matching messages.
+
+## Convention
+
+- Code shape: `DOMAIN_REASON` in CONSTANT_CASE — e.g. `AUTH_TOKEN_EXPIRED`, `SYNC_CONFLICT`,
+  `VALIDATION_REQUIRED_FIELD`.
+- One catalog file per project (e.g. `src/errors/catalog.ts`) — the single source of truth.
+- Error objects expose `{ code, message, cause? }`. `message` is human-facing; `code` is the contract.
+- A lint/check script validates that every code used exists in the catalog and that the catalog has
+  no duplicates. Wire it into the `verify` script as a gate (`lint:error-codes`): register the code **before** implementing; the build fails on an unregistered or duplicate code.
+
+## What the template ships
+
+- This convention.
+- A scaffold check script stub (`stack/` profiles reference it). **The project fills the catalog** —
+  the template does not ship project-specific codes.
+
+## Example (TypeScript)
+
+```ts
+export const ERROR_CODES = {
+  AUTH_TOKEN_EXPIRED: "AUTH_TOKEN_EXPIRED",
+  VALIDATION_REQUIRED_FIELD: "VALIDATION_REQUIRED_FIELD",
+} as const;
+export type ErrorCode = keyof typeof ERROR_CODES;
+
+export class AppError extends Error {
+  constructor(public code: ErrorCode, message: string, public cause?: unknown) {
+    super(message);
+  }
+}
+```

package/.agents/standards/general.md

@@ -1,46 +1,46 @@
----
-updated: 2026-05-31
-status: canonical
-description: 'Baseline conventions: naming, file size, import order, error handling, formatting.'
----
-
-# Standards — general
-
-## Naming
-
-| Thing | Case | Example |
-|---|---|---|
-| files / dirs | kebab-case | `user-profile.ts` |
-| variables / functions | camelCase | `getUserProfile` |
-| types / classes / components | PascalCase | `UserProfile` |
-| constants | CONSTANT_CASE | `MAX_RETRIES` |
-| booleans | `is/has/can/should` prefix | `isActive`, `canEdit` |
-
-Names come from the **domain**, not the implementation. Match the surrounding code.
-
-## File size
-
-- Soft ~200 / hard 300 lines (full limits table: `standards/clean-code.md`). Past that, split by
-  responsibility.
-- One primary export per file where practical.
-
-## Imports (ordering)
-
-1. std lib / runtime
-2. third-party
-3. internal absolute (`@/...`)
-4. relative (`./`, `../`)
-
-Blank line between groups. No unused imports.
-
-## Error handling
-
-- Throw typed errors carrying a **code** (see `error-codes.md`). Never throw bare strings.
-- Catch only what you can handle; otherwise let it propagate.
-- No silent catches. If you swallow an error, log *why* with context.
-- Fail closed on the security path (`rules/50-security.md`).
-
-## Formatting
-
-- Formatter + linter own style (Prettier/ESLint, ruff, gofmt, …). Do not hand-format.
-- `format:check` is part of the `verify` script and must pass.
+---
+updated: 2026-05-31
+status: canonical
+description: 'Baseline conventions: naming, file size, import order, error handling, formatting.'
+---
+
+# Standards — general
+
+## Naming
+
+| Thing | Case | Example |
+|---|---|---|
+| files / dirs | kebab-case | `user-profile.ts` |
+| variables / functions | camelCase | `getUserProfile` |
+| types / classes / components | PascalCase | `UserProfile` |
+| constants | CONSTANT_CASE | `MAX_RETRIES` |
+| booleans | `is/has/can/should` prefix | `isActive`, `canEdit` |
+
+Names come from the **domain**, not the implementation. Match the surrounding code.
+
+## File size
+
+- Soft ~200 / hard 300 lines (full limits table: `standards/clean-code.md`). Past that, split by
+  responsibility.
+- One primary export per file where practical.
+
+## Imports (ordering)
+
+1. std lib / runtime
+2. third-party
+3. internal absolute (`@/...`)
+4. relative (`./`, `../`)
+
+Blank line between groups. No unused imports.
+
+## Error handling
+
+- Throw typed errors carrying a **code** (see `error-codes.md`). Never throw bare strings.
+- Catch only what you can handle; otherwise let it propagate.
+- No silent catches. If you swallow an error, log *why* with context.
+- Fail closed on the security path (`rules/50-security.md`).
+
+## Formatting
+
+- Formatter + linter own style (Prettier/ESLint, ruff, gofmt, …). Do not hand-format.
+- `format:check` is part of the `verify` script and must pass.

package/.agents/standards/guardrail-tests.md

@@ -1,40 +1,40 @@
----
-updated: 2026-05-31
-status: canonical
-description: Structural-invariant tests that fail CI when two sources of truth drift apart.
----
-
-# Standards — guardrail tests (structural invariants)
-
-A **guardrail test** asserts a structural invariant of the codebase, not a behaviour. It diffs two
-sources that must agree and fails CI when they drift. Unit tests catch *wrong logic*; guardrail tests
-catch *wrong wiring* — a channel registered but not allow-listed, an error code thrown but absent
-from the catalog, a permission used but undeclared.
-
-## When to add one
-
-Add a guardrail whenever two places encode the same truth and silent drift between them is a defect:
-
-| Invariant | Sources that must agree |
-|---|---|
-| IPC channels | the channel registry ↔ the main-process allow-list (`rules/50` fail-closed) |
-| Error codes | codes thrown in source ↔ `standards/error-codes.md` catalog |
-| Permissions | `can(permission)` keys used ↔ the declared permission set |
-| Confirmed values | values read in code ↔ the project's confirmed-values table (ADR-tracked) |
-| Routes / events | registered handlers ↔ the typed route/event map |
-
-## Shape
-
-A guardrail is an ordinary test in the project's runner (it rides the existing `verify` gate). It
-must **fail closed**: if it cannot read one side, that is a failure, not a skip. Report the diff both
-ways — present-but-unexpected *and* expected-but-missing — so neither orphan nor gap hides.
-
-```
-actual   = scan source for the live set         // e.g. ipcMain.handle("…") call sites
-declared = read the registry / catalog / table  // the source of truth
-expect(actual − declared).toBeEmpty()   // used but undeclared  → fail closed
-expect(declared − actual).toBeEmpty()   // declared but unused  → stale entry
-```
-
-Starter: `templates/tests/guardrail.invariants.test.ts` (adapt the scanners to the project). Wire it
-into CI as part of `verify` so drift fails the PR, not production.
+---
+updated: 2026-05-31
+status: canonical
+description: Structural-invariant tests that fail CI when two sources of truth drift apart.
+---
+
+# Standards — guardrail tests (structural invariants)
+
+A **guardrail test** asserts a structural invariant of the codebase, not a behaviour. It diffs two
+sources that must agree and fails CI when they drift. Unit tests catch *wrong logic*; guardrail tests
+catch *wrong wiring* — a channel registered but not allow-listed, an error code thrown but absent
+from the catalog, a permission used but undeclared.
+
+## When to add one
+
+Add a guardrail whenever two places encode the same truth and silent drift between them is a defect:
+
+| Invariant | Sources that must agree |
+|---|---|
+| IPC channels | the channel registry ↔ the main-process allow-list (`rules/50` fail-closed) |
+| Error codes | codes thrown in source ↔ `standards/error-codes.md` catalog |
+| Permissions | `can(permission)` keys used ↔ the declared permission set |
+| Confirmed values | values read in code ↔ the project's confirmed-values table (ADR-tracked) |
+| Routes / events | registered handlers ↔ the typed route/event map |
+
+## Shape
+
+A guardrail is an ordinary test in the project's runner (it rides the existing `verify` gate). It
+must **fail closed**: if it cannot read one side, that is a failure, not a skip. Report the diff both
+ways — present-but-unexpected *and* expected-but-missing — so neither orphan nor gap hides.
+
+```
+actual   = scan source for the live set         // e.g. ipcMain.handle("…") call sites
+declared = read the registry / catalog / table  // the source of truth
+expect(actual − declared).toBeEmpty()   // used but undeclared  → fail closed
+expect(declared − actual).toBeEmpty()   // declared but unused  → stale entry
+```
+
+Starter: `templates/tests/guardrail.invariants.test.ts` (adapt the scanners to the project). Wire it
+into CI as part of `verify` so drift fails the PR, not production.