the-grimoire-cli 0.3.2

package/templates/ci/ci.yml

@@ -0,0 +1,49 @@
+# CI — lint, typecheck, test, build. Copy to .github/workflows/ci.yml.
+# This is the correctness gate; security scanning lives in the sibling sast.yml.
+# Commands here must match the active stack profile's `verify` (.agents/stack/<profile>.md) —
+# keep them in sync so local `verify` and CI run the same checks.
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm           # change to pnpm/yarn to match the project
+
+      - run: npm ci
+
+      # --- The four gates. Drop any line a profile doesn't have; order is cheapest-first. ---
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npx tsc --noEmit
+
+      - name: Test
+        run: npm test          # node --test / vitest / jest per profile
+
+      - name: Build
+        run: npm run build
+
+      # --- Contract guard: agent docs/index must not drift (.agents/) ---
+      - name: Grimoire index check
+        run: npx github:nuttchanon/the-grimoire index --check
+        # Remove this step if the project does not vendor Grimoire's INDEX.md generation.
+
+# Per stack profile (.agents/stack/):
+#   web-app  : lint + typecheck + test (vitest) + build (next build). Add the e2e job when present.
+#   desktop  : lint + typecheck + test + build (electron-builder --dir for PR; full pack on release).
+#   library  : lint + typecheck + test + build (tsup/unbuild) + a changesets status check on PRs.
+# Accessibility: add an axe/Lighthouse job for user-facing apps (.agents/standards/accessibility.md).

package/templates/ci/sast.yml

@@ -0,0 +1,44 @@
+# SAST — static application security testing. Copy to .github/workflows/sast.yml.
+# Linters find what is ugly; SAST finds what is exploitable (SQLi, XSS, RCE, secrets, weak crypto).
+# Fail the build on High/Critical. Scanner choice is per stack profile — see notes at the bottom.
+name: sast
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+  security-events: write   # for SARIF upload to GitHub code scanning
+
+jobs:
+  semgrep:
+    # Pattern-based, 30+ languages. Default for every profile.
+    runs-on: ubuntu-latest
+    container: { image: semgrep/semgrep }
+    steps:
+      - uses: actions/checkout@v4
+      - run: semgrep ci --config auto --error
+        env:
+          # Optional: set SEMGREP_APP_TOKEN to use org rules + the Semgrep dashboard.
+          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+
+  njsscan:
+    # JS / Node / React / React Native / Electron. Drop this job for non-JS profiles.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install njsscan
+      - run: njsscan --exit-on-warn .
+
+# Per stack profile (standards/security-scanners.md):
+#   web-app  (Next.js)   : semgrep + njsscan here, AND enable CodeQL code scanning (js/ts).
+#   desktop  (Electron)  : semgrep + njsscan here (njsscan flags Electron sinks), AND CodeQL.
+#   library              : semgrep here; add the language's native scanner (bandit/gosec/…) if not JS/TS.
+#   any Python service   : add a bandit job (pip install bandit; bandit -r src -ll).
+#
+# CodeQL is configured separately — GitHub → Security → Code scanning → enable default setup,
+# or add github/codeql-action via its own workflow. It is free for public repos.

package/templates/codex/INDEX.md

@@ -0,0 +1,18 @@
+# codex — index (read this first)
+
+The project's **knowledge / resource root**. Read this signpost before touching any domain reference,
+then open the matching subfolder's own `INDEX.md`. Project-owned: `grimoire sync` never touches
+`codex/`; the base holds only a pointer to it. Every folder below keeps its own `INDEX.md`.
+
+| Folder | What it holds |
+|---|---|
+| `domain/` | What the system **is** — glossary, context, business rules, capabilities. |
+| `requirements/` | What it must **do** — IDed, versioned base + addons + change requests. |
+| `decisions/` | **Why** it is built this way — ADRs (one file per decision). |
+| `evidence/` | Investigation / reverse-engineering / extraction outputs, each fact sourced. |
+| `resources/` | Raw materials — datasets, vendor specs, dumps, external artifacts/snapshots. |
+| `reference/` | Confirmed-value tables, API/IPC catalogs, big contracts the code reads back. |
+| `runbooks/` | The on-call answer to "production is broken — what now." |
+
+Protocol: `.agents/standards/codex.md`. The structure is **extensible** — add a folder when a new
+kind of knowledge appears; give it an `INDEX.md` and list it here.

