the-grimoire-cli 0.3.2

package/.agents/AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md — master contract (tool-agnostic)
+
+This is the **canonical entry** for every agent working in this repo. Claude Code reaches it via
+`CLAUDE.md` (`@.agents/AGENTS.md`). Read in the order below — do **not** "read everything" up front.
+
+Keep this file lean (`rules/35-context-economy.md`): tone, hardest rules, the map, pointers — detail
+lives in the files it links.
+
+## Tone
+
+The person you work with is a **Product Builder** — address them directly ("you"), not as a passive
+third party. Talk straight: factual and data-driven, no hype, no flattery, no telling them what they
+want to hear. State trade-offs, risks, and disagreements plainly, with the evidence behind them —
+being right matters more than being agreeable. Stay calm and professional, never emotional or
+defensive. They may not know a given technical detail; explain it when it matters, plainly and
+without condescension. Be terse and technical, and match the surrounding code and the user's
+register. Project-specific tone or any communication mode lives in `local/AGENTS.local.md`.
+
+## Load order
+
+1. **This file** — hardest rules + the map (below).
+2. **`rules/`** — always-on working process. Read `00-always.md` every session.
+3. **`codex/INDEX.md`** — the project's knowledge base (domain, requirements, decisions, evidence,
+   resources, reference, runbooks). Read-on-demand, but **read-first for any domain/feature work**.
+4. **`standards/`** — when writing code, load `general.md` + the per-language file.
+5. **`stack/`** — when scaffolding or configuring, load the active profile.
+6. **`codex/decisions/`** — when a decision's *why* matters.
+7. **`local/`** — per-project customization. Read `local/AGENTS.local.md`, then the matching
+   `local/<area>/` (rules/standards/stack/skills/commands/reference) for any base area you touch;
+   **loads last and wins**.
+
+## The map
+
+| Need | Go to |
+|---|---|
+| System structure / what grimoire creates / CLI behavior / layout & lifecycles | `NAVIGATOR.md` |
+| Project knowledge / domain / evidence / resources / requirements / decisions | `codex/` (start at `codex/INDEX.md`) |
+| Working process, modes, handoff routing | `rules/` |
+| Coding standards, naming, error codes | `standards/` |
+| Requirements (base / addon / change request) | `standards/requirements.md` + `codex/requirements/` |
+| Test strategy, release/versioning, accessibility | `standards/testing-strategy.md` · `standards/release-versioning.md` · `standards/accessibility.md` |
+| Framework / lint / test / CI **starter templates** (copy manually — not auto-seeded) | `stack/` + `templates/ci/` · `templates/lint/` · `templates/tests/` |
+| Independent verification (the verifier) | `rules/30-verification.md` + `agents/verifier.md` |
+| What am I doing right now? | `journal/session/current.md` (NOW) |
+| What do we already know? | `journal/memory/` + `journal/memory/MEMORY.md` (KNOWLEDGE) |
+| What work is pending? | `journal/backlog/` (QUEUE) |
+| Project-specific overrides | `local/` |
+| Project domain reference (big contracts, IPC tables, confirmed values) | `local/reference/` |
+| Keeping entry files lean | `rules/35-context-economy.md` |
+| Presenting to a human (HTML) | `rules/45-presentation.md` + `commands/present.md` |
+
+Inside any managed folder **or `local/` folder**, read its generated `INDEX.md` (one line per file)
+**before** opening files — that is the per-folder resource map (regenerate with `grimoire index`; CI
+runs `--check`). `grimoire doctor` health-checks the whole wiring (exits non-zero on error, for CI).
+
+### Hot keywords (jump straight to the file)
+
+| Keyword | File |
+|---|---|
+| error code / error catalog | `standards/error-codes.md` |
+| verify command / done | active `stack/<profile>.md` + `rules/30-verification.md` |
+| security / auth / secrets | `rules/50-security.md` |
+| code quality / clean code | `standards/clean-code.md` + `rules/05-code-quality.md` |
+| over-engineering / laziness / minimal code / the ladder / `ponytail:` marker | `standards/clean-code.md` (ladder + guardrail) · ADR `docs/adr/0007-adopt-ponytail-laziness-ladder.md` |
+| launch / privacy gate | `standards/launch-security-checklist.md` + `standards/security-scanners.md` |
+| requirement / spec / REQ-id / change request | `standards/requirements.md` + `codex/requirements/` |
+| test strategy / how to test / coverage | `standards/testing-strategy.md` |
+| release / changelog / version / rollback | `standards/release-versioning.md` |
+| accessibility / a11y / WCAG | `standards/accessibility.md` |
+| incident / runbook / on-call / outage | `codex/runbooks/` |
+| CI / pipeline / workflow | `templates/ci/ci.yml` + `templates/ci/sast.yml` |
+| commit format | `rules/60-commit-style.md` |
+| HOTFIX | `rules/20-modes.md` |
+| codex / knowledge base / provenance | `standards/codex.md` + `codex/INDEX.md` |
+| domain / glossary / context | `codex/domain/` |
+| evidence / investigation / decompile / reverse-engineer / provenance | `codex/evidence/` + `standards/codex.md` |
+| decision / ADR / "why" | `codex/decisions/` |
+| which skill / capability | `skills/catalog.md` |
+| writing / editing a contract doc | `standards/writing.md` |
+| credit / attribution / license / external source / adopt a tool | `standards/attribution.md` |
+| knowledge retrieval / search the codebase / code graph | `graphify` (ADR `docs/adr/0006-delegate-retrieval-to-external-tooling.md`) |
+| structure / architecture / navigator / what does grimoire create / layout / lifecycle | `NAVIGATOR.md` |
+
+## Source priority (when sources conflict)
+
+Trust in this order: **live code + committed docs/specs** (current) > **this base template**
+(`rules/ standards/ stack/`) > **`journal/memory/` cards** (may be stale — verify before acting on one).
+A memory never overrides what the code currently says; treat it as a lead, not as truth.
+
+## Hardest rules (full text in `rules/00-always.md`)
+
+- **Verify before done.** Code you wrote is not done until the verifier returns `pass` on fresh
+  context. The author cannot mark their own work done.
+- **Doc-sync same turn.** Behavior change and its doc/memory update ship in the same turn.
+- **Security first.** No hardcoded roles/secrets; validate + authorize on the server; fail closed.
+- **Effort is not a constraint.** Do not scope-cut to save effort. Spawn parallel subagents instead.
+
+## Customization & precedence
+
+Base (this template) loads first; `local/` loads last and **wins**.
+
+**In a consuming project, never edit the managed base** — `.agents/AGENTS.md`, `rules/`,
+`standards/`, `stack/`, `agents/`, `skills/`, `commands/`, `tooling.json`. `grimoire sync`
+overwrites all of them, so edits there are lost. Put **every** customization under root `local/`
+(it is never synced): **override** a base behavior by restating it in `local/` (it wins), or **add**
+a project-only rule/skill/command/standard under the matching `local/<area>/`. Protocol:
+`local/README.md`.
+
+**Project domain docs** that don't fit the lean `AGENTS.md` (a big runtime contract, confirmed-value
+tables, an IPC catalog) live in `local/reference/` — `grimoire index` generates its `INDEX.md` too.
+Run `grimoire doctor` to verify the wiring (imports, skill frontmatter, INDEX drift, placeholders);
+it exits non-zero on error, for CI.

