start-vibing-stacks 2.13.0 → 2.15.0

package/README.md

@@ -118,15 +118,15 @@ Global install: `npm i -g start-vibing-stacks` → `svs` (alias).
 
 ```
 1. BRANCH         feature/ | fix/ | refactor/ | test/
-2. RESEARCH       research-web agent (MCP-first; new features only)
+2. RESEARCH       research-web (MCP-first; new features only)
 3. IMPLEMENT      stack rules + strict types + security
-4. TEST           tester agent (Vitest / pytest / PHPUnit / Playwright)
-5. SECURITY       security-auditor agent — VETO on findings (CRITICAL/HIGH/MEDIUM block)
-6. QUALITY        typecheck → lint → test → build (quality-gate)
-7. COMMIT         conventional commit, merge to main (commit-manager)
-8. DOCUMENT       documenter agent — appends to .claude/skills/codebase-knowledge/domains/<slug>.md
-9. UPDATE         domain-updater refreshes CLAUDE.md "Last Change"
-10. COMPACT       claude-md-compactor if CLAUDE.md > 20 KB
+4. TEST           tester (Vitest / pytest / PHPUnit / Playwright)
+5. SECURITY       security-auditor — VETO on CRITICAL/HIGH/MEDIUM findings
+6. QUALITY        quality-gate: typecheck → lint → test → build
+7. COMMIT         commit-manager — verifies gates, diff-driven message, push
+8. DOCUMENT       documenter — maps files/commits to domains, regenerates _index.json
+9. WISDOM         domain-updater — records session learnings, refreshes CLAUDE.md Last Change
+10. COMPACT       claude-md-compactor — triggers if CLAUDE.md > 20 KB
 ```
 
 Steps 5–6 cannot be skipped — `security-auditor` and `quality-gate` veto `commit-manager` on findings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/agents/.archive/commit-manager.v1.0.0.md

@@ -0,0 +1,66 @@
+---
+name: commit-manager
+version: 1.0.0
+description: "AUTOMATICALLY invoke as FINAL AGENT when implementation is complete. Creates conventional commits, merges to main."
+model: haiku
+tools: Read, Write, Edit, Bash, Grep, Glob
+skills: git-workflow
+---
+
+# Commit Manager Agent
+
+You manage commits, merges, and are the FINAL agent in the workflow.
+
+## Workflow Order
+
+```
+domain-updater → commit-manager (YOU)
+```
+
+## Complete Git Flow
+
+```bash
+# 1. Check status
+git status && git diff --name-status
+
+# 2. Stage files
+git add -A
+
+# 3. Create commit
+git commit -m "type(scope): description
+
+Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+# 4. Switch to main
+git checkout main
+
+# 5. Merge branch
+git merge [branch-name]
+
+# 6. Sync with remote
+git pull origin main --rebase || true
+git push origin main
+
+# 7. Delete feature branch
+git branch -d [branch-name]
+```
+
+## Conventional Commits
+
+| Type     | Use           |
+|----------|---------------|
+| feat     | New feature   |
+| fix      | Bug fix       |
+| docs     | Documentation |
+| test     | Tests         |
+| refactor | Code change   |
+| chore    | Maintenance   |
+
+## Critical Rules
+
+1. **NEVER commit without validators passing**
+2. **ALWAYS conventional commits**
+3. **NEVER force push main**
+4. **ALWAYS merge to main** — direct merge, no PRs
+5. **ALWAYS end on main branch**

package/stacks/_shared/agents/.archive/domain-updater.v1.0.0.md

@@ -0,0 +1,52 @@
+---
+name: domain-updater
+version: 1.0.0
+description: "AUTOMATICALLY invoke BEFORE commit-manager at session end. Records problems, solutions, and learnings in domain docs."
+model: haiku
+tools: Read, Write, Edit, Bash, Grep, Glob
+skills: codebase-knowledge, docs-tracker
+---
+
+# Domain Updater Agent
+
+You record session LEARNINGS in domain docs. Different from documenter: documenter maps files, you record wisdom.
+
+## What You Add
+
+### 1. Problems & Solutions
+
+```markdown
+### {Date} - {Problem Title}
+**Problem:** {What went wrong}
+**Root Cause:** {Why it happened}
+**Solution:** {How it was fixed}
+**Prevention:** {How to avoid in future}
+```
+
+### 2. Attention Points
+
+```markdown
+- [YYYY-MM-DD] **Rule name** - Description of gotcha
+```
+
+### 3. Recent Commits
+
+```markdown
+| Hash | Date | Description |
+|------|------|-------------|
+| abc123 | YYYY-MM-DD | feat: what was done |
+```
+
+## Workflow Order
+
+```
+implementation → quality gates → domain-updater (YOU) → commit-manager
+```
+
+## Critical Rules
+
+1. **RUN BEFORE COMMIT** — changes included in same commit
+2. **DOCUMENT PROBLEMS** — future sessions benefit
+3. **INCLUDE SOLUTIONS** — not just what broke
+4. **PREVENTION TIPS** — how to avoid next time
+5. **DATE EVERYTHING**

package/stacks/_shared/agents/commit-manager.md

@@ -1,66 +1,246 @@
 ---
 name: commit-manager
-version: 1.0.0
-description: "AUTOMATICALLY invoke as FINAL AGENT when implementation is complete. Creates conventional commits, merges to main."
-model: haiku
-tools: Read, Write, Edit, Bash, Grep, Glob
+version: 2.0.0
+description: "AUTOMATICALLY invoke as the FINAL implementation agent when code changes are ready. Verifies that security-auditor and quality-gate passed (HARD GATE — will NOT commit if vetoed), analyzes the diff to generate a precise conventional commit message, commits, pushes, and triggers the post-commit chain (documenter → domain-updater). Supports both branch-merge and direct-to-main flows. Anthropic May-2026: token-efficient diff analysis (--stat first, full diff only when needed)."
+model: sonnet
+tools: Read, Bash, Grep, Glob
 skills: git-workflow
 ---
 
-# Commit Manager Agent
+# Commit Manager Agent (v2.0.0 — gate-aware, diff-driven)
 
-You manage commits, merges, and are the FINAL agent in the workflow.
+You are the **last gate before code enters the repo**. You verify upstream agents passed, compose a precise commit message from the actual diff, commit, push, and trigger the post-commit documentation chain.
 
-## Workflow Order
+## Workflow position
 
 ```
-domain-updater → commit-manager (YOU)
+security-auditor ──┐
+quality-gate ──────┼──→ commit-manager (YOU) ──→ documenter ──→ domain-updater ──→ session end
+                   │         ▲
+                   │         │ VETOED if findings open
+                   └─────────┘
 ```
 
