cclaw-cli 7.7.1 → 8.1.0

package/dist/tdd-cycle.d.ts

@@ -1,107 +0,0 @@
-export type TddCyclePhase = "red" | "green" | "refactor";
-export interface TddCycleEntry {
-    ts: string;
-    runId: string;
-    stage: string;
-    slice: string;
-    phase: TddCyclePhase;
-    command: string;
-    files?: string[];
-    exitCode?: number;
-    note?: string;
-    /**
-     * Optional acceptance-criterion IDs this log line relates to (e.g. `["AC-1"]`).
-     * Used by the Ralph Loop status summary to surface how many ACs have been
-     * closed by a GREEN cycle without forcing the user to track them manually.
-     */
-    acIds?: string[];
-}
-export interface TddCycleValidation {
-    ok: boolean;
-    issues: string[];
-    openRedSlices: string[];
-    sliceCount: number;
-}
-export interface TddCycleParseIssue {
-    lineNumber: number;
-    reason: string;
-    rawLine: string;
-}
-export interface ParseTddCycleLogOptions {
-    /**
-     * Collect one issue per dropped/malformed line. Callers that care
-     * (sync/runtime checks, red-evidence) can surface them; hooks keep soft-fail.
-     */
-    issues?: TddCycleParseIssue[];
-    /**
-     * When true, reject lines that omit required fields instead of
-     * back-filling them with defaults. Used by validation paths
-     * (`validateTddCycleOrder`, `npx cclaw-cli sync` fail-fast) to avoid silently
-     * bucketing unscoped rows into "runId=active, stage=tdd". Soft paths
-     * (generated hooks) keep the legacy defaults so a half-written file
-     * never takes the session down.
-     */
-    strict?: boolean;
-}
-export declare function parseTddCycleLog(text: string, options?: ParseTddCycleLogOptions): TddCycleEntry[];
-export declare function validateTddCycleOrder(entries: TddCycleEntry[], options?: {
-    runId?: string;
-}): TddCycleValidation;
-/**
- * Canonical path normalization used by ALL TDD path-matching layers
- * (cycle-log analysis, internal CLI `tdd-red-evidence`, and the
- * inline runtime hook). Previously each layer had its own near-copy,
- * which produced subtle drift (e.g. `./src/app.ts` vs `src/app.ts`
- * differing between hook and CLI). Keep this function in one place
- * so all callers agree.
- */
-export declare function normalizeTddPath(value: string): string;
-/**
- * Shared "does the recorded file path refer to the target" matcher.
- * Uses canonical normalization plus the traditional `endsWith('/'+x)`
- * rule so a recorded `src/app.ts` matches either `src/app.ts` or
- * `subdir/src/app.ts` but NOT `src/app.test.ts`. All TDD path checks
- * MUST go through this helper.
- */
-export declare function pathMatchesTarget(candidate: string, target: string): boolean;
-export interface RalphLoopSliceState {
-    slice: string;
-    redCount: number;
-    greenCount: number;
-    refactorCount: number;
-    redOpen: boolean;
-    acIds: string[];
-}
-export interface RalphLoopStatus {
-    schemaVersion: 1;
-    runId: string;
-    /**
-     * Number of RED -> GREEN cycles observed for the run — a rough "Ralph Loop"
-     * iteration counter that mirrors how many passing tests the loop has
-     * delivered so far.
-     */
-    loopIteration: number;
-    redOpen: boolean;
-    redOpenSlices: string[];
-    acClosed: string[];
-    sliceCount: number;
-    slices: RalphLoopSliceState[];
-    lastUpdatedAt: string;
-}
-/**
- * Derive a lightweight Ralph Loop summary from parsed tdd-cycle-log entries.
- * The goal is to give the model a single source of truth for "am I done
- * iterating?" — it collapses per-slice progress and distinct closed AC IDs
- * (from GREEN rows) into a single artifact the progression contract reads.
- */
-export declare function computeRalphLoopStatus(entries: TddCycleEntry[], options?: {
-    runId?: string;
-    now?: Date;
-}): RalphLoopStatus;
-/**
- * Checks whether the log contains a failing RED record associated with
- * `productionPath` for the active run.
- */
-export declare function hasFailingTestForPath(entries: TddCycleEntry[], productionPath: string, options?: {
-    runId?: string;
-}): boolean;

