cclaw-cli 0.51.24 → 0.51.25

package/dist/content/templates.js

@@ -29,6 +29,11 @@ export const ARTIFACT_TEMPLATES = {
 ### Discovered context
 - (paths, prior artifacts, seeds, prompt fragments — referenced by downstream stages, or \`- None.\`)
 
+## Reference Pattern Candidates
+| Pattern / source | Reusable invariant | Disposition (accept/reject/defer) | Why |
+|---|---|---|---|
+|  |  |  |  |
+
 ## Problem Decision Record
 - **Depth:** lite | standard | deep
 - **Frame type:** product | technical-maintenance
@@ -60,6 +65,12 @@ export const ARTIFACT_TEMPLATES = {
 ## How Might We
 - *How might we …?* — one line naming the user, the desired outcome, and the binding constraint.
 
+## Clarity Gate
+- Ambiguity score (0.00-1.00):
+- Decision boundaries (what this stage will decide):
+- Reaffirmed non-goals:
+- Residual-risk handoff to scope:
+
 ## Sharpening Questions
 > Ask one decision-changing question at a time. For concrete early exits, record \`None - early exit\` with rationale.
 | # | Question | Answer / Assumption | Decision impact |
@@ -81,7 +92,7 @@ export const ARTIFACT_TEMPLATES = {
 - Scope handoff:
 
 ## Approaches
-| Approach | Role | Upside | Architecture | Trade-offs | Reuses | Recommendation |
+| Approach | Role | Upside | Architecture | Trade-offs | Reuses / reference pattern | Recommendation |
 |---|---|---|---|---|---|---|
 | A | baseline | modest |  |  |  |  |
 | B | challenger | high |  |  |  |  |
@@ -195,6 +206,20 @@ ${SEED_SHELF_SECTION}
 - **Success definition:**
 - **Design handoff:**
 
+## Decision Drivers
+| Driver | Weight (1-5) | Option A | Option B | Option C | Notes |
+|---|---|---|---|---|---|
+| Value impact |  |  |  |  |  |
+| Risk reduction |  |  |  |  |  |
+| Reversibility |  |  |  |  |  |
+| Delivery effort |  |  |  |  |  |
+| Timeline fit |  |  |  |  |  |
+
+## Scope Completeness Score
+- Score (0.00-1.00):
+- What is still uncertain:
+- Blockers requiring escalation:
+
 ## Scope Mode
 - [ ] SCOPE EXPANSION — explore ambitious alternatives; user explicitly opts into the larger product slice.
 - [ ] SELECTIVE EXPANSION — hold baseline scope and cherry-pick one high-leverage addition.
@@ -214,6 +239,11 @@ ${SEED_SHELF_SECTION}
 ## Taste Calibration
 - Optional quality-bar references from in-repo modules/files.
 
+## Reference Pattern Registry
+| Pattern / source | Invariant to preserve | Disposition (accepted/rejected/deferred) | Scope boundary impact |
+|---|---|---|---|
+|  |  |  |  |
+
 ## Reference Pull
 - Optional evidence from \`/Users/zuevrs/Downloads/references\`; list accepted/rejected ideas or \`Not needed - compact scope\`.
 
@@ -359,6 +389,11 @@ ${SEED_SHELF_SECTION}
 |---|---|---|---|---|---|---|
 |  |  |  |  |  |  |  |
 
+## Architecture Decision Record (ADR)
+| ADR ID | Context | Decision | Alternatives considered | Consequences | Reversal trigger |
+|---|---|---|---|---|---|
+| ADR-1 |  |  |  |  |  |
+
 ## Search Before Building
 | Layer | Label | What to reuse first |
 |---|---|---|
@@ -466,11 +501,21 @@ ${MARKDOWN_CODE_FENCE}
 |---|---|---|---|
 |  |  |  |  |
 
+## Pre-mortem
+| Scenario | Earliest warning signal | Mitigation owner | Containment action |
+|---|---|---|---|
+|  |  |  |  |
+
 ## Test Strategy
 - Unit:
 - Integration:
 - E2E:
 
+## Test-Diagram Mapping
+| Critical flow | Test coverage (ID/command) | Diagram anchor | Gap status |
+|---|---|---|---|
+|  |  |  | covered/gap |
+
 ## Performance Budget
 | Critical path | Metric | Target | Measurement method |
 |---|---|---|---|
@@ -530,6 +575,11 @@ ${MARKDOWN_CODE_FENCE}
 |---|---|---|
 |  |  |  |
 
+## Reference-Grade Contracts
+| Pattern / source | Reusable invariant | Local adaptation | Rejection boundary | Verification signal |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
 ## Interface Contracts
 - Standard/Deep add-on when module boundaries or APIs change; omit for compact local changes.
 | Module | Produces | Consumes |
@@ -558,6 +608,9 @@ ${SEED_SHELF_SECTION}
 
 **Decisions made:** 0 | **Unresolved:** 0
 
+## Learning Capture Hint
+For meaningful design work, replace the Learnings sentinel with 1-3 JSON learning bullets, for example: \`- {"type":"lesson","trigger":"when design chooses a risky fallback path","action":"record the switch trigger and rollback signal in Spec Handoff","confidence":"medium","domain":"architecture","stage":"design"}\`
+
 ## Learnings
 - None this stage.
 `,
@@ -735,7 +788,7 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 ## Execution Posture
 - Posture: sequential | dependency-batched | blocked
-- RED/GREEN/REFACTOR checkpoint plan:
+- Vertical-slice RED/GREEN/REFACTOR checkpoint plan:
 - Incremental commits: yes/no/deferred because
 
 ## RED Evidence
@@ -744,7 +797,7 @@ Execution rule: complete and verify each batch before starting the next batch.
 | S-1 |  |  |  |
 
 ## Acceptance Mapping
-| Slice | Source item ID | Spec criterion ID |
+| Vertical slice | Source item ID | Spec criterion ID |
 |---|---|---|
 | S-1 | SRC-1 | AC-1 |
 
@@ -793,6 +846,9 @@ Execution rule: complete and verify each batch before starting the next batch.
 |---|---|---|---|---|
 | S-1 |  |  |  |  |
 
+## Learning Capture Hint
+For meaningful TDD work, replace the Learnings sentinel with 1-3 JSON learning bullets, for example: \`- {"type":"pattern","trigger":"when a regression only fails after state rewind","action":"keep the RED fixture and add a cycle-log assertion before GREEN","confidence":"medium","domain":"testing","stage":"tdd"}\`
+
 ## Learnings
 - None this stage.
 `,
@@ -853,6 +909,7 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 ## Review Readiness Snapshot
 
+- Victory Detector: pass | fail (Layer 1, Layer 2, security sweep, structured findings, trace evidence, unresolved-critical status)
 - Completed checks: Layer 1, Layer 2 tags, security sweep, schema validation
 - Delegation log: \`.cclaw/state/delegation-log.json\` required/completed/waived/pending
 - Staleness signal: commit at last review pass vs current commit
@@ -893,6 +950,9 @@ Execution rule: complete and verify each batch before starting the next batch.
 ## Final Verdict
 - APPROVED | APPROVED_WITH_CONCERNS | BLOCKED
 
+## Learning Capture Hint
+For meaningful review work, replace the Learnings sentinel with 1-3 JSON learning bullets, for example: \`- {"type":"lesson","trigger":"when security sweep finds no issues but touches trust boundaries","action":"record NO_SECURITY_IMPACT with inspected surfaces and rationale","confidence":"medium","domain":"security","stage":"review"}\`
+
 ## Learnings
 - None this stage.
 `,
@@ -961,6 +1021,7 @@ ${SHIP_FINALIZATION_ENUM_LINES}
 - NO_VCS handoff target + artifact path (if FINALIZE_NO_VCS):
 
 ## Completion Status
+- Victory Detector: pass | fail (review verdict valid, preflight fresh, rollback ready, one finalization enum selected, execution result present)
 - SHIPPED | SHIPPED_WITH_EXCEPTIONS | BLOCKED
 - Exceptions (if any):
 

package/dist/delegation.d.ts

@@ -96,6 +96,8 @@ export declare function checkMandatoryDelegations(projectRoot: string, stage: Fl
     staleIgnored: string[];
     /** Delegation rows missing required evidence under a role-switch fallback. */
     missingEvidence: string[];
+    /** Current-run scheduled rows with no terminal row sharing the same spanId. */
+    staleWorkers: string[];
     /** Expected fulfillment mode for the active harness set. */
     expectedMode: DelegationFulfillmentMode;
 }>;

package/dist/delegation.js

@@ -9,6 +9,7 @@ import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
 import { stageSchema } from "./content/stage-schema.js";
 const execFileAsync = promisify(execFile);
+const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived"]);
 function delegationLogPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-log.json");
 }
@@ -135,6 +136,11 @@ function isDelegationEntry(value) {
         o.status === "waived";
     const timestampOk = typeof o.ts === "string" ||
         typeof o.startTs === "string";
+    const terminalStatus = o.status === "completed" || o.status === "failed" || o.status === "waived";
+    const lifecycleOk = o.status !== "scheduled" || o.endTs === undefined;
+    const terminalLifecycleOk = !terminalStatus ||
+        o.endTs === undefined ||
+        typeof o.endTs === "string";
     const retryOk = o.retryCount === undefined ||
         (typeof o.retryCount === "number" &&
             Number.isFinite(o.retryCount) &&
@@ -146,6 +152,8 @@ function isDelegationEntry(value) {
         modeOk &&
         statusOk &&
         timestampOk &&
+        lifecycleOk &&
+        terminalLifecycleOk &&
         (o.spanId === undefined || typeof o.spanId === "string") &&
         (o.parentSpanId === undefined || typeof o.parentSpanId === "string") &&
         (o.startTs === undefined || typeof o.startTs === "string") &&
@@ -185,6 +193,7 @@ function parseLedger(raw, runId) {
                     ...item,
                     spanId: item.spanId ?? createSpanId(),
                     startTs: ts,
+                    endTs: TERMINAL_DELEGATION_STATUSES.has(item.status) ? (item.endTs ?? ts) : undefined,
                     ts,
                     retryCount: typeof item.retryCount === "number" && Number.isInteger(item.retryCount) && item.retryCount >= 0
                         ? item.retryCount
@@ -226,6 +235,12 @@ export async function appendDelegation(projectRoot, entry) {
         stamped.spanId = entry.spanId ?? createSpanId();
         stamped.startTs = startTs;
         stamped.ts = startTs;
+        if (TERMINAL_DELEGATION_STATUSES.has(stamped.status) && !stamped.endTs) {
+            stamped.endTs = new Date().toISOString();
+        }
+        if (stamped.status === "scheduled") {
+            delete stamped.endTs;
+        }
         stamped.schemaVersion = 1;
         if (stamped.retryCount === undefined ||
             !Number.isInteger(stamped.retryCount) ||
@@ -247,11 +262,10 @@ export async function appendDelegation(projectRoot, entry) {
                 stamped.fulfillmentMode = expectedFulfillmentMode(fallbacks);
             }
         }
-        // Idempotency: if a caller (or a retried hook) tries to append a row
-        // with a spanId that already exists in the ledger, treat it as a no-op
-        // instead of growing the log with duplicate entries that subsequent
-        // delegation checks would mis-count.
-        if (prior.entries.some((existing) => existing.spanId === stamped.spanId)) {
+        // Idempotency: a retried hook may replay the same lifecycle row. Allow a
+        // terminal row to close an existing scheduled span, but drop exact same
+        // span/status duplicates so checks do not mis-count repeated writes.
+        if (prior.entries.some((existing) => existing.spanId === stamped.spanId && existing.status === stamped.status)) {
             return;
         }
         const ledger = {
@@ -293,6 +307,12 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     const missing = [];
     const waived = [];
     const missingEvidence = [];
+    const terminalSpanIds = new Set(forRun
+        .filter((entry) => TERMINAL_DELEGATION_STATUSES.has(entry.status) && entry.spanId)
+        .map((entry) => entry.spanId));
+    const staleWorkers = forRun
+        .filter((entry) => entry.status === "scheduled" && entry.spanId && !terminalSpanIds.has(entry.spanId))
+        .map((entry) => `${entry.agent}(spanId=${entry.spanId})`);
     const config = await readConfig(projectRoot).catch(() => null);
     const harnesses = config?.harnesses ?? [];
     const configuredFallbacks = harnesses.map((h) => HARNESS_ADAPTERS[h].capabilities.subagentFallback);
@@ -324,11 +344,12 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
         }
     }
     return {
-        satisfied: missing.length === 0 && missingEvidence.length === 0,
+        satisfied: missing.length === 0 && missingEvidence.length === 0 && staleWorkers.length === 0,
         missing,
         waived,
         staleIgnored,
         missingEvidence,
+        staleWorkers,
         expectedMode
     };
 }

package/dist/doctor.js

@@ -131,6 +131,20 @@ async function generatedCliEntrypointsOk(projectRoot) {
             : "local CLI entrypoint check skipped because generated hook scripts are absent"
     };
 }
+function expectedArtifactPrefix(stage) {
+    const index = FLOW_STAGES.indexOf(stage);
+    return `${String(index + 1).padStart(2, "0")}-`;
+}
+function artifactStageFromFileName(fileName) {
+    if (!fileName.endsWith(".md"))
+        return null;
+    for (const stage of FLOW_STAGES) {
+        if (fileName.startsWith(expectedArtifactPrefix(stage))) {
+            return stage;
+        }
+    }
+    return null;
+}
 function extractUserPromptFromIdeaArtifact(markdown) {
     const normalized = markdown.replace(/\r\n?/gu, "\n");
     const heading = /^##\s+User prompt\s*$/imu.exec(normalized);
@@ -1630,13 +1644,21 @@ export async function doctorChecks(projectRoot, options = {}) {
     });
     const artifactsRoot = path.join(projectRoot, RUNTIME_ROOT, "artifacts");
     let artifactPlaceholderHits = [];
+    let duplicateArtifactGroups = [];
     if (await exists(artifactsRoot)) {
         try {
             const entries = await fs.readdir(artifactsRoot, { withFileTypes: true });
             const placeholderPattern = /\b(?:TODO|TBD|FIXME)\b|<fill-in>|<your-.*-here>/giu;
+            const stageArtifactFiles = new Map();
             for (const entry of entries) {
                 if (!entry.isFile() || !entry.name.endsWith(".md"))
                     continue;
+                const stageForArtifact = artifactStageFromFileName(entry.name);
+                if (stageForArtifact) {
+                    const files = stageArtifactFiles.get(stageForArtifact) ?? [];
+                    files.push(entry.name);
+                    stageArtifactFiles.set(stageForArtifact, files);
+                }
                 const filePath = path.join(artifactsRoot, entry.name);
                 const content = await fs.readFile(filePath, "utf8");
                 const matchCount = (content.match(placeholderPattern) ?? []).length;
@@ -1644,9 +1666,13 @@ export async function doctorChecks(projectRoot, options = {}) {
                     artifactPlaceholderHits.push(`${entry.name}:${matchCount}`);
                 }
             }
+            duplicateArtifactGroups = [...stageArtifactFiles.entries()]
+                .filter(([, files]) => files.length > 1)
+                .map(([stageName, files]) => `${stageName}: ${files.sort().join(", ")}`);
         }
         catch {
             artifactPlaceholderHits = [];
+            duplicateArtifactGroups = [];
         }
     }
     checks.push({
@@ -1656,13 +1682,20 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? "no TODO/TBD/FIXME placeholder markers found in active artifacts"
             : `warning: placeholder markers detected in active artifacts (${artifactPlaceholderHits.join(", ")}). Clear before marking completion.`
     });
+    checks.push({
+        name: "warning:artifacts:duplicate_stage_artifacts",
+        ok: duplicateArtifactGroups.length === 0,
+        details: duplicateArtifactGroups.length === 0
+            ? "no duplicate stage artifacts detected in active artifacts"
+            : `warning: duplicate stage artifacts detected (${duplicateArtifactGroups.join("; ")}). The resolver uses the newest matching file; archive or rename stale copies to avoid ambiguous operator handoff.`
+    });
     const staleStages = Object.keys(flowState.staleStages).filter((value) => FLOW_STAGES.includes(value));
     checks.push({
         name: "state:stale_stages_resolved",
         ok: staleStages.length === 0,
         details: staleStages.length === 0
             ? "no stale stages pending acknowledgement"
-            : `stale stages pending acknowledgement: ${staleStages.join(", ")}`
+            : `stale stages pending acknowledgement: ${staleStages.join(", ")}. Re-run the current stale stage, then clear it with cclaw internal rewind --ack ${flowState.currentStage}.`
     });
     const retroGateStatus = await evaluateRetroGate(projectRoot, flowState);
     checks.push({
@@ -1732,18 +1765,27 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: archiveIntegrity.ok,
         details: archiveIntegrity.details
     });
+    const currentGateState = flowState.stageGateCatalog[flowState.currentStage];
+    const currentStageUntouched = flowState.completedStages.length === 0 &&
+        flowState.rewinds.length === 0 &&
+        Object.keys(flowState.guardEvidence).length === 0 &&
+        (currentGateState?.passed.length ?? 0) === 0 &&
+        (currentGateState?.blocked.length ?? 0) === 0;
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage, {
         repairFeatureSystem: false
     });
+    const delegationSatisfiedForDoctor = currentStageUntouched || delegation.satisfied;
     const missingEvidenceNote = delegation.missingEvidence && delegation.missingEvidence.length > 0
         ? ` (role-switch rows without evidenceRefs: ${delegation.missingEvidence.join(", ")})`
         : "";
     checks.push({
         name: "delegation:mandatory:current_stage",
-        ok: delegation.satisfied,
-        details: delegation.satisfied
-            ? `All mandatory delegations satisfied for stage "${flowState.currentStage}" (mode: ${delegation.expectedMode})`
-            : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}${missingEvidenceNote}`
+        ok: delegationSatisfiedForDoctor,
+        details: currentStageUntouched
+            ? `mandatory delegation check deferred for untouched stage "${flowState.currentStage}"; stage-complete enforces it when work begins`
+            : delegation.satisfied
+                ? `All mandatory delegations satisfied for stage "${flowState.currentStage}" (mode: ${delegation.expectedMode})`
+                : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}${missingEvidenceNote}`
     });
     checks.push({
         name: "warning:delegation:waived",

package/dist/gate-evidence.js

@@ -9,6 +9,7 @@ import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { detectPublicApiChanges } from "./internal/detect-public-api-changes.js";
 import { readFlowState, writeFlowState } from "./runs.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
+import { validateTddVerificationEvidence } from "./tdd-verification-evidence.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { FLOW_STAGES } from "./types.js";
 async function currentStageArtifactExists(projectRoot, stage, track) {
@@ -36,6 +37,22 @@ async function readArtifactMarkdown(projectRoot, artifactFile) {
     }
     return null;
 }
+async function readStageArtifactMarkdown(projectRoot, stage, track) {
+    const resolved = await resolveArtifactPath(stage, {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    if (!(await exists(resolved.absPath))) {
+        return null;
+    }
+    try {
+        return await fs.readFile(resolved.absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
 function unique(values) {
     return [...new Set(values)];
 }
@@ -263,6 +280,12 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             issues.push(`passed gate "${gateId}" is missing guardEvidence entry.`);
             continue;
         }
+        if (stage === "tdd" && gateId === "tdd_verified_before_complete") {
+            const verification = await validateTddVerificationEvidence(projectRoot, evidence);
+            if (!verification.ok) {
+                issues.push(`tdd verification gate blocked (${gateId}): ${verification.issues.join(" ")}`);
+            }
+        }
         const discoveredCommandIssue = await verifyDiscoveredCommandEvidence(projectRoot, stage, gateId, flowState);
         if (discoveredCommandIssue) {
             issues.push(discoveredCommandIssue);
@@ -336,7 +359,7 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
         if (stage === "design") {
             const researchGateRequired = schema.requiredGates.some((gate) => gate.id === "design_research_complete" && gate.tier === "required");
             if (researchGateRequired) {
-                const designMarkdown = await readArtifactMarkdown(projectRoot, "03-design.md");
+                const designMarkdown = await readStageArtifactMarkdown(projectRoot, "design", flowState.track);
                 const inlineResearchBody = designMarkdown
                     ? extractMarkdownSectionBody(designMarkdown, "Research Fleet Synthesis")
                     : null;
@@ -354,7 +377,7 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                 const inlineResearchComplete = inlineResearchLines.length > 0;
                 const researchMarkdown = await readArtifactMarkdown(projectRoot, "02a-research.md");
                 if (!inlineResearchComplete && !researchMarkdown) {
-                    issues.push("design research gate blocked (design_research_complete): fill `Research Fleet Synthesis` in `.cclaw/artifacts/03-design.md`, or write `.cclaw/artifacts/02a-research.md` for deep/high-risk research.");
+                    issues.push("design research gate blocked (design_research_complete): fill `Research Fleet Synthesis` in the active design artifact, or write `.cclaw/artifacts/02a-research.md` for deep/high-risk research.");
                 }
                 else if (researchMarkdown) {
                     const missingSections = [];

package/dist/install.js

@@ -23,6 +23,7 @@ import { stageSkillFolder, stageSkillMarkdown } from "./content/skills.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LANGUAGE_RULE_PACK_GENERATORS, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./content/utility-skills.js";
 import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { SUBAGENT_CONTEXT_SKILLS } from "./content/subagent-context-skills.js";
+import { CCLAW_AGENTS } from "./content/core-agents.js";
 import { createInitialFlowState } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
@@ -1339,15 +1340,7 @@ export async function uninstallCclaw(projectRoot) {
     }
     await removeIfEmpty(codexSkillsRoot);
     await removeIfEmpty(path.join(projectRoot, ".agents"));
-    const managedAgentNames = [
-        "planner",
-        "product-manager",
-        "critic",
-        "reviewer",
-        "security-reviewer",
-        "test-author",
-        "doc-updater"
-    ];
+    const managedAgentNames = CCLAW_AGENTS.map((agent) => agent.name);
     for (const agentName of managedAgentNames) {
         await removeBestEffort(path.join(projectRoot, ".opencode/agents", `${agentName}.md`));
         await removeBestEffort(path.join(projectRoot, ".codex/agents", `${agentName}.toml`));