the-grimoire-cli 0.3.2

package/.agents/stack/desktop.md

@@ -0,0 +1,36 @@
+# Profile: desktop
+
+Default for Electron / desktop apps (harvested from ever-sync-adapter).
+
+| Concern | Default |
+|---|---|
+| Shell | Electron |
+| Language | TypeScript (`strict`) |
+| Lint / format | ESLint + Prettier |
+| Test | Vitest (unit) + Playwright/Spectron-style (integration) |
+| IPC | typed channels; document the channel table in `journal/memory/` |
+| Release | new code paths behind env flags (single-unset rollback) |
+| CI | typecheck + lint + test + package on tag |
+| Testing policy | `tdd-mandatory` (override per project) |
+
+`verify`: `tsc --noEmit && eslint . && vitest run --coverage && prettier --check .`
+
+Note: for on-site/production tools, pair with HOTFIX mode (`rules/20-modes.md`).
+
+## Reference defaults (adapt per project; vendor names are examples)
+
+- **Process boundaries:** separate tsconfig per process (main / renderer / preload / shared) with
+  path aliases; explicit IPC channel registry (one `channels.ts`), preload bridge, and typed API.
+- **IPC discipline:** adding a channel touches several files (registry, preload, types, handler, the
+  AGENTS.md/`local/` channel table) — keep that checklist explicit and, ideally, a guardrail test
+  that diffs the registry against the allow-list in CI.
+- **Secrets at rest:** OS keystore (`safeStorage` / keychain), never plaintext in the local DB
+  (`rules/50`).
+- **Native modules:** rebuild for Electron (`electron-rebuild`) before dev/dist; pin native driver
+  versions per backend (e.g. Oracle Instant Client per server version).
+- **Local DB:** embedded SQLite via a typed query builder; a single factory is the only legal
+  instantiation point; temp-DB fixtures (`mkdtemp` + cleanup) for tests.
+- **Tests:** Vitest (unit + integration) + Playwright (E2E); CSP + boundary regression as gates in
+  the `verify` chain. Desktop profile defaults to `tdd-mandatory`.
+- **Lint preset:** start from `templates/lint/` (clean-code limits + type-safety); enforce via
+  `eslint .` in `verify`.

package/.agents/stack/library.md

@@ -0,0 +1,16 @@
+# Profile: library
+
+Default for published or internal reusable packages.
+
+| Concern | Default |
+|---|---|
+| Build | tsup / unbuild → ESM (+ CJS if consumers need it) |
+| Language | TypeScript (`strict`), emit `.d.ts` |
+| Lint / format | ESLint + Prettier |
+| Test | Vitest; high coverage bar (public API) |
+| Public API | explicit `exports` map; no deep imports |
+| Versioning | semver; changesets for release notes |
+| CI | typecheck + lint + test + build + pack-check on PR |
+| Testing policy | `tdd-mandatory` (public contract — override per project) |
+
+`verify`: `tsc --noEmit && eslint . && vitest run --coverage && prettier --check . && npm pack --dry-run`

package/.agents/stack/web-app.md

@@ -0,0 +1,32 @@
+# Profile: web-app
+
+Default for full-stack / front-end web projects.
+
+| Concern | Default |
+|---|---|
+| Framework | Next.js (App Router) or Vite + React |
+| Language | TypeScript (`strict`) — see `standards/typescript.md` |
+| Lint / format | ESLint + Prettier |
+| Test | Vitest + React Testing Library; Playwright for e2e |
+| Coverage | reported in `verify`; threshold set per project |
+| Validation | zod at every boundary |
+| CI | typecheck + lint + test + build on PR |
+| Testing policy | `test-ready-deferred` (override per project) |
+
+`verify`: `tsc --noEmit && eslint . && vitest run --coverage && prettier --check .`
+
+## Reference defaults (adapt per project; vendor names are examples)
+
+- **Auth guards — one model, three call-site shapes:** a single `can(permission)` policy with
+  `requirePermission()` (throws, for actions), `requirePermissionResponse()` (returns 401, for route
+  handlers), `requirePermissionOrRedirect()` (for pages). Zero inline `role === "x"` checks.
+- **Edge-safe auth split:** keep an edge/middleware config with **no DB** separate from the full
+  server auth that hits the DB at sign-in (Auth.js v5 pattern).
+- **Validation:** zod at every server-action boundary; client validation is UX only (`rules/50`).
+- **Module layering:** pure engine + read/write/projection split + schema-ownership by module
+  (`standards/architecture.md`).
+- **Security headers in one place** (e.g. `next.config` headers): CSP, HSTS, X-Frame-Options DENY,
+  X-Content-Type-Options, Referrer-Policy, Permissions-Policy; disable `poweredByHeader`.
+- **DB:** typed query builder / ORM with tracked migrations (generate → migrate); `db:push` dev-only.
+- **Lint preset:** start from `templates/lint/` (clean-code limits + type-safety); `eslint .` in the
+  `verify` script enforces it.

