cclaw-cli 0.42.0 → 0.44.0

package/dist/internal/advance-stage.js

@@ -0,0 +1,425 @@
+import fs from "node:fs/promises";
+import { stageSchema } from "../content/stage-schema.js";
+import { appendDelegation, checkMandatoryDelegations } from "../delegation.js";
+import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../gate-evidence.js";
+import { isFlowTrack, nextStage } from "../flow-state.js";
+import { readFlowState, writeFlowState } from "../runs.js";
+import { FLOW_STAGES } from "../types.js";
+function unique(values) {
+    return [...new Set(values)];
+}
+function parseStringList(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function isFlowStageValue(value) {
+    return typeof value === "string" && FLOW_STAGES.includes(value);
+}
+function parseGuardEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    const next = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (typeof raw !== "string")
+            continue;
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        next[key] = trimmed;
+    }
+    return next;
+}
+function parseCandidateGateCatalog(value, fallback) {
+    const next = {};
+    for (const stage of FLOW_STAGES) {
+        const base = fallback[stage];
+        next[stage] = {
+            required: [...base.required],
+            recommended: [...base.recommended],
+            conditional: [...base.conditional],
+            triggered: [...base.triggered],
+            passed: [...base.passed],
+            blocked: [...base.blocked]
+        };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return next;
+    }
+    const rawCatalog = value;
+    for (const stage of FLOW_STAGES) {
+        const rawStage = rawCatalog[stage];
+        if (!rawStage || typeof rawStage !== "object" || Array.isArray(rawStage)) {
+            continue;
+        }
+        const typed = rawStage;
+        const base = fallback[stage];
+        const allowed = new Set([...base.required, ...base.recommended, ...base.conditional]);
+        const conditional = new Set(base.conditional);
+        const passed = unique(parseStringList(typed.passed)).filter((gateId) => allowed.has(gateId));
+        const blocked = unique(parseStringList(typed.blocked)).filter((gateId) => allowed.has(gateId));
+        const triggered = unique([
+            ...parseStringList(typed.triggered).filter((gateId) => conditional.has(gateId)),
+            ...passed.filter((gateId) => conditional.has(gateId)),
+            ...blocked.filter((gateId) => conditional.has(gateId))
+        ]);
+        next[stage] = {
+            required: [...base.required],
+            recommended: [...base.recommended],
+            conditional: [...base.conditional],
+            triggered,
+            passed,
+            blocked
+        };
+    }
+    return next;
+}
+function coerceCandidateFlowState(raw, fallback) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return fallback;
+    }
+    const typed = raw;
+    const track = isFlowTrack(typed.track) ? typed.track : fallback.track;
+    const currentStage = isFlowStageValue(typed.currentStage)
+        ? typed.currentStage
+        : fallback.currentStage;
+    const completedStages = unique(parseStringList(typed.completedStages).filter((stage) => isFlowStageValue(stage)));
+    const skippedStagesRaw = parseStringList(typed.skippedStages).filter((stage) => isFlowStageValue(stage));
+    const skippedStages = skippedStagesRaw.length > 0 ? skippedStagesRaw : fallback.skippedStages;
+    return {
+        ...fallback,
+        currentStage,
+        completedStages,
+        track,
+        skippedStages,
+        guardEvidence: parseGuardEvidence(typed.guardEvidence),
+        stageGateCatalog: parseCandidateGateCatalog(typed.stageGateCatalog, fallback.stageGateCatalog)
+    };
+}
+function parseEvidenceByGate(raw) {
+    if (!raw || raw.trim().length === 0) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`--evidence-json must be valid JSON object: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("--evidence-json must deserialize to an object.");
+    }
+    const next = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed.length === 0)
+            continue;
+        next[key] = trimmed;
+    }
+    return next;
+}
+function parseCsv(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function parseAdvanceStageArgs(tokens) {
+    const [stageRaw, ...flagTokens] = tokens;
+    if (!isFlowStageValue(stageRaw)) {
+        throw new Error(`internal advance-stage requires a stage positional argument (${FLOW_STAGES.join(", ")}).`);
+    }
+    let evidenceJson;
+    let passed = [];
+    let waiveDelegations = [];
+    let waiverReason;
+    let quiet = false;
+    for (const token of flagTokens) {
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token.startsWith("--evidence-json=")) {
+            evidenceJson = token.replace("--evidence-json=", "");
+            continue;
+        }
+        if (token.startsWith("--passed=")) {
+            passed = [...passed, ...parseCsv(token.replace("--passed=", ""))];
+            continue;
+        }
+        if (token.startsWith("--waive-delegation=")) {
+            waiveDelegations = [
+                ...waiveDelegations,
+                ...parseCsv(token.replace("--waive-delegation=", ""))
+            ];
+            continue;
+        }
+        if (token.startsWith("--waiver-reason=")) {
+            waiverReason = token.replace("--waiver-reason=", "").trim();
+            continue;
+        }
+        throw new Error(`Unknown flag for internal advance-stage: ${token}`);
+    }
+    return {
+        stage: stageRaw,
+        passedGateIds: unique(passed),
+        evidenceByGate: parseEvidenceByGate(evidenceJson),
+        waiveDelegations: unique(waiveDelegations),
+        waiverReason,
+        quiet
+    };
+}
+function parseVerifyFlowStateDiffArgs(tokens) {
+    let afterJson;
+    let afterFile;
+    let quiet = false;
+    for (const token of tokens) {
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token.startsWith("--after-json=")) {
+            afterJson = token.replace("--after-json=", "");
+            continue;
+        }
+        if (token.startsWith("--after-file=")) {
+            afterFile = token.replace("--after-file=", "");
+            continue;
+        }
+        throw new Error(`Unknown flag for internal verify-flow-state-diff: ${token}`);
+    }
+    if (!afterJson && !afterFile) {
+        throw new Error("internal verify-flow-state-diff requires --after-json=<json> or --after-file=<path>.");
+    }
+    return { afterJson, afterFile, quiet };
+}
+function parseVerifyCurrentStateArgs(tokens) {
+    let quiet = false;
+    for (const token of tokens) {
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        throw new Error(`Unknown flag for internal verify-current-state: ${token}`);
+    }
+    return { quiet };
+}
+async function buildValidationReport(projectRoot, flowState) {
+    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
+    const gates = await verifyCurrentStageGateEvidence(projectRoot, flowState);
+    const completedStages = verifyCompletedStagesGateClosure(flowState);
+    const ok = delegation.satisfied && gates.ok && gates.complete && completedStages.ok;
+    return {
+        ok,
+        stage: flowState.currentStage,
+        delegation: {
+            satisfied: delegation.satisfied,
+            missing: delegation.missing,
+            waived: delegation.waived,
+            missingEvidence: delegation.missingEvidence,
+            expectedMode: delegation.expectedMode
+        },
+        gates: {
+            ok: gates.ok,
+            complete: gates.complete,
+            issues: gates.issues,
+            missingRequired: gates.missingRequired,
+            missingTriggeredConditional: gates.missingTriggeredConditional
+        },
+        completedStages: {
+            ok: completedStages.ok,
+            issues: completedStages.issues
+        }
+    };
+}
+async function runAdvanceStage(projectRoot, args, io) {
+    const flowState = await readFlowState(projectRoot);
+    if (flowState.currentStage !== args.stage) {
+        io.stderr.write(`cclaw internal advance-stage: current stage is "${flowState.currentStage}", not "${args.stage}".\n`);
+        return 1;
+    }
+    const schema = stageSchema(args.stage);
+    const requiredGateIds = schema.requiredGates
+        .filter((gate) => gate.tier === "required")
+        .map((gate) => gate.id);
+    const allowedGateIds = new Set(schema.requiredGates.map((gate) => gate.id));
+    const selectedGateIds = args.passedGateIds.length > 0
+        ? args.passedGateIds.filter((gateId) => allowedGateIds.has(gateId))
+        : requiredGateIds;
+    const missingRequired = requiredGateIds.filter((gateId) => !selectedGateIds.includes(gateId));
+    if (missingRequired.length > 0) {
+        io.stderr.write(`cclaw internal advance-stage: required gates not selected as passed: ${missingRequired.join(", ")}.\n`);
+        return 1;
+    }
+    const mandatory = new Set(schema.mandatoryDelegations);
+    for (const agent of args.waiveDelegations) {
+        if (!mandatory.has(agent)) {
+            io.stderr.write(`cclaw internal advance-stage: cannot waive "${agent}" for stage "${args.stage}" (not mandatory).\n`);
+            return 1;
+        }
+    }
+    if (args.waiveDelegations.length > 0) {
+        const waiverReason = args.waiverReason && args.waiverReason.length > 0
+            ? args.waiverReason
+            : "manual_waiver";
+        for (const agent of args.waiveDelegations) {
+            await appendDelegation(projectRoot, {
+                stage: args.stage,
+                agent,
+                mode: "mandatory",
+                status: "waived",
+                waiverReason,
+                fulfillmentMode: "role-switch",
+                ts: new Date().toISOString()
+            });
+        }
+    }
+    const catalog = flowState.stageGateCatalog[args.stage];
+    const nextPassed = unique([...catalog.passed, ...selectedGateIds]).filter((gateId) => allowedGateIds.has(gateId));
+    const nextBlocked = unique(catalog.blocked.filter((gateId) => !nextPassed.includes(gateId))).filter((gateId) => allowedGateIds.has(gateId));
+    const conditional = new Set(catalog.conditional);
+    const nextTriggered = unique([
+        ...catalog.triggered.filter((gateId) => conditional.has(gateId)),
+        ...nextPassed.filter((gateId) => conditional.has(gateId)),
+        ...nextBlocked.filter((gateId) => conditional.has(gateId))
+    ]);
+    const nextGuardEvidence = { ...flowState.guardEvidence };
+    for (const gateId of nextPassed) {
+        const existing = nextGuardEvidence[gateId];
+        if (typeof existing === "string" && existing.trim().length > 0)
+            continue;
+        const provided = args.evidenceByGate[gateId];
+        nextGuardEvidence[gateId] = provided && provided.trim().length > 0
+            ? provided.trim()
+            : `stage-complete helper auto-evidence for ${gateId} @ ${new Date().toISOString()} (${schema.artifactFile})`;
+    }
+    const nextStageCatalog = {
+        required: [...catalog.required],
+        recommended: [...catalog.recommended],
+        conditional: [...catalog.conditional],
+        triggered: nextTriggered,
+        passed: nextPassed,
+        blocked: nextBlocked
+    };
+    const candidateState = {
+        ...flowState,
+        guardEvidence: nextGuardEvidence,
+        stageGateCatalog: {
+            ...flowState.stageGateCatalog,
+            [args.stage]: nextStageCatalog
+        }
+    };
+    const validation = await buildValidationReport(projectRoot, candidateState);
+    if (!validation.ok) {
+        io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}".\n`);
+        if (validation.delegation.missing.length > 0) {
+            io.stderr.write(`- missing delegations: ${validation.delegation.missing.join(", ")}\n`);
+        }
+        if (validation.delegation.missingEvidence.length > 0) {
+            io.stderr.write(`- role-switch evidence missing: ${validation.delegation.missingEvidence.join(", ")}\n`);
+        }
+        if (validation.gates.issues.length > 0) {
+            io.stderr.write(`- gate issues: ${validation.gates.issues.join(" | ")}\n`);
+        }
+        if (validation.completedStages.issues.length > 0) {
+            io.stderr.write(`- completed-stage closure issues: ${validation.completedStages.issues.join(" | ")}\n`);
+        }
+        return 1;
+    }
+    const successor = nextStage(args.stage, flowState.track);
+    const completedStages = flowState.completedStages.includes(args.stage)
+        ? [...flowState.completedStages]
+        : [...flowState.completedStages, args.stage];
+    const finalState = {
+        ...candidateState,
+        completedStages,
+        currentStage: successor ?? args.stage
+    };
+    await writeFlowState(projectRoot, finalState);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "advance-stage",
+            stage: args.stage,
+            nextStage: successor,
+            currentStage: finalState.currentStage,
+            completedStages: finalState.completedStages
+        }, null, 2)}\n`);
+    }
+    return 0;
+}
+async function runVerifyFlowStateDiff(projectRoot, args, io) {
+    let raw = args.afterJson;
+    if (!raw && args.afterFile) {
+        raw = await fs.readFile(args.afterFile, "utf8");
+    }
+    if (!raw) {
+        io.stderr.write("cclaw internal verify-flow-state-diff: no candidate state payload.\n");
+        return 1;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        io.stderr.write(`cclaw internal verify-flow-state-diff: invalid JSON payload (${err instanceof Error ? err.message : String(err)}).\n`);
+        return 1;
+    }
+    const current = await readFlowState(projectRoot);
+    const candidate = coerceCandidateFlowState(parsed, current);
+    const validation = await buildValidationReport(projectRoot, candidate);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify(validation, null, 2)}\n`);
+    }
+    if (!validation.ok) {
+        io.stderr.write(`cclaw internal verify-flow-state-diff: candidate state is invalid for stage "${validation.stage}".\n`);
+    }
+    return validation.ok ? 0 : 1;
+}
+async function runVerifyCurrentState(projectRoot, args, io) {
+    const current = await readFlowState(projectRoot);
+    const validation = await buildValidationReport(projectRoot, current);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify(validation, null, 2)}\n`);
+    }
+    if (!validation.ok) {
+        const unmetDelegations = validation.delegation.missing.length + validation.delegation.missingEvidence.length;
+        const gatesWithoutEvidence = validation.gates.issues.filter((issue) => issue.includes("missing guardEvidence entry")).length;
+        io.stderr.write(`cclaw: current stage has ${unmetDelegations} unmet mandatory delegations and ${gatesWithoutEvidence} gates without evidence.\n`);
+        io.stderr.write(`cclaw internal verify-current-state: unresolved stage constraints for "${validation.stage}".\n`);
+    }
+    return validation.ok ? 0 : 1;
+}
+export async function runInternalCommand(projectRoot, argv, io) {
+    const [subcommand, ...tokens] = argv;
+    if (!subcommand) {
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state\n");
+        return 1;
+    }
+    try {
+        if (subcommand === "advance-stage") {
+            return await runAdvanceStage(projectRoot, parseAdvanceStageArgs(tokens), io);
+        }
+        if (subcommand === "verify-flow-state-diff") {
+            return await runVerifyFlowStateDiff(projectRoot, parseVerifyFlowStateDiffArgs(tokens), io);
+        }
+        if (subcommand === "verify-current-state") {
+            return await runVerifyCurrentState(projectRoot, parseVerifyCurrentStateArgs(tokens), io);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state\n`);
+        return 1;
+    }
+    catch (err) {
+        io.stderr.write(`cclaw internal ${subcommand} failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}

package/dist/types.d.ts

@@ -92,9 +92,30 @@ export interface VibyConfig {
     version: string;
     flowVersion: string;
     harnesses: HarnessId[];
-    /** Prompt guard behavior for runtime write-risk detection hooks. */
+    /**
+     * Single-knob strictness for both guard families. When set, cclaw derives
+     * `promptGuardMode` and `tddEnforcement` from this value unless the legacy
+     * fields are explicitly provided. Default: "advisory".
+     *
+     * Added in v0.43.0 to collapse two fields that always moved together for
+     * ~99% of users. Power users who want asymmetric strictness (e.g. strict
+     * prompt guard, advisory TDD) can still set the legacy fields directly —
+     * explicit per-axis values override the derived strictness.
+     */
+    strictness?: "advisory" | "strict";
+    /**
+     * Prompt guard behavior for runtime write-risk detection hooks.
+     *
+     * Since v0.43.0 this is an advanced override. Prefer `strictness` in new
+     * configs; set this explicitly only when you need strict prompt guarding
+     * while keeping TDD advisory, or vice versa.
+     */
     promptGuardMode?: "advisory" | "strict";
-    /** TDD red->green->refactor enforcement mode used by workflow guard hooks. */
+    /**
+     * TDD red->green->refactor enforcement mode used by workflow guard hooks.
+     *
+     * Since v0.43.0 this is an advanced override — see `strictness`.
+     */
     tddEnforcement?: "advisory" | "strict";
     /** Optional test file globs used by guard guidance and /cc-ops tdd-log docs. */
     tddTestGlobs?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {