cclaw-cli 0.48.0 → 0.48.2

package/dist/artifact-linter.d.ts

@@ -1,4 +1,4 @@
-import { type FlowStage } from "./types.js";
+import { type FlowStage, type FlowTrack } from "./types.js";
 export interface LintFinding {
     section: string;
     required: boolean;
@@ -46,7 +46,7 @@ export interface LearningsParseResult {
     details: string;
 }
 export declare function parseLearningsSection(sectionBody: string): LearningsParseResult;
-export declare function lintArtifact(projectRoot: string, stage: FlowStage): Promise<LintResult>;
+export declare function lintArtifact(projectRoot: string, stage: FlowStage, track?: FlowTrack): Promise<LintResult>;
 export declare function validateReviewArmy(projectRoot: string): Promise<{
     valid: boolean;
     errors: string[];

package/dist/artifact-linter.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RUNTIME_ROOT } from "./constants.js";
+import { RUNTIME_ROOT, SHIP_FINALIZATION_MODES } from "./constants.js";
 import { exists } from "./fs-utils.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { FLOW_STAGES } from "./types.js";
@@ -137,13 +137,7 @@ function tokensFromRule(rule) {
         return [...new Set(allCaps)];
     }
     if (/finalization enum token/iu.test(rule)) {
-        return [
-            "FINALIZE_MERGE_LOCAL",
-            "FINALIZE_OPEN_PR",
-            "FINALIZE_KEEP_BRANCH",
-            "FINALIZE_DISCARD_BRANCH",
-            "FINALIZE_NO_VCS"
-        ];
+        return [...SHIP_FINALIZATION_MODES];
     }
     if (/final verdict/iu.test(rule)) {
         return ["APPROVED", "APPROVED_WITH_CONCERNS", "BLOCKED"];
@@ -795,8 +789,8 @@ function validateSectionBody(sectionBody, rule, sectionName) {
         details: "Section heading and content satisfy lint heuristics."
     };
 }
-export async function lintArtifact(projectRoot, stage) {
-    const schema = stageSchema(stage);
+export async function lintArtifact(projectRoot, stage, track = "standard") {
+    const schema = stageSchema(stage, track);
     const { absPath: absFile, relPath: relFile } = await resolveArtifactPath(projectRoot, schema.artifactFile);
     const findings = [];
     if (!(await exists(absFile))) {

package/dist/constants.d.ts

@@ -3,6 +3,12 @@ import type { FlowStage, HarnessId } from "./types.js";
 export declare const RUNTIME_ROOT = ".cclaw";
 export declare const CCLAW_VERSION: string;
 export declare const FLOW_VERSION = "1.0.0";
+/**
+ * Canonical ship finalization enums used across stage schema, linting, and
+ * runtime gate evidence checks.
+ */
+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[];
 /**
  * Evals subtree. Scaffolds the directory layout and a default config.yaml; the

package/dist/constants.js

@@ -35,6 +35,17 @@ function readPackageVersion() {
 }
 export const CCLAW_VERSION = readPackageVersion();
 export const FLOW_VERSION = "1.0.0";
+/**
+ * Canonical ship finalization enums used across stage schema, linting, and
+ * runtime gate evidence checks.
+ */
+export const SHIP_FINALIZATION_MODES = [
+    "FINALIZE_MERGE_LOCAL",
+    "FINALIZE_OPEN_PR",
+    "FINALIZE_KEEP_BRANCH",
+    "FINALIZE_DISCARD_BRANCH",
+    "FINALIZE_NO_VCS"
+];
 export const DEFAULT_HARNESSES = [
     "claude",
     "cursor",

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

@@ -24,8 +24,60 @@ export interface AgentDefinition {
 }
 /**
  * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ *
+ * Declared with `satisfies` so the array retains literal `name` types for
+ * downstream type-level consumers (e.g. `AgentName`), while still being
+ * checked against the `AgentDefinition` shape at compile time. Do not add
+ * an explicit `AgentDefinition[]` annotation here — it would widen `name`
+ * to `string` and break the compile-time drift guard.
+ */
+export declare const CCLAW_AGENTS: readonly [{
+    readonly name: "planner";
+    readonly description: "MANDATORY for scope/design/plan and PROACTIVE for high-ambiguity work. MUST BE USED when sequencing, dependency mapping, or risk trade-offs are required before coding.";
+    readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
+    readonly model: "deep";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["brainstorm", "scope", "design", "spec", "plan"];
+    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 tools: ["Read", "Grep", "Glob"];
+    readonly model: "balanced";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["spec", "review", "ship"];
+    readonly body: string;
+}, {
+    readonly name: "security-reviewer";
+    readonly description: "MANDATORY during review; PROACTIVE during design/ship for trust-boundary changes. Always produce an explicit no-change attestation when no security-relevant surface moved.";
+    readonly tools: ["Read", "Grep", "Glob"];
+    readonly model: "balanced";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["design", "review", "ship"];
+    readonly body: string;
+}, {
+    readonly name: "test-author";
+    readonly description: "MANDATORY in TDD stage. MUST BE USED for RED -> GREEN -> REFACTOR with evidence-first discipline.";
+    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"];
+    readonly model: "balanced";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["tdd"];
+    readonly body: string;
+}, {
+    readonly name: "doc-updater";
+    readonly description: "MANDATORY at ship and PROACTIVE when behavior/config/public API changes. Keep docs and runbooks in lockstep with shipped behavior.";
+    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob"];
+    readonly model: "fast";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["tdd", "ship"];
+    readonly body: string;
+}];
+/**
+ * Union of known agent names (compile-time). Use this in content that
+ * references agents by name so the TypeScript compiler catches renames
+ * and typos instead of letting them slip into generated artifacts.
  */
-export declare const CCLAW_AGENTS: AgentDefinition[];
+export type AgentName = (typeof CCLAW_AGENTS)[number]["name"];
 /**
  * Render a complete cclaw agent markdown file (YAML frontmatter + body).
  */

package/dist/content/core-agents.js

@@ -15,6 +15,12 @@ function yamlFlowSequence(values) {
 }
 /**
  * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ *
+ * Declared with `satisfies` so the array retains literal `name` types for
+ * downstream type-level consumers (e.g. `AgentName`), while still being
+ * checked against the `AgentDefinition` shape at compile time. Do not add
+ * an explicit `AgentDefinition[]` annotation here — it would widen `name`
+ * to `string` and break the compile-time drift guard.
  */
 export const CCLAW_AGENTS = [
     {

package/dist/content/observe.js

@@ -1094,11 +1094,20 @@ export function claudeHooksJsonWithObservation() {
                         }]
                 }],
             PreToolUse: [{
+                    // `prompt-guard.sh` inspects tool inputs across all tool calls;
+                    // it has to stay on `*` so it sees MCP/Edit/Write/WebSearch
+                    // traffic too. `workflow-guard.sh`, however, only checks TDD
+                    // ordering on write-like operations — it is a no-op for reads.
+                    // Splitting the two matchers cuts Claude's per-read hook
+                    // overhead in half without reducing coverage on write paths.
                     matcher: "*",
                     hooks: [{
                             type: "command",
                             command: hookDispatcherCommand("prompt-guard.sh")
-                        }, {
+                        }]
+                }, {
+                    matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash",
+                    hooks: [{
                             type: "command",
                             command: hookDispatcherCommand("workflow-guard.sh")
                         }]
@@ -1196,6 +1205,18 @@ export function codexHooksJsonWithObservation() {
                     hooks: [{
                             type: "command",
                             command: hookDispatcherCommand("prompt-guard.sh")
+                        }, {
+                            // `workflow-guard.sh` also runs here because Codex's PreToolUse
+                            // only sees Bash; Write/Edit/MCP writes never reach the hook
+                            // surface. Running workflow-guard on UserPromptSubmit catches
+                            // TDD-order violations that originate from the user's prompt
+                            // text (e.g. "edit X.ts to ..."). Payload is a prompt envelope,
+                            // not a tool call, so the script's TOOL extraction falls back
+                            // to "unknown" and advisory mode is a no-op by design — the
+                            // value is that prompt text is scanned for write-shaped intent
+                            // via the existing PAYLOAD_LOWER heuristics.
+                            type: "command",
+                            command: hookDispatcherCommand("workflow-guard.sh")
                         }, {
                             type: "command",
                             command: "bash -lc 'if command -v cclaw >/dev/null 2>&1; then cclaw internal verify-current-state --quiet >/dev/null || true; else npx -y cclaw-cli internal verify-current-state --quiet >/dev/null || true; fi'"

package/dist/content/opencode-plugin.js

@@ -233,11 +233,15 @@ export default function cclawPlugin(ctx) {
         eventType === "session.created" ||
         eventType === "session.resumed" ||
         eventType === "session.compacted" ||
-        eventType === "session.cleared"
+        eventType === "session.cleared" ||
+        eventType === "session.updated"
       ) {
         // Avoid writing directly to stdout in lifecycle hooks because it can
         // interfere with OpenCode TUI rendering. Bootstrap is injected via
         // the system transform hook instead.
+        // session.updated covers config reloads and artifact/rules edits
+        // that happen mid-session; without it the cache would stay stale
+        // until the next compaction or restart.
         refreshBootstrapCache();
       }
       if (eventType === "session.compacted") {

package/dist/content/stage-schema.js

@@ -5,6 +5,7 @@ import { tddStageForTrack } from "./stages/tdd.js";
 const ARTIFACT_STAGE_BY_PATH = {
     ".cclaw/artifacts/01-brainstorm.md": "brainstorm",
     ".cclaw/artifacts/02-scope.md": "scope",
+    ".cclaw/artifacts/02a-research.md": "design",
     ".cclaw/artifacts/03-design.md": "design",
     ".cclaw/artifacts/04-spec.md": "spec",
     ".cclaw/artifacts/05-plan.md": "plan",
@@ -46,6 +47,7 @@ const REQUIRED_GATE_IDS = {
         "tdd_green_full_suite",
         "tdd_refactor_completed",
         "tdd_verified_before_complete",
+        "tdd_docs_drift_check",
         ...(track === "quick" ? [] : ["tdd_traceable_to_plan"])
     ],
     review: (track) => [

package/dist/content/stages/ship.js

@@ -1,3 +1,4 @@
+import { SHIP_FINALIZATION_MODES } from "../../constants.js";
 // ---------------------------------------------------------------------------
 // SHIP — reference: superpowers finishing-a-development-branch + gstack /ship
 // ---------------------------------------------------------------------------
@@ -93,11 +94,7 @@ export const SHIP = {
         "Pre-Ship Checks",
         "Release Notes",
         "Rollback Plan",
-        "FINALIZE_MERGE_LOCAL",
-        "FINALIZE_OPEN_PR",
-        "FINALIZE_KEEP_BRANCH",
-        "FINALIZE_DISCARD_BRANCH",
-        "FINALIZE_NO_VCS"
+        ...SHIP_FINALIZATION_MODES
     ],
     artifactFile: "08-ship.md",
     // `done` exits the stage pipeline. Archive semantics are handled by the

package/dist/content/templates.js

@@ -1,10 +1,12 @@
+import { CCLAW_VERSION, SHIP_FINALIZATION_MODES } from "../constants.js";
 import { orderedStageSchemas } from "./stage-schema.js";
 import { FLOW_STAGES } from "../types.js";
+const SHIP_FINALIZATION_ENUM_LINES = SHIP_FINALIZATION_MODES.map((mode) => `  - ${mode}`).join("\n");
 export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `---
 stage: brainstorm
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -52,7 +54,7 @@ inputs_hash: sha256:pending
     "02-scope.md": `---
 stage: scope
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -158,7 +160,7 @@ inputs_hash: sha256:pending
     "02a-research.md": `---
 stage: design
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -199,7 +201,7 @@ inputs_hash: sha256:pending
     "03-design.md": `---
 stage: design
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -303,7 +305,7 @@ inputs_hash: sha256:pending
     "04-spec.md": `---
 stage: spec
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -359,7 +361,7 @@ inputs_hash: sha256:pending
     "05-plan.md": `---
 stage: plan
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -438,7 +440,7 @@ Execution rule: complete and verify each batch before starting the next batch.
     "06-tdd.md": `---
 stage: tdd
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -505,7 +507,7 @@ inputs_hash: sha256:pending
     "07-review.md": `---
 stage: review
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -614,7 +616,7 @@ inputs_hash: sha256:pending
     "08-ship.md": `---
 stage: ship
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending
@@ -644,11 +646,7 @@ inputs_hash: sha256:pending
 
 ## Finalization
 - Selected enum (exactly one):
-  - FINALIZE_MERGE_LOCAL
-  - FINALIZE_OPEN_PR
-  - FINALIZE_KEEP_BRANCH
-  - FINALIZE_DISCARD_BRANCH
-  - FINALIZE_NO_VCS
+${SHIP_FINALIZATION_ENUM_LINES}
 - Selected label (A/B/C/D/E):
 - Execution result:
 - PR URL / merge commit / kept branch / discard confirmation:
@@ -669,7 +667,7 @@ inputs_hash: sha256:pending
     "09-retro.md": `---
 stage: retro
 schema_version: 1
-version: 0.18.0
+version: ${CCLAW_VERSION}
 feature: <feature-id>
 locked_decisions: []
 inputs_hash: sha256:pending

package/dist/content/utility-skills.d.ts

@@ -48,4 +48,10 @@ export declare const LANGUAGE_RULE_PACK_GENERATORS: Record<string, () => string>
  */
 export declare const LEGACY_LANGUAGE_RULE_PACK_FOLDERS: readonly ["language-typescript", "language-python", "language-go"];
 export declare const UTILITY_SKILL_FOLDERS: readonly ["security", "debugging", "performance", "ci-cd", "docs", "executing-plans", "verification-before-completion", "finishing-a-development-branch", "context-engineering", "source-driven-development", "frontend-accessibility", "landscape-check", "adversarial-review", "security-audit", "knowledge-curation", "retrospective", "document-review", "receiving-code-review"];
-export declare const UTILITY_SKILL_MAP: Record<string, () => string>;
+export type UtilitySkillFolder = (typeof UTILITY_SKILL_FOLDERS)[number];
+/**
+ * One entry per `UTILITY_SKILL_FOLDERS` slot. Typed via the tuple so that
+ * adding a folder without a generator (or vice versa) is a TypeScript
+ * error — keeps the two sources of truth in lockstep at compile time.
+ */
+export declare const UTILITY_SKILL_MAP: Record<UtilitySkillFolder, () => string>;

package/dist/content/utility-skills.js

@@ -1735,6 +1735,11 @@ export const UTILITY_SKILL_FOLDERS = [
     "document-review",
     "receiving-code-review"
 ];
+/**
+ * One entry per `UTILITY_SKILL_FOLDERS` slot. Typed via the tuple so that
+ * adding a folder without a generator (or vice versa) is a TypeScript
+ * error — keeps the two sources of truth in lockstep at compile time.
+ */
 export const UTILITY_SKILL_MAP = {
     security: securityReviewSkill,
     debugging: debuggingSkill,

package/dist/delegation.d.ts

@@ -53,6 +53,8 @@ export type DelegationEntry = {
     retryCount?: number;
     /** Optional references to evidence anchors in artifacts. */
     evidenceRefs?: string[];
+    /** Optional skill marker used for role-specific mandatory checks. */
+    skill?: string;
     /**
      * Fulfillment mode this entry was executed under. Omitted on legacy rows
      * (treated as `"isolated"` for Claude, otherwise inferred from the active
@@ -66,6 +68,16 @@ export type DelegationLedger = {
     runId: string;
     entries: DelegationEntry[];
 };
+/**
+ * Heuristic: does a changed file path strongly imply a trust-boundary
+ * surface? Used to gate adversarial-reviewer requirements on review.
+ *
+ * Matches authN/Z, credentials, crypto, policy, or explicit sanitization
+ * or injection handling. Intentionally excludes broad terms like `input`
+ * and `validation` because they match innocuous paths such as
+ * `form-input.ts` or `number-validation.ts` and produce false positives.
+ */
+export declare function isTrustBoundaryPath(filePath: string): boolean;
 export declare function readDelegationLedger(projectRoot: string): Promise<DelegationLedger>;
 export declare function appendDelegation(projectRoot: string, entry: DelegationEntry): Promise<void>;
 /**
@@ -75,7 +87,9 @@ export declare function appendDelegation(projectRoot: string, entry: DelegationE
  * strongest guarantee.
  */
 export declare function expectedFulfillmentMode(fallbacks: SubagentFallback[]): DelegationFulfillmentMode;
-export declare function checkMandatoryDelegations(projectRoot: string, stage: FlowStage): Promise<{
+export declare function checkMandatoryDelegations(projectRoot: string, stage: FlowStage, options?: {
+    repairFeatureSystem?: boolean;
+}): Promise<{
     satisfied: boolean;
     missing: string[];
     waived: string[];

package/dist/delegation.js

@@ -53,6 +53,18 @@ async function resolveReviewDiffBase(projectRoot) {
         return null;
     }
 }
+/**
+ * Heuristic: does a changed file path strongly imply a trust-boundary
+ * surface? Used to gate adversarial-reviewer requirements on review.
+ *
+ * Matches authN/Z, credentials, crypto, policy, or explicit sanitization
+ * or injection handling. Intentionally excludes broad terms like `input`
+ * and `validation` because they match innocuous paths such as
+ * `form-input.ts` or `number-validation.ts` and produce false positives.
+ */
+export function isTrustBoundaryPath(filePath) {
+    return /(auth|security|secret|token|credential|permission|acl|policy|oauth|session|encrypt|decrypt|sanitize|untrusted|csrf|xss|injection|taint)/iu.test(filePath);
+}
 async function detectReviewTriggers(projectRoot) {
     const empty = {
         changedFiles: 0,
@@ -81,7 +93,7 @@ async function detectReviewTriggers(projectRoot) {
             .split(/\r?\n/gu)
             .map((line) => line.trim())
             .filter((line) => line.length > 0);
-        const trustBoundaryChanged = changedPaths.some((filePath) => /(auth|security|secret|token|credential|permission|acl|policy|oauth|session|encrypt|decrypt|input|validation)/iu.test(filePath));
+        const trustBoundaryChanged = changedPaths.some((p) => isTrustBoundaryPath(p));
         const requireAdversarialReviewer = changedLines > 100 || changedFiles > 10 || trustBoundaryChanged;
         return {
             changedFiles,
@@ -142,6 +154,7 @@ function isDelegationEntry(value) {
         (o.tokens === undefined || isDelegationTokenUsage(o.tokens)) &&
         retryOk &&
         (o.evidenceRefs === undefined || (Array.isArray(o.evidenceRefs) && o.evidenceRefs.every((item) => typeof item === "string"))) &&
+        (o.skill === undefined || typeof o.skill === "string") &&
         (o.schemaVersion === undefined || o.schemaVersion === 1));
 }
 function parseLedger(raw, runId) {
@@ -245,9 +258,11 @@ export function expectedFulfillmentMode(fallbacks) {
         return "role-switch";
     return "harness-waiver";
 }
-export async function checkMandatoryDelegations(projectRoot, stage) {
+export async function checkMandatoryDelegations(projectRoot, stage, options = {}) {
     const mandatory = stageSchema(stage).mandatoryDelegations;
-    const { activeRunId } = await readFlowState(projectRoot);
+    const { activeRunId } = await readFlowState(projectRoot, {
+        repairFeatureSystem: options.repairFeatureSystem
+    });
     const ledger = await readDelegationLedger(projectRoot);
     const forStage = ledger.entries.filter((e) => e.stage === stage);
     const forRun = forStage.filter((e) => e.runId === activeRunId);
@@ -267,14 +282,15 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
         const rows = forRun.filter((e) => e.agent === agent);
         const completedRows = rows.filter((e) => e.status === "completed");
         const waivedRows = rows.filter((e) => e.status === "waived");
-        const requiredCompletedCount = stage === "review" &&
+        const adversarialReviewerRequired = stage === "review" &&
             agent === "reviewer" &&
-            reviewTriggers?.requireAdversarialReviewer
-            ? 2
-            : 1;
+            reviewTriggers?.requireAdversarialReviewer === true;
+        const requiredCompletedCount = adversarialReviewerRequired ? 2 : 1;
         const hasCompleted = completedRows.length >= requiredCompletedCount;
         const hasWaived = waivedRows.length > 0;
-        const ok = hasCompleted || hasWaived;
+        const hasAdversarialSkill = !adversarialReviewerRequired ||
+            completedRows.some((row) => row.skill === "adversarial-review");
+        const ok = hasWaived || (hasCompleted && hasAdversarialSkill);
         if (!ok) {
             missing.push(agent);
             continue;