cclaw-cli 0.5.15 → 0.5.17

package/README.md

@@ -120,6 +120,12 @@ Required repository secret:
 └── runs/                     # archived feature snapshots (YYYY-MM-DD-feature-name)
 ```
 
+## Harness Integration
+
+Supported harnesses: `claude`, `cursor`, `opencode`, `codex`. The full
+per-harness install surface, feature matrix, and lifecycle details live in
+[docs/harnesses.md](./docs/harnesses.md).
+
 ## License
 
 [MIT](./LICENSE)

package/dist/artifact-linter.d.ts

@@ -18,3 +18,16 @@ export declare function validateReviewArmy(projectRoot: string): Promise<{
     valid: boolean;
     errors: string[];
 }>;
+export interface ReviewVerdictConsistencyResult {
+    ok: boolean;
+    errors: string[];
+    finalVerdict: "APPROVED" | "APPROVED_WITH_CONCERNS" | "BLOCKED" | "UNKNOWN";
+    openCriticalCount: number;
+    shipBlockerCount: number;
+}
+/**
+ * Ensure the narrative verdict in 07-review.md is consistent with the
+ * structured review-army reconciliation. A review cannot declare
+ * APPROVED while open Critical findings or shipBlockers remain.
+ */
+export declare function checkReviewVerdictConsistency(projectRoot: string): Promise<ReviewVerdictConsistencyResult>;

package/dist/artifact-linter.js

@@ -134,7 +134,61 @@ function extractRequiredKeywords(rule) {
         return [];
     return phrases;
 }
-function validateSectionBody(sectionBody, rule) {
+const VAGUE_AC_ADJECTIVES = [
+    "fast",
+    "quick",
+    "slow",
+    "fast enough",
+    "quickly",
+    "intuitive",
+    "robust",
+    "reliable",
+    "scalable",
+    "simple",
+    "easy",
+    "user-friendly",
+    "user friendly",
+    "nice",
+    "good",
+    "clean",
+    "secure enough",
+    "responsive",
+    "efficient",
+    "performant",
+    "smooth",
+    "seamless",
+    "modern"
+];
+function isSeparatorRow(line) {
+    return /^\|[-:| ]+\|$/u.test(line);
+}
+function getMarkdownTableRows(sectionBody) {
+    const lines = sectionBody.split(/\r?\n/).map((line) => line.trim());
+    const rows = [];
+    let sawSeparator = false;
+    for (const line of lines) {
+        if (!/^\|.*\|$/u.test(line))
+            continue;
+        if (isSeparatorRow(line)) {
+            sawSeparator = true;
+            continue;
+        }
+        if (!sawSeparator)
+            continue;
+        rows.push(parseMarkdownTableRow(line));
+    }
+    return rows;
+}
+function lineContainsVagueAdjective(text) {
+    const lower = text.toLowerCase();
+    for (const adjective of VAGUE_AC_ADJECTIVES) {
+        const pattern = new RegExp(`(?:^|[^A-Za-z])${adjective.replace(/ /g, "\\s+")}(?:[^A-Za-z]|$)`, "iu");
+        if (pattern.test(lower))
+            return adjective;
+    }
+    return null;
+}
+function validateSectionBody(sectionBody, rule, sectionName) {
     const bodyLines = sectionBody.split(/\r?\n/).map((line) => line.trim());
     const meaningful = meaningfulLineCount(sectionBody);
     if (meaningful === 0) {
@@ -231,6 +285,29 @@ function validateSectionBody(sectionBody, rule) {
             };
         }
     }
+    if (normalizeHeadingTitle(sectionName).toLowerCase() === "acceptance criteria" &&
+        /observable[\s,]*measurable[\s,]+(and )?falsifiable/iu.test(rule)) {
+        const rows = getMarkdownTableRows(sectionBody);
+        for (const row of rows) {
+            const criterionText = row[1] ?? row[0] ?? "";
+            const adjective = lineContainsVagueAdjective(criterionText);
+            if (adjective) {
+                return {
+                    ok: false,
+                    details: `Acceptance criterion uses vague adjective "${adjective}" without a measurable predicate: "${criterionText.slice(0, 140)}". Rewrite with a numeric threshold or boolean outcome.`
+                };
+            }
+            const hasDigit = /\d/u.test(criterionText);
+            const hasMeasurableVerb = /\b(blocks?|rejects?|returns?|matches?|equals?|emits?|succeeds?|fails?|publishes?|logs?|persists?|reads?|writes?|creates?|deletes?|throws?|contains?|restores?|exceeds?|responds?|warns?|quarantines?|includes?|raises?|passes?|denies|refuses|exits|succeeds|completes|prevents|allows|maps|points|signals|surfaces|records|produces|accepts|requires)\b/iu.test(criterionText);
+            const hasMeaningfulText = /[A-Za-z]/u.test(criterionText) && criterionText.trim().length >= 12;
+            if (hasMeaningfulText && !hasDigit && !hasMeasurableVerb) {
+                return {
+                    ok: false,
+                    details: `Acceptance criterion lacks a measurable predicate (no numeric threshold, no observable verb like blocks/returns/publishes/matches): "${criterionText.slice(0, 140)}". Rewrite so the criterion is falsifiable by a single test.`
+                };
+            }
+        }
+    }
     return {
         ok: true,
         details: "Section heading and content satisfy lint heuristics."
@@ -273,7 +350,7 @@ export async function lintArtifact(projectRoot, stage) {
         const body = hasHeading ? sectionBodyByName(sections, v.section) : null;
         const validation = body === null
             ? { ok: false, details: `No ## heading matching required section "${v.section}".` }