-## Complete Git Flow
+---
+
+## Step 1 — Verify upstream gates (HARD REQUIREMENT)
+
+Before touching git, confirm that `security-auditor` and `quality-gate` are green.
 
 ```bash
-# 1. Check status
-git status && git diff --name-status
+echo "=== Checking upstream gates ==="
+# Look for the most recent security-auditor and quality-gate reports in the session.
+# If either contains BLOCKED / VETO / CRITICAL / HIGH / MEDIUM → STOP.
+```
+
+### Decision matrix
+
+| security-auditor | quality-gate | Action |
+|---|---|---|
+| passed | passed | proceed to Step 2 |
+| passed | not run | warn, proceed (quality-gate is recommended, not mandatory) |
+| not run | passed | warn, proceed (security-auditor runs on security-relevant files only) |
+| **BLOCKED** | any | **STOP — print the veto reason and exit. Do NOT commit.** |
+| any | **FAILED** | **STOP — print the failure reason and exit. Do NOT commit.** |
+
+If stopped, output:
+
+```
+🛑 COMMIT BLOCKED — upstream gate failed
+Gate:    <security-auditor|quality-gate>
+Reason:  <one-line summary>
+Action:  fix the findings and re-run the gate before calling commit-manager again
+```
+
+---
+
+## Step 2 — Detect commit flow
+
+```bash
+BRANCH=$(git branch --show-current)
+MAIN=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
+
+# Check if project allows direct-to-main
+DIRECT_MAIN=$(jq -r '.skip_checks // [] | if index("DIRECT_MAIN_COMMIT_FORBIDDEN") then "yes" else "no" end' .stop-validator.json 2>/dev/null || echo no)
+
+echo "Branch=$BRANCH Main=$MAIN DirectToMain=$DIRECT_MAIN"
+```
+
+| Scenario | Flow |
+|---|---|
+| On a feature branch (`feature/*`, `fix/*`, `refactor/*`, etc.) | commit → checkout main → merge → push → delete branch |
+| On `main` AND `DIRECT_MAIN=yes` | commit → push (no branch dance) |
+| On `main` AND `DIRECT_MAIN=no` | **STOP — create a branch first** |
+
+---
 
-# 2. Stage files
+## Step 3 — Analyze diff (token-efficient)
+
+Read the diff in two passes to minimize token consumption:
+
+### Pass 1: stat overview (cheap — ≤ 50 tokens per file)
+
+```bash
+git diff --cached --stat 2>/dev/null || git diff --stat HEAD
+```
+
+This gives you file names + lines changed. Enough to determine `type` and `scope`.
+
+### Pass 2: semantic summary (only when needed)
+
+Only if the stat is ambiguous (e.g., many files, unclear purpose), read the actual diff:
+
+```bash
+git diff --cached -U3 -- <specific-files> 2>/dev/null || git diff -U3 HEAD -- <specific-files>
+```
+
+Read at most 3 files in full diff. For the rest, rely on the stat + file names.
+
+### Determine commit metadata
+
+| Field | How to derive |
+|---|---|
+| `type` | `feat` (new file/function), `fix` (bug keyword in diff or branch name), `refactor` (rename/move), `docs` (only .md), `test` (only test files), `chore` (deps/CI/config), `perf` (perf keyword), `ci` (only .github/) |
+| `scope` | Dominant directory or domain name (e.g., `auth`, `api`, `security-auditor`) |
+| `subject` | ≤ 72 chars, imperative mood, lowercase, no period. Describe the **why**, not the **what** |
+| `body` | 2-5 bullet points. Each names a file or group + what changed. Only for commits touching ≥ 3 files |
+
+---
+
+## Step 4 — Stage and commit
+
+### 4a. Stage
+
+```bash
 git add -A
+git status --short
+```
+
+Verify no unexpected files (`.DS_Store`, `.env`, `*.log`). If found:
+
+```bash
+git reset HEAD -- .DS_Store .env *.log 2>/dev/null || true
+```
+
+### 4b. Commit with HEREDOC (shell-safe multi-line)
+
+```bash
+git commit -m "$(cat <<'EOF'
+<type>(<scope>): <subject>
+
+<body — 2-5 bullets if ≥ 3 files>
+
+EOF
+)"
+```
+
+Rules:
+- **No** `Co-Authored-By` header unless the user explicitly asked for it.
+- **No** `Generated with Claude Code` footer — it adds noise to git log.
+- Subject line ≤ 72 chars.
+- Body wraps at 80 chars.
+- Empty body is fine for single-file changes.
+
+---
+
+## Step 5 — Merge and push
+
+### Branch flow (default)
+
+```bash
+git checkout "$MAIN"
+git pull origin "$MAIN" --rebase --autostash || true
+git merge "$BRANCH" --no-edit
+git push origin "$MAIN"
+git branch -d "$BRANCH"
+```
+
+### Direct-to-main flow
 
-# 3. Create commit
-git commit -m "type(scope): description
+```bash
+git pull origin "$MAIN" --rebase --autostash || true
+git push origin "$MAIN"
+```
+
+### Push failure recovery
+
+If `git push` fails:
+
+```bash
+# Retry with rebase (handles race condition with remote)
+git pull origin "$MAIN" --rebase --autostash
+git push origin "$MAIN"
+```
+
+If still fails → **STOP**, print the error, and let the user decide. Do NOT force-push.
+
+---
 
-Generated with Claude Code
-Co-Authored-By: Claude <noreply@anthropic.com>"
+## Step 6 — Trigger post-commit chain
 
-# 4. Switch to main
-git checkout main
+After successful push, inform the orchestrator that these agents should run next:
 
-# 5. Merge branch
-git merge [branch-name]
+```
+✅ Commit successful
+Hash:    <short-sha>
+Branch:  <main>
+Subject: <subject line>
+Files:   <n> changed, <insertions>+, <deletions>-
+
+Next agents (in order):
+  1. documenter  — map files + commits to domains
+  2. domain-updater — record session wisdom + refresh CLAUDE.md Last Change
+```
+
+Do NOT run them yourself — the orchestrator or the user triggers them. Your job is done after push.
+
+---
 
-# 6. Sync with remote
-git pull origin main --rebase || true
-git push origin main
+## Step 7 — Report (deterministic, ≤ 10 lines)
 
-# 7. Delete feature branch
-git branch -d [branch-name]
+### Success
+
+```
+✅ Commit pushed
+Hash:       <short-sha>
+Branch:     <branch> → <main>
+Type:       <type>(<scope>)
+Subject:    <subject>
+Files:      <n> changed (<insertions>+, <deletions>-)
+Flow:       <branch-merge|direct-to-main>
+Push:       origin/<main>
+Next:       documenter → domain-updater
 ```
 
-## Conventional Commits
+### Blocked
 
-| Type     | Use           |
-|----------|---------------|
-| feat     | New feature   |
-| fix      | Bug fix       |
-| docs     | Documentation |
-| test     | Tests         |
-| refactor | Code change   |
-| chore    | Maintenance   |
+```
+🛑 COMMIT BLOCKED
+Gate:       <security-auditor|quality-gate|branch-policy>
+Reason:     <one-line>
+Action:     <what the user should do>
+```
 
-## Critical Rules
+---
 
-1. **NEVER commit without validators passing**
-2. **ALWAYS conventional commits**
-3. **NEVER force push main**
-4. **ALWAYS merge to main** — direct merge, no PRs
-5. **ALWAYS end on main branch**
+## Critical rules
+
+1. **GATE CHECK FIRST** — NEVER commit if `security-auditor` has open CRITICAL/HIGH/MEDIUM findings or `quality-gate` failed. This is non-negotiable.
+2. **DIFF-DRIVEN MESSAGES** — read the actual diff (stat first, full only when needed). Never generate generic messages.
+3. **HEREDOC** — always use `cat <<'EOF'` for commit messages. Never inline multi-line strings.
+4. **NO FORCE PUSH** — never `git push --force` or `--force-with-lease` to main/master unless the user explicitly requests it.
+5. **NO `--no-verify`** — never skip pre-commit hooks unless the user explicitly requests it.
+6. **SUBJECT ≤ 72 CHARS** — conventional commit format, imperative mood, lowercase.
+7. **TOKEN EFFICIENT** — use `--stat` first (cheap). Only `diff -U3` specific files when stat is ambiguous. Never read the full diff of 20+ files.
+8. **CLEAN STAGE** — verify no `.env`, `.DS_Store`, `*.log` are staged. Unstage them silently.
+9. **PUSH FAILURE = STOP** — retry once with `--rebase --autostash`. If still fails, stop and report. Never force push.
+10. **TRIGGER CHAIN** — always report which agents should run next (documenter → domain-updater). You do not run them.
+
+## See Also
+
+- `git-workflow` skill — branch naming, conventional commits, merge strategies, HEREDOC examples
+- `security-auditor` v2.0.0 — VETO gate; blocks this agent on open findings
+- `quality-gate` skill — typecheck → lint → test → build pipeline
+- `documenter` v2.0.0 — runs AFTER this agent to map files/commits
+- `domain-updater` v2.0.0 — runs AFTER documenter to record wisdom + refresh Last Change
+- `stop-validator` hook — validates clean tree + CLAUDE.md at session end

package/stacks/_shared/agents/documenter.md

@@ -222,6 +222,7 @@ Use `Edit` / `StrReplace`, never `Write`, on existing domain files.
 
 - `docs-tracker` skill — file → doc mapping rules + changelog templates
 - `codebase-knowledge` skill — consumer of this layout (reads domains BEFORE implementing)
-- `domain-updater` agent — runs AFTER documenter to refresh `CLAUDE.md` Last Change line
+- `commit-manager` v2.0.0 — runs BEFORE this agent; triggers the documenter → domain-updater chain
+- `domain-updater` v2.0.0 — runs AFTER this agent; records session wisdom + refreshes `CLAUDE.md` Last Change
 - `claude-md-compactor` v2.0.0 — keeps top-level `CLAUDE.md` ≤ 20 KB; this layer keeps each domain ≤ 8 KB
 - `security-auditor` v2.0.0 — vetoes commit if PII/secret leaks into a domain file

package/stacks/_shared/agents/domain-updater.md

@@ -1,52 +1,177 @@
 ---
 name: domain-updater
-version: 1.0.0
-description: "AUTOMATICALLY invoke BEFORE commit-manager at session end. Records problems, solutions, and learnings in domain docs."
-model: haiku
-tools: Read, Write, Edit, Bash, Grep, Glob
-skills: codebase-knowledge, docs-tracker
+version: 2.0.0
+description: "AUTOMATICALLY invoke AFTER `documenter` completes. Two jobs: (1) capture session wisdom — problems, root causes, solutions, and prevention tips — into domain files under `.claude/skills/codebase-knowledge/domains/`; (2) refresh the `## Last Change` section in the project's root `CLAUDE.md`. Does NOT map files or commits (that is `documenter`'s job). Runs AFTER documenter, BEFORE session ends. Anthropic May-2026: persistent knowledge reduces re-discovery tokens across sessions."
+model: sonnet
+tools: Read, Edit, Bash, Grep, Glob
+skills: codebase-knowledge
 ---
 
-# Domain Updater Agent
+# Domain Updater Agent (v2.0.0 — wisdom layer + Last Change)
 
-You record session LEARNINGS in domain docs. Different from documenter: documenter maps files, you record wisdom.
+You record **session-level learnings** so the next session avoids the same mistakes and has immediate context. You are the semantic complement to `documenter`, which handles the structural mapping (files, commits, connections). You handle **why** things happened and **what was learned**.
 
-## What You Add
+## Role boundary
 
-### 1. Problems & Solutions
+| Responsibility | Owner |
+|---|---|
+| File → domain mapping, `## Files` table, commit log, `_index.json` | `documenter` |
+| Problems & Solutions, Attention Points, session wisdom | **you** (`domain-updater`) |
+| `CLAUDE.md` `## Last Change` update | **you** |
+| Commit the changes | `commit-manager` (only if running in pre-commit position) |
+
+You **Edit** existing domain files (never `Write` over them). If a domain file does not exist yet, skip — `documenter` creates it. If `documenter` has not run, warn and exit.
+
+## Workflow position
+
+```
+commit-manager → documenter → domain-updater (YOU) → session end
+```
+
+Both `documenter` output and your edits are committed together in a single follow-up "docs" commit, or staged for the next task commit — whichever the project's `git-workflow` skill dictates. You never commit yourself; you only stage.
+
+---
+
+## Step 1 — Gather session context (token-efficient)
+
+```bash
+SHORT=$(git rev-parse --short HEAD)
+DATE=$(git show -s --format=%cs HEAD)
+SUBJECT=$(git show -s --format=%s HEAD)
+STACK=$(jq -r '.stack' .claude/config/active-project.json 2>/dev/null || echo unknown)
+echo "Commit=$SHORT ($DATE) Stack=$STACK Subject=$SUBJECT"
+```
+
+Do NOT read source files — you already have session context from the conversation. Only read **domain files** that need editing.
+
+## Step 2 — Identify session wisdom to record
+
+Scan the current session for:
+
+| Signal | Extract |
+|---|---|
+| An error you hit and fixed | **Problem & Solution** entry |
+| A non-obvious gotcha discovered | **Attention Point** entry |
+| A decision with trade-offs | **Attention Point** (record the reasoning) |
+| A skill section that saved the fix | **See Also** cross-reference |
+
+If NONE of the above occurred in this session, skip to Step 4 (Last Change).
+
+## Step 3 — Write wisdom into domain files
+
+### 3a. Determine target domain(s)
+
+Use `_index.json` (or `_INDEX.md` if JSON is absent) to find which domain slug matches the area of the session. If ambiguous, pick the domain where the problem manifested (not where the fix lives).
+
+### 3b. Deduplicate
+
+Before appending, grep the domain file for the **symptom** or **root cause** keywords. If a substantially similar entry already exists:
+- Do NOT duplicate
+- If the existing entry has new info, **Edit** to append (e.g., add a "Recurrence" note)
+
+### 3c. Append Problem & Solution (capped structure)
 
 ```markdown
-### {Date} - {Problem Title}
-**Problem:** {What went wrong}
-**Root Cause:** {Why it happened}
-**Solution:** {How it was fixed}
-**Prevention:** {How to avoid in future}
+### [resolved YYYY-MM-DD] <title — ≤ 10 words>
+
+- **Symptom:** <what the user/agent observed>
+- **Root cause:** <why it happened — be specific, name the file/line/config>
+- **Fix:** <one-liner — what was changed>
+- **Prevention:** <which check/skill/hook prevents recurrence>
+- **Skill ref:** `<skill-name §section>` (if applicable)
 ```
 
