mdkg 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -6,6 +6,24 @@ This project follows a pragmatic changelog style inspired by Keep a Changelog. V
 
 mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL contracts may change quickly while the project converges on a stable v1 surface.
 
+## 0.1.5 - Unreleased
+
+### Added
+
+- Added first-class `goal` nodes for recursive long-running objectives with `goal_state`, `goal_condition`, `active_node`, required skills, required checks, iteration limits, stop conditions, and completion evidence.
+- Added `mdkg new goal "<title>"` and the `mdkg goal show/select/current/clear/next/claim/evaluate/pause/resume/done` command family.
+- Added a bundled `goal.md` template so init, upgrade, and template fallback can support goal nodes.
+- Added `scope_refs` for explicit goal ownership roots and recursive goal traversal through epics and features.
+- Added the `pursue-mdkg-goal` skill for skill-guided recursive pursuit with evidence and controlled skill-improvement proposals.
+- Added goal parser, creation, selected-goal, recursive next-selection, claim, pack, and report-only evaluation tests.
+
+### Changed
+
+- Normal `mdkg next` continues to select concrete task, bug, test, and feature work; goal-scoped selection lives under `mdkg goal next`.
+- `mdkg goal next` is read-only and may omit the goal id when a selected local goal exists; `mdkg goal claim` is the explicit mutating path for `active_node`.
+- Goal required checks are report-only guidance in this release. Agents run commands themselves and record evidence back into mdkg.
+- Skill self-improvement during goal execution is recorded as candidates or proposal work unless the active node is explicit skill-maintenance.
+
 ## 0.1.4 - Unreleased
 
 ### Added

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.1.4`
+Current package version in source: `0.1.5`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -77,6 +77,17 @@ Create a task:
 mdkg new task "bootstrap cli" --status todo --priority 1 --tags cli,build
 ```
 
+Create a recursive goal for long-running agent work:
+
+```bash
+mdkg new goal "reach prepublish readiness"
+mdkg goal show goal-1 --json
+mdkg goal next goal-1
+mdkg goal evaluate goal-1 --json
+```
+
+Goal nodes capture a measurable end condition, recursive loop state, required skills, required checks, and completion evidence. They guide agent harnesses through repeated graph-backed progress, while tasks, bugs, tests, and features remain the concrete executable work units. In this release `mdkg goal evaluate` is report-only: it lists required checks and evidence state, but does not execute scripts.
+
 Create an agent workflow document with a semantic portable id:
 
 ```bash
@@ -226,6 +237,7 @@ These are the commands new users and agents should learn first:
 - `mdkg capability`
 - `mdkg archive`
 - `mdkg work`
+- `mdkg goal`
 - `mdkg task`
 - `mdkg validate`
 
@@ -305,6 +317,16 @@ Fresh `mdkg init` workspaces default to `index.backend: sqlite`, which writes `.
 
 Mutating commands use a workspace mutation lock plus atomic writes. SQLite mode additionally reserves numeric ids in a SQLite transaction before writing Markdown so parallel `mdkg new` and checkpoint calls avoid naming conflicts. Skipped ids after failed writes are acceptable because Markdown remains canonical.
 
+## Goal nodes
+
+Goal nodes are durable recursive objective contracts. Use `mdkg new goal "<objective>"` when a human or agent needs to keep working across multiple concrete nodes until a measurable end condition is achieved.
+
+`goal` is work-like but distinct from `task`: it can have status, priority, graph links, skills, explicit `scope_refs`, and structured goal fields, but normal `mdkg next` does not select goals. Use `mdkg goal select <goal-id>` once, then `mdkg goal next` to choose the next local feature, task, bug, or test inside that goal. `mdkg goal next <goal-id>` remains available for explicit selection. Epics organize goal scope recursively but are not returned as executable work.
+
+Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after choosing the next scoped item. `goal next` is read-only. Use `mdkg goal pause|resume|done` to update goal state after review.
+
+Required checks are stored as report-only guidance. Agents should run the checks themselves, record evidence in the goal or active work item, then use `mdkg goal evaluate` to summarize the current evidence state. During normal goal execution, skill improvements should be recorded as improvement candidates or proposal nodes; edit `SKILL.md` files only when the active node is explicit skill-maintenance work.
+
 ## Agent workflow files
 
 mdkg recognizes a small set of canonical agent workflow documents:
@@ -342,6 +364,7 @@ This release includes:
 - JSON capability cache for skills, `SPEC.md`, `WORK.md`, core docs, and design docs
 - SQLite index backend for fresh workspaces using built-in `node:sqlite`
 - mutation locking and atomic writes for parallel mdkg calls
+- first-class `goal` nodes and `mdkg goal show/next/evaluate/pause/resume/done`
 - optional `skills: [...]` on work items
 - pack-time skill inclusion
 - latest-checkpoint resolver + index hint

package/dist/cli.js

@@ -27,6 +27,7 @@ const init_1 = require("./commands/init");
 const new_1 = require("./commands/new");
 const guide_1 = require("./commands/guide");
 const upgrade_1 = require("./commands/upgrade");
+const goal_1 = require("./commands/goal");
 const event_1 = require("./commands/event");
 const skill_1 = require("./commands/skill");
 const task_1 = require("./commands/task");
@@ -65,6 +66,7 @@ function printUsage(log) {
     log("  bundle      Create, list, show, and verify full graph snapshot bundles");
     log("  subgraph    Register and verify read-only child graph snapshots");
     log("  work        Create and update work contracts, orders, receipts, and artifacts");
+    log("  goal        Inspect and advance recursive goal nodes");
     log("  task        Start, update, and complete task-like nodes");
     log("  next        Suggest the next work item");
     log("  validate    Validate frontmatter + graph");
@@ -126,7 +128,7 @@ function printNewHelp(log) {
     log("Usage:");
     log('  mdkg new <type> "<title>" [options] [--json]');
     log("\nTypes:");
-    log("  rule prd edd dec prop epic feat task bug checkpoint test");
+    log("  rule prd edd dec prop goal epic feat task bug checkpoint test");
     log("\nAgent workflow file types:");
     log("  spec work work_order receipt feedback dispute proposal");
     log("  Use --id <portable-id> with these types for semantic ids like agent.image-worker.");
@@ -545,6 +547,86 @@ function printTaskHelp(log, subcommand) {
             printGlobalOptions(log);
     }
 }
+function printGoalHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "show":
+            log("Usage:");
+            log("  mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]");
+            log("\nWhen to use:");
+            log("  Inspect a goal condition, current goal state, active node, required skills, and required checks.");
+            printGlobalOptions(log);
+            return;
+        case "next":
+            log("Usage:");
+            log("  mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]");
+            log("\nWhen to use:");
+            log("  Select the next local feature, task, bug, or test inside a recursive goal without mutating active_node.");
+            log("  If no goal id is supplied, mdkg uses the selected goal or the unique active goal.");
+            printGlobalOptions(log);
+            return;
+        case "select":
+            log("Usage:");
+            log("  mdkg goal select <goal-id-or-qid> [--ws <alias>] [--json]");
+            log("\nWhen to use:");
+            log("  Store a local selected goal so `mdkg goal next` can omit the goal id.");
+            printGlobalOptions(log);
+            return;
+        case "current":
+            log("Usage:");
+            log("  mdkg goal current [--ws <alias>] [--json]");
+            log("\nWhen to use:");
+            log("  Inspect the selected goal or unique active goal fallback.");
+            printGlobalOptions(log);
+            return;
+        case "clear":
+            log("Usage:");
+            log("  mdkg goal clear [--json]");
+            log("\nWhen to use:");
+            log("  Remove local selected-goal state.");
+            printGlobalOptions(log);
+            return;
+        case "claim":
+            log("Usage:");
+            log("  mdkg goal claim <work-id-or-qid> [--ws <alias>] [--json]");
+            log("  mdkg goal claim <goal-id-or-qid> <work-id-or-qid> [--ws <alias>] [--json]");
+            log("\nWhen to use:");
+            log("  Write active_node explicitly after accepting a goal-scoped next item.");
+            printGlobalOptions(log);
+            return;
+        case "evaluate":
+            log("Usage:");
+            log("  mdkg goal evaluate <goal-id-or-qid> [--ws <alias>] [--json]");
+            log("\nNotes:");
+            log("  Evaluation is report-only; mdkg lists required checks but does not execute scripts.");
+            printGlobalOptions(log);
+            return;
+        case "pause":
+        case "resume":
+        case "done":
+            log("Usage:");
+            log(`  mdkg goal ${subcommand} <goal-id-or-qid> [--ws <alias>] [--json]`);
+            log("\nWhen to use:");
+            log("  Update durable goal state after agent or human review.");
+            printGlobalOptions(log);
+            return;
+        default:
+            log("Usage:");
+            log("  mdkg goal show <goal-id-or-qid> [--json]");
+            log("  mdkg goal select <goal-id-or-qid> [--json]");
+            log("  mdkg goal current [--json]");
+            log("  mdkg goal next [goal-id-or-qid] [--json]");
+            log("  mdkg goal claim [goal-id-or-qid] <work-id-or-qid> [--json]");
+            log("  mdkg goal evaluate <goal-id-or-qid> [--json]");
+            log("  mdkg goal clear [--json]");
+            log("  mdkg goal pause|resume|done <goal-id-or-qid> [--json]");
+            log("\nNotes:");
+            log("  - goals orchestrate recursive progress; features, tasks, bugs, and tests are iterable work units");
+            log("  - `mdkg goal next` is read-only; use `mdkg goal claim` to update active_node");
+            log("  - goal evaluation is report-only and never executes required_checks");
+            log("  - subgraph goal qids are read-only; update the source workspace instead");
+            printGlobalOptions(log);
+    }
+}
 function printEventHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "enable":