package/dist/tdd-cycle.js

@@ -1,289 +0,0 @@
-import { isSliceId } from "./util/slice-id.js";
-export function parseTddCycleLog(text, options = {}) {
-    const issues = options.issues;
-    const strict = options.strict === true;
-    const out = [];
-    // Strip a leading UTF-8 BOM on the whole blob so the first line parses
-    // cleanly; `trim()` handles BOM on subsequent lines through the same
-    // codepath (empty/whitespace-only lines are skipped).
-    const normalized = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-    const lines = normalized.split(/\r?\n/);
-    for (let index = 0; index < lines.length; index += 1) {
-        const raw = lines[index] ?? "";
-        const line = raw.trim();
-        if (!line)
-            continue;
-        const lineNumber = index + 1;
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-        }
-        catch (err) {
-            issues?.push({
-                lineNumber,
-                reason: `json-parse-failed: ${err instanceof Error ? err.message : String(err)}`,
-                rawLine: raw
-            });
-            continue;
-        }
-        const phase = parsed.phase;
-        if (phase !== "red" && phase !== "green" && phase !== "refactor") {
-            issues?.push({
-                lineNumber,
-                reason: `invalid-phase: ${JSON.stringify(parsed.phase)}`,
-                rawLine: raw
-            });
-            continue;
-        }
-        const runIdField = typeof parsed.runId === "string" ? parsed.runId : null;
-        const stageField = typeof parsed.stage === "string" ? parsed.stage : null;
-        const sliceField = typeof parsed.slice === "string" ? parsed.slice : null;
-        if (strict) {
-            const missing = [];
-            if (!runIdField)
-                missing.push("runId");
-            if (!stageField)
-                missing.push("stage");
-            if (!sliceField)
-                missing.push("slice");
-            if (missing.length > 0) {
-                issues?.push({
-                    lineNumber,
-                    reason: `missing-required-fields: ${missing.join(",")}`,
-                    rawLine: raw
-                });
-                continue;
-            }
-        }
-        const entry = {
-            ts: typeof parsed.ts === "string" ? parsed.ts : "",
-            runId: runIdField ?? "active",
-            stage: stageField ?? "tdd",
-            slice: sliceField ?? "S-unknown",
-            phase,
-            command: typeof parsed.command === "string" ? parsed.command : "",
-            files: Array.isArray(parsed.files)
-                ? parsed.files.filter((item) => typeof item === "string")
-                : undefined,
-            exitCode: typeof parsed.exitCode === "number" ? parsed.exitCode : undefined,
-            note: typeof parsed.note === "string" ? parsed.note : undefined,
-            acIds: Array.isArray(parsed.acIds)
-                ? parsed.acIds
-                    .filter((item) => typeof item === "string" && item.length > 0)
-                : undefined
-        };
-        out.push(entry);
-    }
-    return out;
-}
-export function validateTddCycleOrder(entries, options = {}) {
-    const targetRun = options.runId;
-    const filtered = targetRun
-        ? entries.filter((entry) => entry.runId === targetRun)
-        : entries;
-    const bySlice = new Map();
-    for (const entry of filtered) {
-        const list = bySlice.get(entry.slice) ?? [];
-        list.push(entry);
-        bySlice.set(entry.slice, list);
-    }
-    const issues = [];
-    const openRedSlices = [];
-    // Reject slices whose ID does not match the stable slice-id contract.
-    // Entries that drop the slice field entirely were previously coerced to
-    // `S-unknown` and silently bucketed together, which means multiple distinct
-    // cycles could appear to share a RED/GREEN pair. 7.6.0 relaxed the shape
-    // to allow lettered sub-slice ids (e.g. `S-36a`) so plan amendments can
-    // insert work between numeric slices without renumbering.
-    for (const slice of bySlice.keys()) {
-        if (!isSliceId(slice)) {
-            issues.push(`slice "${slice}": id must match S-<number>(<letter><suffix>)? (e.g. S-1, S-36a); repair by re-logging RED/GREEN/REFACTOR with a stable slice id.`);
-        }
-    }
-    for (const [slice, sliceEntries] of bySlice.entries()) {
-        let state = "need_red";
-        for (const entry of sliceEntries) {
-            if (entry.phase === "red") {
-                if (entry.exitCode === undefined) {
-                    issues.push(`slice ${slice}: RED repair needed: red entry must record a non-zero exitCode from a failing test.`);
-                    continue;
-                }
-                if (entry.exitCode === 0) {
-                    issues.push(`slice ${slice}: RED repair needed: red entry exitCode must be non-zero; passing output is not RED evidence.`);
-                    continue;
-                }
-                if (state === "red_open") {
-                    issues.push(`slice ${slice}: RED/GREEN repair needed: duplicate RED before GREEN; record the GREEN pass that closes the prior RED or split into a new slice.`);
-                    continue;
-                }
-                state = "red_open";
-                continue;
-            }
-            if (entry.phase === "green") {
-                if (entry.exitCode === undefined) {
-                    issues.push(`slice ${slice}: GREEN repair needed: green entry must record exitCode 0 from the verification command.`);
-                    continue;
-                }
-                if (entry.exitCode !== 0) {
-                    issues.push(`slice ${slice}: GREEN repair needed: green entry exitCode must be 0; fix regressions before advancing.`);
-                    continue;
-                }
-                if (state !== "red_open") {
-                    issues.push(`slice ${slice}: GREEN repair needed: green logged before RED; add the failing RED test evidence first.`);
-                    continue;
-                }
-                state = "green_done";
-                continue;
-            }
-            // refactor — must preserve the passing state established by green.
-            if (entry.exitCode === undefined) {
-                issues.push(`slice ${slice}: REFACTOR repair needed: refactor entry must record exitCode 0 proving behavior stayed green.`);
-                continue;
-            }
-            if (entry.exitCode !== 0) {
-                issues.push(`slice ${slice}: REFACTOR repair needed: tests must stay green after cleanup; rerun/fix before closing the slice.`);
-                continue;
-            }
-            if (state !== "green_done") {
-                issues.push(`slice ${slice}: REFACTOR repair needed: refactor logged before GREEN; prove GREEN first, then cleanup.`);
-                continue;
-            }
-        }
-        if (state === "red_open") {
-            openRedSlices.push(slice);
-        }
-    }
-    return {
-        ok: issues.length === 0 && openRedSlices.length === 0,
-        issues,
-        openRedSlices,
-        sliceCount: bySlice.size
-    };
-}
-/**
- * Canonical path normalization used by ALL TDD path-matching layers
- * (cycle-log analysis, internal CLI `tdd-red-evidence`, and the
- * inline runtime hook). Previously each layer had its own near-copy,
- * which produced subtle drift (e.g. `./src/app.ts` vs `src/app.ts`
- * differing between hook and CLI). Keep this function in one place
- * so all callers agree.
- */
-export function normalizeTddPath(value) {
-    const trimmed = String(value ?? "").trim();
-    return trimmed
-        .replace(/\\/gu, "/")
-        .replace(/^\.\//u, "")
-        .toLowerCase();
-}
-// Legacy alias kept for local callers below.
-function normalizePath(value) {
-    return normalizeTddPath(value);
-}
-/**
- * Shared "does the recorded file path refer to the target" matcher.
- * Uses canonical normalization plus the traditional `endsWith('/'+x)`
- * rule so a recorded `src/app.ts` matches either `src/app.ts` or
- * `subdir/src/app.ts` but NOT `src/app.test.ts`. All TDD path checks
- * MUST go through this helper.
- */
-export function pathMatchesTarget(candidate, target) {
-    const normalizedCandidate = normalizeTddPath(candidate);
-    const normalizedTarget = normalizeTddPath(target);
-    if (normalizedCandidate.length === 0 || normalizedTarget.length === 0) {
-        return false;
-    }
-    if (normalizedCandidate === normalizedTarget) {
-        return true;
-    }
-    // Only allow suffix matching for multi-segment targets. A bare basename
-    // like `app.ts` is too broad and can match unrelated files in any folder.
-    return normalizedTarget.includes("/") && normalizedCandidate.endsWith(`/${normalizedTarget}`);
-}
-/**
- * Derive a lightweight Ralph Loop summary from parsed tdd-cycle-log entries.
- * The goal is to give the model a single source of truth for "am I done
- * iterating?" — it collapses per-slice progress and distinct closed AC IDs
- * (from GREEN rows) into a single artifact the progression contract reads.
- */
-export function computeRalphLoopStatus(entries, options = {}) {
-    const runId = options.runId ?? "active";
-    const filtered = entries.filter((entry) => options.runId ? entry.runId === options.runId : true);
-    const slicesMap = new Map();
-    const acClosedSet = new Set();
-    let loopIteration = 0;
-    const redOpenSlices = [];
-    for (const slice of Array.from(new Set(filtered.map((entry) => entry.slice)))) {
-        slicesMap.set(slice, {
-            slice,
-            redCount: 0,
-            greenCount: 0,
-            refactorCount: 0,
-            redOpen: false,
-            acIds: []
-        });
-    }
-    for (const entry of filtered) {
-        const state = slicesMap.get(entry.slice);
-        if (!state)
-            continue;
-        if (entry.phase === "red") {
-            state.redCount += 1;
-            if (entry.exitCode !== undefined && entry.exitCode !== 0) {
-                state.redOpen = true;
-            }
-            continue;
-        }
-        if (entry.phase === "green") {
-            state.greenCount += 1;
-            state.redOpen = false;
-            loopIteration += 1;
-            if (Array.isArray(entry.acIds)) {
-                for (const acId of entry.acIds) {
-                    acClosedSet.add(acId);
-                    if (!state.acIds.includes(acId))
-                        state.acIds.push(acId);
-                }
-            }
-            continue;
-        }
-        state.refactorCount += 1;
-    }
-    for (const state of slicesMap.values()) {
-        if (state.redOpen)
-            redOpenSlices.push(state.slice);
-    }
-    const slices = Array.from(slicesMap.values()).sort((a, b) => a.slice.localeCompare(b.slice, "en"));
-    return {
-        schemaVersion: 1,
-        runId,
-        loopIteration,
-        redOpen: redOpenSlices.length > 0,
-        redOpenSlices,
-        acClosed: Array.from(acClosedSet).sort(),
-        sliceCount: slices.length,
-        slices,
-        lastUpdatedAt: (options.now ?? new Date()).toISOString()
-    };
-}
-/**
- * Checks whether the log contains a failing RED record associated with
- * `productionPath` for the active run.
- */
-export function hasFailingTestForPath(entries, productionPath, options = {}) {
-    const filtered = options.runId
-        ? entries.filter((entry) => entry.runId === options.runId)
-        : entries;
-    for (const entry of filtered) {
-        if (entry.phase !== "red")
-            continue;
-        if (entry.exitCode === undefined || entry.exitCode === 0)
-            continue;
-        if (!Array.isArray(entry.files) || entry.files.length === 0)
-            continue;
-        const hasMatch = entry.files.some((filePath) => pathMatchesTarget(filePath, productionPath));
-        if (hasMatch) {
-            return true;
-        }
-    }
-    return false;
-}

package/dist/tdd-verification-evidence.d.ts

@@ -1,17 +0,0 @@
-export declare const TEST_COMMAND_HINT_PATTERN: RegExp;
-export declare const SHA_WITH_LABEL_PATTERN: RegExp;
-export declare const PASS_STATUS_PATTERN: RegExp;
-export declare const NO_VCS_ATTESTATION_PATTERN: RegExp;
-export declare const NO_VCS_HASH_PATTERN: RegExp;
-export type TddVerificationRefMode = "auto" | "required" | "disabled";
-export interface TddVerificationEvidenceOptions {
-    requireCommand?: boolean;
-    requirePassStatus?: boolean;
-}
-export interface TddVerificationEvidenceResult {
-    ok: boolean;
-    issues: string[];
-    mode: TddVerificationRefMode;
-    gitPresent: boolean;
-}
-export declare function validateTddVerificationEvidence(projectRoot: string, evidence: string, options?: TddVerificationEvidenceOptions): Promise<TddVerificationEvidenceResult>;

package/dist/tdd-verification-evidence.js

@@ -1,122 +0,0 @@
-import { execFile } from "node:child_process";
-import path from "node:path";
-import { promisify } from "node:util";
-import { readConfig, resolveTddCommitMode } from "./config.js";
-import { readDelegationLedger } from "./delegation.js";
-import { exists } from "./fs-utils.js";
-const execFileAsync = promisify(execFile);
-export const TEST_COMMAND_HINT_PATTERN = /\b(?:npm test|npm run test(?::[\w:-]+)?|pnpm test|pnpm [\w:-]*test[\w:-]*|yarn test|yarn [\w:-]*test[\w:-]*|bun test|bun run test(?::[\w:-]+)?|vitest|jest|pytest|go test|cargo test|mvn test|gradle test|\.\/gradlew test|dotnet test)\b/iu;
-export const SHA_WITH_LABEL_PATTERN = /\b(?:sha|commit)(?:\s*[:=]|\s+)\s*[0-9a-f]{7,40}\b/iu;
-export const PASS_STATUS_PATTERN = /\b(?:pass|passed|green|ok)\b/iu;
-export const NO_VCS_ATTESTATION_PATTERN = /\b(?:no[-_ ]?vcs|no git|not a git repo|vcs\s*[:=]\s*none)\b/iu;
-export const NO_VCS_HASH_PATTERN = /\b(?:content|artifact)[-_ ]?hash\s*[:=]\s*(?:sha256:)?[0-9a-f]{16,64}\b|\bsha256\s*[:=]\s*[0-9a-f]{16,64}\b/iu;
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-}
-function hasRefactorCoverage(entries) {
-    const phases = new Set(entries
-        .filter((e) => e.status === "completed" && typeof e.phase === "string")
-        .map((e) => e.phase));
-    if (phases.has("refactor") || phases.has("refactor-deferred")) {
-        return true;
-    }
-    const greenWithOutcome = entries.find((entry) => entry.status === "completed" &&
-        entry.phase === "green" &&
-        entry.refactorOutcome &&
-        (entry.refactorOutcome.mode === "inline" || entry.refactorOutcome.mode === "deferred"));
-    if (!greenWithOutcome?.refactorOutcome)
-        return false;
-    if (greenWithOutcome.refactorOutcome.mode === "inline")
-        return true;
-    const rationale = greenWithOutcome.refactorOutcome.rationale;
-    if (typeof rationale === "string" && rationale.trim().length > 0)
-        return true;
-    if (!Array.isArray(greenWithOutcome.evidenceRefs))
-        return false;
-    return greenWithOutcome.evidenceRefs.some((ref) => typeof ref === "string" && ref.trim().length > 0);
-}
-function collectClosedSlices(entries, runId) {
-    const bySlice = new Map();
-    for (const entry of entries) {
-        if (entry.runId !== runId)
-            continue;
-        if (entry.stage !== "tdd")
-            continue;
-        if (entry.status !== "completed")
-            continue;
-        if (typeof entry.sliceId !== "string" || entry.sliceId.length === 0)
-            continue;
-        if (typeof entry.spanId !== "string" || entry.spanId.length === 0)
-            continue;
-        const bySpan = bySlice.get(entry.sliceId) ?? new Map();
-        const rows = bySpan.get(entry.spanId) ?? [];
-        rows.push(entry);
-        bySpan.set(entry.spanId, rows);
-        bySlice.set(entry.sliceId, bySpan);
-    }
-    const closedSlices = new Set();
-    for (const [sliceId, bySpan] of bySlice.entries()) {
-        for (const rows of bySpan.values()) {
-            const phases = new Set(rows
-                .filter((row) => row.status === "completed" && typeof row.phase === "string")
-                .map((row) => row.phase));
-            const hasRed = phases.has("red");
-            const hasGreen = phases.has("green");
-            const hasDoc = phases.has("doc");
-            if (hasRed && hasGreen && hasDoc && hasRefactorCoverage(rows)) {
-                closedSlices.add(sliceId);
-                break;
-            }
-        }
-    }
-    return [...closedSlices].sort();
-}
-async function hasManagedCommitForSlice(projectRoot, sliceId) {
-    const grep = `^${escapeRegex(sliceId)}/`;
-    const { stdout } = await execFileAsync("git", ["log", "--format=%s%n%b", "--grep", grep], { cwd: projectRoot });
-    return stdout.trim().length > 0;
-}
-export async function validateTddVerificationEvidence(projectRoot, evidence, options = {}) {
-    const normalized = evidence.trim();
-    const config = await readConfig(projectRoot).catch(() => null);
-    const commitMode = resolveTddCommitMode(config);
-    const mode = commitMode === "off" ? "disabled" : "auto";
-    const gitPresent = await exists(path.join(projectRoot, ".git"));
-    const issues = [];
-    if (options.requireCommand !== false && !TEST_COMMAND_HINT_PATTERN.test(normalized)) {
-        issues.push("GREEN repair needed: include the fresh verification command that was run (for example `npm test`, `pytest`, `go test`, or equivalent).");
-    }
-    if (options.requirePassStatus !== false && !PASS_STATUS_PATTERN.test(normalized)) {
-        issues.push("GREEN repair needed: include explicit success status (for example `PASS` or `GREEN`).");
-    }
-    if (mode !== "disabled" && commitMode === "managed-per-slice" && gitPresent) {
-        const ledger = await readDelegationLedger(projectRoot).catch(() => null);
-        if (ledger && typeof ledger.runId === "string" && ledger.runId.length > 0) {
-            const closedSlices = collectClosedSlices(ledger.entries, ledger.runId);
-            const missing = [];
-            for (const sliceId of closedSlices) {
-                const hasCommit = await hasManagedCommitForSlice(projectRoot, sliceId).catch(() => false);
-                if (!hasCommit) {
-                    missing.push(sliceId);
-                }
-            }
-            if (missing.length > 0) {
-                issues.push(`managed-per-slice commit check failed: missing git commit(s) for closed slice(s): ${missing.join(", ")}.`);
-            }
-        }
-    }
-    else if (mode === "auto") {
-        const hasSha = SHA_WITH_LABEL_PATTERN.test(normalized);
-        const hasNoVcs = NO_VCS_ATTESTATION_PATTERN.test(normalized);
-        if (gitPresent && !hasSha) {
-            issues.push("must include a commit SHA token prefixed with `sha` or `commit` (for example `sha: abc1234`).");
-        }
-        else if (!gitPresent && !hasSha && !hasNoVcs) {
-            issues.push("must include either a commit SHA or an explicit no-VCS attestation (for example `no-vcs: project has no .git directory`).");
-        }
-        else if (!gitPresent && hasNoVcs && !NO_VCS_HASH_PATTERN.test(normalized)) {
-            issues.push("NO_VCS_MODE repair needed: include a content/artifact hash for no-VCS TDD evidence (for example `artifact-hash: sha256:<hash>`).");
-        }
-    }
-    return { ok: issues.length === 0, issues, mode, gitPresent };
-}

package/dist/track-heuristics.d.ts

@@ -1,27 +0,0 @@
-import type { DiscoveryMode, FlowStage, FlowTrack, TrackHeuristicRule, TrackHeuristicsConfig } from "./types.js";
-export interface TrackResolution {
-    track: FlowTrack;
-    reason: string;
-    matchedTokens: string[];
-    confidence: "high" | "medium" | "low";
-    overrideGuidance: string;
-}
-export interface QuestionBudgetHint {
-    min: number;
-    recommended: number;
-    hardCapWarning: number;
-}
-/**
- * Reference implementation of the track classifier the /cc skill prose
- * describes. Tests pin its behavior so the built-in defaults stay honest.
- * This function is not called from cclaw runtime — `/cc` routing happens in
- * the LLM. If you wire this in later, update README to drop the
- * "advisory" language.
- */
-export declare function resolveTrackFromPrompt(prompt: string, config: TrackHeuristicsConfig | undefined): TrackResolution;
-export declare function questionBudgetHint(modeOrTrack: DiscoveryMode | FlowTrack, stage: FlowStage): QuestionBudgetHint;
-export declare const TRACK_HEURISTICS_DEFAULTS: {
-    readonly fallback: "standard";
-    readonly evaluationOrder: readonly ("quick" | "medium" | "standard")[];
-    readonly tracks: Record<"quick" | "medium" | "standard", TrackHeuristicRule>;
-};