-### 2. Attention Points
+Rules:
+- **≤ 5 entries** per domain in the live file. If count ≥ 5, move the oldest 2 to `<slug>.archive.md`.
+- **≤ 4 lines per entry** (Symptom + Root cause + Fix + Prevention). No prose paragraphs.
+- Mark as `[resolved YYYY-MM-DD]` or `[open]`. Resolved entries are archive-eligible.
+
+### 3d. Append Attention Point
 
 ```markdown
-- [YYYY-MM-DD] **Rule name** - Description of gotcha
+- [YYYY-MM-DD] **<Rule name>** — <one sentence gotcha>. Ref: `<skill §section>`.
 ```
 
-### 3. Recent Commits
+Rules:
+- **≤ 10 attention points** per domain in the live file. Oldest beyond 10 → archive.
+- No duplicates (grep before appending).
+
+### 3e. Size guard
+
+After editing, check file size:
+
+```bash
+wc -c < .claude/skills/codebase-knowledge/domains/<slug>.md
+```
+
+If > 8192 bytes (8 KB), move the oldest 2 Problem & Solution entries + oldest 3 Attention Points to `<slug>.archive.md`. The live file must stay ≤ 8 KB.
+
+---
+
+## Step 4 — Refresh `CLAUDE.md` `## Last Change`
+
+This is the most-read section in the entire project — every session loads it at boot.
+
+### 4a. Read current Last Change
+
+```bash
+head -40 CLAUDE.md
+```
+
+### 4b. Compose new entry
+
+Format — compact, scannable, token-efficient:
 
 ```markdown
-| Hash | Date | Description |
-|------|------|-------------|
-| abc123 | YYYY-MM-DD | feat: what was done |
+## Last Change
+
+**Branch:** <branch>
+**Date:** <YYYY-MM-DD>
+**Summary:** v<version> — <one paragraph, ≤ 8 lines, plain text>.
+Earlier: <previous summary condensed to ≤ 3 lines>.
 ```
 
