cclaw-cli 0.55.2 → 1.0.0

package/dist/content/subagents.js

@@ -5,27 +5,6 @@ import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
  * specialist payloads. Cclaw materializes static instructions — this module does not
  * execute orchestration logic at install time beyond string assembly.
  */
-const SUBAGENT_AGENT_NAMES = [
-    "researcher",
-    "architect",
-    "spec-validator",
-    "spec-document-reviewer",
-    "slice-implementer",
-    "performance-reviewer",
-    "compatibility-reviewer",
-    "observability-reviewer",
-    "release-reviewer",
-    "planner",
-    "product-manager",
-    "product-strategist",
-    "critic",
-    "reviewer",
-    "security-reviewer",
-    "test-author",
-    "doc-updater",
-    "implementer",
-    "fixer"
-];
 const MARKDOWN_CODE_FENCE = "```";
 function formatAgentList(agents) {
     return agents.length > 0 ? agents.join(", ") : "none";
@@ -145,8 +124,8 @@ Concrete per-stage rules so the controller does not have to guess which tier fit
 
 | Stage | Deep slot | Balanced slot(s) | Fast fan-out | Trigger to escalate |
 |---|---|---|---|---|
-| brainstorm | planner (only if ambiguity spans >1 module) | product-manager / critic when product value or premise is uncertain | run in-thread research playbooks | promote to \`balanced\` critic if the do-nothing path may beat the idea |
-| scope | planner (always) | product-manager / product-strategist / critic when mode changes value, trajectory, or boundaries | run \`research/git-history.md\` in-thread when churn is high | promote to \`balanced\` critic if scope mode is disputed |
+| brainstorm | planner (only if ambiguity spans >1 module) | product-discovery / critic when product value or premise is uncertain | run in-thread research playbooks | promote to \`balanced\` critic if the do-nothing path may beat the idea |
+| scope | planner (always) | product-discovery / critic when mode changes value, trajectory, or boundaries | run \`research/git-history.md\` in-thread when churn is high | promote to \`balanced\` critic if scope mode is disputed |
 | design | planner (always) | critic, security-reviewer, test-author when alternatives/trust/testability apply | run \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` in-thread | escalate one specialist to \`deep\` only if a failure mode is Critical-severity |
 | spec | — | spec-validator / spec-document-reviewer / reviewer (for long or high-risk specs) | — | escalate to \`deep\` only for spec ↔ design contradictions |
 | plan | planner (solo, always) | — | — | never fan out at plan stage; one owner for dependency graph |
@@ -176,6 +155,7 @@ Borrow the good part of Team/Ruflo-style orchestration without adding a swarm ru
 - **No parallel writes to adjacent surfaces.** If tasks may touch the same module, serialize them.
 - **Checkpoint before synthesis.** Each agent returns status, files inspected/changed, evidence, and blockers before the parent acts.
 - **Consensus is for hard calls only.** Use two reviewers when severity or architecture is disputed; otherwise one evidence-backed reviewer is enough.
+- **Multi-wave persistence uses the executing-waves skill.** For 2+ wave efforts, maintain \`.cclaw/wave-plans/\` and run carry-forward drift audits in brainstorm.
 
 ## Parallelization Decision Gate
 
@@ -406,6 +386,8 @@ ${conversationLanguagePolicyMarkdown()}
 
 Implementation that touches shared source trees must remain **sequential** unless you have proven disjoint filesystem ownership (rare) and an explicit merge protocol.
 
+When explicit bounded TDD fan-out is approved with parallel \`slice-implementer\` lanes, author \`.cclaw/artifacts/cohesion-contract.md\` + \`.json\` before launch and run \`integration-overseer\` after fan-in.
+
 ## When to Use
 
 - **Independent investigations** (perf vs correctness vs dependency hygiene) with separated code neighborhoods.
@@ -429,11 +411,13 @@ Implementation that touches shared source trees must remain **sequential** unles
 ## Dispatch Protocol
 
 1. **Identify independent problem domains** (no file overlap; no shared mutable working assumptions).
-2. **Craft one prompt per domain** with **full context pasted** — same HARD-GATE as SDD: no “go read X to learn why.”
-3. **Launch ALL agents in a single controller message** (multiple Task tool calls) so they start with comparable timelines.
-4. **Wait for all to return** before synthesis (avoid incremental confirmation bias).
-5. **Reconcile results:** deduplicate findings, merge overlaps, and **conflict-check** contradictions explicitly.
-6. **Run the full test suite after any code changes** — parallel analysis may propose edits; verification stays mandatory.
+2. **Author cohesion contract first** whenever fan-out touches shared interfaces or bounded parallel \`slice-implementer\` lanes.
+3. **Craft one prompt per domain** with **full context pasted** — same HARD-GATE as SDD: no “go read X to learn why.”
+4. **Launch ALL agents in a single controller message** (multiple Task tool calls) so they start with comparable timelines.
+5. **Wait for all to return** before synthesis (avoid incremental confirmation bias).
+6. **Run integration-overseer after fan-in** to verify touchpoints, boundary types, invariants, and integration-test outcomes.
+7. **Reconcile results:** deduplicate findings, merge overlaps, and **conflict-check** contradictions explicitly.
+8. **Run the full test suite after any code changes** — parallel analysis may propose edits; verification stays mandatory.
 
 ## Review Army Pattern (gstack)
 
@@ -1009,60 +993,6 @@ ${MARKDOWN_CODE_FENCE}
 
 `;
 }
-/**
- * Returns markdown fragments augmenting each specialist persona with Task tool
- * delegation guidance. Combine with the existing `body` field from `core-agents.ts`.
- */
-export function enhancedAgentBody(agentName) {
-    switch (agentName) {
-        case "researcher":
-            return researcherEnhancedBody();
-        case "architect":
-            return architectEnhancedBody();
-        case "spec-validator":
-            return specValidatorEnhancedBody();
-        case "spec-document-reviewer":
-            return specDocumentReviewerEnhancedBody();
-        case "slice-implementer":
-            return sliceImplementerEnhancedBody();
-        case "performance-reviewer":
-            return performanceReviewerEnhancedBody();
-        case "compatibility-reviewer":
-            return compatibilityReviewerEnhancedBody();
-        case "observability-reviewer":
-            return observabilityReviewerEnhancedBody();
-        case "release-reviewer":
-            return releaseReviewerEnhancedBody();
-        case "planner":
-            return plannerEnhancedBody();
-        case "product-manager":
-            return productManagerEnhancedBody();
-        case "product-strategist":
-            return productStrategistEnhancedBody();
-        case "critic":
-            return criticEnhancedBody();
-        case "reviewer":
-            return reviewerEnhancedBody();
-        case "security-reviewer":
-            return securityReviewerEnhancedBody();
-        case "test-author":
-            return testAuthorEnhancedBody();
-        case "doc-updater":
-            return docUpdaterEnhancedBody();
-        case "implementer":
-            return implementerEnhancedBody();
-        case "fixer":
-            return fixerEnhancedBody();
-        default:
-            return `
-
-## Task Tool Delegation
-
-_No enhanced Task template is defined for agent \`${agentName}\`._
-
-`;
-    }
-}
 export function subagentsAgentsMdBlock() {
     return `### Subagent Orchestration
 

package/dist/content/templates.js

@@ -1021,6 +1021,76 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 ## Learnings
 - None this stage.
+`,
+    "cohesion-contract.md": `${artifactFrontmatter("tdd")}
+
+# Cohesion Contract — <wave / stage / topic>
+
+## Shared Types & Interfaces
+| Symbol | Path | Signature | Owner slice |
+|---|---|---|---|
+|  |  |  |  |
+
+## Naming Conventions
+- 
+
+## Invariants
+- 
+
+## Integration Touchpoints
+| From slice | To slice | Surface | Integration test name |
+|---|---|---|---|
+|  |  |  |  |
+
+## Behavior Specifications per Slice
+### Slice <n>: <description>
+- test: <name>
+  assert: <one-line assertion>
+  surface: <public interface>
+
+## Status
+| Slice | Implemented | Tests pass | Cohesion verified |
+|---|---|---|---|
+| S-1 | no | no | no |
+
+## Learnings
+- None this stage.
+`,
+    "cohesion-contract.json": `{
+  "version": 1,
+  "sharedTypes": [
+    {
+      "symbol": "",
+      "path": "",
+      "signature": "",
+      "ownerSlice": ""
+    }
+  ],
+  "touchpoints": [
+    {
+      "fromSlice": "",
+      "toSlice": "",
+      "surface": "",
+      "integrationTestName": ""
+    }
+  ],
+  "slices": [
+    {
+      "sliceId": "S-1",
+      "description": "",
+      "test": "",
+      "assert": "",
+      "surface": "",
+      "implemented": false,
+      "testsPass": false,
+      "cohesionVerified": false
+    }
+  ],
+  "status": {
+    "overall": "pending",
+    "notes": ""
+  }
+}
 `,
     "07-review.md": `${artifactFrontmatter("review")}
 
@@ -1094,6 +1164,12 @@ Execution rule: complete and verify each batch before starting the next batch.
 | R-1 | Critical/Important/Suggestion | correctness/security/performance/architecture/external-safety | path:line |  | open/resolved |
 - NO_FINDINGS_ATTESTATION: <required when no findings are reported; cite inspected coverage>
 
+## Lens Coverage
+- Performance: NO_IMPACT | FOUND_<n>
+- Compatibility: NO_IMPACT | FOUND_<n>
+- Observability: NO_IMPACT | FOUND_<n>
+- Security: routed to security-reviewer (always separate)
+
 ## Security Sweep Attestation
 - Result: findings | NO_CHANGE_ATTESTATION | NO_SECURITY_IMPACT
 - Inspected surfaces:
@@ -1115,7 +1191,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)
+- Victory Detector: pass | fail (Layer 1, Layer 2, security sweep, structured findings, acceptance/reproduction coverage 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
@@ -1130,11 +1206,10 @@ Execution rule: complete and verify each batch before starting the next batch.
 - Adversarial review: not triggered | pass | fail
 - Overall: complete | concerns | blocked
 
-## Trace Matrix Check
-- Command: \`npx cclaw-cli internal trace-matrix\` when the active track enforces it; otherwise record direct AC/reproduction-slice coverage.
-- Orphaned criteria: 0
-- Orphaned source items: 0 or \`N/A - direct spec/reproduction coverage\`
-- Orphaned tests: 0
+## Coverage Check
+- AC/source-item/slice coverage rationale:
+- Orphaned source items: none | explain gap
+- Orphaned tests: none | explain gap
 - Evidence ref:
 
 ## Verification Command Discovery
@@ -1209,6 +1284,12 @@ Execution rule: complete and verify each batch before starting the next batch.
 - Type-check:
 - Working tree clean:
 
+## Architect Cross-Stage Verification
+- Skill: architect-cross-stage-verification
+- Result: CROSS_STAGE_VERIFIED | DRIFT_DETECTED | BLOCKED
+- Evidence refs:
+- Drift summary:
+
 ## Base Branch Determination
 - Command run: \`git merge-base HEAD main || git merge-base HEAD master\`
 - Base branch:

package/dist/content/utility-skills.js

@@ -5,128 +5,57 @@
 export function languageTypescriptSkill() {
     return `---
 name: language-typescript
-description: "TypeScript rule pack. Opt-in language lens. Use when reviewing or writing TypeScript/JavaScript diffs during tdd or review — enforces type-safety, runtime-boundary validation, and idiomatic patterns."
+description: "TypeScript rule pack. Compact opt-in lens for tdd/review when diffs touch TS/JS files."
 ---
 
 # TypeScript Rule Pack
 
-## Quick Start
-
-> 1. Activate during tdd or review whenever the diff touches \`.ts\`, \`.tsx\`, \`.mts\`, \`.cts\`, or \`.js\` files.
-> 2. Walk the rule tiers in order. Tier-1 violations block merge. Tier-2 need a named follow-up.
-> 3. Cite each finding as \`file:line — <rule id> — <one-line remediation>\`.
-
-## HARD-GATE
-
-Do not approve a TypeScript change that ships \`any\`, \`@ts-ignore\`, or
-\`@ts-expect-error\` *without* (a) a comment explaining why, (b) a linked issue,
-and (c) an assertion that the blast radius is bounded to the current file.
-No exceptions in production code paths.
-
-## Tier 1 — blocking rules
-
-1. **No silent \`any\`.** Unknown inputs must be typed as \`unknown\` first, then narrowed.
-2. **Runtime validate trust boundaries.** HTTP bodies, env vars, file contents, and
-   IPC payloads must be parsed through a schema validator (zod, valibot, io-ts) before
-   being treated as typed data.
-3. **No \`as\` without a narrowing reason.** \`value as Foo\` is only acceptable when
-   preceded by a runtime check that proves the shape (e.g. \`if ("id" in value)\`).
-4. **Exhaustive switches on discriminated unions.** Every \`switch\` on a tagged
-   union must end with a \`default\` branch that assigns to \`never\` to surface
-   missing cases at compile time.
-5. **Promise hygiene.** No unawaited promises in \`async\` functions; no
-   \`void promise\` unless documented. Use \`@typescript-eslint/no-floating-promises\`.
-6. **Null-safety at the boundary.** Optional chaining (\`?.\`) and nullish
-   coalescing (\`??\`) must only be used when the null path is handled, not as a
-   silent default.
+Use this only when a diff includes \`.ts\`, \`.tsx\`, \`.mts\`, \`.cts\`, or \`.js\`.
 
-## Tier 2 — follow-up rules
+## Blocking rules
 
-7. Prefer \`readonly\` for arrays/object fields that are not mutated.
-8. Prefer \`type\` aliases for unions, \`interface\` for extendable object shapes.
-9. Name generic parameters descriptively once they carry semantic meaning (\`TEvent\`, \`TPayload\`).
-10. Avoid re-exporting entire namespaces; named re-exports keep bundle analysis tractable.
-11. Co-locate test fixtures with their types to keep drift visible.
+1. **No silent \`any\` or blanket \`@ts-ignore\`.** Unknown input starts as \`unknown\` and gets narrowed.
+2. **Validate trust boundaries at runtime.** HTTP/env/file/IPC payloads require schema parse before typed use.
+3. **No floating promises.** Await promises or explicitly document fire-and-forget behavior.
+4. **Exhaustive union handling.** Discriminated-union switches must fail loudly on missing branches.
 
-## Anti-patterns
+## Follow-up rules
 
-- "It compiles, ship it" — compilation is necessary, not sufficient. Runtime boundary validation is the gate.
-- Casting library return types to tighten them without reading the library's actual contract.
-- Wrapping every function in \`try/catch\` and swallowing the error — errors must either be rethrown typed or mapped to a Result/Either shape.
-- Using enums where a string-literal union would do (enums carry runtime cost and erase at tree-shaking time only when \`const\`).
+- Prefer immutable/readonly data by default.
+- Keep types local and explicit at module boundaries.
+- Add/adjust tests when changing inferred public behavior.
 
-## Review output shape
+## Output format
 
-\`\`\`
-- **Rule:** T1-2 (runtime validate trust boundaries)
-- **File:line:** src/api/users.ts:42
-- **Finding:** POST body cast directly to \`UserCreateInput\`; no schema parse.
-- **Remediation:** Parse through \`userCreateSchema\` (zod) before passing to the service layer.
-\`\`\`
+\`file:line — rule id — concise remediation\`
 `;
 }
 export function languagePythonSkill() {
     return `---
 name: language-python
-description: "Python rule pack. Opt-in language lens. Use when reviewing or writing Python diffs during tdd or review — enforces typing, exception hygiene, and idiomatic patterns."
+description: "Python rule pack. Compact opt-in lens for tdd/review when diffs touch Python files."
 ---
 
 # Python Rule Pack
 
-## Quick Start
-
-> 1. Activate during tdd or review whenever the diff touches \`.py\` / \`.pyi\` files.
-> 2. Walk the rule tiers in order. Tier-1 violations block merge. Tier-2 need a named follow-up.
-> 3. Cite each finding as \`file:line — <rule id> — <one-line remediation>\`.
-
-## HARD-GATE
-
-Do not approve a Python change that catches bare \`except:\` or \`except Exception:\`
-in production code *without* (a) re-raising, (b) logging with \`logger.exception\`, or
-(c) a comment explaining the intentional swallow. Silent broad catches are the
-single biggest source of "works on my machine" bugs in Python services.
-
-## Tier 1 — blocking rules
-
-1. **Type hints on public APIs.** Every exported function, method, and dataclass
-   must have full type hints. Use \`from __future__ import annotations\` or PEP 604 union syntax.
-2. **No mutable default arguments.** \`def f(x=[])\` is a bug. Use \`None\` + inline default.
-3. **Exception specificity.** Catch the narrowest exception class you actually handle.
-4. **Context managers for resources.** Files, sockets, DB sessions, locks — always \`with\`.
-5. **No bare \`assert\` in production code.** \`assert\` is stripped under \`python -O\`.
-   For invariants, raise \`ValueError\`/\`RuntimeError\` explicitly.
-6. **Deterministic imports.** No conditional imports at module top level except for
-   platform branches; no import-time side effects.
-
-## Tier 2 — follow-up rules
-
-7. Prefer \`@dataclass(slots=True, frozen=True)\` for value objects.
-8. Prefer \`pathlib.Path\` over \`os.path\` for new code.
-9. Use f-strings for interpolation; reserve \`%\` and \`.format\` for logger messages (lazy eval).
-10. Use \`logging.getLogger(__name__)\` per module; never the root logger.
-11. Pin dependency ranges in \`pyproject.toml\`; lock with \`uv lock\` / \`pip-compile\`.
+Use this only when a diff includes \`.py\` / \`.pyi\`.
 
-## Async-specific
+## Blocking rules
 
-- Do not mix \`requests\`/sync I/O inside \`async def\`. Use \`httpx.AsyncClient\` / \`aiofiles\`.
-- \`asyncio.gather\` with \`return_exceptions=False\` cancels siblings on first failure — be explicit.
-- Every task created with \`asyncio.create_task\` must have its reference kept and awaited.
+1. **No broad silent catches.** Avoid bare \`except\` / \`except Exception\` unless re-raised or justified.
+2. **No mutable defaults.** Use \`None\` + local initialization.
+3. **Type exported surfaces.** Public functions/classes include clear type hints.
+4. **Resource safety by default.** File/DB/network handles use context managers.
 
-## Anti-patterns
+## Follow-up rules
 
-- Using \`**kwargs\` to avoid writing a real signature.
-- Monkey-patching modules from tests without a \`contextlib.contextmanager\` cleanup.
-- Treating \`__init__.py\` as a place to run logic (imports only).
-- Re-inventing \`itertools\`/\`functools\` instead of using stdlib.
+- Prefer explicit, narrow exceptions.
+- Keep async and sync I/O models separated.
+- Add/adjust tests with behavior changes.
 
-## Review output shape
+## Output format
 
-\`\`\`
-- **Rule:** P1-3 (exception specificity)
-- **File:line:** users/service.py:88
-- **Finding:** \`except Exception\` around DB call silently drops integrity errors.
-- **Remediation:** Catch \`IntegrityError\` explicitly; re-raise everything else.
-\`\`\`
+\`file:line — rule id — concise remediation\`
 `;
 }
 export function languageGoSkill() {

package/dist/flow-state.d.ts

@@ -32,14 +32,13 @@ export interface RetroState {
 /**
  * Ship closeout substate machine.
  *
- * After ship completes, cclaw auto-chains retro → compound → archive.
+ * After ship completes, cclaw auto-chains post-ship review → archive.
  * Each step is interruptible: `/cc` reads `shipSubstate` and resumes
  * from the correct step even across sessions.
  *
  * - `idle` — ship not complete, or closeout not yet started.
- * - `retro_review` — 09-retro.md draft exists; awaiting user edit/accept/skip.
- * - `compound_review` — retro accepted; compound pass awaiting execution
- *   (or user skip).
+ * - `post_ship_review` — unified closeout leg: retro acceptance/edit/skip
+ *   plus compound pass execution (or explicit skip).
  * - `ready_to_archive` — retro + compound done; archive is the next
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive
@@ -53,7 +52,7 @@ export interface RetroState {
  * These are not duplicates: `done` lives in stage transitions; `archived` /
  * `idle` live in closeout lifecycle state.
  */
-export declare const SHIP_SUBSTATES: readonly ["idle", "retro_review", "compound_review", "ready_to_archive", "archived"];
+export declare const SHIP_SUBSTATES: readonly ["idle", "post_ship_review", "ready_to_archive", "archived"];
 export type ShipSubstate = (typeof SHIP_SUBSTATES)[number];
 export interface CloseoutState {
     shipSubstate: ShipSubstate;
@@ -85,7 +84,7 @@ export interface FlowState {
     rewinds: RewindRecord[];
     /** Mandatory retrospective gate status before archive. */
     retro: RetroState;
-    /** Ship → retro → compound → archive substate for resumable closeout. */
+    /** Ship → post_ship_review → archive substate for resumable closeout. */
     closeout: CloseoutState;
 }
 export interface InitialFlowStateOptions {

package/dist/flow-state.js

@@ -5,14 +5,13 @@ export const FLOW_STATE_SCHEMA_VERSION = 1;
 /**
  * Ship closeout substate machine.
  *
- * After ship completes, cclaw auto-chains retro → compound → archive.
+ * After ship completes, cclaw auto-chains post-ship review → archive.
  * Each step is interruptible: `/cc` reads `shipSubstate` and resumes
  * from the correct step even across sessions.
  *
  * - `idle` — ship not complete, or closeout not yet started.
- * - `retro_review` — 09-retro.md draft exists; awaiting user edit/accept/skip.
- * - `compound_review` — retro accepted; compound pass awaiting execution
- *   (or user skip).
+ * - `post_ship_review` — unified closeout leg: retro acceptance/edit/skip
+ *   plus compound pass execution (or explicit skip).
  * - `ready_to_archive` — retro + compound done; archive is the next
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive
@@ -28,8 +27,7 @@ export const FLOW_STATE_SCHEMA_VERSION = 1;
  */
 export const SHIP_SUBSTATES = [
     "idle",
-    "retro_review",
-    "compound_review",
+    "post_ship_review",
     "ready_to_archive",
     "archived"
 ];

package/dist/gate-evidence.d.ts

@@ -29,37 +29,6 @@ export interface CompletedStagesClosureResult {
         blocked: string[];
     }>;
 }
-export declare const RECONCILIATION_NOTICES_REL_PATH = ".cclaw/state/reconciliation-notices.json";
-export type ReconciliationNoticeKind = "gate_demotion" | "closeout_substate_demotion";
-export interface CloseoutSubstateDemotionPayload {
-    previous: string;
-    next: string;
-    reason: string;
-}
-export interface ReconciliationNotice {
-    id: string;
-    runId: string;
-    stage: FlowStage;
-    gateId: string;
-    reason: string;
-    demotedAt: string;
-    kind?: ReconciliationNoticeKind;
-    payload?: CloseoutSubstateDemotionPayload;
-}
-export interface ReconciliationNoticesPayload {
-    schemaVersion: number;
-    notices: ReconciliationNotice[];
-    parseOk: boolean;
-    schemaOk: boolean;
-}
-export interface ReconciliationNoticeBuckets {
-    activeBlocked: ReconciliationNotice[];
-    currentStageBlocked: ReconciliationNotice[];
-    unsynced: ReconciliationNotice[];
-    staleRun: ReconciliationNotice[];
-}
-export declare function readReconciliationNotices(projectRoot: string): Promise<ReconciliationNoticesPayload>;
-export declare function classifyReconciliationNotices(flowState: FlowState, notices: ReconciliationNotice[]): ReconciliationNoticeBuckets;
 export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState): Promise<GateEvidenceCheckResult>;
 export declare function verifyCompletedStagesGateClosure(flowState: FlowState): CompletedStagesClosureResult;
 export interface GateReconciliationResult {