cclaw-cli 0.48.28 → 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/stage-schema.js

@@ -67,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",
@@ -172,7 +187,7 @@ 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;
         }

package/dist/content/stages/brainstorm.js

@@ -46,7 +46,7 @@ export const BRAINSTORM = {
             "**Recommend only after reaction** — present final recommendation with rationale that explicitly references user feedback.",
             "**Present design by sections** — scale each section to its complexity. Ask after each section whether it looks right so far. Cover: architecture, key components, data flow.",
             "**Optional visual companion** — when architecture/data flow complexity is medium+ offer a compact diagram (ASCII or Mermaid) before artifact write-up.",
-            "**Write artifact** to `.cclaw/artifacts/01-brainstorm.md`.",
+            "**Write artifact** to `.cclaw/artifacts/01-brainstorm-<slug>.md`.",
             "**Document-quality pass** — run a brief adversarial review of the artifact (gaps, contradictions, missing trade-offs), then patch before user review.",
             "**Self-review** — scan for placeholders/TODOs, check internal consistency, verify scope is focused, resolve any ambiguity.",
             "**User reviews artifact** — ask the user to review the written artifact and explicitly approve or request changes.",
@@ -75,7 +75,7 @@ export const BRAINSTORM = {
             "Collect user reaction before giving your recommendation.",
             "Recommend after reaction and explain how feedback changed the recommendation.",
             "Present design sections incrementally, get approval after each.",
-            "Write approved direction to `.cclaw/artifacts/01-brainstorm.md`.",
+            "Write approved direction to `.cclaw/artifacts/01-brainstorm-<slug>.md`.",
             "Run document-quality pass to close contradictions and weak trade-off reasoning.",
             "Self-review: placeholder scan, internal consistency, scope check, ambiguity check.",
             "Request explicit user approval of the artifact.",
@@ -87,7 +87,7 @@ export const BRAINSTORM = {
             { id: "brainstorm_artifact_reviewed", description: "User reviewed the written brainstorm artifact and confirmed readiness." }
         ],
         requiredEvidence: [
-            "Artifact written to `.cclaw/artifacts/01-brainstorm.md`.",
+            "Artifact written to `.cclaw/artifacts/01-brainstorm-<slug>.md`.",
             "Project context was explored (files, docs, or recent activity referenced).",
             "Clarifying questions and their answers are captured.",
             "2-3 approaches with trade-offs are recorded, including one higher-upside challenger option.",
@@ -119,11 +119,11 @@ export const BRAINSTORM = {
         ]
     },
     artifactRules: {
-        artifactFile: "01-brainstorm.md",
+        artifactFile: "01-brainstorm-<slug>.md",
         completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
         crossStageTrace: {
             readsFrom: [],
-            writesTo: [".cclaw/artifacts/01-brainstorm.md"],
+            writesTo: [".cclaw/artifacts/01-brainstorm-<slug>.md"],
             traceabilityRule: "Scope and design decisions must trace back to explored context and approved brainstorm direction."
         },
         artifactValidation: [

package/dist/content/stages/design.js

@@ -100,7 +100,7 @@ export const DESIGN = {
         ],
         requiredEvidence: [
             "Research artifact written to `.cclaw/artifacts/02a-research.md` with stack/features/architecture/pitfalls sections plus synthesis.",
-            "Artifact written to `.cclaw/artifacts/03-design.md`.",
+            "Artifact written to `.cclaw/artifacts/03-design-<slug>.md`.",
             "Failure-mode table exists in Method/Exception/Rescue/UserSees format.",
             "Data-flow shadow and error-flow diagrams are present for Standard+ complexity.",
             "Security & threat model findings are documented with mitigations.",
@@ -138,15 +138,15 @@ export const DESIGN = {
         ]
     },
     artifactRules: {
-        artifactFile: "03-design.md",
+        artifactFile: "03-design-<slug>.md",
         completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
         crossStageTrace: {
             readsFrom: [
-                ".cclaw/artifacts/01-brainstorm.md",
-                ".cclaw/artifacts/02-scope.md",
+                ".cclaw/artifacts/01-brainstorm-<slug>.md",
+                ".cclaw/artifacts/02-scope-<slug>.md",
                 ".cclaw/artifacts/02a-research.md"
             ],
-            writesTo: [".cclaw/artifacts/03-design.md"],
+            writesTo: [".cclaw/artifacts/03-design-<slug>.md"],
             traceabilityRule: "Every architecture decision must trace to a scope boundary. Every downstream spec requirement must trace to a design decision."
         },
         artifactValidation: [

package/dist/content/stages/plan.js

@@ -135,7 +135,7 @@ export const PLAN = {
     ],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
-        readsFrom: [".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
+        readsFrom: [".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/03-design-<slug>.md", ".cclaw/artifacts/02-scope-<slug>.md"],
         writesTo: [".cclaw/artifacts/05-plan.md"],
         traceabilityRule: "Every task must trace to a spec acceptance criterion. Every locked scope decision (D-XX) must trace to at least one plan task or explicit defer rationale. Every downstream RED test must trace to a plan task."
     },

package/dist/content/stages/scope.js

@@ -93,7 +93,7 @@ export const SCOPE = {
             { id: "scope_user_approved", description: "User approved the final scope direction." }
         ],
         requiredEvidence: [
-            "Artifact written to `.cclaw/artifacts/02-scope.md`.",
+            "Artifact written to `.cclaw/artifacts/02-scope-<slug>.md`.",
             "Pre-Scope System Audit findings are captured (git log/diff/stash/debt markers).",
             "In-scope and out-of-scope lists are explicit.",
             "Discretion areas are explicit (or marked as `None`).",
@@ -131,11 +131,11 @@ export const SCOPE = {
         ]
     },
     artifactRules: {
-        artifactFile: "02-scope.md",
+        artifactFile: "02-scope-<slug>.md",
         completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
         crossStageTrace: {
-            readsFrom: [".cclaw/artifacts/01-brainstorm.md"],
-            writesTo: [".cclaw/artifacts/02-scope.md"],
+            readsFrom: [".cclaw/artifacts/01-brainstorm-<slug>.md"],
+            writesTo: [".cclaw/artifacts/02-scope-<slug>.md"],
             traceabilityRule: "Every scope boundary must be traceable to a brainstorm decision. Every downstream design choice must stay within the scope contract."
         },
         artifactValidation: [

package/dist/content/stages/spec.js

@@ -115,12 +115,12 @@ export const SPEC = {
     ],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
-        readsFrom: [".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
+        readsFrom: [".cclaw/artifacts/03-design-<slug>.md", ".cclaw/artifacts/02-scope-<slug>.md"],
         writesTo: [".cclaw/artifacts/04-spec.md"],
         traceabilityRule: "Every acceptance criterion must trace to a design decision. Every downstream plan task must trace to a spec criterion."
     },
     artifactValidation: [
-        { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable. Table must include a Requirement Ref column linking to R# IDs in 02-scope.md and a Design Decision Ref column tracing back to design artifact. AC IDs (AC-1, AC-2…) are stable across revisions — dropped ACs stay with Priority `DROPPED`." },
+        { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable. Table must include a Requirement Ref column linking to R# IDs in 02-scope-<slug>.md (legacy 02-scope.md is accepted during migration) and a Design Decision Ref column tracing back to design artifact. AC IDs (AC-1, AC-2…) are stable across revisions — dropped ACs stay with Priority `DROPPED`." },
         { section: "Edge Cases", required: true, validationRule: "At least one boundary and one error condition per criterion." },
         { section: "Constraints and Assumptions", required: false, validationRule: "All implicit assumptions surfaced. Constraints have sources." },
         { section: "Testability Map", required: true, validationRule: "Each criterion maps to a concrete test description with verification approach (unit, integration, e2e, manual) and command or manual steps." },

package/dist/content/stages/tdd.js

@@ -168,7 +168,7 @@ export const TDD = {
     ],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
-        readsFrom: [".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/03-design.md"],
+        readsFrom: [".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/03-design-<slug>.md"],
         writesTo: [".cclaw/artifacts/06-tdd.md"],
         traceabilityRule: "Every RED test traces to a plan task. Every GREEN change traces to a RED test. Every plan task traces to a spec criterion. Design decisions inform test strategy. Evidence chain must be unbroken."
     },

package/dist/gate-evidence.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { checkReviewSecurityNoChangeAttestation, checkReviewVerdictConsistency, extractMarkdownSectionBody, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import { resolveArtifactPath } from "./artifact-paths.js";
 import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { readDelegationLedger } from "./delegation.js";
@@ -11,23 +12,12 @@ import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { FLOW_STAGES } from "./types.js";
 async function currentStageArtifactExists(projectRoot, stage, track) {
-    const artifactFile = stageSchema(stage, track).artifactFile;
-    const candidates = [
-        path.join(projectRoot, RUNTIME_ROOT, "artifacts", artifactFile),
-        path.join(projectRoot, artifactFile)
-    ];
-    for (const candidate of candidates) {
-        if (await exists(candidate))
-            return true;
-    }
-    // Artifact-linter also accepts the file under current working directory fallback; stat once more.
-    try {
-        await fs.access(path.join(projectRoot, artifactFile));
-        return true;
-    }
-    catch {
-        return false;
-    }
+    const resolved = await resolveArtifactPath(stage, {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    return exists(resolved.absPath);
 }
 async function readArtifactMarkdown(projectRoot, artifactFile) {
     const candidates = [

package/dist/internal/advance-stage.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import process from "node:process";
+import { resolveArtifactPath } from "../artifact-paths.js";
 import { RUNTIME_ROOT, SHIP_FINALIZATION_MODES } from "../constants.js";
 import { stageSchema } from "../content/stage-schema.js";
 import { appendDelegation, checkMandatoryDelegations } from "../delegation.js";
@@ -355,8 +356,13 @@ function withLearningsHarvestMarker(artifactMarkdown, appendedEntries, skippedDu
     const suffix = artifactMarkdown.endsWith("\n") ? "" : "\n";
     return `${artifactMarkdown}${suffix}${LEARNINGS_HARVEST_MARKER_PREFIX}${new Date().toISOString()} appended=${appendedEntries} skipped=${skippedDuplicates} -->\n`;
 }
-async function harvestStageLearnings(projectRoot, stage, artifactFile) {
-    const artifactPath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", artifactFile);
+async function harvestStageLearnings(projectRoot, stage, track) {
+    const resolvedArtifact = await resolveArtifactPath(stage, {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    const artifactPath = resolvedArtifact.absPath;
     let raw = "";
     try {
         raw = await fs.readFile(artifactPath, "utf8");
@@ -560,7 +566,7 @@ async function runAdvanceStage(projectRoot, args, io) {
         }
         return 1;
     }
-    const learningsHarvest = await harvestStageLearnings(projectRoot, args.stage, schema.artifactFile);
+    const learningsHarvest = await harvestStageLearnings(projectRoot, args.stage, flowState.track);
     if (!learningsHarvest.ok) {
         io.stderr.write(`cclaw internal advance-stage: learnings harvest failed for "${schema.artifactFile}". ${learningsHarvest.details}\n`);
         return 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.48.28",
+  "version": "0.48.29",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {