cclaw-cli 0.1.0 → 0.2.0

package/dist/gate-evidence.js

@@ -0,0 +1,157 @@
+import { lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import { stageSchema } from "./content/stage-schema.js";
+import { readFlowState, writeFlowState } from "./runs.js";
+function unique(values) {
+    return [...new Set(values)];
+}
+function sameStringArray(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((value, index) => value === b[index]);
+}
+export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
+    const stage = flowState.currentStage;
+    const schema = stageSchema(stage);
+    const catalog = flowState.stageGateCatalog[stage];
+    const required = schema.requiredGates.map((gate) => gate.id);
+    const requiredSet = new Set(required);
+    const issues = [];
+    const catalogRequired = unique(catalog.required);
+    const missingInCatalog = required.filter((gateId) => !catalogRequired.includes(gateId));
+    const unexpectedInCatalog = catalogRequired.filter((gateId) => !requiredSet.has(gateId));
+    for (const gateId of missingInCatalog) {
+        issues.push(`gate "${gateId}" missing from stageGateCatalog.required for stage "${stage}".`);
+    }
+    for (const gateId of unexpectedInCatalog) {
+        issues.push(`unexpected gate "${gateId}" found in stageGateCatalog.required for stage "${stage}".`);
+    }
+    const blockedSet = new Set(catalog.blocked);
+    for (const gateId of catalog.passed) {
+        if (!requiredSet.has(gateId)) {
+            issues.push(`passed gate "${gateId}" is not defined for stage "${stage}".`);
+            continue;
+        }
+        if (blockedSet.has(gateId)) {
+            issues.push(`gate "${gateId}" cannot be both passed and blocked.`);
+        }
+        const evidence = flowState.guardEvidence[gateId];
+        if (typeof evidence !== "string" || evidence.trim().length === 0) {
+            issues.push(`passed gate "${gateId}" is missing guardEvidence entry.`);
+        }
+    }
+    for (const gateId of catalog.blocked) {
+        if (!requiredSet.has(gateId)) {
+            issues.push(`blocked gate "${gateId}" is not defined for stage "${stage}".`);
+        }
+    }
+    const shouldValidateArtifact = catalog.passed.length > 0 || flowState.completedStages.includes(stage);
+    if (shouldValidateArtifact) {
+        const lint = await lintArtifact(projectRoot, stage);
+        if (!lint.passed) {
+            const failedRequired = lint.findings
+                .filter((finding) => finding.required && !finding.found)
+                .map((finding) => finding.section);
+            if (failedRequired.length > 0) {
+                issues.push(`artifact validation failed for required sections: ${failedRequired.join(", ")}.`);
+            }
+        }
+        if (stage === "review") {
+            const reviewArmy = await validateReviewArmy(projectRoot);
+            if (!reviewArmy.valid) {
+                issues.push(`review-army validation failed: ${reviewArmy.errors.join("; ")}`);
+            }
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        stage,
+        issues,
+        requiredCount: required.length,
+        passedCount: catalog.passed.length,
+        blockedCount: catalog.blocked.length
+    };
+}
+export function reconcileCurrentStageGateCatalog(flowState) {
+    const stage = flowState.currentStage;
+    const required = stageSchema(stage).requiredGates.map((gate) => gate.id);
+    const requiredSet = new Set(required);
+    const catalog = flowState.stageGateCatalog[stage];
+    const notes = [];
+    const before = {
+        required: [...catalog.required],
+        passed: [...catalog.passed],
+        blocked: [...catalog.blocked]
+    };
+    const passedSet = new Set(unique(catalog.passed).filter((gateId) => {
+        const keep = requiredSet.has(gateId);
+        if (!keep) {
+            notes.push(`removed unknown passed gate "${gateId}"`);
+        }
+        return keep;
+    }));
+    const blockedSet = new Set(unique(catalog.blocked).filter((gateId) => {
+        const keep = requiredSet.has(gateId);
+        if (!keep) {
+            notes.push(`removed unknown blocked gate "${gateId}"`);
+        }
+        return keep;
+    }));
+    for (const gateId of [...passedSet]) {
+        if (!blockedSet.has(gateId))
+            continue;
+        const evidence = flowState.guardEvidence[gateId];
+        if (typeof evidence === "string" && evidence.trim().length > 0) {
+            blockedSet.delete(gateId);
+            notes.push(`resolved overlap for "${gateId}" in favor of passed (evidence present)`);
+            continue;
+        }
+        passedSet.delete(gateId);
+        notes.push(`resolved overlap for "${gateId}" in favor of blocked (missing evidence)`);
+    }
+    for (const gateId of [...passedSet]) {
+        const evidence = flowState.guardEvidence[gateId];
+        if (typeof evidence === "string" && evidence.trim().length > 0)
+            continue;
+        passedSet.delete(gateId);
+        blockedSet.add(gateId);
+        notes.push(`moved "${gateId}" from passed to blocked (missing evidence)`);
+    }
+    const after = {
+        required: [...required],
+        passed: required.filter((gateId) => passedSet.has(gateId)),
+        blocked: required.filter((gateId) => blockedSet.has(gateId) && !passedSet.has(gateId))
+    };
+    const changed = !sameStringArray(before.required, after.required) ||
+        !sameStringArray(before.passed, after.passed) ||
+        !sameStringArray(before.blocked, after.blocked);
+    const nextState = changed
+        ? {
+            ...flowState,
+            stageGateCatalog: {
+                ...flowState.stageGateCatalog,
+                [stage]: after
+            }
+        }
+        : flowState;
+    return {
+        nextState,
+        reconciliation: {
+            stage,
+            changed,
+            before,
+            after,
+            notes
+        }
+    };
+}
+export async function reconcileAndWriteCurrentStageGateCatalog(projectRoot) {
+    const state = await readFlowState(projectRoot);
+    const { nextState, reconciliation } = reconcileCurrentStageGateCatalog(state);
+    if (reconciliation.changed) {
+        await writeFlowState(projectRoot, nextState);
+    }
+    return {
+        ...reconciliation,
+        wrote: reconciliation.changed
+    };
+}

package/dist/harness-adapters.js

@@ -1,12 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
-import { CCLAW_AGENTS, agentMarkdown, agentsAgentsMdBlock } from "./content/agents.js";
-import { autoplanAgentsMdBlock } from "./content/autoplan.js";
-import { learningsAgentsMdBlock } from "./content/learnings.js";
-import { sessionHooksAgentsMdBlock } from "./content/session-hooks.js";
-import { hooksAgentsMdBlock } from "./content/hooks.js";
-import { subagentsAgentsMdBlock } from "./content/subagents.js";
+import { CCLAW_AGENTS, agentMarkdown } from "./content/agents.js";
 import { stageSkillFolder } from "./content/skills.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 export const CCLAW_MARKER_START = "<!-- cclaw-start -->";
@@ -48,9 +43,10 @@ Do not skip required handoff gates.
 function agentsMdBlock() {
     const stageList = COMMAND_FILE_ORDER.map((s) => `| \`/cc-${s}\` | \`.cclaw/skills/${stageSkillFolder(s)}/SKILL.md\` + \`.cclaw/commands/${s}.md\` |`).join("\n");
     return `${CCLAW_MARKER_START}
-## Cclaw — Structured Development Flow
+## Cclaw — Workflow Adapter
 
-> Auto-generated by \`cclaw sync\`. Do not edit manually — run \`npx cclaw sync\`.
+> Auto-generated by \`cclaw sync\`. Do not edit this managed block manually.
+> Existing project rules in this repository take precedence over cclaw defaults.
 
 ### Activation Rule
 
@@ -66,32 +62,19 @@ Before responding to a coding request:
 ${stageList}
 | \`/cc-learn\` | \`.cclaw/skills/learnings/SKILL.md\` + \`.cclaw/commands/learn.md\` |
 | \`/cc-autoplan\` | \`.cclaw/skills/autoplan/SKILL.md\` + \`.cclaw/commands/autoplan.md\` |
+| \`/cc-next\` | \`.cclaw/skills/flow-next-step/SKILL.md\` + \`.cclaw/commands/next.md\` |
 
 **Stage order:** brainstorm > scope > design > spec > plan > test > build > review > ship.
-One stage per invocation. Gates must pass before handoff. Artifacts in \`.cclaw/artifacts/\`.
+One stage per invocation. Gates must pass before handoff.
 
 ### Verification Discipline
 
 No completion claims without fresh evidence. No "Done" / "All good" / "Tests pass" without running the command in this message.
 
-### File Map
+### Detail Level
 
-| Path | Purpose |
-|---|---|
-| \`.cclaw/commands/*.md\` | Stage commands (thin orchestrators) |
-| \`.cclaw/skills/*/SKILL.md\` | Full stage instructions |
-| \`.cclaw/rules/\` | RULES.md + rules.json |
-| \`.cclaw/state/flow-state.json\` | Flow state & gate tracking |
-| \`.cclaw/artifacts/*.md\` | Stage evidence artifacts |
-| \`.cclaw/agents/*.md\` | Specialist agent personas |
-| \`.cclaw/learnings.jsonl\` | Project knowledge base |
-
-${learningsAgentsMdBlock()}
-${autoplanAgentsMdBlock()}
-${agentsAgentsMdBlock()}
-${subagentsAgentsMdBlock()}
-${sessionHooksAgentsMdBlock()}
-${hooksAgentsMdBlock()}
+- This managed AGENTS block is intentionally minimal for cross-project use.
+- Detailed operating procedures live in \`.cclaw/skills/using-cclaw/SKILL.md\`.
 ${CCLAW_MARKER_END}`;
 }
 /** Removes the cclaw AGENTS.md block. */
@@ -169,6 +152,7 @@ export async function syncHarnessShims(projectRoot, harnesses) {
         // Utility command shims
         await writeFileSafe(path.join(commandDir, "cc-learn.md"), utilityShimContent(harness, "learn", "learnings", "learn.md"));
         await writeFileSafe(path.join(commandDir, "cc-autoplan.md"), utilityShimContent(harness, "autoplan", "autoplan", "autoplan.md"));
+        await writeFileSafe(path.join(commandDir, "cc-next.md"), utilityShimContent(harness, "next", "flow-next-step", "next.md"));
     }
     await syncAgentFiles(projectRoot);
     await syncAgentsMd(projectRoot);

package/dist/hook-schema.d.ts

@@ -0,0 +1,6 @@
+export type HookSchemaHarness = "claude" | "cursor" | "codex";
+export interface HookSchemaValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+export declare function validateHookDocument(harness: HookSchemaHarness, document: unknown): HookSchemaValidationResult;

package/dist/hook-schema.js

@@ -0,0 +1,45 @@
+import claudeHooksSchema from "./hook-schemas/claude-hooks.v1.json" with { type: "json" };
+import codexHooksSchema from "./hook-schemas/codex-hooks.v1.json" with { type: "json" };
+import cursorHooksSchema from "./hook-schemas/cursor-hooks.v1.json" with { type: "json" };
+const SCHEMA_MAP = {
+    claude: claudeHooksSchema,
+    cursor: cursorHooksSchema,
+    codex: codexHooksSchema
+};
+function toObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+export function validateHookDocument(harness, document) {
+    const descriptor = SCHEMA_MAP[harness];
+    const root = toObject(document);
+    if (!root) {
+        return { ok: false, errors: ["hook document must be a JSON object"] };
+    }
+    const errors = [];
+    const version = root.cclawHookSchemaVersion;
+    if (version !== descriptor.schemaVersion) {
+        errors.push(`expected cclawHookSchemaVersion=${descriptor.schemaVersion}, got ${JSON.stringify(version)}`);
+    }
+    if (harness === "cursor" && root.version !== 1) {
+        errors.push(`cursor hooks require version=1, got ${JSON.stringify(root.version)}`);
+    }
+    const hooks = toObject(root.hooks);
+    if (!hooks) {
+        errors.push("missing hooks object");
+    }
+    else {
+        for (const eventName of descriptor.requiredEvents) {
+            const eventValue = hooks[eventName];
+            if (!Array.isArray(eventValue) || eventValue.length === 0) {
+                errors.push(`missing required event array "${eventName}"`);
+            }
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        errors
+    };
+}

package/dist/hook-schemas/claude-hooks.v1.json

@@ -0,0 +1,12 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "cclaw://hooks/claude/v1",
+    "harness": "claude",
+    "schemaVersion": 1,
+    "requiredEvents": [
+        "SessionStart",
+        "PreToolUse",
+        "PostToolUse",
+        "Stop"
+    ]
+}

package/dist/hook-schemas/codex-hooks.v1.json

@@ -0,0 +1,12 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "cclaw://hooks/codex/v1",
+    "harness": "codex",
+    "schemaVersion": 1,
+    "requiredEvents": [
+        "SessionStart",
+        "PreToolUse",
+        "PostToolUse",
+        "Stop"
+    ]
+}

package/dist/hook-schemas/cursor-hooks.v1.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "cclaw://hooks/cursor/v1",
+    "harness": "cursor",
+    "schemaVersion": 1,
+    "requiredEvents": [
+        "sessionStart",
+        "sessionResume",
+        "sessionClear",
+        "sessionCompact",
+        "preToolUse",
+        "postToolUse",
+        "stop"
+    ]
+}