package/.agents/NAVIGATOR.md

@@ -0,0 +1,168 @@
+# NAVIGATOR — Grimoire structure & components
+
+Canonical reference for **what Grimoire is, what it creates, and what each part does**. Read this to
+get a consistent mental model before touching the CLI, the contract, or the layout. It ships inside the
+contract (`.agents/NAVIGATOR.md`) so every project shares the same map; it complements `README.md`
+(quickstart) and `.agents/AGENTS.md` (the working contract an agent loads each session).
+
+Grimoire is a single, version-controlled **AI-agent operating system** you pull into any repo. One
+command (`grimoire init`) gives a project a complete contract — rules, standards, subagents, skills,
+commands, stack presets, a verification protocol — plus the root folders an agent writes into. Later,
+`grimoire sync` propagates template updates to old projects **without clobbering** their own data.
+
+The CLI (`grimoire`, source `bin/grimoire.mjs` in the template repo) is **zero dependencies**,
+Node ≥18, ESM. The Grimoire repo itself *is* the template and dogfoods this layout
+(`TEMPLATE_ROOT` = repo root, so its own `.agents/` is the template source).
+
+## The one mental model: three lifecycles
+
+Everything Grimoire manages falls into exactly one of three buckets. This split is the whole design.
+
+| Lifecycle | Who owns it | `grimoire sync` | Where it lives |
+|---|---|---|---|
+| **Contract** (read-only) | the base template | **overwrites wholesale** (delete + copy) | `.agents/` |
+| **Project-owned state/knowledge** | the project / the agent | **never touches** | `codex/`, `journal/`, `local/` (repo root) |
+| **Seed sources** | the base template | shipped, copied into new projects | `templates/` |
+
+Rule of thumb: **`.agents/` is 100% read-only.** Nothing an agent or project writes lives under it.
+Anything written goes to a root folder (`codex/`, `journal/`, `local/`). To customize base behavior,
+never edit `.agents/` in a consuming project — restate it in `local/` (loads last, wins).
+
+## Top-level layout (what a Grimoire project contains)
+
+```
+<repo>/
+├─ CLAUDE.md            # thin pointer: imports @.agents/AGENTS.md + @local/AGENTS.local.md
+├─ .agents/             # CONTRACT — read-only, wholesale-synced
+│  ├─ AGENTS.md         #   canonical entry: tone, hardest rules, the map, load order
+│  ├─ rules/            #   always-on working process (numbered 00–60)
+│  ├─ standards/        #   coding standards (general + per-language) + writing/codex
+│  ├─ stack/            #   tech-stack presets (web-app / desktop / library)
+│  ├─ agents/           #   subagents (e.g. the independent verifier)
+│  ├─ skills/           #   reusable workflows (incl. vendored find-skills)
+│  ├─ commands/         #   slash commands (verify, checkpoint, onboard, present, grimoire)
+│  ├─ tooling.json      #   declared plugins / skills / MCP servers
+│  ├─ grimoire.manifest #   documents the contract surface (no longer used for carve-outs)
+│  └─ VERSION           #   template version + source sha (stamped by init/sync)
+├─ codex/               # KNOWLEDGE — project-owned, seeded once, never synced
+│  ├─ INDEX.md  domain/  requirements/  decisions/  evidence/  resources/  reference/  runbooks/
+├─ journal/             # AGENT STATE — project-owned, never synced
+│  ├─ memory/  (+ MEMORY.md)   # KNOWLEDGE: durable facts (tracked)
+│  ├─ backlog/                 # QUEUE: pending work items (tracked)
+│  └─ session/                 # NOW: per-run state (gitignored)
+└─ local/               # OVERRIDE CONFIG — project-owned, never synced, loads LAST and wins
+   ├─ AGENTS.local.md   #   profile (stack, testing policy), project facts, override declarations
+   ├─ README.md  rules/  standards/  stack/  skills/  commands/  reference/
+   └─ tooling.json      #   project-only plugins / MCP (merged additively by bootstrap)
+```
+
+### The contract — `.agents/` (read-only)
+
+| Path | Holds |
+|---|---|
+| `AGENTS.md` | entry contract + load-order + the map + hot-keywords |
+| `rules/` | always-on process: 00-always, verification, modes, handoff, context-economy, commit-style, … |
+| `standards/` | coding standards (general + per-language), writing, codex, knowledge-management |
+| `stack/` | per-profile defaults (framework / lint / test / verify command) |
+| `agents/` | subagent definitions — notably `verifier` (independent done-check) |
+| `skills/` | re-runnable workflows; `find-skills` is vendored + mirrored to `.claude/skills/` |
+| `commands/` | slash commands |
+| `tooling.json` | source of truth for required plugins / skills / MCP |
+| `grimoire.manifest` | lists the managed paths — documentation only (sync is wholesale) |
+
+### Project-owned roots (never synced)
+
+- **`codex/`** — the project's knowledge base; read-first for any domain/feature work (start at
+  `codex/INDEX.md`). Holds `domain/`, `requirements/`, `decisions/` (ADRs), `evidence/`, `resources/`,
+  `reference/`, `runbooks/`. Seeded once from `templates/codex/`.
+- **`journal/`** — the agent's working state, the "3 homes":
+  - `journal/session/` = **NOW** (current run; gitignored),
+  - `journal/memory/` = **KNOWLEDGE** (durable facts + `MEMORY.md` index; tracked),
+  - `journal/backlog/` = **QUEUE** (pending work; tracked).
+- **`local/`** — the project's customization layer. Loads **last and wins**. Override a base rule by
+  restating it here; add project-only rules/skills/commands/standards under the matching `local/<area>/`.
+
+## What each CLI command creates / does
+
+`grimoire <command> [--dir <path>]` (default dir = cwd).
+
+### `init` — scaffold a project
+1. **Auto-migrate** an old-layout project first (`migrateLegacyLayout`, see below).
+2. **Wholesale-copy** the template `.agents/` into the project (`copyAgentsWholesale`).
+3. Stamp `VERSION` (template version + git sha).
+4. Write `CLAUDE.md` pointer (if absent).
+5. Ensure `.gitignore` has the session/backup ignore snippet.
+6. **Seed root folders** (only if absent / per-file gap-fill, never overwriting):
+   `seedCodex` → `codex/`; `seedRoot("journal")` → `journal/`; `seedRoot("local")` → `local/`.
+7. Mirror discoverable skills into `.claude/skills/` (`find-skills` + every `local/skills/<x>`).
+8. Generate per-folder `INDEX.md` (after all mutations).
+9. Run `bootstrap` in dry-run (prints the plugin/MCP plan; writes nothing).
+
+### `sync` — pull template updates into an existing project
+1. Fail if no `.agents/` (must `init` first).
+2. **Auto-migrate** an old layout (once, with backup).
+3. **Wholesale-replace** `.agents/` from the template (delete + copy) — your contract is refreshed.
+4. Re-stamp `VERSION`; re-seed `codex/`/`journal/`/`local/` (gap-fill only, never clobbers your files);
+   re-mirror skills; regenerate `INDEX.md`.
+   **`codex/`, `journal/`, `local/` are never overwritten** — only missing files are filled in.
+
+### `bootstrap` — wire plugins / MCP / skills
+Reads base `tooling.json` ∪ `local/tooling.json` (base wins on key conflict; local adds new keys).
+- Dry-run (default): prints missing plugins, MCP servers to ensure, and skill install hints.
+- `--apply`: enables missing plugins in `~/.claude/settings.json` (backs it up first, only **adds**,
+  never disables), and merges MCP servers into `.mcp.json` (never clobbers an existing server). Flags
+  unresolved `${ENV}` placeholders.
+
+### `index` — regenerate per-folder `INDEX.md`
+One-line-per-file table built from each file's frontmatter `description:` or its H1 + first sentence.
+Two groups: the contract (`.agents/<folder>`) and the override layer (`local/<folder>`).
+`index --check` is the CI drift gate: fails if any `INDEX.md` is stale, or a `tooling.json` MCP isn't
+documented in `skills/catalog.md`. Newline-agnostic (tolerates CRLF checkouts).
+
+### `doctor` — health-check the wiring (CI-friendly, exits non-zero on error)
+Checks: `CLAUDE.md` imports `@.agents/AGENTS.md` (error) and `@local/AGENTS.local.md` (warn); mirrored
+skills have `name:`+`description:`; INDEX/catalog drift; `local/AGENTS.local.md` stack-profile +
+testing-policy filled; entry files ≤300 lines; `codex/INDEX.md` scaffolded; `local/tooling.json` valid.
+
+## Seed-source map (`templates/` → project root)
+
+`init`/`sync` seed project-owned roots from `templates/`. Source and destination are separate so this
+repo's own live state never doubles as the seed.
+
+| Seed source | Seeds into | How |
+|---|---|---|
+| `templates/codex/` | `codex/` | `seedCodex` — dir-level **seed-once** (skips if `codex/` exists) |
+| `templates/journal/` | `journal/` | `seedRoot` — **per-file gap-fill** (fills missing files only) |
+| `templates/local/` | `local/` | `seedRoot` — **per-file gap-fill** |
+| `templates/CLAUDE.md` | `CLAUDE.md` | copied once (if absent) |
+| `templates/gitignore-snippet.txt` | `.gitignore` | appended once (`journal/session/`, `.agents.bak-*/`) |
+
+## Migration (old layout → new)
+
+Older projects kept agent state under `.agents/{memory,backlog,session,local}`. On the next
+`init`/`sync`, `migrateLegacyLayout` runs once: it backs up the whole `.agents/` to
+`.agents.bak-<stamp>/`, then **moves** each legacy dir to its root home —
+`.agents/memory→journal/memory`, `…/backlog→journal/backlog`, `…/session→journal/session`,
+`…/local→local/` — **only if the destination is absent** (a conflict leaves the legacy copy in the
+backup, never overwriting a newer root copy). Idempotent: a no-op once the legacy dirs are gone.
+
+## How an agent reads a Grimoire project (load order)
+
+1. `CLAUDE.md` → imports `@.agents/AGENTS.md` (contract) + `@local/AGENTS.local.md` (overrides).
+2. `.agents/AGENTS.md` — hardest rules + the map; **read first, don't read everything**.
+3. `.agents/rules/00-always.md` — every session.
+4. `codex/INDEX.md` — read-first for any domain/feature work.
+5. `standards/` + `stack/` — when writing/scaffolding code.
+6. `local/` — loads **last and wins**.
+
+Inside any folder, read its generated `INDEX.md` before opening files (two-level progressive
+disclosure: map → INDEX → file), keeping context lean.
+
+## Invariants (don't break these)
+
+- **Zero runtime dependencies** in `bin/grimoire.mjs` (Node stdlib only).
+- **`.agents/` is read-only** and wholesale-replaced by `sync` — never store project data there.
+- **`codex/`, `journal/`, `local/` are never synced** — safe homes for project-owned content.
+- **`local/` wins** on any conflict (loads last).
+- Behavior change ships with its doc/INDEX update in the **same change** (doc-sync).
+- Code an agent wrote is not done until the independent **verifier** returns `pass`.

