contextdevkit 1.8.0

package/templates/contextkit/workflows/L4-squads.md

@@ -0,0 +1,68 @@
+# L4 — Squads of specialized agents
+
+> Level 4. Solves: **"How do we stop every change from falling on a single
+> generalist Claude whose monolithic context dilutes each domain's posture?"**
+
+## The problem
+
+L1–L3 give one agent context and coordination. But a monolithic posture:
+- accumulates rules from very different domains in one `CLAUDE.md`;
+- applies the same mindset to "implement a feature" and "audit a PR against the
+  constitution" — different work;
+- inflates the context loaded for any task.
+
+## The solution: squads of specialized agents
+
+Agents are grouped into **squads** under `contextkit/squads/`, declared by a manifest
+([`contextkit/squads/README.md`](../squads/README.md)). The base squad is `devteam`
+(architect, code-reviewer, context-keeper, test-engineer, …); higher levels add
+`qa-team`, `security-team`, `design-team`, and more. Each agent is a stack-agnostic
+**archetype** you specialize to your project.
+
+## Two tiers — lean executable + rich briefing
+
+| Tier | Path | Consumed by |
+| --- | --- | --- |
+| Executable frontmatter (auto-load) | `.claude/agents/<name>.md` | Claude Code (the orchestrator) |
+| Rich briefing (reference) | `contextkit/squads/<team>/<name>.md` | a human reading; the agent when consulted |
+
+Keeping the briefing out of the agent file keeps the frontmatter compact — fast to
+load, cheap to carry — while the depth stays one hop away. Scaffold a briefing with
+`/squad brief <agent>`; see coverage with `/squad list`.
+
+## How squads are invoked
+
+**Auto-dispatched** — when a task clearly falls in an agent's domain, the main Claude
+delegates via `Agent(subagent_type="<name>")`. The `description` in the agent's
+frontmatter drives selection. *Example: "add input validation to this route" → the
+backend/service agent.*
+
+**Manual** — in orchestration, or when a session needs a specific posture:
+`Agent(subagent_type="code-reviewer", prompt="review this branch against the constitution")`.
+
+**Delegation between agents** — each briefing has a "delegate to" section. An
+implementer hands off to the data/schema specialist for a migration; `code-reviewer`
+dispatches the right specialist to fix what its report found.
+
+## What each agent carries
+
+1. The slice of the **constitution** that applies to its domain.
+2. The **stack points** (libs/configs) it touches — filled per project.
+3. Domain-specific **anti-patterns** (bad vs good examples) in the briefing.
+4. **Delegation triggers** — when to hand off.
+
+## When to update agents
+
+- Constitution changes → revisit `code-reviewer`'s checklist and the "forbidden"
+  sections of the others.
+- New library adopted → add it to the relevant agent's "stack you touch".
+- Anti-pattern discovered → add it to the rich briefing with an example.
+- Squad reorg (merge/split agents, new squad) → an ADR + update the manifest and the
+  delegation tables. Use `/squad` to show, route, or grow the roster.
+
+## Quality criterion
+
+After ~20 sessions using the squad, review: were delegations correct? did an agent
+need to read another's briefing to continue? was any agent never invoked (a fuzzy or
+redundant domain)? did any domain end up ownerless (a gap)? Feed the answers back via
+`/retro` (L6).

package/templates/contextkit/workflows/L5-proactive.md