package/templates/codex/README.md

@@ -0,0 +1,28 @@
+# codex
+
+The project's **knowledge and resource root**, at the repo root (not under `.agents/`). It is the
+rebuild's source of truth: what the system is, what it must do, why it's built that way, and the raw
+materials and evidence behind those claims. Project-owned — `grimoire sync` never touches it; the
+base contract only points here. Full protocol: `.agents/standards/codex.md`.
+
+## Read-first rule
+
+Any domain reference starts at `codex/INDEX.md`, then the relevant subfolder's `INDEX.md`. New work
+reads the matching INDEX **before** acting — don't start a task blind to recorded knowledge.
+
+## Provenance discipline
+
+Every recorded fact cites its **source** (file + offset/record) and a **CONFIRMED | INFERRED** tag.
+Unsupported claims are removed or demoted to "not recovered" — no unsourced guesses. Pre-existing
+docs are not trusted until audited to this standard (carry `audited: <date>`).
+
+## How to add a folder
+
+codex is extensible. When a new kind of knowledge appears, add a folder, give it an `INDEX.md`
+(signpost table) and a short `README.md`, and list it in the master `codex/INDEX.md`. Keep every
+file lean (context economy).
+
+## Secrets
+
+Real secrets / PHI never go in tracked knowledge docs — see `resources/README.md` and
+`.agents/standards/codex.md`. The chat is the leak boundary: never echo a secret or PHI into output.

package/templates/codex/decisions/0000-template.md

@@ -0,0 +1,36 @@
+---
+id: 0000
+title: <short decision title>
+status: proposed        # proposed | accepted | superseded | deprecated
+date: <YYYY-MM-DD>
+updates-confirmed-values: no   # yes | no — see "Confirmed values" below
+supersedes:             # ADR id(s) this replaces, if any
+---
+
+# ADR 0000 — <short decision title>
+
+## Context
+
+What forces this decision? The problem, constraints, and the options actually on the table. Keep it
+factual — no solution yet.
+
+## Decision
+
+The choice, stated as one sentence in active voice ("We will …"). Then the *why* in a few lines.
+
+## Consequences
+
+What becomes easier, what becomes harder, what we now owe (migrations, follow-ups, risks).
+
+## Confirmed values
+
+> Set `updates-confirmed-values: yes` in the frontmatter **only if this decision changes a value the
+> code treats as ground truth** — an IPC channel name, an error code, a permission key, a hospital/
+> tenant config, an enum the UI and server both depend on.
+
+If `yes`: list each value below **and** update the project's confirmed-values table
+(`codex/reference/`) in the same PR (the PR checklist enforces this). If `no`, delete this section.
+
+| Value | Old | New | Where it lives |
+|---|---|---|---|
+| | | | |

package/templates/codex/decisions/INDEX.md

@@ -0,0 +1,11 @@
+# decisions — index
+
+**Why** the system is built the way it is: Architecture Decision Records, one file per decision.
+Requirements say *what*; decisions say *how* and *why*.
+
+| Entry | What it holds |
+|---|---|
+| `README.md` | When to write an ADR, the `updates-confirmed-values` field, the status lifecycle. |
+| `0000-template.md` | Copy this for each new decision: `NNNN-kebab-title.md`. |
+
+<!-- ADRs accumulate here as NNNN-kebab-title.md; number sequentially, never renumber. -->

package/templates/codex/decisions/README.md

