mdkg 0.3.7 → 0.3.9

package/dist/commands/init.js

@@ -17,6 +17,7 @@ const skill_support_1 = require("./skill_support");
 const skill_mirror_1 = require("./skill_mirror");
 const DEFAULT_SEED_SUBDIR = path_1.default.resolve(__dirname, "..", "init");
 const SOUL_PIN_ID = "rule-soul";
+const COLLABORATION_PIN_ID = "rule-7";
 const HUMAN_PIN_ID = "rule-human";
 const DEFAULT_CORE_LIST_HEADER = [
     "# mdkg verbose core list",
@@ -175,6 +176,52 @@ function humanTemplate(created) {
         "",
     ].join("\n");
 }
+function collaborationTemplate(created) {
+    return [
+        "---",
+        `id: ${COLLABORATION_PIN_ID}`,
+        "type: rule",
+        "title: collaboration profile and operator preferences",
+        "tags: [collaboration, preferences, operator]",
+        "owners: []",
+        "links: []",
+        "artifacts: []",
+        "relates: [rule-human]",
+        "refs: [dec-53]",
+        "aliases: [collaboration, operator-profile]",
+        `created: ${created}`,
+        `updated: ${created}`,
+        "---",
+        "",
+        "# Purpose",
+        "",
+        "Capture stable collaboration preferences, operating boundaries, and repo-specific human expectations so agents can work with less ambiguity.",
+        "",
+        "# Scope",
+        "",
+        "Applies to planning, implementation, review, release, and handoff interactions in this repository.",
+        "",
+        "# Compatibility",
+        "",
+        "`COLLABORATION.md` is canonical. `HUMAN.md` remains a one-release legacy alias for repos and agent prompts that still reference it; read `COLLABORATION.md` first and then use `HUMAN.md` only for compatibility notes not yet migrated.",
+        "",
+        "# Requirements",
+        "",
+        "- Keep top goals, boundaries, and style preferences current.",
+        "- Include ask-before-doing constraints for risky or high-impact actions.",
+        "- Record preferred environment assumptions and validation commands.",
+        "- Preserve local operator customizations during `mdkg upgrade --apply`.",
+        "",
+        "# Notes",
+        "",
+        "Suggested prompts:",
+        "- What are your top 3 goals in this repo right now?",
+        "- What should never happen without confirmation?",
+        "- What coding/review style should the agent prefer?",
+        "- What OS/runtime/test commands should be assumed?",
+        "",
+    ].join("\n");
+}
 function seededInitEvent(nowIso) {
     const event = {
         ts: nowIso,
@@ -277,6 +324,31 @@ function ensureCorePins(coreListPath, requiredPins) {
     fs_1.default.mkdirSync(path_1.default.dirname(coreListPath), { recursive: true });
     fs_1.default.writeFileSync(coreListPath, output, "utf8");
 }
+function refreshManifestHash(root, manifest, relPath) {
+    const entry = manifest.files.find((file) => file.path === relPath);
+    if (!entry) {
+        return;
+    }
+    const targetPath = path_1.default.join(root, relPath);
+    if (fs_1.default.existsSync(targetPath) && fs_1.default.statSync(targetPath).isFile()) {
+        entry.sha256 = (0, init_manifest_1.sha256File)(targetPath);
+    }
+}
+function ensureCreatedCoreManifestEntry(root, manifest, relPath, stats) {
+    if (manifest.files.some((file) => file.path === relPath) || !stats.createdPaths.includes(relPath)) {
+        return;
+    }
+    const targetPath = path_1.default.join(root, relPath);
+    if (!fs_1.default.existsSync(targetPath) || !fs_1.default.statSync(targetPath).isFile()) {
+        return;
+    }
+    manifest.files.push({
+        path: relPath,
+        category: "core",
+        sha256: (0, init_manifest_1.sha256File)(targetPath),
+    });
+    manifest.files.sort((a, b) => a.path.localeCompare(b.path));
+}
 function runInitCommand(options) {
     const root = path_1.default.resolve(options.root);
     const seedRoot = options.seedRoot ? path_1.default.resolve(options.seedRoot) : DEFAULT_SEED_SUBDIR;
@@ -295,6 +367,7 @@ function runInitCommand(options) {
     const seedReadme = path_1.default.join(seedRoot, "README.md");
     const seedDefaultSkills = path_1.default.join(seedRoot, "skills", "default");
     const seedSoul = path_1.default.join(seedCore, "SOUL.md");
+    const seedCollaboration = path_1.default.join(seedCore, "COLLABORATION.md");
     const seedHuman = path_1.default.join(seedCore, "HUMAN.md");
     const seedManifest = (0, init_manifest_1.createInitManifest)(seedRoot, (0, version_1.readPackageVersion)(), {
         includeAgentDocs: Boolean(options.agent),
@@ -367,6 +440,7 @@ function runInitCommand(options) {
         if (options.agent) {
             const today = (0, date_1.formatDate)(new Date());
             const soulPath = path_1.default.join(mdkgDir, "core", "SOUL.md");
+            const collaborationPath = path_1.default.join(mdkgDir, "core", "COLLABORATION.md");
             const humanPath = path_1.default.join(mdkgDir, "core", "HUMAN.md");
             const skillsDir = path_1.default.join(mdkgDir, "skills");
             const registryPath = path_1.default.join(skillsDir, "registry.md");
@@ -378,6 +452,9 @@ function runInitCommand(options) {
             if (!fs_1.default.existsSync(seedSoul)) {
                 writeFileIfMissing(root, soulPath, soulTemplate(today), force, stats);
             }
+            if (!fs_1.default.existsSync(seedCollaboration)) {
+                writeFileIfMissing(root, collaborationPath, collaborationTemplate(today), force, stats);
+            }
             if (!fs_1.default.existsSync(seedHuman)) {
                 writeFileIfMissing(root, humanPath, humanTemplate(today), force, stats);
             }
@@ -386,9 +463,13 @@ function runInitCommand(options) {
                 writeFileIfMissing(root, eventsPath, seededInitEvent(new Date().toISOString()), force, stats);
             }
             const coreListPath = path_1.default.join(mdkgDir, "core", "core.md");
-            ensureCorePins(coreListPath, [SOUL_PIN_ID, HUMAN_PIN_ID]);
-            (0, skill_mirror_1.scaffoldMirrorRoots)(root);
+            ensureCorePins(coreListPath, [SOUL_PIN_ID, COLLABORATION_PIN_ID, HUMAN_PIN_ID]);
+            refreshManifestHash(root, seedManifest, ".mdkg/core/core.md");
+            ensureCreatedCoreManifestEntry(root, seedManifest, ".mdkg/core/SOUL.md", stats);
+            ensureCreatedCoreManifestEntry(root, seedManifest, ".mdkg/core/COLLABORATION.md", stats);
+            ensureCreatedCoreManifestEntry(root, seedManifest, ".mdkg/core/HUMAN.md", stats);
             const config = (0, config_1.loadConfig)(root);
+            (0, skill_mirror_1.scaffoldMirrorRoots)(root, config);
             (0, skill_support_1.refreshSkillsRegistry)(root, config);
             stats.registryRefreshed = true;
             const mirrorResult = (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
@@ -452,7 +533,7 @@ function runInitCommand(options) {
     }
     if (options.agent) {
         console.log("agent bootstrap: AGENT_START.md, AGENTS.md, CLAUDE.md, llms.txt, CLI_COMMAND_MATRIX.md");
-        console.log("agent core pins: rule-soul, rule-human");
+        console.log("agent core pins: rule-soul, rule-7, rule-human");
         console.log("agent event log: .mdkg/work/events/events.jsonl");
         console.log(`skill mirrors: ${stats.mirroredSkills} sync operation(s) across ${stats.mirrorTargets} target(s)`);
         if (stats.registryRefreshed) {

package/dist/commands/new.js

@@ -27,6 +27,7 @@ const DEC_STATUS = new Set(["proposed", "accepted", "rejected", "superseded"]);
 const SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const CORE_TYPES = new Set(["rule"]);
 const DESIGN_TYPES = new Set(["prd", "edd", "dec", "prop"]);
+const LEGACY_NEW_SPEC_WARNING = "warning: mdkg new spec is legacy; use mdkg new manifest. This alias creates MANIFEST.md with type: manifest during the compatibility release.";
 function parseCsvList(raw) {
     if (!raw) {
         return [];
@@ -162,6 +163,9 @@ function fileNameForType(type, id, slug) {
     }
     return `${id}-${slug}.md`;
 }
+function canonicalCreationType(requestedType) {
+    return requestedType === "spec" ? "manifest" : requestedType;
+}
 function ensureExists(index, value, ws, label) {
     const resolved = (0, qid_1.resolveQid)(index, value, ws);
     if (resolved.status !== "ok") {
@@ -177,13 +181,15 @@ function runNewCommandLocked(options) {
     if (!title) {
         throw new errors_1.UsageError("title cannot be empty");
     }
-    const type = options.type.toLowerCase();
-    if (type === "archive") {
+    const requestedType = options.type.toLowerCase();
+    if (requestedType === "archive") {
         throw new errors_1.UsageError("use `mdkg archive add <file>` to create archive sidecars");
     }
-    if (!node_1.ALLOWED_TYPES.has(type)) {
+    if (!node_1.ALLOWED_TYPES.has(requestedType)) {
         throw new errors_1.UsageError(`type must be one of ${Array.from(node_1.ALLOWED_TYPES).join(", ")}`);
     }
+    const type = canonicalCreationType(requestedType);
+    const legacySpecAlias = requestedType === "spec";
     const config = (0, config_1.loadConfig)(options.root);
     const ws = normalizeWorkspace(options.ws);
     if (!config.workspaces[ws]) {
@@ -389,6 +395,9 @@ function runNewCommandLocked(options) {
         ...(status ? { status } : {}),
         ...(priority !== undefined ? { priority } : {}),
     };
+    if (legacySpecAlias) {
+        console.error(LEGACY_NEW_SPEC_WARNING);
+    }
     if (options.json) {
         console.log(JSON.stringify({
             action: "created",

package/dist/commands/skill.js

@@ -186,7 +186,7 @@ function runSkillNewCommandLocked(options) {
     (0, atomic_1.atomicWriteFile)(canonicalPath, content);
     (0, skill_support_1.ensureSkillsRegistry)(root, config);
     (0, skill_support_1.refreshSkillsRegistry)(root, config);
-    if ((0, skill_mirror_1.shouldMaintainSkillMirrors)(root)) {
+    if ((0, skill_mirror_1.shouldMaintainSkillMirrors)(root, config)) {
         (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
     }
     if (config.index.auto_reindex) {

package/dist/commands/skill_mirror.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.configuredSkillMirrorTargets = configuredSkillMirrorTargets;
 exports.syncSkillMirrors = syncSkillMirrors;
 exports.preflightSkillMirrorTargets = preflightSkillMirrorTargets;
 exports.shouldMaintainSkillMirrors = shouldMaintainSkillMirrors;
@@ -10,22 +11,26 @@ exports.auditSkillMirrors = auditSkillMirrors;
 exports.scaffoldMirrorRoots = scaffoldMirrorRoots;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
 const skills_indexer_1 = require("../graph/skills_indexer");
 const errors_1 = require("../util/errors");
-const MIRROR_PRODUCTS = ["agents", "claude"];
 const MANIFEST_FILE = ".mdkg-managed.json";
 const MANAGED_ROOT_MARKERS = [
     path_1.default.join(".mdkg", "core", "SOUL.md"),
+    path_1.default.join(".mdkg", "core", "COLLABORATION.md"),
     path_1.default.join(".mdkg", "core", "HUMAN.md"),
 ];
 const ALLOWED_ROOT_ENTRIES = ["SKILL.md", "references", "assets", "scripts"];
-function resolveMirrorTargets(root) {
-    return MIRROR_PRODUCTS.map((product) => {
-        const rootDir = path_1.default.join(root, `.${product}`);
-        const skillsRoot = path_1.default.join(rootDir, "skills");
+function configuredSkillMirrorTargets(config) {
+    const configured = config?.customization.skill_mirrors.targets ?? (0, config_1.defaultCustomizationConfig)().skill_mirrors.targets;
+    return Array.from(new Set(configured.map((value) => value.trim()).filter(Boolean)));
+}
+function resolveMirrorTargets(root, config) {
+    return configuredSkillMirrorTargets(config).map((configuredPath) => {
+        const skillsRoot = path_1.default.join(root, configuredPath);
         return {
-            product,
-            rootDir,
+            configuredPath,
+            rootDir: path_1.default.dirname(skillsRoot),
             skillsRoot,
             manifestPath: path_1.default.join(skillsRoot, MANIFEST_FILE),
         };
@@ -55,11 +60,11 @@ function writeManifest(target, managed) {
     fs_1.default.mkdirSync(target.skillsRoot, { recursive: true });
     fs_1.default.writeFileSync(target.manifestPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
 }
-function shouldCreateMirrorRoots(root) {
+function shouldCreateMirrorRoots(root, config) {
     if (MANAGED_ROOT_MARKERS.some((relPath) => fs_1.default.existsSync(path_1.default.join(root, relPath)))) {
         return true;
     }
-    return resolveMirrorTargets(root).some((target) => fs_1.default.existsSync(target.rootDir) || fs_1.default.existsSync(target.skillsRoot));
+    return resolveMirrorTargets(root, config).some((target) => fs_1.default.existsSync(target.rootDir) || fs_1.default.existsSync(target.skillsRoot));
 }
 function listAllowedEntries(dirPath) {
     if (!fs_1.default.existsSync(dirPath)) {
@@ -235,7 +240,7 @@ function syncSkillMirrors(options) {
     const sources = loadCanonicalSources(options.root, options.config);
     const createRoots = Boolean(options.createRoots);
     const force = Boolean(options.force);
-    const targets = resolveMirrorTargets(options.root);
+    const targets = resolveMirrorTargets(options.root, options.config);
     let synced = 0;
     let pruned = 0;
     let touchedTargets = 0;
@@ -280,7 +285,7 @@ function preflightSkillMirrorTargets(options) {
     if (slugs.length === 0) {
         return;
     }
-    for (const target of resolveMirrorTargets(options.root)) {
+    for (const target of resolveMirrorTargets(options.root, options.config)) {
         if (!fs_1.default.existsSync(target.rootDir) && !fs_1.default.existsSync(target.skillsRoot)) {
             continue;
         }
@@ -293,18 +298,18 @@ function preflightSkillMirrorTargets(options) {
         }
     }
 }
-function shouldMaintainSkillMirrors(root) {
-    return shouldCreateMirrorRoots(root);
+function shouldMaintainSkillMirrors(root, config) {
+    return shouldCreateMirrorRoots(root, config);
 }
 function auditSkillMirrors(root, config) {
-    const shouldAudit = shouldCreateMirrorRoots(root);
+    const shouldAudit = shouldCreateMirrorRoots(root, config);
     if (!shouldAudit) {
         return [];
     }
     const warnings = [];
     const sources = loadCanonicalSources(root, config);
     const sourceBySlug = new Map(sources.map((source) => [source.slug, source]));
-    for (const target of resolveMirrorTargets(root)) {
+    for (const target of resolveMirrorTargets(root, config)) {
         if (!fs_1.default.existsSync(target.skillsRoot)) {
             warnings.push(`${path_1.default.relative(root, target.skillsRoot)}: mirror root missing; run \`mdkg skill sync\``);
             continue;
@@ -335,8 +340,8 @@ function auditSkillMirrors(root, config) {
     }
     return warnings;
 }
-function scaffoldMirrorRoots(root) {
-    for (const target of resolveMirrorTargets(root)) {
+function scaffoldMirrorRoots(root, config) {
+    for (const target of resolveMirrorTargets(root, config)) {
         fs_1.default.mkdirSync(target.skillsRoot, { recursive: true });
         if (!fs_1.default.existsSync(target.manifestPath)) {
             writeManifest(target, []);

package/dist/commands/skill_support.js

@@ -52,7 +52,7 @@ function registryTemplate() {
         "This directory stores Agent Skills packages used by mdkg tooling and orchestrators.",
         "",
         "Use `mdkg skill new <slug> \"<name>\" --description \"...\"` to scaffold a new skill from the built-in Anthropic-aligned template.",
-        "Use `mdkg skill sync` to mirror canonical skills into `.agents/skills/` and `.claude/skills/` when agent bootstrap is enabled.",
+        "Use `mdkg skill sync` to mirror canonical skills into configured `.mdkg/config.json` targets; defaults are `.agents/skills/` and `.claude/skills/`.",
         "Use `CLI_COMMAND_MATRIX.md` as the canonical command and flag reference when updating skill procedures.",
         "",
         "## Conventions",

package/dist/commands/spec.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runSpecListCommand = runSpecListCommand;
 exports.runSpecShowCommand = runSpecShowCommand;
 exports.runSpecValidateCommand = runSpecValidateCommand;
+exports.runManifestListCommand = runManifestListCommand;
+exports.runManifestShowCommand = runManifestShowCommand;
+exports.runManifestValidateCommand = runManifestValidateCommand;
 const capability_1 = require("./capability");
 const validate_1 = require("./validate");
 const errors_1 = require("../util/errors");
@@ -24,6 +27,9 @@ function loadSpecRecords(options) {
     };
     return sortSpecRecords((0, capability_1.filterCapabilityRecords)((0, capability_1.loadCapabilityRecords)(listOptions), listOptions));
 }
+function commandSurface(options) {
+    return options.surface ?? "spec";
+}
 function matchesSpecRef(record, id) {
     const normalized = id.toLowerCase();
     return (record.id === id ||
@@ -34,15 +40,15 @@ function matchesSpecRef(record, id) {
         record.path.toLowerCase() === normalized ||
         record.aliases.some((alias) => alias.toLowerCase() === normalized));
 }
-function resolveSpecRecord(records, id) {
+function resolveSpecRecord(records, id, surface) {
     const matches = records.filter((record) => matchesSpecRef(record, id));
     if (matches.length === 1) {
         return matches[0];
     }
     if (matches.length > 1) {
-        throw new errors_1.UsageError(`SPEC reference is ambiguous: ${id}`);
+        throw new errors_1.UsageError(`${surface === "manifest" ? "manifest capability" : "SPEC"} reference is ambiguous: ${id}`);
     }
-    throw new errors_1.NotFoundError(`SPEC not found: ${id}`);
+    throw new errors_1.NotFoundError(`${surface === "manifest" ? "manifest capability" : "SPEC"} not found: ${id}`);
 }
 function stringValue(value) {
     return typeof value === "string" ? value : undefined;
@@ -50,33 +56,74 @@ function stringValue(value) {
 function stringArrayValue(value) {
     return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
-function printSpecList(records, json) {
+function compatibilityLabel(record) {
+    const mode = record.manifest?.compatibility_mode;
+    if (mode === "legacy") {
+        return "legacy SPEC.md";
+    }
+    if (mode === "transitional") {
+        return "transitional MANIFEST.md type: spec";
+    }
+    return "MANIFEST.md";
+}
+function legacySpecDeprecation() {
+    return "mdkg spec is a legacy alias for mdkg manifest during the one-compatibility-release bridge.";
+}
+function printSpecList(records, json, surface = "spec") {
     if (json) {
-        console.log(JSON.stringify({
-            kind: "spec",
-            count: records.length,
-            items: records,
-        }, null, 2));
+        const receipt = surface === "manifest"
+            ? {
+                kind: "manifest",
+                compatibility_kind: "spec",
+                count: records.length,
+                items: records,
+            }
+            : {
+                kind: "spec",
+                canonical_kind: "manifest",
+                legacy_alias: true,
+                deprecation: legacySpecDeprecation(),
+                count: records.length,
+                items: records,
+            };
+        console.log(JSON.stringify(receipt, null, 2));
         return;
     }
+    if (surface === "spec") {
+        console.log(legacySpecDeprecation());
+    }
     if (records.length === 0) {
-        console.log("no SPEC.md capabilities found");
+        console.log("no MANIFEST.md/SPEC.md capabilities found");
         return;
     }
-    console.log(`SPEC.md capabilities: ${records.length}`);
+    console.log(`${surface === "manifest" ? "MANIFEST.md" : "MANIFEST.md/SPEC.md"} capabilities: ${records.length}`);
     for (const record of records) {
         const kind = stringValue(record.spec?.spec_kind);
         const kindLabel = kind ? ` | ${kind}` : "";
-        console.log(`${record.qid} | ${record.visibility}${kindLabel} | ${record.title}`);
+        console.log(`${record.qid} | ${record.visibility}${kindLabel} | ${compatibilityLabel(record)} | ${record.title}`);
     }
 }
-function printSpec(record, json) {
+function printSpec(record, json, surface = "spec") {
     if (json) {
-        console.log(JSON.stringify({ kind: "spec", item: record }, null, 2));
+        const receipt = surface === "manifest"
+            ? { kind: "manifest", compatibility_kind: "spec", item: record }
+            : {
+                kind: "spec",
+                canonical_kind: "manifest",
+                legacy_alias: true,
+                deprecation: legacySpecDeprecation(),
+                item: record,
+            };
+        console.log(JSON.stringify(receipt, null, 2));
         return;
     }
+    if (surface === "spec") {
+        console.log(legacySpecDeprecation());
+    }
     console.log(`${record.qid} | ${record.visibility}`);
     console.log(`title: ${record.title}`);
+    console.log(`semantic_kind: ${record.manifest?.semantic_kind ?? "manifest"}`);
+    console.log(`compatibility: ${compatibilityLabel(record)}`);
     const specKind = stringValue(record.spec?.spec_kind);
     if (specKind) {
         console.log(`spec_kind: ${specKind}`);
@@ -88,14 +135,26 @@ function printSpec(record, json) {
     }
 }
 function runSpecListCommand(options) {
-    printSpecList(loadSpecRecords(options), options.json);
+    const surface = commandSurface(options);
+    printSpecList(loadSpecRecords(options), options.json, surface);
 }
 function runSpecShowCommand(options) {
-    printSpec(resolveSpecRecord(loadSpecRecords(options), options.id), options.json);
+    const surface = commandSurface(options);
+    printSpec(resolveSpecRecord(loadSpecRecords(options), options.id, surface), options.json, surface);
 }
 function runSpecValidateCommand(options) {
+    const surface = commandSurface(options);
     if (options.id) {
-        resolveSpecRecord(loadSpecRecords(options), options.id);
+        resolveSpecRecord(loadSpecRecords(options), options.id, surface);
     }
     (0, validate_1.runValidateCommand)({ root: options.root, json: options.json });
 }
+function runManifestListCommand(options) {
+    runSpecListCommand({ ...options, surface: "manifest" });
+}
+function runManifestShowCommand(options) {
+    runSpecShowCommand({ ...options, surface: "manifest" });
+}
+function runManifestValidateCommand(options) {
+    runSpecValidateCommand({ ...options, surface: "manifest" });
+}

package/dist/commands/subgraph.js

@@ -323,6 +323,9 @@ function runSubgraphVerifyCommand(options) {
         throw new errors_1.ValidationError("subgraph verify failed");
     }
 }
+function dirtySourceGuidance(paths) {
+    return `source_path has dirty tracked changes: ${paths.join(", ")}; commit or stash the child repo first, then refresh the root-owned subgraph bundle from the clean accepted child commit`;
+}
 function pushAuditCheck(receipt, check) {
     receipt.checks.push(check);
     if (!check.ok && check.severity === "error") {
@@ -349,7 +352,7 @@ function auditOneAlias(options) {
         source_repo: options.health.source_repo,
         capability_summary: {
             node_count: options.nodeTypes.length,
-            spec_count: options.nodeTypes.filter((type) => type === "spec").length,
+            spec_count: options.nodeTypes.filter((type) => type === "manifest" || type === "spec").length,
             work_count: options.nodeTypes.filter((type) => type === "work").length,
             skill_count: options.nodeTypes.filter((type) => type === "skill").length,
         },
@@ -392,7 +395,7 @@ function auditOneAlias(options) {
                 ok: !gitState.dirtyTracked,
                 severity: "warning",
                 message: gitState.dirtyTracked
-                    ? `source_path has dirty tracked changes: ${gitState.dirtyTrackedPaths.join(", ")}`
+                    ? dirtySourceGuidance(gitState.dirtyTrackedPaths)
                     : "source_path has no dirty tracked changes",
                 path: options.subgraph.source_path,
                 details: { dirty_tracked_paths: gitState.dirtyTrackedPaths },
@@ -539,7 +542,7 @@ function upgradePlanForAlias(options) {
         blockers.push(sourceGitError.message);
     }
     if (options.audit.dirty_tracked) {
-        blockers.push(`source_path has dirty tracked changes: ${options.audit.dirty_tracked_paths?.join(", ")}`);
+        blockers.push(dirtySourceGuidance(options.audit.dirty_tracked_paths ?? []));
     }
     const rootOwnedErrors = options.audit.checks.filter((check) => check.id === "subgraph.bundle.root_owned" && !check.ok);
     blockers.push(...rootOwnedErrors.map((check) => check.message));
@@ -705,7 +708,7 @@ function inspectSourcePath(root, alias, subgraph, allowDirty) {
         ? status.stdout.split(/\r?\n/).map((line) => line.slice(3)).filter(Boolean).sort()
         : [];
     if (dirtyTrackedPaths.length > 0 && !allowDirty) {
-        throw new errors_1.UsageError(`subgraph ${alias} source_path has dirty tracked changes: ${dirtyTrackedPaths.join(", ")}`);
+        throw new errors_1.UsageError(`subgraph ${alias} ${dirtySourceGuidance(dirtyTrackedPaths)}`);
     }
     return {
         sourceRoot,