package/.agents/VERSION

@@ -0,0 +1,4 @@
+grimoire v0.3.2
+source: this repository IS the template (canonical source of truth)
+note: informational only — package.json `version` is the single source of truth;
+      `grimoire init` / `grimoire sync` regenerate this from it and stamp the build sha.

package/.agents/agents/INDEX.md

@@ -0,0 +1,7 @@
+# agents — index
+
+<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
+
+| File | What it covers |
+|---|---|
+| `verifier.md` | Independent verification reviewer. |

package/.agents/agents/verifier.md

@@ -0,0 +1,50 @@
+---
+name: verifier
+description: Independent verification reviewer. Spawn AFTER a change is complete to confirm Definition of Done on fresh context. Receives only requirements + diff + checklist — never the implementer's reasoning. Refutes by default; runs the real verify commands and quotes real output.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the **independent verifier**. You did not write this code. Your job is to **refute** the
+claim that it is done — not to praise it. Default to **FAIL** when uncertain.
+
+## You receive (and ONLY this)
+
+- The requirements / acceptance criteria.
+- The diff (or the changed files).
+- The checklist (Definition of Done items).
+
+You do **not** get the implementer's reasoning or conversation. If context is missing, say so and
+FAIL — do not assume.
+
+## What you must do
+
+1. **Run the real `verify` command** for this project (`npm run verify`, or the profile's command
+   in `stack/`). If there is no verify script, run typecheck + lint + tests directly.
+2. **Quote the actual output.** Real command, real exit code, real failing/passing counts. Never
+   write "looks good", "should pass", or paraphrase results.
+3. Check the diff against **each requirement** and **each checklist item** explicitly.
+4. Look for: untested branches, security regressions (`rules/50-security.md`), hardcoded
+   roles/secrets, swallowed errors, missing doc/memory sync, scope the diff does NOT cover.
+5. **Code-quality rubric.** Load the "Review checklist" in `standards/clean-code.md` and refute the
+   diff against it (limits, readability, function design, type-safety, performance, suppression, dead
+   code). A violation without a recorded justification is a `fail`.
+6. **Scope & contract.** Output meets the task's stated acceptance criteria and nothing out-of-scope
+   crept in (`rules/10` task contract; `rules/25` surgical). Flag any addition the request did not call for.
+
+## Output (structured verdict)
+
+```
+VERDICT: pass | fail
+COMMANDS RUN:
+  <command> -> exit <code>
+  <quoted output, trimmed to the relevant lines>
+REQUIREMENTS:
+  - <req>: met | NOT met — <evidence>
+CHECKLIST:
+  - <item>: done | NOT done
+REASONS (if fail):
+  - <specific, actionable>
+```
+
+Definition of Done = tests green **AND** `VERDICT: pass` **AND** every checklist item done. If any
+one is missing, the verdict is `fail`. Save this verdict as the artifact the main thread cites.

