the-grimoire-cli 0.3.2 → 0.5.0

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

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

@@ -1,45 +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`).
+---
+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`).

package/.agents/standards/observability.md

@@ -1,35 +1,35 @@
----
-updated: 2026-05-31
-status: canonical
-description: Production logging, metrics, and tracing lessons from real data/sync tools.
----
-
-# Standards — observability
-
-Lessons from production data/sync tools. The goal: an operator can self-diagnose a live issue from
-logs alone, without attaching a debugger.
-
-## Make the diagnosable facts visible at INFO
-
-- When a query/request returns **zero rows or an empty result on a path that usually has data**, log
-  enough to tell "correct empty" from "wrong input" — at **INFO**, not DEBUG. Operators rarely have
-  debug mode on in production.
-- For generated queries, log the **rendered parameters** (the actual values sent), not just the
-  template. A silent 0-row from a bad default (locale, era, timezone, unit) is otherwise invisible.
-
-## No silent empty results
-
-- A path that returns nothing where data was expected must surface *why* (filtered, unauthorized,
-  no-match) — never an unexplained empty array.
-
-## Per-source / per-locale overrides are first-class
-
-- Defaults that vary by deployment (date era, timezone, encoding, ID format, DB dialect) must be
-  **documented in onboarding** and overridable per source. Bake the override point in; don't assume
-  one global default fits every site.
-
-## Logging hygiene
-
-- Never log secrets, tokens, or full PII; scrub before logging (`rules/50-security.md`).
-- Structured logs (level + code + context) over free-text — pairs with the error-code catalog
-  (`standards/error-codes.md`).
+---
+updated: 2026-05-31
+status: canonical
+description: Production logging, metrics, and tracing lessons from real data/sync tools.
+---
+
+# Standards — observability
+
+Lessons from production data/sync tools. The goal: an operator can self-diagnose a live issue from
+logs alone, without attaching a debugger.
+
+## Make the diagnosable facts visible at INFO
+
+- When a query/request returns **zero rows or an empty result on a path that usually has data**, log
+  enough to tell "correct empty" from "wrong input" — at **INFO**, not DEBUG. Operators rarely have
+  debug mode on in production.
+- For generated queries, log the **rendered parameters** (the actual values sent), not just the
+  template. A silent 0-row from a bad default (locale, era, timezone, unit) is otherwise invisible.
+
+## No silent empty results
+
+- A path that returns nothing where data was expected must surface *why* (filtered, unauthorized,
+  no-match) — never an unexplained empty array.
+
+## Per-source / per-locale overrides are first-class
+
+- Defaults that vary by deployment (date era, timezone, encoding, ID format, DB dialect) must be
+  **documented in onboarding** and overridable per source. Bake the override point in; don't assume
+  one global default fits every site.
+
+## Logging hygiene
+
+- Never log secrets, tokens, or full PII; scrub before logging (`rules/50-security.md`).
+- Structured logs (level + code + context) over free-text — pairs with the error-code catalog
+  (`standards/error-codes.md`).

package/.agents/standards/release-versioning.md

