cclaw-cli 0.51.15 → 0.51.16

package/dist/artifact-linter.js

@@ -604,11 +604,15 @@ function validateApproachesTaxonomy(sectionBody) {
     const roleIndex = columnIndex(header, "role");
     const upsideIndex = columnIndex(header, "upside");
     if (roleIndex < 0 || upsideIndex < 0) {
+        const firstColumnTokens = rows.map((row) => normalizeTableToken(row[0] ?? ""));
+        const appearsTransposed = firstColumnTokens.includes("role") || firstColumnTokens.includes("upside");
         return {
             rowCount: rows.length,
             roleUpsideOk: false,
             challengerOk: false,
-            details: "Approaches table must include canonical `Role` and `Upside` columns (Role: baseline | challenger | wild-card; Upside: low | modest | high | higher)."
+            details: appearsTransposed
+                ? "Approaches table appears transposed: `Role`/`Upside` are rows, but must be columns. Use `| Approach | Role | Upside | ... |` with one approach per row."
+                : "Approaches table must include canonical `Role` and `Upside` columns (Role: baseline | challenger | wild-card; Upside: low | modest | high | higher)."
         };
     }
     let challengerRows = 0;
@@ -649,6 +653,21 @@ function validateApproachesTaxonomy(sectionBody) {
             : `Approaches table must include exactly one challenger row with Upside high or higher. Found ${challengerRows} challenger row(s).`
     };
 }
+function validateCalibratedSelfReview(sectionBody) {
+    const hasStatus = /^\s*-\s*Status:\s*(?:Approved|Issues Found)\s*$/imu.test(sectionBody);
+    const hasPatches = /^\s*-\s*Patches applied:\s*$/imu.test(sectionBody);
+    const hasConcerns = /^\s*-\s*Remaining concerns:\s*$/imu.test(sectionBody);
+    if (!hasStatus || !hasPatches || !hasConcerns) {
+        return {
+            ok: false,
+            details: "Self-Review Notes must use the calibrated review prompt format: `- Status: Approved | Issues Found`, `- Patches applied:`, and `- Remaining concerns:`."
+        };
+    }
+    return {
+        ok: true,
+        details: "Self-Review Notes use the calibrated review prompt format."
+    };
+}
 function validateRequirementsTaxonomy(sectionBody) {
     const header = tableHeaderCells(sectionBody);
     if (!header) {
@@ -1786,6 +1805,17 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
                 });
             }
         }
+        const selfReviewBody = sectionBodyByName(sections, "Self-Review Notes");
+        if (selfReviewBody !== null) {
+            const selfReview = validateCalibratedSelfReview(selfReviewBody);
+            findings.push({
+                section: "Calibrated Self-Review Format",
+                required: true,
+                rule: "When Self-Review Notes are present, they must use the calibrated review prompt output shape.",
+                found: selfReview.ok,
+                details: selfReview.details
+            });
+        }
     }
     if (stage === "design") {
         const tierResolution = await resolveDesignDiagramTier(projectRoot, track, raw);

package/dist/content/node-hooks.js

@@ -879,6 +879,41 @@ async function buildKnowledgeDigest(root, currentStage, prereadRaw) {
   };
 }
 
