cclaw-cli 0.10.1 → 0.12.0

package/README.md

@@ -41,7 +41,7 @@ sequenceDiagram
 - **Low cognitive load:** one canonical stage flow instead of dozens of competing paths.
 - **Installer-first architecture:** generates files and hooks; does not run a hidden control plane.
 - **Hard-gated quality:** each stage has non-skippable constraints that reduce AI drift.
-- **Cross-harness parity:** same behavior model across Claude Code, Cursor, Codex, OpenCode.
+- **Tiered harness coverage:** transparent capability tiers across Claude Code, Cursor, Codex, OpenCode.
 - **Compounding context:** flow state + project knowledge get rehydrated on new sessions automatically.
 - **Incremental delivery:** active artifacts stay in one place; `cclaw archive` snapshots completed features into dated run folders.
 
@@ -114,16 +114,17 @@ Required repository secret:
 ├── commands/
 ├── hooks/
 ├── templates/
+├── references/
 ├── artifacts/                # active feature artifacts
 ├── state/
-├── knowledge.md              # append-only rule/pattern/lesson log
+├── knowledge.jsonl           # append-only strict-schema rule/pattern/lesson log
 └── 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
+per-harness tier/capability matrix, install surface, and lifecycle details live in
 [docs/harnesses.md](./docs/harnesses.md).
 
 ## License

package/dist/cli.d.ts

