@claude-pw/framework 0.8.0 → 0.9.0

package/README.es.md

@@ -169,8 +169,8 @@ Issue capturado. ¿Arreglar ahora? (sí/no)
 ```
 mi-proyecto/
 ├── .claude/
-│   ├── commands/       10 slash commands (/cpw-*)
-│   ├── agents/         11 agentes especializados
+│   ├── commands/       12 slash commands (/cpw-*)
+│   ├── agents/         12 agentes especializados (4 con memoria persistente)
 │   ├── rules/          3 reglas context-aware (git, interfaces, testing)
 │   ├── hooks/          Hooks Node.js (statusline, monitor de contexto)
 │   └── settings.json

package/README.ja.md

@@ -169,8 +169,8 @@ Issue captured. Fix now? (yes/no)
 ```
 my-project/
 ├── .claude/
-│   ├── commands/       10個のスラッシュコマンド (/cpw-*)
-│   ├── agents/         11個の専門エージェント
+│   ├── commands/       12個のスラッシュコマンド (/cpw-*)
+│   ├── agents/         12個の専門エージェント（4つに永続メモリ）
 │   ├── rules/          3つのコンテキスト対応ルール（git、インターフェース、テスト）
 │   ├── hooks/          Node.js フック（ステータスライン、コンテキストモニター）
 │   └── settings.json

package/README.md

@@ -169,8 +169,8 @@ Issue captured. Fix now? (yes/no)
 ```
 my-project/
 ├── .claude/
-│   ├── commands/       10 slash commands (/cpw-*)
-│   ├── agents/         11 specialized agents
+│   ├── commands/       12 slash commands (/cpw-*)
+│   ├── agents/         12 specialized agents (4 with persistent memory)
 │   ├── rules/          3 context-aware rules (git, interfaces, testing)
 │   ├── hooks/          Node.js hooks (statusline, context monitor)
 │   └── settings.json

package/README.pt-br.md

@@ -169,8 +169,8 @@ Issue captured. Fix now? (yes/no)
 ```
 my-project/
 ├── .claude/
-│   ├── commands/       10 slash commands (/cpw-*)
-│   ├── agents/         11 agentes especializados
+│   ├── commands/       12 slash commands (/cpw-*)
+│   ├── agents/         12 agentes especializados (4 com memória persistente)
 │   ├── rules/          3 regras sensíveis ao contexto (git, interfaces, testes)
 │   ├── hooks/          Hooks Node.js (statusline, monitor de contexto)
 │   └── settings.json

package/README.zh-cn.md

