mdkg 0.1.3 → 0.1.5

package/dist/init/templates/default/goal.md

@@ -0,0 +1,91 @@
+---
+id: {{id}}
+type: goal
+title: {{title}}
+status: {{status}}
+priority: {{priority}}
+goal_state: {{goal_state}}
+goal_condition: {{goal_condition}}
+scope_refs: []
+active_node: {{active_node}}
+required_skills: []
+required_checks: []
+max_iterations: {{max_iterations}}
+blocked_after_attempts: {{blocked_after_attempts}}
+epic: {{epic}}
+parent: {{parent}}
+prev: {{prev}}
+next: {{next}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+aliases: []
+skills: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Objective
+
+State the durable objective the agent should pursue.
+
+# End Condition
+
+Define the exact measurable condition that makes this goal achieved.
+
+# Non-Goals
+
+- Out-of-scope item
+
+# Recursive Algorithm
+
+1. Inspect the current goal state, relevant graph nodes, and required skills.
+2. Create missing mdkg nodes only when evidence shows they are needed.
+3. Select one concrete child node and work it to completion.
+4. Run required checks and record evidence.
+5. Re-evaluate the end condition and continue, pause, or close.
+
+# Required Skills
+
+- Skill slug
+
+# Required Checks
+
+- Command or verification gate
+
+# Acceptance Criteria
+
+- Criterion
+
+# Definition Of Done
+
+- Goal condition is achieved.
+- Required checks have evidence.
+- Completion evidence is recorded in the goal.
+
+# Stop Conditions
+
+- Goal is blocked beyond the configured attempt limit.
+- Required context or permissions are missing.
+- Budget or safety constraints prevent continued work.
+
+# Current State
+
+Record the current active node and any relevant state summary.
+
+# Iteration Log
+
+- No iterations recorded yet.
+
+# Skill Improvement Candidates
+
+- None yet.
+
+# Completion Evidence
+
+- Pending.

package/dist/pack/order.js

@@ -16,13 +16,14 @@ const FALLBACK_TYPES = [
     "dispute",
     "proposal",
     "archive",
+    "goal",
     "epic",
     "feat",
     "task",
     "bug",
     "checkpoint",
 ];
-const WORK_TYPES = ["epic", "feat", "task", "bug", "checkpoint"];
+const WORK_TYPES = ["goal", "epic", "feat", "task", "bug", "checkpoint"];
 function idNumber(id) {
     const match = id.match(/-(\d+)$/);
     if (!match) {

package/dist/pack/pack.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildPack = buildPack;
+const goal_scope_1 = require("../graph/goal_scope");
 const node_body_1 = require("../graph/node_body");
 const qid_1 = require("../util/qid");
 const order_1 = require("./order");
@@ -153,6 +154,22 @@ function buildPack(options) {
     const warnings = [];
     const includeLatestCheckpoint = options.includeLatestCheckpoint ?? true;
     const { qids, depths } = collectNodes(options.index, options.rootQid, options.depth, options.edges);
+    const rootNode = options.index.nodes[options.rootQid];
+    if (rootNode?.type === "goal") {
+        const scoped = (0, goal_scope_1.collectGoalScope)(options.index, rootNode);
+        for (const qid of scoped.qids) {
+            qids.add(qid);
+            if (!depths.has(qid)) {
+                depths.set(qid, 1);
+            }
+        }
+        for (const missing of scoped.missingRefs) {
+            mergeWarnings(warnings, `goal scope ref missing: ${missing}`);
+        }
+        for (const invalid of scoped.invalidRefs) {
+            mergeWarnings(warnings, `goal scope ref unsupported: ${invalid}`);
+        }
+    }
     const workspace = checkpointWorkspaceFromQid(options.rootQid);
     const latestCheckpointHint = options.index.meta.latest_checkpoint_qid?.[workspace];
     const latestCheckpointResolved = includeLatestCheckpoint

package/dist/util/argparse.js

@@ -83,6 +83,7 @@ const VALUE_FLAGS = new Set([
     "--source-path",
     "--source-repo",
     "--max-stale-seconds",
+    "--requires",
 ]);
 const BOOLEAN_FLAGS = new Set([
     "--tolerant",
@@ -116,6 +117,7 @@ const BOOLEAN_FLAGS = new Set([
     "--with-scripts",
     "--clear-blocked-by",
     "--all",
+    "--fresh-only",
 ]);
 const FLAG_ALIASES = {
     "--o": "--out",

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "mdkg",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
     "mdkg": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node scripts/add-shebang.js && node scripts/copy-init-assets.js",
-    "build:test": "tsc -p tsconfig.test.json",
+    "build": "node scripts/clean-build-output.js && tsc -p tsconfig.build.json && node scripts/add-shebang.js && node scripts/copy-init-assets.js",
+    "build:test": "node scripts/clean-build-output.js tests && tsc -p tsconfig.test.json",
     "test": "npm run build && npm run build:test && node --test dist/tests/**/*.test.js",
     "test:coverage": "npm run build && npm run build:test && node --test --experimental-test-coverage dist/tests/**/*.test.js",
     "smoke:consumer": "npm run build && node scripts/smoke-consumer.js",
@@ -18,15 +18,17 @@
     "smoke:capabilities": "npm run build && node scripts/smoke-capabilities.js",
     "smoke:archive-work": "npm run build && node scripts/smoke-archive-work.js",
     "smoke:bundle": "npm run build && node scripts/smoke-bundle.js",
-    "smoke:bundle-import": "npm run build && node scripts/smoke-bundle-import.js",
+    "smoke:bundle-import": "npm run smoke:subgraph",
     "smoke:visibility": "npm run build && node scripts/smoke-visibility.js",
     "smoke:sqlite": "npm run build && node scripts/smoke-sqlite.js",
     "smoke:parallel": "npm run build && node scripts/smoke-parallel.js",
+    "smoke:goal": "npm run build && node scripts/smoke-goal.js",
     "cli:snapshot": "npm run build && node scripts/cli_help_snapshot.js",
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:archive-work && npm run smoke:bundle && npm run smoke:bundle-import && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && node scripts/assert-publish-ready.js",
-    "postinstall": "node scripts/postinstall.js"
+    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:archive-work && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
+    "postinstall": "node scripts/postinstall.js",
+    "smoke:subgraph": "npm run build && node scripts/smoke-subgraph.js"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/dist/commands/bundle_import.js

@@ -1,255 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runBundleImportAddCommand = runBundleImportAddCommand;
-exports.runBundleImportListCommand = runBundleImportListCommand;
-exports.runBundleImportRemoveCommand = runBundleImportRemoveCommand;
-exports.runBundleImportEnableCommand = runBundleImportEnableCommand;
-exports.runBundleImportDisableCommand = runBundleImportDisableCommand;
-exports.runBundleImportVerifyCommand = runBundleImportVerifyCommand;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const config_1 = require("../core/config");
-const migrate_1 = require("../core/migrate");
-const workspace_path_1 = require("../core/workspace_path");
-const bundle_imports_1 = require("../graph/bundle_imports");
-const errors_1 = require("../util/errors");
-const atomic_1 = require("../util/atomic");
-const lock_1 = require("../util/lock");
-const ALIAS_RE = /^[a-z][a-z0-9_]*$/;
-function writeJson(value) {
-    console.log(JSON.stringify(value, null, 2));
-}
-function normalizeAlias(alias) {
-    if (alias === "all") {
-        throw new errors_1.UsageError("bundle import alias cannot be 'all'");
-    }
-    if (alias !== alias.toLowerCase() || !ALIAS_RE.test(alias)) {
-        throw new errors_1.UsageError("bundle import alias must be lowercase and use [a-z0-9_]");
-    }
-    return alias;
-}
-function normalizeVisibility(value) {
-    const normalized = (value ?? "private").toLowerCase();
-    if (normalized === "private" || normalized === "internal" || normalized === "public") {
-        return normalized;
-    }
-    throw new errors_1.UsageError("--visibility must be private, internal, or public");
-}
-function normalizeProfile(value) {
-    const normalized = (value ?? "private").toLowerCase();
-    if (normalized === "private" || normalized === "public") {
-        return normalized;
-    }
-    throw new errors_1.UsageError("--profile must be private or public");
-}
-function normalizeContained(value, label) {
-    try {
-        return (0, workspace_path_1.normalizeContainedWorkspacePath)(value, label);
-    }
-    catch (err) {
-        throw new errors_1.UsageError(err instanceof Error ? err.message : String(err));
-    }
-}
-function readRawConfig(root) {
-    const configPath = path_1.default.join(root, ".mdkg", "config.json");
-    if (!fs_1.default.existsSync(configPath)) {
-        throw new errors_1.NotFoundError(`config not found at ${configPath}`);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(fs_1.default.readFileSync(configPath, "utf8"));
-    }
-    catch (err) {
-        throw new errors_1.UsageError(`failed to read config: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    const migrated = (0, migrate_1.migrateConfig)(parsed).config;
-    (0, config_1.validateConfigSchema)(migrated);
-    if (typeof migrated !== "object" || migrated === null || Array.isArray(migrated)) {
-        throw new errors_1.UsageError("config must be a JSON object");
-    }
-    return { configPath, raw: migrated };
-}
-function writeRawConfig(configPath, raw) {
-    (0, atomic_1.atomicWriteFile)(configPath, `${JSON.stringify(raw, null, 2)}\n`);
-}
-function getImports(raw) {
-    const imports = raw.bundle_imports;
-    if (imports === undefined) {
-        raw.bundle_imports = {};
-        return raw.bundle_imports;
-    }
-    if (typeof imports !== "object" || imports === null || Array.isArray(imports)) {
-        throw new errors_1.UsageError("config.bundle_imports must be an object");
-    }
-    return imports;
-}
-function receiptForHealth(action, health) {
-    return {
-        action,
-        import: health,
-    };
-}
-function healthByAlias(root, alias) {
-    const config = (0, config_1.loadConfig)(root);
-    const health = (0, bundle_imports_1.buildBundleImportsIndex)(root, config).index.imports.find((item) => item.alias === alias);
-    if (!health) {
-        throw new errors_1.NotFoundError(`bundle import not found: ${alias}`);
-    }
-    return health;
-}
-function withBundleImportLock(root, fn) {
-    const config = (0, config_1.loadConfig)(root);
-    return (0, lock_1.withMutationLock)(root, config.index.lock_timeout_ms, fn);
-}
-function runBundleImportAddCommandLocked(options) {
-    const alias = normalizeAlias(options.alias);
-    const bundlePath = normalizeContained(options.bundlePath, "bundle import path");
-    const visibility = normalizeVisibility(options.visibility);
-    const expected_profile = normalizeProfile(options.profile);
-    if (visibility !== "private" && expected_profile !== "public") {
-        throw new errors_1.UsageError("--profile public is required when --visibility is public or internal");
-    }
-    const source_path = options.sourcePath
-        ? normalizeContained(options.sourcePath, "bundle import source path")
-        : undefined;
-    if (options.maxStaleSeconds !== undefined && (!Number.isInteger(options.maxStaleSeconds) || options.maxStaleSeconds <= 0)) {
-        throw new errors_1.UsageError("--max-stale-seconds must be a positive integer");
-    }
-    const { configPath, raw } = readRawConfig(options.root);
-    const imports = getImports(raw);
-    if (imports[alias]) {
-        throw new errors_1.UsageError(`bundle import already exists: ${alias}`);
-    }
-    const workspaces = raw.workspaces;
-    if (workspaces && workspaces[alias]) {
-        throw new errors_1.UsageError(`bundle import alias collides with workspace: ${alias}`);
-    }
-    imports[alias] = {
-        path: bundlePath,
-        enabled: true,
-        visibility,
-        expected_profile,
-        ...(source_path ? { source_path } : {}),
-        ...(options.sourceRepo ? { source_repo: options.sourceRepo } : {}),
-        ...(options.maxStaleSeconds !== undefined ? { max_stale_seconds: options.maxStaleSeconds } : {}),
-    };
-    raw.bundle_imports = imports;
-    const validated = (0, config_1.validateConfigSchema)(raw);
-    const health = (0, bundle_imports_1.buildBundleImportsIndex)(options.root, validated).index.imports.find((item) => item.alias === alias);
-    if (!health) {
-        throw new errors_1.NotFoundError(`bundle import not found after validation: ${alias}`);
-    }
-    if (health.error_count > 0) {
-        throw new errors_1.ValidationError(`bundle import ${alias} is invalid:\n${health.errors.join("\n")}`);
-    }
-    writeRawConfig(configPath, raw);
-    const receipt = receiptForHealth("added", health);
-    if (options.json) {
-        writeJson(receipt);
-        return;
-    }
-    console.log(`bundle import added: ${alias} (${bundlePath})`);
-    if (health.warning_count > 0) {
-        console.log(`warnings: ${health.warning_count}`);
-    }
-}
-function runBundleImportAddCommand(options) {
-    return withBundleImportLock(options.root, () => runBundleImportAddCommandLocked(options));
-}
-function runBundleImportListCommand(options) {
-    const config = (0, config_1.loadConfig)(options.root);
-    const imports = (0, bundle_imports_1.buildBundleImportsIndex)(options.root, config).index.imports;
-    if (options.json) {
-        writeJson({ action: "list", count: imports.length, imports });
-        return;
-    }
-    if (imports.length === 0) {
-        console.log("no bundle imports configured");
-        return;
-    }
-    for (const item of imports) {
-        const status = item.enabled ? item.error_count > 0 ? "invalid" : item.stale ? "stale" : "ok" : "disabled";
-        console.log(`${item.alias} | ${status} | ${item.visibility} | ${item.path}`);
-    }
-}
-function runBundleImportRemoveCommandLocked(options) {
-    const alias = normalizeAlias(options.alias);
-    const { configPath, raw } = readRawConfig(options.root);
-    const imports = getImports(raw);
-    const existing = imports[alias];
-    if (!existing) {
-        throw new errors_1.NotFoundError(`bundle import not found: ${alias}`);
-    }
-    delete imports[alias];
-    raw.bundle_imports = imports;
-    (0, config_1.validateConfigSchema)(raw);
-    writeRawConfig(configPath, raw);
-    const receipt = { action: "removed", import: { alias } };
-    if (options.json) {
-        writeJson(receipt);
-        return;
-    }
-    console.log(`bundle import removed: ${alias}`);
-}
-function runBundleImportRemoveCommand(options) {
-    return withBundleImportLock(options.root, () => runBundleImportRemoveCommandLocked(options));
-}
-function setBundleImportEnabledLocked(options, enabled) {
-    const alias = normalizeAlias(options.alias);
-    const { configPath, raw } = readRawConfig(options.root);
-    const imports = getImports(raw);
-    const existing = imports[alias];
-    if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
-        throw new errors_1.NotFoundError(`bundle import not found: ${alias}`);
-    }
-    imports[alias] = { ...existing, enabled };
-    raw.bundle_imports = imports;
-    (0, config_1.validateConfigSchema)(raw);
-    writeRawConfig(configPath, raw);
-    const health = healthByAlias(options.root, alias);
-    const receipt = receiptForHealth(enabled ? "enabled" : "disabled", health);
-    if (options.json) {
-        writeJson(receipt);
-        return;
-    }
-    console.log(`bundle import ${enabled ? "enabled" : "disabled"}: ${alias}`);
-}
-function runBundleImportEnableCommand(options) {
-    withBundleImportLock(options.root, () => setBundleImportEnabledLocked(options, true));
-}
-function runBundleImportDisableCommand(options) {
-    withBundleImportLock(options.root, () => setBundleImportEnabledLocked(options, false));
-}
-function runBundleImportVerifyCommand(options) {
-    const config = (0, config_1.loadConfig)(options.root);
-    const all = options.all || !options.alias;
-    const imports = (0, bundle_imports_1.buildBundleImportsIndex)(options.root, config).index.imports.filter((item) => all ? true : item.alias === options.alias);
-    if (!all && imports.length === 0) {
-        throw new errors_1.NotFoundError(`bundle import not found: ${options.alias}`);
-    }
-    const ok = imports.every((item) => item.error_count === 0 && !item.stale);
-    const receipt = { action: "verified", ok, count: imports.length, imports };
-    if (options.json) {
-        writeJson(receipt);
-    }
-    else if (ok) {
-        console.log(`bundle imports verified: ${imports.length}`);
-    }
-    else {
-        console.log(`bundle import verify failed: ${imports.length}`);
-        for (const item of imports) {
-            for (const warning of item.warnings) {
-                console.log(`warning: ${item.alias}: ${warning}`);
-            }
-            for (const error of item.errors) {
-                console.log(`error: ${item.alias}: ${error}`);
-            }
-        }
-    }
-    if (!ok) {
-        throw new errors_1.ValidationError("bundle import verify failed");
-    }
-}