cclaw-cli 7.7.1 → 8.1.0

package/dist/early-loop.d.ts

@@ -1,70 +0,0 @@
-export declare const EARLY_LOOP_STAGES: readonly ["brainstorm", "scope", "design"];
-export type EarlyLoopStage = (typeof EARLY_LOOP_STAGES)[number];
-export type EarlyLoopConcernSeverity = "critical" | "important" | "suggestion";
-export interface EarlyLoopConcern {
-    id: string;
-    severity: EarlyLoopConcernSeverity;
-    locator: string;
-    summary: string;
-    firstSeenIteration: number;
-    lastSeenIteration: number;
-    resolvedAtIteration?: number;
-}
-export interface EarlyLoopStatus {
-    schemaVersion: 1;
-    stage: EarlyLoopStage;
-    runId: string;
-    iteration: number;
-    maxIterations: number;
-    openConcerns: EarlyLoopConcern[];
-    resolvedConcerns: EarlyLoopConcern[];
-    lastSeenConcernIds: string[];
-    convergenceTripped: boolean;
-    escalationReason?: string;
-    lastUpdatedAt: string;
-}
-export declare function clampEarlyLoopStatusForWrite(status: EarlyLoopStatus): {
-    status: EarlyLoopStatus;
-    clampedFrom: number | null;
-};
-export interface EarlyLoopLogConcern {
-    id: string;
-    severity: EarlyLoopConcernSeverity;
-    locator: string;
-    summary: string;
-}
-export interface EarlyLoopLogEntry {
-    ts: string;
-    runId: string;
-    stage: string;
-    iteration?: number;
-    concerns: EarlyLoopLogConcern[];
-    resolvedConcernIds: string[];
-}
-export interface EarlyLoopParseIssue {
-    lineNumber: number;
-    reason: string;
-    rawLine: string;
-}
-export interface ParseEarlyLoopLogOptions {
-    issues?: EarlyLoopParseIssue[];
-    strict?: boolean;
-}
-export interface DeriveEarlyLoopStatusOptions {
-    stage: EarlyLoopStage;
-    runId: string;
-    maxIterations?: number;
-    now?: Date;
-}
-export interface ComputeEarlyLoopStatusOptions {
-    maxIterations?: number;
-    now?: Date;
-    parseIssues?: EarlyLoopParseIssue[];
-    strictParse?: boolean;
-}
-export declare function isEarlyLoopStage(value: unknown): value is EarlyLoopStage;
-export declare function normalizeEarlyLoopMaxIterations(value: number | undefined): number;
-export declare function parseEarlyLoopLog(text: string, options?: ParseEarlyLoopLogOptions): EarlyLoopLogEntry[];
-export declare function deriveEarlyLoopStatus(entries: EarlyLoopLogEntry[], options: DeriveEarlyLoopStatusOptions): EarlyLoopStatus;
-export declare function computeEarlyLoopStatus(stage: EarlyLoopStage, runId: string, concernsLogPath: string, options?: ComputeEarlyLoopStatusOptions): Promise<EarlyLoopStatus>;
-export declare function formatEarlyLoopStatusLine(status: EarlyLoopStatus): string;

package/dist/early-loop.js

