cclaw-cli 0.55.2 → 2.0.0

package/dist/artifact-linter/tdd.js

@@ -1,3 +1,6 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readDelegationLedger } from "../delegation.js";
 import { sectionBodyByName } from "./shared.js";
 export async function lintTddStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
@@ -121,4 +124,75 @@ export async function lintTddStage(ctx) {
                     : "Mocks/spies detected without boundary justification; add explicit trust-boundary rationale or replace with real/fake/stub coverage."
         });
     }
+    const delegationLedger = await readDelegationLedger(projectRoot);
+    const activeRunEntries = delegationLedger.entries.filter((entry) => entry.stage === "tdd" && entry.runId === delegationLedger.runId);
+    const completedSliceImplementers = activeRunEntries.filter((entry) => entry.agent === "slice-implementer" && entry.status === "completed");
+    const fanOutDetected = completedSliceImplementers.length > 1;
+    if (fanOutDetected) {
+        const artifactsDir = path.dirname(absFile);
+        const cohesionContractMarkdownPath = path.join(artifactsDir, "cohesion-contract.md");
+        const cohesionContractJsonPath = path.join(artifactsDir, "cohesion-contract.json");
+        let cohesionContractFound = true;
+        const cohesionErrors = [];
+        try {
+            const markdown = await fs.readFile(cohesionContractMarkdownPath, "utf8");
+            if (!/#\s*Cohesion Contract\b/u.test(markdown)) {
+                cohesionContractFound = false;
+                cohesionErrors.push("cohesion-contract.md exists but missing `# Cohesion Contract` heading.");
+            }
+        }
+        catch {
+            cohesionContractFound = false;
+            cohesionErrors.push("cohesion-contract.md is missing.");
+        }
+        try {
+            const jsonRaw = await fs.readFile(cohesionContractJsonPath, "utf8");
+            const parsed = JSON.parse(jsonRaw);
+            const objectLike = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed);
+            const parsedRecord = objectLike ? parsed : null;
+            const hasRequiredShape = parsedRecord !== null &&
+                Array.isArray(parsedRecord.sharedTypes) &&
+                Array.isArray(parsedRecord.touchpoints) &&
+                Array.isArray(parsedRecord.slices) &&
+                parsedRecord.status !== undefined &&
+                typeof parsedRecord.status === "object" &&
+                parsedRecord.status !== null;
+            if (!hasRequiredShape) {
+                cohesionContractFound = false;
+                cohesionErrors.push("cohesion-contract.json must parse and include `sharedTypes[]`, `touchpoints[]`, `slices[]`, and `status`.");
+            }
+        }
+        catch {
+            cohesionContractFound = false;
+            cohesionErrors.push("cohesion-contract.json is missing or invalid JSON.");
+        }
+        findings.push({
+            section: "tdd.cohesion_contract_missing",
+            required: true,
+            rule: "When delegation ledger has >1 completed slice-implementer rows for active TDD run, require `.cclaw/artifacts/cohesion-contract.md` and parseable `.cclaw/artifacts/cohesion-contract.json` sidecar.",
+            found: cohesionContractFound,
+            details: cohesionContractFound
+                ? `Fan-out detected (${completedSliceImplementers.length} completed slice-implementer rows); cohesion contract markdown+JSON sidecar are present and parseable.`
+                : cohesionErrors.join(" ")
+        });
+        const completedOverseerRows = activeRunEntries.filter((entry) => entry.agent === "integration-overseer" && entry.status === "completed");
+        const overseerStatusInEvidence = completedOverseerRows.some((entry) => {
+            const refs = Array.isArray(entry.evidenceRefs) ? entry.evidenceRefs.join(" ") : "";
+            return /\b(?:PASS_WITH_GAPS|PASS)\b/u.test(refs);
+        });
+        const overseerStatusInArtifact = /\bintegration-overseer\b[\s\S]{0,200}\b(?:PASS_WITH_GAPS|PASS)\b/iu.test(raw);
+        const integrationOverseerFound = completedOverseerRows.length > 0 &&
+            (overseerStatusInEvidence || overseerStatusInArtifact);
+        findings.push({
+            section: "tdd.integration_overseer_missing",
+            required: true,
+            rule: "When fan-out is detected, require completed `integration-overseer` evidence with PASS or PASS_WITH_GAPS.",
+            found: integrationOverseerFound,
+            details: integrationOverseerFound
+                ? "integration-overseer completion recorded with PASS/PASS_WITH_GAPS evidence."
+                : completedOverseerRows.length === 0
+                    ? "Fan-out detected but no completed integration-overseer delegation row exists for active run."
+                    : "integration-overseer completion exists, but PASS/PASS_WITH_GAPS evidence is missing in delegation evidenceRefs and artifact text."
+        });
+    }
 }

