chore: add compaction resilience and align with CC v2.1.63-69

.claude/commands/full-review.md

@@ -30,6 +30,20 @@ At start, verify CCO repo using Claude's native tools:
 
 **Use Glob/Read for file detection. Git commands are cross-platform.**
 
+## State Management
+
+Per CCO Rules: State Management. This command uses task prefix `[FR]`.
+
+| Task | Created | Completed |
+|------|---------|-----------|
+| `[FR] Inventory` | Step-2 start | Step-2 end |
+| `[FR] Analyze Batch 1` | Step-3 Batch 1 launch | Batch 1 done |
+| `[FR] Analyze Batch 2` | Step-3 Batch 2 launch | Batch 2 done |
+| `[FR] Prioritize` | Step-4 start | Step-4 end |
+| `[FR] Apply` | Step-6 start | Step-6 end |
+
+**Recovery:** At Step-1, run TaskList. If `[FR]` tasks exist with incomplete status → per State Management recovery protocol.
+
 ## Context Check [CRITICAL]
 
 If not in CCO repository root:
@@ -45,7 +59,7 @@ Run this command from the ClaudeCodeOptimizer directory.
 |------|------|--------|
 | 1 | Setup | Q1: Review mode selection |
 | 2 | Inventory | Detect counts via Glob |
-| 3 | Analyze | 4 Explore agent groups (parallel) |
+| 3 | Analyze | 2+2 batched Explore agent groups |
 | 4 | Prioritize | 80/20 findings |
 | 5 | Approval | Q2: Select fixes (conditional) |
 | 6 | Apply | Delegate to cco-agent-apply |