@@ -0,0 +1,88 @@
+# L5 — Proactive engineering layer
+
+> Level 5. Solves: **"How do we turn 'architecture before syntax' from a posture
+> into executable mechanism — anticipating blast radius and instrumenting code
+> health as versioned artifacts?"**
+
+## The problem
+
+L1–L4 give context, drift detection, multi-session coordination, and a squad. But
+three frictions remain:
+1. **High-blast-radius changes land silently** — no pre-flight analysis.
+2. **The constitution is audited manually and the result vanishes in the chat** — no
+   persistent artifact, so debt grows unseen.
+3. **The system generates memory faster than it distills it** — ledgers and session
+   files accumulate; the boot payload inflates.
+
+## Components
+
+### 1. `/simulate-impact <objective>` — parallel fan-out to the squad
+
+An architectural pre-flight before cross-domain features. It fans `Agent()` out to
+the squad in parallel and aggregates a **Blast Radius Report** shown before any edit.
+It persists a file in `contextkit/memory/predictions/` and marks the ledger via
+`mark-simulation.mjs`. Playbook: [`playbooks/simulate-impact.md`](playbooks/simulate-impact.md).
+
+### 2. `/tech-debt-sweep [profile]` — audit as a versioned artifact
+
+Runs deterministic detectors against the constitution (file-size budget, "And/Or"
+naming, orphan JSDoc, framework state loops) and writes a board under
+`contextkit/memory/`. Profiles are config-driven. CLI: `node
+contextkit/tools/scripts/tech-debt-scan.mjs`. Playbook:
+[`playbooks/tech-debt-sweep.md`](playbooks/tech-debt-sweep.md).
+
+### 3. Contract-drift gate — shift-left on breaking changes
+
+`/contract-check` (`contract-scan.mjs`) compares the public surface declared by
+`contractGlobs` (config) between HEAD and the baseline, flagging removed/renamed
+exports without a `BREAKING CHANGE:` footer. Wire it as a CI job to fail the build.
+
+### 4. PreToolUse gate + staged auto-distill
+
+- **PreToolUse gate** (`contextkit/runtime/hooks/simulate-gate.mjs`) blocks
+  `Edit|Write|MultiEdit` on `highRiskPaths` (config) when this session has no
+  `/simulate-impact` recorded in the ledger. Auditable bypass: a simulation marked
+  `"BYPASS: <reason>"`.
+- **Staged distill** — Stage 0: `check-registration.mjs` archives old registered
+  ledgers (zero risk). Stage 1: `session-start.mjs` observes patterns over the last
+  N sessions and injects an "observed patterns" boot section **without writing to
+  CLAUDE.md**. Stage 2: `/distill-sessions` proposes a CLAUDE.md diff
+  (`.distillation-proposal.md`); `/distill-apply` applies it and records an ADR.
+  Playbook: [`playbooks/distillation-cycle.md`](playbooks/distillation-cycle.md).
+
+### 5. `contextkit/config.json` + `/context-config` — cross-cutting configuration
+
+Replaces hardcoded allowlists, cadences, and L5 parameters. Validated by an optional
+zod schema (dynamic import only — the loader stays zero-dep). Inspect/edit with
+`/context-config show|set`.
+
+## The golden rule
+
+> For any change touching a path in `highRiskPaths`, editing without a
+> `/simulate-impact` recorded in this session's ledger is **forbidden** — not by
+> convention, but by the PreToolUse gate that enforces it. Bypass requires a
+> documented, deliberate act.
+
+## When L5 does NOT apply
+
+- **Bug fixes** — use `/bug-hunt`; there are no feature semantics to simulate.
+- **Refactor with scope locked by `/dev-start`** — the scope is the predictor.
+- **String/i18n/comment/internal rename** — the sweep and contract gate cover what
+  matters; `/simulate-impact` explicitly declines.
+
+## How L5 interacts with L1–L4
+
+| Level | Interaction |
+| --- | --- |
+| L1 | Root `CLAUDE.md` lists the L5 commands. |
+| L2 | L5 extends the ledger schema with `simulations[]`; the PreToolUse gate reads what L2 writes. |
+| L3 | Predictions and the debt board are versioned, so they survive worktrees and parallel sessions. |
+| L4 | `/simulate-impact` consumes the squad **in parallel** — the first feature to fan out, multiplying the ROI of specialization. |
+
+## Calibration over time
+
+`/simulate-impact` predictions get a "predicted vs actual" appendix from
+`/predictions-review` (also run automatically by `/log-session`), which fills each
+prediction's *Actual* section from the ledger; recurring misses refine the command's
+prompts (or become an ADR). Sequential diffs of the debt board show the trend. After
+enough cycles, feed the patterns into `/retro` (L6).

package/templates/contextkit/workflows/README.md

