cclaw-cli 0.51.29 → 0.55.2

package/dist/internal/advance-stage/review-loop.js

@@ -0,0 +1,170 @@
+import { SHIP_FINALIZATION_MODES } from "../../constants.js";
+import { PASS_STATUS_PATTERN, TEST_COMMAND_HINT_PATTERN, validateTddVerificationEvidence } from "../../tdd-verification-evidence.js";
+import { asRecord } from "./helpers.js";
+export const AUTO_REVIEW_LOOP_GATE_BY_STAGE = {
+    design: "design_architecture_locked"
+};
+const SHIP_FINALIZATION_MODE_PATTERN = new RegExp(`\\b(?:${SHIP_FINALIZATION_MODES.join("|")})\\b`, "u");
+const SHIP_FINALIZATION_MODE_HINT = SHIP_FINALIZATION_MODES.join(", ");
+const REVIEW_LOOP_STOP_REASONS = new Set([
+    "quality_threshold_met",
+    "max_iterations_reached",
+    "user_opt_out"
+]);
+export function pickReviewLoopEnvelope(value) {
+    const direct = asRecord(value);
+    if (!direct)
+        return null;
+    if (direct.type === "review-loop")
+        return direct;
+    const payload = asRecord(direct.payload);
+    if (payload?.type === "review-loop")
+        return payload;
+    const nested = asRecord(direct.reviewLoop);
+    if (nested?.type === "review-loop")
+        return nested;
+    return null;
+}
+export function validateReviewLoopGateEvidence(stage, evidence) {
+    let parsed;
+    try {
+        parsed = JSON.parse(evidence);
+    }
+    catch {
+        return "must be JSON containing a review-loop envelope (`type: \"review-loop\"`) in top-level, `payload`, or `reviewLoop`.";
+    }
+    const envelope = pickReviewLoopEnvelope(parsed);
+    if (!envelope) {
+        return "must include a review-loop envelope (`type: \"review-loop\"`) in top-level, `payload`, or `reviewLoop`.";
+    }
+    if (envelope.stage !== stage) {
+        return `review-loop envelope stage must be "${stage}".`;
+    }
+    const targetScore = envelope.targetScore;
+    if (typeof targetScore !== "number" || Number.isNaN(targetScore) || targetScore < 0 || targetScore > 1) {
+        return "review-loop targetScore must be a number between 0 and 1.";
+    }
+    const maxIterations = envelope.maxIterations;
+    if (typeof maxIterations !== "number" ||
+        Number.isNaN(maxIterations) ||
+        !Number.isInteger(maxIterations) ||
+        maxIterations < 1) {
+        return "review-loop maxIterations must be an integer >= 1.";
+    }
+    if (typeof envelope.stopReason !== "string" || !REVIEW_LOOP_STOP_REASONS.has(envelope.stopReason)) {
+        return "review-loop stopReason must be one of quality_threshold_met, max_iterations_reached, user_opt_out.";
+    }
+    const rows = envelope.iterations;
+    if (!Array.isArray(rows) || rows.length === 0) {
+        return "review-loop iterations must be a non-empty array.";
+    }
+    if (rows.length > maxIterations) {
+        return "review-loop iterations count cannot exceed maxIterations.";
+    }
+    let prevScore = -Infinity;
+    let reachedTarget = false;
+    for (let index = 0; index < rows.length; index++) {
+        const row = asRecord(rows[index]);
+        if (!row) {
+            return `review-loop iterations[${index}] must be an object.`;
+        }
+        const iteration = row.iteration;
+        const qualityScore = row.qualityScore;
+        const findingsCount = row.findingsCount;
+        if (typeof iteration !== "number" ||
+            Number.isNaN(iteration) ||
+            !Number.isInteger(iteration) ||
+            iteration < 1) {
+            return `review-loop iterations[${index}].iteration must be an integer >= 1.`;
+        }
+        if (typeof qualityScore !== "number" ||
+            Number.isNaN(qualityScore) ||
+            qualityScore < 0 ||
+            qualityScore > 1) {
+            return `review-loop iterations[${index}].qualityScore must be between 0 and 1.`;
+        }
+        if (typeof findingsCount !== "number" ||
+            Number.isNaN(findingsCount) ||
+            !Number.isInteger(findingsCount) ||
+            findingsCount < 0) {
+            return `review-loop iterations[${index}].findingsCount must be an integer >= 0.`;
+        }
+        if (qualityScore + Number.EPSILON < prevScore) {
+            return "review-loop qualityScore must be monotonic non-decreasing across iterations.";
+        }
+        if (qualityScore >= targetScore) {
+            reachedTarget = true;
+        }
+        prevScore = qualityScore;
+    }
+    if (envelope.stopReason === "quality_threshold_met" && !reachedTarget) {
+        return "review-loop stopReason is quality_threshold_met but no iteration reached targetScore.";
+    }
+    if (envelope.stopReason === "max_iterations_reached" && rows.length < maxIterations) {
+        return "review-loop stopReason is max_iterations_reached but iterations are below maxIterations.";
+    }
+    return null;
+}
+export function validateUserApprovalEvidence(evidence) {
+    const normalized = evidence.trim();
+    if (normalized.length === 0) {
+        return "must cite explicit user approval.";
+    }
+    const reviewLoopEnvelope = (() => {
+        try {
+            return pickReviewLoopEnvelope(JSON.parse(normalized));
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (reviewLoopEnvelope) {
+        return "must cite explicit user approval; review-loop evidence is outside-voice evidence, not user approval.";
+    }
+    if (/\b(?:approved|approval|user approved|confirmed|accepted|yes|ok)\b/iu.test(normalized)) {
+        return null;
+    }
+    if (/\b(?:утвержд(?:аю|ено|ен|ена)|подтвержд(?:аю|ено|ен|ена)|соглас(?:ен|на|овано)|да|ок|принято)\b/iu.test(normalized)) {
+        return null;
+    }
+    return "must cite explicit user approval (for example `user approved the scope contract` or `пользователь утвердил scope`).";
+}
+// Per-gate validators keyed by `${stage}:${gateId}`. Returning a non-null
+// string surfaces the reason as an `advance-stage` failure so evidence is
+// guaranteed to carry the structural breadcrumbs downstream tooling
+// expects. Previously only `tdd:tdd_verified_before_complete` was checked.
+const GATE_EVIDENCE_VALIDATORS = {
+    "review:review_trace_matrix_clean": (evidence) => {
+        if (!TEST_COMMAND_HINT_PATTERN.test(evidence)) {
+            return "must include the fresh verification command that was run before ship handoff (for example `npm test`, `pytest`, `go test`, or equivalent).";
+        }
+        if (!PASS_STATUS_PATTERN.test(evidence)) {
+            return "must include explicit success status (for example `PASS` or `GREEN`).";
+        }
+        return null;
+    },
+    "ship:ship_finalization_executed": (evidence) => {
+        if (!SHIP_FINALIZATION_MODE_PATTERN.test(evidence)) {
+            return `must name the finalization mode that ran (for example ${SHIP_FINALIZATION_MODE_HINT}).`;
+        }
+        return null;
+    },
+    "scope:scope_user_approved": (evidence) => validateUserApprovalEvidence(evidence),
+    "design:design_architecture_locked": (evidence) => validateReviewLoopGateEvidence("design", evidence)
+};
+export async function validateGateEvidenceShape(projectRoot, stage, gateId, evidence) {
+    const normalized = evidence.trim();
+    if (stage === "tdd" && gateId === "tdd_verified_before_complete") {
+        const result = await validateTddVerificationEvidence(projectRoot, normalized);
+        return result.ok ? null : result.issues.join(" ");
+    }
+    const validator = GATE_EVIDENCE_VALIDATORS[`${stage}:${gateId}`];
+    if (!validator)
+        return null;
+    return validator(normalized);
+}
+export function reviewLoopArtifactFixHint(stage, gateId) {
+    if (AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage] !== gateId)
+        return "";
+    return ` Add a \`## ${stage === "scope" ? "Scope Outside Voice Loop" : "Design Outside Voice Loop"}\` table to the artifact with rows like \`| 1 | 0.80 | 0 |\` plus \`- Stop reason: quality_threshold_met\`, \`- Target score: 0.80\`, and \`- Max iterations: 3\`; then omit this gate from manual evidence so stage-complete can auto-hydrate it.`;
+}

package/dist/internal/advance-stage/rewind.d.ts

@@ -0,0 +1,14 @@
+import { type FlowState } from "../../flow-state.js";
+import { type FlowStage } from "../../types.js";
+import type { RewindArgs } from "./parsers.js";
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function rewindLogPath(projectRoot: string): string;
+export declare function rewindId(date?: Date): string;
+export declare function stagesInvalidatedByRewind(current: FlowState, targetStage: FlowStage): FlowStage[];
+export declare function appendRewindLog(projectRoot: string, payload: Record<string, unknown>): Promise<void>;
+export declare function runRewind(projectRoot: string, args: RewindArgs, io: InternalIo): Promise<number>;
+export {};

package/dist/internal/advance-stage/rewind.js

@@ -0,0 +1,108 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "../../constants.js";
+import { ensureDir } from "../../fs-utils.js";
+import { readFlowState, writeFlowState } from "../../runs.js";
+import { TRACK_STAGES } from "../../types.js";
+export function rewindLogPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", "rewind-log.jsonl");
+}
+export function rewindId(date = new Date()) {
+    return `rewind-${date.getTime().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function stagesInvalidatedByRewind(current, targetStage) {
+    const ordered = TRACK_STAGES[current.track];
+    const targetIndex = ordered.indexOf(targetStage);
+    const currentIndex = ordered.indexOf(current.currentStage);
+    if (targetIndex < 0 || currentIndex < 0 || targetIndex > currentIndex) {
+        return [];
+    }
+    return ordered.slice(targetIndex, currentIndex + 1);
+}
+export async function appendRewindLog(projectRoot, payload) {
+    const logPath = rewindLogPath(projectRoot);
+    await ensureDir(path.dirname(logPath));
+    await fs.appendFile(logPath, `${JSON.stringify(payload)}\n`, "utf8");
+}
+export async function runRewind(projectRoot, args, io) {
+    const current = await readFlowState(projectRoot);
+    const now = new Date().toISOString();
+    if (args.mode === "ack") {
+        const marker = current.staleStages[args.targetStage];
+        if (!marker) {
+            io.stderr.write(`cclaw internal rewind: no stale marker exists for "${args.targetStage}".\n`);
+            return 1;
+        }
+        if (current.currentStage !== args.targetStage) {
+            io.stderr.write(`cclaw internal rewind: cannot ack "${args.targetStage}" while currentStage is "${current.currentStage}". Re-run the stale stage before acknowledging it.\n`);
+            return 1;
+        }
+        const staleStages = { ...current.staleStages };
+        delete staleStages[args.targetStage];
+        const nextState = { ...current, staleStages };
+        await writeFlowState(projectRoot, nextState);
+        const payload = {
+            ok: true,
+            command: "rewind",
+            action: "ack",
+            stage: args.targetStage,
+            acknowledgedAt: now,
+            rewindId: marker.rewindId
+        };
+        await appendRewindLog(projectRoot, payload);
+        if (!args.quiet) {
+            io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        }
+        return 0;
+    }
+    const invalidatedStages = stagesInvalidatedByRewind(current, args.targetStage);
+    if (invalidatedStages.length === 0) {
+        io.stderr.write(`cclaw internal rewind: target "${args.targetStage}" is not an earlier or current stage on track "${current.track}" from "${current.currentStage}".\n`);
+        return 1;
+    }
+    const id = rewindId();
+    const completedInvalidated = new Set(invalidatedStages);
+    const staleStages = { ...current.staleStages };
+    for (const stage of invalidatedStages) {
+        staleStages[stage] = {
+            rewindId: id,
+            reason: args.reason ?? "rewind",
+            markedAt: now
+        };
+    }
+    const record = {
+        id,
+        fromStage: current.currentStage,
+        toStage: args.targetStage,
+        reason: args.reason ?? "rewind",
+        timestamp: now,
+        invalidatedStages
+    };
+    const nextState = {
+        ...current,
+        currentStage: args.targetStage,
+        completedStages: current.completedStages.filter((stage) => !completedInvalidated.has(stage)),
+        staleStages,
+        rewinds: [...current.rewinds, record]
+    };
+    await writeFlowState(projectRoot, nextState);
+    const payload = {
+        ok: true,
+        command: "rewind",
+        action: "rewind",
+        rewind: record,
+        currentStage: nextState.currentStage,
+        completedStages: nextState.completedStages,
+        staleStages: Object.keys(nextState.staleStages),
+        nextActions: [
+            `Re-run ${args.targetStage} stage work and update its artifact evidence.`,
+            `Then run cclaw internal rewind --ack ${args.targetStage}.`,
+            "Continue with /cc after the stale marker is acknowledged."
+        ]
+    };
+    await appendRewindLog(projectRoot, payload);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    }
+    return 0;
+}

package/dist/internal/advance-stage/start-flow.d.ts

@@ -0,0 +1,11 @@
+import { type FlowState } from "../../flow-state.js";
+import type { StartFlowArgs } from "./parsers.js";
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function discoverStartFlowContext(projectRoot: string): Promise<string[]>;
+export declare function appendIdeaArtifact(projectRoot: string, args: StartFlowArgs, previous?: FlowState): Promise<void>;
+export declare function runStartFlow(projectRoot: string, args: StartFlowArgs, io: InternalIo): Promise<number>;
+export {};

package/dist/internal/advance-stage/start-flow.js

@@ -0,0 +1,136 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "../../constants.js";
+import { createInitialFlowState } from "../../flow-state.js";
+import { readFlowState, writeFlowState } from "../../runs.js";
+import { listExistingFiles, listFilesUnder, pathExists } from "./helpers.js";
+import { TRACK_STAGES } from "../../types.js";
+import { buildValidationReport } from "./advance.js";
+import { carriedCompletedStageCatalog, completedStageClosureEvidenceIssues, firstIncompleteStageForTrack } from "./verify.js";
+export async function discoverStartFlowContext(projectRoot) {
+    const lines = [];
+    const seedFiles = (await listFilesUnder(projectRoot, path.join(RUNTIME_ROOT, "seeds"), 10))
+        .filter((relPath) => /^\.cclaw\/seeds\/SEED-.*\.md$/u.test(relPath));
+    lines.push(seedFiles.length > 0
+        ? `- Seed shelf scanned: ${seedFiles.join(", ")}.`
+        : "- Seed shelf scanned: no `.cclaw/seeds/SEED-*.md` files found.");
+    const originDirs = ["docs/prd", "docs/rfcs", "docs/adr", "docs/design", "specs", "prd", "rfc", "design"];
+    const originRootFiles = ["PRD.md", "SPEC.md", "DESIGN.md", "REQUIREMENTS.md", "ROADMAP.md"];
+    const originFiles = [
+        ...(await listExistingFiles(projectRoot, originRootFiles)),
+        ...(await Promise.all(originDirs.map((dir) => listFilesUnder(projectRoot, dir, 6)))).flat()
+    ].slice(0, 20);
+    lines.push(originFiles.length > 0
+        ? `- Origin docs scanned: found ${originFiles.join(", ")}.`
+        : "- Origin docs scanned: no PRD/RFC/ADR/design/spec files found in configured locations.");
+    const stackMarkers = await listExistingFiles(projectRoot, [
+        "package.json",
+        "pyproject.toml",
+        "requirements.txt",
+        "requirements-dev.txt",
+        ".python-version",
+        "go.mod",
+        "Cargo.toml",
+        "pom.xml",
+        "build.gradle",
+        "build.gradle.kts",
+        "Dockerfile",
+        "docker-compose.yml",
+        "docker-compose.yaml",
+        ".gitlab-ci.yml"
+    ]);
+    if (await pathExists(projectRoot, ".github/workflows")) {
+        stackMarkers.push(".github/workflows/");
+    }
+    lines.push(stackMarkers.length > 0
+        ? `- Stack markers scanned: found ${stackMarkers.join(", ")}.`
+        : "- Stack markers scanned: no root stack markers found.");
+    return lines;
+}
+export async function appendIdeaArtifact(projectRoot, args, previous) {
+    const artifactPath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", "00-idea.md");
+    await fs.mkdir(path.dirname(artifactPath), { recursive: true });
+    const now = new Date().toISOString();
+    if (args.reclassify) {
+        const entry = [
+            "",
+            `Reclassification: ${now}`,
+            `- From: ${previous?.track ?? "unknown"}`,
+            `- To: ${args.track}`,
+            `- Class: ${args.className || "unspecified"}`,
+            `- Reason: ${args.reason || "unspecified"}`
+        ].join("\n") + "\n";
+        await fs.appendFile(artifactPath, entry, "utf8");
+        return;
+    }
+    const discoveredContext = await discoverStartFlowContext(projectRoot);
+    const body = [
+        "# Idea",
+        `Class: ${args.className || "unspecified"}`,
+        `Track: ${args.track}${args.reason ? ` (${args.reason})` : ""}`,
+        `Stack: ${args.stack || "unknown"}`,
+        "",
+        "## User prompt",
+        args.prompt || "(not provided)",
+        "",
+        "## Discovered context",
+        ...discoveredContext
+    ].join("\n") + "\n";
+    await fs.writeFile(artifactPath, body, "utf8");
+}
+export async function runStartFlow(projectRoot, args, io) {
+    const current = await readFlowState(projectRoot);
+    const hasProgress = current.completedStages.length > 0;
+    if (!args.reclassify && hasProgress && !args.forceReset) {
+        io.stderr.write("cclaw internal start-flow: refusing to reset an active flow with completed stages without --force-reset. Ask the user before resetting.\n");
+        return 1;
+    }
+    let nextState;
+    if (args.reclassify) {
+        const completedInNewTrack = current.completedStages.filter((stage) => TRACK_STAGES[args.track].includes(stage));
+        const fresh = createInitialFlowState({ activeRunId: current.activeRunId, track: args.track });
+        const stageGateCatalog = { ...fresh.stageGateCatalog };
+        const guardEvidence = {};
+        for (const stage of completedInNewTrack) {
+            const carried = carriedCompletedStageCatalog(current, fresh, stage);
+            stageGateCatalog[stage] = carried.catalog;
+            Object.assign(guardEvidence, carried.evidence);
+        }
+        nextState = {
+            ...fresh,
+            completedStages: completedInNewTrack,
+            currentStage: firstIncompleteStageForTrack(args.track, completedInNewTrack),
+            guardEvidence,
+            stageGateCatalog,
+            rewinds: current.rewinds,
+            staleStages: current.staleStages
+        };
+        const validation = await buildValidationReport(projectRoot, nextState);
+        const evidenceIssues = completedStageClosureEvidenceIssues(nextState);
+        if (!validation.completedStages.ok || evidenceIssues.length > 0) {
+            io.stderr.write("cclaw internal start-flow: reclassification would leave completed stages without valid gate closure.\n");
+            const issues = [...validation.completedStages.issues, ...evidenceIssues];
+            if (issues.length > 0) {
+                io.stderr.write(`- completed-stage closure issues: ${issues.join(" | ")}\n`);
+            }
+            return 1;
+        }
+    }
+    else {
+        nextState = createInitialFlowState({ track: args.track });
+    }
+    await writeFlowState(projectRoot, nextState, { allowReset: true });
+    await appendIdeaArtifact(projectRoot, args, current);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "start-flow",
+            reclassify: args.reclassify,
+            track: nextState.track,
+            currentStage: nextState.currentStage,
+            skippedStages: nextState.skippedStages,
+            activeRunId: nextState.activeRunId
+        }, null, 2)}\n`);
+    }
+    return 0;
+}