package/.agents/commands/INDEX.md

@@ -0,0 +1,11 @@
+# commands — index
+
+<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
+
+| File | What it covers |
+|---|---|
+| `checkpoint.md` | Snapshot the NOW whiteboard before a context boundary. |
+| `grimoire.md` | Run grimoire init or sync from inside Claude Code. |
+| `onboard.md` | Onboard an existing (pre-Grimoire) repo onto the template without losing its custom contract. |
+| `present.md` | Render the current spec / review / report / prototype / editing UI as a self-contained HTML artifact and return a file:// URL. |
+| `verify.md` | Run the verify script and dispatch the verifier subagent for independent sign-off. |

package/.agents/commands/checkpoint.md

@@ -0,0 +1,15 @@
+---
+description: Snapshot the NOW whiteboard before a context boundary.
+---
+
+Checkpoint the current session state (`rules` §6 — NOW layer).
+
+Steps:
+
+1. Ensure `journal/session/current.md` reflects the live state: mode, focus, last-done, next-step,
+   blockers, open-questions, files-touched. Rewrite it in place if stale.
+2. Copy it to `journal/session/archive/<timestamp>.md` (timestamp = `YYYY-MM-DD-HHmm`).
+3. Confirm the snapshot path back to the user.
+
+A checkpoint is **not a new file type** — it is a timestamped copy of `current.md`. Resume always
+reads `current.md`; archives are for recovery only.