@@ -665,6 +747,9 @@ function printCommandHelp(log, command, subcommand) {
         case "task":
             printTaskHelp(log, subcommand);
             return;
+        case "goal":
+            printGoalHelp(log, subcommand);
+            return;
         case "event":
             printEventHelp(log, subcommand);
             return;
@@ -1406,6 +1491,92 @@ function runSkillSubcommand(parsed, root) {
             throw new errors_1.UsageError("skill requires new/list/show/search/validate/sync");
     }
 }
+function runGoalSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    switch (subcommand) {
+        case "show": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("goal show requires <goal-id-or-qid>");
+            }
+            (0, goal_1.runGoalShowCommand)({ root, id, ws, json });
+            return 0;
+        }
+        case "select": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("goal select requires <goal-id-or-qid>");
+            }
+            (0, goal_1.runGoalSelectCommand)({ root, id, ws, json });
+            return 0;
+        }
+        case "current":
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("goal current does not accept positional arguments");
+            }
+            (0, goal_1.runGoalCurrentCommand)({ root, ws, json });
+            return 0;
+        case "clear":
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("goal clear does not accept positional arguments");
+            }
+            (0, goal_1.runGoalClearCommand)({ root, json });
+            return 0;
+        case "next": {
+            const id = parsed.positionals[2];
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("goal next accepts at most one goal id");
+            }
+            (0, goal_1.runGoalNextCommand)({ root, id, ws, json });
+            return 0;
+        }
+        case "claim": {
+            const first = parsed.positionals[2];
+            const second = parsed.positionals[3];
+            if (!first || parsed.positionals.length > 4) {
+                throw new errors_1.UsageError("goal claim requires <work-id-or-qid> or <goal-id-or-qid> <work-id-or-qid>");
+            }
+            (0, goal_1.runGoalClaimCommand)({ root, id: second ? first : undefined, workId: second ?? first, ws, json });
+            return 0;
+        }
+        case "evaluate": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("goal evaluate requires <goal-id-or-qid>");
+            }
+            (0, goal_1.runGoalEvaluateCommand)({ root, id, ws, json });
+            return 0;
+        }
+        case "pause": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("goal pause requires <goal-id-or-qid>");
+            }
+            (0, goal_1.runGoalPauseCommand)({ root, id, ws, json });
+            return 0;
+        }
+        case "resume": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("goal resume requires <goal-id-or-qid>");
+            }
+            (0, goal_1.runGoalResumeCommand)({ root, id, ws, json });
+            return 0;
+        }
+        case "done": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("goal done requires <goal-id-or-qid>");
+            }
+            (0, goal_1.runGoalDoneCommand)({ root, id, ws, json });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("goal requires show/select/current/clear/next/claim/evaluate/pause/resume/done");
+    }
+}
 function runTaskSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     switch (subcommand) {
@@ -1663,6 +1834,8 @@ function runCommand(parsed, root, runtime) {
             return runSubgraphSubcommand(parsed, root);
         case "work":
             return runWorkSubcommand(parsed, root);
+        case "goal":
+            return runGoalSubcommand(parsed, root);
         case "task":
             return runTaskSubcommand(parsed, root);
         case "event":