cclaw-cli 0.5.16 → 0.6.0

package/dist/content/learnings.js

@@ -20,6 +20,7 @@ Use it to keep durable knowledge that should survive sessions:
 - **rule**: hard constraint to follow every time
 - **pattern**: repeatable way that works well in this project
 - **lesson**: non-obvious outcome from a failure or trade-off
+- **compound**: post-ship insight about how to make the *next* feature faster (process accelerator, not domain rule)
 
 ## HARD-GATE
 
@@ -33,12 +34,25 @@ Under \`/cc-learn\`, only modify the knowledge store (\`${KNOWLEDGE_PATH}\`) or
 - Context: one short line
 - Insight: one short line
 - Reuse: one short line
+- Confidence: high | medium | low      (optional)
+- Domain: api | infra | ui | testing | …  (optional)
+- Project: <repo or scope name>        (optional)
 \`\`\`
 
 Rules:
-- Type must be exactly one of \`rule\`, \`pattern\`, \`lesson\` (lowercase).
-- Never rewrite history silently; append a newer correction entry instead.
+- Type must be exactly one of \`rule\`, \`pattern\`, \`lesson\`, \`compound\` (lowercase).
+- Never rewrite history silently; append a newer correction entry instead. To replace, prefix the new entry with \`Supersedes: <old-title>\`.
 - Keep entries concise and actionable.
+- Optional fields (\`Confidence\`, \`Domain\`, \`Project\`) are forward-compatible and used by the **knowledge-curation** skill — fill them when known.
+
+## Curation policy (target: ≤ 50 active entries)
+
+The knowledge file is append-only, but entries can be **superseded** rather than deleted:
+
+- When you discover a more correct rule, append a new entry with \`Supersedes: <old-title>\`.
+- During \`/cc-learn curate\`, the assistant surfaces candidates for soft-archive (move to \`.cclaw/knowledge.archive.md\`) when the active file exceeds 50 entries or contains stale/duplicate entries.
+
+See the **knowledge-curation** utility skill for the full curation protocol.
 
 ## Subcommands
 
@@ -52,8 +66,13 @@ Rules:
 
 ### \`/cc-learn add\`
 - Ask for: \`type\`, \`short title\`, \`context\`, \`insight\`, \`reuse\`.
+- Optionally ask for: \`confidence\`, \`domain\`, \`project\`.
 - Append one entry using current UTC timestamp.
 - Re-read the file tail and confirm the entry was written.
+
+### \`/cc-learn curate\`
+- Hand off to the **knowledge-curation** skill (read-only audit + soft-archive plan).
+- Never deletes from \`${KNOWLEDGE_PATH}\` without an explicit user-approved archive plan.
 `;
 }
 export function learnCommandContract() {
@@ -73,7 +92,8 @@ Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`
 |---|---|---|
 | (default) | — | Show recent knowledge entries (tail view). |
 | \`search\` | \`<query>\` | Search knowledge text for relevant prior rules/patterns/lessons. |
-| \`add\` | — | Append a new entry with type \`rule\` / \`pattern\` / \`lesson\`. |
+| \`add\` | — | Append a new entry with type \`rule\` / \`pattern\` / \`lesson\` / \`compound\`. |
+| \`curate\` | — | Hand off to the **knowledge-curation** skill: read-only audit + soft-archive plan when the active file exceeds the curation threshold. |
 `;
 }
 export function selfImprovementBlock(stageName) {
@@ -96,7 +116,7 @@ cat >> ${KNOWLEDGE_PATH} <<EOF
 EOF
 \`\`\`
 
-Type must be exactly one of: \`rule\`, \`pattern\`, \`lesson\`.
+Type must be exactly one of: \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
 `;
 }
 export function learningsSearchPreamble(stage) {
@@ -110,7 +130,7 @@ If the file is empty, continue normally.
 export function learningsAgentsMdBlock() {
     return `### Knowledge Store
 
-\`${KNOWLEDGE_PATH}\` — append-only markdown memory with entry types \`rule\`, \`pattern\`, \`lesson\`.
+\`${KNOWLEDGE_PATH}\` — append-only markdown memory with entry types \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
 At session start and stage transitions, load recent entries and apply relevant ones.
 If a non-obvious reusable rule/pattern/lesson is discovered, append a new entry.
 `;

package/dist/content/meta-skill.js

@@ -89,6 +89,18 @@ These skills live in \`.cclaw/skills/\` but have no slash commands. They activat
 
 **Activation rule:** When a contextual skill applies, read its SKILL.md and follow it as a supplementary lens alongside the current stage. Do not skip the stage workflow — the contextual skill adds depth, not a detour.
 
+## Custom Skills (project-owned, sync-safe)
+
+\`.cclaw/custom-skills/\` is a sync-safe directory. \`cclaw sync\` and \`cclaw upgrade\` **never overwrite** files there.
+
+Use it to add **project-specific** skills that complement the managed library:
+
+- Each skill: \`.cclaw/custom-skills/<folder>/SKILL.md\` with the same frontmatter format as managed skills (\`name\` + \`description\` triggering routing).
+- Activate by mentioning the skill name explicitly, or rely on semantic routing from the description.
+- See \`.cclaw/custom-skills/README.md\` for the full convention and a starter template under \`.cclaw/custom-skills/example/\`.
+
+If a custom skill turns out to generalize (e.g. another project would want the same lens), promote it to a managed skill via a contribution to the cclaw repo — managed skills get versioning and maintenance.
+
 ## Progressive Disclosure (Depth / See Also)
 
 Use this loading order to keep context lean while preserving depth:

package/dist/content/next-command.js

@@ -56,6 +56,14 @@ This is the only progression command the user needs to drive the entire flow. St
 → If current stage's \`next\` is **\`done\`**: report **"Flow complete. All stages finished."** and stop.
 → Otherwise: load **\`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`** and **\`${RUNTIME_ROOT}/commands/<nextStage>.md\`** for the successor stage. Execute that stage's protocol.
 
+### Track-aware successor resolution
+
+\`flow-state.json\` carries a \`track\` field (\`"quick"\` or \`"standard"\`) and a \`skippedStages\` array.
+
+- If \`track === "quick"\`, the critical path is **spec → tdd → review → ship**. When advancing, skip any stage listed in \`skippedStages\` — i.e. after the current stage completes, pick the next stage that is NOT in \`skippedStages\`.
+- If \`track === "standard"\`, advance through all 8 stages in their natural order.
+- Never reintroduce a skipped stage mid-run. If the user wants upstream scoping work, they must archive the run and start a new one with \`track: "standard"\`.
+
 ## Resume Semantics
 
 \`/cc-next\` in a **new session** = resume from where you left off:

package/dist/content/observe.js

@@ -1613,6 +1613,14 @@ export function claudeHooksJsonWithObservation() {
                             command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
                             timeout: 10
                         }]
+                }],
+            PreCompact: [{
+                    matcher: "manual|auto",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`,
+                            timeout: 10
+                        }]
                 }]
         }
     }, null, 2);
@@ -1632,6 +1640,8 @@ export function cursorHooksJsonWithObservation() {
                     command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
                 }],
             sessionCompact: [{
+                    command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`
+                }, {
                     command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
                 }],
             preToolUse: [{
@@ -1684,6 +1694,14 @@ export function codexHooksJsonWithObservation() {
                             command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
                             timeout: 10
                         }]
+                }],
+            PreCompact: [{
+                    matcher: "manual|auto",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`,
+                            timeout: 10
+                        }]
                 }]
         }
     }, null, 2);

package/dist/content/session-hooks.js

@@ -34,7 +34,7 @@ When a new session begins in any harness:
 ### What to show the user at session start
 
 \`\`\`
-Cclaw flow state: [current stage] ([N] of 9 stages completed)
+Cclaw flow state: [current stage] ([N] of 8 stages completed)
 Knowledge highlights: [rule/pattern 1], [rule/pattern 2], [rule/pattern 3]
 Next action: /cc-[stage] to continue, or describe what you'd like to do.
 \`\`\`

package/dist/content/stage-schema.js

@@ -1147,7 +1147,8 @@ const REVIEW = {
         { id: "review_layer2_architecture", description: "Architecture fit review completed." },
         { id: "review_severity_classified", description: "All findings are severity-tagged." },
         { id: "review_criticals_resolved", description: "No unresolved critical blockers remain." },
-        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." }
+        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." },
+        { id: "review_completeness_scored", description: "Completeness score is computed and recorded (AC coverage, task coverage, slice coverage, adversarial pass)." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/07-review.md`.",
@@ -1289,6 +1290,7 @@ const REVIEW = {
         { section: "Layer 2 Findings", required: true, validationRule: "Each finding has severity, description, and resolution status." },
         { section: "Review Army Contract", required: true, validationRule: "Structured findings include id/severity/confidence/fingerprint/reportedBy/status with dedup reconciliation summary." },
         { section: "Review Readiness Dashboard", required: true, validationRule: "At least 4 readiness checklist lines including blocker and recommendation status." },
+        { section: "Completeness Score", required: true, validationRule: "Records AC coverage, task coverage, test-slice coverage, and adversarial-review pass status as numeric or boolean values. At minimum, a line like 'AC coverage: N/M' or 'AC coverage: 100%'." },
         { section: "Severity Summary", required: true, validationRule: "Per-severity count lines for critical, important, and suggestion buckets." },
         { section: "Final Verdict", required: true, validationRule: "Exactly one of: APPROVED, APPROVED_WITH_CONCERNS, BLOCKED." }
     ],
