mdkg 0.3.6 → 0.3.8

package/dist/commands/bundle.js

@@ -349,6 +349,8 @@ function publicFilteringErrors(index, includedQids) {
             node.edges.relates,
             node.edges.blocked_by,
             node.edges.blocks,
+            node.edges.context_refs ?? [],
+            node.edges.evidence_refs ?? [],
         ]) {
             for (const target of targets) {
                 if (index.nodes[target] && !includedQids.has(target)) {

package/dist/commands/capability.js

@@ -79,6 +79,7 @@ function capabilitySearchText(record) {
         ...record.aliases,
         ...record.links,
         ...record.headings.map((heading) => heading.text),
+        JSON.stringify(record.manifest ?? {}),
         JSON.stringify(record.spec ?? {}),
         JSON.stringify(record.work ?? {}),
         JSON.stringify(record.linkage ?? {}),

package/dist/commands/checkpoint.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.CHECKPOINT_KINDS = void 0;
 exports.createCheckpoint = createCheckpoint;
 exports.runCheckpointNewCommand = runCheckpointNewCommand;
 const fs_1 = __importDefault(require("fs"));
@@ -17,6 +18,20 @@ const atomic_1 = require("../util/atomic");
 const lock_1 = require("../util/lock");
 const sqlite_index_1 = require("../graph/sqlite_index");
 const event_support_1 = require("./event_support");
+exports.CHECKPOINT_KINDS = [
+    "implementation",
+    "test-proof",
+    "goal-closeout",
+    "audit",
+    "handoff",
+];
+function normalizeCheckpointKind(value) {
+    const normalized = (value ?? "implementation").toLowerCase();
+    if (exports.CHECKPOINT_KINDS.includes(normalized)) {
+        return normalized;
+    }
+    throw new errors_1.UsageError(`--kind must be one of ${exports.CHECKPOINT_KINDS.join(", ")}`);
+}
 function parseCsvList(raw) {
     if (!raw) {
         return [];
@@ -83,6 +98,125 @@ function normalizeWorkspace(value) {
     }
     return normalized;
 }
+function kindSpecificSection(kind) {
+    switch (kind) {
+        case "implementation":
+            return [
+                "# Implementation Details",
+                "",
+                "- Code or graph surfaces changed:",
+                "- Architecture or data-shape notes:",
+                "- Compatibility notes:",
+            ];
+        case "test-proof":
+            return [
+                "# Test Proof",
+                "",
+                "- Test target:",
+                "- Fixtures or temp repos:",
+                "- Coverage gaps:",
+            ];
+        case "goal-closeout":
+            return [
+                "# Goal Closeout",
+                "",
+                "- Goal condition result:",
+                "- Scoped nodes closed:",
+                "- Remaining deferred work:",
+            ];
+        case "audit":
+            return [
+                "# Audit Findings",
+                "",
+                "- Reviewed surfaces:",
+                "- Findings:",
+                "- Residual risk:",
+            ];
+        case "handoff":
+            return [
+                "# Handoff Summary",
+                "",
+                "- Recipient/context:",
+                "- Starting node or command:",
+                "- Explicit boundaries:",
+            ];
+    }
+}
+function checkpointBody(kind) {
+    return [
+        "# Summary",
+        "",
+        "What was completed in this phase? What is now true?",
+        "",
+        "# Scope Covered",
+        "",
+        "Keep `scope` frontmatter updated when possible.",
+        "",
+        "## Changed Surfaces",
+        "",
+        "- files, commands, nodes, docs, or runtime surfaces changed",
+        "",
+        "## Boundaries",
+        "",
+        "- in scope:",
+        "- out of scope:",
+        "- raw secrets, raw prompts, raw payloads, and bulky execution traces excluded:",
+        "",
+        "# Decisions Captured",
+        "",
+        "Link the most important decision records.",
+        "",
+        "# Implementation Summary",
+        "",
+        "What changed? What patterns or architecture emerged?",
+        "",
+        ...kindSpecificSection(kind),
+        "",
+        "# Verification / Testing",
+        "",
+        "## Command Evidence",
+        "",
+        "- command:",
+        "- result:",
+        "",
+        "## Pass / Fail Status",
+        "",
+        "- status:",
+        "",
+        "## Known Warnings",
+        "",
+        "- warning:",
+        "",
+        "# Known Issues / Follow-ups",
+        "",
+        "- issue 1",
+        "- issue 2",
+        "",
+        "## Follow-up Refs",
+        "",
+        "- task/test/goal refs:",
+        "",
+        "# Links / Artifacts",
+        "",
+        "- packs",
+        "- PRs/commits",
+        "- docs",
+        "- dashboards",
+        "",
+        "# Raw Content Safety",
+        "",
+        "- Summarize evidence and use refs, hashes, and artifact links instead of raw secrets, raw prompts, raw payloads, or bulky execution traces.",
+        "",
+    ].join("\n");
+}
+function replaceRenderedBody(content, body) {
+    const marker = "\n---\n";
+    const start = content.indexOf(marker);
+    if (!content.startsWith("---\n") || start === -1) {
+        return content;
+    }
+    return `${content.slice(0, start + marker.length)}${body}`;
+}
 function createCheckpointLocked(options) {
     const title = options.title.trim();
     if (!title) {
@@ -130,12 +264,14 @@ function createCheckpointLocked(options) {
         }
     }
     const scope = parseCsvList(options.scope).map((value) => normalizeId(value, "--scope"));
+    const kind = normalizeCheckpointKind(options.kind);
     const now = options.now ?? new Date();
     const today = (0, date_1.formatDate)(now);
     const template = (0, loader_1.loadTemplate)(options.root, config, "checkpoint", options.template);
     const content = (0, loader_1.renderTemplate)(template, {
         id,
         title,
+        checkpoint_kind: kind,
         status,
         priority,
         created: today,
@@ -143,8 +279,9 @@ function createCheckpointLocked(options) {
         relates,
         scope,
     });
+    const rendered = replaceRenderedBody(content, checkpointBody(kind));
     try {
-        (0, atomic_1.writeFileExclusive)(filePath, content);
+        (0, atomic_1.writeFileExclusive)(filePath, rendered);
     }
     catch (err) {
         const code = typeof err === "object" && err !== null && "code" in err ? String(err.code) : "";
@@ -168,6 +305,7 @@ function createCheckpointLocked(options) {
         id,
         qid: `${ws}:${id}`,
         path: path_1.default.relative(options.root, filePath),
+        kind,
     };
 }
 function createCheckpoint(options) {

package/dist/commands/db.js

@@ -9,6 +9,7 @@ exports.runDbMigrateCommand = runDbMigrateCommand;
 exports.runDbVerifyCommand = runDbVerifyCommand;
 exports.runDbStatsCommand = runDbStatsCommand;
 exports.runDbQueueCreateCommand = runDbQueueCreateCommand;
+exports.runDbQueueContractCommand = runDbQueueContractCommand;
 exports.runDbQueuePauseCommand = runDbQueuePauseCommand;
 exports.runDbQueueResumeCommand = runDbQueueResumeCommand;
 exports.runDbQueueEnqueueCommand = runDbQueueEnqueueCommand;
@@ -36,6 +37,7 @@ const project_db_1 = require("../core/project_db");
 const project_db_migrations_1 = require("../core/project_db_migrations");
 const project_db_snapshot_1 = require("../core/project_db_snapshot");
 const project_db_queue_1 = require("../core/project_db_queue");
+const project_db_queue_contract_1 = require("../core/project_db_queue_contract");
 const version_1 = require("../core/version");
 const index_1 = require("./index");
 const capabilities_indexer_1 = require("../graph/capabilities_indexer");
@@ -539,6 +541,12 @@ function runDbQueueCreateCommand(options) {
         reason: options.reason,
     }), "db-queue-create");
 }
+function runDbQueueContractCommand(options) {
+    writeQueueJsonOrText("db-queue-contract", {
+        mdkg_version: (0, version_1.readPackageVersion)(),
+        contract: (0, project_db_queue_contract_1.projectDbQueueAdapterContract)(),
+    }, options.json);
+}
 function runDbQueuePauseCommand(options) {
     runQueueMutation(options, (databasePath) => ({ queue: (0, project_db_queue_1.pauseProjectQueue)(databasePath, { queue_name: requireQueueName(options), reason: options.reason }) }), "db-queue-pause");
 }

package/dist/commands/doctor.js

@@ -164,8 +164,8 @@ function runArchiveStorageCheck(root) {
         name: "archive-storage",
         ok: true,
         level: "warn",
-        detail: `stray uncompressed archive file(s) found without managed sidecars: ${strayRaw.join(", ")}; run \`mdkg archive add <file>\` or move raw files under a managed archive source directory`,
-        remediation: "Run `mdkg archive add <file>` or move raw files under a managed archive source directory.",
+        detail: `stray uncompressed archive file(s) found without managed sidecars: ${strayRaw.join(", ")}; these are storage hygiene warnings, not source defects`,
+        remediation: "Either run `mdkg archive add <file>` to create a managed sidecar, move raw files under an existing managed archive source directory, or remove unintended local files before committing.",
         refs: strayRaw,
     });
 }
@@ -255,8 +255,8 @@ function runProjectDbRuntimePolicyCheck(root) {
         name: "project-db-runtime",
         ok: true,
         level: "warn",
-        detail: `active project DB runtime/transient file(s) are local-only and should not be committed: ${files.join(", ")}`,
-        remediation: "Keep runtime DB and transient files ignored; commit sealed state only by explicit repo policy.",
+        detail: `active project DB runtime/transient file(s) are local-only and should not be committed: ${files.join(", ")}; this is expected local state when \`mdkg db verify\` passes`,
+        remediation: "Keep runtime DB and transient files ignored, run `mdkg db verify --json` if DB health is in question, and commit sealed state only by explicit repo policy.",
         refs: files,
     });
 }
@@ -386,7 +386,7 @@ function runSelectedGoalChecks(root, config, options) {
                 ok: true,
                 level: "warn",
                 detail: selected.warning,
-                remediation: "Run `mdkg goal select <goal-id>` or `mdkg goal clear`.",
+                remediation: "Run `mdkg goal clear --json` when no repo-local goal should be selected, or create/select a repo-local active goal only when work is continuing.",
                 strictFail: true,
             }),
         ];