package/dist/artifact-linter.d.ts

@@ -1,5 +1,5 @@
 import type { FlowStage, FlowTrack } from "./types.js";
 import { type LintResult } from "./artifact-linter/shared.js";
 export { validateReviewArmy, checkReviewVerdictConsistency, checkReviewSecurityNoChangeAttestation, type ReviewVerdictConsistencyResult, type ReviewSecurityNoChangeAttestationResult } from "./artifact-linter/review-army.js";
-export { type LintFinding, type LintResult, type LearningEntryType, type LearningConfidence, type LearningSeverity, type LearningUniversality, type LearningMaturity, type LearningSource, type LearningSeedEntry, type LearningsParseResult, extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
+export { type LintFinding, type LintResult, type LearningEntryType, type LearningConfidence, type LearningSeverity, type LearningSource, type LearningSeedEntry, type LearningsParseResult, extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
 export declare function lintArtifact(projectRoot: string, stage: FlowStage, track?: FlowTrack): Promise<LintResult>;

package/dist/artifact-linter.js

@@ -3,7 +3,7 @@ import { resolveArtifactPath as resolveStageArtifactPath } from "./artifact-path
 import { readConfig } from "./config.js";
 import { exists } from "./fs-utils.js";
 import { stageSchema } from "./content/stage-schema.js";
-import { extractH2Sections, extractLockedDecisionAnchors, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody } from "./artifact-linter/shared.js";
+import { duplicateH2Headings, extractH2Sections, extractLockedDecisionAnchors, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody } from "./artifact-linter/shared.js";
 import { lintBrainstormStage } from "./artifact-linter/brainstorm.js";
 import { lintDesignStage } from "./artifact-linter/design.js";
 import { lintPlanStage } from "./artifact-linter/plan.js";
@@ -48,6 +48,16 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
     }
     const raw = await fs.readFile(absFile, "utf8");
     const sections = extractH2Sections(raw);
+    const duplicateHeadings = duplicateH2Headings(raw);
+    if (duplicateHeadings.length > 0) {
+        findings.push({
+            section: "duplicate_h2_heading",
+            required: false,
+            rule: "[P3] keep each `##` heading unique within an artifact; append updates to the existing section instead of cloning headings.",
+            found: false,
+            details: `Duplicate H2 heading(s): ${duplicateHeadings.join(", ")}. Merge edits into the existing heading to avoid split contracts.`
+        });
+    }
     const projectConfig = await readConfig(projectRoot);
     const parsedFrontmatter = parseFrontmatter(raw);
     const frontmatterMissingKeys = FRONTMATTER_REQUIRED_KEYS.filter((key) => {

package/dist/constants.d.ts

@@ -10,7 +10,7 @@ export declare const FLOW_VERSION = "1.0.0";
 export declare const SHIP_FINALIZATION_MODES: readonly ["FINALIZE_MERGE_LOCAL", "FINALIZE_OPEN_PR", "FINALIZE_KEEP_BRANCH", "FINALIZE_DISCARD_BRANCH", "FINALIZE_NO_VCS"];
 export type ShipFinalizationMode = (typeof SHIP_FINALIZATION_MODES)[number];
 export declare const DEFAULT_HARNESSES: HarnessId[];
-export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/templates", ".cclaw/templates/state-contracts", ".cclaw/artifacts", ".cclaw/archive", ".cclaw/state", ".cclaw/rules", ".cclaw/agents", ".cclaw/hooks", ".cclaw/skills/review-prompts"];
+export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/templates", ".cclaw/templates/state-contracts", ".cclaw/artifacts", ".cclaw/wave-plans", ".cclaw/archive", ".cclaw/state", ".cclaw/rules", ".cclaw/agents", ".cclaw/hooks", ".cclaw/skills/review-prompts"];
 export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".agents/skills/cc/SKILL.md", ".agents/skills/cc-*/SKILL.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
 /**
  * Canonical stage -> skill folder mapping.

package/dist/constants.js

@@ -59,6 +59,7 @@ export const REQUIRED_DIRS = [
     `${RUNTIME_ROOT}/templates`,
     `${RUNTIME_ROOT}/templates/state-contracts`,
     `${RUNTIME_ROOT}/artifacts`,
+    `${RUNTIME_ROOT}/wave-plans`,
     `${RUNTIME_ROOT}/archive`,
     `${RUNTIME_ROOT}/state`,
     `${RUNTIME_ROOT}/rules`,

package/dist/content/closeout-guidance.d.ts

@@ -4,7 +4,7 @@
  * Keep closeout chain and ship substate language in one place across command
  * contracts, skills, and stage/docs surfaces.
  */
-export declare const CLOSEOUT_CHAIN = "retro -> compound -> archive";
+export declare const CLOSEOUT_CHAIN = "post_ship_review -> archive";
 export declare const CLOSEOUT_SUBSTATE_KEY = "closeout.shipSubstate";
 export declare function closeoutChainInline(): string;
 export declare function closeoutSubstateInline(): string;

package/dist/content/closeout-guidance.js

@@ -4,7 +4,7 @@
  * Keep closeout chain and ship substate language in one place across command
  * contracts, skills, and stage/docs surfaces.
  */
-export const CLOSEOUT_CHAIN = "retro -> compound -> archive";
+export const CLOSEOUT_CHAIN = "post_ship_review -> archive";
 export const CLOSEOUT_SUBSTATE_KEY = "closeout.shipSubstate";
 export function closeoutChainInline() {
     return `\`${CLOSEOUT_CHAIN}\``;
@@ -18,18 +18,17 @@ export function closeoutNextCommandGuidance() {
 export function closeoutSubstateProtocolBullets() {
     return `When \`currentStage === "ship"\`, route by **${closeoutSubstateInline()}**:
   - \`"idle"\` or missing -> outcome: initialize closeout by setting
-    ${closeoutSubstateInline()} = \`"retro_review"\`, then continue \`/cc\`
+    ${closeoutSubstateInline()} = \`"post_ship_review"\`, then continue \`/cc\`
     into the in-stage retro protocol (draft + one structured accept/edit/skip ask).
-  - \`"retro_review"\` -> outcome: finish retro acceptance/edit/skip and advance
-    closeout; the draft already exists, so continue it and do not regenerate it.
-  - \`"compound_review"\` -> outcome: execute the in-stage compound closeout scan
-    (not \`ce:compound\`) and advance toward archive readiness:
+  - \`"post_ship_review"\` -> outcome: execute the unified post-ship closeout leg
+    (retro acceptance/edit/skip + in-stage compound scan, not \`ce:compound\`)
+    and advance toward archive readiness:
     read \`.cclaw/state/compound-readiness.json\` plus the relevant tail of
     \`.cclaw/knowledge.jsonl\`, assess overlap before adding duplicate knowledge,
     separate bug-track learnings (turn into rules/tests/remediation) from
-    knowledge-track learnings (durable project/process guidance), and use
-    lightweight \`supersedes\` / \`superseded_by\` fields when refreshing stale or
-    partially replaced entries. Optionally ask whether to scan Cursor/Claude/Codex
+    knowledge-track learnings (durable project/process guidance), and refresh stale
+    guidance in place instead of introducing extra lineage metadata. Optionally ask
+    whether to scan Cursor/Claude/Codex
     session transcripts for matching historical learnings; only do it after opt-in.
     Ask **one** structured question (apply / skip) per candidate cluster or a
     single accept-all / skip choice, then advance substate.
@@ -38,8 +37,8 @@ export function closeoutSubstateProtocolBullets() {
   - \`"archived"\` (transient) -> outcome: report "run archived" and stop (flow complete).`;
 }
 export function closeoutFlowMapSentence() {
-    return `The first stage names are the critical path. \`retro\`, \`compound\`, and \`archive\` are post-ship closeout substates under ${closeoutSubstateInline()}, not separate stage schemas or commands. Continue them with \`/cc\`; do not route compound closeout through \`ce:compound\`.`;
+    return `The first stage names are the critical path. \`post_ship_review\` and \`archive\` are post-ship closeout substates under ${closeoutSubstateInline()}, not separate stage schemas or commands. Continue them with \`/cc\`; do not route compound closeout through \`ce:compound\`.`;
 }
 export function closeoutProtocolBehaviorSentence() {
-    return `Keep decision, completion, and preamble discipline inline: ask only decision-changing questions, verify gates before advancing, and keep context compact. After \`ship\`, keep using \`/cc\` through ${closeoutChainInline()}; do not route normal closeout through \`ce:compound\` or a separate operations command. In compound closeout, assess overlap before appending knowledge: refresh recurring bug-track learnings as actionable rules/tests, keep knowledge-track learnings as durable process/project guidance, and mark outdated entries with lightweight \`supersedes\` / \`superseded_by\` fields instead of building a new doc system.`;
+    return `Keep decision, completion, and preamble discipline inline: ask only decision-changing questions, verify gates before advancing, and keep context compact. After \`ship\`, keep using \`/cc\` through ${closeoutChainInline()}; do not route normal closeout through \`ce:compound\` or a separate operations command. Inside \`post_ship_review\`, assess overlap before appending knowledge: refresh recurring bug-track learnings as actionable rules/tests and keep knowledge-track learnings as durable process/project guidance without extra lineage metadata.`;
 }

package/dist/content/core-agents.d.ts

@@ -15,6 +15,8 @@ export interface AgentReturnSchema {
     requiredFields: string[];
     /** Fields that must cite artifact anchors, commands, or code locations when applicable. */
     evidenceFields: string[];
+    /** Additional optional fields allowed for specific agent contracts. */
+    optionalFields?: string[];
 }
 export interface AgentDefinition {
     /** Kebab-case identifier, e.g. `"reviewer"`. */
@@ -62,21 +64,21 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
-    readonly name: "product-manager";
-    readonly description: "PROACTIVE during brainstorm/scope when product value, persona/JTBD, success metric, or why-now framing is unclear. Use for product discovery, not implementation.";
+    readonly name: "product-discovery";
+    readonly description: "MANDATORY during brainstorm and PROACTIVE during scope when value framing or expansion strategy needs product-level discovery pressure.";
     readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
-    readonly model: "balanced";
-    readonly activation: "proactive";
+    readonly model: "deep";
+    readonly activation: "mandatory";
     readonly relatedStages: ["brainstorm", "scope"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
-    readonly name: "product-strategist";
-    readonly description: "PROACTIVE during scope. MUST BE USED when selected scope mode is SCOPE EXPANSION or SELECTIVE EXPANSION to pressure-test 10x vision, strategic upside, and long-term trajectory before lock.";
+    readonly name: "divergent-thinker";
+    readonly description: "PROACTIVE before planner/critic convergence when brainstorm or scope needs option-space expansion and alternative framings.";
     readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
-    readonly model: "deep";
+    readonly model: "balanced";
     readonly activation: "proactive";
-    readonly relatedStages: ["scope"];
+    readonly relatedStages: ["brainstorm", "scope"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
@@ -90,11 +92,11 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly body: string;
 }, {
     readonly name: "architect";
-    readonly description: "MANDATORY during design. MUST BE USED to validate architecture boundaries, alternatives, failure modes, rollout, and spec handoff before implementation.";
+    readonly description: "MANDATORY during design and final ship verification. MUST BE USED to validate architecture boundaries, alternatives, failure modes, rollout, and cross-stage cohesion before release.";
     readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
     readonly model: "deep";
     readonly activation: "mandatory";
-    readonly relatedStages: ["design"];
+    readonly relatedStages: ["design", "ship"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
@@ -116,39 +118,39 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
-    readonly name: "reviewer";
-    readonly description: "MANDATORY during review. MUST BE USED to run a two-pass audit: spec compliance first, then correctness/maintainability/performance/architecture.";
+    readonly name: "coherence-reviewer";
+    readonly description: "PROACTIVE during spec/plan/design when internal consistency must be validated across sections, terminology, references, and dependency narratives.";
     readonly tools: ["Read", "Grep", "Glob"];
     readonly model: "balanced";
-    readonly activation: "mandatory";
-    readonly relatedStages: ["spec", "review", "ship"];
+    readonly activation: "proactive";
+    readonly relatedStages: ["spec", "plan", "design"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
-    readonly name: "performance-reviewer";
-    readonly description: "PROACTIVE during review for hot paths, IO, data volume, caching, rendering, or algorithmic cost changes. Produces no-impact rationale when clean.";
+    readonly name: "scope-guardian-reviewer";
+    readonly description: "PROACTIVE during scope/plan/design when complexity growth, scope drift, or unnecessary abstraction risk needs a dedicated challenge pass.";
     readonly tools: ["Read", "Grep", "Glob"];
     readonly model: "balanced";
     readonly activation: "proactive";
-    readonly relatedStages: ["review"];
+    readonly relatedStages: ["scope", "plan", "design"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
-    readonly name: "compatibility-reviewer";
-    readonly description: "PROACTIVE during design/review when public APIs, config, persisted data, CLI behavior, generated clients, or dependency versions may change.";
+    readonly name: "feasibility-reviewer";
+    readonly description: "PROACTIVE during plan/design when resource, runtime, environment, dependency, or rollout assumptions can make the solution non-viable.";
     readonly tools: ["Read", "Grep", "Glob"];
     readonly model: "balanced";
     readonly activation: "proactive";
-    readonly relatedStages: ["design", "review"];
+    readonly relatedStages: ["plan", "design"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
-    readonly name: "observability-reviewer";
-    readonly description: "PROACTIVE during design/review when diagnosis, telemetry, rollout visibility, or supportability could affect safe operation.";
+    readonly name: "reviewer";
+    readonly description: "MANDATORY during review. MUST BE USED to run a two-pass audit with explicit inline lens coverage for performance, compatibility, and observability.";
     readonly tools: ["Read", "Grep", "Glob"];
     readonly model: "balanced";
-    readonly activation: "proactive";
-    readonly relatedStages: ["design", "review"];
+    readonly activation: "mandatory";
+    readonly relatedStages: ["spec", "review", "ship"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
@@ -160,6 +162,15 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly relatedStages: ["design", "review", "ship"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
+}, {
+    readonly name: "integration-overseer";
+    readonly description: "ON-DEMAND after TDD fan-out to verify cross-slice cohesion contract integrity, integration surfaces, and shared invariants before review handoff.";
+    readonly tools: ["Read", "Grep", "Glob"];
+    readonly model: "balanced";
+    readonly activation: "on-demand";
+    readonly relatedStages: ["tdd", "review"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
 }, {
     readonly name: "test-author";
     readonly description: "MANDATORY in TDD stage. MUST BE USED for RED -> GREEN -> REFACTOR with evidence-first discipline.";
@@ -196,15 +207,6 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly relatedStages: ["tdd"];
     readonly returnSchema: AgentReturnSchema;
     readonly body: string;
-}, {
-    readonly name: "implementer";
-    readonly description: "ON-DEMAND worker for one scoped implementation slice. Use only with self-contained task text, explicit file boundaries, and verification expectations.";
-    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"];
-    readonly model: "balanced";
-    readonly activation: "on-demand";
-    readonly relatedStages: ["tdd"];
-    readonly returnSchema: AgentReturnSchema;
-    readonly body: string;
 }, {
     readonly name: "fixer";
     readonly description: "ON-DEMAND fresh worker after review FAIL/PARTIAL evidence. Must fix only the cited criterion within explicit allowed files.";
@@ -221,9 +223,6 @@ export declare const CCLAW_AGENTS: readonly [{
  * and typos instead of letting them slip into generated artifacts.
  */
 export type AgentName = (typeof CCLAW_AGENTS)[number]["name"];
-/**
- * Render a complete cclaw agent markdown file (YAML frontmatter + body).
- */
 export declare function agentMarkdown(agent: AgentDefinition): string;
 /**
  * Markdown table mapping cclaw stage entry points to specialist agents.