-            : validateSectionBody(body, v.validationRule);
+            : validateSectionBody(body, v.validationRule, v.section);
         const found = hasHeading && validation.ok;
         findings.push({
             section: v.section,
@@ -384,18 +461,19 @@ export async function validateReviewArmy(projectRoot) {
             if (!isStringArray(o.reportedBy) || o.reportedBy.length === 0) {
                 errors.push(`findings[${i}].reportedBy must be a non-empty string array.`);
             }
-            if (o.location !== undefined) {
-                if (o.location === null || typeof o.location !== "object" || Array.isArray(o.location)) {
-                    errors.push(`findings[${i}].location must be an object when present.`);
+            if (o.location === undefined || o.location === null) {
+                errors.push(`findings[${i}].location is required and must be an object with file + line.`);
+            }
+            else if (typeof o.location !== "object" || Array.isArray(o.location)) {
+                errors.push(`findings[${i}].location must be an object with file + line.`);
+            }
+            else {
+                const loc = o.location;
+                if (!isNonEmptyString(loc.file)) {
+                    errors.push(`findings[${i}].location.file must be a non-empty string.`);
                 }
-                else {
-                    const loc = o.location;
-                    if (!isNonEmptyString(loc.file)) {
-                        errors.push(`findings[${i}].location.file must be a non-empty string.`);
-                    }
-                    if (!isFiniteNumber(loc.line) || loc.line < 1) {
-                        errors.push(`findings[${i}].location.line must be a positive number.`);
-                    }
+                if (!isFiniteNumber(loc.line) || loc.line < 1) {
+                    errors.push(`findings[${i}].location.line must be a positive number.`);
                 }
             }
             if (o.recommendation !== undefined && !isNonEmptyString(o.recommendation)) {
@@ -445,6 +523,21 @@ export async function validateReviewArmy(projectRoot) {
             for (const msId of rec.multiSpecialistConfirmed) {
                 if (!findingIds.has(msId)) {
                     errors.push(`reconciliation.multiSpecialistConfirmed references unknown finding id "${msId}".`);
+                    continue;
+                }
+                if (Array.isArray(root.findings)) {
+                    const finding = root.findings.find((f) => {
+                        return f && typeof f === "object" && !Array.isArray(f) && f.id === msId;
+                    });
+                    if (finding && typeof finding === "object" && !Array.isArray(finding)) {
+                        const reportedBy = finding.reportedBy;
+                        const count = Array.isArray(reportedBy)
+                            ? new Set(reportedBy.filter((v) => typeof v === "string")).size
+                            : 0;
+                        if (count < 2) {
+                            errors.push(`reconciliation.multiSpecialistConfirmed entry "${msId}" must be confirmed by at least 2 distinct reviewers (found ${count}).`);
+                        }
+                    }
                 }
             }
         }
@@ -474,3 +567,79 @@ export async function validateReviewArmy(projectRoot) {
     }
     return { valid: errors.length === 0, errors };
 }
+/**
+ * Ensure the narrative verdict in 07-review.md is consistent with the
+ * structured review-army reconciliation. A review cannot declare
+ * APPROVED while open Critical findings or shipBlockers remain.
+ */
+export async function checkReviewVerdictConsistency(projectRoot) {
+    const errors = [];
+    const reviewMdPath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", "07-review.md");
+    const armyJsonPath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", "07-review-army.json");
+    let finalVerdict = "UNKNOWN";
+    if (await exists(reviewMdPath)) {
+        const raw = await fs.readFile(reviewMdPath, "utf8");
+        const sections = extractH2Sections(raw);
+        const verdictBody = sectionBodyByName(sections, "Final Verdict");
+        if (verdictBody) {
+            const chosen = [];
+            for (const token of ["APPROVED_WITH_CONCERNS", "APPROVED", "BLOCKED"]) {
+                const regex = new RegExp(`\\b${token}\\b`, "u");
+                if (regex.test(verdictBody)) {
+                    // APPROVED would match inside APPROVED_WITH_CONCERNS; prefer the longer match first.
+                    if (token === "APPROVED" && /\bAPPROVED_WITH_CONCERNS\b/u.test(verdictBody))
+                        continue;
+                    chosen.push(token);
+                }
+            }
+            if (chosen.length === 1) {
+                finalVerdict = chosen[0];
+            }
+            else if (chosen.length > 1) {
+                errors.push(`Final Verdict section lists multiple verdict tokens (${chosen.join(", ")}). Select exactly one.`);
+            }
+            else {
+                errors.push('Final Verdict section does not select APPROVED, APPROVED_WITH_CONCERNS, or BLOCKED.');
+            }
+        }
+        else {
+            errors.push('07-review.md is missing the "## Final Verdict" section.');
+        }
+    }
+    let openCriticalCount = 0;
+    let shipBlockerCount = 0;
+    if (await exists(armyJsonPath)) {
+        try {
+            const raw = await fs.readFile(armyJsonPath, "utf8");
+            const parsed = JSON.parse(raw);
+            const findings = Array.isArray(parsed.findings) ? parsed.findings : [];
+            for (const f of findings) {
+                if (!f || typeof f !== "object" || Array.isArray(f))
+                    continue;
+                const o = f;
+                if (o.severity === "Critical" && o.status === "open") {
+                    openCriticalCount++;
+                }
+            }
+            const rec = parsed.reconciliation && typeof parsed.reconciliation === "object" && !Array.isArray(parsed.reconciliation)
+                ? parsed.reconciliation
+                : null;
+            if (rec && Array.isArray(rec.shipBlockers)) {
+                shipBlockerCount = rec.shipBlockers.filter((v) => typeof v === "string").length;
+            }
+        }
+        catch {
+            // JSON validity is the concern of validateReviewArmy; skip silently here.
+        }
+    }
+    if (finalVerdict === "APPROVED" && (openCriticalCount > 0 || shipBlockerCount > 0)) {
+        errors.push(`Final Verdict is APPROVED but review-army has ${openCriticalCount} open Critical finding(s) and ${shipBlockerCount} shipBlocker(s). Use BLOCKED or APPROVED_WITH_CONCERNS.`);
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        finalVerdict,
+        openCriticalCount,
+        shipBlockerCount
+    };
+}

package/dist/cli.d.ts

@@ -6,7 +6,10 @@ interface ParsedArgs {
     harnesses?: HarnessId[];
     reconcileGates?: boolean;
     archiveName?: string;
+    showHelp?: boolean;
+    showVersion?: boolean;
 }
+export declare function usage(): string;
 declare function parseHarnesses(raw: string): HarnessId[];
 declare function parseArgs(argv: string[]): ParsedArgs;
 export { parseArgs, parseHarnesses };

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import process from "node:process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -9,18 +9,63 @@ import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js
 import { error, info } from "./logger.js";
 import { archiveRun } from "./runs.js";
 const INSTALLER_COMMANDS = ["init", "sync", "doctor", "upgrade", "uninstall", "archive"];
-function usage() {
+export function usage() {
     return `cclaw - installer-first flow toolkit
 
 Usage:
-  cclaw init [--harnesses=claude,cursor,opencode,codex]
-  cclaw sync
-  cclaw doctor [--reconcile-gates]
-  cclaw archive [--name=feature-name]
-  cclaw upgrade
-  cclaw uninstall
+  cclaw <command> [flags]
+  cclaw --help | -h
+  cclaw --version | -v
+
+Commands:
+  init       Bootstrap .cclaw runtime, state, and harness shims in this project.
+             Flags: --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex).
+  sync       Regenerate harness shim files from the current .cclaw config (non-destructive).
+  doctor     Run health checks against the local .cclaw runtime. Exit code 2 on failure.
+             Flags: --reconcile-gates   Recompute current-stage gate evidence before checks.
+  archive    Move .cclaw/artifacts into .cclaw/runs/<date>-<slug> and reset flow state.
+             Flags: --name=<feature>    Feature slug (default: inferred from 00-idea.md).
+  upgrade    Refresh generated files in .cclaw without modifying user artifacts.
+  uninstall  Remove .cclaw runtime and the generated harness shim files.
+
+Global flags:
+  -h, --help     Show this help message and exit 0.
+  -v, --version  Print the cclaw CLI version and exit 0.
+
+Examples:
+  cclaw init --harnesses=claude,cursor
+  cclaw doctor --reconcile-gates
+  cclaw archive --name=payments-revamp
+
+Docs:   https://github.com/zuevrs/cclaw
+Issues: https://github.com/zuevrs/cclaw/issues
 `;
 }
+function cliPackageVersion() {
+    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
+    }
+    return "unknown";
+}
 function parseHarnesses(raw) {
     const requested = raw
         .split(",")
@@ -33,11 +78,19 @@ function parseHarnesses(raw) {
     return requested;
 }
 function parseArgs(argv) {
-    const [commandRaw, ...flags] = argv;
-    const command = INSTALLER_COMMANDS.includes(commandRaw)
+    const parsed = {};
+    const helpFlag = argv.find((arg) => arg === "--help" || arg === "-h");
+    if (helpFlag) {
+        parsed.showHelp = true;
+    }
+    const versionFlag = argv.find((arg) => arg === "--version" || arg === "-v");
+    if (versionFlag) {
+        parsed.showVersion = true;
+    }
+    const [commandRaw, ...flags] = argv.filter((arg) => arg !== "--help" && arg !== "-h" && arg !== "--version" && arg !== "-v");
+    parsed.command = INSTALLER_COMMANDS.includes(commandRaw)
         ? commandRaw
         : undefined;
-    const parsed = { command };
     for (const flag of flags) {
         if (flag.startsWith("--harnesses=")) {
             parsed.harnesses = parseHarnesses(flag.replace("--harnesses=", ""));
@@ -54,6 +107,14 @@ function parseArgs(argv) {
     return parsed;
 }
 async function runCommand(parsed, ctx) {
+    if (parsed.showHelp) {
+        ctx.stdout.write(usage());
+        return 0;
+    }
+    if (parsed.showVersion) {
+        ctx.stdout.write(`cclaw ${cliPackageVersion()}\n`);
+        return 0;
+    }
     const command = parsed.command;
     if (!command) {
         ctx.stderr.write(usage());
@@ -88,7 +149,10 @@ async function runCommand(parsed, ctx) {
     }
     if (command === "archive") {
         const archived = await archiveRun(ctx.cwd, parsed.archiveName);
-        info(ctx, `Archived active artifacts to ${archived.archivePath}. Flow state reset to brainstorm.`);
+        const snapshotSummary = archived.snapshottedStateFiles.length > 0
+            ? ` Snapshotted ${archived.snapshottedStateFiles.length} state file(s) under ${archived.archivePath}/state and wrote archive-manifest.json.`
+            : "";
+        info(ctx, `Archived active artifacts to ${archived.archivePath}. Flow state reset to brainstorm.${snapshotSummary}`);
         return 0;
     }
     await uninstallCclaw(ctx.cwd);

package/dist/content/agents.js

@@ -94,10 +94,10 @@ export const CCLAW_AGENTS = [
     },
     {
         name: "security-reviewer",
-        description: "PROACTIVE after auth, crypto, secrets, parsers, or sensitive data paths change. MUST BE USED when trust boundaries move, new external inputs arrive, or LLM/tool output influences privileged actions.",
+        description: "MANDATORY during every review stage. Even when no auth, crypto, secrets, parsers, or sensitive data paths changed, produce an explicit 'no-change' security attestation. MUST BE USED when trust boundaries move, new external inputs arrive, or LLM/tool output influences privileged actions.",
         tools: ["Read", "Grep", "Glob"],
         model: "balanced",
-        activation: "proactive",
+        activation: "mandatory",
         relatedStages: ["review", "design"],
         body: [
             "You are a **security vulnerability detection** specialist focused on practical exploitability.",
@@ -216,7 +216,7 @@ export function agentRoutingTable() {
 | Brainstorm (start with \`/cc <idea>\`) | planner | — |
 | Scope / Design / Spec / Plan (advance via \`/cc-next\`) | planner | security-reviewer on design, spec-reviewer on spec |
 | TDD (via \`/cc-next\`) | test-author | doc-updater |
-| Review (via \`/cc-next\`) | spec-reviewer, code-reviewer | security-reviewer |
+| Review (via \`/cc-next\`) | spec-reviewer, code-reviewer, security-reviewer | — |
 | Ship (via \`/cc-next\`) | — | doc-updater |
 `;
 }
@@ -231,8 +231,8 @@ Cclaw provides specialist agents under \`.cclaw/agents/\` for targeted delegatio
 ${agentRoutingTable()}
 
 **Activation modes:**
-- **Mandatory:** MUST be used when the related stage runs (spec-reviewer, code-reviewer during review)
-- **Proactive:** Should be used automatically when context matches (planner for complex features, security-reviewer for auth code)
+- **Mandatory:** MUST be used when the related stage runs (spec-reviewer, code-reviewer, and security-reviewer during review; planner during scope and design; test-author during tdd; doc-updater during ship). Even if a change has no trust-boundary impact, security-reviewer produces an explicit no-change attestation.
+- **Proactive:** Should be used automatically when context matches (planner for complex features, security-reviewer escalations outside review, doc-updater on behavior changes)
 - **On-demand:** Invoked only when explicitly requested
 
 **Agent files:** \`.cclaw/agents/{name}.md\` — each contains YAML frontmatter with tools and model tier.