@@ -74,6 +88,10 @@ if (!isUnattended && !isReportOnly) {
 
 ## Step-2: Inventory Detection
 
+**Recovery check:** TaskList → filter `[FR]` prefix. If incomplete tasks found → per State Management recovery protocol.
+
+TaskCreate `[FR] Inventory` (status: in_progress).
+
 ```javascript
 // Cross-platform detection using Claude's native tools — all counts are dynamic
 skills    = Glob("skills/cco-*/SKILL.md").length
@@ -87,11 +105,20 @@ inventory = { skills, agents, docs, workflows, version }
 
 **Note:** Rules are in `rules/cco-rules.md` (single source of truth). Never hardcode expected counts — always detect dynamically and compare across reference files.
 
+TaskUpdate `[FR] Inventory` → completed. Store counts in description.
+
 ---
 
-## Step-3: 8-Category Analysis [PARALLEL AGENTS]
+## Step-3: 8-Category Analysis [BATCHED: 2+2 AGENTS]
+
+Per CCO Rules: Parallel Execution (max 2 Task calls per message). Launch in 2 batches:
 
-Launch 4 parallel Explore agents covering 8 categories:
+**Batch 1:** Group A (Inventory & Release) + Group B (Skill & Agent Quality + Architecture)
+**Batch 2:** Group C (AI Communication + Efficiency) + Group D (Production Standards + Documentation)
+
+Wait for Batch 1 to complete before launching Batch 2. After each batch, TaskUpdate corresponding `[FR] Analyze Batch N` → completed, write findings to description in compact format.
+
+8 categories across 4 groups:
 
 ### Group A: Inventory & Release (Cat 1 + Cat 8)
 
@@ -215,11 +242,15 @@ Per CCO Rules: Severity Levels.
 
 ## Step-4: Prioritize
 
+TaskCreate `[FR] Prioritize` (status: in_progress).
+
 Rank findings by 80/20 rule:
 1. **Quick Win** — CRITICAL + HIGH, auto-fixable
 2. **Moderate** — MEDIUM, requires targeted edit
 3. **Complex** — LOW or multi-file structural changes
 
+TaskUpdate `[FR] Prioritize` → completed. Store prioritized findings in description.
+
 ---
 
 ## Step-5: Fix Approval [SKIP IF --auto or --preview or zero findings]
@@ -247,6 +278,10 @@ if (findings.length > 0) {
 
 ## Step-6: Apply Fixes [DELEGATE TO AGENT]
 
+TaskCreate `[FR] Apply` (status: in_progress).
+
+**Recovery-aware read:** If findings not in conversation context (compaction occurred), reconstruct from TaskGet on `[FR] Analyze Batch 1/2` task descriptions.
+
 ```javascript
 if (toApply.length > 0) {
   Task("cco-agent-apply", `
@@ -268,6 +303,8 @@ if (toApply.length > 0) {
 
 ## Step-7: Summary
 
+**State cleanup:** TaskUpdate all `[FR]` tasks → completed.
+
 ```
 ═══════════════════════════════════════════════════════════
                      CCO FULL REVIEW

agents/cco-agent-analyze.md

@@ -1,7 +1,11 @@
 ---
 name: cco-agent-analyze
 description: "Sub-agent: codebase analysis with severity scoring — security, privacy, hygiene, types, performance, robustness, functional-completeness. Used by /cco-optimize, /cco-align, /cco-blueprint and autonomously for code audits."
-tools: Glob, Read, Grep, Bash
+tools:
+  - Glob
+  - Read
+  - Grep
+  - Bash
 model: haiku
 ---
 

agents/cco-agent-apply.md

@@ -1,7 +1,15 @@
 ---
 name: cco-agent-apply
 description: "Sub-agent: batch write operations with verification, cascade fixing, and accounting. Used by /cco-optimize, /cco-align and autonomously for bulk fixes."
-tools: Grep, Read, Glob, Bash, Edit, Write, NotebookEdit, AskUserQuestion
+tools:
+  - Grep
+  - Read
+  - Glob
+  - Bash
+  - Edit
+  - Write
+  - NotebookEdit
+  - AskUserQuestion
 ---
 
 # cco-agent-apply

agents/cco-agent-research.md

@@ -1,7 +1,12 @@
 ---
 name: cco-agent-research
 description: "Sub-agent: web search, source scoring, and CRAAP+ synthesis. Used by /cco-research skill and autonomously for research tasks."
-tools: WebSearch, WebFetch, Read, Grep, Glob
+tools:
+  - WebSearch
+  - WebFetch
+  - Read
+  - Grep
+  - Glob
 model: haiku
 ---
 

docs/architecture.md

@@ -86,7 +86,16 @@ Rules are loaded automatically at session start via Claude Code's native mechani
 
 Skills use Claude Code's native skill mechanism with `SKILL.md` files in `~/.claude/skills/{name}/`. Frontmatter fields (`allowed-tools`, `description`) are enforced by Claude Code, unlike the legacy `commands/` directory.
 
-6 skills have auto-invoke enabled (triggered by natural language), 2 require explicit invocation (`/cco-blueprint`, `/cco-update`).
+8 skills total: 6 have auto-invoke enabled (triggered by natural language) and 2 require explicit invocation.
+
+| Mode | Skills |
+|------|--------|
+| Auto-invoke | `cco-optimize`, `cco-align`, `cco-commit`, `cco-research`, `cco-docs`, `cco-pr` |
+| Explicit only | `cco-blueprint` (`/cco-blueprint`), `cco-update` (`/cco-update`) |
+
+### Skill Variables
+
+Claude Code provides `${CLAUDE_SKILL_DIR}` (v2.1.69+), which resolves to the skill's own directory at runtime. CCO skills currently use inline content and reference agents by name, so this variable is not yet used. It becomes relevant when skills need to reference local assets (templates, schemas, config files) stored alongside SKILL.md.
 
 ### Shared Patterns
 
@@ -160,6 +169,18 @@ Skills invoke agents using these standard groupings:
 5. Merge findings, deduplicate by file:line (keep highest severity)
 6. Per CCO Rules: CRITICAL Escalation — validate CRITICAL findings with opus before proceeding
 
+### Compaction Resilience
+
+Long-running skills use Task tools for compaction-resilient state tracking.
+
+| Layer | Mechanism | Survives Compaction |
+|-------|-----------|---------------------|
+| Phase progress | TaskCreate/TaskUpdate status | Yes |
+| Findings summary | Task description (compact format) | Yes |
+| Recovery anchor | TaskList + prefix filter | Yes |
+
+Skills with 3+ phases create prefixed tasks (`[BP]`, `[OPT]`, `[ALN]`, `[FR]`, `[RSC]`, `[DOC]`) and update them at phase gates. On compaction, TaskList retrieves completed phases and TaskGet reconstructs findings from compact descriptions. See CCO Rules: State Management.
+
 ### File Manifest Sync
 
 The file list in `extras/installer/manifest.go` is the single source of truth for installed files. When adding or removing a skill/agent file, update `manifest.go`.

docs/skills.md

@@ -266,6 +266,22 @@ Update CCO to the latest version.
 
 ---
 
+## CCO vs Built-in Commands
+
+Claude Code includes built-in `/simplify` and `/batch` commands (v2.1.63+). Key differences from CCO:
+
+| Feature | `/simplify` (built-in) | `/cco-optimize` |
+|---------|----------------------|-----------------|
+| Scope | Changed code only (reuse, quality, efficiency) | 9 scopes, 97 checks across entire codebase |
+| Severity scoring | No | CRITICAL/HIGH/MEDIUM/LOW with confidence |
+| Parallel analysis | No | Batched agent analysis |
+| Accounting | No | applied + failed + needs_approval = total |
+| Blueprint integration | No | Feeds into `/cco-blueprint` health scores |
+
+Use `/simplify` for quick post-edit cleanup. Use `/cco-optimize` for comprehensive code quality analysis.
+
+---
+
 ## Common Patterns
 
 ### Unattended Mode
@@ -280,6 +296,16 @@ Update CCO to the latest version.
 
 Per CCO Rules: `applied + failed + needs_approval = total` (no silent skips)
 
+### Compaction Resilience
+
+Long-running skills (`/cco-blueprint`, `/cco-optimize`, `/cco-align`, `/cco-research`, `/cco-docs`, `/full-review`) track progress via Task tools. If context compaction occurs mid-skill:
+
+1. TaskList shows completed vs pending phases
+2. Completed phase findings are preserved in task descriptions
+3. Only incomplete phases are re-run
+
+Per CCO Rules: State Management.
+
 ### Recovery
 
 | Situation | Command |

release-please-config.json

@@ -1,4 +1,6 @@
 {
+  "pull-request-title-pattern": "chore: release v${version}",
+  "pull-request-header": ":bookmark: Automated release — review changelog below, then merge to publish.",
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
   "packages": {
     ".": {

rules/cco-rules.md

@@ -100,6 +100,20 @@ When --auto active: no questions, no deferrals. Fix everything except large arch
 
 Agents return structured data as final text message. Never write to files. On failure: {"error": "message"}. Validate before processing; retry once if malformed. On second failure, continue with remaining groups. Score failed dimensions as N/A.
 
+**Bash sanitization:** When agents construct Bash commands dynamically (file paths from findings, user-provided scope names), never interpolate raw values into shell strings. Use `--` to terminate flag parsing, quote all path arguments, and reject values containing shell metacharacters (`;`, `|`, `&`, `$`, `` ` ``, `\n`). Prefer passing arguments as separate tokens over string concatenation.
+
+### Hook Integration
+
+Claude Code supports `PreToolUse`, `PostToolUse`, `Stop`, and `InstructionsLoaded` hooks in skill and agent frontmatter. CCO leverages hooks where they add portable, cross-project value:
+
+| Hook | Where | Purpose |
+|------|-------|---------|
+| `InstructionsLoaded` | User config | Auto-trigger `/cco-update --check` on session start (optional, user-configured) |
+| `PreToolUse` | Skills using Bash | Validate dynamically constructed commands before execution (sanitization gate) |
+| `PostToolUse` | Agent apply | Verify edit/write results against expectations (cascade trigger) |
+
+Hook commands must be portable (no OS-specific or project-specific tool assumptions). Hooks that require external tools (gitleaks, linters) follow Tool Prerequisites: skip silently if unavailable.
+
 ### Tool Prerequisites
 
 Verify required external tools before execution.
@@ -128,6 +142,7 @@ When findings > 0 and not --auto, display plan table before asking:
 2. If "By Severity": severity filter (multiselect) — CRITICAL / HIGH / MEDIUM / LOW
 3. Use `markdown` preview on each option to show the findings that would be affected (full table for Fix All, filtered for By Severity, etc.)
 4. If the user's response includes annotations (notes), use them to adjust behavior — e.g., "skip test coverage items" filters findings before apply
+5. **Fix planning** (skills with apply phase): Before applying, group findings by file dependency and display execution plan — independent groups can be applied in parallel, dependent groups sequentially
 
 ### Needs-Approval Protocol
 
@@ -173,7 +188,7 @@ Agent frontmatter `model: haiku` is the default. Skills override via Task tool's
 
 When any analyze agent reports a CRITICAL finding:
 1. Skill isolates the CRITICAL finding(s)
-2. Single Task call to cco-agent-analyze (model: opus, scopes: [original scope], mode: review) with only the file(s) containing CRITICAL findings
+2. Single Task call to cco-agent-analyze (model: opus, scopes: [original scope], mode: review) with only the file(s) containing CRITICAL findings. Include "ultrathink" in the prompt to ensure high effort — default medium effort on Opus 4.6 may miss nuanced security patterns.
 3. Opus confirms → keep CRITICAL. Opus rejects → downgrade to HIGH or discard.
 4. Applied in all modes including --auto. CRITICAL false positives are costlier than one extra validation.
 5. Max 1 escalation call per skill invocation (batch all CRITICALs into one call).
@@ -184,6 +199,28 @@ Fix suggestions and applied changes must comply with: DRY (no duplicate logic),
 
 Agents verify before suggesting/applying: existing pattern exists? → reference it. New abstraction needed? → only if 3+ uses. Cross-module change? → needs_approval.
 
+### State Management
+
+Skills with 3+ phases use Task tools for compaction-resilient progress tracking. No files are created.
+
+**Task lifecycle:**
+1. TaskCreate at skill start — one task per major phase group, prefixed: `[BP]`, `[OPT]`, `[ALN]`, `[FR]`, `[RSC]`, `[DOC]`
+2. TaskUpdate after each phase gate — status: in_progress → completed, description: compact findings
+3. Recovery: TaskList at skill start — if own-prefix tasks exist with incomplete status, offer resume
+
+**Compact findings format** (stored in task description):
+
+    ID|SEVERITY|file:line|title
+
+One line per finding. Apply phase reads these via TaskGet to reconstruct context.
+
+**Recovery protocol:**
+- Own-prefix tasks found + incomplete → offer resume (--auto: resume silently, skip completed phases, re-run incomplete)
+- Own-prefix tasks found + all completed → stale, start fresh
+- No own-prefix tasks → proceed normally
+
+**Fix planning:** Before apply phase (findings > 0, not --auto, not --preview), group findings by file dependency and display execution plan with independent/dependent groups.
+
 ### Project Types
 
 Standard project type taxonomy used across all CCO skills, agents, and scoring. Referenced as `context.projectType`.

skills/cco-align/SKILL.md

@@ -1,7 +1,14 @@
 ---
 description: Align codebase with ideal architecture — gap analysis and strategic fixes. Use for architecture review, structural improvements, or design pattern evaluation.
 argument-hint: "[--auto] [--preview] [--force-approve]"
-allowed-tools: Read, Grep, Glob, Edit, Bash, Task, AskUserQuestion
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Edit
+  - Bash
+  - Task
+  - AskUserQuestion
 ---
 
 # /cco-align
@@ -22,6 +29,20 @@ For tactical file-level fixes, use `/cco-optimize`.
 | `--preview` | Analyze only, show gaps and findings, don't apply |
 | `--force-approve` | Auto-apply needs_approval items (architectural changes). Combines with `--auto`. |
 
+## State Management
+
+Per CCO Rules: State Management. This skill uses task prefix `[ALN]`.
+
+| Task | Created | Completed |
+|------|---------|-----------|
+| `[ALN] Analyze Batch 1` | Phase 2 Batch 1 launch | Batch 1 done |
+| `[ALN] Analyze Batch 2` | Phase 2 Batch 2 launch | Batch 2 done |
+| `[ALN] Gap+Recs` | Phase 3 start | Phase 4 end |
+| `[ALN] Apply` | Phase 6 start | Phase 6 end |
+| `[ALN] Summary` | Phase 7 start | Phase 7 end |
+
+**Recovery:** At Phase 1 start, run TaskList. If `[ALN]` tasks exist with incomplete status → per State Management recovery protocol.
+
 ## Context
 
 - Git status: !`git status --short --branch`
@@ -38,6 +59,8 @@ Setup → Analyze → Gap Analysis → Recommendations → [Plan] → Apply →
 
 **Pre-flight:** Verify git repo: `git rev-parse --git-dir 2>/dev/null` → not a repo: warn "Not a git repo — git context unavailable" and continue (git optional for align).
 
+**Recovery check:** TaskList → filter `[ALN]` prefix. If incomplete tasks found → per State Management recovery protocol.
+
 ```javascript
 AskUserQuestion([{
   question: "Which areas should be reviewed?",
@@ -65,12 +88,16 @@ Per CCO Rules: Parallel Execution, Agent Contract, Model Routing.
 
 Wait for ALL batches. Phase gate: do not proceed until all tracks return or fail.
 
+**State update:** After each batch, TaskCreate + TaskUpdate `[ALN] Analyze Batch N` → completed, write findings to description in compact format.
+
 Merge findings. Per CCO Rules: CRITICAL Escalation — if any CRITICAL findings, run single opus validation call before proceeding.
 
 **Gate:** If findings = 0 → skip Phase 5-6, display gap analysis (Phase 3-4) with: `cco-align: OK | No structural issues | Gaps: {metric table}`
 
 ### Phase 3: Gap Analysis [CURRENT vs IDEAL]
 
+TaskCreate `[ALN] Gap+Recs` (status: in_progress).
+
 If blueprint profile exists in CLAUDE.md: use its Ideal Metrics as targets. Otherwise: use project-type defaults per `/cco-blueprint`.
 
 Calculate gaps: current vs ideal for coupling, cohesion, complexity, coverage. Display Current vs Ideal table.
@@ -106,10 +133,18 @@ Categorize by effort/impact: Quick Win → Moderate → Complex → Major.
 
 ### Phase 5: Plan Review [findings > 0, SKIP if --auto]
 
+TaskUpdate `[ALN] Gap+Recs` → completed.
+
 Per CCO Rules: Plan Review Protocol — display findings table (ID, severity, title, file:line), then ask with markdown previews. Options: Fix All (recommended) / By Severity / Review Each / Report Only.
 
+Per CCO Rules: Plan Review Protocol item 5 (fix planning) — display fix execution plan before apply.
+
 ### Phase 6: Apply [SKIP if --preview]
 
+TaskCreate `[ALN] Apply` (status: in_progress).
+
+**Recovery-aware read:** If findings not in conversation context (compaction occurred), reconstruct from TaskGet on `[ALN] Analyze Batch 1/2` task descriptions.
+
 Send to cco-agent-apply (scope: fix, findings: [...], fixAll: --auto). Count findings, not locations. On error: count as failed, continue.
 
 ### Phase 6.1: Needs-Approval Review [CONDITIONAL, SKIP if --auto, AUTO-APPLY if --force-approve]
@@ -118,6 +153,8 @@ Per CCO Rules: Needs-Approval Protocol.
 
 ### Phase 7: Summary
 
+**State cleanup:** TaskUpdate all `[ALN]` tasks → completed. TaskCreate `[ALN] Summary` with final accounting in description.
+
 Per CCO Rules: Accounting, Auto Mode.
 
 Interactive output format: