mdkg 0.3.7 → 0.3.8

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,

package/dist/commands/upgrade.js

@@ -15,6 +15,8 @@ const project_db_1 = require("../core/project_db");
 const errors_1 = require("../util/errors");
 const frontmatter_1 = require("../graph/frontmatter");
 const workspace_files_1 = require("../graph/workspace_files");
+const agent_file_types_1 = require("../graph/agent_file_types");
+const atomic_1 = require("../util/atomic");
 const init_manifest_1 = require("./init_manifest");
 const skill_support_1 = require("./skill_support");
 const skill_mirror_1 = require("./skill_mirror");
@@ -65,6 +67,13 @@ function writeFile(filePath, content) {
     fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
     fs_1.default.writeFileSync(filePath, content, "utf8");
 }
+function repoRelativePath(root, filePath) {
+    return path_1.default.relative(root, filePath).split(path_1.default.sep).join("/");
+}
+function renderFrontmatterDocument(frontmatter, body) {
+    const frontmatterBlock = ["---", ...(0, frontmatter_1.formatFrontmatter)(frontmatter, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER), "---"].join("\n");
+    return body.length > 0 ? `${frontmatterBlock}\n${body}` : frontmatterBlock;
+}
 function createSummary() {
     return {
         created: 0,
@@ -323,9 +332,59 @@ function migrateClosedGoalActiveNodes(root, dryRun, summary, changes) {
                     frontmatter.last_active_node = activeNode;
                 }
                 delete frontmatter.active_node;
-                const frontmatterBlock = ["---", ...(0, frontmatter_1.formatFrontmatter)(frontmatter, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER), "---"].join("\n");
-                const body = parsed.body.length > 0 ? parsed.body : "";
-                writeFile(filePath, body.length > 0 ? `${frontmatterBlock}\n${body}` : frontmatterBlock);
+                writeFile(filePath, renderFrontmatterDocument(frontmatter, parsed.body.length > 0 ? parsed.body : ""));
+            }
+        }
+    }
+    if (planned === 0) {
+        summary.unchanged += 1;
+    }
+}
+function migrateLegacySpecManifests(root, dryRun, summary, changes) {
+    const config = (0, config_1.validateConfigSchema)((0, migrate_1.migrateConfig)(JSON.parse(fs_1.default.readFileSync((0, paths_1.configPath)(root), "utf8"))).config);
+    const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(root, config);
+    let planned = 0;
+    for (const files of Object.values(filesByAlias)) {
+        for (const filePath of files) {
+            if (path_1.default.basename(filePath) !== agent_file_types_1.LEGACY_SPEC_BASENAME) {
+                continue;
+            }
+            const content = fs_1.default.readFileSync(filePath, "utf8");
+            let parsed;
+            try {
+                parsed = (0, frontmatter_1.parseFrontmatter)(content, filePath);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.frontmatter.type !== "spec") {
+                continue;
+            }
+            planned += 1;
+            const targetPath = path_1.default.join(path_1.default.dirname(filePath), agent_file_types_1.CANONICAL_MANIFEST_BASENAME);
+            const relativePath = repoRelativePath(root, filePath);
+            const relativeTargetPath = repoRelativePath(root, targetPath);
+            if (fs_1.default.existsSync(targetPath)) {
+                record(summary, changes, {
+                    path: relativePath,
+                    target_path: relativeTargetPath,
+                    category: "manifest_migration",
+                    action: "conflict",
+                    reason: "sibling MANIFEST.md already exists; legacy SPEC.md content preserved",
+                });
+                continue;
+            }
+            record(summary, changes, {
+                path: relativePath,
+                target_path: relativeTargetPath,
+                category: "manifest_migration",
+                action: "migrate",
+                reason: "rename legacy SPEC.md to MANIFEST.md and normalize type: spec to type: manifest",
+            });
+            if (!dryRun) {
+                const frontmatter = { ...parsed.frontmatter, type: "manifest" };
+                (0, atomic_1.atomicWriteFile)(filePath, renderFrontmatterDocument(frontmatter, parsed.body));
+                fs_1.default.renameSync(filePath, targetPath);
             }
         }
     }
@@ -422,6 +481,9 @@ function ensureArchiveIgnorePolicy(root, dryRun, summary, changes) {
 function isWritableChange(change) {
     return change.action === "create" || change.action === "update" || change.action === "migrate" || change.action === "sync";
 }
+function writablePathForChange(change) {
+    return change.target_path ?? change.path;
+}
 function buildApplySideEffects(options) {
     const hasDirectWrites = options.changes.some(isWritableChange);
     if (!hasDirectWrites && options.existingManifest) {
@@ -468,7 +530,8 @@ function emitHumanReceipt(receipt) {
     }
     else {
         for (const change of receipt.changes) {
-            console.log(`  ${change.action}: ${change.path} (${change.reason})`);
+            const target = change.target_path ? ` -> ${change.target_path}` : "";
+            console.log(`  ${change.action}: ${change.path}${target} (${change.reason})`);
         }
     }
     if (receipt.apply_side_effects.length > 0) {
@@ -501,6 +564,7 @@ function runUpgradeCommand(options) {
     const managedCurrentFiles = [];
     migrateConfigIfNeeded(root, dryRun, summary, changes);
     migrateClosedGoalActiveNodes(root, dryRun, summary, changes);
+    migrateLegacySpecManifests(root, dryRun, summary, changes);
     for (const file of currentManifest.files) {
         if (!shouldIncludeFile(file, agentWorkspace)) {
             continue;
@@ -544,8 +608,8 @@ function runUpgradeCommand(options) {
         }
     }
     const preservedCustomizations = changes.filter((change) => change.action === "conflict");
-    const blockingConflicts = [];
-    const willWritePaths = changes.filter(isWritableChange).map((change) => change.path);
+    const blockingConflicts = changes.filter((change) => change.action === "conflict" && change.category === "manifest_migration");
+    const willWritePaths = changes.filter(isWritableChange).map(writablePathForChange);
     const receipt = {
         action: "upgrade",
         dry_run: dryRun,

package/dist/commands/validate.js

@@ -129,6 +129,20 @@ function collectRawContentWarnings(qid, node) {
     }
     return warnings;
 }
+function collectManifestCompatibilityWarnings(qid, filePath, node) {
+    const basename = path_1.default.basename(filePath);
+    if (basename === agent_file_types_1.LEGACY_SPEC_BASENAME && node.type === "spec") {
+        return [
+            `${qid}: manifest.compat.spec_legacy warning: SPEC.md is legacy; MANIFEST.md is the canonical manifest filename. Rename this file before the compatibility release closes.`,
+        ];
+    }
+    if (basename === agent_file_types_1.CANONICAL_MANIFEST_BASENAME && node.type === "spec") {
+        return [
+            `${qid}: manifest.compat.type_spec warning: MANIFEST.md uses legacy type: spec; use type: manifest before the compatibility release closes.`,
+        ];
+    }
+    return [];
+}
 function collectChangedPaths(root) {
     const result = (0, child_process_1.spawnSync)("git", ["-C", root, "status", "--porcelain", "--", ".mdkg"], {
         encoding: "utf8",
@@ -166,6 +180,7 @@ function warningPath(message, nodes) {
 }
 function warningDiagnostic(message, nodes) {
     const qid = qidFromWarning(message);
+    const nodeType = qid && nodes[qid] ? nodes[qid].type : undefined;
     const pathValue = warningPath(message, nodes);
     const rawMatch = /raw-content\.([a-z_]+)/.exec(message);
     if (rawMatch) {
@@ -175,6 +190,7 @@ function warningDiagnostic(message, nodes) {
             severity: "warning",
             message,
             qid,
+            node_type: nodeType,
             path: pathValue,
             ref: qid,
             remediation: "Replace raw secrets, prompts, tokens, or payloads with refs, hashes, redacted summaries, or archive/artifact links.",
@@ -187,6 +203,7 @@ function warningDiagnostic(message, nodes) {
             severity: "warning",
             message,
             qid,
+            node_type: nodeType,
             path: pathValue,
             ref: qid,
             remediation: "Run mdkg format --headings --dry-run to review missing heading additions, then --apply if acceptable.",
@@ -198,16 +215,32 @@ function warningDiagnostic(message, nodes) {
             category: "templates",
             severity: "warning",
             message,
+            node_type: nodeType,
             path: pathValue,
             remediation: "Run mdkg upgrade --apply to vendor missing built-in template schemas when the managed asset update is safe.",
         };
     }
+    const manifestCompatMatch = /manifest\.compat\.([a-z_]+)/.exec(message);
+    if (manifestCompatMatch) {
+        return {
+            id: `manifest.compat.${manifestCompatMatch[1]}`,
+            category: "manifest-compatibility",
+            severity: "warning",
+            message,
+            qid,
+            node_type: nodeType,
+            path: pathValue,
+            ref: qid,
+            remediation: "Rename legacy SPEC.md files to MANIFEST.md and update transitional type: spec frontmatter to type: manifest before the compatibility release closes.",
+        };
+    }
     if (message.includes("sqlite") || message.includes("index")) {
         return {
             id: "cache.index",
             category: "cache",
             severity: "warning",
             message,
+            node_type: nodeType,
             path: pathValue,
             remediation: "Run mdkg index or mdkg db index rebuild when generated cache state should be refreshed.",
         };
@@ -218,6 +251,7 @@ function warningDiagnostic(message, nodes) {
             category: "skills",
             severity: "warning",
             message,
+            node_type: nodeType,
             path: pathValue,
             remediation: "Run mdkg skill sync after reviewing managed skill mirror drift.",
         };
@@ -228,6 +262,7 @@ function warningDiagnostic(message, nodes) {
             category: "subgraph",
             severity: "warning",
             message,
+            node_type: nodeType,
             path: pathValue,
             remediation: "Run mdkg subgraph verify or refresh the source bundle after reviewing child graph freshness.",
         };
@@ -238,11 +273,67 @@ function warningDiagnostic(message, nodes) {
         severity: "warning",
         message,
         qid,
+        node_type: nodeType,
         path: pathValue,
         ref: qid,
         remediation: "Review the warning and apply the focused mdkg command suggested by the message when appropriate.",
     };
 }
+function countBuckets(values) {
+    const counts = new Map();
+    for (const value of values) {
+        if (!value) {
+            continue;
+        }
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+    return Array.from(counts.entries())
+        .map(([key, count]) => ({ key, count }))
+        .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
+}
+function normalizeLimit(limit) {
+    if (limit === undefined) {
+        return 50;
+    }
+    if (!Number.isInteger(limit) || limit < 0) {
+        throw new errors_1.ValidationError("--limit must be a non-negative integer");
+    }
+    return limit;
+}
+function buildWarningSummary(diagnostics, limit) {
+    const effectiveLimit = limit === null || limit === undefined ? diagnostics.length : limit;
+    const emitted = Math.min(diagnostics.length, effectiveLimit);
+    const truncated = emitted < diagnostics.length;
+    return {
+        total: diagnostics.length,
+        emitted,
+        truncated,
+        omitted_count: diagnostics.length - emitted,
+        limit: limit === undefined ? null : limit,
+        affected_file_count: new Set(diagnostics.map((diagnostic) => diagnostic.path).filter(Boolean)).size,
+        by_id: countBuckets(diagnostics.map((diagnostic) => diagnostic.id)),
+        by_category: countBuckets(diagnostics.map((diagnostic) => diagnostic.category)),
+        by_node_type: countBuckets(diagnostics.map((diagnostic) => diagnostic.node_type)),
+        top_qids: countBuckets(diagnostics.map((diagnostic) => diagnostic.qid)).slice(0, 25),
+        top_paths: countBuckets(diagnostics.map((diagnostic) => diagnostic.path)).slice(0, 25),
+    };
+}
+function shapeValidateReceiptForSummary(receipt, limit) {
+    const effectiveLimit = normalizeLimit(limit);
+    const warningDiagnostics = receipt.warning_diagnostics.slice(0, effectiveLimit);
+    return {
+        ...receipt,
+        warnings: warningDiagnostics.map((warning) => warning.message),
+        warning_diagnostics: warningDiagnostics,
+        warning_summary: buildWarningSummary(receipt.warning_diagnostics, effectiveLimit),
+    };
+}
+function writeJsonReceipt(root, jsonOut, receipt) {
+    const outPath = path_1.default.resolve(root, jsonOut);
+    fs_1.default.mkdirSync(path_1.default.dirname(outPath), { recursive: true });
+    fs_1.default.writeFileSync(outPath, `${JSON.stringify(receipt, null, 2)}\n`, "utf8");
+    return outPath;
+}
 function isCoreListFile(filePath) {
     return path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core";
 }
@@ -412,6 +503,7 @@ function collectValidateReceipt(options) {
     const idsByWorkspace = {};
     for (const [alias, files] of Object.entries(filesByAlias)) {
         idsByWorkspace[alias] = new Map();
+        errors.push(...(0, agent_file_types_1.collectManifestSiblingConflicts)(files, (dirPath) => path_1.default.relative(options.root, dirPath).split(path_1.default.sep).join("/") || "."));
         for (const filePath of files) {
             if (isCoreListFile(filePath)) {
                 continue;
@@ -450,6 +542,7 @@ function collectValidateReceipt(options) {
                     }
                 }
                 warnings.push(...collectRawContentWarnings(qid, node));
+                warnings.push(...collectManifestCompatibilityWarnings(qid, filePath, node));
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : "unknown error";
@@ -546,6 +639,7 @@ function collectValidateReceipt(options) {
         error_count: uniqueErrors.length,
         warnings: uniqueWarnings,
         warning_diagnostics: filteredWarningDiagnostics,
+        warning_summary: buildWarningSummary(filteredWarningDiagnostics),
         errors: uniqueErrors,
         ...(outPath ? { report_path: outPath } : {}),
         ...(options.changedOnly
@@ -555,18 +649,27 @@ function collectValidateReceipt(options) {
     return receipt;
 }
 function runValidateCommand(options) {
-    const receipt = collectValidateReceipt(options);
+    let receipt = collectValidateReceipt(options);
+    if (options.jsonOut) {
+        const jsonOutPath = path_1.default.resolve(options.root, options.jsonOut);
+        receipt = { ...receipt, json_receipt_path: jsonOutPath };
+        writeJsonReceipt(options.root, options.jsonOut, receipt);
+    }
+    const displayReceipt = options.summary ? shapeValidateReceiptForSummary(receipt, options.limit) : receipt;
     if (options.json) {
-        console.log(JSON.stringify(receipt, null, 2));
+        console.log(JSON.stringify(displayReceipt, null, 2));
         if (receipt.error_count > 0) {
             throw new errors_1.ValidationError(`validation failed with ${receipt.error_count} error(s)`);
         }
         return;
     }
     if (!options.quiet) {
-        for (const warning of receipt.warnings) {
+        for (const warning of displayReceipt.warnings) {
             console.error(`warning: ${warning}`);
         }
+        if (displayReceipt.warning_summary.truncated) {
+            console.error(`warning summary: omitted ${displayReceipt.warning_summary.omitted_count} warning(s); rerun without --summary or use --json-out <path> for full diagnostics`);
+        }
     }
     if (receipt.error_count > 0) {
         if (receipt.report_path) {

package/dist/commands/work.js

@@ -247,6 +247,10 @@ function workflowDiagnosticCode(message) {
     if (message.includes("missing recommended heading")) {
         return "heading.missing";
     }
+    const manifestCompatMatch = /manifest\.compat\.([a-z_]+)/.exec(message);
+    if (manifestCompatMatch) {
+        return `manifest.compat.${manifestCompatMatch[1]}`;
+    }
     if (message.includes("references missing") || message.includes("references missing node")) {
         return "reference.missing";
     }
@@ -384,8 +388,8 @@ function resolveTriggerWorkNode(index, ws, refRaw) {
     if (node.type === "work") {
         return { workNode: node };
     }
-    if (node.type !== "spec") {
-        throw new errors_1.UsageError(`work trigger requires a WORK.md or SPEC.md ref, got ${node.type}: ${node.qid}`);
+    if (!(0, agent_file_types_1.isManifestSemanticType)(node.type)) {
+        throw new errors_1.UsageError(`work trigger requires a WORK.md or MANIFEST.md/SPEC.md ref, got ${node.type}: ${node.qid}`);
     }
     const candidates = new Map();
     const specDir = path_1.default.posix.dirname(node.path);
@@ -411,11 +415,12 @@ function resolveTriggerWorkNode(index, ws, refRaw) {
         }
     }
     const workNodes = Array.from(candidates.values()).sort((a, b) => a.qid.localeCompare(b.qid));
+    const manifestLabel = node.type === "spec" ? "legacy SPEC.md" : "MANIFEST.md";
     if (workNodes.length === 0) {
-        throw new errors_1.NotFoundError(`SPEC.md ${node.qid} has no resolvable WORK.md contract`);
+        throw new errors_1.NotFoundError(`${manifestLabel} ${node.qid} has no resolvable WORK.md contract`);
     }
     if (workNodes.length > 1) {
-        throw new errors_1.UsageError(`SPEC.md ${node.qid} has multiple work contracts; trigger one explicitly: ${workNodes
+        throw new errors_1.UsageError(`${manifestLabel} ${node.qid} has multiple work contracts; trigger one explicitly: ${workNodes
             .map((workNode) => workNode.qid)
             .join(", ")}`);
     }
@@ -757,7 +762,9 @@ function runWorkContractNewCommandLocked(options) {
     const agentId = normalizePortableIdRef(options.agentId, "--agent-id");
     const kind = options.kind.toLowerCase();
     const resolvedAgent = (0, qid_1.resolveQid)(index, agentId, ws);
-    const relates = resolvedAgent.status === "ok" && index.nodes[resolvedAgent.qid]?.type === "spec" ? [agentId] : [];
+    const relates = resolvedAgent.status === "ok" && (0, agent_file_types_1.isManifestSemanticType)(index.nodes[resolvedAgent.qid]?.type ?? "")
+        ? [agentId]
+        : [];
     const requiredCapabilities = parseCsvList(options.requiredCapabilities);
     const receipt = createAgentWorkflowNode({
         root: options.root,