@@ -418,7 +418,7 @@ function runSelectedGoalChecks(root, config, options) {
                     ok: true,
                     level: "warn",
                     detail: `selected goal ${selected.state.qid} is missing from the graph`,
-                    remediation: "Run `mdkg goal select <active-goal>` or `mdkg goal clear`.",
+                    remediation: "Run `mdkg goal clear --json` when no repo-local goal should be selected, or `mdkg goal activate <goal-id> --json` for the next active repo-local goal.",
                     refs: [selected.state.qid],
                     strictFail: true,
                 }),
@@ -433,7 +433,7 @@ function runSelectedGoalChecks(root, config, options) {
                     ok: true,
                     level: "warn",
                     detail: `selected goal ${selected.state.qid} is achieved but still current`,
-                    remediation: "Run `mdkg goal select <active-goal>` or `mdkg goal clear`.",
+                    remediation: "Run `mdkg goal clear --json` for an achieved current goal, or `mdkg goal activate <goal-id> --json` only when a new repo-local goal should become active. Root orchestrators should not mutate dirty child repos without approval.",
                     refs: [selected.state.qid],
                     strictFail: true,
                 }),

package/dist/commands/format.js

@@ -19,6 +19,7 @@ const id_1 = require("../util/id");
 const refs_1 = require("../util/refs");
 const atomic_1 = require("../util/atomic");
 const lock_1 = require("../util/lock");
