cclaw-cli 0.48.2 → 0.48.3

package/dist/install.js

@@ -178,15 +178,15 @@ async function ensureStructure(projectRoot) {
         await ensureDir(path.join(projectRoot, dir));
     }
 }
-async function writeCommandContracts(projectRoot) {
-    for (const stage of FLOW_STAGES) {
-        await writeFileSafe(runtimePath(projectRoot, "commands", `${stage}.md`), stageCommandContract(stage));
-    }
+async function writeCommandContracts(projectRoot, track = "standard") {
+    await Promise.all(FLOW_STAGES.map(async (stage) => {
+        await writeFileSafe(runtimePath(projectRoot, "commands", `${stage}.md`), stageCommandContract(stage, track));
+    }));
 }
 async function writeArtifactTemplates(projectRoot) {
-    for (const [fileName, content] of Object.entries(ARTIFACT_TEMPLATES)) {
+    await Promise.all(Object.entries(ARTIFACT_TEMPLATES).map(async ([fileName, content]) => {
         await writeFileSafe(runtimePath(projectRoot, "templates", fileName), content);
-    }
+    }));
 }
 /**
  * Seed the `.cclaw/evals/` scaffold. Only writes files that do not already
@@ -699,7 +699,7 @@ async function writeHooks(projectRoot, config) {
 async function ensureKnowledgeStore(projectRoot) {
     const storePath = runtimePath(projectRoot, "knowledge.jsonl");
     if (!(await exists(storePath))) {
-        await writeFileSafe(storePath, "");
+        await writeFileSafe(storePath, "", { mode: 0o600 });
     }
     const legacyMdPath = runtimePath(projectRoot, "knowledge.md");
     if (await exists(legacyMdPath)) {
@@ -874,7 +874,7 @@ async function ensureSessionStateFiles(projectRoot) {
     }
     const activityPath = path.join(stateDir, "stage-activity.jsonl");
     if (!(await exists(activityPath))) {
-        await writeFileSafe(activityPath, "");
+        await writeFileSafe(activityPath, "", { mode: 0o600 });
     }
     const checkpointPath = path.join(stateDir, "checkpoint.json");
     if (!(await exists(checkpointPath))) {
@@ -887,7 +887,7 @@ async function ensureSessionStateFiles(projectRoot) {
             blockers: [],
             timestamp: new Date().toISOString()
         };
-        await writeFileSafe(checkpointPath, `${JSON.stringify(initialCheckpoint, null, 2)}\n`);
+        await writeFileSafe(checkpointPath, `${JSON.stringify(initialCheckpoint, null, 2)}\n`, { mode: 0o600 });
     }
     const suggestionMemoryPath = path.join(stateDir, "suggestion-memory.json");
     if (!(await exists(suggestionMemoryPath))) {
@@ -897,11 +897,11 @@ async function ensureSessionStateFiles(projectRoot) {
             lastSuggestedStage: "",
             lastSuggestedAt: ""
         };
-        await writeFileSafe(suggestionMemoryPath, `${JSON.stringify(suggestionMemory, null, 2)}\n`);
+        await writeFileSafe(suggestionMemoryPath, `${JSON.stringify(suggestionMemory, null, 2)}\n`, { mode: 0o600 });
     }
     const contextModePath = path.join(stateDir, "context-mode.json");
     if (!(await exists(contextModePath))) {
-        await writeFileSafe(contextModePath, `${JSON.stringify(createInitialContextModeState(), null, 2)}\n`);
+        await writeFileSafe(contextModePath, `${JSON.stringify(createInitialContextModeState(), null, 2)}\n`, { mode: 0o600 });
     }
     const knowledgeDigestPath = path.join(stateDir, "knowledge-digest.md");
     if (!(await exists(knowledgeDigestPath))) {
@@ -909,18 +909,18 @@ async function ensureSessionStateFiles(projectRoot) {
     }
     const tddCycleLogPath = path.join(stateDir, "tdd-cycle-log.jsonl");
     if (!(await exists(tddCycleLogPath))) {
-        await writeFileSafe(tddCycleLogPath, "");
+        await writeFileSafe(tddCycleLogPath, "", { mode: 0o600 });
     }
     const reconciliationNoticesPath = path.join(stateDir, "reconciliation-notices.json");
     if (!(await exists(reconciliationNoticesPath))) {
-        await writeFileSafe(reconciliationNoticesPath, `${JSON.stringify({ schemaVersion: 1, notices: [] }, null, 2)}\n`);
+        await writeFileSafe(reconciliationNoticesPath, `${JSON.stringify({ schemaVersion: 1, notices: [] }, null, 2)}\n`, { mode: 0o600 });
     }
     const flowSnapshotPath = path.join(stateDir, "flow-state.snapshot.json");
     if (!(await exists(flowSnapshotPath))) {
         await writeFileSafe(flowSnapshotPath, `${JSON.stringify({
             capturedAt: new Date().toISOString(),
             state: flow
-        }, null, 2)}\n`);
+        }, null, 2)}\n`, { mode: 0o600 });
     }
 }
 async function writeRulebook(projectRoot) {
@@ -978,7 +978,7 @@ async function writeState(projectRoot, config, forceReset = false) {
         return;
     }
     const state = createInitialFlowState({ track: config.defaultTrack ?? "standard" });
-    await writeFileSafe(statePath, `${JSON.stringify(state, null, 2)}\n`);
+    await writeFileSafe(statePath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
 }
 async function writeAdapterManifest(projectRoot, harnesses) {
     const manifest = {
@@ -1198,13 +1198,15 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await ensureStructure(projectRoot);
     await cleanLegacyArtifacts(projectRoot);
     await cleanStaleFiles(projectRoot);
-    await writeCommandContracts(projectRoot);
-    await writeUtilityCommands(projectRoot, config);
-    await writeSkills(projectRoot, config);
-    await writeContextModes(projectRoot);
-    await writeArtifactTemplates(projectRoot);
-    await writeEvalScaffold(projectRoot);
-    await writeRulebook(projectRoot);
+    await Promise.all([
+        writeCommandContracts(projectRoot, config.defaultTrack ?? "standard"),
+        writeUtilityCommands(projectRoot, config),
+        writeSkills(projectRoot, config),
+        writeContextModes(projectRoot),
+        writeArtifactTemplates(projectRoot),
+        writeEvalScaffold(projectRoot),
+        writeRulebook(projectRoot)
+    ]);
     await writeState(projectRoot, config, forceStateReset);
     await ensureRunSystem(projectRoot, { createIfMissing: false });
     await ensureSessionStateFiles(projectRoot);

package/dist/internal/advance-stage.js

@@ -433,8 +433,9 @@ async function runAdvanceStage(projectRoot, args, io) {
     const selectedGateIds = args.passedGateIds.length > 0
         ? args.passedGateIds.filter((gateId) => selectableGateIds.has(gateId))
         : requiredGateIds;
+    const selectedGateIdSet = new Set(selectedGateIds);
     const selectedTransitionGuards = selectedGateIds.filter((gateId) => transitionGuardIds.has(gateId));
-    const missingRequired = requiredGateIds.filter((gateId) => !selectedGateIds.includes(gateId));
+    const missingRequired = requiredGateIds.filter((gateId) => !selectedGateIdSet.has(gateId));
     if (missingRequired.length > 0) {
         io.stderr.write(`cclaw internal advance-stage: required gates not selected as passed: ${missingRequired.join(", ")}.\n`);
         return 1;
@@ -464,7 +465,8 @@ async function runAdvanceStage(projectRoot, args, io) {
     }
     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 nextPassedSet = new Set(nextPassed);
+    const nextBlocked = unique(catalog.blocked.filter((gateId) => !nextPassedSet.has(gateId))).filter((gateId) => allowedGateIds.has(gateId));
     const conditional = new Set(catalog.conditional);
     const nextTriggered = unique([
         ...catalog.triggered.filter((gateId) => conditional.has(gateId)),

package/dist/knowledge-store.d.ts

@@ -58,9 +58,17 @@ export interface AppendKnowledgeResult {
     errors: string[];
     appendedEntries: KnowledgeEntry[];
 }
+export interface ReadKnowledgeOptions {
+    lockAware?: boolean;
+}
+export interface ReadKnowledgeResult {
+    entries: KnowledgeEntry[];
+    malformedLines: number;
+}
 export declare function validateKnowledgeEntry(entry: unknown): {
     ok: boolean;
     errors: string[];
 };
 export declare function materializeKnowledgeEntry(seed: KnowledgeSeedEntry, defaults?: AppendKnowledgeDefaults): KnowledgeEntry;
+export declare function readKnowledgeSafely(projectRoot: string, options?: ReadKnowledgeOptions): Promise<ReadKnowledgeResult>;
 export declare function appendKnowledge(projectRoot: string, seeds: KnowledgeSeedEntry[], defaults?: AppendKnowledgeDefaults): Promise<AppendKnowledgeResult>;

package/dist/knowledge-store.js

@@ -66,8 +66,78 @@ function dedupeKey(entry) {
         entry.severity === undefined ? "none" : entry.severity
     ].join("|");
 }
+function emptyKnowledgeSnapshot() {
+    return {
+        lines: [],
+        entries: [],
+        malformedLines: 0,
+        keyToIndex: new Map(),
+        entryByIndex: new Map()
+    };
+}
+function parseKnowledgeSnapshot(raw) {
+    const lines = stripBom(raw).split(/\r?\n/u);
+    const entries = [];
+    const keyToIndex = new Map();
+    const entryByIndex = new Map();
+    let malformedLines = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        const trimmed = lines[i].trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            const validated = validateKnowledgeEntry(parsed);
+            if (!validated.ok) {
+                malformedLines += 1;
+                continue;
+            }
+            const entry = parsed;
+            entries.push(entry);
+            const key = dedupeKey(entry);
+            if (!keyToIndex.has(key)) {
+                keyToIndex.set(key, i);
+            }
+            entryByIndex.set(i, entry);
+        }
+        catch {
+            malformedLines += 1;
+        }
+    }
+    return {
+        lines,
+        entries,
+        malformedLines,
+        keyToIndex,
+        entryByIndex
+    };
+}
+async function readKnowledgeSnapshot(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        return parseKnowledgeSnapshot(raw);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            return emptyKnowledgeSnapshot();
+        }
+        throw error;
+    }
+}
+function mergeKnowledgeOccurrence(target, incoming) {
+    const mergedFrequency = target.frequency + Math.max(1, incoming.frequency);
+    const mergedLastSeen = target.last_seen_ts >= incoming.last_seen_ts
+        ? target.last_seen_ts
+        : incoming.last_seen_ts;
+    return {
+        ...target,
+        frequency: mergedFrequency,
+        last_seen_ts: mergedLastSeen
+    };
+}
 function isIsoUtcTimestamp(value) {
-    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/u.test(value);
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u.test(value);
 }
 function isNullableString(value) {
     return value === null || typeof value === "string";
@@ -176,29 +246,19 @@ export function materializeKnowledgeEntry(seed, defaults = {}) {
     }
     return entry;
 }
-async function readExistingKnowledgeKeys(filePath) {
-    const keys = new Set();
-    try {
-        const raw = stripBom(await fs.readFile(filePath, "utf8"));
-        const lines = raw.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line.length > 0);
-        for (const line of lines) {
-            try {
-                const parsed = JSON.parse(line);
-                const validated = validateKnowledgeEntry(parsed);
-                if (!validated.ok)
-                    continue;
-                const entry = parsed;
-                keys.add(dedupeKey(entry));
-            }
-            catch {
-                // Ignore malformed historical lines for dedupe indexing.
-            }
-        }
-    }
-    catch {
-        // Missing file is fine — treat as empty store.
+export async function readKnowledgeSafely(projectRoot, options = {}) {
+    const filePath = knowledgePath(projectRoot);
+    const read = async () => {
+        const snapshot = await readKnowledgeSnapshot(filePath);
+        return {
+            entries: snapshot.entries,
+            malformedLines: snapshot.malformedLines
+        };
+    };
+    if (options.lockAware === false) {
+        return read();
     }
-    return keys;
+    return withDirectoryLock(knowledgeLockPath(projectRoot), read);
 }
 export async function appendKnowledge(projectRoot, seeds, defaults = {}) {
     if (seeds.length === 0) {
@@ -221,22 +281,42 @@ export async function appendKnowledge(projectRoot, seeds, defaults = {}) {
     const appendedEntries = [];
     await withDirectoryLock(knowledgeLockPath(projectRoot), async () => {
         await fs.mkdir(path.dirname(filePath), { recursive: true });
-        const existingKeys = await readExistingKnowledgeKeys(filePath);
-        const batchKeys = new Set();
-        const linesToAppend = [];
+        const snapshot = await readKnowledgeSnapshot(filePath);
+        const updatedByIndex = new Map();
+        const batchEntries = new Map();
         for (const entry of materialized) {
             const key = dedupeKey(entry);
-            if (existingKeys.has(key) || batchKeys.has(key)) {
+            const existingIndex = snapshot.keyToIndex.get(key);
+            if (existingIndex !== undefined) {
                 skippedDuplicates += 1;
+                const base = updatedByIndex.get(existingIndex) ?? snapshot.entryByIndex.get(existingIndex);
+                if (base) {
+                    updatedByIndex.set(existingIndex, mergeKnowledgeOccurrence(base, entry));
+                }
                 continue;
             }
-            batchKeys.add(key);
-            existingKeys.add(key);
-            appendedEntries.push(entry);
-            linesToAppend.push(JSON.stringify(entry));
+            const existingBatchEntry = batchEntries.get(key);
+            if (existingBatchEntry) {
+                skippedDuplicates += 1;
+                batchEntries.set(key, mergeKnowledgeOccurrence(existingBatchEntry, entry));
+                continue;
+            }
+            batchEntries.set(key, { ...entry });
+        }
+        appendedEntries.push(...batchEntries.values());
+        if (updatedByIndex.size === 0 && batchEntries.size === 0) {
+            return;
         }
-        if (linesToAppend.length > 0) {
-            await fs.appendFile(filePath, `${linesToAppend.join("\n")}\n`, "utf8");
+        const rewrittenLines = snapshot.lines.map((line, index) => {
+            const updated = updatedByIndex.get(index);
+            return updated ? JSON.stringify(updated) : line;
+        }).filter((line) => line.trim().length > 0);
+        const linesToWrite = [
+            ...rewrittenLines,
+            ...Array.from(batchEntries.values(), (entry) => JSON.stringify(entry))
+        ];
+        if (linesToWrite.length > 0) {
+            await fs.writeFile(filePath, `${linesToWrite.join("\n")}\n`, "utf8");
         }
     });
     return {

package/dist/retro-gate.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
 import { exists, stripBom } from "./fs-utils.js";
+import { readKnowledgeSafely } from "./knowledge-store.js";
 function activeArtifactsPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "artifacts");
 }
@@ -61,35 +62,44 @@ export async function evaluateRetroGate(projectRoot, state) {
         }
     }
     const shouldFallbackScan = compoundEntries <= 0 && (windowStartMs !== null || windowEndMs !== null);
-    const knowledgeFile = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
-    if (shouldFallbackScan && (await exists(knowledgeFile))) {
+    if (shouldFallbackScan) {
+        const countIfEligible = (parsed) => {
+            if (parsed.type !== "compound") {
+                return 0;
+            }
+            const created = typeof parsed.created === "string" ? parseIsoTimestamp(parsed.created) : null;
+            if (created === null || !inInclusiveWindow(created, windowStartMs, windowEndMs)) {
+                return 0;
+            }
+            const source = typeof parsed.source === "string"
+                ? parsed.source.trim().toLowerCase()
+                : null;
+            const legacyRetroStage = parsed.stage === "retro";
+            return source === "retro" || legacyRetroStage ? 1 : 0;
+        };
         try {
-            const raw = stripBom(await fs.readFile(knowledgeFile, "utf8"));
+            const knowledgeFile = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
+            const { entries } = await readKnowledgeSafely(projectRoot);
             compoundEntries = 0;
-            for (const line of raw.split(/\r?\n/)) {
-                const trimmed = line.trim();
-                if (!trimmed)
-                    continue;
-                try {
-                    const parsed = JSON.parse(trimmed);
-                    if (parsed.type !== "compound") {
-                        continue;
-                    }
-                    const created = typeof parsed.created === "string" ? parseIsoTimestamp(parsed.created) : null;
-                    if (created === null || !inInclusiveWindow(created, windowStartMs, windowEndMs)) {
+            for (const parsed of entries) {
+                compoundEntries += countIfEligible(parsed);
+            }
+            // Backward compatibility for historical/hand-edited rows that don't pass
+            // strict knowledge schema validation but still carry retro evidence.
+            if (compoundEntries === 0 && (await exists(knowledgeFile))) {
+                const raw = stripBom(await fs.readFile(knowledgeFile, "utf8"));
+                for (const line of raw.split(/\r?\n/)) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
                         continue;
+                    try {
+                        const parsed = JSON.parse(trimmed);
+                        compoundEntries += countIfEligible(parsed);
                     }
-                    const source = typeof parsed.source === "string"
-                        ? parsed.source.trim().toLowerCase()
-                        : null;
-                    const legacyRetroStage = parsed.stage === "retro";
-                    if (source === "retro" || legacyRetroStage) {
-                        compoundEntries += 1;
+                    catch {
+                        // ignore malformed lines for retro gate calculation
                     }
                 }
-                catch {
-                    // ignore malformed lines for retro gate calculation
-                }
             }
         }
         catch {

package/dist/run-archive.js

@@ -4,6 +4,7 @@ import { RUNTIME_ROOT } from "./constants.js";
 import { createInitialFlowState } from "./flow-state.js";
 import { readActiveFeature, syncActiveFeatureSnapshot } from "./feature-system.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
+import { readKnowledgeSafely } from "./knowledge-store.js";
 import { evaluateRetroGate } from "./retro-gate.js";
 import { ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
@@ -79,9 +80,9 @@ async function snapshotStateDirectory(projectRoot, destinationRoot) {
 async function resetCarryoverStateFiles(projectRoot, activeRunId) {
     const stateDir = stateDirPath(projectRoot);
     await ensureDir(stateDir);
-    await writeFileSafe(path.join(stateDir, DELEGATION_LOG_FILE), `${JSON.stringify({ runId: activeRunId, entries: [] }, null, 2)}\n`);
-    await writeFileSafe(path.join(stateDir, TDD_CYCLE_LOG_FILE), "");
-    await writeFileSafe(path.join(stateDir, RECONCILIATION_NOTICES_FILE), `${JSON.stringify({ schemaVersion: 1, notices: [] }, null, 2)}\n`);
+    await writeFileSafe(path.join(stateDir, DELEGATION_LOG_FILE), `${JSON.stringify({ runId: activeRunId, entries: [] }, null, 2)}\n`, { mode: 0o600 });
+    await writeFileSafe(path.join(stateDir, TDD_CYCLE_LOG_FILE), "", { mode: 0o600 });
+    await writeFileSafe(path.join(stateDir, RECONCILIATION_NOTICES_FILE), `${JSON.stringify({ schemaVersion: 1, notices: [] }, null, 2)}\n`, { mode: 0o600 });
 }
 function toArchiveDate(date = new Date()) {
     const yyyy = date.getFullYear().toString();
@@ -312,12 +313,8 @@ export async function archiveRun(projectRoot, featureName, options = {}) {
 }
 const KNOWLEDGE_SOFT_THRESHOLD = 50;
 async function readKnowledgeStats(projectRoot) {
-    const knowledgePath = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
-    let activeEntryCount = 0;
-    if (await exists(knowledgePath)) {
-        const text = await fs.readFile(knowledgePath, "utf8");
-        activeEntryCount = countActiveKnowledgeEntries(text);
-    }
+    const { entries } = await readKnowledgeSafely(projectRoot);
+    const activeEntryCount = entries.length;
     return {
         activeEntryCount,
         softThreshold: KNOWLEDGE_SOFT_THRESHOLD,

package/dist/run-persistence.js

@@ -381,7 +381,7 @@ export async function writeFlowState(projectRoot, state, options = {}) {
             }
         }
         const safe = coerceFlowState({ ...state });
-        await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`);
+        await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`, { mode: 0o600 });
     });
     await syncActiveFeatureSnapshot(projectRoot);
 }

package/dist/trace-matrix.js

@@ -124,17 +124,17 @@ export async function buildTraceMatrix(projectRoot) {
     const acToTasks = new Map();
     for (const [task, acs] of taskToAcs) {
         for (const ac of acs) {
-            const prev = acToTasks.get(ac) ?? [];
-            if (!prev.includes(task)) {
-                acToTasks.set(ac, [...prev, task]);
-            }
+            const prev = acToTasks.get(ac) ?? new Set();
+            prev.add(task);
+            acToTasks.set(ac, prev);
         }
     }
     const entries = criterionIds.map((criterionId) => {
-        const taskIds = acToTasks.get(criterionId) ?? [];
+        const taskIds = [...(acToTasks.get(criterionId) ?? new Set())];
+        const taskIdSet = new Set(taskIds);
         const testSlices = [];
         for (const [slice, tasks] of sliceToTasks) {
-            if (tasks.some((t) => taskIds.includes(t))) {
+            if (tasks.some((t) => taskIdSet.has(t))) {
                 testSlices.push(slice);
             }
         }
@@ -145,7 +145,7 @@ export async function buildTraceMatrix(projectRoot) {
             reviewFindings: layer1LinesForCriterion(layer1, criterionId)
         };
     });
-    const orphanedCriteria = criterionIds.filter((ac) => (acToTasks.get(ac) ?? []).length === 0);
+    const orphanedCriteria = criterionIds.filter((ac) => (acToTasks.get(ac)?.size ?? 0) === 0);
     const tasksWithSlice = new Set();
     for (const tasks of sliceToTasks.values()) {
         for (const t of tasks) {

package/package.json

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