mdkg 0.1.4 → 0.1.5

package/dist/init/skills/default/pursue-mdkg-goal/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: pursue-mdkg-goal
+description: Pursue a selected mdkg goal by repeatedly selecting one scoped work item, executing it with evidence, and evaluating the goal until done, blocked, paused, or budget-limited.
+tags: [stage:execute, writer:orchestrator, mdkg, goal, recursive]
+version: 0.1.0
+authors: [mdkg]
+links: [AGENT_START.md, CLI_COMMAND_MATRIX.md, .mdkg/design/prd-3-mdkg-goal-node-ux-and-agent-harness-contract.md, .mdkg/design/edd-10-mdkg-goal-node-architecture-and-recursive-agent-loop.md]
+---
+
+# Goal
+
+Move one durable mdkg goal forward without losing scope, evidence, or user intent.
+
+## When To Use
+
+- A user has selected or named an mdkg goal.
+- A long-running objective needs one concrete next work item at a time.
+- Goal progress should improve the graph while keeping skill changes controlled.
+
+## Inputs
+
+- Optional goal id or qid.
+- Current selected goal state from `mdkg goal current`.
+- The goal node, scoped work nodes, required skills, and required checks.
+- User constraints, budget, and stop conditions.
+
+## Steps
+
+1. Resolve the goal:
+   - If a goal id is provided, run `mdkg goal select <goal-id>`.
+   - Otherwise run `mdkg goal current`.
+   - If the result is missing or ambiguous, ask the user to select a goal.
+2. Inspect the goal with `mdkg goal show <goal-id>` and build context with `mdkg pack <goal-id>`.
+3. Run `mdkg goal next` to surface exactly one scoped feature, task, bug, or test.
+4. If `goal next` returns no node, evaluate the goal with `mdkg goal evaluate <goal-id>` and report whether completion, blocker, or new-node creation is needed.
+5. Before coding, run `mdkg goal claim <work-id>` to set `active_node` when the surfaced node is accepted.
+6. Work only the claimed node to completion. Do not expand into unrelated urgent work.
+7. Run the required technical checks yourself. mdkg goal required checks are report-only; mdkg does not execute them.
+8. Record evidence on the active work node, then evaluate the goal with `mdkg goal evaluate <goal-id>`.
+9. Repeat steps 3-8 until the goal condition is achieved, blocked, paused, budget-limited, or the user stops the run.
+
+## Skill Improvement Candidates
+
+- During normal goal execution, record skill improvement ideas in the goal body or a proposal node.
+- Edit `SKILL.md` files only when the active node is explicitly skill-maintenance work.
+- After intentional skill edits, run `mdkg skill sync`, `mdkg skill validate`, `mdkg index`, and `mdkg validate`.
+
+## Outputs
+
+- One active scoped work item at a time.
+- Evidence recorded on the active node and summarized on the goal when useful.
+- Required checks reported with pass/fail status.
+- A clear stop reason: continue, achieved, blocked, paused, or budget-limited.
+
+## Safety
+
+- `mdkg goal next` is read-only; do not treat it as a claim.
+- `mdkg goal claim` is the durable `active_node` mutation.
+- Do not mutate subgraph/imported qids; update the owning source workspace.
+- Do not create missing nodes without evidence that the current goal scope needs them.
+- Do not edit skills opportunistically while pursuing product or code work.
+
+## Failure Handling
+
+- If selection is ambiguous, ask for a goal instead of guessing.
+- If scoped work is missing, create a proposal or task only after explaining the gap.
+- If checks fail, keep the active node open and record the failure evidence.
+- If repeated attempts hit the same blocker, mark the goal blocked or ask for direction.

package/dist/init/skills/default/select-work-and-ground-context/SKILL.md

@@ -26,13 +26,15 @@ Choose the correct work item and load the smallest deterministic context needed
 ## Steps
 
 1. If a task id is already known, inspect it with `mdkg show <id>`.