@@ -0,0 +1,47 @@
+# contextkit/workflows — the levels (L1–L6) + playbooks
+
+ContextDevKit's context system operates in **levels**. Each one solves a distinct
+problem of humans + Claude sharing one codebase across many sessions. These docs
+are the *narrative* layer — the **why** and **how it fits together** — behind the
+executable hooks (`contextkit/runtime/hooks/`), slash commands (`.claude/commands/`),
+and config (`contextkit/config.json`).
+
+> These are reference docs; they never run. Behaviour lives in the hooks and
+> scripts — this folder explains the design so a human (or Claude) can reason about
+> it. Keep a doc in sync **in the same change** that alters its mechanism.
+
+## The levels
+
+| Level | Problem it solves | Doc |
+| --- | --- | --- |
+| **L1** | Loading the essentials at boot without the user re-explaining. | [`L1-static-loading.md`](L1-static-loading.md) |
+| **L2** | Detecting that a session touched important files but was never logged. | [`L2-session-ledger.md`](L2-session-ledger.md) |
+| **L3** | Parallel sessions (one dev in many chats, or many devs) without state corruption. | [`L3-multi-session.md`](L3-multi-session.md) |
+| **L4** | Domain delegation via a squad of specialized sub-agents. | [`L4-squads.md`](L4-squads.md) |
+| **L5** | Turning "architecture before syntax" into executable gates (impact, debt, contracts). | [`L5-proactive.md`](L5-proactive.md) |
+| **L6** | Insight, autonomy, and a learning loop on top of the L5 gates. | *capability tier — see below* |
+
+**L6 adds no new hook** — same wiring as L5. It's a capability tier: insight
+(`/context-stats`), autonomy (`/ship`), and a learning loop (`/retro` +
+`/distill-sessions`). See [`docs/ROADMAP.md`](../../docs/ROADMAP.md) for the rationale.
+
+## Playbooks
+
+Files in [`playbooks/`](playbooks/) describe **reusable working procedures** Claude
+follows during a session. Each is the detailed *why / how to read / anti-patterns*
+behind a slash command — the file in `.claude/commands/` is the operational spec;
+the playbook is the judgment around it.
+
+| Playbook | Slash command(s) | What it governs |
+| --- | --- | --- |
+| [`tech-debt-sweep.md`](playbooks/tech-debt-sweep.md) | `/tech-debt-sweep` | Reading the deterministic debt scan; resisting "fix it all". |
+| [`simulate-impact.md`](playbooks/simulate-impact.md) | `/simulate-impact` | Pre-flight blast-radius analysis before high-risk edits. |
+| [`distillation-cycle.md`](playbooks/distillation-cycle.md) | `/distill-sessions` + `/distill-apply` | Turning observed patterns into governed CLAUDE.md rules. |
+| [`security-batch.md`](playbooks/security-batch.md) | `/deep-analysis` + `/deps-audit` | The recurring security sweep and how to triage it. |
+
+## Maintenance
+
+- Keep each doc **lean** and under the constitution's file-size budget (280 lines).
+- These are stack-agnostic on purpose. Project-specific detail belongs in a scoped
+  `CLAUDE.md` or an ADR, not here.
+- A stale workflow doc is worse than none — update it when its mechanism changes.

package/templates/contextkit/workflows/playbooks/distillation-cycle.md

@@ -0,0 +1,74 @@
+# Playbook — Distillation cycle (L5 Stage 2)
+
+> Operational: `.claude/commands/{distill-sessions,distill-apply}.md` + the Stage 2
+> nudge in `check-registration.mjs`. This page is the **end-to-end flow**,
+> **anti-patterns**, and **calibration**.
+
+## The cycle in one sentence
+
+> Stage 1 observes silently. Stage 2 proposes (`/distill-sessions`) and applies with
+> human approval (`/distill-apply`). Each applied cycle becomes an ADR.
+
+## Prerequisites before the first Stage 2
+
+Do **not** run `/distill-sessions` before:
+- several weeks of Stage 1 active;
+- enough registered sessions to have signal;
+- the boot context consistently showing the "observed patterns" section with real
+  data (≥ 2 entries in at least one category).
+
+Earlier than that, Stage 2 produces speculative rules — and a bad rule applied via
+ADR is costlier to remove than to avoid.
+
+## End-to-end flow
+
+```
+[soak] → Stop hook counts registered sessions ≥ proposeAfterSessions → nudge suggests /distill-sessions
+USER runs /distill-sessions
+  → observe patterns · read 5–10 session excerpts · delegate the proposal to context-keeper
+  → write .distillation-proposal.md (gitignored) · show the user
+USER reviews (edits / removes rules)
+USER runs /distill-apply   (or deletes the proposal)
+  → create ADR "Distillation cycle X" · update the ADR index · apply the CLAUDE.md diff
+  → clean up the proposal · show git diff --stat
+USER commits
+[next cycle gated by another soak]
+```
+
+## What makes a good distilled rule
+
+- **Frequency** — ≥ 3 sessions mention the same pattern.
+- **Concreteness** — fits in 1–3 lines in CLAUDE.md.
+- **Non-duplication** — not already in CLAUDE.md or an ADR.
+- **Actionability** — the next session behaves differently because of it.
+- **Mentally testable** — you can picture the error it prevents.
+
+## Anti-patterns
+
+1. **Skipping Stage 1.** Stage 1 feeds Stage 2 statistical signal; without it, Stage
+   2 is an agent guessing — the very anti-pattern L5 avoids.
+2. **Applying without reading the proposal.** The propose/apply split exists to force
+   a read in the middle. Skipping it is applying a diff blind.
+3. **A "rule" that's really an ADR.** If it needs 50 lines to explain, it's an
+   architectural decision — `/new-adr`, then reference it in one line.
+4. **Back-to-back cycles.** The soak window exists so patterns are stable, not
+   emergent. Respect `proposeAfterSessions`.
+5. **Editing the proposal to force a rule the agent rejected.** It was rejected for a
+   reason (contradiction, duplication, vagueness). Ask why; if it still holds, make a
+   direct ADR — don't bypass the check.
+
+## Calibration over time
+
+After ~5 applied cycles: audit reverts (did a rule get contradicted? refine the
+prompts), audit "no-shows" (a Stage 1 pattern that never became a rule — maybe the
+frequency threshold is wrong), and consider a more frequent auto-propose stage only
+after the manual stage has proven itself.
+
+## Relation to `/log-session` and ADRs
+
+| Event | Artifact | Lifecycle |
+| --- | --- | --- |
+| `/log-session` | `contextkit/memory/sessions/<file>.md` | Immutable after creation |
+| `/simulate-impact` | `contextkit/memory/predictions/<file>.md` | Updated by `/log-session` |
+| `/distill-sessions` | `.distillation-proposal.md` | Temporary, gitignored |
+| `/distill-apply` | `contextkit/memory/decisions/NNNN-distillation-cycle-X.md` + CLAUDE.md diff | Permanent, versioned, revertible |

package/templates/contextkit/workflows/playbooks/landing-page.md