@@ -0,0 +1,25 @@
+# Architecture Decision Records
+
+One file per decision: `codex/decisions/NNNN-kebab-title.md`, copied from `0000-template.md`. ADRs are
+**project-owned** — `grimoire sync` never touches this folder. Number sequentially; never renumber.
+
+## When to write one
+
+- A choice with lasting consequences (framework, data model, auth model, module boundaries).
+- A trade-off a future reader would otherwise relitigate.
+- **No test suite for a unit of work.** Absence of tests is a *recorded decision*, not a silent
+  omission: open an ADR stating why (spike/throwaway, external constraint) and the conditions under
+  which tests get backfilled. A missing test suite with no ADR is a defect.
+
+## The `updates-confirmed-values` field
+
+Some values are **ground truth** the code reads back — IPC channel names, error codes, permission
+keys, tenant/hospital configs, shared enums. When an ADR changes one of these, set
+`updates-confirmed-values: yes` and, **in the same PR**, update the project's confirmed-values table
+(`codex/reference/`). The PR checklist must verify the table was updated; a `yes` ADR without a
+matching table change does not merge.
+
+## Status lifecycle
+
+`proposed` → `accepted` (merged) → later `superseded` (point the new ADR's `supersedes:` at it) or
+`deprecated`. Never delete an accepted ADR; supersede it so the history stays legible.

package/templates/codex/domain/INDEX.md

@@ -0,0 +1,14 @@
+# domain — index
+
+What the system **is**: the shared language and rules that everything else cites. Read before
+writing requirements or code in an unfamiliar area.
+
+| Entry | What it holds |
+|---|---|
+| `README.md` | What belongs in `domain/` and how to keep it sourced. |
+| `glossary.md` | Domain terms → precise definitions (add as the language stabilizes). |
+| `context.md` | The business/system context: actors, boundaries, why the system exists. |
+| `business-rules.md` | The rules the system must enforce, each cited to its source. |
+| `capabilities.md` | What the system can do, at the capability (not requirement) level. |
+
+<!-- Seed these files as the domain takes shape; delete rows you don't use yet. -->

package/templates/codex/domain/README.md

@@ -0,0 +1,10 @@
+# domain
+
+What the system **is** — the shared vocabulary and the business rules that requirements, decisions,
+and code all refer back to. This is where you fix the language so two people (or agents) mean the
+same thing by the same word. Glossary, business/system context, enforced business rules, and the
+high-level capability map live here.
+
+Hold to the codex provenance discipline: each rule or definition that comes from a source artifact
+cites it (file + offset, `CONFIRMED | INFERRED`). A definition you invented for convenience is
+`INFERRED` until confirmed. See `.agents/standards/codex.md`.

package/templates/codex/evidence/0000-extraction-template.md

@@ -0,0 +1,36 @@
+---
+id: 0000
+title: <what was extracted / investigated>
+status: draft           # draft | reviewed
+date: <YYYY-MM-DD>
+audited: <YYYY-MM-DD>   # date this doc was checked to the provenance standard
+---
+
+# Extraction 0000 — <what was extracted / investigated>
+
+## Source artifact
+
+What you investigated: file path / binary / dump / vendor doc, version or hash if known. One artifact
+per doc where possible.
+
+## Method / tool
+
+How you extracted it — the tool, command, decompiler, query, or manual read. Enough that someone
+could repeat it and get the same result.
+
+## Findings
+
+| item | source (file + offset/record) | CONFIRMED \| INFERRED | purpose |
+|---|---|---|---|
+| <value / rule / field> | `<file>:<offset>` or `<table>:<row>` | CONFIRMED | <what it's for> |
+
+## Not recovered
+
+What you looked for and could **not** establish, and why (encrypted, stripped, absent). This bounds
+the claim — don't let a gap pass as settled.
+
+## Security / redaction note
+
+Confirm no real secret / PHI is recorded above. If the artifact contained any, record only its
+**location + purpose** here for rotate/revoke; the value goes in the gitignored inventory
+(`resources/`), never in this tracked doc.

package/templates/codex/evidence/INDEX.md

@@ -0,0 +1,11 @@
+# evidence — index
+
+Outputs of investigation, reverse-engineering, and extraction — the raw findings that feed `domain/`,
+`reference/`, and `requirements/`. Every fact here is sourced.
+
+| Entry | What it holds |
+|---|---|
+| `README.md` | The provenance discipline, in brief; points to `.agents/standards/codex.md`. |
+| `0000-extraction-template.md` | Copy for each extraction run: source, method, sourced findings table. |
+
+<!-- Extraction docs accumulate here as NNNN-<slug>.md. -->

package/templates/codex/evidence/README.md

@@ -0,0 +1,15 @@
+# evidence
+
+Where investigation lands: reverse-engineering a legacy binary, extracting values from a vendor spec,
+reading a database dump, recovering a protocol. These docs are the **paper trail** behind every
+confirmed fact in `domain/`, `reference/`, and `requirements/`.
+
+## Provenance discipline (in brief)
+
+- Every finding cites its **source** — file + offset/record — and a **CONFIRMED | INFERRED** tag.
+- What you couldn't recover is listed explicitly under "Not recovered" — silence is not a finding.
+- No unsourced guesses. An `INFERRED` row stays inferred until a source confirms it.
+- Never paste a real secret / PHI into an evidence doc; record its **location and purpose**, not its
+  value (see `resources/README.md` + `.agents/standards/codex.md`).
+
+Copy `0000-extraction-template.md` per run. Full standard: `.agents/standards/codex.md`.

package/templates/codex/reference/INDEX.md

@@ -0,0 +1,11 @@
+# reference — index
+
+The confirmed-value layer: ground-truth tables, API/IPC catalogs, and big contract docs the **code
+reads back**. ADRs that set `updates-confirmed-values: yes` update tables here in the same PR.
+
+| Entry | What it holds |
+|---|---|
+| `README.md` | What belongs here vs `domain/`; the confirmed-values discipline. |
+| `confirmed-values.md` | Ground-truth values (error codes, permission keys, enums, channel names). |
+
+<!-- Add catalogs / contract docs alongside; list each here. -->

package/templates/codex/reference/README.md

@@ -0,0 +1,15 @@
+# reference
+
+Confirmed-value tables and large runtime contracts the code depends on literally: error-code
+catalogs, permission keys, shared enums, IPC/channel names, API/IPC catalogs, tenant/hospital config
+tables. `domain/` explains *what things mean*; `reference/` pins *the exact values* both sides read
+back.
+
+## Confirmed-values discipline
+
+- A value here is **ground truth** — code, tests, UI, and server agree on it. Treat a change as
+  breaking until proven otherwise.
+- An ADR (`codex/decisions/`) that alters one sets `updates-confirmed-values: yes` and updates the
+  table **in the same PR** (the PR checklist enforces this).
+- Each value carries its provenance (`CONFIRMED | INFERRED`, source) per `.agents/standards/codex.md`.
+  An `INFERRED` value is a lead, not a contract — confirm it before code relies on it.

package/templates/codex/reference/confirmed-values.md

@@ -0,0 +1,18 @@
+---
+updated: <YYYY-MM-DD>
+status: canonical
+description: Ground-truth values the code reads back. Changed only via an ADR with updates-confirmed-values: yes, in the same PR.
+---
+
+# Confirmed values
+
+Values the system treats as **ground truth** — error codes, permission keys, shared enums, channel /
+IPC names, tenant configs. Changing one is breaking: it goes through an ADR
+(`codex/decisions/`) with `updates-confirmed-values: yes`, updated here in the **same PR**.
+
+| key | value | kind | source (file + offset) | CONFIRMED \| INFERRED |
+|---|---|---|---|---|
+| <e.g. ERR_AUTH_EXPIRED> | <value> | error code | `<file>:<offset>` | CONFIRMED |
+
+<!-- One table per kind is fine (error codes, permissions, enums…). Never silently edit a value:
+     every change traces to an ADR. -->

package/templates/codex/requirements/INDEX.md

@@ -0,0 +1,11 @@
+# requirements — index
+
+What the system must **do**, as a tracked, IDed, versioned artifact. Protocol:
+`.agents/standards/requirements.md`.
+
+| Entry | What it holds |
+|---|---|
+| `README.md` | Rules of the road: stable ids, base-reflects-now, testable statements. |
+| `base.md` | The baseline — what the system must do **now**. Changed only via an applied addon/CR. |
+| `addons/0000-template.md` | Template for a new capability layered on the base. |
+| `changes/0000-template.md` | Template for a change request modifying existing requirements. |

package/templates/codex/requirements/README.md

@@ -0,0 +1,22 @@
+# Requirements
+
+The project's requirements as a tracked, referenceable artifact. Project-owned: `grimoire sync` never
+touches this folder (seeded once by `grimoire init`). Full protocol:
+`.agents/standards/requirements.md`.
+
+## Files
+
+| Path | Holds |
+|---|---|
+| `base.md` | The baseline — what the system must do **now**. Changed only via an applied addon/CR. |
+| `addons/<id>-<slug>.md` | A new capability layered on the base (copy `addons/0000-template.md`). |
+| `changes/<id>-<slug>.md` | A change request modifying existing requirements (copy `changes/0000-template.md`). |
+
+## Rules of the road
+
+- Every requirement has a stable id `REQ-<AREA>-<NNN>` — sequential per area, **never reused or
+  renumbered**. A removed requirement becomes `status: withdrawn`; its row stays.
+- Cite the id in commits (`implements REQ-…`), test names, and the ADR that decided *how*.
+- The **base always reflects now**; addons and CRs are the **audit trail** of how it got there.
+  Never change a requirement in `base.md` without a matching addon/CR file recording the diff.
+- A requirement must be a **testable** statement. If it can't be verified, it isn't finished.

package/templates/codex/requirements/addons/0000-template.md

@@ -0,0 +1,35 @@
+---
+id: ADDON-0000
+title: <short addon title>
+status: proposed        # proposed | accepted | implemented | withdrawn
+date: <YYYY-MM-DD>
+extends:                # REQ-… ids in base this builds on, if any
+---
+
+# Addon ADDON-0000 — <short addon title>
+
+A self-contained new capability layered on the base. Reviewable on its own. When it ships, fold its
+rows into `base.md` and bump the base `version`; this file stays as history.
+See `.agents/standards/requirements.md`.
+
+## Why
+
+What user need / opportunity this addresses. Link the PRD or discussion if any.
+
+## New requirements
+
+| id | statement | priority | status | acceptance | source |
+|---|---|---|---|---|---|
+| REQ-<AREA>-<NNN> | The system must <testable statement>. | must | proposed | <test or check> | this addon |
+
+## Dependencies & impact
+
+- **Builds on:** <REQ-… in base, or "none">
+- **Touches:** <code areas, modules>
+- **Decisions needed:** <ADR id(s) this spawns, if a design choice is required>
+- **Confirmed values:** <does it add/change an error code, permission key, enum, channel? if so, the
+  ADR sets `updates-confirmed-values: yes` and the table updates in the same PR>
+
+## Acceptance (addon-level)
+
+How we know the whole addon is done — the set of checks across its requirements.

package/templates/codex/requirements/base.md

@@ -0,0 +1,36 @@
+---
+version: 0.1.0
+updated: <YYYY-MM-DD>
+status: canonical
+description: Baseline requirements — what the system must do now. Changed only via an applied addon or change request.
+---
+
+# Requirements — baseline
+
+The agreed requirements at the current accepted state. This file always reflects **now**. It changes
+only when an addon (`addons/`) or change request (`changes/`) is applied — see
+`.agents/standards/requirements.md` for the flow. Never edit a requirement here without a matching
+addon/CR file recording the diff.
+
+## How to read a row
+
+`id` (stable `REQ-<AREA>-<NNN>`, never reused) · `statement` (one testable "the system must …") ·
+`priority` (`must | should | could`) · `status` (`proposed | accepted | implemented | withdrawn`) ·
+`acceptance` (the test or check that proves it) · `source` (who/what introduced it).
+
+## Requirements
+
+### AREA: <e.g. AUTH>
+
+| id | statement | priority | status | acceptance | source |
+|---|---|---|---|---|---|
+| REQ-AUTH-001 | The system must <testable statement>. | must | accepted | `test/auth/...` or manual check | initial spec |
+
+<!-- Add one section per area. Keep numbers sequential per area; never renumber or reuse an id.
+     A withdrawn requirement stays in the table with status: withdrawn — do not delete the row. -->
+
+## Changelog (applied addons / CRs)
+
+| date | id | kind | summary | base version after |
+|---|---|---|---|---|
+| <YYYY-MM-DD> | <ADDON-001 / CR-001> | addon \| change | <one line> | 0.1.0 |

package/templates/codex/requirements/changes/0000-template.md

@@ -0,0 +1,39 @@
+---
+id: CR-0000
+title: <short change title>
+status: proposed        # proposed | accepted | applied | rejected
+date: <YYYY-MM-DD>
+affects:                # the REQ-… id(s) this change modifies
+---
+
+# Change Request CR-0000 — <short change title>
+
+A modification to one or more **existing** requirements. Records the diff old → new so the change is
+auditable. When applied, update the affected rows in `base.md`, bump the base `version`, and log it in
+the base changelog; this file stays as history. See `.agents/standards/requirements.md`.
+
+## Reason for change
+
+What changed in the world (new constraint, user feedback, regulation, a wrong assumption) that forces
+this. Be factual.
+
+## The change
+
+| id | old statement | new statement |
+|---|---|---|
+| REQ-<AREA>-<NNN> | <the current statement> | <the revised statement> |
+
+<!-- For a withdrawal: new statement = "(withdrawn — <reason>)" and set the row's status to withdrawn
+     in base.md (keep the id). -->
+
+## Impact
+
+- **Code/tests:** what must change to honor the new statement.
+- **Decisions:** ADR id(s) this needs or supersedes.
+- **Confirmed values:** if a ground-truth value changes (error code, permission key, enum, channel),
+  the linked ADR sets `updates-confirmed-values: yes` and the table updates in the **same PR**.
+- **Downstream requirements:** other `REQ-…` affected by this change.
+
+## Acceptance
+
+The check that proves the new statement holds (and the old behavior is gone).

package/templates/codex/resources/INDEX.md

@@ -0,0 +1,11 @@
+# resources — index
+
+Raw materials the project draws on: datasets, vendor specs, dumps, external artifacts and snapshots.
+The inputs to investigation (`evidence/`), not the conclusions.
+
+| Entry | What it holds |
+|---|---|
+| `README.md` | What belongs here; large / secret / binary handling; the manifest rule. |
+| `manifest.md` | Tracked index of every resource — including gitignored ones — with source + purpose. |
+
+<!-- Add resources alongside this INDEX; list each in manifest.md. -->

package/templates/codex/resources/README.md

@@ -0,0 +1,17 @@
+# resources
+
+Raw materials and external artifacts: datasets, vendor/API specs, database dumps, binary snapshots,
+captured payloads — the inputs you reverse-engineer or extract from. Conclusions go in `evidence/`
+and `reference/`; the raw stuff lives here.
+
+## Large / secret / binary handling
+
+- **Secret-bearing or PHI-bearing raw material** (dumps, captures, credential files) is **gitignored**
+  — it must never enter git history. Add the path to the project `.gitignore`.
+- **Huge or binary** artifacts: keep out of the repo (or use the project's large-file mechanism);
+  don't bloat history.
+- **Always keep a tracked `manifest.md`**: one row per resource — name, source/provenance, purpose,
+  and whether it's tracked or gitignored. The manifest is the durable record even when the bytes are
+  not in git, so a reader knows what exists and where to get it.
+
+Never echo a secret / PHI from a resource into chat or agent output. See `.agents/standards/codex.md`.

package/templates/codex/resources/manifest.md

@@ -0,0 +1,11 @@
+# Resource manifest
+
+One row per resource — tracked **and** gitignored. The durable record of what exists and where to get
+it, even when the bytes aren't in git. Keep it current.
+
+| resource | source / provenance | purpose | git status |
+|---|---|---|---|
+| `<path or name>` | <where it came from> | <what it's used for> | tracked \| gitignored |
+
+<!-- For gitignored secret/PHI-bearing material: record location + purpose only here; the value lives
+     in the gitignored inventory, never in a tracked doc. -->

package/templates/codex/runbooks/INDEX.md

@@ -0,0 +1,9 @@
+# runbooks — index
+
+The on-call answer to "production is broken — what now." One file per service, kept short and
+runnable under stress. Required by the launch-security checklist
+(`.agents/standards/launch-security-checklist.md`).
+
+| Entry | What it holds |
+|---|---|
+| `incident-runbook-template.md` | Copy per service to `codex/runbooks/<service>.md`. |

package/templates/codex/runbooks/README.md

@@ -0,0 +1,8 @@
+# runbooks
+
+The on-call answer to "production is broken — what now." One runbook per service, copied from
+`incident-runbook-template.md` to `codex/runbooks/<service>.md`. Keep each short, current, and
+runnable under stress — a runbook nobody can follow at 3am is worse than none.
+
+Required by the launch-security checklist (`.agents/standards/launch-security-checklist.md`). The
+highest-value section is "Common failure modes" — fill it in per service as incidents teach you.

package/templates/codex/runbooks/incident-runbook-template.md

@@ -0,0 +1,58 @@
+# Incident runbook — <service / app name>
+
+The on-call answer to "production is broken — what now." Required by the launch-security checklist
+(`.agents/standards/launch-security-checklist.md`). Keep it short, current, and runnable under stress.
+Copy to `codex/runbooks/<service>.md`.
+
+## At a glance
+
+- **Service:** <name + one line on what it does>
+- **Owners / on-call:** <names / rotation / how to reach>
+- **Dashboards:** <links — metrics, logs, error tracker, uptime>
+- **Status page / comms channel:** <where incidents are announced>
+
+## Severity levels
+
+| Sev | Meaning | Response |
+|---|---|---|
+| SEV1 | Full outage / data loss / security breach | Page now; all hands; comms immediately |
+| SEV2 | Major feature down / degraded for many | Page on-call; fix within hours |
+| SEV3 | Minor / workaround exists | Next business day |
+
+## First 15 minutes
+
+1. **Acknowledge** — claim the incident so others know it's owned.
+2. **Assess severity** (table above) and **declare** in the comms channel.
+3. **Stabilize, don't fix yet** — stop the bleeding: roll back the last release (see
+   `.agents/standards/release-versioning.md` → rollback), flip the feature flag off
+   (`.agents/rules/20-modes.md` HOTFIX), or scale/restart. Recovery beats root-cause under SEV1/2.
+4. **Communicate** — short status update; repeat on a cadence until resolved.
+
+## Diagnose
+
+- Check the dashboards above; read logs by **error code**, not message text
+  (`.agents/standards/observability.md` + `standards/error-codes.md`).
+- What changed? Last deploy/tag, last migration, last flag flip, upstream provider status.
+- Reproduce on the smallest input that triggers it.
+
+## Common failure modes
+
+<!-- Fill in per service: symptom → likely cause → action. This is the highest-value section. -->
+| Symptom | Likely cause | Action |
+|---|---|---|
+| <e.g. 5xx spike after deploy> | <bad release> | <roll back to previous tag> |
+| <DB connection errors> | <pool exhausted / provider down> | <check provider; restart; raise pool> |
+
+## Recovery & rollback
+
+- **Roll back a release:** `<exact command / steps; previous-good-tag location>`.
+- **Disable a feature:** `<flag name + how to flip>`.
+- **Restore data:** `<backup location, restore procedure, last-known-good>`.
+
+## After: post-incident
+
+- Write a blameless post-mortem: timeline, impact, root cause, what made it worse/better, action
+  items with owners.
+- File the action items in `journal/backlog/` (`.agents/rules/40-handoff.md`).
+- If the root cause was an unrecorded assumption or a ground-truth value, update the owning doc /
+  ADR / requirement the same turn (`.agents/rules/00-always.md`).

package/templates/gitignore-snippet.txt

@@ -0,0 +1,12 @@
+# --- Grimoire: session state is per-run, never tracked ---
+journal/session/
+
+# --- Grimoire: adopt-safety backups from `grimoire init`/`sync` (never tracked) ---
+.agents.bak-*/
+
+# --- Grimoire: graphify code-graph — commit the graph artifacts (team shares one map), ignore internal/local ---
+graphify-out/*
+!graphify-out/graph.json
+!graphify-out/graph.html
+!graphify-out/GRAPH_REPORT.md
+!graphify-out/manifest.json