@@ -6,7 +6,13 @@ interface ParsedArgs {
     harnesses?: HarnessId[];
     track?: FlowTrack;
     profile?: InitProfile;
+    dryRun?: boolean;
+    interactive?: boolean;
     reconcileGates?: boolean;
+    doctorJson?: boolean;
+    doctorExplain?: boolean;
+    doctorQuiet?: boolean;
+    doctorOnly?: string[];
     archiveName?: string;
     showHelp?: boolean;
     showVersion?: boolean;

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { readFileSync, realpathSync } from "node:fs";
 import process from "node:process";
 import path from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { FLOW_TRACKS, HARNESS_IDS, INIT_PROFILES } from "./types.js";
 import { doctorChecks, doctorSucceeded } from "./doctor.js";
@@ -9,6 +10,9 @@ import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js
 import { error, info } from "./logger.js";
 import { archiveRun } from "./runs.js";
 import { RUNTIME_ROOT } from "./constants.js";
+import { createDefaultConfig, createProfileConfig } from "./config.js";
+import { detectHarnesses } from "./init-detect.js";
+import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 const INSTALLER_COMMANDS = ["init", "sync", "doctor", "upgrade", "uninstall", "archive"];
 export function usage() {
     return `cclaw - installer-first flow toolkit
@@ -22,10 +26,17 @@ Commands:
   init       Bootstrap .cclaw runtime, state, and harness shims in this project.
              Flags: --profile=<id>      Pre-fill defaults. One of: minimal | standard | full. Default: standard.
                     --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex). Overrides the profile default.
-                    --track=<id>        Flow track for new runs (standard | quick). Overrides the profile default.
+                    --track=<id>        Flow track for new runs (standard | medium | quick). Overrides the profile default.
+                    --interactive       Force interactive prompts (TTY only).
+                    --no-interactive    Skip interactive prompts even on TTY.
+                    --dry-run           Print resolved config + generated surfaces without writing files.
   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.
+  doctor     Run health checks against the local .cclaw runtime. Exit code 2 when any error-severity check fails.
              Flags: --reconcile-gates   Recompute current-stage gate evidence before checks.
+                    --json              Emit machine-readable JSON output.
+                    --only=<filter>     Comma list of severities/check-name filters (error,warning,info,trace:,hook:...).
+                    --explain           Include fix + doc reference per check in text mode.
+                    --quiet             Print only failing checks (and totals).
   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.
@@ -94,6 +105,208 @@ function parseProfile(raw) {
     }
     return trimmed;
 }
+function isInitPromptAllowed(ctx) {
+    return Boolean(process.stdin.isTTY && ctx.stdout.isTTY);
+}
+function buildInitSurfacePreview(harnesses) {
+    const lines = [
+        ".cclaw/config.yaml",
+        ".cclaw/commands/*.md",
+        ".cclaw/skills/*/SKILL.md",
+        ".cclaw/state/*.json|*.jsonl",
+        ".cclaw/references/**",
+        "AGENTS.md (managed block)"
+    ];
+    for (const harness of harnesses) {
+        const adapter = HARNESS_ADAPTERS[harness];
+        lines.push(`${adapter.commandDir}/cc*.md`);
+        if (harness === "claude") {
+            lines.push(".claude/hooks/hooks.json");
+        }
+        if (harness === "cursor") {
+            lines.push(".cursor/hooks.json");
+            lines.push(".cursor/rules/cclaw-workflow.mdc");
+        }
+        if (harness === "codex") {
+            lines.push(".codex/hooks.json");
+        }
+        if (harness === "opencode") {
+            lines.push(".opencode/plugins/cclaw-plugin.mjs");
+            lines.push("opencode.json(.c) plugin registration");
+        }
+    }
+    return lines;
+}
+function inferTrackDefault(profile, track) {
+    if (track)
+        return track;
+    if (!profile)
+        return "standard";
+    return createProfileConfig(profile).defaultTrack ?? "standard";
+}
+async function promptInitConfig(defaults, ctx) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: ctx.stdout
+    });
+    const pickSingle = async (label, options, fallback) => {
+        while (true) {
+            ctx.stdout.write(`\n${label}\n`);
+            options.forEach((option, index) => {
+                const marker = option === fallback ? " (default)" : "";
+                ctx.stdout.write(`  ${index + 1}) ${option}${marker}\n`);
+            });
+            const answer = (await rl.question("> ")).trim();
+            if (answer.length === 0) {
+                return fallback;
+            }
+            const numeric = Number(answer);
+            if (Number.isInteger(numeric) && numeric >= 1 && numeric <= options.length) {
+                return options[numeric - 1];
+            }
+            if (options.includes(answer)) {
+                return answer;
+            }
+            ctx.stdout.write("Invalid selection. Use option number or value.\n");
+        }
+    };
+    const pickHarnesses = async (fallback) => {
+        const fallbackText = fallback.join(",");
+        while (true) {
+            const answer = (await rl.question(`\nHarnesses (comma list from ${HARNESS_IDS.join(", ")}) [${fallbackText}]: `)).trim();
+            if (answer.length === 0) {
+                return fallback;
+            }
+            try {
+                const parsed = parseHarnesses(answer);
+                if (parsed.length === 0) {
+                    ctx.stdout.write("Select at least one harness.\n");
+                    continue;
+                }
+                return parsed;
+            }
+            catch (err) {
+                ctx.stdout.write(`${err instanceof Error ? err.message : "Invalid harness list"}\n`);
+            }
+        }
+    };
+    try {
+        const profile = await pickSingle("Select init profile:", INIT_PROFILES, defaults.profile);
+        const trackDefault = inferTrackDefault(profile, defaults.track);
+        const track = await pickSingle("Select default flow track:", FLOW_TRACKS, trackDefault);
+        const harnesses = await pickHarnesses(defaults.harnesses);
+        return { profile, track, harnesses };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function resolveInitInputs(parsed, ctx) {
+    const detectedHarnesses = parsed.harnesses ? [] : await detectHarnesses(ctx.cwd);
+    const autoHarnesses = parsed.harnesses
+        ? parsed.harnesses
+        : (detectedHarnesses.length > 0 ? detectedHarnesses : undefined);
+    const promptRequested = parsed.interactive === true;
+    const promptForbidden = parsed.interactive === false;
+    const implicitPrompt = !promptForbidden &&
+        isInitPromptAllowed(ctx) &&
+        parsed.profile === undefined &&
+        parsed.track === undefined &&
+        parsed.harnesses === undefined;
+    const shouldPrompt = promptRequested || implicitPrompt;
+    if (!shouldPrompt) {
+        return {
+            profile: parsed.profile,
+            track: parsed.track,
+            harnesses: autoHarnesses,
+            detectedHarnesses
+        };
+    }
+    if (!isInitPromptAllowed(ctx)) {
+        throw new Error("Interactive init requires a TTY. Remove --interactive or run in a terminal.");
+    }
+    const defaults = {
+        profile: parsed.profile ?? "standard",
+        track: inferTrackDefault(parsed.profile, parsed.track),
+        harnesses: autoHarnesses ?? HARNESS_IDS.slice()
+    };
+    const prompted = await promptInitConfig(defaults, ctx);
+    return {
+        profile: prompted.profile,
+        track: prompted.track,
+        harnesses: prompted.harnesses,
+        detectedHarnesses
+    };
+}
+function parseDoctorOnly(raw) {
+    return raw
+        .split(",")
+        .map((item) => item.trim().toLowerCase())
+        .filter((item) => item.length > 0);
+}
+function filterDoctorChecks(checks, filters) {
+    if (!filters || filters.length === 0) {
+        return checks;
+    }
+    return checks.filter((check) => {
+        const name = check.name.toLowerCase();
+        return filters.some((filter) => {
+            if (filter === "error" || filter === "warning" || filter === "info") {
+                return check.severity === filter;
+            }
+            return name.includes(filter);
+        });
+    });
+}
+function doctorCountsBySeverity(checks) {
+    const result = {
+        error: { total: 0, failing: 0 },
+        warning: { total: 0, failing: 0 },
+        info: { total: 0, failing: 0 }
+    };
+    for (const check of checks) {
+        const bucket = result[check.severity];
+        bucket.total += 1;
+        if (!check.ok) {
+            bucket.failing += 1;
+        }
+    }
+    return result;
+}
+function printDoctorText(ctx, checks, options) {
+    const orderedSeverities = ["error", "warning", "info"];
+    const view = options.quiet ? checks.filter((check) => !check.ok) : checks;
+    for (const severity of orderedSeverities) {
+        const inBucket = view.filter((check) => check.severity === severity);
+        if (inBucket.length === 0)
+            continue;
+        ctx.stdout.write(`\n[${severity.toUpperCase()}]\n`);
+        for (const check of inBucket) {
+            const status = check.ok ? "PASS" : "FAIL";
+            ctx.stdout.write(`${status} ${check.name} :: ${check.summary}\n`);
+            if (!options.quiet) {
+                ctx.stdout.write(`  details: ${check.details}\n`);
+            }
+            if (options.explain) {
+                ctx.stdout.write(`  fix: ${check.fix}\n`);
+                if (check.docRef) {
+                    ctx.stdout.write(`  docs: ${check.docRef}\n`);
+                }
+            }
+        }
+    }
+    const counts = doctorCountsBySeverity(checks);
+    const failingErrors = checks.filter((check) => check.severity === "error" && !check.ok).length;
+    ctx.stdout.write(`\nTotals: error ${counts.error.failing}/${counts.error.total} failing, ` +
+        `warning ${counts.warning.failing}/${counts.warning.total} failing, ` +
+        `info ${counts.info.failing}/${counts.info.total} failing\n`);
+    if (failingErrors > 0) {
+        ctx.stdout.write(`Doctor status: BLOCKED (${failingErrors} failing error checks)\n`);
+    }
+    else {
+        ctx.stdout.write("Doctor status: HEALTHY (no failing error checks)\n");
+    }
+}
 function parseArgs(argv) {
     const parsed = {};
     const helpFlag = argv.find((arg) => arg === "--help" || arg === "-h");
@@ -121,10 +334,38 @@ function parseArgs(argv) {
             parsed.profile = parseProfile(flag.replace("--profile=", ""));
             continue;
         }
+        if (flag === "--interactive") {
+            parsed.interactive = true;
+            continue;
+        }
+        if (flag === "--no-interactive") {
+            parsed.interactive = false;
+            continue;
+        }
+        if (flag === "--dry-run") {
+            parsed.dryRun = true;
+            continue;
+        }
         if (flag === "--reconcile-gates") {
             parsed.reconcileGates = true;
             continue;
         }
+        if (flag === "--json") {
+            parsed.doctorJson = true;
+            continue;
+        }
+        if (flag === "--explain") {
+            parsed.doctorExplain = true;
+            continue;
+        }
+        if (flag === "--quiet") {
+            parsed.doctorQuiet = true;
+            continue;
+        }
+        if (flag.startsWith("--only=")) {
+            parsed.doctorOnly = parseDoctorOnly(flag.replace("--only=", ""));
+            continue;
+        }
         if (flag.startsWith("--name=")) {
             parsed.archiveName = flag.replace("--name=", "").trim();
         }
@@ -146,14 +387,44 @@ async function runCommand(parsed, ctx) {
         return 1;
     }
     if (command === "init") {
+        const resolved = await resolveInitInputs(parsed, ctx);
+        const effectiveProfile = resolved.profile;
+        const effectiveTrack = resolved.track;
+        const effectiveHarnesses = resolved.harnesses;
+        if (parsed.dryRun === true) {
+            const previewConfig = effectiveProfile
+                ? createProfileConfig(effectiveProfile, {
+                    harnesses: effectiveHarnesses,
+                    defaultTrack: effectiveTrack
+                })
+                : createDefaultConfig(effectiveHarnesses, effectiveTrack);
+            const previewSurfaces = buildInitSurfacePreview(previewConfig.harnesses);
+            info(ctx, "Dry run: no files were written.");
+            if (resolved.detectedHarnesses.length > 0 && parsed.harnesses === undefined) {
+                info(ctx, `Detected harnesses from repo: ${resolved.detectedHarnesses.join(", ")}`);
+            }
+            ctx.stdout.write(`${JSON.stringify({
+                profile: effectiveProfile ?? "standard(default)",
+                track: previewConfig.defaultTrack ?? "standard",
+                harnesses: previewConfig.harnesses,
+                promptGuardMode: previewConfig.promptGuardMode,
+                gitHookGuards: previewConfig.gitHookGuards,
+                languageRulePacks: previewConfig.languageRulePacks,
+                generatedSurfaces: previewSurfaces
+            }, null, 2)}\n`);
+            return 0;
+        }
         await initCclaw({
             projectRoot: ctx.cwd,
-            harnesses: parsed.harnesses,
-            track: parsed.track,
-            profile: parsed.profile
+            harnesses: effectiveHarnesses,
+            track: effectiveTrack,
+            profile: effectiveProfile
         });
-        const profileNote = parsed.profile ? ` profile=${parsed.profile}` : "";
-        const trackNote = parsed.track ? ` track=${parsed.track}` : "";
+        if (resolved.detectedHarnesses.length > 0 && parsed.harnesses === undefined) {
+            info(ctx, `Detected harnesses from repo: ${resolved.detectedHarnesses.join(", ")}`);
+        }
+        const profileNote = effectiveProfile ? ` profile=${effectiveProfile}` : "";
+        const trackNote = effectiveTrack ? ` track=${effectiveTrack}` : "";
         const suffix = profileNote || trackNote ? ` (${(profileNote + trackNote).trim()})` : "";
         info(ctx, `Initialized .cclaw runtime and generated harness shims${suffix}`);
         return 0;
@@ -167,8 +438,25 @@ async function runCommand(parsed, ctx) {
         const checks = await doctorChecks(ctx.cwd, {
             reconcileCurrentStageGates: parsed.reconcileGates === true
         });
-        for (const check of checks) {
-            ctx.stdout.write(`${check.ok ? "PASS" : "FAIL"} ${check.name} :: ${check.details}\n`);
+        const filteredChecks = filterDoctorChecks(checks, parsed.doctorOnly);
+        const explain = parsed.doctorExplain === true;
+        const quiet = parsed.doctorQuiet === true;
+        if (parsed.doctorJson === true) {
+            const counts = doctorCountsBySeverity(filteredChecks);
+            ctx.stdout.write(`${JSON.stringify({
+                ok: doctorSucceeded(checks),
+                filters: parsed.doctorOnly ?? [],
+                counts,
+                checks: filteredChecks
+            }, null, 2)}\n`);
+        }
+        else {
+            if (filteredChecks.length === 0) {
+                ctx.stdout.write("No checks matched the --only filter.\n");
+            }
+            else {
+                printDoctorText(ctx, filteredChecks, { explain, quiet });
+            }
         }
         return doctorSucceeded(checks) ? 0 : 2;
     }

package/dist/config.js

@@ -19,7 +19,8 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "promptGuardMode",
     "gitHookGuards",
     "defaultTrack",
-    "languageRulePacks"
+    "languageRulePacks",
+    "trackHeuristics"
 ]);
 function configFixExample() {
     return `harnesses:
@@ -34,6 +35,21 @@ function configValidationError(configFilePath, reason) {
         `Example config:\n${configFixExample()}\n` +
         `After fixing, run: cclaw sync`);
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateStringArray(value, fieldName, configFilePath) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw configValidationError(configFilePath, `"${fieldName}" must be an array of strings`);
+    }
+    const invalid = value.filter((item) => typeof item !== "string");
+    if (invalid.length > 0) {
+        throw configValidationError(configFilePath, `"${fieldName}" must contain only strings`);
+    }
+    return value;
+}
 export function configPath(projectRoot) {
     return path.join(projectRoot, CONFIG_PATH);
 }
