cclaw-cli 0.51.30 → 0.55.2

package/dist/early-loop.d.ts

@@ -0,0 +1,66 @@
+export declare const EARLY_LOOP_STAGES: readonly ["brainstorm", "scope", "design"];
+export type EarlyLoopStage = (typeof EARLY_LOOP_STAGES)[number];
+export type EarlyLoopConcernSeverity = "critical" | "important" | "suggestion";
+export interface EarlyLoopConcern {
+    id: string;
+    severity: EarlyLoopConcernSeverity;
+    locator: string;
+    summary: string;
+    firstSeenIteration: number;
+    lastSeenIteration: number;
+    resolvedAtIteration?: number;
+}
+export interface EarlyLoopStatus {
+    schemaVersion: 1;
+    stage: EarlyLoopStage;
+    runId: string;
+    iteration: number;
+    maxIterations: number;
+    openConcerns: EarlyLoopConcern[];
+    resolvedConcerns: EarlyLoopConcern[];
+    lastSeenConcernIds: string[];
+    convergenceTripped: boolean;
+    escalationReason?: string;
+    lastUpdatedAt: string;
+}
+export interface EarlyLoopLogConcern {
+    id: string;
+    severity: EarlyLoopConcernSeverity;
+    locator: string;
+    summary: string;
+}
+export interface EarlyLoopLogEntry {
+    ts: string;
+    runId: string;
+    stage: string;
+    iteration?: number;
+    concerns: EarlyLoopLogConcern[];
+    resolvedConcernIds: string[];
+}
+export interface EarlyLoopParseIssue {
+    lineNumber: number;
+    reason: string;
+    rawLine: string;
+}
+export interface ParseEarlyLoopLogOptions {
+    issues?: EarlyLoopParseIssue[];
+    strict?: boolean;
+}
+export interface DeriveEarlyLoopStatusOptions {
+    stage: EarlyLoopStage;
+    runId: string;
+    maxIterations?: number;
+    now?: Date;
+}
+export interface ComputeEarlyLoopStatusOptions {
+    maxIterations?: number;
+    now?: Date;
+    parseIssues?: EarlyLoopParseIssue[];
+    strictParse?: boolean;
+}
+export declare function isEarlyLoopStage(value: unknown): value is EarlyLoopStage;
+export declare function normalizeEarlyLoopMaxIterations(value: number | undefined): number;
+export declare function parseEarlyLoopLog(text: string, options?: ParseEarlyLoopLogOptions): EarlyLoopLogEntry[];
+export declare function deriveEarlyLoopStatus(entries: EarlyLoopLogEntry[], options: DeriveEarlyLoopStatusOptions): EarlyLoopStatus;
+export declare function computeEarlyLoopStatus(stage: EarlyLoopStage, runId: string, concernsLogPath: string, options?: ComputeEarlyLoopStatusOptions): Promise<EarlyLoopStatus>;
+export declare function formatEarlyLoopStatusLine(status: EarlyLoopStatus): string;

package/dist/early-loop.js