@@ -1,302 +0,0 @@
-import fs from "node:fs/promises";
-import { DEFAULT_EARLY_LOOP_MAX_ITERATIONS } from "./config.js";
-export const EARLY_LOOP_STAGES = ["brainstorm", "scope", "design"];
-export function clampEarlyLoopStatusForWrite(status) {
-    if (status.iteration <= status.maxIterations) {
-        return { status, clampedFrom: null };
-    }
-    return {
-        status: {
-            ...status,
-            iteration: status.maxIterations
-        },
-        clampedFrom: status.iteration
-    };
-}
-const CONCERN_ID_PREFIX = "C-";
-function severityWeight(severity) {
-    if (severity === "critical")
-        return 3;
-    if (severity === "important")
-        return 2;
-    return 1;
-}
-function normalizeSeverity(value) {
-    if (value === "critical" || value === "important" || value === "suggestion") {
-        return value;
-    }
-    return "important";
-}
-function normalizeText(value, fallback) {
-    if (typeof value !== "string")
-        return fallback;
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : fallback;
-}
-function stableConcernFallbackId(locator, summary) {
-    const seed = `${locator}::${summary}`.trim().toLowerCase();
-    let hash = 0;
-    for (let index = 0; index < seed.length; index += 1) {
-        hash = (Math.imul(31, hash) + seed.charCodeAt(index)) >>> 0;
-    }
-    return `${CONCERN_ID_PREFIX}${hash.toString(16).padStart(8, "0")}`;
-}
-function normalizeConcernId(id, locator, summary) {
-    if (typeof id === "string") {
-        const trimmed = id.trim();
-        if (trimmed.length > 0) {
-            return trimmed;
-        }
-    }
-    return stableConcernFallbackId(locator, summary);
-}
-function normalizeConcerns(value) {
-    if (!Array.isArray(value))
-        return [];
-    const concerns = [];
-    for (const row of value) {
-        if (!row || typeof row !== "object" || Array.isArray(row))
-            continue;
-        const typed = row;
-        const locator = normalizeText(typed.locator, "unknown-location");
-        const summary = normalizeText(typed.summary, "missing-summary");
-        concerns.push({
-            id: normalizeConcernId(typed.id, locator, summary),
-            severity: normalizeSeverity(typed.severity),
-            locator,
-            summary
-        });
-    }
-    return concerns;
-}
-function normalizeResolvedConcernIds(value) {
-    if (!Array.isArray(value))
-        return [];
-    return value
-        .filter((entry) => typeof entry === "string")
-        .map((entry) => entry.trim())
-        .filter((entry) => entry.length > 0);
-}
-export function isEarlyLoopStage(value) {
-    return typeof value === "string" && EARLY_LOOP_STAGES.includes(value);
-}
-export function normalizeEarlyLoopMaxIterations(value) {
-    if (typeof value === "number" && Number.isInteger(value) && value >= 1) {
-        return value;
-    }
-    return DEFAULT_EARLY_LOOP_MAX_ITERATIONS;
-}
-export function parseEarlyLoopLog(text, options = {}) {
-    const strict = options.strict === true;
-    const issues = options.issues;
-    const normalized = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-    const lines = normalized.split(/\r?\n/u);
-    const entries = [];
-    for (let index = 0; index < lines.length; index += 1) {
-        const raw = lines[index] ?? "";
-        const line = raw.trim();
-        if (line.length === 0)
-            continue;
-        const lineNumber = index + 1;
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-        }
-        catch (error) {
-            issues?.push({
-                lineNumber,
-                reason: `json-parse-failed: ${error instanceof Error ? error.message : String(error)}`,
-                rawLine: raw
-            });
-            continue;
-        }
-        const runId = normalizeText(parsed.runId, "");
-        const stage = normalizeText(parsed.stage, "");
-        const concerns = normalizeConcerns(parsed.concerns);
-        const resolvedConcernIds = normalizeResolvedConcernIds(parsed.resolvedConcernIds);
-        const iteration = typeof parsed.iteration === "number" &&
-            Number.isInteger(parsed.iteration) &&
-            parsed.iteration >= 1
-            ? parsed.iteration
-            : undefined;
-        if (strict) {
-            const missing = [];
-            if (runId.length === 0)
-                missing.push("runId");
-            if (stage.length === 0)
-                missing.push("stage");
-            if (concerns.length === 0 && resolvedConcernIds.length === 0) {
-                missing.push("concerns/resolvedConcernIds");
-            }
-            if (missing.length > 0) {
-                issues?.push({
-                    lineNumber,
-                    reason: `missing-required-fields: ${missing.join(",")}`,
-                    rawLine: raw
-                });
-                continue;
-            }
-        }
-        // schema repair: legacy logs may carry rows with no runId
-        // (the prior parser silently coerced them to "active", which then
-        // collided across runs). Surface a structured warning on read but
-        // skip the row so derived status doesn't fold cross-run state.
-        // Writers must always provide a runId (enforced upstream in the
-        // CLI/hook surface).
-        if (runId.length === 0) {
-            issues?.push({
-                lineNumber,
-                reason: "missing-runId: legacy entry skipped to avoid cross-run pollution",
-                rawLine: raw
-            });
-            continue;
-        }
-        entries.push({
-            ts: normalizeText(parsed.ts, ""),
-            runId,
-            stage: stage.length > 0 ? stage : "brainstorm",
-            iteration,
-            concerns,
-            resolvedConcernIds
-        });
-    }
-    return entries;
-}
-function sortConcerns(a, b) {
-    const severityDiff = severityWeight(b.severity) - severityWeight(a.severity);
-    if (severityDiff !== 0)
-        return severityDiff;
-    if (a.firstSeenIteration !== b.firstSeenIteration) {
-        return a.firstSeenIteration - b.firstSeenIteration;
-    }
-    if (a.lastSeenIteration !== b.lastSeenIteration) {
-        return a.lastSeenIteration - b.lastSeenIteration;
-    }
-    return a.id.localeCompare(b.id, "en");
-}
-export function deriveEarlyLoopStatus(entries, options) {
-    const maxIterations = normalizeEarlyLoopMaxIterations(options.maxIterations);
-    const concerns = new Map();
-    const filtered = entries.filter((entry) => entry.runId === options.runId && entry.stage === options.stage);
-    let previousConcernSnapshotKey = "";
-    let sameConcernStreak = 0;
-    let convergenceTripped = false;
-    let escalationReason;
-    let currentIteration = 0;
-    let lastSeenConcernIds = [];
-    for (const entry of filtered) {
-        currentIteration += 1;
-        const iteration = entry.iteration ?? currentIteration;
-        const seenThisIteration = new Set();
-        for (const concern of entry.concerns) {
-            seenThisIteration.add(concern.id);
-            const existing = concerns.get(concern.id);
-            if (!existing) {
-                concerns.set(concern.id, {
-                    id: concern.id,
-                    severity: concern.severity,
-                    locator: concern.locator,
-                    summary: concern.summary,
-                    firstSeenIteration: iteration,
-                    lastSeenIteration: iteration
-                });
-                continue;
-            }
-            existing.lastSeenIteration = iteration;
-            existing.locator = concern.locator;
-            existing.summary = concern.summary;
-            if (severityWeight(concern.severity) >= severityWeight(existing.severity)) {
-                existing.severity = concern.severity;
-            }
-            delete existing.resolvedAtIteration;
-        }
-        for (const concernId of entry.resolvedConcernIds) {
-            const existing = concerns.get(concernId);
-            if (!existing)
-                continue;
-            if (seenThisIteration.has(concernId))
-                continue;
-            if (existing.resolvedAtIteration === undefined) {
-                existing.resolvedAtIteration = iteration;
-            }
-        }
-        for (const concern of concerns.values()) {
-            if (concern.resolvedAtIteration !== undefined)
-                continue;
-            if (seenThisIteration.has(concern.id))
-                continue;
-            concern.resolvedAtIteration = iteration;
-        }
-        const openConcernIds = Array.from(concerns.values())
-            .filter((concern) => concern.resolvedAtIteration === undefined)
-            .map((concern) => concern.id)
-            .sort((a, b) => a.localeCompare(b, "en"));
-        lastSeenConcernIds = openConcernIds;
-        const snapshotKey = openConcernIds.join("|");
-        if (snapshotKey.length > 0 && snapshotKey === previousConcernSnapshotKey) {
-            sameConcernStreak += 1;
-            if (!convergenceTripped && sameConcernStreak >= 2) {
-                convergenceTripped = true;
-                escalationReason = `same concerns ${sameConcernStreak} iterations in a row`;
-            }
-        }
-        else {
-            sameConcernStreak = snapshotKey.length > 0 ? 1 : 0;
-        }
-        previousConcernSnapshotKey = snapshotKey;
-    }
-    const openConcerns = Array.from(concerns.values())
-        .filter((concern) => concern.resolvedAtIteration === undefined)
-        .sort(sortConcerns);
-    const resolvedConcerns = Array.from(concerns.values())
-        .filter((concern) => concern.resolvedAtIteration !== undefined)
-        .sort((a, b) => {
-        if (a.resolvedAtIteration !== b.resolvedAtIteration) {
-            return a.resolvedAtIteration - b.resolvedAtIteration;
-        }
-        return sortConcerns(a, b);
-    });
-    if (!convergenceTripped && openConcerns.length > 0 && currentIteration >= maxIterations) {
-        convergenceTripped = true;
-        escalationReason = `max iterations ${maxIterations} reached with ${openConcerns.length} open concern(s)`;
-    }
-    const iteration = Math.min(currentIteration, maxIterations);
-    return {
-        schemaVersion: 1,
-        stage: options.stage,
-        runId: options.runId,
-        iteration,
-        maxIterations,
-        openConcerns,
-        resolvedConcerns,
-        lastSeenConcernIds,
-        convergenceTripped,
-        ...(escalationReason ? { escalationReason } : {}),
-        lastUpdatedAt: (options.now ?? new Date()).toISOString()
-    };
-}
-export async function computeEarlyLoopStatus(stage, runId, concernsLogPath, options = {}) {
-    let raw = "";
-    try {
-        raw = await fs.readFile(concernsLogPath, "utf8");
-    }
-    catch (error) {
-        if (error.code !== "ENOENT") {
-            throw error;
-        }
-    }
-    const parsed = parseEarlyLoopLog(raw, {
-        issues: options.parseIssues,
-        strict: options.strictParse
-    });
-    return deriveEarlyLoopStatus(parsed, {
-        stage,
-        runId,
-        maxIterations: options.maxIterations,
-        now: options.now
-    });
-}
-export function formatEarlyLoopStatusLine(status) {
-    const convergence = status.convergenceTripped ? "tripped" : "clear";
-    return `Early Loop: stage=${status.stage}, iter=${status.iteration}/${status.maxIterations}, open=${status.openConcerns.length}, convergence=${convergence}`;
-}

package/dist/execution-topology.d.ts

@@ -1,44 +0,0 @@
-import type { ExecutionStrictnessProfile, ExecutionTopology } from "./types.js";
-export interface ExecutionTopologyShape {
-    /** Ready implementation units/slices the controller could execute now. */
-    unitCount: number;
-    /** Ready units with no declared dependency/path conflict against each other. */
-    independentUnitCount?: number;
-    /** Ready units large enough to justify isolated builder overhead. */
-    substantialUnitCount?: number;
-    /** True when same-wave path ownership overlaps or is unknown-dangerous. */
-    hasPathConflicts?: boolean;
-    /** True for migrations, public contracts, security, data loss, or broad API changes. */
-    highRisk?: boolean;
-    /** True when a plan or controller explicitly requests micro-slice discipline. */
-    requiresStrictMicro?: boolean;
-    /** True when the controller can safely execute the unit inline in the current harness. */
-    inlineSafe?: boolean;
-    /**
-     * 7.7.1 — count of ready units classified as discovery-only/scaffold/docs
-     * lanes that are not high-risk and have no path conflicts. When this equals
-     * `unitCount`, the auto router collapses the wave into `inline` (small
-     * batch) or `single-builder` (large batch) so trivial markdown spikes never
-     * fan out into one slice-builder span per file.
-     */
-    discoveryOnlyUnits?: number;
-}
-export interface ExecutionTopologyDecision {
-    topology: Exclude<ExecutionTopology, "auto">;
-    maxBuilders: number;
-    reason: string;
-}
-export interface RouteExecutionTopologyOptions {
-    configuredTopology?: ExecutionTopology;
-    strictness?: ExecutionStrictnessProfile;
-    maxBuilders?: number;
-    shape: ExecutionTopologyShape;
-}
-/**
- * Choose the cheapest safe execution topology for a ready TDD surface.
- *
- * Safety invariants are intentionally conservative: explicit strict-micro wins,
- * path conflicts prevent fan-out, and parallel builders require multiple
- * independent substantial units plus a builder cap above one.
- */
-export declare function routeExecutionTopology(options: RouteExecutionTopologyOptions): ExecutionTopologyDecision;

package/dist/execution-topology.js

@@ -1,95 +0,0 @@
-const DEFAULT_MAX_BUILDERS = 5;
-function normalizeMaxBuilders(value) {
-    return typeof value === "number" && Number.isInteger(value) && value >= 1
-        ? value
-        : DEFAULT_MAX_BUILDERS;
-}
-/**
- * Choose the cheapest safe execution topology for a ready TDD surface.
- *
- * Safety invariants are intentionally conservative: explicit strict-micro wins,
- * path conflicts prevent fan-out, and parallel builders require multiple
- * independent substantial units plus a builder cap above one.
- */
-export function routeExecutionTopology(options) {
-    const configured = options.configuredTopology ?? "auto";
-    const strictness = options.strictness ?? "balanced";
-    const maxBuilders = normalizeMaxBuilders(options.maxBuilders);
-    const shape = options.shape;
-    if (configured !== "auto") {
-        return {
-            topology: configured,
-            maxBuilders,
-            reason: `configured execution.topology=${configured}`
-        };
-    }
-    if (shape.requiresStrictMicro || strictness === "strict") {
-        return {
-            topology: "strict-micro",
-            maxBuilders,
-            reason: shape.requiresStrictMicro
-                ? "plan requested strict micro-slice execution"
-                : "strict execution profile selected"
-        };
-    }
-    const unitCount = Math.max(0, shape.unitCount);
-    if (unitCount === 0) {
-        return {
-            topology: "inline",
-            maxBuilders,
-            reason: "no ready units; controller can reconcile inline"
-        };
-    }
-    if (shape.hasPathConflicts) {
-        return {
-            topology: "single-builder",
-            maxBuilders,
-            reason: "path conflicts require serialized execution"
-        };
-    }
-    // 7.7.1 — lane-aware short-circuit. When every ready unit is a non-high-risk
-    // discovery/scaffold/docs lane with no path conflicts, never fan out: the
-    // controller should fulfil a small batch inline, or hand the whole wave to a
-    // single builder when the batch is large enough that one inline turn would
-    // bloat the controller transcript.
-    const discoveryOnly = shape.discoveryOnlyUnits ?? 0;
-    if (!shape.highRisk &&
-        discoveryOnly === unitCount &&
-        unitCount >= 1) {
-        if (unitCount <= 3) {
-            return {
-                topology: "inline",
-                maxBuilders,
-                reason: "discovery-only ready set; controller can fulfill inline"
-            };
-        }
-        return {
-            topology: "single-builder",
-            maxBuilders,
-            reason: "discovery-only ready set is large; one builder owns the wave"
-        };
-    }
-    const independent = shape.independentUnitCount ?? unitCount;
-    const substantial = shape.substantialUnitCount ?? unitCount;
-    if (maxBuilders > 1 && independent >= 2 && substantial >= 2) {
-        return {
-            topology: "parallel-builders",
-            maxBuilders,
-            reason: "multiple independent substantial units are ready"
-        };
-    }
-    if (unitCount === 1 && shape.inlineSafe && !shape.highRisk) {
-        return {
-            topology: "inline",
-            maxBuilders,
-            reason: "single low-risk inline-safe unit"
-        };
-    }
-    return {
-        topology: "single-builder",
-        maxBuilders,
-        reason: unitCount === 1
-            ? "single ready unit keeps builder evidence isolated"
-            : "ready units are not safely parallelizable"
-    };
-}

package/dist/gate-evidence.d.ts

@@ -1,85 +0,0 @@
-import type { FlowState, StageGateState } from "./flow-state.js";
-import { type FlowStage } from "./types.js";
-/**
- * Structured signal for the harness UI describing the adaptive
- * elicitation Q&A floor for the current stage. Always present on
- * brainstorm/scope/design verifications; null on other stages.
- *
- * Mirrors the `evaluateQaLogFloor` linter helper. Harness can render
- * `count / min` progress, surface stop-signal/skip-questions hints, and
- * differentiate between blocking and advisory.
- */
-export interface QaLogFloorSignal {
-    ok: boolean;
-    count: number;
-    /**
-     * always 0. The convergence floor no longer enforces
-     * a fixed count. Harness UIs may render `questionBudgetHint(track,
-     * stage).recommended` separately as a soft hint.
-     */
-    min: number;
-    hasStopSignal: boolean;
-    /** Always false; see `min` note above. */
-    liteShortCircuit: boolean;
-    skipQuestionsAdvisory: boolean;
-    blocking: boolean;
-    /** Forcing-question topics deemed addressed in `## Q&A Log`. */
-    forcingCovered: string[];
-    /** Forcing-question topics still pending (no Q&A row matched). */
-    forcingPending: string[];
-    /** Ralph-Loop convergence detector verdict for the last 2 rows. */
-    noNewDecisions: boolean;
-}
-export interface GateEvidenceCheckResult {
-    ok: boolean;
-    stage: FlowStage;
-    issues: string[];
-    requiredCount: number;
-    recommendedCount: number;
-    conditionalCount: number;
-    triggeredConditionalCount: number;
-    passedCount: number;
-    blockedCount: number;
-    /** True only when required + triggered conditional gates are passed and unblocked. */
-    complete: boolean;
-    /** Required gate ids that are neither passed nor blocked. */
-    missingRequired: string[];
-    /** Recommended gates not yet passed (does not block). */
-    missingRecommended: string[];
-    /** Triggered conditional gates that are not yet passed. */
-    missingTriggeredConditional: string[];
-    /** Q&A floor signal for adaptive elicitation stages, null otherwise. */
-    qaLogFloor: QaLogFloorSignal | null;
-}
-export interface CompletedStagesClosureResult {
-    ok: boolean;
-    issues: string[];
-    openStages: Array<{
-        stage: FlowStage;
-        missingRequired: string[];
-        missingTriggeredConditional: string[];
-        blocked: string[];
-    }>;
-}
-export interface VerifyCurrentStageGateEvidenceOptions {
-    /** Extra stage flags propagated from the in-flight CLI args (e.g. `--skip-questions`). */
-    extraStageFlags?: string[];
-}
-export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState, options?: VerifyCurrentStageGateEvidenceOptions): Promise<GateEvidenceCheckResult>;
-export declare function verifyCompletedStagesGateClosure(flowState: FlowState): CompletedStagesClosureResult;
-export interface GateReconciliationResult {
-    stage: FlowStage;
-    changed: boolean;
-    before: StageGateState;
-    after: StageGateState;
-    demotedGateIds: string[];
-    notes: string[];
-}
-export interface GateReconciliationWritebackResult extends GateReconciliationResult {
-    wrote: boolean;
-}
-export declare function reconcileCurrentStageGateCatalog(flowState: FlowState): {
-    nextState: FlowState;
-    reconciliation: GateReconciliationResult;
-};
-export declare function reconcileAndWriteCurrentStageGateCatalog(projectRoot: string): Promise<GateReconciliationWritebackResult>;