package/.agents/commands/grimoire.md

@@ -0,0 +1,14 @@
+---
+description: Run grimoire init or sync from inside Claude Code.
+---
+
+Wrap the Grimoire CLI (`bin/grimoire.mjs`).
+
+- **init** — scaffold `.agents/` + pointers into a new project. Run:
+  `npx github:nuttchanon/the-grimoire init` (or `node bin/grimoire.mjs init` when developing the template).
+- **sync** — pull the latest template into an existing project. Overwrites **managed paths only**
+  (`.agents/grimoire.manifest`); never touches `codex/ journal/ local/`. Run:
+  `npx github:nuttchanon/the-grimoire sync`.
+
+After `sync`, print the changelog (git log between the old and new template sha) and bump
+`.agents/VERSION`. Confirm with the user before running `sync` if there are uncommitted changes.

package/.agents/commands/onboard.md

@@ -0,0 +1,56 @@
+---
+description: Onboard an existing (pre-Grimoire) repo onto the template without losing its custom contract.
+---
+
+# onboard — adopt Grimoire in an existing repo
+
+Use this when a repo already has its own agent contract (a hand-rolled `.agents/`, a long `CLAUDE.md`,
+ad-hoc rules) and you want it on the managed template. `init` lays the base and **backs up** an
+existing `.agents/` to `.agents.bak-<timestamp>/`; this playbook moves the project's signal into
+`local/` so nothing is lost and `grimoire sync` stays conflict-free. Work on a branch.
+
+## Steps
+
+1. **Branch + survey.** `git checkout -b chore/grimoire-onboard`. Read the existing `.agents/` (every
+   rule), `CLAUDE.md`, and any existing ADR/requirements layout (e.g. `docs/adr/`, `docs/requirements/`).
+   Note what is project-specific (domain, stack, security model, env gotchas) vs generic (it'll be
+   replaced by the base).
+
+2. **Run init.** `npx github:nuttchanon/the-grimoire init`. If an `.agents/` was present it is now
+   safe in `.agents.bak-<timestamp>/`; the managed base + `local/` skeleton are in place. `init` also
+   seeds a single project-owned `codex/` tree at the repo root (decisions, requirements, runbooks,
+   domain, evidence, …) via `seedCodex` — seed-once, only when `codex/` is absent, and never touched
+   by `grimoire sync`.
+
+3. **Move custom rules → `local/rules/`.** For each project rule worth keeping, recreate it under
+   `local/rules/` with a **`local-` prefix** (avoids number collisions with the base — see
+   `local/README.md`). Carry the content verbatim; add a frontmatter `description:`.
+
+4. **Move CLAUDE.md context → `local/AGENTS.local.md` (+ big docs → `local/reference/`).** Set the
+   profile (stack, testing policy, verify command). Move the system model, doc map, domain pointers,
+   access/auth model, and env/build gotchas into **Project facts**; park large domain contracts (IPC
+   tables, confirmed values) in `local/reference/`. Record any base behaviour you're overriding under
+   **Override declarations**.
+
+5. **Slim CLAUDE.md to a pointer.** Reduce it to the Grimoire imports
+   (`@.agents/AGENTS.md` + `@local/AGENTS.local.md`) plus one line of orientation.
+
+6. **Migrate ADRs/requirements into `codex/`.** If the repo already had `docs/adr/` (or
+   `docs/requirements/`, or another ADR layout), move those decisions into `codex/decisions/` and
+   requirements into `codex/requirements/`, then remove the old trees. `seedCodex` only scaffolds
+   `codex/` when it is absent, so it won't clobber a `codex/` you populate. Note any non-default
+   location in **Override declarations**.
+
+7. **Move bespoke paths to the repo root.** `.agents/` is now a fully read-only contract — `sync`
+   wholesale-replaces it, so nothing project-owned can live under it. Any bespoke project dirs (e.g.
+   `field-reports/`, `handoff/`) belong at the repo root, alongside `codex/`, `journal/`, and `local/`.
+
+8. **Verify + clean up.** `grimoire index` (regen INDEX.md), `grimoire doctor` (check wiring), run the
+   project's verify command, confirm the contract loads. Delete the `.agents.bak-*` backup once
+   everything is migrated. Commit; open a PR.
+
+## Done when
+
+The `.agents.bak-*` backup is gone · every kept project rule lives under `local/rules/` (prefixed) ·
+`CLAUDE.md` is a thin pointer · `grimoire index --check` + `grimoire doctor` are clean · decisions and
+requirements live under `codex/` with no leftover `docs/adr/` (or `docs/requirements/`) tree.