@@ -0,0 +1,197 @@
+# Playbook — Landing page & high-conversion sites
+
+> Operational entry: `/landing-page` (the slash command) calls the
+> `landing-architect` briefing, which reads this playbook on every
+> invocation. The SEO + AISO gate (ADR-0025) is mandatory — every
+> public surface goes through `seo-specialist` before this playbook's
+> visual recommendations apply.
+>
+> Authority: [ADR-0023](../../memory/decisions/0023-landing-page-and-conversion-posture.md). Freshness: package recommendations dated **2026-06-02** — re-evaluate quarterly.
+
+## Why this playbook exists
+
+The current generation of AI-generated landing pages has a uniform
+look: gradient hero, three feature cards, three-tier pricing,
+testimonial slider, FAQ accordion, newsletter signup. A savvy visitor
+recognises the pattern in under three seconds, and recognition reads as
+"AI-built" — which reads as "low effort" — which costs conversion on
+the same page that was supposed to convert. This playbook is the kit's
+explicit refusal of that pattern and its substitute.
+
+## Folds — the strategic minimum
+
+| Folds | Use when | Cost of more |
+|---|---|---|
+| **3 (min)** — hero · proof · CTA | utility tool, single-feature, free product with one job-to-be-done | adding more is "while we're here" — every extra fold is friction |
+| **5–7 (ideal, SaaS)** — hero · problem · solution · social proof · pricing/CTA · FAQ · footer-CTA | most SaaS landing pages | beyond 7, recall + scroll-depth fall off; pick the fight you actually need |
+| **9 (max recommended)** — adds: how it works · integrations · founder note | high-ticket B2B where the deal needs more context | beyond 9 you are writing a sales letter; that is a different format |
+
+**Per-fold rule, non-negotiable:**
+
+- **One message.** One thing the visitor should take away.
+- **One action.** One next step that fold invites.
+- **One proof.** When you make a claim, one concrete artefact that
+  makes it credible (a number, a quote, a logo, a screenshot — never
+  three "as featured in" rows).
+
+A fold that does not pass all three is the section to cut.
+
+## Above the fold (the only fold that exists at first)
+
+Hard rules:
+
+- **Value prop ≤ 8 words.** If it does not fit, the message is not
+  sharp yet. "X for Y" / "The Z that does W" / "Verb + outcome" are
+  the shapes that work. Refuse: "Solutions for the modern enterprise",
+  "AI-powered platform for the future of work", "Empower your team to
+  do more with less" — all dead.
+- **One concrete next action.** Not "Learn more" + "See pricing" +
+  "Watch demo" all weighted equally — that is paralysis. Pick the
+  *next* action the visitor's funnel state implies, give it visual
+  weight, demote the rest to text links.
+- **No second-guessing in the headline.** "We help teams" / "We
+  believe" / "We're on a mission" — refuse. The reader does not care
+  about you yet; they care about themselves.
+
+## Anti-Lovable refusals (cookie-cutter patterns the playbook rejects)
+
+Each row: the smell, why it is wrong, the substitute.
+
+| Cookie-cutter | Why it dies | Substitute |
+|---|---|---|
+| Gradient purple-pink hero with centred title + "Get Started" button | recognised in 3 s as AI-generated; signals low effort | editorial layout: a strong point of view in the headline, asymmetric grid, real imagery — Veo/Nano Banana hero (ADR-0024) of the *actual* product or domain |
+| Three feature cards in a row with icon + 2-line description | tells nothing; the icons are decorative; the descriptions are generic | one feature shown in context (screenshot + 1-sentence outcome), repeated 2–3 times, each tied to a real user moment |
+| Three-tier pricing table (Basic / Pro / Enterprise) as default | most products do not have three tiers; the table is performative | start with one price + a "is this for me?" decision tree; if multi-tier, lay out as recommendation engine ("for teams of X → plan Y"), not table |
+| Testimonial slider at the bottom | sliders hide content; visitors do not interact with them | in-context quotes *next to the feature they validate* + a single hero testimonial above the fold with a real photo |
+| FAQ accordion at the bottom | hidden by default; never read; useless for AISO | FAQ as scannable Q&A headings near the relevant section + `FAQPage` JSON-LD schema for AISO (ADR-0025) |
+| Full-width newsletter signup in the footer | nobody signs up for a newsletter from a landing page in 2026 | offer one specific resource (a guide, a calculator, a template) gated by an email — earned, not begged |
+| Generic stock photos of people at laptops | reads as fake; everyone uses the same Unsplash bucket | real product screenshots, custom illustrations, or Veo/Nano Banana renders of the *domain* (ADR-0024) |
+| `Inter` font, `Heroicons` icons, `tailwindui.com` patterns | the "AI tells" of 2026 — recognised instantly | pair a display face (e.g. Fraunces / Schibsted Grotesk / Migra) with a clean body (e.g. Geist / SF Pro Web fallback). Lucide or hand-rolled SVG for icons. |
+
+## Package recommendations — by concern (dated 2026-06-02)
+
+Refresh quarterly. A recommendation that no longer holds gets replaced
+via an ADR-0023 amendment.
+
+### Framework (rendering — load-bearing for SEO/AISO)
+
+| Pick | When |
+|---|---|
+| **Astro** (recommended default) | content-driven landing page, marketing site, blog. SSG by default, islands for interactivity, zero JS shipped for static parts. Indexable by default. |
+| **Next.js App Router** (RSC) | landing page is part of a larger Next app; team already runs Next. Heavier than Astro for pure marketing pages but ergonomically familiar. |
+| **Nuxt** | same shape as Next for Vue teams. |
+| **SvelteKit** | same shape as Next for Svelte teams. |
+| **Plain Vite + React** | **refused** for a landing page. The empty `<div id="root">` SSR payload fails the indexability gate (ADR-0025). Use Astro instead. |
+
+### Styling
+
+| Pick | Notes |
+|---|---|
+| **Tailwind CSS** + **CSS custom properties for tokens** | the unopinionated default. Tokens via `:root { --color-primary: ... }` and Tailwind's `theme.extend` — never raw hex literals in components. |
+| **Material UI, Chakra, NextUI** | **refused as defaults** — too generic; turn every product into the same product. Pick if the design team explicitly wants the trade-off. |
+| **CSS-in-JS (Emotion, styled-components)** | fine technically; pays a runtime cost on every render. Prefer Tailwind for landing pages. |
+
+### Animation
+
+| Pick | When |
+|---|---|
+| **Motion** (formerly Framer Motion) | React/Vue interactions. The default. |
+| **Lenis** | smooth scroll. Adds polish at zero cost for users who prefer reduced motion (respects `prefers-reduced-motion`). |
+| **GSAP** | complex sequenced animations (scroll-driven, sequenced timelines). Pay the licence if commercial. |
+| **View Transitions API** | route transitions, expanding cards. Astro + Next + Nuxt all wire it up. |
+
+### Typography
+
+| Pick | Notes |
+|---|---|
+| **Fontsource** | self-host any Google Font. No `<link>` to fonts.googleapis.com (GDPR + performance). |
+| **`@next/font` / Astro Fonts** | same, framework-native. |
+| **`Inter` as the only face** | **refused as default** — became the Helvetica of 2025; signals "AI-built". Pair a display face with a clean body. |
+
+### Icons
+
+| Pick | Notes |
+|---|---|
+| **Lucide** | clean, consistent, tree-shakeable. The default. |
+| **Hand-rolled SVG** | when the brand justifies it. |
+| **Heroicons** | **refused as default** — too tied to Tailwind UI templates. |
+
+### Forms
+
+| Pick | Notes |
+|---|---|
+| **react-hook-form + zod** | unopinionated, type-safe, zero re-render cost. |
+| **Form backend**: **Formspree**, **Convex**, or a server route. Pick by what the rest of the project uses. |
+
+### Analytics
+
+| Pick | Notes |
+|---|---|
+| **Plausible** | privacy-first, GDPR-OK, lightweight (1 KB script). RUM-friendly for Core Web Vitals. The default. |
+| **Vercel Analytics** | if already on Vercel. Web Vitals included. |
+| **GA4** | **refused as default** — heavy, ugly DX, GDPR-fragile. Pick when the stakeholder requires it. |
+
+### Experimentation
+
+| Pick | Notes |
+|---|---|
+| **GrowthBook** | self-hostable, OSS, feature flags + A/B. The kit's recommended option (user preference recorded in memory). |
+| **PostHog** | if already running PostHog for product analytics. |
+
+### Imagery & video
+
+| Pick | Notes |
+|---|---|
+| **`/media-gen`** (the kit) | Veo for video, Nano Banana for image — ADR-0024. Domain-specific renders instead of stock. |
+| **Unsplash API** | placeholders while iterating. Replace before launch. |
+
+## Performance budget (Core Web Vitals are a ranking signal)
+
+Targets:
+
+- **LCP < 2.5 s** (Largest Contentful Paint)
+- **INP < 200 ms** (Interaction to Next Paint — replaced FID)
+- **CLS < 0.1** (Cumulative Layout Shift)
+- **First-fold JS < 100 kB compressed**
+
+Measure with:
+
+- **PageSpeed Insights** during development
+- **Lighthouse CI** on every PR
+- **Plausible** or **Vercel Analytics** for real-user metrics post-launch
+
+A landing page that fails any of these in lab measurement is a refusal
+on this playbook + a finding in `seo-audit.mjs`.
+
+## Indexability gate (cross-link)
+
+Every public route the user wants indexed goes through
+[`seo-aiso.md`](seo-aiso.md) before this playbook's visual
+recommendations apply. The gate refuses:
+
+- Plain client-rendered SPAs (no SSR/SSG).
+- Pages with `<title>` set in JS.
+- Routes missing `<link rel="canonical">`.
+- Sites without `sitemap.xml`, `robots.txt`, or `llms.txt` at the root.
+
+The override path is a project-local ADR explicitly carving out the
+surface (e.g. "internal admin tool — no SEO needed").
+
+## Freshness protocol
+
+Package recommendations decay. This playbook's rec table carries a
+date (top of the file). When that date is more than 90 days old,
+`seo-specialist` and `landing-architect` are licensed to override the
+rec inline with a one-line note, and an amendment ADR is filed if the
+override would be permanent.
+
+## When this playbook does NOT apply
+
+- **Internal tools / admin dashboards** — no indexability gate, no
+  conversion focus. Use `ui-designer` + `ux-designer` directly.
+- **Documentation sites** — different posture; SSG-by-default is the
+  same but the playbook's hero / fold rules do not apply. Use a docs-
+  specific frame (Astro Starlight, Nextra, Docusaurus).
+- **Web apps with a marketing wrapper** — the marketing page follows
+  this playbook; the app inside does not. Keep them on separate
+  routes / subdomains so the SEO posture is unambiguous.