@@ -0,0 +1,275 @@
+import fs from "node:fs/promises";
+import { DEFAULT_EARLY_LOOP_MAX_ITERATIONS } from "./config.js";
+export const EARLY_LOOP_STAGES = ["brainstorm", "scope", "design"];
+const CONCERN_ID_PREFIX = "C-";
+function severityWeight(severity) {
+    if (severity === "critical")
+        return 3;
+    if (severity === "important")
+        return 2;
+    return 1;
+}
+function normalizeSeverity(value) {
+    if (value === "critical" || value === "important" || value === "suggestion") {
+        return value;
+    }
+    return "important";
+}
+function normalizeText(value, fallback) {
+    if (typeof value !== "string")
+        return fallback;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : fallback;
+}
+function stableConcernFallbackId(locator, summary) {
+    const seed = `${locator}::${summary}`.trim().toLowerCase();
+    let hash = 0;
+    for (let index = 0; index < seed.length; index += 1) {
+        hash = (Math.imul(31, hash) + seed.charCodeAt(index)) >>> 0;
+    }
+    return `${CONCERN_ID_PREFIX}${hash.toString(16).padStart(8, "0")}`;
+}
+function normalizeConcernId(id, locator, summary) {
+    if (typeof id === "string") {
+        const trimmed = id.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    return stableConcernFallbackId(locator, summary);
+}
+function normalizeConcerns(value) {
+    if (!Array.isArray(value))
+        return [];
+    const concerns = [];
+    for (const row of value) {
+        if (!row || typeof row !== "object" || Array.isArray(row))
+            continue;
+        const typed = row;
+        const locator = normalizeText(typed.locator, "unknown-location");
+        const summary = normalizeText(typed.summary, "missing-summary");
+        concerns.push({
+            id: normalizeConcernId(typed.id, locator, summary),
+            severity: normalizeSeverity(typed.severity),
+            locator,
+            summary
+        });
+    }
+    return concerns;
+}
+function normalizeResolvedConcernIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+export function isEarlyLoopStage(value) {
+    return typeof value === "string" && EARLY_LOOP_STAGES.includes(value);
+}
+export function normalizeEarlyLoopMaxIterations(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 1) {
+        return value;
+    }
+    return DEFAULT_EARLY_LOOP_MAX_ITERATIONS;
+}
+export function parseEarlyLoopLog(text, options = {}) {
+    const strict = options.strict === true;
+    const issues = options.issues;
+    const normalized = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const lines = normalized.split(/\r?\n/u);
+    const entries = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const raw = lines[index] ?? "";
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        const lineNumber = index + 1;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            issues?.push({
+                lineNumber,
+                reason: `json-parse-failed: ${error instanceof Error ? error.message : String(error)}`,
+                rawLine: raw
+            });
+            continue;
+        }
+        const runId = normalizeText(parsed.runId, "");
+        const stage = normalizeText(parsed.stage, "");
+        const concerns = normalizeConcerns(parsed.concerns);
+        const resolvedConcernIds = normalizeResolvedConcernIds(parsed.resolvedConcernIds);
+        const iteration = typeof parsed.iteration === "number" &&
+            Number.isInteger(parsed.iteration) &&
+            parsed.iteration >= 1
+            ? parsed.iteration
+            : undefined;
+        if (strict) {
+            const missing = [];
+            if (runId.length === 0)
+                missing.push("runId");
+            if (stage.length === 0)
+                missing.push("stage");
+            if (concerns.length === 0 && resolvedConcernIds.length === 0) {
+                missing.push("concerns/resolvedConcernIds");
+            }
+            if (missing.length > 0) {
+                issues?.push({
+                    lineNumber,
+                    reason: `missing-required-fields: ${missing.join(",")}`,
+                    rawLine: raw
+                });
+                continue;
+            }
+        }
+        entries.push({
+            ts: normalizeText(parsed.ts, ""),
+            runId: runId.length > 0 ? runId : "active",
+            stage: stage.length > 0 ? stage : "brainstorm",
+            iteration,
+            concerns,
+            resolvedConcernIds
+        });
+    }
+    return entries;
+}
+function sortConcerns(a, b) {
+    const severityDiff = severityWeight(b.severity) - severityWeight(a.severity);
+    if (severityDiff !== 0)
+        return severityDiff;
+    if (a.firstSeenIteration !== b.firstSeenIteration) {
+        return a.firstSeenIteration - b.firstSeenIteration;
+    }
+    if (a.lastSeenIteration !== b.lastSeenIteration) {
+        return a.lastSeenIteration - b.lastSeenIteration;
+    }
+    return a.id.localeCompare(b.id, "en");
+}
+export function deriveEarlyLoopStatus(entries, options) {
+    const maxIterations = normalizeEarlyLoopMaxIterations(options.maxIterations);
+    const concerns = new Map();
+    const filtered = entries.filter((entry) => entry.runId === options.runId && entry.stage === options.stage);
+    let previousConcernSnapshotKey = "";
+    let sameConcernStreak = 0;
+    let convergenceTripped = false;
+    let escalationReason;
+    let currentIteration = 0;
+    let lastSeenConcernIds = [];
+    for (const entry of filtered) {
+        currentIteration += 1;
+        const iteration = entry.iteration ?? currentIteration;
+        const seenThisIteration = new Set();
+        for (const concern of entry.concerns) {
+            seenThisIteration.add(concern.id);
+            const existing = concerns.get(concern.id);
+            if (!existing) {
+                concerns.set(concern.id, {
+                    id: concern.id,
+                    severity: concern.severity,
+                    locator: concern.locator,
+                    summary: concern.summary,
+                    firstSeenIteration: iteration,
+                    lastSeenIteration: iteration
+                });
+                continue;
+            }
+            existing.lastSeenIteration = iteration;
+            existing.locator = concern.locator;
+            existing.summary = concern.summary;
+            if (severityWeight(concern.severity) >= severityWeight(existing.severity)) {
+                existing.severity = concern.severity;
+            }
+            delete existing.resolvedAtIteration;
+        }
+        for (const concernId of entry.resolvedConcernIds) {
+            const existing = concerns.get(concernId);
+            if (!existing)
+                continue;
+            if (seenThisIteration.has(concernId))
+                continue;
+            if (existing.resolvedAtIteration === undefined) {
+                existing.resolvedAtIteration = iteration;
+            }
+        }
+        for (const concern of concerns.values()) {
+            if (concern.resolvedAtIteration !== undefined)
+                continue;
+            if (seenThisIteration.has(concern.id))
+                continue;
+            concern.resolvedAtIteration = iteration;
+        }
+        const openConcernIds = Array.from(concerns.values())
+            .filter((concern) => concern.resolvedAtIteration === undefined)
+            .map((concern) => concern.id)
+            .sort((a, b) => a.localeCompare(b, "en"));
+        lastSeenConcernIds = openConcernIds;
+        const snapshotKey = openConcernIds.join("|");
+        if (snapshotKey.length > 0 && snapshotKey === previousConcernSnapshotKey) {
+            sameConcernStreak += 1;
+            if (!convergenceTripped && sameConcernStreak >= 2) {
+                convergenceTripped = true;
+                escalationReason = `same concerns ${sameConcernStreak} iterations in a row`;
+            }
+        }
+        else {
+            sameConcernStreak = snapshotKey.length > 0 ? 1 : 0;
+        }
+        previousConcernSnapshotKey = snapshotKey;
+    }
+    const openConcerns = Array.from(concerns.values())
+        .filter((concern) => concern.resolvedAtIteration === undefined)
+        .sort(sortConcerns);
+    const resolvedConcerns = Array.from(concerns.values())
+        .filter((concern) => concern.resolvedAtIteration !== undefined)
+        .sort((a, b) => {
+        if (a.resolvedAtIteration !== b.resolvedAtIteration) {
+            return a.resolvedAtIteration - b.resolvedAtIteration;
+        }
+        return sortConcerns(a, b);
+    });
+    if (!convergenceTripped && openConcerns.length > 0 && currentIteration >= maxIterations) {
+        convergenceTripped = true;
+        escalationReason = `max iterations ${maxIterations} reached with ${openConcerns.length} open concern(s)`;
+    }
+    return {
+        schemaVersion: 1,
+        stage: options.stage,
+        runId: options.runId,
+        iteration: currentIteration,
+        maxIterations,
+        openConcerns,
+        resolvedConcerns,
+        lastSeenConcernIds,
+        convergenceTripped,
+        ...(escalationReason ? { escalationReason } : {}),
+        lastUpdatedAt: (options.now ?? new Date()).toISOString()
+    };
+}
+export async function computeEarlyLoopStatus(stage, runId, concernsLogPath, options = {}) {
+    let raw = "";
+    try {
+        raw = await fs.readFile(concernsLogPath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    const parsed = parseEarlyLoopLog(raw, {
+        issues: options.parseIssues,
+        strict: options.strictParse
+    });
+    return deriveEarlyLoopStatus(parsed, {
+        stage,
+        runId,
+        maxIterations: options.maxIterations,
+        now: options.now
+    });
+}
+export function formatEarlyLoopStatusLine(status) {
+    const convergence = status.convergenceTripped ? "tripped" : "clear";
+    return `Early Loop: stage=${status.stage}, iter=${status.iteration}/${status.maxIterations}, open=${status.openConcerns.length}, convergence=${convergence}`;
+}

package/dist/gate-evidence.d.ts

@@ -30,6 +30,12 @@ export interface CompletedStagesClosureResult {
     }>;
 }
 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;
@@ -37,6 +43,8 @@ export interface ReconciliationNotice {
     gateId: string;
     reason: string;
     demotedAt: string;
+    kind?: ReconciliationNoticeKind;
+    payload?: CloseoutSubstateDemotionPayload;
 }
 export interface ReconciliationNoticesPayload {
     schemaVersion: number;

package/dist/gate-evidence.js

@@ -2,10 +2,12 @@ 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 { readConfig } from "./config.js";
 import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { readDelegationLedger } from "./delegation.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+import { computeEarlyLoopStatus, isEarlyLoopStage, normalizeEarlyLoopMaxIterations } from "./early-loop.js";
 import { detectPublicApiChanges } from "./internal/detect-public-api-changes.js";
 import { readFlowState, writeFlowState } from "./runs.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
@@ -119,6 +121,92 @@ async function verifyDiscoveredCommandEvidence(projectRoot, stage, gateId, flowS
         return null;
     return `${stage} verification gate blocked (${gateId}): guard evidence must cite one discovered real test command: ${commands.join(", ")}.`;
 }
+function toEarlyLoopGateSnapshot(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const typed = value;
+    const stage = typeof typed.stage === "string" ? typed.stage : "";
+    const runId = typeof typed.runId === "string" ? typed.runId : "active";
+    const iteration = typeof typed.iteration === "number" && Number.isInteger(typed.iteration) && typed.iteration >= 0
+        ? typed.iteration
+        : 0;
+    const maxIterations = normalizeEarlyLoopMaxIterations(typeof typed.maxIterations === "number" ? typed.maxIterations : undefined);
+    const openConcernIds = Array.isArray(typed.openConcerns)
+        ? typed.openConcerns
+            .flatMap((concern) => {
+            if (!concern || typeof concern !== "object" || Array.isArray(concern))
+                return [];
+            const id = concern.id;
+            return typeof id === "string" && id.trim().length > 0 ? [id.trim()] : [];
+        })
+            .sort((a, b) => a.localeCompare(b, "en"))
+        : [];
+    if (stage.length === 0)
+        return null;
+    return {
+        stage,
+        runId,
+        iteration,
+        maxIterations,
+        openConcernIds,
+        openConcernCount: openConcernIds.length,
+        convergenceTripped: typed.convergenceTripped === true,
+        escalationReason: typeof typed.escalationReason === "string" && typed.escalationReason.trim().length > 0
+            ? typed.escalationReason.trim()
+            : undefined
+    };
+}
+async function readEarlyLoopGateSnapshot(projectRoot, flowState) {
+    if (!isEarlyLoopStage(flowState.currentStage)) {
+        return { snapshot: null };
+    }
+    const stateDir = path.join(projectRoot, RUNTIME_ROOT, "state");
+    const statusPath = path.join(stateDir, "early-loop.json");
+    let onDisk = null;
+    if (await exists(statusPath)) {
+        try {
+            onDisk = toEarlyLoopGateSnapshot(JSON.parse(await fs.readFile(statusPath, "utf8")));
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return {
+                snapshot: null,
+                issue: `early loop gate blocked (early_loop_open_concerns): unable to parse ${statusPath} (${reason}). ` +
+                    "Rebuild status with `cclaw internal early-loop-status --write`."
+            };
+        }
+    }
+    if (onDisk &&
+        onDisk.stage === flowState.currentStage &&
+        onDisk.runId === flowState.activeRunId) {
+        return { snapshot: onDisk };
+    }
+    try {
+        const config = await readConfig(projectRoot);
+        const computed = await computeEarlyLoopStatus(flowState.currentStage, flowState.activeRunId, path.join(stateDir, "early-loop-log.jsonl"), {
+            maxIterations: config.earlyLoop?.maxIterations
+        });
+        return {
+            snapshot: {
+                stage: computed.stage,
+                runId: computed.runId,
+                iteration: computed.iteration,
+                maxIterations: computed.maxIterations,
+                openConcernIds: computed.openConcerns.map((concern) => concern.id),
+                openConcernCount: computed.openConcerns.length,
+                convergenceTripped: computed.convergenceTripped,
+                escalationReason: computed.escalationReason
+            }
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            snapshot: null,
+            issue: `early loop gate blocked (early_loop_open_concerns): unable to compute status from early-loop-log.jsonl (${reason}).`
+        };
+    }
+}
 const RECONCILIATION_NOTICES_FILE = "reconciliation-notices.json";
 const RECONCILIATION_NOTICES_SCHEMA_VERSION = 1;
 const DESIGN_RESEARCH_REQUIRED_SECTIONS = [
@@ -156,13 +244,31 @@ function sanitizeReconciliationNotice(raw) {
         typeof typed.demotedAt !== "string") {
         return null;
     }
+    const kind = typed.kind === "closeout_substate_demotion"
+        ? "closeout_substate_demotion"
+        : "gate_demotion";
+    let payload;
+    if (kind === "closeout_substate_demotion" && typed.payload && typeof typed.payload === "object" && !Array.isArray(typed.payload)) {
+        const payloadTyped = typed.payload;
+        if (typeof payloadTyped.previous === "string" &&
+            typeof payloadTyped.next === "string" &&
+            typeof payloadTyped.reason === "string") {
+            payload = {
+                previous: payloadTyped.previous,
+                next: payloadTyped.next,
+                reason: payloadTyped.reason
+            };
+        }
+    }
     return {
         id: typed.id,
         runId: typed.runId,
         stage: typed.stage,
         gateId: typed.gateId,
         reason: typed.reason,
-        demotedAt: typed.demotedAt
+        demotedAt: typed.demotedAt,
+        kind,
+        payload
     };
 }
 export async function readReconciliationNotices(projectRoot) {
@@ -211,6 +317,9 @@ export function classifyReconciliationNotices(flowState, notices) {
             staleRun.push(notice);
             continue;
         }
+        if (notice.kind === "closeout_substate_demotion") {
+            continue;
+        }
         const stageCatalog = flowState.stageGateCatalog[notice.stage];
         const blocked = stageCatalog.blocked.includes(notice.gateId);
         if (!blocked) {
@@ -239,6 +348,7 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
     const recommendedSet = new Set(recommended);
     const allowedSet = new Set([...required, ...recommended]);
     const issues = [];
+    const softNotices = [];
     const catalogRequired = unique(catalog.required);
     const catalogRecommended = unique(catalog.recommended ?? []);
     const catalogConditional = unique(catalog.conditional ?? []);
@@ -439,8 +549,33 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             }
         }
     }
+    if (isEarlyLoopStage(stage)) {
+        const { snapshot, issue } = await readEarlyLoopGateSnapshot(projectRoot, flowState);
+        if (issue) {
+            issues.push(issue);
+        }
+        else if (snapshot && snapshot.openConcernCount > 0) {
+            const concernTail = snapshot.openConcernIds.length > 3
+                ? `, +${snapshot.openConcernIds.length - 3} more`
+                : "";
+            const concernSample = snapshot.openConcernIds.slice(0, 3).join(", ");
+            if (snapshot.convergenceTripped) {
+                const reason = snapshot.escalationReason ?? "convergence guard tripped";
+                softNotices.push(`early loop escalation notice (early_loop_open_concerns): ${reason}; ` +
+                    `open concerns remain (${concernSample}${concernTail}). Request explicit human override before advancing.`);
+            }
+            else {
+                issues.push(`early loop gate blocked (early_loop_open_concerns): ` +
+                    `${snapshot.openConcernCount} open concern(s) remain after iteration ` +
+                    `${snapshot.iteration}/${snapshot.maxIterations} (${concernSample}${concernTail}).`);
+            }
+        }
+    }
     const missingRequired = required.filter((gateId) => !passedSet.has(gateId));
-    const missingRecommended = recommended.filter((gateId) => !passedSet.has(gateId));
+    const missingRecommended = [
+        ...recommended.filter((gateId) => !passedSet.has(gateId)),
+        ...softNotices
+    ];
     const missingTriggeredConditional = [];
     const blockingBlocked = catalog.blocked.filter((gateId) => requiredSet.has(gateId));
     const complete = missingRequired.length === 0 && blockingBlocked.length === 0;
@@ -617,9 +752,9 @@ export async function reconcileAndWriteCurrentStageGateCatalog(projectRoot) {
         noticesChanged = true;
     }
     if (reconciliation.demotedGateIds.length > 0) {
-        const existing = new Set(noticesPayload.notices.map((notice) => `${notice.runId}:${notice.stage}:${notice.gateId}`));
+        const existing = new Set(noticesPayload.notices.map((notice) => `${notice.runId}:${notice.stage}:${notice.gateId}:${notice.kind ?? "gate_demotion"}`));
         for (const gateId of reconciliation.demotedGateIds) {
-            const dedupeKey = `${effectiveState.activeRunId}:${reconciliation.stage}:${gateId}`;
+            const dedupeKey = `${effectiveState.activeRunId}:${reconciliation.stage}:${gateId}:gate_demotion`;
             if (existing.has(dedupeKey)) {
                 continue;
             }
@@ -630,7 +765,8 @@ export async function reconcileAndWriteCurrentStageGateCatalog(projectRoot) {
                 stage: reconciliation.stage,
                 gateId,
                 reason: "demoted from passed to blocked during gate reconciliation (missing evidence)",
-                demotedAt: ts
+                demotedAt: ts,
+                kind: "gate_demotion"
             });
             existing.add(dedupeKey);
             noticesChanged = true;

package/dist/harness-adapters.d.ts

@@ -32,7 +32,7 @@ export type SubagentFallback =
  *   directories under a skills root (Codex CLI ≥0.89, Jan 2026). cclaw
  *   writes `<commandDir>/<skillName>/SKILL.md` and the agent invokes it
  *   either via `/use <skillName>` or via automatic description matching
- *   when the user's text mentions `/cc`, `/cc-ideate`, or `/cc-cancel`.
+ *   when the user's text mentions `/cc`, `/cc-idea`, or `/cc-cancel`.
  */
 export type ShimKind = "command" | "skill";
 export interface HarnessAdapter {
@@ -47,7 +47,7 @@ export interface HarnessAdapter {
      * Root directory where cclaw writes `/cc*` entry points.
      *
      * - For `shimKind: "command"` this is the directory containing flat
-     *   markdown files (`<commandDir>/cc.md`, `<commandDir>/cc-ideate.md`, …).
+     *   markdown files (`<commandDir>/cc.md`, `<commandDir>/cc-idea.md`, …).
      * - For `shimKind: "skill"` this is the skills root that contains
      *   per-skill subdirectories (`<commandDir>/<skillName>/SKILL.md`).
      */