package/.agents/commands/present.md

@@ -0,0 +1,23 @@
+---
+description: Render the current spec / review / report / prototype / editing UI as a self-contained HTML artifact and return a file:// URL.
+---
+
+Turn a human-facing deliverable into an interactive HTML page a person will actually read — not a
+long Markdown wall they skim. Use for a spec comparison, code-review dashboard, report/explainer,
+design prototype, or a custom editing UI (see `skills/catalog.md` -> Presentation).
+
+Honor presentation mode (`rules/45-presentation.md`): render HTML only when the mode is on for this
+project (`local/AGENTS.local.md`) or the user asks; otherwise stay in Markdown.
+
+Steps:
+
+1. Keep the **source canonical** — the Markdown/spec stays the source of truth; the HTML is a *view*
+   generated from it.
+2. Build ONE self-contained `.html`: inline CSS + JS, **no external/remote `<script>` or CDN**, works
+   offline via `file://`. **Escape** any code/diff/user text you embed (no raw injection).
+3. Write it to `journal/session/artifacts/<YYYY-MM-DD-HHmm>-<slug>.html` (ephemeral, gitignored).
+4. Return the absolute `file://` path so the user can open it in a browser.
+5. For editing UIs, include a **"copy as JSON / copy as Markdown"** button so the user can export
+   their changes back into the conversation (close the loop).
+
+Token-aware: render HTML for deliverables that earn it, not routine replies.

package/.agents/commands/verify.md

@@ -0,0 +1,20 @@
+---
+description: Run the verify script and dispatch the verifier subagent for independent sign-off.
+---
+
+Verify the current change to Definition-of-Done standard (`rules/30-verification.md`).
+
+Steps:
+
+1. Identify the `verify` command for this project (package script `verify`, or the active
+   `stack/` profile's command). If none exists, fall back to typecheck + lint + tests.
+2. Run it. Capture real output and exit code.
+3. Spawn the **verifier** subagent (Task/Agent tool) on **fresh context**, passing ONLY:
+   - the requirements / acceptance criteria for this change,
+   - the diff (`git diff` of the change),
+   - the Definition-of-Done checklist.
+   Do **not** pass your own reasoning or this conversation.
+4. Relay the verifier's structured verdict. If `fail`, the change is **not done** — address the
+   reasons and re-run. Do not declare done without a `pass` artifact.
+
+For large or risky changes, also run `/code-review` (or `/code-review ultra`).

package/.agents/grimoire.manifest

@@ -0,0 +1,18 @@
+# Managed contract surface — everything under `.agents/` is read-only and OVERWRITTEN by
+# `grimoire sync` (wholesale replace). This file documents the contract; sync no longer needs
+# it to compute carve-outs. One path (file or dir) per line, relative to .agents/.
+
+AGENTS.md
+NAVIGATOR.md
+rules/
+standards/
+stack/
+agents/
+skills/
+commands/
+tooling.json
+
+# Project-owned, NEVER synced — live at the repo ROOT, outside .agents/ (listed for clarity):
+#   codex/    — knowledge base (domain, requirements, decisions, evidence, runbooks)
+#   journal/  — agent working state (memory/, backlog/, session/)
+#   local/    — project override config (loads last, wins)

package/.agents/rules/00-always.md

@@ -0,0 +1,42 @@
+---
+updated: 2026-05-31
+description: The non-negotiable rules; violating any is a hard error, not a style nit. Read every session.
+---
+
+# 00 — Always (hard errors)
+
+Always-on. Violating any of these is a hard error, not a style nit.
+
+- **Verify before done.** Code is not done until the independent verifier (`30-verification.md`)
+  returns `pass` on **fresh context**. The author of a change cannot mark it done — bias comes from
+  shared context. Definition of Done = tests green **AND** verifier `pass` **AND** checklist complete.
+  For **user-facing, data-collecting** apps, the launch-security checklist
+  (`standards/launch-security-checklist.md`) is part of Done, not a later pass.
+- **Read the knowledge base first.** Before domain/feature work, read `codex/INDEX.md` — the
+  project's source-of-truth knowledge base (domain, requirements, decisions, evidence). Don't start
+  blind.
+- **Doc-sync same turn.** Any behavior/interface change updates its doc and `journal/memory/` in the **same
+  turn** as the code. No "I'll document later".
+- **Security first.** Never hardcode roles, permissions, secrets, or hostnames. Validate and
+  authorize on the server. Fail **closed**. (Detail: `50-security.md`.)
+- **No hardcoded roles.** Gate behavior through helpers/config, never string literals like
+  `if (user.role === "admin")`.
+- **Effort is not a constraint.** Never reduce scope, skip tests, or pick the lazy design to save
+  effort. If the work is large, **spawn parallel subagents** — do not cut corners.
+- **No silent test gaps.** Shipping a unit of work without a test suite is a *recorded decision*, not
+  a silent omission: write an ADR (`codex/decisions/`) stating why (spike/throwaway, external constraint) and
+  when tests get backfilled. A missing test suite with no ADR is a defect.
+- **Confirmed values change with their ADR.** When a decision alters ground-truth values the code
+  reads back (IPC channels, error codes, permission keys, tenant configs, shared enums), the ADR sets
+  `updates-confirmed-values: yes` and the same PR updates the project's confirmed-values table.
+- **Small increments.** One coherent change at a time; keep the diff reviewable. (Detail: `10-working-process.md`.)
+- **Surgical changes.** Every changed line traces to the request; don't touch adjacent code you were
+  not asked to. (Detail: `25-surgical-changes.md`.)
+- **Never edit the managed base; customize in `local/`.** In a consuming project, the base
+  (`.agents/AGENTS.md`, `rules/`, `standards/`, `stack/`, `agents/`, `skills/`, `commands/`,
+  `tooling.json`) is overwritten by `grimoire sync`. Put every project change under root `local/`
+  (never synced) — it loads last and wins. Protocol: `local/README.md`.
+- **State your assumptions; don't pick silently.** If a requirement is ambiguous, name what is
+  confusing and present the interpretations — do not choose one quietly. Ask when the wrong guess is
+  expensive; otherwise pick the obvious default and say so. Push back when a simpler or better
+  approach exists.

package/.agents/rules/05-code-quality.md

@@ -0,0 +1,28 @@
+---
+updated: 2026-05-31
+description: Always-on code-quality essentials; the full standard lives in standards/clean-code.md.
+---
+
+# 05 — Code quality (standards overview)
+
+- **Small files.** Split when a file grows past its single responsibility. Prefer many small,
+  named modules over one large one.
+- **Minimal comments — why, not what.** Code says *what*; comments explain *why* only when
+  non-obvious. Delete comments that restate the code.
+- **DRY, but not prematurely.** Extract on the *third* repetition, not the first.
+- **YAGNI — climb the ladder.** Before writing, stop at the first rung that holds: skip it → stdlib →
+  native platform → existing dependency → one line → only then minimal code. No speculative
+  abstraction, config, or hooks; no error handling for impossible scenarios. Mark a deliberate
+  shortcut with `// ponytail: <ceiling>, <upgrade path>`. Full ladder + the "never simplify away"
+  guardrail: `standards/clean-code.md`.
+- **Simplicity first.** Minimum code that solves the problem. If 200 lines could be 50, rewrite.
+  Sanity check: would a senior engineer call this overcomplicated? If yes, simplify.
+- **Naming mirrors the domain.** Names come from the problem domain, not the implementation.
+  Match the surrounding code's idiom, casing, and comment density.
+
+- **No silent suppression.** `eslint-disable` / `@ts-ignore` / `any` need an inline comment naming
+  the constraint + a follow-up. Greening CI by disabling a rule without a replacement guard is
+  tracked tech debt (ADR if structural).
+
+Full standard: `standards/clean-code.md` (limits, type-safety, performance, suppression) +
+`standards/general.md` + the per-language file.

package/.agents/rules/10-working-process.md

@@ -0,0 +1,31 @@
+---
+updated: 2026-05-31
+description: 'How to work a task end to end: plan, task contract, right altitude, small increments, tools, TDD.'
+---
+
+# 10 — Working process
+
+- **Plan before code.** For anything beyond a trivial edit, state the plan (files, approach,
+  test strategy) before touching code. For large/ambiguous work, get a thumbs-up first.
+- **Goal-driven.** Turn the task into a verifiable goal before starting: "fix the bug" → "write a
+  test that reproduces it, then make it pass". Strong success criteria let you loop to done without
+  re-asking; weak ones ("make it work") force constant clarification.
+- **Task contract.** Before non-trivial code, state the contract: the verifiable **goal**, explicit
+  **acceptance criteria**, and what is **out of scope**. The verifier checks output against it — "done"
+  means the criteria are met and nothing out-of-scope crept in.
+- **Right altitude.** Match effort and abstraction to the ask. Do the full *right* thing for the
+  actual request — neither gold-plate (speculative abstraction; YAGNI, `rules/05`) nor scope-cut to
+  save effort (`rules/00`). When the right altitude is unclear, state your read and proceed.
+- **Ask before large work.** Multi-session, schema-changing, or architecture-shifting work →
+  route to **BACKLOG** (`40-handoff.md`) and confirm scope before starting.
+- **Small increments.** Land coherent, reviewable slices. Vertical (tracer-bullet) over horizontal.
+- **Use the tools.** When a skill or command fits the task, use it instead of improvising.
+- **Adapt external guidance.** When applying an article, talk, or vendor doc, extract the principle and fit it to this stack and domain. Vendor names and examples in the source are illustrations, not mandates — keep the core tool-agnostic.
+- **Update NOW.** Keep `journal/session/current.md` reflecting the live state (focus / last-done /
+  next-step / blockers). Rewrite in place; do not append.
+- **Session hygiene.** Batch related asks into one well-planned request — every prompt reloads the
+  always-on context, so one-shotting beats drip-feeding. Finish a task, then compact or clear:
+  continuity lives in the three homes (`standards/knowledge-management.md`), not in chat history.
+  For work-in-progress, capture state via `journal/session/current.md` or the `handoff` skill before clearing.
+- **TDD per stack policy.** Follow the active profile's testing policy
+  (`tdd-mandatory` | `test-ready-deferred` | `none`) — see `stack/`.