@@ -169,8 +169,8 @@ UAT 演练：
 ```
 my-project/
 ├── .claude/
-│   ├── commands/       10 个斜杠命令（/cpw-*）
-│   ├── agents/         11 个专用代理
+│   ├── commands/       12 个斜杠命令（/cpw-*）
+│   ├── agents/         12 个专用代理（4 个具有持久记忆）
 │   ├── rules/          3 个上下文感知规则（git、interfaces、testing）
 │   ├── hooks/          Node.js 钩子（状态栏、上下文监控）
 │   └── settings.json

package/RELEASES.md

@@ -2,6 +2,13 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
+## [0.9.0] - 2026-03-15
+
+### Added
+- `/cpw-cleanup` command — archive completed phase files and clean accumulated state (.planning/archive/)
+- `cleanupPolicy` in config.json — configurable retention for applied learnings, debug sessions, quick log entries
+- Cleanup suggestion in `/cpw-next-step` after phase advancement (when 3+ completed phases unarchived)
+
 ## [0.3.0] - 2026-03-15
 
 ### Added

package/install.js

@@ -602,7 +602,7 @@ async function main() {
   header('Listo');
   console.log('');
   console.log(`  ${projectName}/`);
-  console.log('  ├── .claude/commands/    10 commands (/cpw-startup, /cpw-next-step, /cpw-quick, ...)');
+  console.log('  ├── .claude/commands/    12 commands (/cpw-startup, /cpw-next-step, /cpw-quick, ...)');
   console.log('  ├── .claude/agents/      11 agentes (plan-checker, debugger, researcher, implementer, ...)');
   console.log('  ├── .claude/rules/       3 reglas (interfaces, testing, git)');
   console.log('  ├── .claude/hooks/       2 hooks (statusline, context monitor)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-pw/framework",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Structured Project Workflow for Claude Code — adaptive pipeline, context management, quality gates",
   "bin": {
     "claude-pw": "./install.js"

package/templates/CLAUDE.md.tpl

@@ -24,6 +24,7 @@ TODO: Phase 0
 - Ad-hoc tasks that don't affect the plan -> /cpw-quick
 - Debug that may take several sessions -> /cpw-debug (persists state)
 - If something seems broken or inconsistent -> /cpw-health
+- Completed phases accumulating? -> /cpw-cleanup (archive and free context)
 - If the user corrects you, capture the correction in .planning/learnings/queue.md (include the active command in the Command field)
 - Learnings are auto-processed based on config (autoReflect: off/remind/auto)
 - When you discover something non-obvious (debug, workaround), evaluate for skill extraction → .claude/skills/
@@ -37,4 +38,4 @@ TODO: Phase 0
 - plans/decisions.md — Decisions and RFCs
 - src/interfaces/ — Contracts (RFC required to modify)
 - .planning/ — Project state (gitignored by default, set commitPlanning: true to track)
-- .planning/config.json — Workflow config (autoAdvance, granularity, modelProfile, modelOverrides, gitStrategy, commitPlanning, toolingSources, maxConsecutiveFailures, autoReflect)
+- .planning/config.json — Workflow config (autoAdvance, granularity, modelProfile, modelOverrides, gitStrategy, commitPlanning, toolingSources, maxConsecutiveFailures, autoReflect, cleanupPolicy)

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

@@ -0,0 +1,139 @@
+---
+description: "Archive completed phases and clean accumulated state"
+---
+
+## Arguments
+- No arguments: dry-run (show what would be cleaned, ask for confirmation)
+- `--execute`: skip confirmation, execute immediately
+
+## 0. Load state
+
+Read `.planning/config.json` -> extract `cleanupPolicy` (use defaults if missing):
+- `archiveCompletedPhases`: true
+- `keepAppliedLearnings`: 20
+- `keepResolvedDebug`: 5
+- `keepQuickLogDone`: 10
+
+Read PLAN.md -> extract phases table. Identify phases with Status = "done".
+Read STATUS.md -> identify current phase (to avoid archiving it).
+
+If no completed phases and no accumulated state to clean:
+```
+Nothing to clean up. All phases are current or pending.
+```
+STOP.
+
+## 1. Identify what to clean
+
+### 1.1 Completed phase files
+If `archiveCompletedPhases` is true:
+For each phase with Status "done" in PLAN.md:
+- Check if `plans/phase-N.md` still exists (not already archived)
+- Check if `plans/phase-N-context.md` exists
+- Add to archive list
+- NEVER archive the current phase or pending phases
+
+### 1.2 Quick log done entries
+Read `.planning/quick/log.md` (if exists):
+- Count entries with Status: done or dismissed
+- If count > `keepQuickLogDone`: mark oldest excess entries for removal
+
+### 1.3 Resolved debug sessions
+List `.planning/debug/resolved/` (if exists):
+- Count files
+- If count > `keepResolvedDebug`: mark oldest files for deletion (by filename date prefix)
+
+### 1.4 Applied learnings
+Read `.planning/learnings/applied.md` (if exists):
+- Count entries (each entry starts with `---`)
+- If count > `keepAppliedLearnings`: mark oldest excess entries for trimming
+
+### 1.5 Stale files
+- `.planning/handoff.md` — if it exists AND STATUS.md does NOT show a handoff in progress
+- `.planning/uat.md` — if it exists AND all phases it references are done (no active UAT)
+
+## 2. Present cleanup plan
+
+```
+Cleanup Summary:
+
+ARCHIVE (move to .planning/archive/):
+  - plans/phase-0.md (6 steps, all done)
+  - plans/phase-0-context.md
+  - plans/phase-1.md (4 steps, all done)
+
+TRIM:
+  - quick/log.md: remove N done entries (keeping last M)
+  - debug/resolved/: delete N old sessions (keeping last M)
+  - learnings/applied.md: trim N old entries (keeping last M)
+
+DELETE:
+  - .planning/handoff.md (stale)
+
+NO CHANGES:
+  - plans/phase-2.md (current phase)
+  - plans/decisions.md (cumulative, always kept)
+  - docs/* (living documentation, always kept)
+```
+
+If nothing to clean in a category, omit it from the summary.
+
+If `--execute`: show the summary and proceed to step 3.
+Otherwise: ask "Proceed? (yes/no)". If no: STOP.
+
+## 3. Execute
+
+### 3.1 Archive phase files
+```bash
+mkdir -p .planning/archive
+```
+For each phase in the archive list:
+- Move `plans/phase-N.md` to `.planning/archive/phase-N.md`
+- Move `plans/phase-N-context.md` to `.planning/archive/phase-N-context.md` (if exists)
+
+### 3.2 Update PLAN.md
+For each archived phase, change the sub-plan column from `plans/phase-N.md` to `(archived)`:
+```
+| 0 | Stack and Scaffolding | plans/phase-0.md | done |
+```
+becomes:
+```
+| 0 | Stack and Scaffolding | (archived) | done |
+```
+
+### 3.3 Trim quick log
+Remove done/dismissed entries beyond the keep limit from `.planning/quick/log.md`.
+Keep the most recent N entries (by date). Preserve the table header.
+
+### 3.4 Delete old debug sessions
+Delete files from `.planning/debug/resolved/` beyond the keep limit.
+Delete the oldest by filename date prefix.
+
+### 3.5 Trim applied learnings
+Remove the oldest entries from `.planning/learnings/applied.md` beyond the keep limit.
+Keep the most recent N entries. Each entry is delimited by `---`.
+
+### 3.6 Delete stale files
+Delete identified stale files (handoff.md, uat.md).
+
+### 3.7 Commit
+Read `commitPlanning` from `.planning/config.json`.
+
+Git add the changes:
+- `PLAN.md` (always — sub-plan column updated)
+- `plans/` (always — phase files removed)
+- `.planning/` (only if `commitPlanning: true`)
+
+`make commit m="chore: cleanup completed phases and accumulated state"`
+
+## 4. Report
+
+```
+Cleanup complete.
+
+Archived: N phase files → .planning/archive/
+Trimmed: M quick log entries, K debug sessions, L learnings
+Deleted: P stale files
+
+Next: /cpw-next-step to continue.
+```

package/templates/claude/commands/cpw-next-step.md

@@ -8,6 +8,10 @@ description: "Load context and execute the next pipeline stage"
 
 ## 0. Health check (session start)
 
+### Orphan phase-active cleanup
+If `.planning/.phase-active` exists AND `--phase` flag is NOT active:
+- Delete the file (leftover from interrupted session)
+
 ### Post-update detection
 If `.planning/.updated-from` exists:
 - Read the file — it contains the previous version
@@ -266,7 +270,7 @@ Estimated context resets: [N / based on step count, suggest /clear every 3 steps
 ```
 
 Ask: "Execute this plan? (yes / adjust / cancel)"
-- **yes**: proceed with auto-advance. When delegating to agents during --phase, spawn them with `permissionMode: bypassPermissions` to avoid permission interruptions.
+- **yes**: create `.planning/.phase-active` (enables auto-approve for tool permissions via PreToolUse hook), then proceed with auto-advance.
 - **adjust**: ask what to change (skip a step, reorder, modify pipeline). Update sub-plan if needed, re-present.
 - **cancel**: exit --phase mode, continue as normal /cpw-next-step (step by step)
 
@@ -576,6 +580,7 @@ If all deliverables passed (or issues were fixed):
   ## Session notes
   - (empty)
   ```
+- Delete `.planning/.phase-active` if it exists (re-enables normal tool permissions)
 - If `--phase` flag is active: STOP. Do NOT advance to next phase. Report:
   ```
   Phase N complete. UAT passed.
@@ -593,4 +598,13 @@ If all deliverables passed (or issues were fixed):
   "  3. `/cpw-next-step` — start directly"
 - If autoAdvance is **auto** or **yolo** (and no --phase): Suggest /clear for context refresh, then automatically continue with Phase N+1 (run tooling audit → first step).
 
+### Cleanup suggestion
+After phase advancement, count completed phases in PLAN.md that still have sub-plan files in `plans/` (sub-plan column is NOT `(archived)`).
+If count >= 3:
+```
+Tip: You have N completed phase files that could be archived.
+     Run /cpw-cleanup to free up context.
+```
+This is a suggestion only — do NOT block advancement.
+
 NEVER advance between phases without completing UAT first (in any mode).

package/templates/claude/hooks/cpw-phase-approve.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Auto-approve tool calls during --phase execution
+# Created by: /cpw-next-step --phase (creates .planning/.phase-active)
+# Removed by: /cpw-next-step at UAT or phase end
+
+PHASE_FILE=".planning/.phase-active"
+
+if [ -f "$PHASE_FILE" ]; then
+  # Check for stale file (>24h)
+  if [ "$(find "$PHASE_FILE" -mmin +1440 2>/dev/null)" ]; then
+    rm -f "$PHASE_FILE"
+    exit 0
+  fi
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"--phase active: plan approved by user"}}'
+fi
+exit 0

package/templates/claude/settings.json

@@ -4,6 +4,15 @@
     "command": "node .claude/hooks/cpw-statusline.js"
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "bash .claude/hooks/cpw-phase-approve.sh"
+        }]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "matcher": "",

package/templates/planning/config.json

@@ -7,5 +7,11 @@
   "toolingSources": ["skills.sh", "claude-code-templates"],
   "maxConsecutiveFailures": null,
   "gitStrategy": "trunk-based",
-  "autoReflect": "remind"
+  "autoReflect": "remind",
+  "cleanupPolicy": {
+    "archiveCompletedPhases": true,
+    "keepAppliedLearnings": 20,
+    "keepResolvedDebug": 5,
+    "keepQuickLogDone": 10
+  }
 }