cclaw-cli 0.48.27 → 0.48.29

package/dist/artifact-linter.js

@@ -1,10 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { resolveArtifactPath as resolveStageArtifactPath } from "./artifact-paths.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";
-async function resolveArtifactPath(projectRoot, fileName) {
+async function resolveNamedArtifactPath(projectRoot, fileName) {
     const relPath = path.join(RUNTIME_ROOT, "artifacts", fileName);
     const absPath = path.join(projectRoot, relPath);
     return { absPath, relPath };
@@ -791,7 +792,11 @@ function validateSectionBody(sectionBody, rule, sectionName) {
 }
 export async function lintArtifact(projectRoot, stage, track = "standard") {
     const schema = stageSchema(stage, track);
-    const { absPath: absFile, relPath: relFile } = await resolveArtifactPath(projectRoot, schema.artifactFile);
+    const { absPath: absFile, relPath: relFile } = await resolveStageArtifactPath(stage, {
+        projectRoot,
+        track,
+        intent: "read"
+    });
     const findings = [];
     if (!(await exists(absFile))) {
         for (const v of schema.artifactValidation) {
@@ -949,8 +954,14 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
                 ? "No placeholder tokens detected in Task List."
                 : `Detected placeholder token(s) in Task List: ${placeholderHits.join(", ")}.`
         });
-        const scopePath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", "02-scope.md");
-        const scopeRaw = (await exists(scopePath)) ? await fs.readFile(scopePath, "utf8") : "";
+        const scopeArtifact = await resolveStageArtifactPath("scope", {
+            projectRoot,
+            track,
+            intent: "read"
+        });
+        const scopeRaw = (await exists(scopeArtifact.absPath))
+            ? await fs.readFile(scopeArtifact.absPath, "utf8")
+            : "";
         const scopeDecisionIds = extractDecisionIds(scopeRaw);
         const missingDecisionRefs = scopeDecisionIds.filter((id) => !raw.includes(id));
         findings.push({
@@ -1053,7 +1064,7 @@ function isStringArray(v) {
 }
 export async function validateReviewArmy(projectRoot) {
     const errors = [];
-    const { absPath, relPath } = await resolveArtifactPath(projectRoot, "07-review-army.json");
+    const { absPath, relPath } = await resolveNamedArtifactPath(projectRoot, "07-review-army.json");
     if (!(await exists(absPath))) {
         return { valid: false, errors: [`Missing file: ${relPath}`] };
     }

package/dist/artifact-paths.d.ts

@@ -0,0 +1,28 @@
+import type { FlowStage, FlowTrack } from "./types.js";
+export type ArtifactPathIntent = "read" | "write";
+export interface ResolveArtifactPathContext {
+    projectRoot: string;
+    track?: FlowTrack;
+    /**
+     * Optional brainstorm topic used for `<slug>` interpolation.
+     * When omitted, the resolver attempts to infer it from `00-idea.md`.
+     */
+    topic?: string;
+    /**
+     * - read: locate an existing artifact first (new slug shape, then legacy fallback).
+     * - write: return a non-colliding writable path for a new artifact.
+     */
+    intent?: ArtifactPathIntent;
+}
+export interface ResolvedArtifactPath {
+    stage: FlowStage;
+    fileName: string;
+    relPath: string;
+    absPath: string;
+    source: "existing" | "generated";
+    legacy: boolean;
+}
+export declare function isSlugArtifactPattern(filePattern: string): boolean;
+export declare function legacyArtifactFileName(filePattern: string): string;
+export declare function slugifyArtifactTopic(topic: string): string;
+export declare function resolveArtifactPath(stage: FlowStage, context: ResolveArtifactPathContext): Promise<ResolvedArtifactPath>;

package/dist/artifact-paths.js

@@ -0,0 +1,261 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stageSchema } from "./content/stage-schema.js";
+import { RUNTIME_ROOT } from "./constants.js";
+import { exists } from "./fs-utils.js";
+const LEGACY_ARTIFACT_GRACE_CYCLES = 2;
+const DEFAULT_TOPIC_SLUG = "topic";
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function splitExt(fileName) {
+    const ext = path.extname(fileName);
+    if (!ext) {
+        return { stem: fileName, ext: "" };
+    }
+    return { stem: fileName.slice(0, -ext.length), ext };
+}
+function appendCollisionSuffix(fileName, index) {
+    const { stem, ext } = splitExt(fileName);
+    return `${stem}-${index}${ext}`;
+}
+export function isSlugArtifactPattern(filePattern) {
+    return filePattern.includes("<slug>");
+}
+export function legacyArtifactFileName(filePattern) {
+    if (!isSlugArtifactPattern(filePattern)) {
+        return filePattern;
+    }
+    return filePattern.replace(/-<slug>/gu, "");
+}
+export function slugifyArtifactTopic(topic) {
+    const normalized = topic
+        .toLowerCase()
+        .trim()
+        .replace(/[`"'“”‘’()[\]{}<>]/gu, " ")
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-+/u, "")
+        .replace(/-+$/u, "");
+    if (normalized.length === 0) {
+        return DEFAULT_TOPIC_SLUG;
+    }
+    return normalized.slice(0, 48);
+}
+function slugPatternRegex(filePattern) {
+    const [left, right] = filePattern.split("<slug>");
+    return new RegExp(`^${escapeRegExp(left ?? "")}[a-z0-9]+(?:-[a-z0-9]+)*(?:-\\d+)?${escapeRegExp(right ?? "")}$`, "u");
+}
+function searchRoots(projectRoot) {
+    return [
+        {
+            absDir: path.join(projectRoot, RUNTIME_ROOT, "artifacts"),
+            relPrefix: path.join(RUNTIME_ROOT, "artifacts")
+        },
+        {
+            absDir: projectRoot,
+            relPrefix: ""
+        }
+    ];
+}
+function candidateFromRoot(root, fileName) {
+    return {
+        relPath: root.relPrefix ? path.join(root.relPrefix, fileName) : fileName,
+        absPath: path.join(root.absDir, fileName)
+    };
+}
+async function inferTopicFromIdeaArtifact(projectRoot) {
+    const ideaPath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", "00-idea.md");
+    if (!(await exists(ideaPath))) {
+        return null;
+    }
+    try {
+        const raw = await fs.readFile(ideaPath, "utf8");
+        const lines = raw.split(/\r?\n/gu);
+        const userPromptHeading = lines.findIndex((line) => /^##\s+user prompt\b/iu.test(line.trim()));
+        if (userPromptHeading >= 0) {
+            for (let i = userPromptHeading + 1; i < lines.length; i += 1) {
+                const line = lines[i].trim();
+                if (line.length === 0)
+                    continue;
+                if (/^##\s+/u.test(line))
+                    break;
+                const candidate = line.replace(/^[-*>\s#]+/u, "").trim();
+                if (candidate.length > 0) {
+                    return candidate;
+                }
+            }
+        }
+        const metadataLine = /^(?:class|track|stack|reclassification)\s*:/iu;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            if (metadataLine.test(trimmed))
+                continue;
+            if (/^##\s+/u.test(trimmed))
+                continue;
+            const candidate = trimmed.replace(/^[-*>\s#]+/u, "").trim();
+            if (candidate.length > 0) {
+                return candidate;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function resolvedTopicSlug(projectRoot, stage, explicitTopic) {
+    if (explicitTopic && explicitTopic.trim().length > 0) {
+        return slugifyArtifactTopic(explicitTopic);
+    }
+    const inferred = await inferTopicFromIdeaArtifact(projectRoot);
+    if (inferred && inferred.trim().length > 0) {
+        return slugifyArtifactTopic(inferred);
+    }
+    return slugifyArtifactTopic(stage);
+}
+async function collectExistingCandidates(projectRoot, filePattern, legacyFile) {
+    const roots = searchRoots(projectRoot);
+    const candidates = [];
+    const hasSlugPattern = isSlugArtifactPattern(filePattern);
+    const matcher = hasSlugPattern ? slugPatternRegex(filePattern) : null;
+    for (const root of roots) {
+        if (hasSlugPattern && matcher) {
+            let entries = [];
+            try {
+                entries = await fs.readdir(root.absDir);
+            }
+            catch {
+                entries = [];
+            }
+            for (const entry of entries) {
+                if (!matcher.test(entry))
+                    continue;
+                const { relPath, absPath } = candidateFromRoot(root, entry);
+                let mtimeMs = 0;
+                try {
+                    const stat = await fs.stat(absPath);
+                    mtimeMs = stat.mtimeMs;
+                }
+                catch {
+                    continue;
+                }
+                candidates.push({
+                    fileName: entry,
+                    relPath,
+                    absPath,
+                    mtimeMs,
+                    legacy: false
+                });
+            }
+        }
+        else {
+            const { relPath, absPath } = candidateFromRoot(root, filePattern);
+            if (await exists(absPath)) {
+                let mtimeMs = 0;
+                try {
+                    const stat = await fs.stat(absPath);
+                    mtimeMs = stat.mtimeMs;
+                }
+                catch {
+                    mtimeMs = 0;
+                }
+                candidates.push({
+                    fileName: filePattern,
+                    relPath,
+                    absPath,
+                    mtimeMs,
+                    legacy: false
+                });
+            }
+        }
+        if (legacyFile && LEGACY_ARTIFACT_GRACE_CYCLES > 0) {
+            const { relPath, absPath } = candidateFromRoot(root, legacyFile);
+            if (await exists(absPath)) {
+                let mtimeMs = 0;
+                try {
+                    const stat = await fs.stat(absPath);
+                    mtimeMs = stat.mtimeMs;
+                }
+                catch {
+                    mtimeMs = 0;
+                }
+                candidates.push({
+                    fileName: legacyFile,
+                    relPath,
+                    absPath,
+                    mtimeMs,
+                    legacy: true
+                });
+            }
+        }
+    }
+    candidates.sort((a, b) => {
+        if (b.mtimeMs !== a.mtimeMs) {
+            return b.mtimeMs - a.mtimeMs;
+        }
+        if (a.legacy !== b.legacy) {
+            return a.legacy ? 1 : -1;
+        }
+        return a.fileName.localeCompare(b.fileName);
+    });
+    return candidates;
+}
+export async function resolveArtifactPath(stage, context) {
+    const track = context.track ?? "standard";
+    const intent = context.intent ?? "read";
+    const filePattern = stageSchema(stage, track).artifactFile;
+    const hasSlugPattern = isSlugArtifactPattern(filePattern);
+    const legacyFile = hasSlugPattern ? legacyArtifactFileName(filePattern) : null;
+    const existing = await collectExistingCandidates(context.projectRoot, filePattern, legacyFile);
+    if (intent === "read" && existing.length > 0) {
+        const picked = existing[0];
+        return {
+            stage,
+            fileName: picked.fileName,
+            relPath: picked.relPath,
+            absPath: picked.absPath,
+            source: "existing",
+            legacy: picked.legacy
+        };
+    }
+    const artifactRoot = path.join(context.projectRoot, RUNTIME_ROOT, "artifacts");
+    if (!hasSlugPattern) {
+        return {
+            stage,
+            fileName: filePattern,
+            relPath: path.join(RUNTIME_ROOT, "artifacts", filePattern),
+            absPath: path.join(artifactRoot, filePattern),
+            source: "generated",
+            legacy: false
+        };
+    }
+    const topicSlug = await resolvedTopicSlug(context.projectRoot, stage, context.topic);
+    const baseFileName = filePattern.replace("<slug>", topicSlug);
+    if (intent === "read") {
+        return {
+            stage,
+            fileName: baseFileName,
+            relPath: path.join(RUNTIME_ROOT, "artifacts", baseFileName),
+            absPath: path.join(artifactRoot, baseFileName),
+            source: "generated",
+            legacy: false
+        };
+    }
+    let candidate = baseFileName;
+    let index = 2;
+    // Keep incrementing while a matching file exists under active artifacts root.
+    while (await exists(path.join(artifactRoot, candidate))) {
+        candidate = appendCollisionSuffix(baseFileName, index);
+        index += 1;
+    }
+    return {
+        stage,
+        fileName: candidate,
+        relPath: path.join(RUNTIME_ROOT, "artifacts", candidate),
+        absPath: path.join(artifactRoot, candidate),
+        source: "generated",
+        legacy: false
+    };
+}

package/dist/content/contracts.js

@@ -1,4 +1,4 @@
-import { stageSchema } from "./stage-schema.js";
+import { stagePolicyNeedles, stageSchema } from "./stage-schema.js";
 import { stageSkillFolder } from "./skills.js";
 export function stageCommandContract(stage, track = "standard") {
     const schema = stageSchema(stage, track);
@@ -17,6 +17,7 @@ export function stageCommandContract(stage, track = "standard") {
     const writeStepPaths = writes.length > 1
         ? writes.map((w) => `\`${w}\``).join(" and ")
         : `\`${primaryArtifact}\``;
+    const policyNeedles = stagePolicyNeedles(stage, track);
     return `# /cc-${stage}
 
 Load and follow **${skillPath}** — it contains the full checklist, examples, interaction protocol, and verification discipline.
@@ -45,6 +46,6 @@ ${gateIds}
 ${schema.exitCriteria.map((v) => `- ${v}`).join("\n")}
 
 ## Anchors
-${schema.policyNeedles.map((v) => `- ${v}`).join("\n")}
+${policyNeedles.map((v) => `- ${v}`).join("\n")}
 `;
 }

package/dist/content/stage-schema.d.ts

@@ -1,6 +1,6 @@
 import type { FlowStage, FlowTrack, TransitionRule } from "../types.js";
 import type { StageComplexityTier, StageAutoSubagentDispatch, StageSchema } from "./stages/schema-types.js";
-export type { ArtifactValidation, CrossStageTrace, ReviewSection, StageComplexityTier, StageExecutionModel, StagePhilosophy, StageArtifactRules, StageReviewLens, StageAutoSubagentDispatch, StageGate, StageSchema, StageSchemaInput } from "./stages/schema-types.js";
+export type { ArtifactValidation, CrossStageTrace, ReviewSection, StageComplexityTier, StageExecutionModel, StagePhilosophy, StageArtifactRules, StageReviewLens, StageAutoSubagentDispatch, StageGate, StageSchemaLegacyInput, StageSchema, StageSchemaInput, StageSchemaV2Input } from "./stages/schema-types.js";
 export declare const SKILL_ENVELOPE_KINDS: readonly ["stage-output", "gate-result", "delegation-record"];
 export type SkillEnvelopeKind = (typeof SKILL_ENVELOPE_KINDS)[number];
 export interface SkillEnvelope {

package/dist/content/stage-schema.js

@@ -1,6 +1,7 @@
 import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "../types.js";
 import { STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { BRAINSTORM, SCOPE, DESIGN, SPEC, PLAN, TDD, REVIEW, SHIP } from "./stages/index.js";
+import { stagePolicyNeedlesFromMetadata } from "./stages/_lint-metadata/index.js";
 import { tddStageForTrack } from "./stages/tdd.js";
 // ---------------------------------------------------------------------------
 // NOTE: The former QUESTION_FORMAT_SPEC / ERROR_BUDGET_SPEC exports were
@@ -66,17 +67,32 @@ export function parseSkillEnvelope(raw) {
     }
     return parsed;
 }
-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",
-    ".cclaw/artifacts/06-tdd.md": "tdd",
-    ".cclaw/artifacts/07-review.md": "review",
-    ".cclaw/artifacts/08-ship.md": "ship"
+const ARTIFACT_STAGE_BY_PREFIX = {
+    "01": "brainstorm",
+    "02": "scope",
+    "03": "design",
+    "04": "spec",
+    "05": "plan",
+    "06": "tdd",
+    "07": "review",
+    "08": "ship"
 };
+const ARTIFACT_STAGE_BY_SPECIAL_FILE = {
+    "02a-research.md": "design"
+};
+function stageFromArtifactPath(artifactPath) {
+    const normalized = artifactPath.replace(/\\/gu, "/");
+    const fileName = normalized.split("/").pop() ?? normalized;
+    const special = ARTIFACT_STAGE_BY_SPECIAL_FILE[fileName];
+    if (special) {
+        return special;
+    }
+    const match = /^(\d{2})(?:[a-z])?-/u.exec(fileName);
+    if (!match) {
+        return null;
+    }
+    return ARTIFACT_STAGE_BY_PREFIX[match[1]] ?? null;
+}
 const REQUIRED_GATE_IDS = {
     brainstorm: [
         "brainstorm_approaches_compared",
@@ -171,13 +187,53 @@ function tieredArtifactValidation(stage, rows) {
 function readsFromForTrack(readsFrom, track) {
     const stageSet = new Set(TRACK_STAGES[track]);
     return readsFrom.filter((artifactPath) => {
-        const stage = ARTIFACT_STAGE_BY_PATH[artifactPath];
+        const stage = stageFromArtifactPath(artifactPath);
         if (!stage) {
             return true;
         }
         return stageSet.has(stage);
     });
 }
+function isStageSchemaV2Input(value) {
+    return value.schemaShape === "v2";
+}
+function normalizeStageSchemaInput(value) {
+    if (!isStageSchemaV2Input(value)) {
+        return value;
+    }
+    return {
+        stage: value.stage,
+        skillFolder: value.skillFolder,
+        skillName: value.skillName,
+        skillDescription: value.skillDescription,
+        complexityTier: value.complexityTier,
+        hardGate: value.philosophy.hardGate,
+        ironLaw: value.philosophy.ironLaw,
+        purpose: value.philosophy.purpose,
+        whenToUse: value.philosophy.whenToUse,
+        whenNotToUse: value.philosophy.whenNotToUse,
+        interactionProtocol: value.executionModel.interactionProtocol,
+        process: value.executionModel.process,
+        requiredGates: value.executionModel.requiredGates,
+        requiredEvidence: value.executionModel.requiredEvidence,
+        inputs: value.executionModel.inputs,
+        requiredContext: value.executionModel.requiredContext,
+        researchPlaybooks: value.executionModel.researchPlaybooks,
+        outputs: value.reviewLens.outputs,
+        blockers: value.executionModel.blockers,
+        exitCriteria: value.executionModel.exitCriteria,
+        commonRationalizations: value.philosophy.commonRationalizations,
+        artifactFile: value.artifactRules.artifactFile,
+        next: value.next,
+        checklist: value.executionModel.checklist,
+        reviewSections: value.reviewLens.reviewSections,
+        completionStatus: value.artifactRules.completionStatus,
+        crossStageTrace: value.artifactRules.crossStageTrace,
+        artifactValidation: value.artifactRules.artifactValidation,
+        batchExecutionAllowed: value.batchExecutionAllowed,
+        trivialOverrideSections: value.artifactRules.trivialOverrideSections
+    };
+}
 // ---------------------------------------------------------------------------
 // Stage map and accessors
 // ---------------------------------------------------------------------------
@@ -357,7 +413,8 @@ export function mandatoryDelegationsForStage(stage, complexityTier = "standard")
             .map((d) => d.agent))];
 }
 export function stageSchema(stage, track = "standard") {
-    const base = stage === "tdd" ? tddStageForTrack(track) : STAGE_SCHEMA_MAP[stage];
+    const rawInput = stage === "tdd" ? tddStageForTrack(track) : STAGE_SCHEMA_MAP[stage];
+    const base = normalizeStageSchemaInput(rawInput);
     const tieredGates = tieredStageGates(stage, base.requiredGates, track);
     const tieredValidation = tieredArtifactValidation(stage, base.artifactValidation);
     const crossStageTrace = {
@@ -396,8 +453,7 @@ export function stageSchema(stage, track = "standard") {
     const reviewLens = {
         outputs: base.outputs,
         reviewSections: base.reviewSections,
-        mandatoryDelegations,
-        policyNeedles: base.policyNeedles
+        mandatoryDelegations
     };
     return {
         ...base,
@@ -464,7 +520,7 @@ export function buildTransitionRules() {
     return rules;
 }
 export function stagePolicyNeedles(stage, track = "standard") {
-    return stageSchema(stage, track).policyNeedles;
+    return stagePolicyNeedlesFromMetadata(stage, track);
 }
 export function stageAutoSubagentDispatch(stage) {
     return STAGE_AUTO_SUBAGENT_DISPATCH[stage];

package/dist/content/stages/_lint-metadata/index.d.ts

@@ -0,0 +1,2 @@
+import type { FlowStage, FlowTrack } from "../../../types.js";
+export declare function stagePolicyNeedlesFromMetadata(stage: FlowStage, track?: FlowTrack): string[];

package/dist/content/stages/_lint-metadata/index.js

@@ -0,0 +1,79 @@
+import { SHIP_FINALIZATION_MODES } from "../../../constants.js";
+const STAGE_POLICY_NEEDLES = {
+    brainstorm: [
+        "Explore project context",
+        "One question at a time",
+        "2-3 architecturally distinct approaches",
+        "State what is being approved",
+        "Self-review before handoff",
+        "Do NOT implement, scaffold, or modify behavior"
+    ],
+    scope: [
+        "Scope mode",
+        "In Scope",
+        "Out of Scope",
+        "Discretion Areas",
+        "NOT in scope",
+        "Premise Challenge",
+        "Locked Decisions"
+    ],
+    design: [
+        "Parallel Research Fleet",
+        "Architecture",
+        "Data Flow",
+        "Failure Modes and Mitigation",
+        "Performance Budget",
+        "One issue at a time"
+    ],
+    spec: ["Acceptance Criteria", "Constraints", "Testability", "approved spec", "Edge Cases"],
+    plan: [
+        "WAIT_FOR_CONFIRM",
+        "Task Graph",
+        "Dependency Batches",
+        "Acceptance Mapping",
+        "verification steps",
+        "Locked Decision Coverage"
+    ],
+    tdd: [
+        "RED",
+        "GREEN",
+        "REFACTOR",
+        "failing test",
+        "full test suite",
+        "acceptance criteria",
+        "traceable to plan slice"
+    ],
+    review: [
+        "Layer 1",
+        "Layer 2",
+        "Critical",
+        "Review Army",
+        "Ready to Ship",
+        "ROUTE_BACK_TO_TDD",
+        "One issue at a time"
+    ],
+    ship: [
+        "Pre-Ship Checks",
+        "Release Notes",
+        "Rollback Plan",
+        ...SHIP_FINALIZATION_MODES
+    ]
+};
+function quickTrackText(value) {
+    return value
+        .replace(/\btask from the plan\b/giu, "acceptance criterion from the spec")
+        .replace(/\bplan task ID\b/giu, "acceptance criterion ID")
+        .replace(/\bplan task\b/giu, "acceptance criterion")
+        .replace(/\bplan row\b/giu, "acceptance row")
+        .replace(/\bplan slice\b/giu, "acceptance slice")
+        .replace(/\bplan artifact\b/giu, "spec artifact")
+        .replace(/\btraceable to plan slice\b/giu, "traceable to acceptance criterion")
+        .replace(/05-plan\.md/gu, "04-spec.md");
+}
+export function stagePolicyNeedlesFromMetadata(stage, track = "standard") {
+    const needles = STAGE_POLICY_NEEDLES[stage];
+    if (stage === "tdd" && track === "quick") {
+        return needles.map(quickTrackText);
+    }
+    return [...needles];
+}