+const validate_1 = require("./validate");
 const DEC_ID_RE = /^dec-[0-9]+$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const ID_LIST_KEYS = new Set(["refs", "scope"]);
@@ -46,6 +47,62 @@ function isValidId(value) {
 function isCoreListFile(filePath) {
     return path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core";
 }
+function normalizeHeading(value) {
+    return value.trim().toLowerCase();
+}
+function existingHeadings(body) {
+    const headings = new Set();
+    for (const line of body.split(/\r?\n/)) {
+        const match = /^#+\s+(.*)$/.exec(line);
+        if (match) {
+            headings.add(normalizeHeading(match[1] ?? ""));
+        }
+    }
+    return headings;
+}
+function appendMissingHeadings(body, headings) {
+    if (headings.length === 0) {
+        return body;
+    }
+    const trimmed = body.replace(/\s+$/g, "");
+    const prefix = trimmed.length > 0 ? `${trimmed}\n\n` : "";
+    return `${prefix}${headings.map((heading) => `# ${heading}\n`).join("\n")}`;
+}
+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 buildHeadingsSummary(changes, limit) {
+    const effectiveLimit = limit === null || limit === undefined ? changes.length : limit;
+    const emitted = Math.min(changes.length, effectiveLimit);
+    return {
+        total: changes.length,
+        emitted,
+        truncated: emitted < changes.length,
+        omitted_count: changes.length - emitted,
+        limit: limit === undefined ? null : limit,
+        affected_file_count: new Set(changes.map((change) => change.path)).size,
+        by_node_type: countBuckets(changes.map((change) => change.type)),
+        top_paths: countBuckets(changes.map((change) => change.path)).slice(0, 25),
+    };
+}
 function normalizeScalar(value) {
     return value.trim();
 }
@@ -250,7 +307,105 @@ function normalizeFrontmatter(frontmatter, schema, type, workStatusEnum, priorit
     }
     return { normalized, errors };
 }