+async function readStageSupportContext(root, currentStage) {
+  const stage = typeof currentStage === "string" ? currentStage : "";
+  const validStages = new Set(["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"]);
+  if (!validStages.has(stage)) return [];
+
+  const parts = [];
+  const contractPath = path.join(root, RUNTIME_ROOT, "templates", "state-contracts", stage + ".json");
+  const contract = (await readTextFile(contractPath, "")).trim();
+  if (contract.length > 0) {
+    parts.push(
+      "Current stage state contract (read before drafting or editing the stage artifact):\\n" +
+        contract
+    );
+  }
+
+  const reviewPromptByStage = {
+    brainstorm: "brainstorm-self-review.md",
+    scope: "scope-ceo-review.md",
+    design: "design-eng-review.md"
+  };
+  const promptName = reviewPromptByStage[stage];
+  if (typeof promptName === "string") {
+    const promptPath = path.join(root, RUNTIME_ROOT, "skills", "review-prompts", promptName);
+    const prompt = (await readTextFile(promptPath, "")).trim();
+    if (prompt.length > 0) {
+      parts.push(
+        "Current stage calibrated review prompt (use before asking for approval/completion):\\n" +
+          prompt
+      );
+    }
+  }
+
+  return parts;
+}
+
 async function handleSessionStart(runtime) {
   const state = await readFlowState(runtime.root);
   const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
@@ -984,6 +1019,7 @@ async function handleSessionStart(runtime) {
   const staleStages = toObject(state.raw.staleStages) || {};
   const staleStageNames = Object.keys(staleStages);
   const metaContent = (await readTextFile(metaSkillFile, "")).trim();
+  const stageSupportContext = await readStageSupportContext(runtime.root, state.currentStage);
 
   const parts = [
     "cclaw loaded. Flow: stage=" +
@@ -1017,6 +1053,9 @@ async function handleSessionStart(runtime) {
         knowledge.digestLines.join("\\n")
     );
   }
+  if (stageSupportContext.length > 0) {
+    parts.push(...stageSupportContext);
+  }
   if (ironLawLines.length > 0) {
     parts.push("Iron laws (enforced policy highlights):\\n" + ironLawLines.join("\\n"));
   }

package/dist/content/opencode-plugin.js

@@ -4,7 +4,7 @@ export function opencodePluginJs(_options = {}) {
     return `// cclaw OpenCode plugin — generated by npx cclaw-cli sync
 import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 
 export default function cclawPlugin(ctx) {
   const root = ctx.directory || process.cwd();
@@ -16,6 +16,13 @@ export default function cclawPlugin(ctx) {
   const flowStatePath = join(stateDir, "flow-state.json");
   const knowledgePath = join(runtimeDir, "knowledge.jsonl");
   const metaSkillPath = join(runtimeDir, "skills/${META_SKILL_NAME}/SKILL.md");
+  const STAGE_IDS = ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"];
+  const REVIEW_PROMPT_BY_STAGE = {
+    brainstorm: "brainstorm-self-review.md",
+    scope: "scope-ceo-review.md",
+    design: "design-eng-review.md"
+  };
+  const REVIEW_PROMPT_FILES = Object.values(REVIEW_PROMPT_BY_STAGE);
 
   function ensureRuntimeDirs() {
     try {
@@ -83,6 +90,29 @@ export default function cclawPlugin(ctx) {
     return readTailLines(knowledgePath, 12);
   }
 
+  async function readStageSupportContext(stage) {
+    if (typeof stage !== "string" || !STAGE_IDS.includes(stage)) return [];
+    const parts = [];
+    const contract = (await readFileText(join(runtimeDir, "templates/state-contracts", stage + ".json"))).trim();
+    if (contract.length > 0) {
+      parts.push(
+        "Current stage state contract (read before drafting or editing the stage artifact):\\n" +
+          contract
+      );
+    }
+    const reviewPromptName = REVIEW_PROMPT_BY_STAGE[stage];
+    if (reviewPromptName) {
+      const prompt = (await readFileText(join(runtimeDir, "skills/review-prompts", reviewPromptName))).trim();
+      if (prompt.length > 0) {
+        parts.push(
+          "Current stage calibrated review prompt (use before asking for approval/completion):\\n" +
+            prompt
+        );
+      }
+    }
+    return parts;
+  }
+
   const BOOTSTRAP_MARKER = "<!-- cclaw-bootstrap-v1 -->";
 
   async function buildBootstrap() {
@@ -97,6 +127,9 @@ export default function cclawPlugin(ctx) {
     const knowledge = await readKnowledgeDigest();
     if (knowledge.length > 0) parts.push("Knowledge digest (top relevant entries):", ...knowledge);
 
+    const stageSupport = await readStageSupportContext(flow.stage);
+    if (stageSupport.length > 0) parts.push(...stageSupport);
+
     parts.push(
       "If you discover a non-obvious rule or pattern during stage work, add it to the current artifact ## Learnings section; stage-complete harvests it into .cclaw/knowledge.jsonl. Direct JSONL append is only for explicit manual learnings operations."
     );
@@ -112,7 +145,9 @@ export default function cclawPlugin(ctx) {
   const BOOTSTRAP_SOURCE_PATHS = [
     flowStatePath,
     knowledgePath,
-    metaSkillPath
+    metaSkillPath,
+    ...STAGE_IDS.map((stage) => join(runtimeDir, "templates/state-contracts", stage + ".json")),
+    ...REVIEW_PROMPT_FILES.map((file) => join(runtimeDir, "skills/review-prompts", file))
   ];
 
   async function readMtimeMs(filePath) {
@@ -244,6 +279,23 @@ export default function cclawPlugin(ctx) {
     return false;
   }
 
+  function resolveNodeExecutable() {
+    const override = typeof process.env.CCLAW_NODE_EXECUTABLE === "string"
+      ? process.env.CCLAW_NODE_EXECUTABLE.trim()
+      : "";
+    if (override.length > 0) return override;
+
+    const execName = basename(process.execPath || "").toLowerCase();
+    if (execName === "node" || execName === "node.exe") {
+      return process.execPath;
+    }
+
+    // OpenCode can host plugins from its own CLI binary, making
+    // process.execPath point at opencode instead of Node. Fall back to the
+    // user's Node on PATH so generated cclaw hooks execute as JavaScript.
+    return "node";
+  }
+
   async function runHookScript(hookName, payload = {}) {
     const { spawn } = await import("node:child_process");
     const hookRuntimePath = join(root, "${RUNTIME_ROOT}/hooks/run-hook.mjs");
@@ -260,7 +312,7 @@ export default function cclawPlugin(ctx) {
 
       let child;
       try {
-        child = spawn(process.execPath, [hookRuntimePath, hookName], {
+        child = spawn(resolveNodeExecutable(), [hookRuntimePath, hookName], {
           cwd: root,
           stdio: ["pipe", "ignore", "pipe"]
         });

package/dist/content/templates.js

@@ -96,7 +96,11 @@ ${SEED_SHELF_SECTION}
 - (compact ASCII/Mermaid diagram for medium+ complexity, or one-line justification for omission.)
 
 ## Self-Review Notes
-- (list patches applied to this artifact during self-review, or \`- None.\`)
+- Status: Approved | Issues Found
+- Patches applied:
+  - None
+- Remaining concerns:
+  - None
 
 ## Assumptions and Open Questions
 - **Assumptions:**

package/dist/internal/advance-stage.js

@@ -4,8 +4,8 @@ import { spawn } from "node:child_process";
 import process from "node:process";
 import { resolveArtifactPath } from "../artifact-paths.js";
 import { RUNTIME_ROOT, SHIP_FINALIZATION_MODES } from "../constants.js";
-import { stageSchema } from "../content/stage-schema.js";
-import { appendDelegation, checkMandatoryDelegations } from "../delegation.js";
+import { stageAutoSubagentDispatch, stageSchema } from "../content/stage-schema.js";
+import { appendDelegation, checkMandatoryDelegations, readDelegationLedger } from "../delegation.js";
 import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../gate-evidence.js";
 import { extractMarkdownSectionBody, parseLearningsSection } from "../artifact-linter.js";
 import { getAvailableTransitions, getTransitionGuards, isFlowTrack, createInitialFlowState } from "../flow-state.js";
@@ -827,6 +827,7 @@ async function runAdvanceStage(projectRoot, args, io) {
             nextGuardEvidence[gateId] = provided.trim();
         }
     }
+    await ensureProactiveDelegationTrace(projectRoot, args.stage);
     const nextStageCatalog = {
         required: [...catalog.required],
         recommended: [...catalog.recommended],
@@ -968,6 +969,121 @@ function firstIncompleteStageForTrack(track, completedStages) {
     const stages = TRACK_STAGES[track];
     return stages.find((stage) => !completed.has(stage)) ?? stages[stages.length - 1] ?? "brainstorm";
 }
+async function ensureProactiveDelegationTrace(projectRoot, stage) {
+    const proactiveRules = stageAutoSubagentDispatch(stage).filter((rule) => rule.mode === "proactive");
+    if (proactiveRules.length === 0)
+        return;
+    const ledger = await readDelegationLedger(projectRoot);
+    const currentRunEntries = ledger.entries.filter((entry) => entry.runId === ledger.runId);
+    for (const rule of proactiveRules) {
+        const alreadyRecorded = currentRunEntries.some((entry) => entry.stage === stage && entry.agent === rule.agent && entry.mode === "proactive");
+        if (alreadyRecorded)
+            continue;
+        await appendDelegation(projectRoot, {
+            stage,
+            agent: rule.agent,
+            mode: "proactive",
+            status: "waived",
+            waiverReason: "auto-recorded: proactive delegation was not explicitly triggered before stage completion",
+            conditionTrigger: rule.when,
+            skill: rule.skill,
+            ts: new Date().toISOString()
+        });
+    }
+}
+async function pathExists(projectRoot, relPath) {
+    try {
+        await fs.stat(path.join(projectRoot, relPath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function listExistingFiles(projectRoot, relPaths) {
+    const matches = [];
+    for (const relPath of relPaths) {
+        try {
+            const stat = await fs.stat(path.join(projectRoot, relPath));
+            if (stat.isFile())
+                matches.push(relPath);
+        }
+        catch {
+            // continue
+        }
+    }
+    return matches;
+}
+async function listFilesUnder(projectRoot, relDir, limit = 20) {
+    const root = path.join(projectRoot, relDir);
+    const out = [];
+    async function walk(absDir) {
+        if (out.length >= limit)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (out.length >= limit)
+                return;
+            if (entry.name.startsWith("."))
+                continue;
+            const abs = path.join(absDir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(abs);
+            }
+            else if (entry.isFile()) {
+                out.push(path.relative(projectRoot, abs).split(path.sep).join("/"));
+            }
+        }
+    }
+    await walk(root);
+    return out;
+}
+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;
+}
 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 });
@@ -984,6 +1100,7 @@ async function appendIdeaArtifact(projectRoot, args, previous) {
         await fs.appendFile(artifactPath, entry, "utf8");
         return;
     }
+    const discoveredContext = await discoverStartFlowContext(projectRoot);
     const body = [
         "# Idea",
         `Class: ${args.className || "unspecified"}`,
@@ -994,7 +1111,7 @@ async function appendIdeaArtifact(projectRoot, args, previous) {
         args.prompt || "(not provided)",
         "",
         "## Discovered context",
-        "- None recorded by managed start-flow."
+        ...discoveredContext
     ].join("\n") + "\n";
     await fs.writeFile(artifactPath, body, "utf8");
 }

package/package.json

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