cclaw-cli 0.1.0

package/dist/learnings-summarizer.js

@@ -0,0 +1,201 @@
+const ERROR_PATTERN = /(error|fail|timeout|exception)/iu;
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+function parseJsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function toText(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "";
+    }
+}
+function asValidLearning(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const obj = value;
+    const ts = obj.ts;
+    const skill = obj.skill;
+    const type = obj.type;
+    const key = obj.key;
+    const insight = obj.insight;
+    const confidence = obj.confidence;
+    const source = obj.source;
+    if (typeof ts !== "string" || !ts)
+        return null;
+    if (typeof skill !== "string" || !skill)
+        return null;
+    if (type !== "pitfall" && type !== "pattern" && type !== "preference")
+        return null;
+    if (typeof key !== "string" || !KEY_PATTERN.test(key))
+        return null;
+    if (typeof insight !== "string" || insight.trim().length < 16)
+        return null;
+    if (typeof confidence !== "number" || !Number.isInteger(confidence) || confidence < 1 || confidence > 10)
+        return null;
+    if (source !== "observed" && source !== "user-stated" && source !== "inferred")
+        return null;
+    return {
+        ts,
+        skill,
+        type,
+        key,
+        insight,
+        confidence,
+        source
+    };
+}
+function normalizeToken(value) {
+    const normalized = value.trim().replace(/[^A-Za-z0-9._-]+/gu, "-");
+    return normalized.replace(/^-+/u, "").replace(/-+$/u, "") || "unknown";
+}
+function maybeObservation(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const obj = value;
+    return {
+        ts: typeof obj.ts === "string" ? obj.ts : undefined,
+        event: typeof obj.event === "string" ? obj.event : undefined,
+        tool: typeof obj.tool === "string" ? obj.tool : undefined,
+        phase: typeof obj.phase === "string" ? obj.phase : undefined,
+        stage: typeof obj.stage === "string" ? obj.stage : undefined,
+        runId: typeof obj.runId === "string" ? obj.runId : undefined,
+        data: obj.data
+    };
+}
+function bestByConfidence(candidates) {
+    const table = new Map();
+    for (const candidate of candidates) {
+        const token = `${candidate.key}:${candidate.type}`;
+        const current = table.get(token);
+        if (!current || candidate.confidence > current.confidence) {
+            table.set(token, candidate);
+        }
+    }
+    return Array.from(table.values());
+}
+function buildCandidates(observations, timestamp) {
+    const toolUsage = new Map();
+    const toolErrors = new Map();
+    const stageErrors = new Map();
+    const longPayload = new Map();
+    for (const obs of observations) {
+        const tool = normalizeToken(obs.tool ?? "unknown");
+        const stage = normalizeToken(obs.stage ?? "none");
+        const payload = toText(obs.data);
+        toolUsage.set(tool, (toolUsage.get(tool) ?? 0) + 1);
+        if (payload.length >= 1500) {
+            longPayload.set(tool, (longPayload.get(tool) ?? 0) + 1);
+        }
+        if ((obs.event ?? "") === "tool_complete" && ERROR_PATTERN.test(payload)) {
+            toolErrors.set(tool, (toolErrors.get(tool) ?? 0) + 1);
+            stageErrors.set(stage, (stageErrors.get(stage) ?? 0) + 1);
+        }
+    }
+    const candidates = [];
+    for (const [tool, errors] of toolErrors.entries()) {
+        if (errors < 3)
+            continue;
+        candidates.push({
+            ts: timestamp,
+            skill: "observation",
+            type: "pitfall",
+            key: `frequent-errors-${tool}`,
+            insight: `Tool ${tool} produced ${errors} error-like completions in a single session; add a preflight checklist before using it.`,
+            confidence: Math.min(9, 4 + Math.floor(errors / 2)),
+            source: "observed"
+        });
+    }
+    for (const [tool, total] of toolUsage.entries()) {
+        if (total < 8)
+            continue;
+        const errors = toolErrors.get(tool) ?? 0;
+        if (errors > Math.max(1, Math.floor(total * 0.15)))
+            continue;
+        candidates.push({
+            ts: timestamp,
+            skill: "observation",
+            type: "pattern",
+            key: `reliable-tool-${tool}`,
+            insight: `Tool ${tool} was used ${total} times with low failure rate; prefer it as a first option for similar tasks.`,
+            confidence: Math.min(8, 3 + Math.floor(total / 3)),
+            source: "observed"
+        });
+    }
+    for (const [stage, errors] of stageErrors.entries()) {
+        if (stage === "none" || errors < 4)
+            continue;
+        candidates.push({
+            ts: timestamp,
+            skill: "observation",
+            type: "pitfall",
+            key: `stage-hotspot-${stage}`,
+            insight: `Stage ${stage} produced ${errors} error-like tool completions in one session; add stage-specific checks before execution.`,
+            confidence: Math.min(8, 3 + Math.floor(errors / 2)),
+            source: "observed"
+        });
+    }
+    for (const [tool, count] of longPayload.entries()) {
+        if (count < 3)
+            continue;
+        candidates.push({
+            ts: timestamp,
+            skill: "observation",
+            type: "preference",
+            key: `truncate-heavy-payloads-${tool}`,
+            insight: `Tool ${tool} produced large payloads repeatedly; summarize outputs earlier to avoid context pressure.`,
+            confidence: Math.min(7, 3 + Math.floor(count / 2)),
+            source: "observed"
+        });
+    }
+    return bestByConfidence(candidates).filter((entry) => asValidLearning(entry) !== null);
+}
+function appendableCandidates(existing, candidates) {
+    const bestExisting = new Map();
+    for (const entry of existing) {
+        const token = `${entry.key}:${entry.type}`;
+        const current = bestExisting.get(token) ?? 0;
+        if (entry.confidence > current)
+            bestExisting.set(token, entry.confidence);
+    }
+    const appendable = [];
+    for (const candidate of candidates) {
+        const token = `${candidate.key}:${candidate.type}`;
+        const current = bestExisting.get(token) ?? 0;
+        if (candidate.confidence > current) {
+            appendable.push(candidate);
+            bestExisting.set(token, candidate.confidence);
+        }
+    }
+    return appendable;
+}
+export function summarizeObservationLearnings(observationJsonl, existingLearningsJsonl, timestamp) {
+    const observations = observationJsonl
+        .split(/\r?\n/gu)
+        .map(parseJsonLine)
+        .filter((value) => value !== null)
+        .map(maybeObservation)
+        .filter((value) => value !== null);
+    const existing = existingLearningsJsonl
+        .split(/\r?\n/gu)
+        .map(parseJsonLine)
+        .map((value) => (value ? asValidLearning(value) : null))
+        .filter((value) => value !== null);
+    const candidates = buildCandidates(observations, timestamp);
+    const appendable = appendableCandidates(existing, candidates);
+    return { candidates, appendable };
+}