+function runHeadingFormatCommandLocked(options) {
+    if (options.dryRun && options.apply) {
+        throw new errors_1.ValidationError("format --headings cannot use --dry-run and --apply together");
+    }
+    const config = (0, config_1.loadConfig)(options.root);
+    const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(options.root, config);
+    const errors = [];
+    const changes = [];
+    for (const files of Object.values(filesByAlias)) {
+        for (const filePath of files) {
+            if (isCoreListFile(filePath)) {
+                continue;
+            }
+            let content = "";
+            try {
+                content = fs_1.default.readFileSync(filePath, "utf8");
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : "unknown error";
+                errors.push(`${filePath}: failed to read file: ${message}`);
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = (0, frontmatter_1.parseFrontmatter)(content, filePath);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : "unknown error";
+                errors.push(message);
+                continue;
+            }
+            const typeValue = parsed.frontmatter.type;
+            if (typeof typeValue !== "string") {
+                errors.push(`${filePath}: type is required`);
+                continue;
+            }
+            const type = typeValue.toLowerCase();
+            const recommended = validate_1.RECOMMENDED_HEADINGS[type];
+            if (!recommended) {
+                continue;
+            }
+            if (!node_1.ALLOWED_TYPES.has(type)) {
+                errors.push(`${filePath}: type must be one of ${Array.from(node_1.ALLOWED_TYPES).join(", ")}`);
+                continue;
+            }
+            const present = existingHeadings(parsed.body);
+            const addedHeadings = recommended.filter((heading) => !present.has(normalizeHeading(heading)));
+            if (addedHeadings.length === 0) {
+                continue;
+            }
+            const frontmatterEnd = content.indexOf("---", 3);
+            const frontmatterBlock = frontmatterEnd >= 0 ? content.slice(0, frontmatterEnd + 3) : ["---", ...(0, frontmatter_1.formatFrontmatter)(parsed.frontmatter, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER), "---"].join("\n");
+            const nextBody = appendMissingHeadings(parsed.body, addedHeadings);
+            const nextContent = `${frontmatterBlock}\n${nextBody.endsWith("\n") ? nextBody : `${nextBody}\n`}`;
+            changes.push({
+                filePath,
+                path: path_1.default.relative(options.root, filePath).split(path_1.default.sep).join("/"),
+                id: typeof parsed.frontmatter.id === "string" ? parsed.frontmatter.id : undefined,
+                type,
+                added_headings: addedHeadings,
+                content: nextContent,
+            });
+        }
+    }
+    if (errors.length > 0) {
+        for (const error of errors) {
+            console.error(error);
+        }
+        throw new errors_1.ValidationError(`format --headings failed with ${errors.length} error(s)`);
+    }
+    const apply = options.apply === true;
+    if (apply) {
+        for (const change of changes) {
+            (0, atomic_1.atomicWriteFile)(change.filePath, change.content);
+        }
+    }
+    const publicChanges = changes.map(({ filePath: _filePath, content: _content, ...change }) => change);
+    const summaryLimit = options.summary ? normalizeLimit(options.limit) : undefined;
+    const emittedChanges = options.summary ? publicChanges.slice(0, summaryLimit) : publicChanges;
+    const receipt = {
+        action: "format.headings",
+        ok: true,
+        dry_run: !apply,
+        applied: apply,
+        changed_count: changes.length,
+        summary: buildHeadingsSummary(publicChanges, summaryLimit),
+        changes: emittedChanges,
+    };
+    if (options.json) {
+        console.log(JSON.stringify(receipt, null, 2));
+        return;
+    }
+    console.log(`${apply ? "format headings updated" : "format headings dry-run"} ${changes.length} file(s)`);
+}
 function runFormatCommandLocked(options) {
+    if (options.headings) {
+        runHeadingFormatCommandLocked(options);
+        return;
+    }
     const config = (0, config_1.loadConfig)(options.root);
     const templateSchemas = (0, template_schema_1.loadTemplateSchemas)(options.root, config, node_1.ALLOWED_TYPES);
     const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(options.root, config);

package/dist/commands/goal.js

@@ -227,6 +227,7 @@ function goalReceipt(root, loaded) {
         goal_condition: String(fm.goal_condition ?? ""),
         scope_refs: toStringList(fm.scope_refs),
         active_node: optionalString(fm.active_node),
+        last_active_node: optionalString(fm.last_active_node),
         required_skills: toStringList(fm.required_skills),
         required_checks: toStringList(fm.required_checks),
         max_iterations: optionalString(fm.max_iterations),
@@ -276,6 +277,11 @@ function isConcreteCandidate(node, statusRanks) {
     }
     return node.status !== "done";
 }
+function isAchievedGoal(node, frontmatter) {
+    const status = frontmatter ? String(frontmatter.status ?? "") : node.status;
+    const goalState = frontmatter ? String(frontmatter.goal_state ?? "") : String(node.attributes.goal_state ?? "");
+    return status === "done" || goalState === "achieved";
+}
 function resolveCandidate(index, idOrQid, ws) {
     const resolved = (0, qid_1.resolveQid)(index, idOrQid, ws);
     if (resolved.status !== "ok") {
@@ -283,6 +289,29 @@ function resolveCandidate(index, idOrQid, ws) {
     }
     return index.nodes[resolved.qid];
 }
+function readOnlySubgraphBlockerWarnings(index, qids) {
+    const warnings = [];
+    const seen = new Set();
+    for (const qid of [...qids].sort()) {
+        const node = index.nodes[qid];
+        if (!node || node.source?.imported || node.status === "done") {
+            continue;
+        }
+        for (const blockerQid of node.edges.blocked_by) {
+            const blocker = index.nodes[blockerQid];
+            if (!blocker?.source?.imported) {
+                continue;
+            }
+            const subgraph = blocker.source.subgraph_alias;
+            const warning = `${node.qid} is blocked by read-only subgraph node ${blocker.qid}; update the source workspace for subgraph ${subgraph} or refresh the subgraph bundle before claiming local work`;
+            if (!seen.has(warning)) {
+                seen.add(warning);
+                warnings.push(warning);
+            }
+        }
+    }
+    return warnings;
+}
 function runGoalShowCommand(options) {
     const loaded = loadGoal(options.root, options.id, options.ws);
     const receipt = { action: "showed", goal: goalReceipt(options.root, loaded) };
@@ -296,6 +325,9 @@ function runGoalShowCommand(options) {
     if (loaded.frontmatter.active_node) {
         console.log(`active_node: ${loaded.frontmatter.active_node}`);
     }
+    if (loaded.frontmatter.last_active_node) {
+        console.log(`last_active_node: ${loaded.frontmatter.last_active_node}`);
+    }
     const checks = toStringList(loaded.frontmatter.required_checks);
     console.log(`required_checks: ${checks.length === 0 ? "none" : checks.join(", ")}`);
 }
@@ -351,6 +383,23 @@ function runGoalNextCommand(options) {
         console.error("no actionable local work found for goal");
         return;
     }
+    if (isAchievedGoal(loaded.node, loaded.frontmatter)) {
+        if (options.json) {
+            console.log(JSON.stringify({
+                action: "selected",
+                goal: goalReceipt(options.root, loaded),
+                goal_source: loaded.resolutionSource,
+                node: null,
+                warnings: loaded.warnings,
+            }, null, 2));
+            return;
+        }
+        for (const warning of loaded.warnings) {
+            console.error(`warning: ${warning}`);
+        }
+        console.error("no actionable local work found for achieved goal");
+        return;
+    }
     const statusPreference = loaded.config.work.next.status_preference.map((status) => status.toLowerCase());
     const statusRanks = new Set(statusPreference);
     const warnings = [...loaded.warnings];
@@ -362,6 +411,7 @@ function runGoalNextCommand(options) {
     for (const invalid of scope.invalidRefs) {
         warnings.push(`scope contains non-actionable or unsupported node: ${invalid}`);
     }
+    warnings.push(...readOnlySubgraphBlockerWarnings(loaded.index, scope.actionableQids));
     if (activeNode) {
         const node = resolveCandidate(loaded.index, activeNode, loaded.node.ws);
         if (node && scope.actionableQids.has(node.qid) && isConcreteCandidate(node, statusRanks)) {
@@ -549,6 +599,7 @@ function runGoalCurrentCommand(options) {
             goal_condition: String(node.attributes.goal_condition ?? ""),
             scope_refs: toStringList(node.attributes.scope_refs),
             active_node: optionalString(node.attributes.active_node),
+            last_active_node: optionalString(node.attributes.last_active_node),
             required_skills: toStringList(node.attributes.required_skills),
             required_checks: toStringList(node.attributes.required_checks),
             max_iterations: optionalString(node.attributes.max_iterations),
@@ -643,6 +694,15 @@ function runGoalStateMutationLocked(action, options) {
         throw new errors_1.UsageError(`cannot ${action} archived goal ${loaded.node.qid}`);
     }
     const now = options.now ?? new Date();
+    if (action === "done" || action === "archive") {
+        const activeNode = optionalString(loaded.frontmatter.active_node);
+        if (activeNode) {
+            if (!loaded.frontmatter.last_active_node) {
+                loaded.frontmatter.last_active_node = activeNode;
+            }
+            delete loaded.frontmatter.active_node;
+        }
+    }
     loaded.frontmatter.goal_state = GOAL_STATE_BY_ACTION[action];
     loaded.frontmatter.status = ensureStatusAllowed(loaded.config, STATUS_BY_ACTION[action]);
     writeGoalFile(loaded, now);