contextdevkit 1.8.0

package/templates/contextkit/detectors/README.md

@@ -0,0 +1,45 @@
+# Custom tech-debt detectors
+
+Drop-in extension point for `/tech-debt-sweep` (`tech-debt-scan.mjs`). Any
+`*.mjs` file in **this folder** is auto-loaded and its exported detector
+function(s) run alongside the built-ins on every scan — no core edit needed.
+
+> This folder itself is **excluded from scanning** (you don't lint your linters),
+> and a broken detector is skipped defensively rather than failing the run.
+
+## The contract
+
+A detector is a pure function:
+
+```js
+// (relativePath, fileContent) => findings[]
+export default function detectName(path, content) {
+  // return [] when there's nothing to report
+}
+```
+
+Each **finding** is an object:
+
+| field      | type   | notes                                                  |
+| ---------- | ------ | ------------------------------------------------------ |
+| `kind`     | string | short id, e.g. `"console-log"`                          |
+| `severity` | 1–5    | 5 = RED zone (fails the CI gate), 1 = info              |
+| `path`     | string | the `path` arg                                          |
+| `line`     | number | 1-based line number (optional)                         |
+| `message`  | string | what's wrong + ideally how to fix                      |
+| `snippet`  | string | optional offending line excerpt                        |
+
+A module may `export default` one detector **or** export several named
+functions — all exported functions are collected.
+
+## Enable the example
+
+```bash
+cp contextkit/detectors/example-detector.mjs.example contextkit/detectors/console-log.mjs
+node contextkit/tools/scripts/tech-debt-scan.mjs   # now flags stray console.log calls
+```
+
+## ⚠️ Trust
+
+Detectors are **executed** by the scanner with full Node privileges. Only add
+detectors you've read and trust — treat them like any other code in the repo.

package/templates/contextkit/detectors/example-detector.mjs.example

@@ -0,0 +1,25 @@
+/**
+ * Example custom tech-debt detector — flags stray `console.log(` calls left in
+ * source (a common debug leftover). Copy this file to `<name>.mjs` in this
+ * folder to ACTIVATE it (the `.example` suffix keeps it inert until you do):
+ *
+ *   cp example-detector.mjs.example console-log.mjs
+ *
+ * Contract: `(relativePath, fileContent) => findings[]`. See README.md.
+ */
+export default function detectConsoleLog(path, content) {
+  const findings = [];
+  content.split('\n').forEach((line, i) => {
+    if (/\bconsole\.log\(/.test(line)) {
+      findings.push({
+        kind: 'console-log',
+        severity: 2,
+        path,
+        line: i + 1,
+        snippet: line.trim().slice(0, 120),
+        message: 'Stray `console.log` — remove it or route through a real logger.',
+      });
+    }
+  });
+  return findings;
+}

package/templates/contextkit/instrucoes.md

@@ -0,0 +1,114 @@
+# ContextDevKit — Guia de Uso (pt-BR)
+
+> Guia prático em português. **Comandos, caminhos e chaves de config** ficam em
+> inglês de propósito (é o "principal" do projeto) — só a explicação é em pt-BR.
+
+## O que é
+
+O ContextDevKit transforma "AI-assisted coding" em **engenharia**: em vez de torcer pra
+IA lembrar do contexto, o ambiente (hooks do Claude Code) **força** boas
+práticas e guarda o histórico no próprio repositório.
+
+## Primeiro uso
+
+Abra o projeto no Claude Code, aprove os hooks, e rode **`/setupcontextdevkit`** —
+ele detecta a stack, ajusta o config, preenche o `CLAUDE.md`, marca paths de
+risco, cria um ADR base e registra a sessão. Um banner de "first run" aparece
+no boot até você rodá-lo.
+
+Projeto vazio (greenfield)? Use **`/aidevtool-from0`** — questionário interativo
+de produto → visão, stack, roadmap, boas práticas e DevPipeline montados num
+único passo.
+
+## Os 7 níveis
+
+| Nível | O que ativa |
+| --- | --- |
+| **L1 Memory** | contexto no boot, `/log-session`, ADRs, changelog |
+| **L2 Ledger** | detecção de drift |
+| **L3 Multi** | claims, worktrees, índices auto-gerados, git hooks (Conventional Commits + pre-push contra conflito real) |
+| **L4 Squads** | 28 sub-agentes em 7 squads (devteam, qa-team, design-team com `seo-specialist` + `landing-architect`, security, compliance-LGPD, ops, agent-forge) |
+| **L5 Proactive** | gate `/simulate-impact`, tech-debt, distill-detect, contract drift |
+| **L6 Autonomy** | pipeline `/ship`, learning loop `/retro`, métricas, agent-forge ativo |
+| **L7 Ecosystem** | `/fleet` (multi-repo), `/tune-agents`, testes visuais, playbook runner |
+
+Trocar de nível: `/context-level <n>` (reinicie o Claude Code depois).
+
+## Comandos principais
+
+- **Setup:** `/aidevtool-from0` (vazio) · `/setupcontextdevkit` (existente)
+- **Diário:** `/state` · `/log-session` (no fim) · `/new-adr` · `/close-version` ·
+  `/context-refresh` · `/bug-hunt` · `/dashboard` · `/watch` · `/playbook` ·
+  `/context-stats` · `/distill-sessions` · `/distill-apply`
+- **Trabalho focado:** `/dev-start` (mostra PRs abertos via sync-check) ·
+  `/workflow` · `/ship` · `/resume`
+- **Coordenação (L3):** `/claim` · `/release` · `/worktree-new` · `/git`
+- **Qualidade (pack `qa/` + L5):** `/test-plan` · `/scaffold-tests` ·
+  `/qa-signoff` · `/visual-test` · `/simulate-impact` · `/tech-debt-sweep` ·
+  `/analyze-code-ia-practices` · `/contract-check`
+- **Auditoria (pack `audit/`):** `/audit` · `/deep-analysis` · `/security-setup` ·
+  `/deps-audit` · **`/seo-audit`** *(novo — SEO + AISO)*
+- **Landing pages & mídia *(novo na v1.7)*:** `/landing-page` (architect
+  opinionado anti-cookie-cutter) · `/media-gen` (Veo + Nano Banana via `.env`)
+- **Produto & execução:** `/roadmap` · `/pipeline` · `/runs` · `/retro` ·
+  `/squad` · `/claude-md`
+- **Plataforma:** `/context-doctor` · `/context-config` · `/context-level` ·
+  `/fleet` *(L7)* · `/tune-agents` *(L6)*
+- **Agent-forge** *(L6+)*: 14 comandos `forge-*` para o ciclo de Agent Packages
+
+## Squads
+
+| Squad | Specialists | Quando |
+|---|---|---|
+| **devteam** | architect, code-reviewer, context-keeper, test-engineer | Design + revisão + memória |
+| **qa-team** | qa-orchestrator + unit/integration/fuzzer/perf/e2e | Testes |
+| **design-team** | ui-designer, ux-designer, accessibility, **seo-specialist**, **landing-architect** | UI/UX, WCAG AA, SEO+AISO, landing |
+| **security-team** | security, code-security, infra-security | Auth, deps, IaC |
+| **compliance-team** | privacy-lgpd, governance-officer | LGPD, políticas |
+| **ops-team** | devops | CI/CD, deploys |
+| **agent-forge** *(L6+)* | forge-orchestrator + 7 specialists | Pipeline pra Agent Packages portáveis |
+
+## Provider adapters *(novo)*
+
+Dois surfaces plugáveis sob `runtime/providers/`:
+
+- **`review/`** — adapters de CLI de PR (hoje: `gh`; adicione `glab.mjs` /
+  `bb.mjs` no mesmo contrato).
+- **`media/`** — geração de mídia (hoje: `nano-banana` para imagem via Imagen 3
+  e `veo` para vídeo, ambos via `GOOGLE_AI_API_KEY` configurado em
+  `contextkit/.env`).
+
+Setup do `/media-gen`:
+1. Pega chave em https://aistudio.google.com/apikey
+2. Copia `contextkit/.env.example` pra `contextkit/.env`, cola em `GOOGLE_AI_API_KEY=`
+3. (Opcional) `CONTEXTDEVKIT_MEDIA_MAX_USD=5.00` pra capar custo por processo
+4. Roda com `node --env-file=contextkit/.env contextkit/tools/scripts/media-gen.mjs ...`
+
+## Boas práticas
+
+- **Onde começar:** projeto **vazio** → L3; projeto que **já tem código** → L7
+  (use tudo; os gates ficam inertes até configurar `highRiskPaths`). O
+  instalador escolhe automaticamente.
+- **ADR antes** de decisão grande (`/new-adr`). ADR aceito é imutável.
+- **Registre a sessão** (`/log-session`) — veja seu `drift rate` em
+  `/context-stats`. Se perdeu, `/resume`.
+- Ajuste `contextkit/config.json` → `ledger.*` ao seu stack (ou `/context-config`).
+- Mantenha o `CLAUDE.md` curto e com as regras imutáveis preenchidas.
+- Não edite arquivos gerados (`SESSIONS.md`, `WORKSPACE.md`, `tech-debt-board.md`,
+  `dashboard.html`) — são regenerados.
+- Sessões paralelas → `/worktree-new` (nunca dois chats no mesmo diretório).
+- **Landing page?** Use `/landing-page` antes de codar — recusa SPA puro,
+  define fold count, escolhe pacotes da rec table datada, delega imagery pra
+  `/media-gen` (sem stock photos genéricas).
+
+## Manutenção
+
+- `/context-doctor` — saúde do install. `/context-stats` — métricas.
+- `/audit` — auditoria geral (bom agendar via `/loop` ou `/schedule`).
+- `/dashboard` — visual do estado em HTML; `--watch` em tempo real.
+- Atualizar o kit: rode o instalador de novo (não perde memória/config) ou
+  `npx contextdevkit@latest --target . --update`.
+
+Docs completos (inglês): `contextkit/README.md` e a pasta `docs/` do kit
+(`docs/ARCHITECTURE.md`, `docs/CUSTOMIZING.md`, `docs/SQUADS/design-team.md`,
+`docs/SQUADS/agent-forge.md`, `docs/LEVELS.md`).

package/templates/contextkit/memory/GLOSSARY.md

@@ -0,0 +1,13 @@
+# Glossary — domain term ↔ code identifier
+
+> The naming authority for this project. Before coining a new domain identifier
+> (variable, function, table, endpoint), check here. Keeps UI/business language
+> and code vocabulary aligned, and prevents three names for the same concept.
+
+| Domain term (UI / business) | Code identifier | Notes |
+| --- | --- | --- |
+| _example: customer_ | `user` | one canonical word per concept |
+
+<!-- Grow this table as the domain language emerges. When the UI audience speaks
+     a different language than the code, this table is where the translation is
+     pinned down (e.g. "ruivo" → `copper`). -->

package/templates/contextkit/memory/SESSIONS.md

@@ -0,0 +1,9 @@
+# Session History
+
+> ⚠️  **AUTO-GENERATED FILE — DO NOT EDIT BY HAND**.
+> Each session lives in its own file under `contextkit/memory/sessions/`.
+> Regenerated by `session-reindex` (also runs on pre-commit).
+
+Register a new session with `/log-session`.
+
+_(No sessions registered yet.)_

package/templates/contextkit/memory/WORKSPACE.md

@@ -0,0 +1,7 @@
+# Workspace — Active Sessions
+
+> ⚠️  **AUTO-GENERATED FILE — DO NOT EDIT BY HAND**.
+> Regenerated by `workspace-sync` (runs on pre-commit) from
+> `.claude/.workspace/<sid>.json` files maintained by hooks and slash commands.
+
+_(No active sessions. The workspace is idle.)_

package/templates/contextkit/memory/business-rules/_TEMPLATE.md

@@ -0,0 +1,33 @@
+# Business Rule: <name> (v1)
+
+- **Status**: Draft   <!-- Draft | Active | Superseded by <name>-vN -->
+- **Version**: v1
+- **Owner**: <team / role>   ·   **Updated**: YYYY-MM-DD
+- **Related**: [GLOSSARY](../GLOSSARY.md) terms · ADR(s) · roadmap P-IDs
+
+## Rule
+State the rule precisely, in domain language — what MUST happen, for whom, and
+when. A reader should be able to implement or verify it from this section alone.
+
+## Inputs → outputs
+- **Given**: <preconditions / inputs>
+- **Then**: <the deterministic result>
+
+## Edge cases & exceptions
+- <boundary condition> → <expected behaviour>
+- <conflict / failure mode> → <expected behaviour>
+
+## Rationale (why)
+Why the rule exists (business / legal / UX). If a technical decision enforces it,
+link the ADR in `../decisions/`.
+
+## Examples
+| Input | Expected |
+| --- | --- |
+| <case> | <result> |
+
+<!-- One file per cohesive rule, versioned (`-v1`, `-v2`). When a rule changes
+     materially, add a new version and mark the old one "Superseded". Keep the
+     business language consistent with GLOSSARY.md. This folder mirrors the
+     source platform's docs/business-rules/, kept in contextkit/memory/ alongside
+     the rest of the project's durable memory. -->

package/templates/contextkit/memory/decisions/0000-record-architecture-decisions.md

@@ -0,0 +1,34 @@
+# ADR-0000: Record architecture decisions
+
+- **Status**: Accepted
+- **Date**: 2020-01-01
+- **Deciders**: ContextDevKit
+
+## Context
+
+Significant architectural choices on a project get made in conversations, chat
+logs, and people's heads — then forgotten. Six months later nobody remembers why
+the datastore was chosen, why a library was rejected, or what constraint a
+strange-looking design protects. AI coding sessions make this worse: each fresh
+session starts blind unless the *why* is written down somewhere durable.
+
+## Decision
+
+We will record every significant architectural decision as an **Architecture
+Decision Record (ADR)** — a numbered, immutable markdown file in
+`contextkit/memory/decisions/`, following Michael Nygard's format
+(Context / Decision / Consequences).
+
+- Create one with `/new-adr <title>` **before** implementing the decision.
+- ADRs are **immutable once Accepted**. To change a decision, write a NEW ADR
+  that supersedes the old one and update the old one's status.
+- The immutable rules in `CLAUDE.md` should each point to the ADR that justifies
+  them.
+
+## Consequences
+
+- **Positive**: durable institutional memory; new sessions (human or AI) can
+  reconstruct intent; debates don't get re-litigated.
+- **Trade-off**: a small ritual cost per decision. Worth it — the alternative is
+  silent drift.
+- **Follow-up**: keep ADRs short. They capture *why*, not implementation detail.

package/templates/contextkit/memory/decisions/_TEMPLATE.md

@@ -0,0 +1,25 @@
+# ADR-NNNN: <Short decision title>
+
+- **Status**: Proposed <!-- Proposed | Accepted | Superseded by ADR-XXXX -->
+- **Date**: YYYY-MM-DD
+- **Deciders**: <who>
+
+## Context
+
+What is the situation and the forces at play? Why is a decision needed now?
+State the constraints (technical, business, team, time) honestly. This section
+should let a future reader understand the problem WITHOUT already knowing the answer.
+
+## Decision
+
+What we will do, stated plainly and in the active voice. "We will use X because Y."
+
+## Consequences
+
+- **Positive**: what becomes easier / safer / faster.
+- **Negative / trade-offs**: what becomes harder, what we give up, the risks.
+- **Follow-ups**: anything this decision obligates us to do next.
+
+<!-- If this supersedes an earlier ADR, add:
+     Supersedes [ADR-XXXX](XXXX-...md). And set that ADR's status to
+     "Superseded by ADR-NNNN". ADRs are immutable once Accepted. -->

package/templates/contextkit/memory/roadmap.md

@@ -0,0 +1,28 @@
+# Product Roadmap
+
+> The **product / business plan** — capabilities and milestones, ordered by value.
+> The *what* and *why*. Execution (bugs, increments, tasks, SLA) lives in the
+> **DevPipeline** (`contextkit/pipeline/`), not here. Built collaboratively via
+> `/roadmap`; keep it current as priorities change.
+>
+> **Convention — P-IDs:** phases are `P1`, `P2`, …; items are `P1.1`, `P1.2`, …
+> Each item is a user-facing capability with a one-line acceptance note. Mark
+> status with: 📋 planned · ⏳ in progress (a session is on it) · 🟡 partial/blocked ·
+> ✅ done — flip an item to ⏳ when a session starts it, to ✅ when it ships.
+> Cross-reference DevPipeline tasks by P-ID (a task's `roadmap:` field).
+
+<!-- ROADMAP-NOT-DEFINED -->
+_No roadmap defined yet._ Run **`/roadmap`** — in a new project it's built with
+you step by step; in an existing project it looks for a roadmap/PRD/spec to
+import, or analyzes the code and proposes one for you to refine and extend.
+
+<!--
+Example shape once defined:
+
+## P1 — <phase name / theme>
+- **P1.1** 📋 <capability> — _accept:_ <one-line done criterion>
+- **P1.2** 📋 <capability> — _accept:_ <...>
+
+## P2 — <next phase>
+- **P2.1** 📋 <capability> — _accept:_ <...>
+-->

package/templates/contextkit/pipeline/devpipeline.md

@@ -0,0 +1,9 @@
+# DevPipeline — execution board
+
+> ⚠️  **AUTO-GENERATED** by `pipeline.mjs sync` (also on pre-commit). Do not hand-edit.
+> The product/business plan is `contextkit/memory/roadmap.md`. THIS is execution control:
+> bugs, increments, chores and roadmap items broken into tasks with priority + SLA.
+
+Backlog **0** · Testing **0** · Concluded **0**
+
+_(No tasks yet. Add one with `/pipeline` or `node contextkit/tools/scripts/pipeline.mjs add ...`.)_

package/templates/contextkit/review-protocol.md

@@ -0,0 +1,214 @@
+# AI-Assisted Coding Review Protocol
+
+> How `/analyze-code-ia-practices` is meant to be *run* — severity vocabulary,
+> when each tier applies, the audit protocol, and the contract between the
+> deterministic scanner and the agent.
+>
+> **Paired with `best-practices.md`** (the rubric: principles, tiers, rules,
+> over-apply clauses). That file says *what good looks like*; this file says
+> *how to apply it and how to report.*
+>
+> **Scope.** This protocol covers the *code-quality* lens: architecture
+> (Tier 1) and hygiene (Tier 2). Security, accessibility, privacy and
+> dependency / supply-chain concerns are owned by the kit's specialised
+> agents and commands — see *Adjacent concerns* at the foot of
+> `best-practices.md` for the routing.
+>
+> Keep both files in sync with the constitution in `CLAUDE.md` and with
+> `contextkit/config.json` (thresholds and ledger paths).
+
+## Severity vocabulary
+
+Anchored on the scanner's existing **1..5** scale (used by `tech-debt-scan`
+and its `--ci` gate) so the rubric, the deterministic scan, and the build
+gate stay aligned. Inventing a parallel scale would drift them apart.
+
+| Label       | Scanner sev | Meaning                                                |
+| ----------- | :---------: | ------------------------------------------------------ |
+| `BLOCKER`   | 5           | Fix before merge. Fails `tech-debt-scan --ci`.         |
+| `HARD`      | 4           | Clear violation, no cohesion excuse. Fix it.           |
+| `CANDIDATE` | 2–3         | Judgment call; may be justified. Explain the tradeoff. |
+| `NIT`       | 1           | Mention once, don't litigate.                          |
+
+Mapping rules of thumb:
+
+- A **Tier 1** (architecture) finding is typically `HARD` — the cost of
+  leaving it grows fast. Downgrade to `CANDIDATE` only when the affected
+  surface is genuinely small and isolated.
+- A **Tier 2** (hygiene) finding starts at `CANDIDATE` and rises to `HARD`
+  only when the over-apply clause has been considered and rejected, or to
+  `BLOCKER` when the scanner already emits severity 5 (e.g. `> 308` lines —
+  the project's line-budget RED zone, configurable in `contextkit/config.json
+  → l5.lineBudget`).
+- For **security findings**, dispatch the security-team — see *Adjacent
+  concerns* in `best-practices.md`. The severity vocabulary here applies
+  inside the rubric's lane only.
+
+## When this rubric applies
+
+Rigor must match the stakes, or it's either waste or negligence.
+
+- **Production paths** (anything shipped to users, anything that holds real
+  data): the full rubric applies.
+- **Spikes & throwaways** (prototypes, scratch directories like
+  `/experiments` or `/spikes`, code you will delete within the week):
+  **Tier 2 hygiene and tests are relaxed.** Don't demand JSDoc or coverage
+  on code that isn't going to survive. Naming and obvious-error handling
+  still matter — but the documentation/tests bar drops.
+- **Tier 1 (architecture)** sits in the middle. A three-file script doesn't
+  need a hexagonal architecture; an app with a real domain does. The
+  *direction* of dependencies still matters at any size — the *depth* of
+  layering scales with complexity.
+
+## Running the analysis
+
+How `/analyze-code-ia-practices` should behave once the scanner has run.
+
+1. **Read both rubric files first** (`best-practices.md` and this protocol).
+   Use the project's `l5.lineBudget` thresholds from `contextkit/config.json`
+   (defaults: `yellow: 240`, `red: 308`).
+
+2. **Run the deterministic scan:**
+
+   ```
+   node contextkit/tools/scripts/tech-debt-scan.mjs --json
+   ```
+
+   The scan surfaces mechanical signal — oversized files, "And/Or/E"
+   identifier names, TODO/FIXME/HACK/XXX markers, and (in React/JSX
+   projects only) `useState`/`useEffect` loops. That is the *floor* of the
+   report, not the ceiling.
+
+3. **Apply judgment the regex can't, in tier order:**
+
+   - **Tier 1 first.** Read the code: does the domain depend on
+     infrastructure? Are boundaries respected? Any circular imports or
+     fan-out monsters? Where does state actually live, and does it live
+     once?
+   - **Tier 2 next.** Walk the scanner findings; for each file, decide the
+     *right* fix per H1's preference list (extract a unit with one job,
+     promote inline render functions, lift complex state into a hook,
+     separate layers), not "split at random."
+
+4. **Lead with the right fix, per file.** Name the concrete refactor
+   ("extract the `OrderRepo` port", "lift this state into a hook", "move
+   business math out of the route handler") rather than "this is too big."
+   A Tier-1 finding usually reframes the Tier-2 ones — don't lead with
+   "this file is 320 lines" when the real story is "the domain imports the
+   persistence client."
+
+5. **Honor each rule's "Don't over-apply" clause.** If the clause covers
+   the case, say so and move on. Manufactured findings cost more trust
+   than they save.
+
+6. **Silence is a valid result.** Clean code gets a clean bill. Do not
+   manufacture findings to look thorough.
+
+7. **Route adjacent concerns out, don't smuggle them in.** If during the
+   pass you spot a security/accessibility/privacy/dependency issue, name
+   it briefly and dispatch the relevant agent/command (see *Adjacent
+   concerns* in `best-practices.md`). Don't expand the rubric's lane.
+
+8. **Feed the DevPipeline backlog** with the surviving items,
+   auto-prioritised by severity (BLOCKER → P0, HARD → P1, CANDIDATE → P2,
+   NIT → P3):
+
+   ```
+   node contextkit/tools/scripts/pipeline.mjs add --type chore --priority <P> \
+     --source "practices:<file>" --title "<short fix description>"
+   ```
+
+   `--source` keeps re-runs idempotent. Priorities remain editable
+   (`/pipeline` or `pipeline.mjs prioritize <id> <P>`).
+
+9. **Do not refactor in this command** — it is analysis. Offer to open a
+   focused `/dev-start "refactor <file> by responsibility"` (or `/ship`)
+   on the top item if the user wants to act.
+
+## Report shape
+
+Each finding follows the same shape so reports are scannable and sortable:
+
+```
+path:line — TIER/§ID — SEVERITY — what's wrong — proposed fix
+```
+
+Example findings:
+
+```
+src/api/orders.ts:142 — TIER1/S1 — HARD — controller imports DB client directly — extract an OrderRepo port; inject from edge
+src/state/cart.ts:88  — TIER1/S4 — HARD — cart total cached in 3 components, drifting — derive from one source (one query hook)
+src/ui/Dashboard.tsx  — TIER2/H1 — BLOCKER — 412 lines (> 308) — extract `useDashboardData` hook + promote `renderHeader` to component
+src/lib/helpers.ts:8  — TIER2/H5 — NIT — `arr` carries meaning here — rename to `pendingInvoices`
+```
+
+**Sort by:** tier (1 → 2), then severity (5 → 1), then **blast radius** —
+how far the smell spreads (how many call sites, how exposed the code path
+is). A `BLOCKER` on a widely-imported module beats a `BLOCKER` on a leaf
+utility.
+
+Group findings by file in the final report so the human sees the *file's*
+story, not a flat list.
+
+## Scanner map — what's mechanical vs. what needs judgment
+
+The deterministic scanner (`tech-debt-scan.mjs`) owns the mechanical
+signal; the agent owns everything that needs judgment. The split is honest
+— the rubric does not promise enforcement the scanner cannot deliver.
+
+### Scanner (regex, cheap, exact — runs today)
+
+| Detector               | Rule informed     | Sev    | Notes                                        |
+| ---------------------- | ----------------- | :----: | -------------------------------------------- |
+| `detectLineBudget`     | H1                | 3 / 5  | Yellow ≥ 240, RED > 308 (configurable).      |
+| `detectSrpAnd`         | H2                | 2      | JS/TS `And`/`Or`/`E`; Python `_and_`/`_or_`. |
+| `detectReactStateLoop` | H3 (React/JSX)    | 3      | `> 2 useState + ≥ 1 useEffect`; no-op elsewhere. |
+| `detectTodoMarkers`    | H4 / H6 (debt)    | 1      | `TODO`/`FIXME`/`HACK`/`XXX` in comments.     |
+
+The scanner auto-restricts each detector by file extension; in a project
+with no React, `detectReactStateLoop` is a silent no-op. That is what makes
+the kit stack-agnostic in practice, not just in principle.
+
+**Custom detectors** drop into `contextkit/detectors/*.mjs` and are
+auto-loaded. A broken custom detector is skipped, never blocks the scan
+(constitution, rule 2 — "hooks never break real work").
+
+**`--ci` gate** fails the build on any severity-5 finding. This is the
+hard line the project will not regress past.
+
+**Plug-in slot is the right place for stack-specific detectors** (e.g. a
+project that wants to detect its specific ORM's misuse, or a particular
+secret-naming convention) — add a `*.mjs` file under `contextkit/detectors/`
+exporting a `default` function or a `detectors` array. The kit ships zero
+stack-specific detectors on purpose (constitution, rule 9 — templates
+carry no invented domain content).
+
+### Agent only — judgment, no regex can do it
+
+- **All of Tier 1** (S1 dependency direction, S2 boundaries, S3 coupling
+  and cycles, S4 state location). These require reading import graphs and
+  understanding intent, not pattern-matching strings.
+- **Whether a flagged H1 size is cohesion or rot.** The scanner sees 312
+  lines; only the agent can tell whether they're a dumb constants file or
+  a god component.
+- **The right refactor per file.** "Extract `X`", "lift state into a
+  hook", "promote `renderY` to a component" — these are H1's *Fix*
+  preference list, not the scanner's job.
+- **Whether a Tier-2 violation is relaxable** because the file is a spike
+  or throwaway (see *When this rubric applies*).
+
+### What this protocol deliberately does not promise
+
+- **No `// context-allow §ID: reason` pragma** — not implemented in the
+  scanner. If you find one in someone's proposal, it is aspirational, not
+  honored. (Rule 9: don't ship a speculative half. A future ADR may add it
+  as an atomic change: detector + selfcheck assertion + this doc.)
+- **No import-cycle, secret-pattern, or `any`-counter detection in the
+  kit's default set.** These belong in custom detectors a project adds for
+  itself, or in future ADRs that ship them properly with tests.
+- **No security/AppSec coverage in this rubric.** That is the security-team's
+  lane: `code-security`, `security`, `infra-security` agents; `/audit`,
+  `/deps-audit`, `/security-setup` commands.
+
+Keep this map and `contextkit/config.json` in agreement; keep the whole pair
+of files in sync with `CLAUDE.md` and `best-practices.md`.