-2. If the task is not known, read `AGENT_START.md` and use `mdkg next` or `mdkg search "<query>"` to narrow candidates.
-3. Use `mdkg show <id> --meta` when you only need the card and link metadata.
-4. Confirm the selected node has the right constraints, related design docs, and current status.
-5. If the task is ambiguous, resolve that before building a pack.
-6. If the chosen task is ready to be claimed, hand off to `mdkg task start <id>` in the writer stage for the structured status change.
-7. If resuming closeout work for a feat or epic, inspect the latest relevant checkpoint before deciding what remains open.
-8. Treat this stage as read-only: inspect and decide, but do not mutate mdkg state or commit.
+2. If a goal may be active, run `mdkg goal current`.
+3. If a selected or unique active goal exists, use `mdkg goal next` to surface one scoped feature, task, bug, or test before falling back to global work discovery.
+4. If the task is not known and no goal is active, read `AGENT_START.md` and use `mdkg next` or `mdkg search "<query>"` to narrow candidates.
+5. Use `mdkg show <id> --meta` when you only need the card and link metadata.
+6. Confirm the selected node has the right constraints, related design docs, and current status.
+7. If the task is ambiguous, resolve that before building a pack.
+8. If the chosen task is ready to be claimed in a goal, hand off to `mdkg goal claim <id>` in the writer stage; otherwise hand off to `mdkg task start <id>` for task-like status changes.
+9. If resuming closeout work for a feat or epic, inspect the latest relevant checkpoint before deciding what remains open.
+10. Treat this stage as read-only: inspect and decide, but do not mutate mdkg state or commit.
 
 ## Outputs
 

package/dist/init/skills/default/verify-close-and-checkpoint/SKILL.md

@@ -30,15 +30,16 @@ Finish work with evidence, validation, and minimal memory drift.
 2. Run `mdkg validate` before closing the task.
 3. For mdkg scaffold or release work, include `mdkg upgrade` dry-run/apply evidence and any package smoke that exercises upgrade behavior.
 4. Use `mdkg task update <id> ...` for additive evidence and structured metadata changes; keep narrative/body edits in markdown.
-5. Use `mdkg task done <id> --checkpoint "<title>"` when the task should close with milestone compression.
-6. Batch durable mdkg writes at one boundary: task status, artifact refs, optional checkpoint, and commit.
-7. Mark tasks done only after evidence exists.
-8. Create a checkpoint only for milestone-level transitions, not every small step.
-9. For feat or epic closeout, prefer a checkpoint body as the durable narrative summary of what changed and what is next.
-10. Use feat closeout scope as direct children with `parent: <feat-id>` and epic closeout scope as descendant work with `epic: <epic-id>`.
-11. Parent status edits remain manual; do not invent a hidden parent-closeout workflow.
-12. If the latest checkpoint is relevant, use it as durable recall; treat raw events as provenance/debugging, not primary execution context.
-13. If `events.jsonl` is missing, recreate it with `mdkg event enable` before expecting automatic JSONL provenance.
+5. When pursuing a goal, record evidence on the active node and summarize goal evidence before running `mdkg goal evaluate <goal-id>`.
+6. Use `mdkg task done <id> --checkpoint "<title>"` when the task should close with milestone compression.
+7. Batch durable mdkg writes at one boundary: task status, artifact refs, optional checkpoint, goal evidence, and commit.
+8. Mark tasks done only after evidence exists.
+9. Create a checkpoint only for milestone-level transitions, not every small step.
+10. For feat or epic closeout, prefer a checkpoint body as the durable narrative summary of what changed and what is next.
+11. Use feat closeout scope as direct children with `parent: <feat-id>` and epic closeout scope as descendant work with `epic: <epic-id>`.
+12. Parent status edits remain manual; do not invent a hidden parent-closeout workflow.
+13. If the latest checkpoint is relevant, use it as durable recall; treat raw events as provenance/debugging, not primary execution context.
+14. If `events.jsonl` is missing, recreate it with `mdkg event enable` before expecting automatic JSONL provenance.
 
 ## Pre-Publish Release Gate
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -22,10 +22,11 @@
     "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:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && 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: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"
   },