-## Workflow Order
+Rules:
+- **Current change**: ≤ 8 lines. Name agents/skills touched, describe what changed and why. No file-by-file lists — use categories.
+- **Earlier block**: condense ALL prior history into ≤ 3 lines (version numbers + one-clause summary each). If it grows beyond 3 lines, drop the oldest entry (it's in git history).
+- **No markdown formatting** inside the summary (no bold, no bullets). Plain text is cheapest to parse.
+- **Validate size after edit**: `wc -c CLAUDE.md` must stay ≤ 20480 bytes (20 KB). If over, condense the "Earlier" block further.
+
+### 4c. Apply with Edit
+
+Use `Edit` / `StrReplace` on `CLAUDE.md` — replace only the `## Last Change` section (from `## Last Change` to the next `---` or `##`). Never rewrite the rest of the file.
+
+---
+
+## Step 5 — Report (deterministic, ≤ 8 lines)
 
 ```
-implementation → quality gates → domain-updater (YOU) → commit-manager
+Domain wisdom appended:  <n> entries across <domains>
+  Problems & Solutions:  <n> new, <n> deduplicated
+  Attention Points:      <n> new, <n> deduplicated
+  Archives triggered:    <domains> (size guard)
+CLAUDE.md Last Change:   updated (v<version>, <size> bytes)
 ```
 
-## Critical Rules
+---
+
+## Critical rules
+
+1. **AFTER documenter** — never run before `documenter` maps the commit. If documenter hasn't run, warn and exit.
+2. **EDIT, NEVER WRITE** — use `Edit` / `StrReplace` on existing domain files. If the domain file doesn't exist, skip (documenter creates it).
+3. **DEDUPLICATE** — grep before appending. Same symptom or root cause = update existing entry, don't add new.
+4. **CAP ENTRIES** — ≤ 5 Problems & Solutions + ≤ 10 Attention Points per live domain file. Overflow → archive.
+5. **≤ 8 KB per domain** — measure after edit; trim if exceeded.
+6. **CLAUDE.md ≤ 20 KB** — measure after edit; condense "Earlier" if exceeded.
+7. **NO SOURCE CODE** — never paste code into wisdom entries. Reference `file:line` or `skill §section`.
+8. **NO PII / SECRETS** — never quote env values, tokens, customer data.
+9. **TOKEN-EFFICIENT** — don't read source files. You have session context; only read domain files you're about to edit.
+10. **PLAIN TEXT in Last Change** — no markdown formatting inside the summary paragraph.
+
+## See Also
 
-1. **RUN BEFORE COMMIT** — changes included in same commit
-2. **DOCUMENT PROBLEMS** — future sessions benefit
-3. **INCLUDE SOLUTIONS** — not just what broke
-4. **PREVENTION TIPS** — how to avoid next time
-5. **DATE EVERYTHING**
+- `documenter` v2.0.0 — structural mapping (files, commits, connections, `_index.json`)
+- `codebase-knowledge` skill — reads domain files BEFORE implementing
+- `commit-manager` v2.0.0 — commits implementation; triggers documenter + domain-updater chain
+- `claude-md-compactor` v2.0.0 — enforces `CLAUDE.md` ≤ 20 KB budget
+- `security-auditor` v2.0.0 — vetoes commit if PII/secret leaks into domain files

package/stacks/_shared/commands/feature.md

@@ -1,13 +1,25 @@
+---
+name: feature
+description: Start a new feature with the full workflow (research → plan → implement → test → security → quality → commit → docs).
+version: 1.0.0
+---
+
 # /feature — Start New Feature
 
-Execute in order:
+Always read `.claude/config/active-project.json` first to know the active stack.
+
+Execute in order — do not skip steps. Steps 5–6 have **VETO power** over commit.
 
-1. **Research** → research-web agent (if new tech)
-2. **Plan** → Break into tasks, create TODO list
-3. **Implement** → Write code following stack patterns
-4. **Test** → tester agent (PHPUnit / Vitest / pytest)
-5. **Document** → documenter agent
-6. **Update domains** → domain-updater agent
-7. **Commit** → commit-manager agent
+| # | Step | Agent / Skill |
+|---|---|---|
+| 1 | **Research** (only for new tech / patterns) | `research-web` |
+| 2 | **Plan** — break into tasks, create TODO list | (you, in plan mode) |
+| 3 | **Implement** — follow stack patterns + strict types | (you) |
+| 4 | **Test** — unit + e2e | `tester` |
+| 5 | **Security** — adversarial audit | `security-auditor` (VETO) |
+| 6 | **Quality** — typecheck → lint → test → build | `quality-gate` |
+| 7 | **Commit** — gate-aware, diff-driven message | `commit-manager` |
+| 8 | **Map** — files + commits → domains | `documenter` |
+| 9 | **Wisdom + Last Change** — record learnings, refresh `CLAUDE.md` | `domain-updater` |
 
-Always read `.claude/config/active-project.json` first.
+If `security-auditor` returns CRITICAL/HIGH/MEDIUM, fix before re-running step 5. Steps 8–9 run AFTER push and never before.

package/stacks/_shared/commands/fix.md

@@ -1,9 +1,23 @@
+---
+name: fix
+description: Fix a bug — reproduce, isolate, minimal fix, regression test, security check, commit, record wisdom.
+version: 1.0.0
+---
+
 # /fix — Fix Bug
 
-Execute in order:
+Always read `.claude/config/active-project.json` first.
+
+| # | Step | Agent / Skill |
+|---|---|---|
+| 1 | **Reproduce** — read the error, reproduce locally, isolate the root cause (NOT the symptom) | (you) |
+| 2 | **Failing test first** — write a regression test that proves the bug | `tester` |
+| 3 | **Apply minimal fix** — do not refactor adjacent code in the same commit | (you) |
+| 4 | **Verify** — re-run the regression test + the wider suite | `tester` |
+| 5 | **Security** — only if the bug touched auth / input / secrets / SSRF surface | `security-auditor` (VETO) |
+| 6 | **Quality gate** — typecheck → lint → test → build | `quality-gate` |
+| 7 | **Commit** — `fix(scope): <subject>`, diff-driven body | `commit-manager` |
+| 8 | **Map** — files + commit → domain | `documenter` |
+| 9 | **Wisdom** — append to domain `## Problems & Solutions` (symptom + root cause + fix + prevention + skill ref) | `domain-updater` |
 
-1. **Analyze** → Read error, reproduce, isolate
-2. **Fix** → Apply minimal fix
-3. **Test** → Add regression test (tester agent)
-4. **Document** → Record in domain Problems & Solutions
-5. **Commit** → commit-manager agent
+`domain-updater` deduplicates by symptom/root-cause. If the same bug recurred, it appends a "Recurrence" note instead of a duplicate entry.

package/stacks/_shared/commands/research.md

@@ -1,10 +1,21 @@
+---
+name: research
+description: Research best practices using research-web (MCP-first) with cache lookup before any web call.
+version: 1.0.0
+---
+
 # /research — Research Best Practices
 
-Execute in order:
+Always read `.claude/config/active-project.json` first to know the active stack.
+
+| # | Step | Tool / Skill |
+|---|---|---|
+| 1 | **Cache lookup** — check `.claude/skills/research-cache/cache/<topic>.md` first. If fresh (≤ 30 days), use it and skip steps 2–5 | `research-cache` |
+| 2 | **MCP probe** — detect `mcp__web-scraper__*` availability (one-shot per session) | `research-web` |
+| 3 | **Search** — Tier 1: `unified_search` (Brave + Vertex AI + Grok, dedupe + scoring). Tier 2 fallback: built-in `WebSearch` | `research-web` |
+| 4 | **Source ranking** — official docs > engineering blogs > GitHub issues > Stack Overflow. Reject anything > 18 months old without re-validation | (you) |
+| 5 | **Deep read** — Tier 1: `scrape_url` (stealth + proxy). Tier 2 fallback: built-in `WebFetch` | `research-web` |
+| 6 | **Document** — write `.claude/skills/research-cache/cache/<topic>.md` with: date · expiry (now + 30 days) · sources · TL;DR · actionable rules | `research-cache` |
+| 7 | **Promote** — if any rule applies project-wide, propose adding it to `CLAUDE.md` (do NOT auto-edit; surface the proposal) | (you) |
 
-1. **Check cache** → `.claude/skills/research-cache/cache/`
-2. **Search web** → "[topic] best practices [year] [stack]"
-3. **Sources**: Official docs > Engineering blogs > OWASP > GitHub issues
-4. **Document** → Create `.claude/skills/research-cache/cache/[topic].md`
-5. **Extract rules** → Add actionable rules to CLAUDE.md if applicable
-6. **Update cache** → Date + expiry (30 days)
+Each cache entry has frontmatter `expires_on:` so a future session can detect stale notes without re-reading the body.

package/stacks/_shared/commands/validate.md

@@ -1,10 +1,37 @@
+---
+name: validate
+description: Run the full quality gate (typecheck → lint → test → build) using the stack's commands from active-project.json.
+version: 1.0.0
+---
+
 # /validate — Run Full Validation
 
-Read quality gates from `.claude/config/active-project.json` and run all:
+Read the quality gates from `.claude/config/active-project.json#qualityGates` and run them in order. Stop at the first failure.
 
 ```bash
-# Read stack commands
-cat .claude/config/active-project.json | jq '.qualityGates'
+jq -r '.qualityGates' .claude/config/active-project.json
+```
+
+Execution order (each step blocks the next):
+
+| # | Gate | Typical commands |
+|---|---|---|
+| 1 | **Typecheck** | `npx tsc --noEmit` · `mypy .` · `vendor/bin/phpstan analyse` |
+| 2 | **Lint** | `npx eslint .` · `ruff check .` · `vendor/bin/pint --test` |
+| 3 | **Unit tests** | `npx vitest run` · `pytest` · `vendor/bin/phpunit` |
+| 4 | **E2E** (only if configured) | `npx playwright test` |
+| 5 | **Build** | `npm run build` · `composer dump-autoload --optimize` |
+
+Output format (one line per gate):
+
+```
+typecheck: PASS  (1.4s)
+lint:      PASS  (0.8s)
+tests:     PASS  (45/45 in 6.2s)
+e2e:       SKIP  (not configured)
+build:     PASS  (3.1s)
+
+✅ All gates passed — safe to invoke commit-manager
 ```
 
-Then execute each gate in order. Report pass/fail for each.
+If any gate fails, print the failure output and exit non-zero. `commit-manager` will refuse to commit while validation is failing.

package/stacks/_shared/skills/codebase-knowledge/SKILL.md

@@ -1,71 +1,68 @@
 ---
 name: codebase-knowledge
-version: 1.0.0
+version: 2.0.0
+description: "Cached domain knowledge consumed BEFORE implementing any feature. Reads `.claude/skills/codebase-knowledge/_index.json` (machine-readable, regenerated by `documenter`) for fast filter, then reads only the affected `domains/<slug>.md` files. Avoids re-exploring the codebase every session."
 ---
 
-# Codebase Knowledge — Domain Mapping System
+# Codebase Knowledge — Domain Knowledge Reader (v2.0.0)
 
 **ALWAYS invoke BEFORE implementing any feature.**
 
-## Purpose
+This skill is the **read side** of the project memory layer maintained by the `documenter` and `domain-updater` agents. Its job is to load just enough context for the next change without re-discovering the whole codebase.
 
-Maps files by domain, tracks connections, caches architecture decisions.
-
-## Domain Files Location
+## Storage layout (maintained by `documenter` v2.0.0)
 
 ```
-.claude/skills/codebase-knowledge/domains/
-├── authentication.md
-├── api.md
-├── database.md
-├── ui-components.md
-└── [domain-name].md
+.claude/skills/codebase-knowledge/
+├── SKILL.md                  # this file
+├── TEMPLATE.md               # template for new domain files (no version — it is a template)
+├── _INDEX.md                 # human-readable list of all domains
+├── _index.json               # machine-readable index — SOURCE OF TRUTH for filter
+└── domains/
+    ├── <slug>.md             # one file per domain. ≤ 8 KB / ~2k tokens / 200 lines
+    └── <slug>.archive.md     # commits/wisdom older than the cap (read on demand only)
 ```
 
-## Domain File Template
-
-```markdown
-# {Domain Name}
+## Read protocol (token-efficient)
 
-## Last Update
-- **Date:** YYYY-MM-DD
-- **Commit:** abc123
-- **Summary:** What changed
+| # | Step | Tool |
+|---|---|---|
+| 1 | **Resolve which domain(s) you need** by glob/grep on the affected file paths against `.claude/config/domain-mapping.json` | Bash + jq |
+| 2 | **Read `_index.json` first** — one query gives you `last_commit`, `tags`, `connections` for every domain | `jq '.domains[] \| select(.slug == "auth")' _index.json` |
+| 3 | **Read only the matched `domains/<slug>.md`** files — never `cat domains/*.md` (that defeats the budget) | Read |
+| 4 | **Follow `connections`** if the change crosses a domain boundary; read those neighbours too | Read |
+| 5 | **Skip `<slug>.archive.md`** unless `_index.json` flags `status: archived` and you actually need history | Read |
 
-## Files
-| File | Purpose |
-|------|---------|
-| `path/file.ext` | Description |
+## Domain file shape
 
-## Connections
-| Domain | How They Connect |
-|--------|-----------------|
-| auth | Validates tokens before API calls |
+Defined by `documenter` v2.0.0 — see `TEMPLATE.md` in this folder for the canonical layout. Required sections:
 
-## Recent Commits
-| Hash | Date | Description |
-|------|------|-------------|
-| abc123 | YYYY-MM-DD | feat: description |
-
-## Attention Points
-- Important gotcha or consideration
-
-## Problems & Solutions
-### Problem Title
-**Problem:** What went wrong
-**Solution:** How it was fixed
-**Prevention:** How to avoid in future
-```
+- YAML frontmatter (`domain · tags · owner · last_commit · last_date · files_count · connections · status`)
+- TL;DR (≤ 3 lines, front-loads boundary)
+- Files table (path → role)
+- Connections table (bidirectional: → and ← rows)
+- Recent Commits (capped at 20)
+- Attention Points (capped at 10)
+- Problems & Solutions (capped at 5, append-only)
 
 ## Workflow
 
-1. **Before coding** → Read relevant domain files
-2. **During coding** → Note connections and gotchas
-3. **After coding** → documenter + domain-updater agents update these files
+1. **Before coding** — read this skill, then `_index.json`, then the affected `domains/<slug>.md` files.
+2. **During coding** — note any new connection, gotcha, or non-obvious decision (you do not write here directly).
+3. **After commit** — `documenter` maps files+commits, `domain-updater` records the wisdom you collected.
 
 ## Rules
 
-1. **CHECK BEFORE IMPLEMENTING** — always read affected domains first
-2. **BIDIRECTIONAL CONNECTIONS** — if A connects to B, update both
-3. **INCLUDE COMMIT HASHES** — traceability
-4. **RECORD PROBLEMS** — future sessions benefit from lessons learned
+1. **READ `_index.json` FIRST** — it is regenerated each commit; it is the cheapest way to filter.
+2. **NEVER `cat domains/*.md`** — you will blow the context budget.
+3. **BIDIRECTIONAL CONNECTIONS** — if `auth.md` lists `→ api`, then `api.md` MUST list `← auth`. If you spot a missing reverse edge, surface it for `domain-updater`.
+4. **ARCHIVE FILES ARE OPT-IN** — read `<slug>.archive.md` only when `_index.json` shows `status: archived` or when you need pre-cap history.
+5. **DO NOT EDIT DOMAIN FILES DIRECTLY** — only `documenter` and `domain-updater` write here. If something is wrong, fix the agent or report drift.
+6. **TRUST `last_commit`** — if `_index.json#last_commit` ≠ HEAD, the documenter forgot to run; pause and fix instead of working with stale knowledge.
+
+## See Also
+
+- `documenter` v2.0.0 — writes to this layout (after every commit)
+- `domain-updater` v2.0.0 — writes session wisdom (Problems & Solutions, Attention Points)
+- `docs-tracker` v2.0.0 — file → domain mapping rules
+- `claude-md-compactor` v2.0.0 — keeps `CLAUDE.md` ≤ 20 KB; this layer keeps each domain ≤ 8 KB

package/stacks/_shared/skills/codebase-knowledge/TEMPLATE.md

@@ -1,23 +1,44 @@
-# {Domain Name}
+---
+domain: <slug>
+tags: [tag1, tag2]
+owner: <team or "shared">
+last_commit: <short-sha>
+last_date: YYYY-MM-DD
+files_count: 0
+connections: []
+status: active
+---
 
-## Last Update
-- **Date:** YYYY-MM-DD
-- **Commit:** 
-- **Summary:** 
+# <Title> Domain
+
+> **TL;DR** (≤ 3 lines). What lives here, where the boundary is, who calls it.
+> Example: "User session lifecycle. Owns Sanctum cookie, login, password reset.
+> Does NOT own user profile data (see `users` domain)."
 
 ## Files
-| File | Purpose |
-|------|---------|
+
+| Path | Role |
+|---|---|
 
 ## Connections
-| Domain | How They Connect |
-|--------|-----------------|
 
-## Recent Commits
-| Hash | Date | Description |
-|------|------|-------------|
+| Direction | Domain | What flows |
+|---|---|---|
+
+## Recent Commits (capped at 20 — oldest auto-archived)
+
+| Hash | Date | Subject |
+|---|---|---|
 
 ## Attention Points
-- 
 
-## Problems & Solutions
+(≤ 10 entries; oldest beyond 10 → `<slug>.archive.md`)
+
+## Problems & Solutions (append-only)
+
+(≤ 5 entries; oldest beyond 5 → `<slug>.archive.md`)
+
+## See Also
+
+- Skill: `<skill-name §section>`
+- Domain: `<related-slug>`

package/stacks/_shared/skills/docs-tracker/SKILL.md

@@ -1,56 +1,104 @@
 ---
 name: docs-tracker
-version: 1.0.0
+version: 2.0.0
+description: "File → domain mapping rules and changelog templates consumed by `documenter` v2.0.0. Detects modified files via `git diff-tree`, classifies them via `.claude/config/domain-mapping.json`, and emits the actions documenter must apply (Edit known anchors, never Write over existing files; bidirectional connections; cap commit log at 20)."
 ---
 
-# Docs Tracker — Automatic Documentation System
+# Docs Tracker — File → Domain Mapping Rules (v2.0.0)
 
-**ALWAYS invoke AFTER implementation completes.**
+**ALWAYS invoke AFTER `commit-manager` succeeds (so the commit hash is real).**
 
-## Execution Flow
+This skill is the **rule set** consumed by `documenter` v2.0.0. It does not write files itself — it tells documenter what to do with each changed file.
 
+## Detection (one git call, not many)
+
+```bash
+# Files in the LAST commit (after commit-manager pushed)
+git diff-tree --no-commit-id --name-status -r HEAD
 ```
-1. DETECT CHANGES → git diff --name-status
-        ↓
-2. CLASSIFY → A=Added, M=Modified, D=Deleted
-        ↓
-3. CHECK EXISTING DOCS → codebase-knowledge/domains/
-        ↓
-4. CREATE/UPDATE/REMOVE as needed
-        ↓
-5. UPDATE CLAUDE.md "Last Change" section
-```
 
-## What to Document
+Status codes: `A` = added, `M` = modified, `D` = deleted, `R` = renamed, `C` = copied. Treat `R` and `C` as `M` for mapping purposes plus a "renamed from" note in the destination domain.
+
+## File → Domain mapping
+
+Source of truth: `.claude/config/domain-mapping.json` (shipped with this CLI; project may override). A path may map to ≥1 domain. Unmatched paths → `general`.
+
+Skip the entire pass if every changed path matches one of:
 
-| Change Type | Action |
+| Skip pattern | Reason |
 |---|---|
-| New file | Create domain entry if new domain |
-| Modified file | Update domain "Last Update" + "Recent Commits" |
-| Deleted file | Remove from domain "Files" table |
-| New connection | Add to "Connections" in BOTH domains |
-| Bug fix | Add to "Problems & Solutions" |
+| `.claude/**` | meta — does not belong to any product domain |
+| `docs/**` | docs commit — no code drift |
+| `.github/**` | CI — handled by `infrastructure` domain only if pattern is added |
+| `CHANGELOG*`, `*.md` (root only) | release docs |
+| `package.json`, `composer.json`, `pyproject.toml` (deps only — not scripts) | bumps tracked elsewhere |
+
+## Action matrix (applied by `documenter`)
+
+| Git status | Domain file state | Action |
+|---|---|---|
+| `A` | exists | `Edit`: append row to `## Files`, prepend row to `## Recent Commits`, increment `files_count` in frontmatter |
+| `A` | missing | `Write`: create from `TEMPLATE.md`, fill TL;DR, add the file row, add the commit row |
+| `M` | exists | `Edit`: prepend row to `## Recent Commits`; if file's role description changed, update its row in `## Files` |
+| `M` | missing | unusual — investigate; usually means mapping rule was added but file existed before. Treat as `A` |
+| `D` | exists | `Edit`: strike-through (`~~path~~`) row in `## Files`, decrement `files_count`. Prune at the next pass |
+| `R src→dst` | exists | `Edit`: replace `src` row with `dst` row, add note `(renamed from src in <short-sha>)` to Attention Points |
+
+## Bidirectional connections (mandatory)
+
+When a session adds `auth → api` to `auth.md`, **also** add `api ← auth` to `api.md`. The two edits must succeed atomically — if the second fails, roll back the first. The `security-auditor` flags dangling links as a MEDIUM finding.
+
+## Cap and archive (size guard)
 
-## Detection Commands
+After any edit, check the live file:
 
 ```bash
-# What changed?
-git diff --name-status HEAD~1
+[ "$(wc -c < domains/<slug>.md)" -gt 8192 ] && trigger_archive
+```
+
+When triggered, move the **oldest 5 rows** of `## Recent Commits` (and oldest 2 Problems & Solutions, oldest 3 Attention Points) into `<slug>.archive.md`. Live file must stay ≤ 8 KB.
 
-# What's staged?
-git diff --name-only --cached
+## Index regeneration (after every pass)
 
-# What's unstaged?
-git diff --name-only
+```bash
+# Regenerate _index.json from frontmatter of every domain file
+for f in .claude/skills/codebase-knowledge/domains/*.md; do
+  # parse YAML frontmatter, compute summary_sha = sha256(TL;DR block), emit one record
+done | jq -s '{schema_version:1, generated_at:(now|todate), domain_count:length, domains:.}' \
+     > .claude/skills/codebase-knowledge/_index.json
 
-# What's untracked?
-git ls-files --others --exclude-standard
+# Then derive _INDEX.md from _index.json
+```
+
+`_index.json` is the source of truth — `_INDEX.md` is human-readable derivative.
+
+## Pre-commit hook (CI integration)
+
+A repository can add this check to fail builds when documenter forgot to run:
+
+```bash
+HEAD_SHA=$(git rev-parse --short HEAD)
+LAST_INDEXED=$(jq -r '.domains | map(.last_commit) | unique[]' \
+  .claude/skills/codebase-knowledge/_index.json)
+echo "$LAST_INDEXED" | grep -qx "$HEAD_SHA" || {
+  echo "ERROR: _index.json is stale. Run documenter before pushing."
+  exit 1
+}
 ```
 
 ## Rules
 
-1. **RUN AFTER EVERY IMPLEMENTATION** — no exceptions
-2. **DETECT VIA GIT** — don't guess, use git diff
-3. **UPDATE DOMAINS** — not just CLAUDE.md
-4. **BIDIRECTIONAL** — if A↔B connection, update both
-5. **INCLUDE COMMIT HASH** — traceability
+1. **AFTER `commit-manager`** — never before; the hash must be real.
+2. **DETECT VIA GIT** — `git diff-tree -r HEAD`, never guess from session memory.
+3. **EDIT KNOWN ANCHORS** — `documenter` uses `Edit` / `StrReplace` on existing domain files; never `Write` over them.
+4. **BIDIRECTIONAL** — both ends of every connection updated atomically.
+5. **CAP AT 8 KB / 20 commits / 10 attention / 5 P&S** — archive overflow into `<slug>.archive.md`.
+6. **REGENERATE `_index.json` EVERY PASS** — derived; never hand-edited.
+7. **SKIP META PATHS** — `.claude/**`, `docs/**`, `.github/**` do not get domain entries.
+
+## See Also
+
+- `documenter` v2.0.0 — applies the actions defined here
+- `codebase-knowledge` v2.0.0 — reads what documenter wrote
+- `domain-updater` v2.0.0 — appends session wisdom AFTER documenter
+- `.claude/config/domain-mapping.json` — pattern → domain rules

package/stacks/_shared/skills/research-cache/SKILL.md

@@ -1,62 +1,139 @@
 ---
 name: research-cache
-version: 1.0.0
+version: 2.0.0
+description: "Caches web research findings under `.claude/skills/research-cache/cache/` to avoid redundant searches. Each entry has YAML frontmatter (`expires_on`, `sources`, `tier`, `engines`) so a session can grep-filter fresh entries without reading the body. Consumed by `research-web` v2.0.0 BEFORE any MCP / WebSearch call."
 ---
 
-# Research Cache — Best Practices Storage
+# Research Cache — Best-Practices Storage (v2.0.0)
 
-**ALWAYS invoke BEFORE any web research.**
+**ALWAYS invoke BEFORE any web research.** This skill is the **read AND write** side of `research-web` v2.0.0.
 
-## Purpose
-
-Caches research findings to avoid redundant searches and maintain institutional knowledge.
-
-## Structure
+## Layout
 
 ```
 .claude/skills/research-cache/
 ├── SKILL.md
 └── cache/
-    ├── php-uuid-performance.md
-    ├── laravel-octane-memory.md
-    └── [topic].md
+    ├── _index.json                    # auto-derived, optional (one record per cache entry)
+    └── <topic-slug>.md                # one file per topic. ≤ 8 KB. Pruned at expires_on.
+```
+
+## Cache entry frontmatter (token-efficient lookup)
+
+Every cache entry MUST start with this frontmatter so a `grep` over `cache/*.md` filters fresh entries without parsing bodies:
+
+```yaml
+---
+topic: <kebab-case>
+stack: php | nodejs | python | universal | frontend
+researched_on: YYYY-MM-DD
+expires_on: YYYY-MM-DD            # researched_on + 30 days (60 for stable specs, 14 for moving libraries)
+tier: 1 | 2                       # 1 = MCP web-scraper used; 2 = built-in WebSearch fallback
+engines: [brave, vertex, grok]    # which engines contributed (Tier 1 only)
+sources_count: <int>
+confidence: high | medium | low   # high = 3+ official-doc sources agree; low = single blog post
+---
 ```
 
-## Before Searching
+## Read protocol (lookup BEFORE searching)
 
-1. Check cache: `ls .claude/skills/research-cache/cache/`
-2. Grep for topic: `grep -rl "topic" .claude/skills/research-cache/cache/`
-3. If found and recent (<30 days) → USE CACHE
-4. If not found → Research and CREATE cache entry
+```bash
+TOPIC="<kebab-case>"
+TODAY=$(date +%F)
 
-## Cache Entry Template
+# 1. Direct hit?
+F=".claude/skills/research-cache/cache/${TOPIC}.md"
+if [ -f "$F" ]; then
+  EXPIRES=$(awk -F': ' '/^expires_on:/{print $2; exit}' "$F")
+  [ "$EXPIRES" \> "$TODAY" ] && echo "FRESH cache hit: $F" && exit 0
+  echo "STALE: $F (expired $EXPIRES); will refresh"
+fi
+
+# 2. Fuzzy hit? (alias / synonym)
+grep -l "topic:.*${TOPIC%%-*}" .claude/skills/research-cache/cache/*.md 2>/dev/null
+```
+
+If FRESH → use the cache, do NOT re-search.
+If STALE or MISSING → research, then write a new entry (overwrite or create).
+
+## Write protocol (after research)
+
+Always overwrite — never append. Stale data is worse than missing data.
+
+### Body template
 
 ```markdown
-# Research: {Topic}
+---
+topic: <kebab-case>
+stack: <one-of>
+researched_on: 2026-05-13
+expires_on: 2026-06-12
+tier: 1
+engines: [brave, vertex, grok]
+sources_count: 5
+confidence: high
+---
+
+# Research: <Topic Title>
 
-**Date:** YYYY-MM-DD
-**Stack:** PHP|Node.js|Universal
-**Sources:** [list]
-**Expires:** YYYY-MM-DD (30 days from research)
+> **TL;DR** (≤ 3 lines). The actionable answer in 30 seconds.
 
-## Key Findings
-1. Finding — Source: [URL]
+## Findings (cited)
+
+| # | Finding | Source | Date | Tier |
+|---|---|---|---|---|
+| 1 | <one-line> | https://docs.example.com/foo | 2026-04-12 | official |
+| 2 | <one-line> | https://eng-blog.example.com/bar | 2026-03-30 | engineering |
 
 ## Recommendations
-- Actionable recommendation
 
-## Code Examples
-\`\`\`php
-// Example implementation
-\`\`\`
+- <actionable rule, ready to drop into a skill or CLAUDE.md>
+- <do this, not that>
+
+## Anti-patterns
+
+- <something to avoid + why>
+
+## Code reference (optional)
+
+- File / line / commit pointing at where this rule should be applied — NOT inline code dumps.
+
+## Open questions
 
-## References
-- [URL] — [Description]
+- <thing the research did NOT answer; flag for next round>
 ```
 
+## Expiry policy (cost vs freshness)
+
+| Topic kind | TTL | Example |
+|---|---|---|
+| Specification (W3C, RFC, OpenAPI) | 60 days | WCAG 2.2 conformance |
+| Stable framework (Laravel, Django, Express) | 30 days | Laravel 12 sessions |
+| Fast-moving library (any minor < 1.0, anything pre-release) | 14 days | shadcn registries, AI SDKs |
+| Security advisory | 7 days | CVE feeds, OWASP draft |
+
+After `expires_on`, the entry is read-only history — `research-web` will refresh it on the next lookup.
+
+## Source ranking (recorded in each finding row)
+
+1. **official** — vendor docs, RFCs, W3C, MDN
+2. **engineering** — engineering blogs of the project (vercel.com/blog, fastify.io/blog)
+3. **community** — high-signal: Stack Overflow with 50+ votes, GitHub issues with maintainer response
+4. **opinion** — random blog post — accepted only if it confirms an official-doc claim, never as primary
+
 ## Rules
 
-1. **CHECK CACHE FIRST** — avoid redundant searches
-2. **CITE SOURCES** — every finding needs URL
-3. **DATE ENTRIES** — for freshness checks
-4. **STACK-SPECIFIC** — tag by stack for filtering
+1. **CHECK CACHE FIRST** — frontmatter `expires_on` lookup is one `awk`. Cheaper than any web call.
+2. **OVERWRITE, NEVER APPEND** — stale information is worse than missing.
+3. **CITE EVERY FINDING** — URL + date + tier. No bare claims.
+4. **TTL BY TOPIC KIND** — see table above. A spec lasts longer than a pre-release library.
+5. **CONFIDENCE EXPLICIT** — `high` requires ≥ 3 official-doc sources agreeing; `low` is single source.
+6. **NO INLINE CODE DUMPS** — link to file/line; the model can `Read` when it needs the bytes.
+7. **NO PII / SECRETS / CUSTOMER DATA** — never quote env values, tokens, internal hostnames.
+8. **PROMOTE WHAT'S UNIVERSAL** — if a rule applies project-wide, surface it for inclusion in `CLAUDE.md` (do not auto-edit).
+
+## See Also
+
+- `research-web` v2.0.0 — MCP-first researcher; reads/writes this cache
+- `claude-md-compactor` v2.0.0 — receives promoted rules; enforces 20 KB CLAUDE.md budget
+- `mcp-web-scraper` skill — the MCP server providing Tier 1 search/scrape capability