@@ -1,53 +1,53 @@
----
-updated: 2026-05-31
-status: canonical
-description: "Versioning, changelog, and release discipline across app and library profiles — what ships, how it's tagged, how it's recorded."
----
-
-# Standards — release & versioning
-
-Every project needs an answer to "what version is live, and what changed since the last one." This
-standard gives the default; the active `stack/` profile refines the tooling.
-
-## Versioning scheme
-
-- **Libraries** (`stack/library.md`): strict **SemVer** — major = breaking API, minor = added API,
-  patch = fix. Public API changes drive the bump. Use **changesets** so each PR declares its bump.
-- **Apps** (web-app / desktop): SemVer-ish or CalVer — pick one and stay consistent. The number is
-  for humans tracing "which build has this fix," so what matters is that a tag exists per release and
-  maps to a commit. Tag the release commit (`vX.Y.Z`); the tag is the source of truth for "what
-  shipped."
-
-## Changelog — required, generated from commits
-
-- Keep a `CHANGELOG.md` (Keep-a-Changelog style: grouped Added / Changed / Fixed / Removed /
-  Security under each version + date).
-- It is **derived from Conventional Commits** (`rules/60-commit-style.md`): `feat:` → Added,
-  `fix:` → Fixed, `feat!:`/`BREAKING CHANGE:` → a major bump + a Changed/Removed entry. A tool
-  (changesets, release-please, or `git-cliff`) generates it; do not hand-curate from memory.
-- Cite requirement and ADR ids where relevant (`implements REQ-…`, `see ADR 00NN`) so a release
-  links back to *why* (`standards/requirements.md`).
-
-## Release checklist (gate before tagging)
-
-1. Verifier `pass` on fresh context; full suite green (`rules/30-verification.md`).
-2. For a user-facing app: the launch-security checklist passes
-   (`standards/launch-security-checklist.md`).
-3. `CHANGELOG.md` updated for this version; version bumped in the manifest (`package.json` etc.).
-4. Any `updates-confirmed-values: yes` ADR in this range has its confirmed-values table updated.
-5. Docs synced (`rules/00-always.md`) — no behavior shipped with stale docs.
-6. Tag the release commit; push the tag; publish (library: registry; app: deploy).
-
-## Deploy & rollback
-
-- The deploy target and any region/config pinning that the code depends on belong in the project's
-  `local/` notes or an ADR (not hardcoded, not tribal knowledge).
-- Every release must be **rollback-able**: know the previous good tag and the procedure to redeploy
-  it. A migration that can't roll back is itself a decision — record it in an ADR with the
-  forward-fix plan.
-
-## Pre-release / staged rollout
-
-Feature flags or env gates (same mechanism as HOTFIX, `rules/20-modes.md`) let a change ship dark and
-ramp. A flag is debt: record its name, the ramp/cleanup condition, and remove it once fully rolled
-out — a stale flag is a silent fork in behavior.
+---
+updated: 2026-05-31
+status: canonical
+description: "Versioning, changelog, and release discipline across app and library profiles — what ships, how it's tagged, how it's recorded."
+---
+
+# Standards — release & versioning
+
+Every project needs an answer to "what version is live, and what changed since the last one." This
+standard gives the default; the active `stack/` profile refines the tooling.
+
+## Versioning scheme
+
+- **Libraries** (`stack/library.md`): strict **SemVer** — major = breaking API, minor = added API,
+  patch = fix. Public API changes drive the bump. Use **changesets** so each PR declares its bump.
+- **Apps** (web-app / desktop): SemVer-ish or CalVer — pick one and stay consistent. The number is
+  for humans tracing "which build has this fix," so what matters is that a tag exists per release and
+  maps to a commit. Tag the release commit (`vX.Y.Z`); the tag is the source of truth for "what
+  shipped."
+
+## Changelog — required, generated from commits
+
+- Keep a `CHANGELOG.md` (Keep-a-Changelog style: grouped Added / Changed / Fixed / Removed /
+  Security under each version + date).
+- It is **derived from Conventional Commits** (`rules/60-commit-style.md`): `feat:` → Added,
+  `fix:` → Fixed, `feat!:`/`BREAKING CHANGE:` → a major bump + a Changed/Removed entry. A tool
+  (changesets, release-please, or `git-cliff`) generates it; do not hand-curate from memory.
+- Cite requirement and ADR ids where relevant (`implements REQ-…`, `see ADR 00NN`) so a release
+  links back to *why* (`standards/requirements.md`).
+
+## Release checklist (gate before tagging)
+
+1. Verifier `pass` on fresh context; full suite green (`rules/30-verification.md`).
+2. For a user-facing app: the launch-security checklist passes
+   (`standards/launch-security-checklist.md`).
+3. `CHANGELOG.md` updated for this version; version bumped in the manifest (`package.json` etc.).
+4. Any `updates-confirmed-values: yes` ADR in this range has its confirmed-values table updated.
+5. Docs synced (`rules/00-always.md`) — no behavior shipped with stale docs.
+6. Tag the release commit; push the tag; publish (library: registry; app: deploy).
+
+## Deploy & rollback
+
+- The deploy target and any region/config pinning that the code depends on belong in the project's
+  `local/` notes or an ADR (not hardcoded, not tribal knowledge).
+- Every release must be **rollback-able**: know the previous good tag and the procedure to redeploy
+  it. A migration that can't roll back is itself a decision — record it in an ADR with the
+  forward-fix plan.
+
+## Pre-release / staged rollout
+
+Feature flags or env gates (same mechanism as HOTFIX, `rules/20-modes.md`) let a change ship dark and
+ramp. A flag is debt: record its name, the ramp/cleanup condition, and remove it once fully rolled
+out — a stale flag is a silent fork in behavior.

package/.agents/standards/requirements.md

@@ -1,75 +1,75 @@
----
-updated: 2026-05-31
-status: canonical
-description: "How requirements are captured, identified, versioned, and traced — base requirements plus addons and change requests."
----
-
-# Standards — requirements
-
-A project's requirements are a **tracked, referenceable artifact**, not scattered chat history. They
-live under `codex/requirements/` (project-owned; `grimoire sync` never touches them — seeded by
-`grimoire init` from `templates/codex/`). Every requirement has a stable ID so code, tests,
-commits, ADRs, and change requests can cite it.
-
-## The three documents
-
-| File | Holds | When it changes |
-|---|---|---|
-| `codex/requirements/base.md` | The **baseline** — the agreed requirements at the current accepted state | Only via an applied change request (CR) |
-| `codex/requirements/addons/<id>-<slug>.md` | A self-contained **addon** — a new feature/capability layered on the base | New file per feature; merged into base when it ships |
-| `codex/requirements/changes/<id>-<slug>.md` | A **change request (CR)** — a modification to an existing requirement | New file per change; records old → new |
-
-Base = the source of truth for "what the system must do *now*." Addons and CRs are the **audit
-trail** of how it got there. Nothing edits a requirement silently — the diff always exists as a CR
-or an addon.
-
-## Requirement IDs — stable and traceable
-
-- Format: `REQ-<area>-<NNN>` — e.g. `REQ-AUTH-001`, `REQ-ROSTER-014`. Area is a short uppercase
-  domain tag; number is zero-padded, sequential per area, **never reused or renumbered**.
-- A requirement keeps its ID for life. If it is removed, mark it `status: withdrawn` — do not delete
-  the row (the ID must never point at something else later).
-- Cite the ID everywhere the requirement is realized: commit body (`implements REQ-AUTH-001`), test
-  name/describe block, the ADR that decided *how*, and the CR that last changed it. An auditor reads
-  one ID and finds the whole chain.
-
-## Each requirement row carries
-
-`id` · `statement` (one testable "the system must …" sentence) · `rationale` (why) ·
-`acceptance` (how we verify it — links to the test or the manual check) · `status`
-(`proposed | accepted | implemented | withdrawn`) · `priority` (`must | should | could`) ·
-`source` (who asked / which CR or addon introduced it).
-
-A requirement that cannot be phrased as a **testable** statement is not done being written — sharpen
-it until its acceptance criterion is observable.
-
-## Change flow (base ← addon / CR)
-
-1. **New feature** → write an **addon** (`addons/<id>-<slug>.md`) with its own `REQ-…` rows. It is
-   reviewable on its own and references the base requirements it depends on or extends.
-2. **Modify an existing requirement** → write a **CR** (`changes/<id>-<slug>.md`): name the affected
-   `REQ-…` id(s), give **old statement → new statement**, the reason, and the impact (code, tests,
-   ADRs, confirmed-values).
-3. **On merge**, fold the addon's / CR's outcome into `base.md` (update the rows, bump the base
-   `version`), and leave the addon/CR file in place as history. The base always reflects *now*; the
-   addon/CR explains *the change*.
-4. If the change alters a **ground-truth value** (error code, permission key, enum, channel name),
-   the linked ADR sets `updates-confirmed-values: yes` and the confirmed-values table updates in the
-   **same PR** (`codex/decisions/` + `standards/error-codes.md`).
-
-## Versioning the base
-
-`base.md` carries a `version` (semantic-ish: bump minor for an added requirement, patch for a
-clarification, major for a breaking removal/redefinition) and a `changelog` table listing each
-applied addon/CR by id and date. Diffing two base versions = the requirements delta between releases.
-
-## Relationship to the rest of the contract
-
-- **Planning** (`rules/10-working-process.md`): the task contract's *goal* and *acceptance criteria*
-  should cite the `REQ-…` ids it satisfies.
-- **Verification** (`rules/30-verification.md`): the verifier checks output against the cited
-  requirement's acceptance criterion — "done" means that criterion is met.
-- **Decisions** (`codex/decisions/`): requirements say *what*; ADRs say *how* and *why*. A CR that needs a
-  design choice spawns an ADR; the ADR's `supersedes` and the CR cross-link.
-- **PRD/spec skills** (`skills/catalog.md`: `to-prd`, `brainstorming`) produce the prose; this
-  standard is where that prose lands as IDed, versioned rows.
+---
+updated: 2026-05-31
+status: canonical
+description: "How requirements are captured, identified, versioned, and traced — base requirements plus addons and change requests."
+---
+
+# Standards — requirements
+
+A project's requirements are a **tracked, referenceable artifact**, not scattered chat history. They
+live under `codex/requirements/` (project-owned; `grimoire sync` never touches them — seeded by
+`grimoire init` from `templates/codex/`). Every requirement has a stable ID so code, tests,
+commits, ADRs, and change requests can cite it.
+
+## The three documents
+
+| File | Holds | When it changes |
+|---|---|---|
+| `codex/requirements/base.md` | The **baseline** — the agreed requirements at the current accepted state | Only via an applied change request (CR) |
+| `codex/requirements/addons/<id>-<slug>.md` | A self-contained **addon** — a new feature/capability layered on the base | New file per feature; merged into base when it ships |
+| `codex/requirements/changes/<id>-<slug>.md` | A **change request (CR)** — a modification to an existing requirement | New file per change; records old → new |
+
+Base = the source of truth for "what the system must do *now*." Addons and CRs are the **audit
+trail** of how it got there. Nothing edits a requirement silently — the diff always exists as a CR
+or an addon.
+
+## Requirement IDs — stable and traceable
+
+- Format: `REQ-<area>-<NNN>` — e.g. `REQ-AUTH-001`, `REQ-ROSTER-014`. Area is a short uppercase
+  domain tag; number is zero-padded, sequential per area, **never reused or renumbered**.
+- A requirement keeps its ID for life. If it is removed, mark it `status: withdrawn` — do not delete
+  the row (the ID must never point at something else later).
+- Cite the ID everywhere the requirement is realized: commit body (`implements REQ-AUTH-001`), test
+  name/describe block, the ADR that decided *how*, and the CR that last changed it. An auditor reads
+  one ID and finds the whole chain.
+
+## Each requirement row carries
+
+`id` · `statement` (one testable "the system must …" sentence) · `rationale` (why) ·
+`acceptance` (how we verify it — links to the test or the manual check) · `status`
+(`proposed | accepted | implemented | withdrawn`) · `priority` (`must | should | could`) ·
+`source` (who asked / which CR or addon introduced it).
+
+A requirement that cannot be phrased as a **testable** statement is not done being written — sharpen
+it until its acceptance criterion is observable.
+
+## Change flow (base ← addon / CR)
+
+1. **New feature** → write an **addon** (`addons/<id>-<slug>.md`) with its own `REQ-…` rows. It is
+   reviewable on its own and references the base requirements it depends on or extends.
+2. **Modify an existing requirement** → write a **CR** (`changes/<id>-<slug>.md`): name the affected
+   `REQ-…` id(s), give **old statement → new statement**, the reason, and the impact (code, tests,
+   ADRs, confirmed-values).
+3. **On merge**, fold the addon's / CR's outcome into `base.md` (update the rows, bump the base
+   `version`), and leave the addon/CR file in place as history. The base always reflects *now*; the
+   addon/CR explains *the change*.
+4. If the change alters a **ground-truth value** (error code, permission key, enum, channel name),
+   the linked ADR sets `updates-confirmed-values: yes` and the confirmed-values table updates in the
+   **same PR** (`codex/decisions/` + `standards/error-codes.md`).
+
+## Versioning the base
+
+`base.md` carries a `version` (semantic-ish: bump minor for an added requirement, patch for a
+clarification, major for a breaking removal/redefinition) and a `changelog` table listing each
+applied addon/CR by id and date. Diffing two base versions = the requirements delta between releases.
+
+## Relationship to the rest of the contract
+
+- **Planning** (`rules/10-working-process.md`): the task contract's *goal* and *acceptance criteria*
+  should cite the `REQ-…` ids it satisfies.
+- **Verification** (`rules/30-verification.md`): the verifier checks output against the cited
+  requirement's acceptance criterion — "done" means that criterion is met.
+- **Decisions** (`codex/decisions/`): requirements say *what*; ADRs say *how* and *why*. A CR that needs a
+  design choice spawns an ADR; the ADR's `supersedes` and the CR cross-link.
+- **PRD/spec skills** (`skills/catalog.md`: `to-prd`, `brainstorming`) produce the prose; this
+  standard is where that prose lands as IDed, versioned rows.

