cclaw-cli 0.11.0 → 0.13.0

package/dist/content/research-playbooks.js

@@ -0,0 +1,135 @@
+/**
+ * In-thread research playbooks.
+ *
+ * These files intentionally have no YAML frontmatter and are not standalone
+ * delegated personas. The primary agent loads and executes them directly.
+ */
+export const RESEARCH_PLAYBOOKS = {
+    "repo-scan.md": `# Repo Scan Playbook
+
+## Purpose
+
+Build a grounded map of existing modules and reuse candidates before design lock.
+
+## Steps
+
+1. Identify 3-8 task keywords (feature nouns + action verbs).
+2. Search for likely modules with \`rg\` and \`Glob\` patterns.
+3. List existing implementations or close analogs with file citations.
+4. Flag duplication risk and obvious extension points.
+
+## Output Contract
+
+- Relevant modules: \`path - purpose\`
+- Reuse candidates: \`file:line - why reusable\`
+- Gaps: capabilities not currently present
+
+## Guardrails
+
+- Read-only procedure.
+- Never invent paths or ownership.
+- If scope is too broad, return bounded partial coverage explicitly.
+`,
+    "learnings-lookup.md": `# Learnings Lookup Playbook
+
+## Purpose
+
+Reuse prior project knowledge before choosing a direction.
+
+## Steps
+
+1. Read \`.cclaw/knowledge.jsonl\`.
+2. Match by stage/domain keywords from the current task.
+3. Rank matches by confidence and recency.
+4. Return the top entries verbatim.
+
+## Output Contract
+
+- Matched rules
+- Matched patterns
+- Matched lessons
+- Matched compounds
+- Explicit no-match note when empty
+
+## Guardrails
+
+- Append-only store: do not rewrite history entries.
+- Prefer exact quote over paraphrase.
+`,
+    "framework-docs-lookup.md": `# Framework Docs Lookup Playbook
+
+## Purpose
+
+Anchor design decisions to version-accurate framework/library docs.
+
+## Steps
+
+1. Resolve the actual dependency version from lockfiles/manifests.
+2. Fetch official docs for that version (context7 when available).
+3. Extract APIs used by the task and any migration or deprecation notes.
+
+## Output Contract
+
+- Library + version
+- APIs/signatures touched
+- Relevant breaking changes or gotchas
+- Source links/references
+
+## Guardrails
+
+- No speculative APIs.
+- If docs conflict or are unclear, mark UNKNOWN and escalate.
+`,
+    "best-practices-lookup.md": `# Best Practices Lookup Playbook
+
+## Purpose
+
+Summarize citable domain practices for a narrow design decision.
+
+## Steps
+
+1. Narrow the domain to one concrete sub-problem.
+2. Gather 3-5 authoritative sources.
+3. Produce short practice and anti-pattern lists tied to sources.
+
+## Output Contract
+
+- Recommended practices (\`practice - rationale - source\`)
+- Common traps (\`trap - why it fails - source\`)
+- Decision hooks (1-3 questions to resolve before proceeding)
+
+## Guardrails
+
+- Cite authoritative sources (official docs/standards).
+- State uncertainty explicitly when consensus is weak.
+`,
+    "git-history.md": `# Git History Playbook
+
+## Purpose
+
+Detect churn, regressions, and ownership signals before locking scope/design.
+
+## Steps
+
+1. For impacted paths, inspect recent history and themes:
+   - \`git log --follow -n 20 -- <path>\`
+2. Check ownership hotspots:
+   - \`git blame <path>\`
+   - \`git log --since="<window>" --format="%an" -- <path>\`
+3. Search for regression signals:
+   - \`git log --since="<window>" --grep="revert|regression" -- <path>\`
+
+## Output Contract
+
+- Recent themes
+- Revert/regression signals (with SHAs)
+- Ownership hints
+- Collision risks with ongoing refactors
+
+## Guardrails
+
+- Read-only git usage.
+- If there is no history, say so explicitly.
+`
+};
+export const RESEARCH_PLAYBOOK_FILES = Object.keys(RESEARCH_PLAYBOOKS).sort();

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

@@ -0,0 +1,2 @@
+export declare function retroCommandContract(): string;
+export declare function retroCommandSkillMarkdown(): string;

package/dist/content/retro-command.js

@@ -0,0 +1,77 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const RETRO_SKILL_FOLDER = "flow-retro";
+const RETRO_SKILL_NAME = "flow-retro";
+function flowStatePath() {
+    return `${RUNTIME_ROOT}/state/flow-state.json`;
+}
+function retroArtifactPath() {
+    return `${RUNTIME_ROOT}/artifacts/09-retro.md`;
+}
+function knowledgePath() {
+    return `${RUNTIME_ROOT}/knowledge.jsonl`;
+}
+export function retroCommandContract() {
+    return `# /cc-retro
+
+## Purpose
+
+Mandatory retrospective gate before archive once ship is complete.
+
+## HARD-GATE
+
+- Do not mark retro complete without writing \`${retroArtifactPath()}\`.
+- Do not finish retro without appending at least one \`type=compound\` entry into \`${knowledgePath()}\`.
+
+## Algorithm
+
+1. Read \`${flowStatePath()}\`; confirm ship stage is complete for current run.
+2. Synthesize retrospective artifact \`${retroArtifactPath()}\` with:
+   - what slowed this run
+   - what accelerated this run
+   - concrete repeatable rule for next run
+3. Append >=1 strict-schema JSONL entry to \`${knowledgePath()}\` with:
+   - \`type: "compound"\`
+   - \`stage: "ship"\` or \`"retro"\`
+4. Update flow-state \`retro\` block:
+   - \`required: true\`
+   - \`completedAt: <ISO>\`
+   - \`compoundEntries: <count>\`
+5. Report completion summary and remind user that \`cclaw archive\` is now unblocked.
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${RETRO_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function retroCommandSkillMarkdown() {
+    return `---
+name: ${RETRO_SKILL_NAME}
+description: "Run mandatory retrospective and record compound knowledge before archive."
+---
+
+# /cc-retro
+
+## HARD-GATE
+
+Archive must remain blocked until retro artifact exists and compound knowledge was appended.
+
+## Protocol
+
+1. Confirm ship completion from \`${flowStatePath()}\`.
+2. Create/update \`${retroArtifactPath()}\` with concise retrospective sections:
+   - outcomes
+   - bottlenecks
+   - reusable acceleration patterns
+3. Append at least one \`compound\` knowledge entry into \`${knowledgePath()}\`.
+4. Update \`flow-state.json.retro\` with completion timestamp + compound count.
+5. Print explicit completion line:
+   - \`retro gate: complete\`
+   - \`compound entries added: <N>\`
+
+## Validation
+
+- \`${retroArtifactPath()}\` exists and is non-empty.
+- \`${knowledgePath()}\` contains >=1 valid \`compound\` line.
+- \`retro.completedAt\` is set in flow-state.
+`;
+}

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

@@ -0,0 +1,3 @@
+export declare function rewindCommandContract(): string;
+export declare function rewindAcknowledgeCommandContract(): string;
+export declare function rewindCommandSkillMarkdown(): string;

package/dist/content/rewind-command.js

@@ -0,0 +1,120 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const REWIND_SKILL_FOLDER = "flow-rewind";
+const REWIND_SKILL_NAME = "flow-rewind";
+function flowStatePath() {
+    return `${RUNTIME_ROOT}/state/flow-state.json`;
+}
+function artifactsPath() {
+    return `${RUNTIME_ROOT}/artifacts`;
+}
+function rewindLogPath() {
+    return `${RUNTIME_ROOT}/state/rewind-log.jsonl`;
+}
+export function rewindCommandContract() {
+    return `# /cc-rewind
+
+## Purpose
+
+Rewind active flow to an earlier stage and atomically invalidate downstream work.
+
+## HARD-GATE
+
+- Never rewind without preserving downstream artifact history.
+- Mark downstream stages as stale; do not leave completedStages pointing to invalidated work.
+- Record a rewind reason in \`${rewindLogPath()}\`.
+
+## Inputs
+
+\`/cc-rewind <target-stage> [reason]\`
+
+## Algorithm
+
+1. Read \`${flowStatePath()}\` and current track.
+2. Validate \`target-stage\` belongs to the active track and is not ahead of current stage.
+3. Compute downstream stages to invalidate (all stages after target that were completed or current).
+4. Archive downstream artifacts into \`${artifactsPath()}/_rewind-archive/<rewind-id>/\`.
+5. Rename active downstream artifacts to \`*.stale.md\`.
+6. Update flow-state:
+   - \`currentStage = target-stage\`
+   - trim \`completedStages\` to stages before target-stage
+   - clear gate evidence/catalog for target-stage and downstream
+   - mark downstream entries in \`staleStages\`
+   - append \`rewinds[]\` record
+7. Append JSON line to \`${rewindLogPath()}\`.
+
+## Output
+
+- Rewind id
+- from -> to stage
+- Invalidated stages list
+- Number of stale artifacts
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${REWIND_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function rewindAcknowledgeCommandContract() {
+    return `# /cc-rewind-ack
+
+## Purpose
+
+Acknowledge and clear stale-stage markers after downstream work is intentionally redone.
+
+## Input
+
+\`/cc-rewind-ack <stage>\`
+
+## HARD-GATE
+
+- Only clear stale marker for the requested stage.
+- Never modify completedStages from this command.
+
+## Algorithm
+
+1. Read \`${flowStatePath()}\`.
+2. If \`staleStages.<stage>\` is missing, report no-op.
+3. Remove \`staleStages.<stage>\`.
+4. Write updated flow-state.
+5. Print remaining stale stages (if any).
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${REWIND_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function rewindCommandSkillMarkdown() {
+    return `---
+name: ${REWIND_SKILL_NAME}
+description: "Rewind active flow stage safely and acknowledge stale invalidations."
+---
+
+# /cc-rewind + /cc-rewind-ack
+
+## HARD-GATE
+
+Rewind is an atomic state transition. Never leave flow-state half-updated (for example currentStage changed but stale markers/artifact archive missing).
+
+## Protocol
+
+### rewind
+1. Validate target stage belongs to current track and is upstream.
+2. Archive downstream artifacts under \`${artifactsPath()}/_rewind-archive/<rewind-id>/\`.
+3. Mark downstream artifacts as stale (\`*.stale.md\`).
+4. Reset downstream gate catalog and guard evidence.
+5. Record \`rewinds[]\` and \`staleStages\` in flow-state.
+6. Append rewind entry into \`${rewindLogPath()}\`.
+
+### rewind-ack
+1. Load flow-state stale map.
+2. Remove exactly one stale stage marker.
+3. Report remaining stale stages.
+
+## Validation checklist
+
+- \`${flowStatePath()}\` remains valid JSON.
+- \`currentStage\` equals requested rewind target.
+- invalidated stages are absent from \`completedStages\`.
+- archived copies exist for each moved artifact.
+`;
+}

package/dist/content/skills.js

@@ -54,6 +54,22 @@ Mandatory delegations for this stage: ${mandatoryList}.
 Record completion/waiver in \`${delegationLogRel}\` before stage completion.
 `;
 }
+function researchPlaybooksBlock(stage) {
+    const playbooks = stageSchema(stage).researchPlaybooks ?? [];
+    if (playbooks.length === 0)
+        return "";
+    const rows = playbooks
+        .map((playbook) => `- \`${RUNTIME_ROOT}/skills/${playbook}\``)
+        .join("\n");
+    return `## Research Playbooks
+
+Use these in-thread research procedures before locking this stage. They are
+playbooks (not delegated personas), so execute them in the primary agent context
+and record outcomes in the stage artifact when relevant.
+
+${rows}
+`;
+}
 function reviewSectionsBlock(stage) {
     const schema = stageSchema(stage);
     if (schema.reviewSections.length === 0)
@@ -92,6 +108,9 @@ function waveExecutionModeBlock(stage) {
 
 Execute the current dependency wave task-by-task (RED -> GREEN -> REFACTOR).
 Stop on BLOCKED status or when user input is required.
+Apply preamble budget discipline: one preamble per wave, then continue without
+repeating it for each task. Re-emit only when the wave boundary changes or the
+plan changes materially.
 
 Detailed walkthrough:
 \`.cclaw/${STAGE_EXAMPLES_REFERENCE_DIR}/tdd-wave-walkthrough.md\`
@@ -313,6 +332,7 @@ ${schema.requiredContext.length > 0 ? schema.requiredContext.map((item) => `- ${
 
 ${contextLoadingBlock(stage)}
 ${autoSubagentDispatchBlock(stage)}
+${researchPlaybooksBlock(stage)}
 
 ## Outputs
 ${schema.outputs.map((item) => `- ${item}`).join("\n")}

package/dist/content/stage-schema.d.ts

@@ -33,7 +33,7 @@ export interface ArtifactValidation {
     validationRule: string;
 }
 export interface StageAutoSubagentDispatch {
-    agent: "planner" | "spec-reviewer" | "code-reviewer" | "security-reviewer" | "test-author" | "doc-updater" | "repo-research-analyst" | "learnings-researcher" | "framework-docs-researcher" | "best-practices-researcher" | "git-history-analyzer";
+    agent: "planner" | "reviewer" | "security-reviewer" | "test-author" | "doc-updater";
     /**
      * - `mandatory` — must be dispatched (or explicitly waived) before stage transition.
      * - `proactive` — should be dispatched automatically when context matches `when`.
@@ -81,6 +81,8 @@ export interface StageSchema {
     requiredEvidence: string[];
     inputs: string[];
     requiredContext: string[];
+    /** In-thread research procedures for this stage (`.cclaw/skills/research/*.md`). */
+    researchPlaybooks?: string[];
     outputs: string[];
     blockers: string[];
     exitCriteria: string[];

package/dist/content/stage-schema.js

@@ -190,6 +190,10 @@ const BRAINSTORM = {
         "current behavior of affected area",
         "business and delivery constraints"
     ],
+    researchPlaybooks: [
+        "research/repo-scan.md",
+        "research/learnings-lookup.md"
+    ],
     outputs: [
         "approved design direction",
         "alternatives with trade-offs",
@@ -339,6 +343,9 @@ const SCOPE = {
         "existing capabilities and reusable components",
         "delivery deadlines and risk tolerance"
     ],
+    researchPlaybooks: [
+        "research/git-history.md"
+    ],
     outputs: ["scope mode decision", "scope contract", "discretion areas list", "deferred scope list", "scope summary", "scope completion dashboard"],
     blockers: [
         "scope mode not selected",
@@ -553,6 +560,10 @@ const DESIGN = {
         "operational constraints",
         "security and reliability expectations"
     ],
+    researchPlaybooks: [
+        "research/framework-docs-lookup.md",
+        "research/best-practices-lookup.md"
+    ],
     outputs: [
         "architecture lock",
         "risk and failure map",
@@ -1266,7 +1277,7 @@ const REVIEW = {
     checklist: [
         "Diff Scope — Run `git diff` against base branch. If no diff, exit early with APPROVED (no changes to review). Scope the review to changed files unless blast-radius analysis requires wider inspection.",
         "Change-Size Check — ~100 lines = normal. ~300 lines = consider splitting. ~1000+ lines = strongly recommend stacked PRs. Flag large diffs to the user.",
-        "Adversarial Trigger Check — compute changed-line count (`git diff --shortstat <base>..HEAD`), files-touched count, and whether trust boundaries changed (auth/secrets/external inputs/permissions). If `lines > 100` OR `files > 10` OR `trust boundary changed`, **dispatch a SECOND code-reviewer agent with the `adversarial-review` skill loaded** and reconcile its findings into the review army (treat the conditional dispatch as mandatory whenever the trigger holds; record the trigger that fired in the dashboard).",
+        "Adversarial Trigger Check — compute changed-line count (`git diff --shortstat <base>..HEAD`), files-touched count, and whether trust boundaries changed (auth/secrets/external inputs/permissions). If `lines > 100` OR `files > 10` OR `trust boundary changed`, **dispatch a SECOND reviewer agent with the `adversarial-review` skill loaded** and reconcile its findings into the review army (treat the conditional dispatch as mandatory whenever the trigger holds; record the trigger that fired in the dashboard).",
         "Load upstream evidence — read TDD artifact (RED + GREEN + REFACTOR), spec, and plan. Verify evidence chain is unbroken.",
         "Layer 1: Spec Compliance — check every acceptance criterion against implementation. Verdict: pass/fail per criterion.",
         "Layer 2a: Correctness — logic errors, race conditions, boundary violations, null handling.",
@@ -1642,20 +1653,6 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When request is ambiguous, multi-surface, or spans multiple modules.",
             purpose: "Map scope and alternatives before direction lock.",
             requiresUserGate: false
-        },
-        {
-            agent: "repo-research-analyst",
-            mode: "proactive",
-            when: "When the user's idea touches an unfamiliar module, stack, or integration surface.",
-            purpose: "Parallel fan-out: summarise existing code paths, tech stack, and similar features already present — feeds the alternatives list.",
-            requiresUserGate: false
-        },
-        {
-            agent: "learnings-researcher",
-            mode: "proactive",
-            when: "On every non-trivial brainstorm where `.cclaw/knowledge.jsonl` has entries.",
-            purpose: "Surface prior learnings and anti-patterns that apply to the current task before direction lock.",
-            requiresUserGate: false
         }
     ],
     scope: [
@@ -1665,13 +1662,6 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "Always during scope shaping.",
             purpose: "Challenge premise, map alternatives, and produce explicit in/out contract.",
             requiresUserGate: false
-        },
-        {
-            agent: "git-history-analyzer",
-            mode: "proactive",
-            when: "When scope touches modules with churn, recent regressions, or unclear ownership.",
-            purpose: "Read recent commits, PRs, and issue references for the affected paths before scope lock.",
-            requiresUserGate: false
         }
     ],
     design: [
@@ -1688,20 +1678,6 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When trust boundaries, auth, secrets, or external inputs are involved.",
             purpose: "Catch design-level security risks before implementation.",
             requiresUserGate: false
-        },
-        {
-            agent: "framework-docs-researcher",
-            mode: "proactive",
-            when: "When a specific framework/library version is detected and a non-trivial API is in play.",
-            purpose: "Retrieve version-specific docs + migration notes so the design does not rely on stale training priors.",
-            requiresUserGate: false
-        },
-        {
-            agent: "best-practices-researcher",
-            mode: "conditional",
-            when: "When the user flags a quality axis (performance, accessibility, reliability) as primary.",
-            purpose: "Pull domain best-practices and contrast them with the current design choice.",
-            requiresUserGate: false
         }
     ],
     spec: [
@@ -1713,7 +1689,7 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             requiresUserGate: false
         },
         {
-            agent: "spec-reviewer",
+            agent: "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.",
@@ -1747,17 +1723,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
     ],
     review: [
         {
-            agent: "spec-reviewer",
+            agent: "reviewer",
             mode: "mandatory",
             when: "Always in review stage.",
-            purpose: "Verify implementation against acceptance criteria with file evidence.",
-            requiresUserGate: false
-        },
-        {
-            agent: "code-reviewer",
-            mode: "mandatory",
-            when: "Always in review stage.",
-            purpose: "Assess correctness, maintainability, architecture, and ship risk.",
+            purpose: "Run spec compliance and code-quality passes with file evidence.",
             requiresUserGate: false
         },
         {
@@ -1769,10 +1738,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             skill: "security-audit"
         },
         {
-            agent: "code-reviewer",
+            agent: "reviewer",
             mode: "conditional",
             condition: "diff_lines_gt:100||files_touched_gt:10||trust_boundary_changed",
-            when: "When the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent code-reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
+            when: "When the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
             purpose: "Adversarial second-opinion review on large or trust-sensitive diffs. The second reviewer treats the implementation as hostile and tries to break it (hostile-user, future-maintainer, competitor lenses) instead of sympathetically explaining it.",
             requiresUserGate: false,
             skill: "adversarial-review"
@@ -1787,10 +1756,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             requiresUserGate: false
         },
         {
-            agent: "code-reviewer",
+            agent: "security-reviewer",
             mode: "proactive",
-            when: "When release involves broad blast radius or unresolved concerns.",
-            purpose: "Provide final integration-scale quality pass.",
+            when: "When release involves broad blast radius, trust-boundary movement, or unresolved security concerns.",
+            purpose: "Provide final exploitability check before release finalization.",
             requiresUserGate: false
         }
     ]