@@ -1450,7 +1452,8 @@ const SHIP = {
         { section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
         { section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
         { section: "Finalization", required: true, validationRule: "Exactly one finalization enum token selected. Execution result documented. Worktree cleaned if applicable." },
-        { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." }
+        { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." },
+        { section: "Compound Step", required: false, validationRule: "Optional retrospective: at least one bullet of the form 'Insight: ... | Action: append [compound] entry to .cclaw/knowledge.md', or an explicit 'No compound insight this run.' line." }
     ],
     namedAntiPattern: {
         title: "Green CI Means Safe to Merge",
@@ -1512,6 +1515,13 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When acceptance criteria are unclear or constraints conflict.",
             purpose: "Normalize measurable criteria and testability mapping.",
             requiresUserGate: false
+        },
+        {
+            agent: "spec-reviewer",
+            mode: "proactive",
+            when: "When acceptance criteria and edge cases are drafted and need independent validation before plan stage.",
+            purpose: "Independent review of spec against measurability, testability, and completeness before locking the contract for plan.",
+            requiresUserGate: false
         }
     ],
     plan: [

package/dist/content/status-command.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Command contract for /cc-status — a read-only snapshot command.
+ * Does not mutate state. Always safe to run.
+ */
+export declare function statusCommandContract(): string;
+/**
+ * Skill body for /cc-status — read-only status snapshot.
+ */
+export declare function statusCommandSkillMarkdown(): string;

package/dist/content/status-command.js

@@ -0,0 +1,132 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const STATUS_SKILL_FOLDER = "flow-status";
+const STATUS_SKILL_NAME = "flow-status";
+function flowStatePath() {
+    return `${RUNTIME_ROOT}/state/flow-state.json`;
+}
+function delegationLogPath() {
+    return `${RUNTIME_ROOT}/state/delegation-log.json`;
+}
+function knowledgePath() {
+    return `${RUNTIME_ROOT}/knowledge.md`;
+}
+/**
+ * Command contract for /cc-status — a read-only snapshot command.
+ * Does not mutate state. Always safe to run.
+ */
+export function statusCommandContract() {
+    const flowPath = flowStatePath();
+    const delegationPath = delegationLogPath();
+    return `# /cc-status
+
+## Purpose
+
+**Read-only snapshot of the cclaw run.** Shows track, current stage, completed stages,
+gate coverage, mandatory delegations, and the top 3 knowledge highlights.
+
+This command **never mutates state**. Use it at session start to orient, or at any
+time to answer "where are we?" without advancing the flow.
+
+## HARD-GATE
+
+- **Do not** use \`/cc-status\` output to infer gate completion for decisions — cite
+  artifact evidence via \`/cc-next\` when advancing.
+- **Do not** mutate \`${flowPath}\` or delegation log from this command.
+
+## Algorithm
+
+1. Read **\`${flowPath}\`** — capture \`track\`, \`currentStage\`, \`completedStages\`,
+   \`skippedStages\`, and per-stage gate catalog.
+2. Read **\`${delegationPath}\`** — count delegated / completed / waived / pending entries
+   for the current stage's \`mandatoryDelegations\`.
+3. Read the top of **\`${knowledgePath}\`** — surface up to 3 most recent entries
+   (by trailing timestamp or source marker).
+4. Emit the status block described below. Do **not** load any stage skill.
+
+## Status Block Format
+
+\`\`\`
+cclaw status
+  track:            <quick|standard>
+  current stage:    <stage>     (<N>/<total> in track)
+  completed stages: <list or "none">
+  skipped stages:   <list or "none">
+
+  gates:
+    passed:   <count> of <required>
+    blocked:  <count>
+    unmet:    <list of gate ids>
+
+  delegations (current stage):
+    required:  <list>
+    completed: <list>
+    pending:   <list>
+
+  knowledge highlights:
+    - <latest entry summary line>
+    - <second entry summary line>
+    - <third entry summary line>
+
+  next action:
+    /cc-next  (advance or resume current stage)
+\`\`\`
+
+## Anti-patterns
+
+- Inventing gate status without reading \`${flowPath}\`.
+- Reporting delegations as satisfied when the log says \`pending\`.
+- Advancing the stage from \`/cc-status\` — progression belongs to \`/cc-next\`.
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${STATUS_SKILL_FOLDER}/SKILL.md**
+`;
+}
+/**
+ * Skill body for /cc-status — read-only status snapshot.
+ */
+export function statusCommandSkillMarkdown() {
+    const flowPath = flowStatePath();
+    const delegationPath = delegationLogPath();
+    return `---
+name: ${STATUS_SKILL_NAME}
+description: "Read-only snapshot of the cclaw flow: track, stage, gate coverage, delegations, knowledge highlights. Never mutates state."
+---
+
+# /cc-status — Flow Status Snapshot
+
+## Overview
+
+\`/cc-status\` is the quickest way to answer "where are we in the flow?" without
+advancing or mutating anything. Safe to run at any point.
+
+## HARD-GATE
+
+Do **not** mutate \`${flowPath}\` or \`${delegationPath}\` from this skill. This is
+a read-only command.
+
+## Algorithm
+
+1. Read \`${flowPath}\`. If missing → report **BLOCKED: flow state absent** and suggest \`cclaw init\`.
+2. Read \`${delegationPath}\`. Missing → treat all mandatory delegations as pending.
+3. Read \`${RUNTIME_ROOT}/knowledge.md\`. If missing or empty → knowledge highlights are \`(none recorded)\`.
+4. For each gate in \`stageGateCatalog[currentStage].required\`:
+   - Satisfied if present in \`passed\` and absent from \`blocked\`.
+5. Build and print the status block (see command contract for layout).
+6. Suggest the next action:
+   - If current stage has unmet gates → \`/cc-next\` to resume.
+   - If current stage is complete → \`/cc-next\` to advance (or report "Flow complete" if terminal).
+
+## Output Guidelines
+
+- Keep output compact (≤ 25 lines) — status, not narrative.
+- Report counts, not full artifact contents.
+- If any data source is missing or corrupt, say so explicitly rather than guessing.
+
+## Anti-patterns
+
+- Rebuilding trace-matrix or running doctor from \`/cc-status\` — those belong to dedicated tools.
+- Treating absence of delegation log as "all delegations complete".
+- Mutating state to "clean up" during a status check.
+`;
+}

package/dist/content/templates.js

@@ -349,8 +349,16 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Layer 2 complete:
 - Review army schema valid:
 - Open critical blockers:
+- Adversarial review pass:
 - Ship recommendation:
 
+## Completeness Score
+- AC coverage: <N>/<M> (<percent>%)
+- Task coverage (tasks backed by ≥1 test slice): <N>/<M>
+- Slice coverage (slices linked to ≥1 AC): <N>/<M>
+- Adversarial review pass: true | false
+- Overall score: <0-100>
+
 ## Severity Summary
 - Critical:
 - Important:
@@ -361,28 +369,13 @@ Execution rule: complete and verify each wave before starting the next wave.
 `,
     "07-review-army.json": `{
   "version": 1,
-  "generatedAt": "",
+  "generatedAt": "<ISO 8601 timestamp, e.g. 2026-04-14T12:00:00Z>",
   "scope": {
-    "base": "",
-    "head": "",
+    "base": "<base branch or ref>",
+    "head": "<head branch or ref>",
     "files": []
   },
-  "findings": [
-    {
-      "id": "",
-      "title": "",
-      "severity": "Critical",
-      "confidence": 7,
-      "category": "correctness",
-      "location": {
-        "file": ""
-      },
-      "fingerprint": "",
-      "reportedBy": [],
-      "status": "open",
-      "recommendation": ""
-    }
-  ],
+  "findings": [],
   "reconciliation": {
     "duplicatesCollapsed": 0,
     "conflicts": [],
@@ -426,6 +419,12 @@ Execution rule: complete and verify each wave before starting the next wave.
 ## Completion Status
 - SHIPPED | SHIPPED_WITH_EXCEPTIONS | BLOCKED
 - Exceptions (if any):
+
+## Compound Step
+_Optional retrospective. The goal is to make the **next** feature faster, not to evaluate this one._
+_If you have nothing to add, write the explicit line: \`No compound insight this run.\`_
+- Insight: <one short line about what should accelerate the next run>
+- Action: append \`[compound]\` entry to \`.cclaw/knowledge.md\` capturing the insight
 `
 };
 export const RULEBOOK_MARKDOWN = `# Cclaw Rulebook

package/dist/content/utility-skills.d.ts

@@ -1,5 +1,5 @@
 /**
- * Utility skills that complement the 9 flow stages.
+ * Utility skills that complement the 8 flow stages.
  * These are contextual lenses, not flow stages.
  * Each skill: ~120-180 lines, under the 500-line progressive disclosure guideline.
  */
@@ -12,5 +12,9 @@ export declare function executingPlansSkill(): string;
 export declare function contextEngineeringSkill(): string;
 export declare function sourceDrivenDevelopmentSkill(): string;
 export declare function frontendAccessibilitySkill(): string;
-export declare const UTILITY_SKILL_FOLDERS: readonly ["security", "debugging", "performance", "ci-cd", "docs", "executing-plans", "context-engineering", "source-driven-development", "frontend-accessibility"];
+export declare function landscapeCheckSkill(): string;
+export declare function knowledgeCurationSkill(): string;
+export declare function securityAuditSkill(): string;
+export declare function adversarialReviewSkill(): string;
+export declare const UTILITY_SKILL_FOLDERS: readonly ["security", "debugging", "performance", "ci-cd", "docs", "executing-plans", "context-engineering", "source-driven-development", "frontend-accessibility", "landscape-check", "adversarial-review", "security-audit", "knowledge-curation"];
 export declare const UTILITY_SKILL_MAP: Record<string, () => string>;