package/dist/logger.d.ts

@@ -0,0 +1,3 @@
+import type { CliContext } from "./types.js";
+export declare function info(ctx: CliContext, message: string): void;
+export declare function error(ctx: CliContext, message: string): void;

package/dist/logger.js

@@ -0,0 +1,6 @@
+export function info(ctx, message) {
+    ctx.stdout.write(`[cclaw] ${message}\n`);
+}
+export function error(ctx, message) {
+    ctx.stderr.write(`[cclaw:error] ${message}\n`);
+}

package/dist/policy.d.ts

@@ -0,0 +1,6 @@
+export interface PolicyCheck {
+    name: string;
+    ok: boolean;
+    details: string;
+}
+export declare function policyChecks(projectRoot: string): Promise<PolicyCheck[]>;

package/dist/policy.js

@@ -0,0 +1,179 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
+import { stageSchema, stagePolicyNeedles } from "./content/stage-schema.js";
+import { stageSkillFolder } from "./content/skills.js";
+import { exists } from "./fs-utils.js";
+const POLICY_RULES = [];
+export async function policyChecks(projectRoot) {
+    const checks = [];
+    const rules = [...POLICY_RULES];
+    for (const stage of COMMAND_FILE_ORDER) {
+        const folder = stageSkillFolder(stage);
+        const schema = stageSchema(stage);
+        const commandFile = `${RUNTIME_ROOT}/commands/${stage}.md`;
+        const skillFile = `${RUNTIME_ROOT}/skills/${folder}/SKILL.md`;
+        // --- thin command mandatory sections ---
+        for (const heading of [
+            "## HARD-GATE",
+            "## Gates",
+            "## Exit",
+            "## Anchors",
+            "## Context Hydration"
+        ]) {
+            rules.push({
+                filePath: commandFile,
+                needle: heading,
+                name: `command:${stage}:section:${heading.replace(/^## /, "").toLowerCase().replace(/[^a-z0-9]+/g, "_")}`
+            });
+        }
+        // --- command must reference the skill ---
+        rules.push({
+            filePath: commandFile,
+            needle: `${folder}/SKILL.md`,
+            name: `command:${stage}:skill_ref`
+        });
+        // --- skill mandatory sections ---
+        for (const heading of [
+            "## Process",
+            "## Verification",
+            "## Interaction Protocol",
+            "## Common Rationalizations",
+            "## Red Flags",
+            "## HARD-GATE",
+            "## Checklist",
+            "## Context Loading",
+            "## Automatic Subagent Dispatch",
+            "## Cognitive Patterns",
+            "## Cross-Stage Traceability",
+            "## Completion Status",
+            "## Artifact Validation"
+        ]) {
+            rules.push({
+                filePath: skillFile,
+                needle: heading,
+                name: `skill:${stage}:section:${heading.replace(/^## /, "").toLowerCase().replace(/[^a-z0-9]+/g, "_")}`
+            });
+        }
+        // --- gate IDs in skills ---
+        for (const gate of schema.requiredGates) {
+            rules.push({
+                filePath: skillFile,
+                needle: `\`${gate.id}\``,
+                name: `skill:${stage}:gate:${gate.id}`
+            });
+        }
+        // --- verification section for build/review/ship skills ---
+        if (["build", "review", "ship"].includes(stage)) {
+            rules.push({
+                filePath: skillFile,
+                needle: "## Verification Before Completion",
+                name: `skill:${stage}:section:verification_before_completion`
+            });
+        }
+        // --- policy needles in commands ---
+        for (const needle of stagePolicyNeedles(stage)) {
+            rules.push({
+                filePath: commandFile,
+                needle,
+                name: `command:${stage}:anchor:${needle.toLowerCase().replace(/[^a-z0-9]+/g, "_")}`
+            });
+        }
+    }
+    // --- utility skill checks ---
+    const runtimeFile = (relativePath) => `${RUNTIME_ROOT}/${relativePath}`;
+    const utilitySkillChecks = [
+        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Learning Entry Schema", name: "utility_skill:learnings:schema" },
+        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Subcommands", name: "utility_skill:learnings:subcommands" },
+        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Confidence Decay", name: "utility_skill:learnings:decay" },
+        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:learnings:hard_gate" },
+        { file: runtimeFile("skills/autoplan/SKILL.md"), needle: "## Phase Sequence", name: "utility_skill:autoplan:phases" },
+        { file: runtimeFile("skills/autoplan/SKILL.md"), needle: "Decision Principles", name: "utility_skill:autoplan:principles" },
+        { file: runtimeFile("skills/autoplan/SKILL.md"), needle: "## Decision Taxonomy", name: "utility_skill:autoplan:taxonomy" },
+        { file: runtimeFile("skills/autoplan/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:autoplan:hard_gate" },
+        { file: runtimeFile("skills/autoplan/SKILL.md"), needle: "## Restore Points", name: "utility_skill:autoplan:restore_points" },
+        { file: runtimeFile("commands/learn.md"), needle: "## Subcommands", name: "utility_command:learn:subcommands" },
+        { file: runtimeFile("commands/autoplan.md"), needle: "## Phase Sequence", name: "utility_command:autoplan:phases" },
+        { file: runtimeFile("commands/autoplan.md"), needle: "## Decision Principles", name: "utility_command:autoplan:principles" },
+        { file: runtimeFile("skills/subagent-dev/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:sdd:hard_gate" },
+        { file: runtimeFile("skills/subagent-dev/SKILL.md"), needle: "## Status Contract", name: "utility_skill:sdd:status_contract" },
+        { file: runtimeFile("skills/subagent-dev/SKILL.md"), needle: "Implementer", name: "utility_skill:sdd:implementer_template" },
+        { file: runtimeFile("skills/parallel-dispatch/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:parallel:hard_gate" },
+        { file: runtimeFile("skills/parallel-dispatch/SKILL.md"), needle: "Review Army", name: "utility_skill:parallel:review_army" },
+        { file: runtimeFile("skills/parallel-dispatch/SKILL.md"), needle: "Reconciliation", name: "utility_skill:parallel:reconciliation" },
+        { file: runtimeFile("skills/session/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:session:hard_gate" },
+        { file: runtimeFile("skills/session/SKILL.md"), needle: "## Session Start Protocol", name: "utility_skill:session:start" },
+        { file: runtimeFile("skills/session/SKILL.md"), needle: "## Session Stop Protocol", name: "utility_skill:session:stop" },
+        { file: runtimeFile("skills/using-cclaw/SKILL.md"), needle: "## Skill Discovery Flowchart", name: "meta_skill:discovery" },
+        { file: runtimeFile("skills/using-cclaw/SKILL.md"), needle: "## Activation Rules", name: "meta_skill:activation" },
+        { file: runtimeFile("skills/using-cclaw/SKILL.md"), needle: "## Stage Quick Reference", name: "meta_skill:reference" },
+        { file: runtimeFile("skills/using-cclaw/SKILL.md"), needle: "## Failure Modes", name: "meta_skill:failure_modes" },
+        { file: runtimeFile("skills/using-cclaw/SKILL.md"), needle: "## Contextual Skills", name: "meta_skill:contextual_skills" },
+        { file: runtimeFile("skills/using-cclaw/SKILL.md"), needle: "## Decision Protocol", name: "meta_skill:decision_protocol" },
+        { file: runtimeFile("skills/session/SKILL.md"), needle: "## Session Resume Protocol", name: "utility_skill:session:resume" },
+        { file: runtimeFile("skills/security/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:security:hard_gate" },
+        { file: runtimeFile("skills/security/SKILL.md"), needle: "## Checklist", name: "utility_skill:security:checklist" },
+        { file: runtimeFile("skills/security/SKILL.md"), needle: "## Severity Classification", name: "utility_skill:security:severity" },
+        { file: runtimeFile("skills/debugging/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:debugging:hard_gate" },
+        { file: runtimeFile("skills/debugging/SKILL.md"), needle: "## The Protocol", name: "utility_skill:debugging:protocol" },
+        { file: runtimeFile("skills/debugging/SKILL.md"), needle: "Step 1 — Reproduce", name: "utility_skill:debugging:reproduce" },
+        { file: runtimeFile("skills/performance/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:performance:hard_gate" },
+        { file: runtimeFile("skills/performance/SKILL.md"), needle: "## Workflow", name: "utility_skill:performance:workflow" },
+        { file: runtimeFile("skills/performance/SKILL.md"), needle: "## Core Web Vitals Reference", name: "utility_skill:performance:cwv" },
+        { file: runtimeFile("skills/ci-cd/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:cicd:hard_gate" },
+        { file: runtimeFile("skills/ci-cd/SKILL.md"), needle: "## Quality Gate Pipeline", name: "utility_skill:cicd:pipeline" },
+        { file: runtimeFile("skills/ci-cd/SKILL.md"), needle: "## CI Debugging Protocol", name: "utility_skill:cicd:debugging" },
+        { file: runtimeFile("skills/docs/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:docs:hard_gate" },
+        { file: runtimeFile("skills/docs/SKILL.md"), needle: "## ADR (Architecture Decision Record)", name: "utility_skill:docs:adr" },
+        { file: runtimeFile("skills/docs/SKILL.md"), needle: "## README Guidance", name: "utility_skill:docs:readme" },
+        { file: runtimeFile("hooks/session-start.sh"), needle: "ACTIVE_RUN=", name: "hooks:session_start:active_run" },
+        { file: runtimeFile("hooks/session-start.sh"), needle: "checkpoint.json", name: "hooks:session_start:checkpoint_ref" },
+        { file: runtimeFile("hooks/session-start.sh"), needle: "stage-activity.jsonl", name: "hooks:session_start:activity_ref" },
+        { file: runtimeFile("hooks/session-start.sh"), needle: "suggestion-memory.json", name: "hooks:session_start:suggestion_memory" },
+        { file: runtimeFile("hooks/session-start.sh"), needle: "context-warnings.jsonl", name: "hooks:session_start:context_warning_ref" },
+        { file: runtimeFile("hooks/stop-checkpoint.sh"), needle: "checkpoint.json", name: "hooks:stop:checkpoint_write" },
+        { file: runtimeFile("hooks/prompt-guard.sh"), needle: "write_to_cclaw_runtime", name: "hooks:guard:risky_write_advisory" },
+        { file: runtimeFile("hooks/context-monitor.sh"), needle: "remaining is", name: "hooks:context:threshold_warning" },
+        { file: runtimeFile("hooks/observe.sh"), needle: "stage-activity.jsonl", name: "hooks:observe:activity_write" },
+        { file: runtimeFile("hooks/summarize-observations.mjs"), needle: "frequent-errors-", name: "hooks:summarize:runtime_module" },
+        { file: runtimeFile("hooks/opencode-plugin.mjs"), needle: "activeRunId", name: "hooks:opencode:active_run" }
+    ];
+    for (const check of utilitySkillChecks) {
+        rules.push({
+            filePath: check.file,
+            needle: check.needle,
+            name: check.name
+        });
+    }
+    const contentCache = new Map();
+    const readCached = async (filePath) => {
+        if (contentCache.has(filePath)) {
+            return contentCache.get(filePath) ?? null;
+        }
+        if (!(await exists(filePath))) {
+            contentCache.set(filePath, null);
+            return null;
+        }
+        const content = await fs.readFile(filePath, "utf8");
+        contentCache.set(filePath, content);
+        return content;
+    };
+    for (const rule of rules) {
+        const filePath = path.join(projectRoot, rule.filePath);
+        const content = await readCached(filePath);
+        if (content === null) {
+            checks.push({
+                name: rule.name,
+                ok: false,
+                details: `${filePath} not found`
+            });
+            continue;
+        }
+        checks.push({
+            name: rule.name,
+            ok: content.includes(rule.needle),
+            details: `expect "${rule.needle}" in ${filePath}`
+        });
+    }
+    return checks;
+}

package/dist/runs.d.ts

@@ -0,0 +1,18 @@
+import { type FlowState } from "./flow-state.js";
+export interface CclawRunMeta {
+    id: string;
+    title: string;
+    createdAt: string;
+    archivedAt?: string;
+    stateSnapshot?: Omit<FlowState, "activeRunId">;
+}
+export declare function readFlowState(projectRoot: string): Promise<FlowState>;
+export declare function writeFlowState(projectRoot: string, state: FlowState): Promise<void>;
+export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
+export declare function ensureRunSystem(projectRoot: string): Promise<FlowState>;
+export declare function startNewFeatureRun(projectRoot: string, title?: string): Promise<CclawRunMeta>;
+export declare function resumeRun(projectRoot: string, runId: string): Promise<CclawRunMeta>;
+export declare function archiveRun(projectRoot: string, runId?: string): Promise<{
+    archived: CclawRunMeta;
+    active: CclawRunMeta;
+}>;