@claude-pw/framework 0.3.0

package/templates/claude/commands/cpw-reflect.md

@@ -0,0 +1,209 @@
+---
+description: "Review captured corrections and turn them into project learnings"
+---
+
+## Arguments
+- No arguments: normal flow (steps 1-5)
+- `--dedupe`: scan destination files for duplicates and contradictions (step 6)
+- `--scan-history`: scan past sessions for missed corrections (step 1.1)
+- `--days N`: limit history scan to last N days (default: 30). Only with --scan-history.
+
+## 0. Check arguments
+
+If the user passed `--dedupe`, go directly to step 6.
+If `--scan-history`, continue to step 1 then step 1.1.
+Otherwise, continue with the normal flow (skip step 1.1).
+
+## 1. Load learning queue
+Read `.planning/learnings/queue.md`.
+- If it doesn't exist or is empty (no `---` entries): "No pending corrections. Nothing to do."
+- If it has entries: continue.
+- **Backwards compatibility**: if there are entries in the old table format (`| Fecha | Correccion | Contexto |`), migrate each row to v2 format with `Pattern: correction`, `Confidence: 0.65`, `Validated: no`.
+
+## 1.1 Scan session history (only with --scan-history)
+
+### Locate session files
+Determine the project session directory:
+- Project path: current working directory (pwd)
+- Encode path: replace `/` with `-`, remove leading `-`
+- Session dir: `~/.claude/projects/-[ENCODED_PATH]/`
+- Find `*.jsonl` files, filter by `--days N` modification time (default: 30 days)
+
+If no session files found: "No sessions found for this project in the last N days."
+
+### Extract corrections from sessions
+For each session file, read and scan for user messages (role: "user") that match correction patterns:
+- Explicit: "remember:", "recuerda:"
+- Strong corrections: "no use", "don't", "actually", "stop", "never", "always", "I told you", "I said"
+- Tool rejections: messages where the user blocked a tool action and provided corrective feedback
+
+Skip:
+- Messages marked as `isMeta: true` (command expansions like /cpw-reflect itself)
+- Very long messages (>500 chars) unless they contain explicit markers
+- Messages that are clearly task requests or questions
+
+### Add to working queue
+For each extracted correction:
+- Create a queue entry: `Pattern: correction`, `Confidence: 0.65`, `Validated: no`
+- Tool rejections get `Confidence: 0.80` (user explicitly stopped an action)
+- Deduplicate against existing queue entries and `.planning/learnings/applied.md`
+
+Show summary:
+```
+Session scan: X sessions analyzed (last N days)
+  - Y potential corrections found
+  - Z already in queue/applied (skipped)
+  - W new entries added to working queue
+```
+
+Continue to step 1.5 with the enriched queue.
+
+## 1.5 Semantic validation
+
+For each entry with `Validated: no`, analyze semantically:
+
+### Filter false positives
+Silently discard if the correction is:
+- A disguised question ("why did you use X?" without proposing an alternative)
+- A bug report ("this fails", "there's an error in...")
+- A task request ("add a test for...", "implement...")
+- A simple confirmation ("ok", "yes", "sure", "done")
+- A one-off instruction, not generalizable
+
+This step supports any language — analyze the intent, not just keywords.
+
+### Extract actionable learning
+For each valid entry, rewrite the correction as a concise imperative statement:
+- Input: "no no, actually use Zod for that, don't use Joi"
+- Learning: "Use Zod instead of Joi for schema validation"
+
+### Adjust confidence
+Evaluate semantic confidence (0.0-1.0) based on:
+- **Clarity**: is it specific? does it mention concrete tools/patterns? (+)
+- **Generality**: does it always apply or only in this specific case? (+)
+- **Emphasis**: was the user emphatic (repetition, "I told you", "always")? (+)
+
+Final confidence = `max(pattern_confidence, semantic_confidence)`
+
+### Update entries
+- Valid entries: set `Validated: yes`, update `Confidence`, annotate the rewritten learning
+- Discarded entries: remove from queue
+
+Show summary before continuing:
+```
+Semantic validation: X entries analyzed
+  - Y confirmed as learnings
+  - Z discarded (false positives)
+
+Discarded:
+  - "why did you use that?" — question, not correction
+  - "there's an error in the login" — bug report
+```
+
+## 2. Review each entry
+For each validated correction, delegate to the learning-extractor agent:
+<files_to_read>
+- ./CLAUDE.md (if exists)
+- .planning/learnings/queue.md
+- .planning/learnings/applied.md (if exists)
+</files_to_read>
+Correction: [the correction entry]
+The agent classifies and proposes a destination:
+- **RULE**: new rule or adjustment to CLAUDE.md / .claude/rules/
+- **CONVENTION**: document in docs/conventions.md
+- **DECISION**: record in plans/decisions.md
+- **PIPELINE**: adjust default stages in next-step, startup, or route back to the specific command/agent file
+- **SKILL**: non-obvious discovery → create .claude/skills/[name].md
+- **DISCARD**: not generalizable, one-off case
+
+### Command-aware routing
+If the entry has a **Command** field, the learning-extractor uses it to route corrections back to the originating command or its agents. For example, a correction captured during `/cpw-next-step` about skipping SPIKE stage routes to `.claude/commands/cpw-next-step.md`, not to a generic file.
+
+## 3. Present to user
+Show each proposal with change preview and confidence:
+```
+1. [RULE] (0.85) "Use X instead of Y for Z" -> CLAUDE.md
+2. [CONVENTION] (0.75) "Always use alias imports @/" -> docs/conventions.md
+3. [PIPELINE] (0.85) "Always run tests before CLOSE" -> .claude/commands/cpw-next-step.md
+   (captured during /cpw-next-step)
+4. [SKILL] (0.80) "ESM import error in Jest actually means missing transform config" -> .claude/skills/jest-esm-transform.md
+5. [DISCARD] (0.50) "Variable typo" -> n/a
+```
+Wait for item-by-item approval (or "apply all").
+
+### SKILL creation
+For approved SKILL items:
+- Create the skill file at `.claude/skills/[name-slug].md` using the template from learning-extractor output
+- Ask: "Should this skill apply globally (~/.claude/skills/) or only to this project? (project/global)"
+  - In autoAdvance auto/yolo: default to project
+- Verify the description contains specific keywords for semantic retrieval (error messages, framework names, symptoms)
+
+## 4. Apply approved changes
+- Write to the corresponding destination
+- For SKILL items: create .claude/skills/[name-slug].md
+- For PIPELINE items routed to commands/agents: append as a new section or update existing guidance
+- Mark as processed in queue.md
+- `make commit m="learn: apply session learnings"`
+
+## 5. Clean up
+Move processed entries to `.planning/learnings/applied.md` with this format:
+```
+---
+- **Date applied**: [today]
+- **Learning**: [concise learning statement]
+- **Type**: [RULE|CONVENTION|DECISION|PIPELINE]
+- **Destination**: [file where it was applied]
+- **Final confidence**: [numeric score]
+---
+```
+Remove processed entries from queue.md.
+
+## 6. Deduplication (only with --dedupe)
+
+### 6.1 Load destinations
+Read all files containing applied learnings:
+- CLAUDE.md
+- docs/conventions.md (if exists)
+- plans/decisions.md (if exists)
+- .claude/rules/*.md
+
+### 6.2 Extract entries
+For each file, extract individual lines/bullet points that represent rules, conventions, or decisions.
+
+### 6.3 Detect semantic duplicates
+Group entries that:
+- Refer to the same tool, pattern, or concept
+- Give redundant or overlapping advice
+- Could be merged without losing information
+
+### 6.4 Detect contradictions
+Look for entries that contradict each other:
+- "Use X" vs "Don't use X"
+- "Always do Y" vs "Never do Y"
+
+### 6.5 Present findings
+```
+══════════════════════════════════════════
+DEDUPLICATION
+══════════════════════════════════════════
+
+CONTRADICTIONS (if any):
+  file:line "Rule A"
+  file:line "Rule B"
+  -> Description of the conflict
+
+SIMILAR ENTRIES (if any):
+  Group 1:
+    file:line "Entry A"
+    file:line "Entry B"
+    -> Consolidated proposal: "Unified text"
+
+Unique entries: N (no changes needed)
+══════════════════════════════════════════
+```
+
+### 6.6 Apply with approval
+- For each contradiction: ask the user which one to keep
+- For each similar group: ask whether to apply the consolidated version
+- Apply approved changes with Edit
+- `make commit m="learn: deduplicate learnings"`

package/templates/claude/commands/cpw-startup.md

@@ -0,0 +1,321 @@
+---
+description: "Discovery session -- detect mode (greenfield/brownfield/bluefield), interview and generate plan"
+---
+
+Note: For standalone codebase analysis without starting the full workflow,
+run /cpw-startup on an existing project — the SCAN step produces a full
+analysis report. You can stop after the scan by declining plan generation.
+
+## 0. MODE DETECTION
+
+Check the directory state:
+- Are there source files? (src/, lib/, app/, *.py, *.ts, *.go, etc.)
+- Is there git history? (more than 3 commits)
+- Is there a package manager? (package.json, requirements.txt, go.mod, Cargo.toml, etc.)
+
+If there is NO code:
+- Automatic **GREENFIELD** mode. Go to step 1.
+
+If there IS code, ask:
+```
+Detected an existing project ([detected stack], [N files], [N commits]).
+What do you want to do?
+
+1. BROWNFIELD — Add claude-pw workflow structure to this project as-is
+2. BLUEFIELD — Rewrite or replace parts of this project
+3. GREENFIELD — Ignore existing code, start from scratch
+```
+
+## 0.5 SCAN (brownfield/bluefield only)
+
+Delegate to the codebase-mapper agent:
+<files_to_read>
+- ./CLAUDE.md (if exists)
+</files_to_read>
+Wait for report.
+Pre-fill context with findings:
+- Stack -> detected
+- Modules -> inferred from code
+- Conventions -> detected
+- Integrations -> detected
+- Tech debt -> identified (relevant for bluefield)
+
+Write docs/ with the report (same logic as /cpw-startup steps 3-4).
+
+## 0.7 TOOLING HEALTH CHECK (brownfield only)
+
+Skip this step for greenfield and bluefield.
+
+After the codebase scan, audit the project's existing tooling against best practices for the detected stack. Check each category:
+
+| Category | What to check |
+|----------|--------------|
+| **Linter** | Installed? Configured? Version current? (ESLint, Pylint, golangci-lint, etc.) |
+| **Formatter** | Installed? Configured? (Prettier, Black, gofmt, etc.) |
+| **Type checking** | TypeScript, JSDoc, mypy, type hints? strictness level? |
+| **Test runner** | Installed? Tests exist? Coverage configured? Coverage threshold? |
+| **Pre-commit hooks** | Husky, lint-staged, pre-commit (Python)? What do they run? |
+| **CI/CD** | Pipeline exists? (.github/workflows, .gitlab-ci, etc.) What does it run? |
+| **Git hygiene** | .gitignore complete? Lockfile committed? Secrets exposed? (.env, credentials, API keys in repo) |
+| **Dependencies** | Major versions outdated? Deprecated packages? Known vulnerabilities? |
+
+Present a report:
+
+```
+══════════════════════════════════════════
+TOOLING HEALTH — [project name]
+══════════════════════════════════════════
+
+✓ Linter: ESLint 9.x (up to date)
+✗ Formatter: none detected
+✓ Tests: Jest (48 tests, no coverage config)
+✗ Pre-commit: none
+✗ CI/CD: none
+✓ Types: TypeScript 5.x (strict mode)
+⚠ .gitignore: missing .env
+✓ Dependencies: all current
+
+Recommendations:
+  1. Add Prettier for code formatting
+  2. Add Husky + lint-staged for pre-commit
+  3. Configure coverage threshold (suggest 80%)
+  4. Add CI pipeline (GitHub Actions recommended for this stack)
+══════════════════════════════════════════
+```
+
+These recommendations will be incorporated as steps in Phase 0 of the generated plan.
+Do NOT ask the user to act on them now — just present the report and continue to the interview.
+
+---
+
+## 1. INITIAL CONTEXT
+
+**Greenfield**: Ask the user to describe the project freely. Don't interrupt.
+
+**Brownfield**: Present scan synthesis. Ask: "Does this accurately reflect the project? What's missing or wrong?"
+
+**Bluefield**: Present scan synthesis + ask: "Which parts do you want to rewrite and why? What stays?"
+
+## 2. STRUCTURED INTERVIEW
+
+MAXIMUM 3-4 questions per turn. Adapt based on mode:
+
+### Greenfield (6 full rounds)
+
+**Round 1 -- Problem and objective:**
+- What problem does this project solve?
+- Who will use it?
+- Is there something existing we're replacing or is it completely new?
+
+**Round 2 -- Scope:**
+- What should it be able to do in the first version (v1)?
+- What should it explicitly NOT do? (boundaries)
+- Is there a deadline or time constraint?
+
+**Round 3 -- Components and architecture:**
+- What logical parts do you see? (if unsure, propose modules based on what was described)
+- Are there external integrations? (APIs, DBs, third-party services)
+- Architecture preference? (monolith, services, serverless, etc.)
+
+**Round 4 -- Stack and technical constraints:**
+- Preferred language/framework or open to proposals?
+- Infrastructure? (cloud, local, docker, etc.)
+- Any tech already decided or prohibited?
+
+**Round 5 -- Tooling and accelerators:**
+- Are there domains where a skill or MCP server would help?
+- Do you already use any MCP server or Claude Code skill?
+- Prefer keeping it minimal or open to installing tools that speed things up?
+
+**Round 6 -- Development context:**
+- Working solo or in a team?
+- Priority: delivery speed vs robustness?
+
+### Brownfield (2 rounds — the scan covers the rest)
+
+**Round 1 -- Objective:**
+- What do you want to achieve now with this project? (new feature, refactor, improvement?)
+- Is there a defined scope for what's next?
+- Any deadline or constraint?
+
+**Round 2 -- Gaps:**
+- Did the scan detect the architecture correctly? Anything to fix?
+- Are there undocumented decisions I should know about?
+- Useful skills/MCPs for what's coming?
+
+### Bluefield (3 rounds)
+
+**Round 1 -- Motivation:**
+- Why rewrite? (tech debt, new requirement, stack change, compliance?)
+- What stays from the current system? (data, public APIs, UI?)
+- What gets discarded?
+
+**Round 2 -- Target:**
+- What should the new system look like?
+- Stack change? Yes/No and why
+- Strategy: big bang or gradual migration?
+
+**Round 3 -- Constraints:**
+- Need to maintain backward compatibility? With what?
+- Deadline for the migration?
+- Useful skills/MCPs?
+
+If the user doesn't know something, mark it as "pending decision for Phase 0".
+Don't bombard -- if a round is partially answered, adapt the next one.
+
+## 3. SYNTHESIS
+Produce a structured summary:
+
+```
+### Mode: [GREENFIELD | BROWNFIELD | BLUEFIELD]
+
+### Vision
+[2-3 sentences]
+
+### Identified modules
+- [module]: [responsibility]
+
+### Scope v1
+- Includes: [list]
+- Excludes: [list]
+
+### Constraints and decisions already made
+- [decision]: [reason]
+
+### Skills and MCPs to evaluate in Phase 0
+- [skill/MCP]: [what it would be used for]
+- (or "none identified for now")
+
+### Pending for Phase 0
+- [what still needs to be decided]
+```
+
+**Bluefield extra:**
+```
+### Migration plan
+- Keep: [what stays untouched]
+- Rewrite: [modules to replace]
+- Strategy: [big bang | gradual]
+- Backward compat: [yes/no + details]
+```
+
+Present it to the user. Do NOT proceed without approval.
+
+## 3.5 AUTO-RESEARCH (if applicable)
+Review the synthesis. For each item in "Pending for Phase 0" and uncertain technical decisions:
+- If it's "which library/framework to use" -> delegate to the researcher agent:
+  <files_to_read>
+  - ./CLAUDE.md (if exists)
+  - docs/architecture.md (if exists)
+  </files_to_read>
+  Type: library
+  Topic: [item from pending decisions]
+- If it's "is this approach viable" -> delegate to the researcher agent:
+  <files_to_read>
+  - ./CLAUDE.md (if exists)
+  - docs/architecture.md (if exists)
+  </files_to_read>
+  Type: feasibility
+  Topic: [item from pending decisions]
+- If it's a preference/business decision -> skip (needs human)
+
+Save results in docs/research/. Present summaries along with the synthesis.
+If there's nothing to research, skip this section.
+
+## 3.7 WORKFLOW CONFIGURATION
+
+Before generating the plan, ask workflow preferences:
+
+```
+Workflow configuration:
+
+1. Advance mode:
+   a) MANUAL -- I approve each pipeline stage (recommended for learning)
+   b) AUTO -- Auto-advances all stages, pauses only for UAT and ambiguous decisions
+   c) YOLO -- Auto-advances everything including UAT, pauses only on errors or issues found
+
+2. Plan granularity:
+   a) COARSE -- 3-5 phases, large steps (small projects)
+   b) STANDARD -- 5-8 phases (default)
+   c) FINE -- 8-12 phases, smaller steps (complex projects)
+
+3. Model profile for agents:
+   a) QUALITY -- opus for all (maximum performance, higher cost)
+   b) BALANCED -- sonnet + haiku by role (default)
+   c) BUDGET -- haiku for most (lower cost)
+
+4. Git strategy:
+   a) TRUNK-BASED -- commit directly to main, push after each step (default, solo dev)
+   b) FEATURE-BRANCH -- branch per phase, PR to merge when phase completes (teams, code review)
+   c) GITFLOW -- develop branch + feature branches per phase, release branches (teams, formal releases)
+
+5. Track planning docs in git?
+   a) YES -- .planning/ committed to git (team projects, shared decisions)
+   b) NO -- .planning/ stays local-only (default, solo projects, OSS contributions)
+```
+
+Recommend based on context:
+- Solo dev or small project → trunk-based
+- Team or needs code review → feature-branch
+- Team with release cycles → gitflow
+
+Save responses in `.planning/config.json`:
+```json
+{
+  "autoAdvance": "off|auto|yolo",
+  "granularity": "coarse|standard|fine",
+  "modelProfile": "quality|balanced|budget",
+  "modelOverrides": {},
+  "gitStrategy": "trunk-based|feature-branch|gitflow",
+  "commitPlanning": false
+}
+```
+
+If the user has no preference, use defaults (off/standard/balanced/no).
+
+**If `commitPlanning: true`:**
+- Remove `.planning/` from `.gitignore`
+- Planning artifacts (config, learnings, decisions, debug sessions) will be tracked in git
+- STATUS.md is ALWAYS gitignored (personal session state)
+
+**If `commitPlanning: false` (default):**
+- Keep `.planning/` in `.gitignore`
+- Planning stays local-only
+
+---
+
+## 4. PLAN GENERATION
+Once the synthesis is approved, generate:
+
+Read `granularity` from `.planning/config.json` to determine how many phases to generate:
+- **coarse**: 3-5 total phases. Combine related modules. Larger steps.
+- **standard**: 5-8 phases. One phase per module. (default)
+- **fine**: 8-12 phases. Large modules split into sub-features. Smaller steps.
+
+1. **README.md** -- Project README with: what it is (1-2 sentences), stack, how to install/run, project structure, contributing notes. Keep it concise but useful for any developer opening the repo for the first time.
+2. **PLAN.md** -- Index: description, modules, phase table, key files
+3. **plans/phase-0.md** -- Stack and Scaffolding
+   - Greenfield: complete (6 steps)
+   - Brownfield: adapted — skip steps covered by scan (stack already detected), add steps from tooling health check recommendations (e.g.: "add pre-commit hooks", "configure CI pipeline", "add coverage threshold")
+   - Bluefield: includes migration steps (new setup + bridge with old)
+4. **plans/phase-1.md** -- Interfaces and Modules (always)
+5. **plans/phase-2+.md** -- One phase per identified module (draft if info is missing)
+   - Bluefield: migration phases per module (old -> new)
+6. **plans/decisions.md** -- With decisions made during startup
+7. **docs/architecture.md** -- Draft (greenfield) or updated (brownfield/bluefield)
+8. **STATUS.md** -- Pointing to Phase 0, Step 0.1, Stage DESIGN
+
+## 5. PLAN REVIEW
+Present the plan phase by phase for review:
+- First PLAN.md (complete index)
+- Then each sub-plan, one by one
+- Wait for approval/adjustment on each before moving to the next
+- Update files with adjustments
+
+## 6. COMMIT AND START
+- `make commit m="chore: initial plan from startup ([mode])"`
+- Report: "Plan generated. Run `/clear` first to reset context, then:"
+- "  1. `/cpw-discuss` — clarify ambiguities before building (recommended)"
+- "  2. `/cpw-todos` — review pending todos before starting"
+- "  3. `/cpw-next-step` — start Phase 0 directly"
+- IMPORTANT: startup fills the context window significantly. Always recommend `/clear` before continuing.

package/templates/claude/commands/cpw-todos.md

@@ -0,0 +1,100 @@
+---
+description: "Capture ideas for later or review pending todos"
+---
+
+If the user provided a description (e.g., `/cpw-todos Add rate limiting`):
+→ Go to **CAPTURE mode**
+
+If no description provided:
+→ Go to **REVIEW mode**
+
+---
+
+## CAPTURE mode
+
+### 1. Extract description
+Take the todo from the user's message. Keep it concise — one sentence that future-you will understand weeks later.
+
+### 2. Infer area
+Based on file paths mentioned or keywords, classify into one area:
+- `api` — endpoints, routes, controllers, middleware
+- `ui` — components, layouts, styles, responsive
+- `data` — models, schemas, migrations, queries
+- `auth` — authentication, authorization, sessions
+- `testing` — tests, coverage, fixtures, mocks
+- `docs` — documentation, README, guides
+- `tooling` — build, CI/CD, scripts, config
+- `general` — anything else
+
+If ambiguous, default to `general`.
+
+### 3. Check duplicates
+Read `.planning/quick/log.md`. If there's an existing entry with a very similar description, warn:
+"Similar todo already exists: '[existing]'. Still add? (y/n)"
+
+### 4. Add to log
+Append to `.planning/quick/log.md`:
+```
+---
+- **Date**: [today]
+- **Todo**: [concise description]
+- **Area**: [inferred area]
+- **Files**: [relevant file paths, or "none"]
+- **Status**: pending
+---
+```
+
+### 5. Confirm and continue
+Report: "Captured: [description]. Continue with current work."
+Do NOT change context, read additional files, or start working on the todo.
+
+---
+
+## REVIEW mode
+
+### 1. Load todos
+Read `.planning/quick/log.md`. Parse all entries with `Status: pending`.
+If no pending todos: "No pending todos. Nothing to review."
+
+### 2. Display list
+Show numbered list with area, description, and age:
+```
+Pending todos (N):
+  1. [api] Add rate limiting to public endpoints (3 days ago)
+  2. [ui] Empty state for dashboard when no data (1 week ago)
+  3. [testing] Add contract tests for auth service (2 weeks ago)
+```
+
+If the user provided an area filter (e.g., `/cpw-todos --area api`), show only matching entries.
+
+### 3. User selects
+Ask: "Which todo? (number, or 'done' to exit)"
+
+### 4. Show detail and offer actions
+Show the full todo entry (description, area, files) and offer:
+
+```
+Actions:
+  a) Work on it now — start /cpw-quick with this context
+  b) Add to current plan — suggest which phase/step it fits
+  c) Dismiss — mark as dismissed with reason
+  d) Back to list
+```
+
+### Action a: Work on it now
+- Update the entry's Status to `in-progress`
+- Start `/cpw-quick` with the todo description as context
+
+### Action b: Add to current plan
+- Read STATUS.md to determine current phase
+- Read the phase sub-plan
+- Suggest where this todo fits (which step, or as a new step)
+- If user agrees, add to the sub-plan and mark Status as `planned`
+
+### Action c: Dismiss
+- Ask for brief reason
+- Update Status to `dismissed`
+- No further action
+
+### Action d: Back to list
+- Return to step 2

package/templates/claude/hooks/cpw-context-monitor.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Context monitor — PostToolUse hook that warns agent when context is running low
+// Reads bridge file written by cpw-statusline.js
+// Never blocks tool execution — exits silently on any error
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+try {
+  // Find most recent bridge file
+  const tmpdir = os.tmpdir();
+  const files = fs.readdirSync(tmpdir).filter(f => f.startsWith('cpw-ctx-') && f.endsWith('.json'));
+  if (files.length === 0) process.exit(0);
+
+  const bridge = path.join(tmpdir, files[0]);
+  const data = JSON.parse(fs.readFileSync(bridge, 'utf8'));
+  const usedPct = data.used_pct || 0;
+  const ts = data.ts || 0;
+
+  // Ignore stale data (>60s old)
+  const now = Math.floor(Date.now() / 1000);
+  if (now - ts > 60) process.exit(0);
+
+  // Determine severity
+  let level;
+  if (usedPct >= 80) level = 'CRITICAL';
+  else if (usedPct >= 65) level = 'WARNING';
+  else process.exit(0);
+
+  // Debounce: track last warning to avoid spamming agent
+  // Severity escalation (WARNING->CRITICAL) bypasses debounce
+  const stateFile = path.join(tmpdir, 'cpw-ctx-state');
+  let lastLevel = 'none';
+  let lastCount = 0;
+
+  if (fs.existsSync(stateFile)) {
+    const parts = fs.readFileSync(stateFile, 'utf8').trim().split(':');
+    lastLevel = parts[0] || 'none';
+    lastCount = parseInt(parts[1] || '0', 10);
+  }
+
+  if (level === lastLevel && lastCount < 5) {
+    fs.writeFileSync(stateFile, `${level}:${lastCount + 1}`);
+    process.exit(0);
+  }
+
+  // Reset debounce counter
+  fs.writeFileSync(stateFile, `${level}:0`);
+
+  // Emit warning
+  if (level === 'CRITICAL') {
+    process.stdout.write(`[CONTEXT CRITICAL — ${usedPct}%] Stop after the current task. Save state with /cpw-pause immediately. Do NOT start new complex work.\n`);
+  } else {
+    process.stdout.write(`[CONTEXT WARNING — ${usedPct}%] Context window filling up. Wrap up the current step and consider /cpw-pause or completing CLOSE stage soon.\n`);
+  }
+} catch (e) {
+  // Silent fail — never break tool execution
+}