package/.agents/standards/INDEX.md

@@ -0,0 +1,23 @@
+# standards — index
+
+<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
+
+| File | What it covers |
+|---|---|
+| `accessibility.md` | Baseline accessibility (WCAG 2.x AA) for any user-facing surface — the non-negotiable floor plus how to verify it. |
+| `architecture.md` | Module layering and boundaries distilled from real modular codebases. |
+| `attribution.md` | Credit the external work the project builds on: what to record when adopting a tool/pattern/idea, where it goes, and the adapt-not-copy rul… |
+| `clean-code.md` | The canonical code-quality standard: minimize complexity, with limits, type-safety, and performance rules. |
+| `codex.md` | The codex — the project's knowledge/resource root at the repo root: read-first rule, provenance discipline, secrets boundary, and how it re… |
+| `error-codes.md` | Every error carries a stable code so logs, tests, and UIs switch on it, not on message strings. |
+| `general.md` | Baseline conventions: naming, file size, import order, error handling, formatting. |
+| `guardrail-tests.md` | Structural-invariant tests that fail CI when two sources of truth drift apart. |
+| `knowledge-management.md` | The second-brain model: three homes for work-state, and how to view memory as an optional Obsidian vault. |
+| `launch-security-checklist.md` | Pre-launch privacy + security gate for any app that collects user data. |
+| `observability.md` | Production logging, metrics, and tracing lessons from real data/sync tools. |
+| `release-versioning.md` | Versioning, changelog, and release discipline across app and library profiles — what ships, how it's tagged, how it's recorded. |
+| `requirements.md` | How requirements are captured, identified, versioned, and traced — base requirements plus addons and change requests. |
+| `security-scanners.md` | SAST scanners by language and how to wire them into CI to catch exploitable bugs. |
+| `testing-strategy.md` | The project-wide testing approach: the pyramid, what to test at each level, the active policy, and what 'tested' means. |
+| `typescript.md` | TypeScript specifics: strict mode, no any, type-safety expectations. |
+| `writing.md` | How to write agent-facing docs so they are high-signal and versioned. |

package/.agents/standards/accessibility.md

@@ -0,0 +1,50 @@
+---
+updated: 2026-05-31
+status: canonical
+description: "Baseline accessibility (WCAG 2.x AA) for any user-facing surface — the non-negotiable floor plus how to verify it."
+---
+
+# Standards — accessibility
+
+Applies to every user-facing surface (web, desktop UI). Target: **WCAG 2.2 level AA**. Accessibility
+is part of Definition of Done for UI work, not a later pass — it is cheapest built in and most
+expensive retrofitted.
+
+## The non-negotiable floor
+
+- **Semantic HTML first.** Use the right element (`button`, `a`, `nav`, `main`, `label`, `table`).
+  A `div` with a click handler is not a button — it loses keyboard, focus, and screen-reader
+  semantics. Reach for ARIA only when no native element fits, and prefer a native one.
+- **Keyboard operable.** Every interactive control is reachable and operable by keyboard alone, in a
+  logical tab order, with a **visible focus indicator**. No keyboard trap. Test by unplugging the
+  mouse.
+- **Labels & names.** Every input has an associated `<label>`; every icon-only control has an
+  accessible name (`aria-label`); every meaningful image has `alt` (decorative → `alt=""`).
+- **Contrast.** Text ≥ 4.5:1 (≥ 3:1 for large text); UI/graphics ≥ 3:1. Don't encode meaning by
+  **color alone** — pair it with text, icon, or pattern.
+- **Forms & errors.** Errors are announced (not color-only), tied to their field
+  (`aria-describedby`), and the message says how to fix it. Don't disable submit silently.
+- **Structure.** One `h1`; headings nest without skipping. Landmarks (`main`, `nav`) so AT users can
+  jump. Page has a sensible `<title>` and `lang`.
+- **Motion & media.** Respect `prefers-reduced-motion`; no content flashes > 3×/sec; captions/text
+  alternatives for audio/video.
+- **Targets & zoom.** Touch targets ≥ 24×24 CSS px; layout survives 200% zoom and 320px width
+  (reflow, no horizontal scroll).
+- **Live regions.** Dynamic updates (toasts, async results) use `aria-live` so they are announced.
+
+## Internationalization note
+
+If the app is localized (e.g. Thai-first), set `lang` correctly, don't hardcode LTR assumptions, and
+don't build strings by concatenation — these intersect with screen-reader correctness.
+
+## Verify it (not by eye alone)
+
+1. **Automated:** run an axe-based check (axe-core / Playwright `@axe-core/playwright` / Lighthouse)
+   in CI for key pages. Catches ~40% of issues — necessary, not sufficient.
+2. **Keyboard pass:** tab through the whole flow; confirm order, focus visibility, no trap.
+3. **Screen reader smoke:** one pass with VoiceOver/NVDA on the primary flow.
+4. **Zoom/reflow:** 200% zoom + 320px width with no loss of content or function.
+
+The `ecc:frontend-a11y` skill (`skills/catalog.md`) automates much of the audit; this standard is the
+floor it audits against. For UI work, an a11y check is part of the verifier's review
+(`rules/30-verification.md`).

