cclaw-cli 7.7.1 → 8.1.1

package/dist/constants.js

@@ -1,108 +1,21 @@
-import { readFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-/** Hidden runtime directory at project root (dot-prefixed). */
+export const CCLAW_VERSION = "8.1.1";
 export const RUNTIME_ROOT = ".cclaw";
-/**
- * Resolved once at module load from the cclaw-cli package.json. Walking a
- * short list of candidates keeps the helper working in both the compiled
- * `dist/` layout and the in-repo `src/` layout (tests, ts-node).
- */
-function readPackageVersion() {
-    try {
-        const here = path.dirname(fileURLToPath(import.meta.url));
-        const candidates = [
-            path.resolve(here, "../package.json"),
-            path.resolve(here, "../../package.json")
-        ];
-        for (const candidate of candidates) {
-            try {
-                const raw = readFileSync(candidate, "utf8");
-                const parsed = JSON.parse(raw);
-                if (parsed.name === "cclaw-cli" && typeof parsed.version === "string") {
-                    return parsed.version;
-                }
-            }
-            catch {
-                continue;
-            }
-        }
-    }
-    catch {
-        // Fall through to dev fallback.
-    }
-    return "0.0.0-dev";
-}
-export const CCLAW_VERSION = readPackageVersion();
-export const FLOW_VERSION = "1.0.0";
-/**
- * Canonical ship finalization enums used across stage schema, linting, and
- * runtime gate evidence checks.
- */
-export const SHIP_FINALIZATION_MODES = [
-    "FINALIZE_MERGE_LOCAL",
-    "FINALIZE_OPEN_PR",
-    "FINALIZE_KEEP_BRANCH",
-    "FINALIZE_DISCARD_BRANCH",
-    "FINALIZE_NO_VCS"
-];
-export const DEFAULT_HARNESSES = [
-    "claude",
-    "cursor",
-    "opencode",
-    "codex"
-];
-export const REQUIRED_DIRS = [
-    RUNTIME_ROOT,
-    `${RUNTIME_ROOT}/commands`,
-    `${RUNTIME_ROOT}/skills`,
-    `${RUNTIME_ROOT}/templates`,
-    `${RUNTIME_ROOT}/templates/state-contracts`,
-    `${RUNTIME_ROOT}/artifacts`,
-    `${RUNTIME_ROOT}/wave-plans`,
-    `${RUNTIME_ROOT}/archive`,
-    `${RUNTIME_ROOT}/worktrees`,
-    `${RUNTIME_ROOT}/state`,
-    `${RUNTIME_ROOT}/rules`,
-    `${RUNTIME_ROOT}/agents`,
-    `${RUNTIME_ROOT}/hooks`,
-    `${RUNTIME_ROOT}/skills/review-prompts`
-];
-export const REQUIRED_GITIGNORE_PATTERNS = [
-    "# cclaw generated artifacts",
-    `${RUNTIME_ROOT}/`,
-    ".claude/commands/cc-*.md",
-    ".claude/commands/cc.md",
-    ".cursor/commands/cc-*.md",
-    ".cursor/commands/cc.md",
-    ".opencode/commands/cc-*.md",
-    ".opencode/commands/cc.md",
-    // Codex uses skill-kind shims under `.agents/skills/cc*/` since
-    // Codex shim layout (renamed from the older `cclaw-cc*` layout).
-    // `cclaw sync` and `cclaw uninstall` both auto-remove the legacy
-    // `cclaw-cc*` directories.
-    ".agents/skills/cc/SKILL.md",
-    ".agents/skills/cc-*/SKILL.md",
-    ".claude/hooks/hooks.json",
-    ".cursor/hooks.json",
-    ".codex/hooks.json",
-    ".opencode/plugins/cclaw-plugin.mjs",
-    ".cursor/rules/cclaw-workflow.mdc"
-];
-/**
- * Canonical stage -> skill folder mapping.
- */
-export const STAGE_TO_SKILL_FOLDER = {
-    brainstorm: "brainstorm",
-    scope: "scope",
-    design: "design",
-    spec: "spec",
-    plan: "plan",
-    tdd: "tdd",
-    review: "review",
-    ship: "ship"
-};
-export const SUBAGENT_SKILL_FOLDERS = [
-    "subagent-dev",
-    "parallel-dispatch"
+export const STATE_REL_PATH = `${RUNTIME_ROOT}/state`;
+export const HOOKS_REL_PATH = `${RUNTIME_ROOT}/hooks`;
+export const FLOWS_ROOT = `${RUNTIME_ROOT}/flows`;
+export const LIB_ROOT = `${RUNTIME_ROOT}/lib`;
+export const FLOW_STATE_REL_PATH = `${STATE_REL_PATH}/flow-state.json`;
+export const KNOWLEDGE_LOG_REL_PATH = `${RUNTIME_ROOT}/knowledge.jsonl`;
+export const IDEAS_REL_PATH = `${RUNTIME_ROOT}/ideas.md`;
+export const SHIPPED_DIR_REL_PATH = `${FLOWS_ROOT}/shipped`;
+export const CANCELLED_DIR_REL_PATH = `${FLOWS_ROOT}/cancelled`;
+export const LIB_DIRS = [
+    "agents",
+    "skills",
+    "templates",
+    "runbooks",
+    "patterns",
+    "research",
+    "recovery",
+    "examples"
 ];

package/dist/content/antipatterns.d.ts

@@ -0,0 +1 @@
+export declare const ANTIPATTERNS = "# .cclaw/lib/antipatterns.md\n\nPatterns we have seen fail. Each entry is a short symptom, the underlying mistake, and the corrective action. The orchestrator and specialists open this file when a smell is detected; the reviewer cites entries as findings when applicable.\n\n## A-1 \u2014 \"Just one more AC\"\n\n**Symptom.** A plan starts with 4 AC and ends with 11. Most of the additions appeared during build.\n\n**Underlying mistake.** Scope is being expanded mid-flight without going back to plan-stage.\n\n**Correction.** When build encounters new work, surface it as a follow-up in `.cclaw/ideas.md` or a fresh slug. If the new work is genuinely required to satisfy an existing AC, that AC was wrong; cancel the slug and re-plan with a tighter AC set.\n\n## A-2 \u2014 TDD phase integrity broken\n\n**Symptom (any of):**\n\n- Build commits land for AC-N with `--phase=green` but no `--phase=red` recorded earlier.\n- AC has RED + GREEN commits but no `--phase=refactor` (skipped or applied) entry in flow-state.\n- A `--phase=red` commit touches `src/`, `lib/`, or `app/` \u2014 production code slipped into RED.\n- Tests for AC-N appear in a separate commit a few minutes after the AC-N implementation lands.\n\n**Underlying mistake.** The TDD cycle was treated as ceremony, not as the contract. The cycle exists so the failing test encodes the AC; skipping or scrambling phases produces an audit trail that nobody can trust.\n\n**Correction.** `commit-helper.mjs` enforces RED \u2192 GREEN \u2192 REFACTOR per AC. Write a failing test first and commit under `--phase=red` (test files only). Implement the smallest production change that turns it green; commit under `--phase=green`. Either commit a refactor under `--phase=refactor` or skip it explicitly with `--phase=refactor --skipped --message=\"refactor(AC-N) skipped: <reason>\"`. The reviewer cites this entry whenever the chain is incomplete.\n\n## A-3 \u2014 Work outside the AC\n\n**Symptom (any of):**\n\n- A small AC commit also restructures an unrelated module.\n- A commit produced by `commit-helper.mjs` contains files that are unrelated to the AC.\n- `git add -A` appears in shell history inside `/cc`.\n\n**Underlying mistake.** Slice-builder absorbed unrelated edits or silently expanded scope. The AC commit no longer maps cleanly to the AC.\n\n**Correction.** Stage AC-related files explicitly: `git add <path>` per file, or `git add -p` to pick hunks. Never `git add -A` inside `/cc`. If a refactor really must happen, capture it as a follow-up; if it really blocks the AC, cancel the slug and re-plan as a refactor + behaviour-change pair.\n\n## A-4 \u2014 AC that mirror sub-tasks\n\n**Symptom.** AC read like \"implement the helper\", \"wire the helper\", \"test the helper\".\n\n**Underlying mistake.** AC are outcomes, not sub-tasks. Outcomes survive refactors; sub-tasks do not.\n\n**Correction.** Rewrite AC as observable outcomes. The helper is an implementation detail, not an AC.\n\n## A-5 \u2014 Over-careful brainstormer\n\n**Symptom.** Brainstormer produces three pages of Context for a small task; planner is then unable to size the work.\n\n**Underlying mistake.** Brainstormer ignored the routing class. Trivial / small-medium tasks should have a one-paragraph Context, not a Frame + Scope + Alternatives sweep.\n\n**Correction.** Brainstormer reads the routing class first and short-circuits when the task is small. Three sentences of Context is enough for AC-1.\n\n## A-6 \u2014 \"I already looked\"\n\n**Symptom.** Reviewer reports a \"clear\" decision without a Five Failure Modes pass.\n\n**Underlying mistake.** The Five Failure Modes pass is the artifact. Skipping it because \"I already looked\" produces no audit trail.\n\n**Correction.** Reviewer always emits the Five Failure Modes block. Each item gets yes / no with citation when yes. A \"no\" with no thinking attached is fine; an absent block is not.\n\n## A-7 \u2014 Shipping with a pending AC\n\n**Symptom.** `runCompoundAndShip()` is invoked while flow-state has at least one AC with `status: pending`.\n\n**Underlying mistake.** The agent expected the orchestrator to \"figure it out\" and complete the AC silently.\n\n**Correction.** The AC traceability gate refuses ship. Either complete the AC (slice-builder) or cancel the slug (`/cc-cancel`) and re-plan with the smaller AC set. There is no override.\n\n## A-8 \u2014 Re-creating a shipped slug instead of refining\n\n**Symptom.** A new `/cc` invocation produces a slug whose plan is 80% identical to a slug already in `.cclaw/flows/shipped/`.\n\n**Underlying mistake.** Existing-plan detection was skipped or its output was ignored.\n\n**Correction.** Existing-plan detection is mandatory at the start of every `/cc`. When a shipped match is offered, the user picks **refine shipped** or **new unrelated**, not \"ignore the match\".\n\n## A-9 \u2014 Editing shipped artifacts\n\n**Symptom.** A shipped slug's `plan.md` is edited weeks after ship.\n\n**Underlying mistake.** Shipped artifacts are immutable. Editing them invalidates the knowledge index and breaks refinement chains.\n\n**Correction.** Open a refinement slug. The new slug carries `refines: <old-slug>` and contains the corrections. The old slug stays as it shipped.\n\n## A-10 \u2014 Force-push during ship\n\n**Symptom.** `git push --force` appears in shell history during ship.\n\n**Underlying mistake.** Force-push rewrites the SHAs that flow-state and the AC traceability block reference. The chain breaks silently; nothing in the runtime detects it.\n\n**Correction.** Refuse `git push --force` inside `/cc` unless the user explicitly requested it twice (initial request + confirmation). After the force-push, every recorded SHA in the slug must be re-verified by hand and updated.\n\n## A-11 \u2014 Hidden security surface\n\n**Symptom.** A slug ships without `security_flag: true` even though the diff added a new auth-adjacent code path.\n\n**Underlying mistake.** The author judged \"this is mostly UI\" and skipped the security checklist.\n\n**Correction.** `security_flag` is set whenever the diff touches authn / authz / secrets / supply chain / data exposure, even when the change feels small. The cost of a spurious security flag is a few minutes; the cost of a missed one is a CVE.\n\n## A-12 \u2014 Single test green, didn't run the suite\n\n**Symptom.** `flows/<slug>/build.md` GREEN evidence column shows `npm test path/to/single.test` only; full-suite run is missing.\n\n**Underlying mistake.** A passing single test is not GREEN. Production change can break adjacent tests; without running the suite, the AC is shipped on a regression.\n\n**Correction.** GREEN evidence must be the **full relevant suite** for the affected module(s), not the single test. The reviewer cites this as a block finding.\n";

package/dist/content/antipatterns.js

@@ -0,0 +1,109 @@
+export const ANTIPATTERNS = `# .cclaw/lib/antipatterns.md
+
+Patterns we have seen fail. Each entry is a short symptom, the underlying mistake, and the corrective action. The orchestrator and specialists open this file when a smell is detected; the reviewer cites entries as findings when applicable.
+
+## A-1 — "Just one more AC"
+
+**Symptom.** A plan starts with 4 AC and ends with 11. Most of the additions appeared during build.
+
+**Underlying mistake.** Scope is being expanded mid-flight without going back to plan-stage.
+
+**Correction.** When build encounters new work, surface it as a follow-up in \`.cclaw/ideas.md\` or a fresh slug. If the new work is genuinely required to satisfy an existing AC, that AC was wrong; cancel the slug and re-plan with a tighter AC set.
+
+## A-2 — TDD phase integrity broken
+
+**Symptom (any of):**
+
+- Build commits land for AC-N with \`--phase=green\` but no \`--phase=red\` recorded earlier.
+- AC has RED + GREEN commits but no \`--phase=refactor\` (skipped or applied) entry in flow-state.
+- A \`--phase=red\` commit touches \`src/\`, \`lib/\`, or \`app/\` — production code slipped into RED.
+- Tests for AC-N appear in a separate commit a few minutes after the AC-N implementation lands.
+
+**Underlying mistake.** The TDD cycle was treated as ceremony, not as the contract. The cycle exists so the failing test encodes the AC; skipping or scrambling phases produces an audit trail that nobody can trust.
+
+**Correction.** \`commit-helper.mjs\` enforces RED → GREEN → REFACTOR per AC. Write a failing test first and commit under \`--phase=red\` (test files only). Implement the smallest production change that turns it green; commit under \`--phase=green\`. Either commit a refactor under \`--phase=refactor\` or skip it explicitly with \`--phase=refactor --skipped --message="refactor(AC-N) skipped: <reason>"\`. The reviewer cites this entry whenever the chain is incomplete.
+
+## A-3 — Work outside the AC
+
+**Symptom (any of):**
+
+- A small AC commit also restructures an unrelated module.
+- A commit produced by \`commit-helper.mjs\` contains files that are unrelated to the AC.
+- \`git add -A\` appears in shell history inside \`/cc\`.
+
+**Underlying mistake.** Slice-builder absorbed unrelated edits or silently expanded scope. The AC commit no longer maps cleanly to the AC.
+
+**Correction.** Stage AC-related files explicitly: \`git add <path>\` per file, or \`git add -p\` to pick hunks. Never \`git add -A\` inside \`/cc\`. If a refactor really must happen, capture it as a follow-up; if it really blocks the AC, cancel the slug and re-plan as a refactor + behaviour-change pair.
+
+## A-4 — AC that mirror sub-tasks
+
+**Symptom.** AC read like "implement the helper", "wire the helper", "test the helper".
+
+**Underlying mistake.** AC are outcomes, not sub-tasks. Outcomes survive refactors; sub-tasks do not.
+
+**Correction.** Rewrite AC as observable outcomes. The helper is an implementation detail, not an AC.
+
+## A-5 — Over-careful brainstormer
+
+**Symptom.** Brainstormer produces three pages of Context for a small task; planner is then unable to size the work.
+
+**Underlying mistake.** Brainstormer ignored the routing class. Trivial / small-medium tasks should have a one-paragraph Context, not a Frame + Scope + Alternatives sweep.
+
+**Correction.** Brainstormer reads the routing class first and short-circuits when the task is small. Three sentences of Context is enough for AC-1.
+
+## A-6 — "I already looked"
+
+**Symptom.** Reviewer reports a "clear" decision without a Five Failure Modes pass.
+
+**Underlying mistake.** The Five Failure Modes pass is the artifact. Skipping it because "I already looked" produces no audit trail.
+
+**Correction.** Reviewer always emits the Five Failure Modes block. Each item gets yes / no with citation when yes. A "no" with no thinking attached is fine; an absent block is not.
+
+## A-7 — Shipping with a pending AC
+
+**Symptom.** \`runCompoundAndShip()\` is invoked while flow-state has at least one AC with \`status: pending\`.
+
+**Underlying mistake.** The agent expected the orchestrator to "figure it out" and complete the AC silently.
+
+**Correction.** The AC traceability gate refuses ship. Either complete the AC (slice-builder) or cancel the slug (\`/cc-cancel\`) and re-plan with the smaller AC set. There is no override.
+
+## A-8 — Re-creating a shipped slug instead of refining
+
+**Symptom.** A new \`/cc\` invocation produces a slug whose plan is 80% identical to a slug already in \`.cclaw/flows/shipped/\`.
+
+**Underlying mistake.** Existing-plan detection was skipped or its output was ignored.
+
+**Correction.** Existing-plan detection is mandatory at the start of every \`/cc\`. When a shipped match is offered, the user picks **refine shipped** or **new unrelated**, not "ignore the match".
+
+## A-9 — Editing shipped artifacts
+
+**Symptom.** A shipped slug's \`plan.md\` is edited weeks after ship.
+
+**Underlying mistake.** Shipped artifacts are immutable. Editing them invalidates the knowledge index and breaks refinement chains.
+
+**Correction.** Open a refinement slug. The new slug carries \`refines: <old-slug>\` and contains the corrections. The old slug stays as it shipped.
+
+## A-10 — Force-push during ship
+
+**Symptom.** \`git push --force\` appears in shell history during ship.
+
+**Underlying mistake.** Force-push rewrites the SHAs that flow-state and the AC traceability block reference. The chain breaks silently; nothing in the runtime detects it.
+
+**Correction.** Refuse \`git push --force\` inside \`/cc\` unless the user explicitly requested it twice (initial request + confirmation). After the force-push, every recorded SHA in the slug must be re-verified by hand and updated.
+
+## A-11 — Hidden security surface
+
+**Symptom.** A slug ships without \`security_flag: true\` even though the diff added a new auth-adjacent code path.
+
+**Underlying mistake.** The author judged "this is mostly UI" and skipped the security checklist.
+
+**Correction.** \`security_flag\` is set whenever the diff touches authn / authz / secrets / supply chain / data exposure, even when the change feels small. The cost of a spurious security flag is a few minutes; the cost of a missed one is a CVE.
+
+## A-12 — Single test green, didn't run the suite
+
+**Symptom.** \`flows/<slug>/build.md\` GREEN evidence column shows \`npm test path/to/single.test\` only; full-suite run is missing.
+
+**Underlying mistake.** A passing single test is not GREEN. Production change can break adjacent tests; without running the suite, the AC is shipped on a regression.
+
+**Correction.** GREEN evidence must be the **full relevant suite** for the affected module(s), not the single test. The reviewer cites this as a block finding.
+`;

package/dist/content/artifact-templates.d.ts

@@ -0,0 +1,10 @@
+export interface ArtifactTemplate {
+    id: "plan" | "build" | "review" | "ship" | "decisions" | "learnings" | "manifest" | "ideas";
+    fileName: string;
+    description: string;
+    body: string;
+}
+export declare const ARTIFACT_TEMPLATES: ArtifactTemplate[];
+export declare function templateBody(id: ArtifactTemplate["id"], replacements?: Record<string, string>): string;
+export declare function planTemplateForSlug(slug: string): string;
+export declare function manifestTemplate(slug: string, shipCommit: string, shippedAt: string): string;