@@ -64,7 +80,7 @@ export function createProfileConfig(profile, overrides = {}) {
                 autoAdvance: false,
                 promptGuardMode: "advisory",
                 gitHookGuards: false,
-                defaultTrack: overrides.defaultTrack ?? "quick",
+                defaultTrack: overrides.defaultTrack ?? "medium",
                 languageRulePacks: overrides.languageRulePacks ?? []
             };
         case "standard":
@@ -161,6 +177,69 @@ export async function readConfig(projectRoot) {
         throw configValidationError(fullPath, `unknown languageRulePacks id(s): ${formatted}`);
     }
     const languageRulePacks = [...new Set(rawPacks)];
+    const trackHeuristicsRaw = parsed.trackHeuristics;
+    let trackHeuristics = undefined;
+    if (Object.prototype.hasOwnProperty.call(parsed, "trackHeuristics")) {
+        if (!isRecord(trackHeuristicsRaw)) {
+            throw configValidationError(fullPath, `"trackHeuristics" must be an object`);
+        }
+        const fallbackRaw = trackHeuristicsRaw.fallback;
+        if (fallbackRaw !== undefined && (typeof fallbackRaw !== "string" || !FLOW_TRACK_SET.has(fallbackRaw))) {
+            throw configValidationError(fullPath, `"trackHeuristics.fallback" must be one of: ${SUPPORTED_TRACKS_TEXT}`);
+        }
+        const priorityRaw = trackHeuristicsRaw.priority;
+        let priority;
+        if (priorityRaw !== undefined) {
+            if (!Array.isArray(priorityRaw)) {
+                throw configValidationError(fullPath, `"trackHeuristics.priority" must be an array`);
+            }
+            const invalidPriority = priorityRaw.filter((value) => typeof value !== "string" || !FLOW_TRACK_SET.has(value));
+            if (invalidPriority.length > 0) {
+                throw configValidationError(fullPath, `"trackHeuristics.priority" must contain only: ${SUPPORTED_TRACKS_TEXT}`);
+            }
+            priority = [...new Set(priorityRaw)];
+        }
+        const tracksRaw = trackHeuristicsRaw.tracks;
+        let tracks = undefined;
+        if (tracksRaw !== undefined) {
+            if (!isRecord(tracksRaw)) {
+                throw configValidationError(fullPath, `"trackHeuristics.tracks" must be an object`);
+            }
+            tracks = {};
+            for (const [trackName, ruleRaw] of Object.entries(tracksRaw)) {
+                if (!FLOW_TRACK_SET.has(trackName)) {
+                    throw configValidationError(fullPath, `"trackHeuristics.tracks" contains unknown track "${trackName}". Supported: ${SUPPORTED_TRACKS_TEXT}`);
+                }
+                if (!isRecord(ruleRaw)) {
+                    throw configValidationError(fullPath, `"trackHeuristics.tracks.${trackName}" must be an object`);
+                }
+                const triggers = validateStringArray(ruleRaw.triggers, `trackHeuristics.tracks.${trackName}.triggers`, fullPath);
+                const patterns = validateStringArray(ruleRaw.patterns, `trackHeuristics.tracks.${trackName}.patterns`, fullPath);
+                const veto = validateStringArray(ruleRaw.veto, `trackHeuristics.tracks.${trackName}.veto`, fullPath);
+                if (patterns) {
+                    for (const pattern of patterns) {
+                        try {
+                            // eslint-disable-next-line no-new
+                            new RegExp(pattern, "iu");
+                        }
+                        catch {
+                            throw configValidationError(fullPath, `"trackHeuristics.tracks.${trackName}.patterns" contains invalid regex "${pattern}"`);
+                        }
+                    }
+                }
+                tracks[trackName] = {
+                    triggers,
+                    patterns,
+                    veto
+                };
+            }
+        }
+        trackHeuristics = {
+            fallback: fallbackRaw,
+            priority,
+            tracks
+        };
+    }
     return {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
@@ -169,7 +248,8 @@ export async function readConfig(projectRoot) {
         promptGuardMode,
         gitHookGuards,
         defaultTrack,
-        languageRulePacks
+        languageRulePacks,
+        trackHeuristics
     };
 }
 export async function writeConfig(projectRoot, config) {

package/dist/content/core-agents.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Agent persona content for cclaw.
+ *
+ * cclaw materializes markdown agent definitions (`.md` with YAML frontmatter)
+ * under `.cclaw/agents/` for harness delegation. Research work that does not
+ * need isolated subagent context lives in `.cclaw/skills/research/*.md`
+ * playbooks and is executed in-thread by the primary agent.
+ */
+export interface AgentDefinition {
+    /** Kebab-case identifier, e.g. `"reviewer"`. */
+    name: string;
+    /** When to invoke — include PROACTIVE / MUST BE USED guidance. */
+    description: string;
+    /** Allowed tools for this agent (harness-specific names). */
+    tools: string[];
+    /** Model tier for routing cost/latency vs depth. */
+    model: "fast" | "balanced" | "deep";
+    /** How the harness should treat activation relative to flow context. */
+    activation: "proactive" | "on-demand" | "mandatory";
+    /** cclaw flow stages this agent is designed to support. */
+    relatedStages: string[];
+    /** Markdown body rendered below the YAML frontmatter. */
+    body: string;
+}
+/**
+ * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ */
+export declare const CCLAW_AGENTS: AgentDefinition[];
+/**
+ * Render a complete cclaw agent markdown file (YAML frontmatter + body).
+ */
+export declare function agentMarkdown(agent: AgentDefinition): string;
+/**
+ * Markdown table mapping cclaw stage entry points to specialist agents.
+ */
+export declare function agentRoutingTable(): string;
+/**
+ * Cost tier routing for the core-5 agent roster.
+ */
+export declare function agentCostTierTable(): string;
+/**
+ * AGENTS.md-ready section describing cclaw’s specialist delegation model.
+ */
+export declare function agentsAgentsMdBlock(): string;