cclaw-cli 0.51.30 → 1.0.0

package/dist/internal/compound-readiness.d.ts

@@ -5,7 +5,7 @@ interface InternalIo {
     stderr: Writable;
 }
 /**
- * Count archived runs as sub-directories under `.cclaw/runs/`. Missing
+ * Count archived runs as sub-directories under `.cclaw/archive/`. Missing
  * dir / ENOENT is interpreted as zero — callers should NOT conflate
  * that with "unknown" (undefined); we only return undefined on
  * unexpected errors so the caller can choose to skip the relaxation

package/dist/internal/compound-readiness.js

@@ -42,10 +42,10 @@ function stateDir(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state");
 }
 function archiveRunsDir(projectRoot) {
-    return path.join(projectRoot, RUNTIME_ROOT, "runs");
+    return path.join(projectRoot, RUNTIME_ROOT, "archive");
 }
 /**
- * Count archived runs as sub-directories under `.cclaw/runs/`. Missing
+ * Count archived runs as sub-directories under `.cclaw/archive/`. Missing
  * dir / ENOENT is interpreted as zero — callers should NOT conflate
  * that with "unknown" (undefined); we only return undefined on
  * unexpected errors so the caller can choose to skip the relaxation

package/dist/internal/early-loop-status.d.ts

@@ -0,0 +1,7 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function runEarlyLoopStatusCommand(projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};

package/dist/internal/early-loop-status.js

@@ -0,0 +1,90 @@
+import path from "node:path";
+import { readConfig } from "../config.js";
+import { RUNTIME_ROOT } from "../constants.js";
+import { computeEarlyLoopStatus, formatEarlyLoopStatusLine, isEarlyLoopStage } from "../early-loop.js";
+import { writeFileSafe } from "../fs-utils.js";
+import { readFlowState } from "../runs.js";
+function parseArgs(tokens) {
+    const args = { json: false, quiet: false, write: true };
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        const nextToken = tokens[index + 1];
+        if (token === "--json") {
+            args.json = true;
+            continue;
+        }
+        if (token === "--quiet") {
+            args.quiet = true;
+            continue;
+        }
+        if (token === "--write") {
+            args.write = true;
+            continue;
+        }
+        if (token === "--no-write") {
+            args.write = false;
+            continue;
+        }
+        if (token === "--stage") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--stage requires a value: brainstorm | scope | design");
+            }
+            if (!isEarlyLoopStage(nextToken)) {
+                throw new Error("--stage must be one of: brainstorm, scope, design");
+            }
+            args.stage = nextToken;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--stage=")) {
+            const stageRaw = token.slice("--stage=".length);
+            if (!isEarlyLoopStage(stageRaw)) {
+                throw new Error("--stage must be one of: brainstorm, scope, design");
+            }
+            args.stage = stageRaw;
+            continue;
+        }
+        if (token === "--run-id") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--run-id requires a value.");
+            }
+            args.runId = nextToken.trim();
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--run-id=")) {
+            args.runId = token.slice("--run-id=".length).trim();
+            continue;
+        }
+        throw new Error(`Unknown early-loop-status flag: ${token}`);
+    }
+    return args;
+}
+function stateDir(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state");
+}
+export async function runEarlyLoopStatusCommand(projectRoot, argv, io) {
+    const args = parseArgs(argv);
+    const flow = await readFlowState(projectRoot).catch(() => null);
+    const config = await readConfig(projectRoot).catch(() => null);
+    const stage = args.stage ?? flow?.currentStage;
+    if (!isEarlyLoopStage(stage)) {
+        io.stderr.write("cclaw internal early-loop-status: current stage is not an early-loop stage. Pass --stage=brainstorm|scope|design.\n");
+        return 1;
+    }
+    const runId = (args.runId ?? flow?.activeRunId ?? "active").trim() || "active";
+    const status = await computeEarlyLoopStatus(stage, runId, path.join(stateDir(projectRoot), "early-loop-log.jsonl"), { maxIterations: config?.earlyLoop?.maxIterations });
+    if (args.write) {
+        const target = path.join(stateDir(projectRoot), "early-loop.json");
+        await writeFileSafe(target, `${JSON.stringify(status, null, 2)}\n`);
+    }
+    if (!args.quiet) {
+        if (args.json) {
+            io.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+        }
+        else {
+            io.stdout.write(`${formatEarlyLoopStatusLine(status)}\n`);
+        }
+    }
+    return 0;
+}

package/dist/internal/runtime-integrity.d.ts

@@ -0,0 +1,7 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function runRuntimeIntegrityCommand(projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};

package/dist/internal/runtime-integrity.js

@@ -0,0 +1,288 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readConfig } from "../config.js";
+import { RUNTIME_ROOT } from "../constants.js";
+import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "../codex-feature-flag.js";
+import { exists } from "../fs-utils.js";
+import { HARNESS_ADAPTERS, harnessShimFileNames, harnessShimSkillNames } from "../harness-adapters.js";
+import { validateHookDocument } from "../hook-schema.js";
+import { MANAGED_RESOURCE_MANIFEST_REL_PATH, validateManagedResourceManifest } from "../managed-resources.js";
+import { CorruptFlowStateError, readFlowState } from "../runs.js";
+function parseArgs(tokens) {
+    const args = { json: false, quiet: false };
+    for (const token of tokens) {
+        if (token === "--json") {
+            args.json = true;
+            continue;
+        }
+        if (token === "--quiet") {
+            args.quiet = true;
+            continue;
+        }
+        throw new Error(`Unknown runtime-integrity flag: ${token}`);
+    }
+    return args;
+}
+function stripJsonCommentsOutsideStrings(input) {
+    let out = "";
+    let i = 0;
+    let inString = false;
+    let escape = false;
+    while (i < input.length) {
+        const c = input[i];
+        if (inString) {
+            out += c;
+            if (escape) {
+                escape = false;
+            }
+            else if (c === "\\") {
+                escape = true;
+            }
+            else if (c === "\"") {
+                inString = false;
+            }
+            i += 1;
+            continue;
+        }
+        if (c === "\"") {
+            inString = true;
+            out += c;
+            i += 1;
+            continue;
+        }
+        const next = input[i + 1];
+        if (c === "/" && next === "/") {
+            while (i < input.length && input[i] !== "\n" && input[i] !== "\r")
+                i += 1;
+            continue;
+        }
+        if (c === "/" && next === "*") {
+            i += 2;
+            while (i < input.length - 1 && !(input[i] === "*" && input[i + 1] === "/"))
+                i += 1;
+            i = Math.min(i + 2, input.length);
+            continue;
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+function parseJsonWithRecovery(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Continue with comment/trailing-comma recovery.
+    }
+    try {
+        const normalized = stripJsonCommentsOutsideStrings(raw).replace(/,\s*([}\]])/gu, "$1");
+        return JSON.parse(normalized);
+    }
+    catch {
+        return null;
+    }
+}
+function okFinding(id, message) {
+    return {
+        id,
+        severity: "error",
+        ok: true,
+        message
+    };
+}
+function errorFinding(id, message, details) {
+    return {
+        id,
+        severity: "error",
+        ok: false,
+        message,
+        ...(details && details.length > 0 ? { details } : {})
+    };
+}
+function warningFinding(id, ok, message, details) {
+    return {
+        id,
+        severity: "warning",
+        ok,
+        message,
+        ...(details && details.length > 0 ? { details } : {})
+    };
+}
+async function checkStaleSentinel(projectRoot) {
+    const sentinelPath = path.join(projectRoot, RUNTIME_ROOT, "state", ".init-in-progress");
+    if (!(await exists(sentinelPath))) {
+        return warningFinding("stale_init_sentinel", true, "No stale init sentinel detected.");
+    }
+    let startedAt = "unknown time";
+    try {
+        const raw = await fs.readFile(sentinelPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.startedAt === "string" && parsed.startedAt.trim().length > 0) {
+            startedAt = parsed.startedAt;
+        }
+    }
+    catch {
+        // best-effort parse only
+    }
+    return warningFinding("stale_init_sentinel", false, "Detected stale .init-in-progress sentinel from a previous interrupted sync/init run.", [`startedAt: ${startedAt}`, `path: ${sentinelPath}`]);
+}
+async function checkFlowState(projectRoot) {
+    try {
+        await readFlowState(projectRoot);
+        return okFinding("flow_state", "Flow state is readable.");
+    }
+    catch (error) {
+        if (error instanceof CorruptFlowStateError) {
+            return errorFinding("flow_state", "Corrupt flow-state detected.", [error.message]);
+        }
+        return errorFinding("flow_state", "Flow-state read failed.", [
+            error instanceof Error ? error.message : String(error)
+        ]);
+    }
+}
+async function checkManagedManifest(projectRoot) {
+    const manifestPath = path.join(projectRoot, MANAGED_RESOURCE_MANIFEST_REL_PATH);
+    if (!(await exists(manifestPath))) {
+        return errorFinding("managed_manifest", "Managed resource manifest is missing.", [`missing: ${manifestPath}`]);
+    }
+    const rawText = await fs.readFile(manifestPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (error) {
+        return errorFinding("managed_manifest", "Managed resource manifest is not valid JSON.", [error instanceof Error ? error.message : String(error)]);
+    }
+    const issues = validateManagedResourceManifest(parsed);
+    if (issues.length > 0) {
+        const detail = issues.slice(0, 12).map((issue) => {
+            const scope = issue.path ?? (issue.index !== undefined ? `resources[${issue.index}]` : "manifest");
+            return `${scope}.${issue.field}: ${issue.message}`;
+        });
+        return errorFinding("managed_manifest", "Managed resource manifest schema validation failed.", detail);
+    }
+    return okFinding("managed_manifest", "Managed resource manifest is valid.");
+}
+function hookFilePath(projectRoot, harness) {
+    if (harness === "claude")
+        return path.join(projectRoot, ".claude/hooks/hooks.json");
+    if (harness === "cursor")
+        return path.join(projectRoot, ".cursor/hooks.json");
+    return path.join(projectRoot, ".codex/hooks.json");
+}
+async function checkHookDocument(projectRoot, harness) {
+    const hookPath = hookFilePath(projectRoot, harness);
+    if (!(await exists(hookPath))) {
+        return errorFinding(`hook_document_${harness}`, `Hook document is missing for ${harness}.`, [`missing: ${hookPath}`]);
+    }
+    const raw = await fs.readFile(hookPath, "utf8");
+    const parsed = parseJsonWithRecovery(raw);
+    if (parsed === null) {
+        return errorFinding(`hook_document_${harness}`, `Hook document for ${harness} is unparseable JSON.`, [`path: ${hookPath}`]);
+    }
+    const validation = validateHookDocument(harness, parsed);
+    if (!validation.ok) {
+        return errorFinding(`hook_document_${harness}`, `Hook document for ${harness} is invalid.`, validation.errors);
+    }
+    return okFinding(`hook_document_${harness}`, `Hook document for ${harness} is valid.`);
+}
+async function checkHarnessShims(projectRoot, harnesses) {
+    const findings = [];
+    const expectedFiles = harnessShimFileNames();
+    const expectedSkillFolders = harnessShimSkillNames();
+    for (const harness of harnesses) {
+        const adapter = HARNESS_ADAPTERS[harness];
+        const base = path.join(projectRoot, adapter.commandDir);
+        const missing = [];
+        for (const fileName of expectedFiles) {
+            const target = adapter.shimKind === "skill"
+                ? path.join(base, fileName.replace(/\.md$/u, ""), "SKILL.md")
+                : path.join(base, fileName);
+            if (!(await exists(target))) {
+                missing.push(target);
+            }
+        }
+        if (adapter.shimKind === "skill") {
+            for (const folder of expectedSkillFolders) {
+                const target = path.join(base, folder, "SKILL.md");
+                if (!(await exists(target))) {
+                    missing.push(target);
+                }
+            }
+        }
+        if (missing.length > 0) {
+            findings.push(errorFinding(`shim_drift_${harness}`, `Harness shim drift detected for ${harness}.`, missing));
+        }
+        else {
+            findings.push(okFinding(`shim_drift_${harness}`, `Harness shims for ${harness} are present.`));
+        }
+    }
+    return findings;
+}
+async function checkCodexHooksFlag(harnesses) {
+    if (!harnesses.includes("codex")) {
+        return warningFinding("codex_hooks_flag", true, "Codex harness is not enabled.");
+    }
+    const configTomlPath = codexConfigPath();
+    let existing;
+    try {
+        existing = await readCodexConfig(configTomlPath);
+    }
+    catch (error) {
+        return warningFinding("codex_hooks_flag", false, "Could not read Codex config.toml to validate codex_hooks.", [error instanceof Error ? error.message : String(error)]);
+    }
+    const state = classifyCodexHooksFlag(existing);
+    if (state === "enabled") {
+        return warningFinding("codex_hooks_flag", true, "Codex hooks feature flag is enabled.");
+    }
+    return warningFinding("codex_hooks_flag", false, "Codex hooks file is present, but [features] codex_hooks is not true in Codex config.", [`configPath: ${configTomlPath}`, `state: ${state}`]);
+}
+function buildReport(findings) {
+    const errors = findings.filter((finding) => !finding.ok && finding.severity === "error").length;
+    const warnings = findings.filter((finding) => !finding.ok && finding.severity === "warning").length;
+    return {
+        ok: errors === 0,
+        generatedAt: new Date().toISOString(),
+        findings,
+        summary: { errors, warnings }
+    };
+}
+function writeTextReport(io, report) {
+    io.stdout.write(`runtime-integrity: ${report.ok ? "ok" : "failed"}\n`);
+    io.stdout.write(`errors=${report.summary.errors} warnings=${report.summary.warnings}\n`);
+    for (const finding of report.findings) {
+        if (finding.ok)
+            continue;
+        io.stdout.write(`[${finding.severity}] ${finding.id}: ${finding.message}\n`);
+        for (const detail of finding.details ?? []) {
+            io.stdout.write(`  - ${detail}\n`);
+        }
+    }
+}
+export async function runRuntimeIntegrityCommand(projectRoot, argv, io) {
+    const args = parseArgs(argv);
+    const config = await readConfig(projectRoot);
+    const harnesses = config.harnesses;
+    const findings = [];
+    findings.push(await checkStaleSentinel(projectRoot));
+    findings.push(await checkFlowState(projectRoot));
+    findings.push(await checkManagedManifest(projectRoot));
+    findings.push(...await checkHarnessShims(projectRoot, harnesses));
+    for (const harness of harnesses) {
+        if (harness === "claude" || harness === "cursor" || harness === "codex") {
+            findings.push(await checkHookDocument(projectRoot, harness));
+        }
+    }
+    findings.push(await checkCodexHooksFlag(harnesses));
+    const report = buildReport(findings);
+    if (!args.quiet) {
+        if (args.json) {
+            io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        }
+        else {
+            writeTextReport(io, report);
+        }
+    }
+    return report.ok ? 0 : 1;
+}

package/dist/internal/tdd-red-evidence.js

@@ -95,7 +95,7 @@ export async function runTddRedEvidenceCommand(projectRoot, tokens, io) {
     if (!effectiveRunId || effectiveRunId.trim().length === 0) {
         const reason = "tdd-red-evidence: cannot scope check — no --runId provided and " +
             "flow-state.json has no activeRunId. Pass --runId=<id> explicitly " +
-            "or run `cclaw doctor` to reconcile state.";
+            "or run `npx cclaw-cli sync` to reconcile state.";
         if (!args.quiet) {
             io.stdout.write(`${JSON.stringify({
                 ok: false,

package/dist/knowledge-store.d.ts

@@ -2,29 +2,21 @@ import { type FlowStage } from "./types.js";
 export type KnowledgeEntryType = "rule" | "pattern" | "lesson" | "compound";
 export type KnowledgeEntryConfidence = "high" | "medium" | "low";
 export type KnowledgeEntrySeverity = "critical" | "important" | "suggestion";
-export type KnowledgeEntryUniversality = "project" | "personal" | "universal";
-export type KnowledgeEntryMaturity = "raw" | "lifted-to-rule" | "lifted-to-enforcement";
-export type KnowledgeEntrySource = "stage" | "retro" | "compound" | "ideate" | "manual";
+export type KnowledgeEntrySource = "stage" | "retro" | "compound" | "idea" | "manual";
 export interface KnowledgeEntry {
     type: KnowledgeEntryType;
     trigger: string;
     action: string;
     confidence: KnowledgeEntryConfidence;
     severity?: KnowledgeEntrySeverity;
-    domain: string | null;
     stage: FlowStage | null;
     origin_stage: FlowStage | null;
-    origin_run: string | null;
     frequency: number;
-    universality: KnowledgeEntryUniversality;
-    maturity: KnowledgeEntryMaturity;
     created: string;
     first_seen_ts: string;
     last_seen_ts: string;
     project: string | null;
     source?: KnowledgeEntrySource | null;
-    supersedes?: string[];
-    superseded_by?: string;
 }
 export interface KnowledgeSeedEntry {
     type: KnowledgeEntryType;
@@ -32,27 +24,18 @@ export interface KnowledgeSeedEntry {
     action: string;
     confidence: KnowledgeEntryConfidence;
     severity?: KnowledgeEntrySeverity;
-    domain?: string | null;
     stage?: FlowStage | null;
     origin_stage?: FlowStage | null;
-    origin_run?: string | null;
-    /** @deprecated Use `origin_run`. Accepted only for legacy JSONL/backfill inputs. */
-    origin_feature?: string | null;
     frequency?: number;
-    universality?: KnowledgeEntryUniversality;
-    maturity?: KnowledgeEntryMaturity;
     created?: string;
     first_seen_ts?: string;
     last_seen_ts?: string;
     project?: string | null;
     source?: KnowledgeEntrySource | null;
-    supersedes?: string[];
-    superseded_by?: string;
 }
 export interface AppendKnowledgeDefaults {
     stage?: FlowStage | null;
     originStage?: FlowStage | null;
-    originRun?: string | null;
     project?: string | null;
     source?: KnowledgeEntrySource | null;
     nowIso?: string;
@@ -100,8 +83,6 @@ export interface CompoundReadinessCluster {
     lastSeenTs: string;
     /** Entry types observed (rule/pattern/lesson/compound). */
     types: KnowledgeEntryType[];
-    /** Distinct maturity values observed across the cluster. */
-    maturity: KnowledgeEntryMaturity[];
 }
 export interface CompoundReadiness {
     schemaVersion: 2;
@@ -143,7 +124,7 @@ export interface ComputeCompoundReadinessOptions {
     maxReady?: number;
     now?: Date;
     /**
-     * Count of archived runs under `.cclaw/runs/`. When supplied and
+     * Count of archived runs under `.cclaw/archive/`. When supplied and
      * `< SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD`, the effective threshold
      * is lowered to `min(threshold, SMALL_PROJECT_RECURRENCE_THRESHOLD)`.
      * Matches the rule documented in `docs/config.md`.
@@ -169,15 +150,11 @@ export declare function effectiveCompoundThreshold(baseThreshold: number, archiv
  *
  * Clustering key: `(type, normalizeText(trigger), normalizeText(action))`
  * which mirrors the compound readiness clustering in runtime state.
- * Entries with `maturity === "lifted-to-enforcement"` or `superseded_by`
- * are excluded — they were already promoted/replaced and should not re-appear
- * as ready.
+ * The readiness surface intentionally stays simple: no maturity/supersede
+ * suppression logic in this pass.
  */
 export declare function computeCompoundReadiness(entries: KnowledgeEntry[], options?: ComputeCompoundReadinessOptions): CompoundReadiness;
-export interface ValidateKnowledgeEntryOptions {
-    allowLegacyOriginFeature?: boolean;
-}
-export declare function validateKnowledgeEntry(entry: unknown, options?: ValidateKnowledgeEntryOptions): {
+export declare function validateKnowledgeEntry(entry: unknown): {
     ok: boolean;
     errors: string[];
 };