package/.agents/standards/security-scanners.md

@@ -1,42 +1,42 @@
----
-updated: 2026-05-31
-status: canonical
-description: SAST scanners by language and how to wire them into CI to catch exploitable bugs.
----
-
-# Security scanners (SAST)
-
-Linters find what is ugly; **SAST** finds what is exploitable — SQLi, XSS, RCE, path traversal,
-hardcoded secrets, weak crypto. Pick by language, run in CI, fail on High/Critical. OSS unless noted.
-
-| Scanner | Scope | Use when |
-|---|---|---|
-| **Semgrep** | pattern-based, 30+ languages | default for any project (incl. TS/JS) |
-| **njsscan** | JS / Node / React Native | Next.js, Electron, React Native |
-| **CodeQL** | semantic taint-tracking, GitHub-native | any repo on GitHub (free for public) — enable Code Scanning |
-| **Bandit** | Python | any Python service |
-| **Brakeman** | Ruby on Rails | Rails apps |
-| **gosec** | Go | Go services |
-| **Snyk Code** | AI-assisted, inline fixes (freemium) | optional, on top of the above |
-
-## For this org's stacks (TypeScript · Next.js · Electron)
-
-Run **Semgrep + njsscan** in CI and enable **CodeQL** Code Scanning on GitHub. Add **Bandit** if a
-Python service appears.
-
-## CI wiring
-
-Drop-in workflow: copy `templates/ci/sast.yml` → `.github/workflows/sast.yml` (Semgrep + njsscan;
-CodeQL enabled separately). It fails the build on findings. Per profile:
-
-| Profile | Run |
-|---|---|
-| web-app (Next.js) | Semgrep + njsscan + CodeQL (js/ts) |
-| desktop (Electron) | Semgrep + njsscan + CodeQL |
-| library | Semgrep + the language's native scanner (bandit/gosec/…) if not JS/TS |
-| + any Python service | add Bandit (`bandit -r src -ll`) |
-
-CodeQL: GitHub → Security → Code scanning → enable, or the `github/codeql-action` workflow.
-
-Pre-launch: clear High/Critical and wire the scan into `standards/launch-security-checklist.md`. For
-user-facing, data-collecting apps this is part of Definition of Done (`rules/00-always.md`).
+---
+updated: 2026-05-31
+status: canonical
+description: SAST scanners by language and how to wire them into CI to catch exploitable bugs.
+---
+
+# Security scanners (SAST)
+
+Linters find what is ugly; **SAST** finds what is exploitable — SQLi, XSS, RCE, path traversal,
+hardcoded secrets, weak crypto. Pick by language, run in CI, fail on High/Critical. OSS unless noted.
+
+| Scanner | Scope | Use when |
+|---|---|---|
+| **Semgrep** | pattern-based, 30+ languages | default for any project (incl. TS/JS) |
+| **njsscan** | JS / Node / React Native | Next.js, Electron, React Native |
+| **CodeQL** | semantic taint-tracking, GitHub-native | any repo on GitHub (free for public) — enable Code Scanning |
+| **Bandit** | Python | any Python service |
+| **Brakeman** | Ruby on Rails | Rails apps |
+| **gosec** | Go | Go services |
+| **Snyk Code** | AI-assisted, inline fixes (freemium) | optional, on top of the above |
+
+## For this org's stacks (TypeScript · Next.js · Electron)
+
+Run **Semgrep + njsscan** in CI and enable **CodeQL** Code Scanning on GitHub. Add **Bandit** if a
+Python service appears.
+
+## CI wiring
+
+Drop-in workflow: copy `templates/ci/sast.yml` → `.github/workflows/sast.yml` (Semgrep + njsscan;
+CodeQL enabled separately). It fails the build on findings. Per profile:
+
+| Profile | Run |
+|---|---|
+| web-app (Next.js) | Semgrep + njsscan + CodeQL (js/ts) |
+| desktop (Electron) | Semgrep + njsscan + CodeQL |
+| library | Semgrep + the language's native scanner (bandit/gosec/…) if not JS/TS |
+| + any Python service | add Bandit (`bandit -r src -ll`) |
+
+CodeQL: GitHub → Security → Code scanning → enable, or the `github/codeql-action` workflow.
+
+Pre-launch: clear High/Critical and wire the scan into `standards/launch-security-checklist.md`. For
+user-facing, data-collecting apps this is part of Definition of Done (`rules/00-always.md`).