package/templates/contextkit/workflows/playbooks/security-batch.md

@@ -0,0 +1,68 @@
+# Playbook — Security batch (recurring security sweep)
+
+> Operational specs: [`.claude/commands/deep-analysis.md`](../../../.claude/commands/deep-analysis.md)
+> and [`.claude/commands/deps-audit.md`](../../../.claude/commands/deps-audit.md).
+> This page is the **why**, the **recurring rhythm**, and how to **triage** the output.
+
+## Why it exists
+
+Security review tends to happen reactively — after an incident, or never. A *batch*
+turns it into a scheduled, artifact-producing sweep, so risk is found before it ships
+and the findings live in the backlog, not in a lost chat.
+
+The kit makes security **active, not reactive**: a SessionStart trigger reminds you
+to run `/deep-analysis` every N sessions (`securityMode.everyNSessions`, on by
+default). This playbook is what you do when that reminder fires — or before a release
+that touches a sensitive surface.
+
+## The batch, in order
+
+1. **Dependency & supply chain** — `/deps-audit`: lockfile present and respected,
+   versions pinned, known CVEs, license posture. Owned by the **security-team**
+   (`security` for AppSec, `infra-security` for IaC/cloud, `devops` for delivery).
+2. **Global sweep** — `/deep-analysis`: aggregates every deterministic scanner
+   (tech-debt, deps, contract) into one report, then adds judgment — a security pass,
+   an architecture pass, a bug pass.
+3. **Triage into the backlog** — every finding becomes a DevPipeline task
+   (`/pipeline`) with a severity (S1–S4) and an SLA, so nothing is "noted and
+   forgotten".
+4. **Promote the systemic ones to ADRs** — a recurring class of finding (not a
+   one-off) is a decision, not a ticket: `/new-adr`.
+
+## How to triage
+
+- **Severity over volume.** One S1 (auth bypass, secret exposure, RCE) outranks
+  twenty nits. Sort by blast radius, not by count.
+- **Trust boundaries first.** Findings at input boundaries (auth, deserialization,
+  external webhooks, file upload) outrank internal hygiene.
+- **A scanner finding is a lead, not a verdict.** Deterministic scanners produce
+  false positives; confirm before filing an S1.
+- **Pin the fix to an owner.** Each accepted finding → a backlog task with an owner
+  and an SLA, or an explicit, recorded "won't fix (why)".
+
+## Anti-patterns
+
+1. **Running the batch and never triaging.** A report nobody turns into tasks is
+   theatre. The deliverable is backlog items, not a markdown file.
+2. **Fixing low-severity nits while an S1 waits.** Severity ordering is the whole
+   point.
+3. **Suppressing a CVE by ignoring the advisory.** Upgrade, replace, or record an
+   accepted-risk decision with an expiry — never silently mute.
+4. **Treating every finding as an ADR.** One-offs are tickets; only the recurring,
+   systemic class earns an ADR.
+5. **Disabling security mode "because it's noisy".** Tune `everyNSessions` instead;
+   turning it off removes the signal exactly when it matters.
+
+## Cadence & configuration
+
+`securityMode` lives in `contextkit/config.json` (`active`, `everyNSessions`). Tune via
+`/context-config set`. Pair the batch with a release: run it before closing a version
+(`/close-version`) that touched auth, crypto, dependencies, or infra.
+
+## Relation to other components
+
+- **`/tech-debt-sweep`** — health vs security: the sweep's `security` profile is a
+  fast pre-filter; the batch is the deep pass.
+- **`/simulate-impact`** — fire it before implementing a fix on a high-risk path.
+- **Contract-drift gate** — a security fix that changes a public signature still
+  needs a `BREAKING CHANGE:` footer.