package/.agents/standards/architecture.md

@@ -0,0 +1,39 @@
+---
+updated: 2026-05-31
+status: canonical
+description: Module layering and boundaries distilled from real modular codebases.
+---
+
+# Standards — architecture
+
+Patterns distilled from real modular codebases. Apply where the module is non-trivial; don't
+over-structure a thin CRUD screen (YAGNI).
+
+## Pure domain layer
+
+- Keep business logic in a layer with **zero framework/DB/IO imports** (call it `engine/`, `domain/`,
+  or `core/`). Plain functions in, plain data out.
+- DB/IO lives only in dedicated read/write modules that call into the pure layer — never the reverse.
+- Make non-determinism injectable: pass a **seeded RNG** / clock, so generation is reproducible and
+  unit-testable without mocks.
+
+## Read / write / projection split
+
+- **reads** — query module (`data/queries.ts`), `server-only`, returns raw rows.
+- **writes** — action module (`actions/`), the only place that mutates.
+- **projections** — pure shape transforms for each render surface, no DB. Independently testable.
+- A view layer composes reads + projections and owns the cache tag.
+
+## Schema / ownership by module
+
+- Core owns identity-level schema only; each module owns its own tables. The shared DB client is
+  **schema-less** (doesn't import module tables at init), so modules don't become a circular hub.
+- Modules may re-export core tables for FK convenience — never invert the dependency.
+
+## Invariants
+
+- Where correctness depends on a structural fact (an inner-join that excludes ghosts, an ordering, a
+  default), state it with a `// INVARIANT:` comment **and** a test. A silent structural invariant
+  breaks the first time someone writes a left-join.
+- Validate required env at the **startup boundary** with a clear error — never `process.env.X!`
+  scattered at use sites (a missing var should fail loud at init, not as a random runtime error).

package/.agents/standards/attribution.md

@@ -0,0 +1,39 @@
+---
+updated: 2026-06-14
+status: canonical
+description: "Credit the external work the project builds on: what to record when adopting a tool/pattern/idea, where it goes, and the adapt-not-copy rule."
+---
+
+# Standards — attribution
+
+Credit the external work the project builds on. When you adopt something from outside — a tool,
+library, framework, pattern, or idea (including an article or gist you adapt) — record it and credit
+its author. This is ethics **and** provenance: a future reader must know what is ours, what is
+borrowed, and where it came from. It is the same discipline as `standards/codex.md` (every fact cites
+its source), applied to dependencies.
+
+## What to record
+
+For every external adoption:
+
+- **Name** + **author** (handle / org if known)
+- **Source** — repo URL, package name, or article/gist link
+- **License** — and any redistribution constraint. **Verify it; never guess a license.**
+- **What you adopted** — the tool/pattern, and whether used **as-is** or **adapted**
+- **Where it's wired** — the adopting ADR, and the files/standards that reference it
+- **Date**
+
+## Where it goes
+
+- **The adopting ADR cites the source.** Any decision to bring in an external tool/pattern names and
+  links it in `codex/decisions/` (this template repo: `docs/adr/`). The *why* carries the credit —
+  non-negotiable.
+- **A running ledger** collects them in one place: `docs/attributions.md` at the repo root (the
+  Grimoire template uses this), or `codex/resources/manifest.md` for a consuming project's resources.
+
+## Adapt, don't copy
+
+When you adapt an external idea to this stack, say so and say what you changed — a vendor example is an
+illustration, not a mandate. Credit the source for the idea even when little of its form survives.
+
+Keep this lean (`rules/35-context-economy.md`).

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

@@ -0,0 +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.

package/.agents/standards/codex.md

@@ -0,0 +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.

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

@@ -0,0 +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);
+  }
+}
+```

package/.agents/standards/general.md

@@ -0,0 +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.

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

@@ -0,0 +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.

package/.agents/standards/knowledge-management.md

@@ -0,0 +1,35 @@
+---
+updated: 2026-05-31
+status: canonical
+description: 'The second-brain model: three homes for work-state, and how to view memory as an optional Obsidian vault.'
+---
+
+# Standards — knowledge management
+
+Where work-state lives so context survives across sessions and compaction. Three homes, each
+answering one question; nothing duplicated between them. Continuity lives here, not in chat history.
+
+## Three homes
+
+| Layer | Answers | Home | Git |
+|---|---|---|---|
+| NOW | what am I doing right now? | `journal/session/current.md` | gitignored |
+| KNOWLEDGE | what do we already know? | `journal/memory/` + `journal/memory/MEMORY.md` | tracked |
+| QUEUE | what work is pending? | `journal/backlog/` | tracked |
+
+Write the live state to NOW as you go; promote durable facts to KNOWLEDGE; route pending work to
+QUEUE (`rules/40-handoff.md`). Finish a task, then compact or clear the session — the three homes
+carry continuity, so a fresh session loses nothing that mattered.
+
+## Memory cards
+
+One fact per file under `journal/memory/`, linked with `[[wikilinks]]`; `MEMORY.md` is the one-line index.
+Convert relative dates to absolute. Link liberally — a `[[name]]` with no file yet marks a card
+worth writing later.
+
+## Optional: view memory as an Obsidian vault
+
+`journal/memory/` is plain Markdown using `[[wikilinks]]` — already Obsidian-native. Point an Obsidian vault
+at it for graph view and backlinks over the agent's knowledge base. This is a **human view layer
+only**: Grimoire never depends on Obsidian (the core stays tool-agnostic), and nothing in `journal/memory/`
+requires it.

package/.agents/standards/launch-security-checklist.md

@@ -0,0 +1,45 @@
+---
+updated: 2026-05-31
+status: canonical
+description: Pre-launch privacy + security gate for any app that collects user data.
+---
+
+# Launch security checklist
+
+A pre-launch gate for any app that collects user data. Do not ship to real users until every item
+passes — legal and breach exposure scale with user count, so clear these before marketing.
+
+## 1. Privacy & data map
+- Publish a privacy policy (GDPR / CCPA / PDPA as applicable). PHI → HIPAA (see `skills/catalog.md`
+  Healthcare).
+- Keep a data map: what personal data you collect, where it lives, who can read it, retention.
+- Collect the minimum; delete what you do not need.
+
+## 2. Row-level authorization on every user table
+- Each row is restricted to its authenticated owner (Postgres/Supabase RLS, or app-layer checks).
+- **Default-deny** — zero policies = a wide-open database. Verify one user cannot read another
+  user's rows (open DevTools / hit the API as user B).
+
+## 3. Failure / abuse-path tests (not just the happy path)
+- Wrong password ×N (lockout/backoff), reset for a non-existent email (no user enumeration),
+  expired / missing session, malformed / oversized / injection input. Attackers probe these first.
+
+## 4. Server-side validation on every write route
+- Validate **and** authorize on the server. Client (zod) validation is UX only — attackers call the
+  API directly with JS disabled.
+
+## 5. Security headers + OWASP review
+- Set headers: CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy.
+- Run an OWASP Top 10 review (injection, broken auth, broken access control, XSS, SSRF…) via
+  `ecc:security-review` / `ecc:security-scan`.
+
+## 6. SAST scan
+- Run a static analysis scanner in CI and fix **High/Critical** before launch.
+  See `standards/security-scanners.md`.
+
+## 7. Incident runbook reviewed
+- A dated incident/rollback runbook exists and has had a tabletop or review — not just a green CI.
+  Shipping to production with an untested playbook is a launch risk in itself.
+
+**Gate:** for any user-facing, data-collecting app this checklist is part of the Definition of Done
+(`rules/30-verification.md`).