the-grimoire-cli 0.3.2

package/templates/journal/backlog/README.md

@@ -0,0 +1,18 @@
+# QUEUE — backlog
+
+One work item per file: `backlog/<id>.md`. Frontmatter:
+
+```
+---
+id: <kebab-id>
+status: open        # open | active | blocked | done
+priority: normal    # normal | hotfix
+---
+```
+
+- **Hotfix is a priority flag, not a separate tree.** A hotfix item carries a cleanup checklist
+  (tests to backfill, env flag to remove, ADR if implied).
+- Done → move the file to `backlog/done/` with close-out evidence (ADR link, test reproducer,
+  sign-off) inside it.
+
+Routing (chat → item) is defined in `rules/40-handoff.md`.

package/templates/journal/memory/MEMORY.md

@@ -0,0 +1,15 @@
+# KNOWLEDGE index
+
+One fact per file in `memory/`. Each file has frontmatter (`name` / `description` /
+`type: lesson | field-report | decision-note | reference`) and links to related cards with
+`[[name]]`. This index holds one line per memory — never the content itself.
+
+Architecture-level decisions graduate to `codex/decisions/`.
+
+## Promotion & pruning
+
+Promote a fact into `memory/` only if **all three** hold: non-obvious, project-specific, and worth
+keeping past this week. Session scratch stays in `session/` (gitignored). Prune periodically: drop
+cards whose underlying state has shifted or that a written ADR now supersedes.
+
+<!-- - [Title](file.md) — one-line hook -->

package/templates/journal/session/archive/.gitkeep

@@ -0,0 +1 @@
+

package/templates/journal/session/artifacts/.gitkeep

@@ -0,0 +1 @@
+

package/templates/journal/session/current.md

@@ -0,0 +1,12 @@
+# NOW — current session (template)
+
+> Rewrite this file **in place** every turn. Do not append. Local/gitignored — about *this run* only.
+> Before a context boundary, copy to `session/archive/<YYYY-MM-DD-HHmm>.md` (or run `/checkpoint`).
+
+- **mode:** NORMAL            <!-- NORMAL | HOTFIX -->
+- **focus:**                  <!-- the one thing in flight -->
+- **last-done:**
+- **next-step:**
+- **blockers:**
+- **open-questions:**
+- **files-touched:**

package/templates/lint/README.md

@@ -0,0 +1,25 @@
+# Clean-code lint preset
+
+Mechanical enforcement of `standards/clean-code.md`. **Copy into your project** and extend — do not
+edit in place (the project owns its lint config).
+
+## Use
+
+```sh
+npm i -D eslint @eslint/js typescript-eslint
+cp templates/lint/eslint.config.mjs ./eslint.config.mjs
+```
+
+Extend the tsconfig from your `tsconfig.json`:
+
+```json
+{ "extends": "./tsconfig.base.json" }
+```
+
+## Severities
+
+`warn` for size/complexity limits (guidance while a codebase stabilizes); `error` for safety rules
+(`any`, floating promises, non-null assertions, console). Tighten `warn`→`error` per project once
+clean. Any rule can be overridden in your own config block — it wins.
+
+`tsconfig.base.json` is intentionally comment-free so tooling can parse it as plain JSON.

package/templates/lint/eslint.config.mjs

@@ -0,0 +1,33 @@
+// Grimoire clean-code ESLint preset (flat config). Copy to your project root as eslint.config.mjs
+// (or import + extend it). Install peers: `npm i -D eslint @eslint/js typescript-eslint`.
+// Encodes standards/clean-code.md limits. Override any rule in your own config block — yours wins.
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  {
+    languageOptions: {
+      parserOptions: { projectService: true },
+    },
+    rules: {
+      // --- complexity / size limits (warn: guide, do not block early) ---
+      complexity: ["warn", 10],
+      "max-depth": ["warn", 3],
+      "max-params": ["warn", 4],
+      "max-lines-per-function": ["warn", { max: 50, skipBlankLines: true, skipComments: true }],
+      "max-lines": ["warn", { max: 300, skipBlankLines: true, skipComments: true }],
+      "no-nested-ternary": "warn",
+
+      // --- safety (error: never ship) ---
+      "no-console": ["error", { allow: ["warn", "error"] }],
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-non-null-assertion": "error",
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/switch-exhaustiveness-check": "error",
+      "@typescript-eslint/explicit-module-boundary-types": "error",
+      "@typescript-eslint/prefer-readonly": "error",
+    },
+  },
+);

