@claude-pw/framework 0.8.1 → 0.9.1

package/README.es.md

@@ -169,7 +169,7 @@ Issue capturado. ¿Arreglar ahora? (sí/no)
 ```
 mi-proyecto/
 ├── .claude/
-│   ├── commands/       11 slash commands (/cpw-*)
+│   ├── 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)

package/README.ja.md

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

package/README.md

@@ -169,7 +169,7 @@ Issue captured. Fix now? (yes/no)
 ```
 my-project/
 ├── .claude/
-│   ├── commands/       11 slash commands (/cpw-*)
+│   ├── 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)

package/README.pt-br.md

@@ -169,7 +169,7 @@ Issue captured. Fix now? (yes/no)
 ```
 my-project/
 ├── .claude/
-│   ├── commands/       11 slash commands (/cpw-*)
+│   ├── 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)

package/README.zh-cn.md

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

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.1",
+  "version": "0.9.1",
   "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,152 @@
+---
+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 ALL lists are empty after step 1 filtering (no files to archive, nothing exceeds retention limits, no stale files):
+```
+Nothing to clean — completed phases already archived and accumulated state within retention limits.
+```
+STOP.
+
+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`.
+
+Build commit message based on what was actually executed:
+- If phases were archived AND state was trimmed: `"chore: archive phases N-M and trim planning state"`
+- If only phases were archived: `"chore: archive completed phases N-M"`
+- If only state was trimmed: `"chore: trim accumulated planning state"`
+
+Git add the changes:
+- `PLAN.md` (always — sub-plan column updated)
+- `plans/` (always — phase files removed)
+- `.planning/` (only if `commitPlanning: true`)
+
+Check if there are staged changes (`git diff --cached --quiet`).
+- If there are changes: `make commit m="[built message]"`
+- If there are NO changes (e.g., only .planning/ was modified and commitPlanning is false): skip commit. Report: "Only local state cleaned (.planning/ is gitignored) — no commit needed."
+
+## 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

@@ -598,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/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
+  }
 }