cclaw-cli 8.1.1 → 8.2.0

package/README.md

@@ -1,35 +1,53 @@
 # cclaw
 
-**cclaw is a lightweight harness-first flow toolkit for coding agents.** It installs three slash commands, six on-demand specialists, twelve auto-trigger skills (including TDD cycle and conversation-language), ten artifact templates, four stage runbooks, eight reference patterns, five research playbooks, five recovery playbooks, thirteen worked examples, an antipatterns library, a decision protocol, a meta-skill, an interactive harness picker, and a tiny runtime — together a deep content layer wrapped around a runtime under 1 KLOC — so Claude Code, Cursor, OpenCode, or Codex can move from idea to shipped change with a clear plan, AC traceability, TDD per AC, and almost no ceremony.
+**cclaw is a lightweight harness-first flow toolkit for coding agents.** Three slash commands. Five hops (`Detect → Triage → Dispatch → Pause → Compound/Ship`). Four stages (`plan → build → review → ship`, where **build IS a TDD cycle**: RED → GREEN → REFACTOR). Six on-demand specialists, all running as isolated sub-agents. Three Acceptance-Criteria modes (`inline` / `soft` / `strict`) so trivial edits do not pay the price of risky migrations. A deep content layer of skills, templates, runbooks, patterns, examples, and recovery playbooks wrapped around a runtime under 1 KLOC — so Claude Code, Cursor, OpenCode, or Codex can move from idea to shipped change with a clear plan, the right amount of ceremony, and almost no orchestrator bloat.
 
 ```text
-        idea
-         │
-         ▼
-     /cc <task>
-         │
-   ┌─────┴─────────────────────────────────────┐
-   │ Phase 0 calibration:                      │
-   │ targeted change or multi-component?       │
-   └─────┬─────────────────┬───────────────────┘
-         │trivial          │small/medium       │large/risky
-         ▼                 ▼                   ▼
-    edit + commit     plan → build       brainstormer →
-    per AC            → review → ship    architect → planner
-                                         (each is optional)
-                              │
-                              ▼
-                     compound (auto, gated)
-                              │
-                              ▼
-                  active artifacts → shipped/<slug>/
+            idea
+             │
+             ▼
+         /cc <task>
+             │
+   ┌─────────┴──────────────────────────────────────────┐
+   │ Hop 1: Detect — fresh start? or resume active flow? │
+   └─────────┬──────────────────────────────────────────┘
+             │ fresh
+             ▼
+   ┌────────────────────────────────────────────────────┐
+   │ Hop 2: Triage — auto-classify task,                │
+   │ recommend path + acMode, user accepts or overrides │
+   └─────────┬──────────────────────────────────────────┘
+             │
+   trivial   │   small-medium       │   large-risky
+   acMode    │   acMode soft        │   acMode strict
+   inline    │                      │
+             ▼                      ▼                      ▼
+        edit + commit        plan → build → review → ship   brainstorm? → architect? → plan → build → review → ship
+        (no plan)            each stage in a fresh sub-agent  each stage in a fresh sub-agent, parallel-build allowed
+                                     │                      │
+                                     └─────────┬────────────┘
+                                               ▼
+                                  compound (auto, gated by quality)
+                                               │
+                                               ▼
+                                   active flows → shipped/<slug>/
 ```
 
-Three slash commands. Four stages (`plan → build → review → ship`, where **build IS a TDD cycle**: RED → GREEN → REFACTOR per AC). Six specialists. Eleven skills (including a TDD-cycle skill that's always-on while building). Ten templates. Four runbooks. Eight reference patterns. Five research playbooks. Five recovery playbooks. Thirteen worked examples. Two mandatory gates (AC traceability + TDD phase chain).
+Three slash commands (`/cc`, `/cc-cancel`, `/cc-idea`). Four stages (`plan → build → review → ship`). Six specialists, all on-demand, all running as sub-agents. Fifteen skills including the always-on `triage-gate`, `flow-resume`, `tdd-cycle`, `conversation-language`, and `anti-slop`. Ten templates including `plan-soft.md` and `build-soft.md` for the soft-mode path. Four runbooks. Eight reference patterns. Three research playbooks. Five recovery playbooks. Eight worked examples. Two mandatory gates in strict mode (AC traceability + TDD phase chain); soft mode keeps both as advisory; inline mode skips both.
+
+## What changed in 8.2
+
+8.2 is a non-breaking redesign of the `/cc` orchestrator on top of 8.1.
+
+- **Triage gate.** Every fresh flow runs the `triage-gate` skill, which classifies the task as `trivial` / `small-medium` / `large-risky` from six heuristics, recommends a path and an `acMode`, and asks the user to accept or override. The decision is persisted into `flow-state.json` so resumes never re-prompt.
+- **Graduated AC.** Acceptance Criteria are no longer one-size-fits-all. `inline` (trivial) skips them entirely. `soft` (small-medium) uses a bullet list of testable conditions with no AC IDs and an advisory commit-helper. `strict` (large-risky) is the 8.1 behaviour byte-for-byte: AC IDs, mandatory `commit-helper.mjs --ac-id=AC-N --phase=red|green|refactor`, per-AC TDD chain.
+- **Sub-agent dispatch.** `plan`, `build`, `review`, and `ship` each run in a fresh sub-agent invocation. The orchestrator hands a slim envelope (slug / stage / acMode / artifact paths) and gets back a fixed 5-to-7-line summary plus the artifact on disk. No specialist reasoning leaks into the orchestrator context.
+- **Resume.** Invoking `/cc` while a flow is active triggers the `flow-resume` skill: 4-line summary plus `r` resume / `s` show / `c` cancel / `n` start new. The triage decision is preserved across sessions.
+- **Schema bump.** `flow-state.json` is now `schemaVersion: 3` with a `triage` field. Existing v2 files are auto-migrated on first read with `acMode: strict` so existing flows behave exactly as in 8.1.
 
 ## What changed in v8
 
-cclaw v8.0 is a breaking redesign. We dropped the 7.x stage machine: no more `brainstorm` / `scope` / `design` / `spec` / `tdd` mandatory stages, no more 18 specialists, no more 9 state files, no more 30 stage gates. v7.x runs are not migrated; see [docs/migration-v7-to-v8.md](docs/migration-v7-to-v8.md).
+cclaw v8.0 was a breaking redesign of the v7 stage machine. We dropped the 7.x stage machine: no more `brainstorm` / `scope` / `design` / `spec` / `tdd` mandatory stages, no more 18 specialists, no more 9 state files, no more 30 stage gates. v7.x runs are not migrated; see [docs/migration-v7-to-v8.md](docs/migration-v7-to-v8.md).
 
 What we kept and made deeper:
 

package/dist/cli.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { CCLAW_VERSION } from "./constants.js";
 import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js";
 import { configureLogger, error as logError, info } from "./logger.js";
@@ -112,8 +115,36 @@ export async function runCli(argv, context) {
             return 2;
     }
 }
-const isMain = import.meta.url === `file://${process.argv[1]}`;
-if (isMain) {
+/**
+ * True when this module is the program entry point. Resolves both the
+ * argv[1] path and the import.meta.url to their realpath because:
+ *  - `npx cclaw-cli` invokes the CLI through a symlink under
+ *    `~/.npm/_npx/<hash>/node_modules/.bin/cclaw-cli` that points at the
+ *    real `dist/cli.js`. argv[1] keeps the symlink path, but
+ *    import.meta.url resolves through to the real file. The naive
+ *    `import.meta.url === \`file://${argv[1]}\`` check returns false in
+ *    this case and the CLI silently exits 0 without doing anything.
+ *  - On macOS `/tmp` is a symlink to `/private/tmp`, which produces the
+ *    same mismatch even when no user-level symlink is involved.
+ *  - `npm install -g cclaw-cli` creates a similar symlink in the global
+ *    bin directory.
+ *
+ * Mirrors the v7.x `isDirectExecution()` check that is known to work
+ * across npx, global installs, and macOS path normalisation.
+ */
+function isDirectExecution() {
+    if (!process.argv[1])
+        return false;
+    try {
+        const entryPath = realpathSync(path.resolve(process.argv[1]));
+        const modulePath = realpathSync(fileURLToPath(import.meta.url));
+        return entryPath === modulePath;
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectExecution()) {
     runCli(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr })
         .then((code) => {
         process.exit(code);

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const CCLAW_VERSION = "8.1.1";
+export declare const CCLAW_VERSION = "8.2.0";
 export declare const RUNTIME_ROOT = ".cclaw";
 export declare const STATE_REL_PATH = ".cclaw/state";
 export declare const HOOKS_REL_PATH = ".cclaw/hooks";

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const CCLAW_VERSION = "8.1.1";
+export const CCLAW_VERSION = "8.2.0";
 export const RUNTIME_ROOT = ".cclaw";
 export const STATE_REL_PATH = `${RUNTIME_ROOT}/state`;
 export const HOOKS_REL_PATH = `${RUNTIME_ROOT}/hooks`;

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

@@ -1,5 +1,5 @@
 export interface ArtifactTemplate {
-    id: "plan" | "build" | "review" | "ship" | "decisions" | "learnings" | "manifest" | "ideas";
+    id: "plan" | "plan-soft" | "build" | "build-soft" | "review" | "ship" | "decisions" | "learnings" | "manifest" | "ideas";
     fileName: string;
     description: string;
     body: string;

package/dist/content/artifact-templates.js

@@ -92,6 +92,53 @@ _(Planner topology mode. Default: \`inline\`. \`parallel-build\` is opt-in; see
 
 This block is rebuilt by \`commit-helper.mjs\` after every AC commit. Do not edit by hand once a commit is recorded.
 `;
+const PLAN_TEMPLATE_SOFT = `---
+slug: SLUG-PLACEHOLDER
+stage: plan
+status: active
+ac_mode: soft
+last_specialist: null
+refines: null
+shipped_at: null
+ship_commit: null
+review_iterations: 0
+security_flag: false
+---
+
+# SLUG-PLACEHOLDER
+
+> One short paragraph: what we are doing and why. If the goal does not fit in 4 lines, the request is probably too large — split it or re-triage to large-risky.
+
+## Plan
+
+_(Planner authors this. One short paragraph describing the change end-to-end. No phases, no AC IDs.)_
+
+## Testable conditions
+
+_(Bullet list. Each line is a behaviour the slice-builder's tests must verify. Conditions are observable; if you can't name a test or manual step that proves it, drop the bullet.)_
+
+- _Condition 1 — observable behaviour, e.g. "Pill renders the request status (Pending / Approved / Denied)."_
+- _Condition 2._
+- _Condition 3._
+
+## Verification
+
+_(One block per layer. Tests file paths, manual steps, runner command.)_
+
+- \`tests/unit/<module>.test.ts\` — covers all listed conditions in one test file.
+- Manual: _open <url>, perform <action>, observe <outcome>_.
+
+## Touch surface
+
+_(Files the slice-builder is allowed to modify. Used by reviewer to flag scope creep.)_
+
+- \`src/<module>/<file>.ts\`
+- \`tests/unit/<module>.test.ts\`
+
+## Notes
+
+_(Optional. Brainstormer / architect did NOT run for soft-mode flows; if you discover the work needs structural decisions or threat modelling mid-flight, surface back to the orchestrator and ask to re-triage as large-risky.)_
+`;
 const BUILD_TEMPLATE = `---
 slug: SLUG-PLACEHOLDER
 stage: build
@@ -162,6 +209,38 @@ _(Append one fix-iteration block per review iteration that returned \`block\`. S
 
 _(Surprises, deviations from the plan, tests added, refactors that came up, paths considered and discarded, etc.)_
 `;
+const BUILD_TEMPLATE_SOFT = `---
+slug: SLUG-PLACEHOLDER
+stage: build
+status: active
+ac_mode: soft
+last_commit: null
+---
+
+# Build log — SLUG-PLACEHOLDER
+
+This is the soft-mode build log. One TDD cycle covers all listed conditions; commits are plain \`git commit\` (the commit-helper is advisory in soft mode).
+
+> **Iron Law:** NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. The RED failure is the spec.
+
+## Plan summary
+
+_(One paragraph mirroring \`flows/SLUG-PLACEHOLDER/plan.md\` Plan section.)_
+
+## Build log
+
+- **Tests added**: _\`tests/unit/<module>.test.ts\` — N tests, mirroring the listed conditions._
+- **Discovery**: _\`src/<module>/<file>.ts:<line>\`, \`tests/unit/<existing>.test.ts:<line>\`._
+- **RED**: _\`<runner command>\` → N failing (expected). Cite the assertion that fails (≤3 lines)._
+- **GREEN**: _One sentence on the minimal change. \`<full-suite command>\` → all passing._
+- **REFACTOR**: _One-line shape change applied, or "skipped: <reason>"._
+- **Commit**: _\`<one-line message>\` (\`<SHA>\`)._
+- **Follow-ups**: _\`info\` items deferred to a separate slug, or "none"._
+
+## Notes
+
+_(Surprises, deviations from the plan, paths considered and discarded, etc.)_
+`;
 const REVIEW_TEMPLATE = `---
 slug: SLUG-PLACEHOLDER
 stage: review
@@ -519,8 +598,10 @@ This file is a free-form idea backlog. Entries are appended by \`/cc-idea\` and
 Each entry begins with an ISO timestamp, then a single-line summary, then the body.
 `;
 export const ARTIFACT_TEMPLATES = [
-    { id: "plan", fileName: "plan.md", description: "Plan template with frontmatter, AC table, and traceability block.", body: PLAN_TEMPLATE },
-    { id: "build", fileName: "build.md", description: "Build log template with commit table and hook invocation log.", body: BUILD_TEMPLATE },
+    { id: "plan", fileName: "plan.md", description: "Strict-mode plan template (AC table, parallelSafe, touchSurface, traceability block).", body: PLAN_TEMPLATE },
+    { id: "plan-soft", fileName: "plan-soft.md", description: "Soft-mode plan template (bullet-list testable conditions, no AC IDs).", body: PLAN_TEMPLATE_SOFT },
+    { id: "build", fileName: "build.md", description: "Strict-mode build log (six-column TDD table, RED proofs, GREEN suite evidence).", body: BUILD_TEMPLATE },
+    { id: "build-soft", fileName: "build-soft.md", description: "Soft-mode build log (single-cycle summary, plain git commit).", body: BUILD_TEMPLATE_SOFT },
     { id: "review", fileName: "review.md", description: "Review template with iteration table, findings table, and Five Failure Modes pass.", body: REVIEW_TEMPLATE },
     { id: "ship", fileName: "ship.md", description: "Ship notes template with AC↔commit map, push/PR section, release notes paragraph.", body: SHIP_TEMPLATE },
     { id: "decisions", fileName: "decisions.md", description: "Architect-style decision record template (D-N entries).", body: DECISIONS_TEMPLATE },

package/dist/content/node-hooks.js

@@ -20,9 +20,14 @@ if (!state) {
   process.exit(0);
 }
 
-if (state.schemaVersion !== 2) {
-  console.error("[cclaw] flow-state schema is from cclaw 7.x. cclaw v8 cannot resume it.");
-  console.error("[cclaw] options: 1) finish/abandon the run with cclaw 7.x; 2) delete .cclaw/state/flow-state.json; 3) start a new v8 plan.");
+if (state.schemaVersion === 1 || state.schemaVersion === undefined) {
+  console.error("[cclaw] flow-state predates cclaw v8 and cannot be auto-migrated.");
+  console.error("[cclaw] options: 1) finish/abandon the run with the older cclaw; 2) delete .cclaw/state/flow-state.json; 3) start a new flow.");
+  process.exit(0);
+}
+
+if (state.schemaVersion !== 3 && state.schemaVersion !== 2) {
+  console.error(\`[cclaw] unknown flow-state schemaVersion \${state.schemaVersion}.\`);
   process.exit(0);
 }
 
@@ -31,9 +36,14 @@ if (!state.currentSlug) {
   process.exit(0);
 }
 
-const pending = (state.ac || []).filter((item) => item.status !== "committed").length;
-const total = (state.ac || []).length;
-console.log(\`[cclaw] active: \${state.currentSlug} (stage=\${state.currentStage ?? "n/a"}); AC committed \${total - pending}/\${total}\`);
+const acMode = state.triage?.acMode ?? "strict";
+const ac = state.ac ?? [];
+if (acMode === "strict" && ac.length > 0) {
+  const pending = ac.filter((item) => item.status !== "committed").length;
+  console.log(\`[cclaw] active: \${state.currentSlug} (stage=\${state.currentStage ?? "n/a"}, mode=strict); AC committed \${ac.length - pending}/\${ac.length}\`);
+} else {
+  console.log(\`[cclaw] active: \${state.currentSlug} (stage=\${state.currentStage ?? "n/a"}, mode=\${acMode}).\`);
+}
 `;
 const STOP_HANDOFF_HOOK = `#!/usr/bin/env node
 // cclaw stop-handoff: short reminder when the agent stops mid-flow.
@@ -53,13 +63,30 @@ async function readState() {
 
 const state = await readState();
 if (!state || !state.currentSlug) process.exit(0);
-const pending = (state.ac || []).filter((item) => item.status !== "committed");
-if (pending.length === 0) process.exit(0);
-console.error(\`[cclaw] stopping with \${pending.length} pending AC for \${state.currentSlug}: \${pending.map((item) => item.id).join(", ")}\`);
+
+const acMode = state.triage?.acMode ?? "strict";
+if (acMode === "strict") {
+  const pending = (state.ac || []).filter((item) => item.status !== "committed");
+  if (pending.length === 0) process.exit(0);
+  console.error(\`[cclaw] stopping with \${pending.length} pending AC for \${state.currentSlug}: \${pending.map((item) => item.id).join(", ")}\`);
+  process.exit(0);
+}
+
+console.error(\`[cclaw] stopping mid-flow for \${state.currentSlug} (stage=\${state.currentStage ?? "n/a"}, mode=\${acMode}). Run /cc to resume.\`);
 `;
 const COMMIT_HELPER_HOOK = `#!/usr/bin/env node
-// cclaw commit-helper: TDD-aware atomic commit per AC phase
-// (RED -> GREEN -> REFACTOR) + AC traceability gate.
+// cclaw commit-helper: ac_mode-aware atomic commit hook.
+//
+// strict mode (large-risky / security-flagged):
+//   commit-helper.mjs --ac=AC-N --phase=red|green|refactor [--skipped] [--message="..."]
+//   enforces TDD cycle, AC trace, no production files in RED, full chain RED -> GREEN -> REFACTOR.
+//
+// soft / inline mode (small-medium / trivial):
+//   commit-helper.mjs --message="..."
+//   advisory only — proxies to git commit, prints a one-line note. --ac/--phase ignored.
+//
+// the mode is read from flow-state.json: state.triage.acMode. if no triage is recorded,
+// default to strict (preserves v8.0/v8.1 behaviour for migrated projects).
 import { execFileSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -77,19 +104,58 @@ function flag(name) {
   return process.argv.includes(\`--\${name}\`);
 }
 
+let state;
+try {
+  state = JSON.parse(await fs.readFile(statePath, "utf8"));
+} catch {
+  console.error("[commit-helper] no flow-state.json. Start a flow with /cc first.");
+  process.exit(2);
+}
+
+if (state.schemaVersion !== 3 && state.schemaVersion !== 2) {
+  console.error(\`[commit-helper] unsupported flow-state schemaVersion \${state.schemaVersion}.\`);
+  process.exit(2);
+}
+
+const acMode = state.triage?.acMode ?? "strict";
+
+if (acMode !== "strict") {
+  // soft / inline mode: advisory passthrough.
+  const message = arg("message");
+  if (!message) {
+    console.error("[commit-helper] --message=\\"...\\" is required.");
+    process.exit(2);
+  }
+  let staged;
+  try {
+    staged = execFileSync("git", ["diff", "--cached", "--name-only"], { cwd: root, encoding: "utf8" }).trim();
+  } catch (error) {
+    console.error(\`[commit-helper] git not available: \${error.message}\`);
+    process.exit(2);
+  }
+  if (!staged) {
+    console.error("[commit-helper] nothing staged. Stage your changes before invoking commit-helper.");
+    process.exit(2);
+  }
+  execFileSync("git", ["commit", "-m", message], { cwd: root, stdio: "inherit" });
+  console.log(\`[commit-helper] committed in \${acMode} mode (no AC trace recorded).\`);
+  process.exit(0);
+}
+
+// strict mode below.
 const acId = arg("ac");
 const phase = arg("phase");
 const message = arg("message") ?? \`cclaw: progress on \${acId ?? "AC"}\`;
 const skipped = flag("skipped");
 
 if (!acId || !/^AC-\\d+$/.test(acId)) {
-  console.error("[commit-helper] usage: commit-helper.mjs --ac=AC-N --phase=red|green|refactor [--skipped] [--message='...']");
+  console.error("[commit-helper] strict mode usage: commit-helper.mjs --ac=AC-N --phase=red|green|refactor [--skipped] [--message='...']");
   process.exit(2);
 }
 
 if (!phase || !["red", "green", "refactor"].includes(phase)) {
-  console.error("[commit-helper] --phase is required. Allowed: red, green, refactor.");
-  console.error("[commit-helper] build is a TDD cycle: every AC needs RED -> GREEN -> REFACTOR.");
+  console.error("[commit-helper] --phase is required in strict mode. Allowed: red, green, refactor.");
+  console.error("[commit-helper] strict-mode build is a TDD cycle: every AC needs RED -> GREEN -> REFACTOR.");
   process.exit(2);
 }
 
@@ -98,19 +164,6 @@ if (skipped && phase !== "refactor") {
   process.exit(2);
 }
 
-let state;
-try {
-  state = JSON.parse(await fs.readFile(statePath, "utf8"));
-} catch {
-  console.error("[commit-helper] no flow-state.json. Start a flow with /cc first.");
-  process.exit(2);
-}
-
-if (state.schemaVersion !== 2) {
-  console.error("[commit-helper] flow-state schema is not v8.");
-  process.exit(2);
-}
-
 const matching = (state.ac ?? []).find((item) => item.id === acId);
 if (!matching) {
   console.error(\`[commit-helper] AC \${acId} is not declared in plan.md / flow-state.\`);