package/templates/lint/tsconfig.base.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true
+  }
+}

package/templates/local/AGENTS.local.md

@@ -0,0 +1,33 @@
+# Local overrides — this project (loads LAST, wins)
+
+`grimoire sync` never touches anything under `local/`. See `local/README.md` for the full protocol.
+**Do not edit the managed base** (`.agents/rules|standards|stack|agents|skills|commands`,
+`AGENTS.md`, `tooling.json`) — put every change here.
+
+## Project profile
+
+- **Active stack profile:** <!-- web-app | desktop | library -->
+- **Testing policy:** <!-- tdd-mandatory | test-ready-deferred | none -->
+- **Verify command (if non-default):**
+- **Presentation mode:** off  <!-- off | on — render human-facing deliverables as HTML (rules/45-presentation.md) -->
+
+## Project facts
+
+<!-- This section is the new home for everything that used to live in a long CLAUDE.md: the system
+     model, doc map, domain glossary pointers, access/auth model, environment/build gotchas, confirmed
+     values, error-code catalog location, IPC/channel tables. CLAUDE.md becomes a thin pointer; the
+     durable project context moves HERE (it loads last and wins, and `grimoire sync` never touches it).
+     Large domain contracts (IPC tables, confirmed-value sheets) belong in `local/reference/`.
+     Onboarding an existing repo? See commands/onboard.md and move the old CLAUDE.md body into here. -->
+
+## Override declarations
+
+<!-- List any base rule/standard/stack default you are overriding, and where the override lives.
+     e.g. "rules/10 plan-before-code relaxed for spikes — see local/rules/local-10-spikes.md"
+     e.g. "ADRs live in docs/core/adr/ + docs/adr-index.md, not the seeded docs/adr/" -->
+
+## Added (project-only)
+
+<!-- Point to project-only rules/skills/commands you added under local/<area>/.
+     Project rules go in local/rules/ with a `local-` prefix (see local/README.md → naming).
+     Big domain reference docs go in local/reference/. -->

package/templates/local/README.md

@@ -0,0 +1,55 @@
+# local/ — your project's customization layer
+
+Everything under `local/` (at the repo root) belongs to **this project**. `grimoire sync` **never touches it**.
+This is where ALL per-repo customization lives.
+
+## The one hard rule
+
+**Never edit the managed base in a consuming project.** These paths are overwritten on every
+`grimoire sync` (they are the "generals" shipped by the template):
+
+```
+.agents/AGENTS.md  rules/  standards/  stack/  agents/  skills/  commands/  tooling.json
+```
+
+If you edit them, your change is lost on the next sync. Put the change in `local/` instead.
+
+## Two ways to customize
+
+1. **Override** a base behavior — restate it in `local/`. Because `local/` loads **last**, it wins.
+   - A base rule → add the corrected rule in `local/rules/` (or note it in `AGENTS.local.md`).
+   - A base standard/stack default → put the project version in `local/standards/` or `local/stack/`.
+2. **Add** something the base doesn't have — a project-only rule, skill, command, or standard goes
+   straight into the matching `local/<area>/`.
+
+## Layout
+
+| Path | Holds |
+|---|---|
+| `AGENTS.local.md` | entry: active stack profile, testing policy, project facts, override declarations |
+| `rules/` | project-only always-on rules (named `local-*.md`) |
+| `standards/` | project-only coding standards / per-language additions |
+| `stack/` | project-only stack notes or profile overrides |
+| `skills/` | project-only skills — each `<name>/SKILL.md` is mirrored to `.claude/skills/` by init/sync |
+| `commands/` | project-only slash commands |
+| `reference/` | project domain reference docs (big runtime contract, IPC tables, confirmed values) — indexed by `grimoire index` |
+| `tooling.json` | project-only plugins / MCP servers (Linear, Sentry, Supabase, Figma, …) — `grimoire bootstrap` merges them additively with the base |
+
+## Naming `local/rules/` — avoid number collisions with the base
+
+The base ships numbered rules `00–60` (`rules/00-always.md`, `rules/30-verification.md`, …). A
+project rule named `30-security.md` under `local/rules/` reads as "rule 30" too — ambiguous with the
+base's `30-verification.md`. **Prefix every project rule with `local-`** so the number space never
+clashes and the source is obvious at a glance:
+
+```
+local/rules/local-10-design-system.md   ✅  unambiguous, clearly project-owned
+local/rules/30-security.md              ❌  collides with base rules/30-verification.md
+```
+
+Keep the original topic number after the prefix if it helps (`local-30-security.md`) — the `local-`
+makes it distinct regardless. Reference them from `AGENTS.local.md` so the load order is explicit.
+
+## Precedence
+
+base loads first → `local/` loads last → **`local/` wins**. See the load order in `.agents/AGENTS.md`.

package/templates/tests/guardrail.invariants.test.ts

@@ -0,0 +1,59 @@
+// Guardrail test — structural invariants (standards/guardrail-tests.md).
+// Copy into the project's test dir and adapt the scanners. Runs under the existing `verify` gate
+// (Vitest shown; the pattern is runner-agnostic). Fail CLOSED: a scan that returns nothing because
+// it could not read its source is a failure, not a pass.
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+
+const SRC = path.resolve(__dirname, "..", "src");
+
+function walk(dir: string, ext = ".ts"): string[] {
+  const out: string[] = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p, ext));
+    else if (e.name.endsWith(ext)) out.push(p);
+  }
+  return out;
+}
+
+function scan(re: RegExp): Set<string> {
+  const hits = new Set<string>();
+  for (const f of walk(SRC)) {
+    const text = fs.readFileSync(f, "utf8");
+    for (const m of text.matchAll(re)) hits.add(m[1]);
+  }
+  return hits;
+}
+
+function diff(a: Set<string>, b: Set<string>): string[] {
+  return [...a].filter((x) => !b.has(x)).sort();
+}
+
+describe("guardrail: IPC channels are allow-listed", () => {
+  // EXAMPLE — replace with the project's real registry/allow-list source of truth.
+  const ALLOW_LIST: string[] = require("../src/ipc/allow-list").CHANNELS; // declared truth
+  const used = scan(/ipcMain\.handle\(\s*["']([^"']+)["']/g); // live call sites
+
+  it("every registered channel is declared (fail closed on undeclared)", () => {
+    expect(used.size).toBeGreaterThan(0); // scanner found something — not a silent empty
+    expect(diff(used, new Set(ALLOW_LIST))).toEqual([]); // used but undeclared
+  });
+
+  it("no stale allow-list entries", () => {
+    expect(diff(new Set(ALLOW_LIST), used)).toEqual([]); // declared but unused
+  });
+});
+
+describe("guardrail: thrown error codes exist in the catalog", () => {
+  // EXAMPLE — replace catalog source + throw pattern with the project's.
+  const catalog = fs.readFileSync(path.resolve(__dirname, "../.agents/standards/error-codes.md"), "utf8");
+  const declared = new Set([...catalog.matchAll(/`([A-Z]+_[A-Z0-9_]+)`/g)].map((m) => m[1]));
+  const thrown = scan(/AppError\(\s*["']([A-Z]+_[A-Z0-9_]+)["']/g);
+
+  it("every thrown code is catalogued", () => {
+    expect(declared.size).toBeGreaterThan(0); // catalog readable — fail closed, not a silent skip
+    expect(diff(thrown, declared)).toEqual([]);
+  });
+});