package/dist/internal/advance-stage/verify.d.ts

@@ -0,0 +1,29 @@
+import { type StageAutoSubagentDispatch } from "../../content/stage-schema.js";
+import { type FlowState, type StageGateState } from "../../flow-state.js";
+import { type FlowStage, type FlowTrack } from "../../types.js";
+import type { VerifyCurrentStateArgs, VerifyFlowStateDiffArgs } from "./parsers.js";
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+interface ProactiveDelegationTraceResult {
+    missingRules: StageAutoSubagentDispatch[];
+}
+export declare function runVerifyFlowStateDiff(projectRoot: string, args: VerifyFlowStateDiffArgs, io: InternalIo): Promise<number>;
+export declare function runVerifyCurrentState(projectRoot: string, args: VerifyCurrentStateArgs, io: InternalIo): Promise<number>;
+export declare function firstIncompleteStageForTrack(track: FlowTrack, completedStages: FlowStage[]): FlowStage;
+export declare function carriedCompletedStageCatalog(current: FlowState, fresh: FlowState, stage: FlowStage): {
+    catalog: StageGateState;
+    evidence: Record<string, string>;
+};
+export declare function completedStageClosureEvidenceIssues(flowState: FlowState): string[];
+export declare function ensureProactiveDelegationTrace(projectRoot: string, stage: FlowStage, options: {
+    acceptWaiver: boolean;
+    waiverReason?: string;
+}): Promise<ProactiveDelegationTraceResult>;
+export declare function pathExists(projectRoot: string, relPath: string): Promise<boolean>;
+export declare function listExistingFiles(projectRoot: string, relPaths: string[]): Promise<string[]>;
+export declare function listFilesUnder(projectRoot: string, relDir: string, limit?: number): Promise<string[]>;
+export declare function discoverStartFlowContext(projectRoot: string): Promise<string[]>;
+export {};