mdkg 0.1.4 → 0.1.6

package/dist/graph/goal_scope.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GOAL_SCOPE_ALLOWED_TYPES = exports.GOAL_SCOPE_ACTIONABLE_TYPES = exports.GOAL_SCOPE_CONTAINER_TYPES = void 0;
+exports.goalScopeRefs = goalScopeRefs;
+exports.collectGoalScope = collectGoalScope;
+const qid_1 = require("../util/qid");
+exports.GOAL_SCOPE_CONTAINER_TYPES = new Set(["epic", "feat"]);
+exports.GOAL_SCOPE_ACTIONABLE_TYPES = new Set(["feat", "task", "bug", "test"]);
+exports.GOAL_SCOPE_ALLOWED_TYPES = new Set([
+    ...exports.GOAL_SCOPE_CONTAINER_TYPES,
+    ...exports.GOAL_SCOPE_ACTIONABLE_TYPES,
+]);
+function toStringList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function goalScopeRefs(goal) {
+    return toStringList(goal.attributes.scope_refs);
+}
+function resolveGoalScopeRef(index, value, ws) {
+    const resolved = (0, qid_1.resolveQid)(index, value, ws);
+    return resolved.status === "ok" ? resolved.qid : undefined;
+}
+function addIfPresent(values, value) {
+    if (value) {
+        values.add(value);
+    }
+}
+function collectDirectCompatibilityRefs(index, goal) {
+    const qids = new Set();
+    const edges = goal.edges;
+    addIfPresent(qids, edges.next);
+    addIfPresent(qids, edges.prev);
+    addIfPresent(qids, edges.parent);
+    addIfPresent(qids, edges.epic);
+    for (const value of edges.relates) {
+        qids.add(value);
+    }
+    for (const value of edges.blocks) {
+        qids.add(value);
+    }
+    for (const value of edges.blocked_by) {
+        qids.add(value);
+    }
+    for (const node of Object.values(index.nodes)) {
+        if (node.edges.parent === goal.qid ||
+            node.edges.epic === goal.qid ||
+            node.edges.prev === goal.qid ||
+            node.edges.next === goal.qid ||
+            node.edges.relates.includes(goal.qid) ||
+            node.edges.blocked_by.includes(goal.qid) ||
+            node.edges.blocks.includes(goal.qid)) {
+            qids.add(node.qid);
+        }
+    }
+    return qids;
+}
+function descendantQids(index, qid) {
+    const byEpic = index.reverse_edges.epic?.[qid] ?? [];
+    const byParent = index.reverse_edges.parent?.[qid] ?? [];
+    return [...new Set([...byEpic, ...byParent])].sort();
+}
+function collectGoalScope(index, goal, options = {}) {
+    const includeCompatibilityRefs = options.includeCompatibilityRefs ?? true;
+    const rootQids = [];
+    const qids = new Set();
+    const actionableQids = new Set();
+    const missingRefs = [];
+    const invalidRefs = [];
+    const queued = new Set();
+    const queue = [];
+    function enqueue(qid) {
+        if (queued.has(qid)) {
+            return;
+        }
+        queued.add(qid);
+        queue.push(qid);
+    }
+    for (const ref of goalScopeRefs(goal)) {
+        const resolved = resolveGoalScopeRef(index, ref, goal.ws);
+        if (!resolved) {
+            missingRefs.push(ref);
+            continue;
+        }
+        rootQids.push(resolved);
+        enqueue(resolved);
+    }
+    if (includeCompatibilityRefs) {
+        for (const qid of collectDirectCompatibilityRefs(index, goal)) {
+            rootQids.push(qid);
+            enqueue(qid);
+        }
+    }
+    while (queue.length > 0) {
+        const qid = queue.shift();
+        if (!qid) {
+            break;
+        }
+        const node = index.nodes[qid];
+        if (!node) {
+            continue;
+        }
+        if (!exports.GOAL_SCOPE_ALLOWED_TYPES.has(node.type)) {
+            invalidRefs.push(qid);
+            continue;
+        }
+        qids.add(qid);
+        if (exports.GOAL_SCOPE_ACTIONABLE_TYPES.has(node.type)) {
+            actionableQids.add(qid);
+        }
+        if (exports.GOAL_SCOPE_CONTAINER_TYPES.has(node.type)) {
+            for (const childQid of descendantQids(index, qid)) {
+                enqueue(childQid);
+            }
+        }
+    }
+    rootQids.sort();
+    return {
+        rootQids: [...new Set(rootQids)],
+        qids,
+        actionableQids,
+        missingRefs,
+        invalidRefs: [...new Set(invalidRefs)].sort(),
+    };
+}

package/dist/graph/node.js

@@ -10,7 +10,7 @@ const id_1 = require("../util/id");
 const refs_1 = require("../util/refs");
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const DEC_ID_RE = /^dec-[0-9]+$/;
-exports.WORK_TYPES = new Set(["epic", "feat", "task", "bug", "checkpoint", "test"]);
+exports.WORK_TYPES = new Set(["goal", "epic", "feat", "task", "bug", "checkpoint", "test"]);
 exports.DEC_TYPES = new Set(["dec"]);
 exports.ALLOWED_TYPES = new Set([
     "rule",
@@ -18,6 +18,7 @@ exports.ALLOWED_TYPES = new Set([
     "edd",
     "dec",
     "prop",
+    "goal",
     "epic",
     "feat",
     "task",
@@ -28,7 +29,18 @@ exports.ALLOWED_TYPES = new Set([
     ...agent_file_types_1.AGENT_FILE_TYPES,
 ]);
 const DEC_STATUS = new Set(["proposed", "accepted", "rejected", "superseded"]);
+const GOAL_STATE = new Set(["active", "paused", "achieved", "blocked", "budget_limited"]);
 const SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const GOAL_ATTRIBUTE_KEYS = [
+    "goal_state",
+    "goal_condition",
+    "scope_refs",
+    "active_node",
+    "required_skills",
+    "required_checks",
+    "max_iterations",
+    "blocked_after_attempts",
+];
 function formatError(filePath, message) {
     return new Error(`${filePath}: ${message}`);
 }
@@ -142,6 +154,71 @@ function normalizeSkillList(values, filePath) {
         return normalized;
     });
 }
+function parsePositiveIntegerString(value, key, filePath) {
+    if (!/^[1-9][0-9]*$/.test(value)) {
+        throw formatError(filePath, `${key} must be a positive integer`);
+    }
+    return value;
+}
+function validateGoalFrontmatter(type, frontmatter, filePath) {
+    if (type !== "goal") {
+        return;
+    }
+    const goalState = requireLowercase(expectString(frontmatter, "goal_state", filePath), "goal_state", filePath);
+    if (!GOAL_STATE.has(goalState)) {
+        throw formatError(filePath, `goal_state must be one of ${Array.from(GOAL_STATE).join(", ")}`);
+    }
+    const goalCondition = expectString(frontmatter, "goal_condition", filePath);
+    if (goalCondition.length > 4000) {
+        throw formatError(filePath, "goal_condition must be 4000 characters or fewer");
+    }
+    const activeNode = optionalString(frontmatter, "active_node", filePath);
+    if (activeNode !== undefined) {
+        const normalized = requireLowercase(activeNode, "active_node", filePath);
+        if (!(0, id_1.isPortableIdRef)(normalized)) {
+            throw formatError(filePath, "active_node must be a local id or qid");
+        }
+    }
+    const scopeRefs = optionalList(frontmatter, "scope_refs", filePath);
+    for (const [index, value] of scopeRefs.entries()) {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw formatError(filePath, `scope_refs[${index}] must not be empty`);
+        }
+        const normalized = requireLowercase(value, `scope_refs[${index}]`, filePath);
+        if (!(0, id_1.isPortableIdRef)(normalized)) {
+            throw formatError(filePath, `scope_refs[${index}] must be a local id or qid`);
+        }
+    }
+    const requiredSkills = optionalList(frontmatter, "required_skills", filePath);
+    normalizeSkillList(requiredSkills, filePath);
+    const requiredChecks = optionalList(frontmatter, "required_checks", filePath);
+    for (const [index, value] of requiredChecks.entries()) {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw formatError(filePath, `required_checks[${index}] must not be empty`);
+        }
+    }
+    const maxIterations = optionalString(frontmatter, "max_iterations", filePath);
+    if (maxIterations !== undefined) {
+        parsePositiveIntegerString(maxIterations, "max_iterations", filePath);
+    }
+    const blockedAfterAttempts = optionalString(frontmatter, "blocked_after_attempts", filePath);
+    if (blockedAfterAttempts !== undefined) {
+        parsePositiveIntegerString(blockedAfterAttempts, "blocked_after_attempts", filePath);
+    }
+}
+function extractGoalAttributes(type, frontmatter) {
+    if (type !== "goal") {
+        return {};
+    }
+    const attributes = {};
+    for (const key of GOAL_ATTRIBUTE_KEYS) {
+        const value = frontmatter[key];
+        if (value !== undefined) {
+            attributes[key] = value;
+        }
+    }
+    return attributes;
+}
 function requireTemplateSchema(type, templateSchemas, filePath) {
     const schema = templateSchemas[type];
     if (!schema) {
@@ -185,6 +262,7 @@ function parseNode(content, filePath, options) {
     validateTemplateKeys(frontmatter, schema, filePath);
     (0, agent_file_types_1.validateAgentFrontmatter)(type, frontmatter, filePath);
     (0, archive_file_1.validateArchiveFrontmatter)(type, frontmatter, filePath);
+    validateGoalFrontmatter(type, frontmatter, filePath);
     const idValue = requireLowercase(expectString(frontmatter, "id", filePath), "id", filePath);
     const id = isPortableType
         ? requirePortableIdFormat(idValue, "id", filePath)
@@ -250,6 +328,7 @@ function parseNode(content, filePath, options) {
     }
     const edges = (0, edges_1.extractEdges)(frontmatter, filePath, { allowPortableRefs: isPortableType });
     const attributes = {
+        ...extractGoalAttributes(type, frontmatter),
         ...(0, agent_file_types_1.extractAgentAttributes)(type, frontmatter),
         ...(0, archive_file_1.extractArchiveAttributes)(type, frontmatter),
     };

package/dist/graph/validate_graph.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectGraphErrors = collectGraphErrors;
 exports.validateGraph = validateGraph;
 const refs_1 = require("../util/refs");
+const goal_scope_1 = require("./goal_scope");
 function pushError(errors, message) {
     if (errors) {
         errors.push(message);
@@ -433,6 +434,45 @@ function validateArchiveUriRefs(index, allowMissing, errors) {
         }
     }
 }
+function validateGoalRefs(index, allowMissing, errors) {
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        if (node.type !== "goal") {
+            continue;
+        }
+        const scope = (0, goal_scope_1.collectGoalScope)(index, node, { includeCompatibilityRefs: false });
+        for (const ref of scope.missingRefs) {
+            if (allowMissing) {
+                continue;
+            }
+            pushError(errors, `${qid}: scope_refs references missing node ${ref}`);
+        }
+        for (const ref of scope.invalidRefs) {
+            const target = index.nodes[ref];
+            const typeLabel = target ? target.type : "missing";
+            pushError(errors, `${qid}: scope_refs references ${ref} with type ${typeLabel}, expected ${Array.from(goal_scope_1.GOAL_SCOPE_ALLOWED_TYPES).join(", ")}`);
+        }
+        const activeNode = node.attributes.active_node;
+        if (typeof activeNode !== "string") {
+            continue;
+        }
+        const activeQid = activeNode.includes(":") ? activeNode : `${node.ws}:${activeNode}`;
+        const target = index.nodes[activeQid];
+        if (!target) {
+            if (allowMissing) {
+                continue;
+            }
+            pushError(errors, `${qid}: active_node references missing node ${activeNode}`);
+            continue;
+        }
+        if (!goal_scope_1.GOAL_SCOPE_ACTIONABLE_TYPES.has(target.type)) {
+            pushError(errors, `${qid}: active_node references ${activeQid} with type ${target.type}, expected ${Array.from(goal_scope_1.GOAL_SCOPE_ACTIONABLE_TYPES).join(", ")}`);
+            continue;
+        }
+        if (scope.qids.size > 0 && !scope.actionableQids.has(activeQid)) {
+            pushError(errors, `${qid}: active_node ${activeQid} is not inside goal scope_refs`);
+        }
+    }
+}
 function detectPrevNextCycles(index, errors) {
     const nodes = index.nodes;
     const seen = new Set();
@@ -480,6 +520,7 @@ function collectGraphErrors(index, options = {}) {
     validateAgentWorkflowDisputeRefs(index, allowMissing, errors);
     validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, externalWorkspaces, errors);
     validateArchiveUriRefs(index, allowMissing, errors);
+    validateGoalRefs(index, allowMissing, errors);
     detectPrevNextCycles(index, errors);
     return errors;
 }

package/dist/init/AGENT_START.md

@@ -23,6 +23,11 @@ Agent operating prompt:
 - Treat mdkg rules, EDDs, DECs, PRDs, and work nodes as more authoritative than chat memory.
 - Use `mdkg show <id>` for direct inspection and `mdkg show <id> --meta` for card-only inspection.
 - Use `mdkg search "..."` and `mdkg next` to discover current work.
+- Use `mdkg new goal "..."` for long-running recursive objectives that need an explicit end condition, active node, required skills, required checks, and completion evidence.
+- Use `mdkg goal select <goal-id>` when a goal is active, then `mdkg goal next` to surface one scoped feature, task, bug, or test at a time; normal `mdkg next` remains for non-goal concrete work.
+- Use `mdkg goal claim [goal-id] <work-id>` only after accepting the surfaced work item; `mdkg goal next` is read-only.
+- Treat goal `required_checks` as report-only guidance from mdkg. Run commands yourself, then record evidence in the goal or active work item.
+- Record skill improvement candidates during normal goal execution; edit `SKILL.md` only when the active node is explicit skill-maintenance work.
 - Use `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>` for skill discovery.
 - Use `mdkg capability list/search/show` for deterministic skills, `SPEC.md`, `WORK.md`, core-doc, and design-doc capability discovery.
 - Use `mdkg index` to refresh JSON compatibility caches and `.mdkg/index/mdkg.sqlite` when SQLite mode is enabled.
@@ -37,7 +42,7 @@ Agent operating prompt:
 - Mark archive sidecars public only with explicit `mdkg archive add --visibility public` intent.
 - Treat sidecar `.md` plus deterministic `.zip` caches as the commit-eligible archive record; validation and `mdkg archive verify` both check ZIP payload integrity.
 - Before committing repos that track archive caches or `.mdkg/bundles/`, run `mdkg archive compress --all`, `mdkg archive verify --json`, `mdkg bundle create --profile private`, and `mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip`.
-- Use `mdkg task start/update/done` for structured task, bug, and test lifecycle fields.
+- Use `mdkg task start/update/done` for structured feature, task, bug, and test lifecycle fields.
 - Use `mdkg upgrade` to preview scaffold updates; only run `mdkg upgrade --apply` after reviewing the receipt.
 - Keep nuanced summaries, body text, and manual parent closeout edits in markdown.
 - Use `mdkg event enable` only if `events.jsonl` is missing and provenance should be restored.
@@ -51,6 +56,16 @@ If the active task is known:
 - `mdkg task done <id>` when work is complete
 - `mdkg validate`
 
+If an active goal is known:
+- `mdkg goal select <goal-id>`
+- `mdkg goal current`
+- `mdkg goal next`
+- `mdkg goal claim <work-id>`
+- work the selected concrete node to completion
+- run required checks and record evidence
+- `mdkg goal evaluate <goal-id>`
+- repeat until the goal condition is achieved, blocked, paused, or budget-limited
+
 If no task is known:
 - `mdkg search "..."`
 - `mdkg show <id>`

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -19,6 +19,7 @@ Primary commands:
 - `mdkg archive`
 - `mdkg bundle`
 - `mdkg work`
+- `mdkg goal`
 - `mdkg task`
 - `mdkg validate`
 
@@ -32,6 +33,7 @@ Validation commands:
 
 Node creation commands:
 - `mdkg new <type> "<title>" [options] [--json]`
+- `mdkg new goal "<title>" [options] [--json]`
 
 Agent workflow file type creation:
 - `mdkg new spec "<title>" [options] [--json]`
@@ -48,6 +50,7 @@ Agent workflow notes:
 - `--id <portable-id>` is only for agent workflow file types.
 - `spec` and `work` scaffold as validation-clean standalone docs.
 - `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
+- `goal` nodes capture recursive objective state and required checks, but normal `mdkg next` does not select them.
 
 Workspace registry commands:
 - `mdkg workspace ls [--json]`
@@ -146,6 +149,30 @@ Work semantic mirrors:
 - `artifact://...` refs identify external/runtime-managed artifacts; `archive://...` refs identify committed mdkg archive sidecars
 - work update and artifact commands accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace
 
+Goal nodes:
+- `mdkg goal show <goal-id-or-qid> [--json]`
+- `mdkg goal select <goal-id-or-qid> [--json]`
+- `mdkg goal current [--json]`
+- `mdkg goal clear [--json]`
+- `mdkg goal next [goal-id-or-qid] [--json]`
+- `mdkg goal claim [goal-id-or-qid] <work-id-or-qid> [--json]`
+- `mdkg goal evaluate <goal-id-or-qid> [--json]`
+- `mdkg goal pause|resume|done <goal-id-or-qid> [--json]`
+- `mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal select <goal-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal current [--ws <alias>] [--json]`
+- `mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]`
+- `mdkg goal claim <work-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal claim <goal-id-or-qid> <work-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal evaluate <goal-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal pause <goal-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal resume <goal-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal done <goal-id-or-qid> [--ws <alias>] [--json]`
+- goals orchestrate recursive progress through explicit `scope_refs`; tasks, bugs, tests, and features remain concrete executable units
+- `goal next` is read-only; use `goal claim` to set `active_node`
+- `mdkg goal evaluate` is report-only and never runs commands from `required_checks`
+- skill improvements discovered during normal goal execution should be recorded as candidates or proposals unless the active node is skill-maintenance
+
 Discovery/show export flags:
 - `--json`
 - `--xml`

package/dist/init/README.md

@@ -30,7 +30,7 @@ mdkg subgraph list --json
 mdkg validate
 ```
 
-This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg new` to create work, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
+This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal select/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
 
 Agent workflow docs can use semantic ids:
 

package/dist/init/core/rule-3-cli-contract.md

@@ -157,6 +157,7 @@ If a user provides an unqualified ID and it is ambiguous globally:
   - uses global templates (root-only) via token substitution
   - writes into the appropriate workspace-local `.mdkg/<area>/` folder
   - updates index if necessary
+  - supports `goal` nodes for recursive objective contracts
 
 Common flags:
 - `--ws <alias>` (default `root`)
@@ -176,6 +177,27 @@ Common flags:
 - `--skills <slug,slug,...>` (work items)
 - `--template <set>` (default from config)
 
+### Goal commands
+- `mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]`
+  - reports condition, goal state, scope refs, active node, required skills, required checks, and source path
+- `mdkg goal select <goal-id-or-qid> [--ws <alias>] [--json]`
+  - stores local ignored selected-goal state at `.mdkg/state/selected-goal.json`
+- `mdkg goal current [--ws <alias>] [--json]`
+  - reports selected goal or a unique active goal fallback without requiring committed state
+- `mdkg goal clear [--json]`
+  - clears local selected-goal state
+- `mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]`
+  - read-only; resolves explicit id, then selected goal, then one unique active goal
+  - recursively expands `scope_refs` through `epic` and `parent` edges
+  - selects local `feat`, `task`, `bug`, or `test` work and never returns the goal or container-only epic itself
+- `mdkg goal claim [goal-id-or-qid] <work-id-or-qid> [--ws <alias>] [--json]`
+  - explicit mutating path that writes goal `active_node` after the work is confirmed inside scope
+- `mdkg goal evaluate <goal-id-or-qid> [--ws <alias>] [--json]`
+  - report-only; lists required checks and completion evidence state without executing scripts
+- `mdkg goal pause|resume|done <goal-id-or-qid> [--ws <alias>] [--json]`
+  - updates `goal_state`, compatible work status, and `updated`
+- subgraph goal qids are read-only and must be changed in their source workspace
+
 ### Read/search
 - `mdkg show <id-or-qid> [--meta] [--json|--xml|--toon|--md]`
   - default behavior shows the full node body
@@ -290,6 +312,7 @@ Common flags:
 - `mdkg next [<id-or-qid>] [--ws <alias>]`
   - If `<id>` provided: follow `next` if present; otherwise fall back to priority-based selection.
   - If no `<id>` provided: use priority-based selection (and optionally an epic filter in future).
+  - Does not select `goal` nodes; use `mdkg goal select <goal-id>` plus `mdkg goal next`, or explicit `mdkg goal next <goal-id>`, for goal-scoped selection.
 
 ### Checkpoints
 - `mdkg checkpoint new "<title>" [--ws <alias>] [--relates <id,...>] [--scope <id,...>]`
@@ -310,6 +333,9 @@ Common flags:
   - `TASK_STARTED`
   - `TASK_UPDATED`
   - `TASK_DONE`
+  - `GOAL_PAUSE`
+  - `GOAL_RESUME`
+  - `GOAL_DONE`
 
 ### Validation and formatting
 - `mdkg validate`

package/dist/init/core/rule-4-repo-safety-and-ignores.md

@@ -23,6 +23,7 @@ mdkg content may contain sensitive notes and internal project planning. This rul
 - `.mdkg/` must not be published to npm.
 - Generated JSON index, temp, lock, WAL, SHM, and journal files under `.mdkg/index/` must not be committed.
 - `.mdkg/index/mdkg.sqlite` is a rebuildable access cache and may be committed when the repo intentionally tracks it and it stays reasonably small.
+- `.mdkg/state/` stores local workflow convenience state and must not be committed.
 - `.mdkg/bundles/` may be committed only when the repo intentionally tracks private or public snapshot bundles.
 
 ## Git ignore requirements
@@ -37,6 +38,7 @@ The repo MUST ignore at minimum:
 - `.mdkg/index/*.sqlite-wal`
 - `.mdkg/index/*.sqlite-shm`
 - `.mdkg/index/*.sqlite-journal`
+- `.mdkg/state/`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
 
@@ -47,6 +49,7 @@ Recommended `.gitignore` entries:
 - `.mdkg/index/*.sqlite-wal`
 - `.mdkg/index/*.sqlite-shm`
 - `.mdkg/index/*.sqlite-journal`
+- `.mdkg/state/`
 - `.mdkg/pack/`
 - `.mdkg/archive/**/source/`
 
@@ -87,7 +90,7 @@ For application builds:
 
 `mdkg init` updates ignore files by default for safety:
 
-- `.gitignore` appends generated index cache/temp/lock patterns, `.mdkg/pack/`, and raw archive source ignores.
+- `.gitignore` appends generated index cache/temp/lock patterns, `.mdkg/state/`, `.mdkg/pack/`, and raw archive source ignores.
 - `.npmignore` appends `.mdkg/`, generated index cache/temp/lock patterns, and `.mdkg/pack/`.
 - `--no-update-ignores` disables these default writes
 
@@ -102,6 +105,7 @@ Explicit flags remain available and take precedence:
 - `.mdkg/index/` contains generated caches.
 - JSON index files may contain extracted metadata and could expose sensitive strings; they MUST be ignored from git.
 - `.mdkg/index/mdkg.sqlite` contains the same rebuildable access data and may be committed only by explicit repo policy; `mdkg doctor` warns when it exceeds `index.sqlite_commit_warning_bytes`.
+- `.mdkg/state/` contains local workflow convenience state such as selected goals and MUST stay ignored.
 - Index rebuild should be deterministic and safe to regenerate at any time.
 
 ## Bundle safety
@@ -131,6 +135,7 @@ Workspace-local `.mdkg/` directories (near code) should follow the same rules:
 ## Summary checklist
 
 - ✅ generated JSON index/temp/lock files ignored
+- ✅ local `.mdkg/state/` ignored
 - ✅ `.mdkg/index/mdkg.sqlite` committed only by explicit repo policy
 - ✅ event logs are committed by default unless a repo chooses to ignore them manually
 - ✅ npm publishes only `dist/`, `README.md`, `LICENSE`

package/dist/init/core/rule-6-templates-and-schemas.md

@@ -91,12 +91,21 @@ All nodes MAY include the following searchable frontmatter lists:
 List fields SHOULD be written as `[]` when empty.
 Optional scalar graph fields (like `epic`, `parent`, `prev`, `next`) should be omitted when empty.
 
-Work items (`epic/feat/task/bug/checkpoint/test`):
+Work items (`goal/epic/feat/task/bug/checkpoint/test`):
   - `status` (enum)
   - optional `priority` (0..9)
   - optional `skills: [slug, ...]` (kebab-case skill slugs)
   - optional graph edges: `epic`, `parent`, `relates`, `blocked_by`, `blocks`, `prev`, `next`
 
+Goal nodes (`goal-*`):
+- required `goal_state`: `active`, `paused`, `achieved`, `blocked`, or `budget_limited`
+- required `goal_condition` up to 4000 characters for external slash-command compatibility
+- optional `scope_refs: [id-or-qid, ...]` naming explicit goal ownership roots; allowed targets are `epic`, `feat`, `task`, `bug`, and `test`
+- optional `active_node`
+- optional `required_skills: [slug, ...]`
+- optional `required_checks: [command, ...]` as report-only guidance; mdkg does not execute these scripts
+- optional positive integer strings `max_iterations` and `blocked_after_attempts`
+
 Decision records (`dec-*`):
 - `status` (enum: `proposed`, `accepted`, `rejected`, `superseded`)
 - optional `supersedes: dec-#`

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.1.4",
+  "mdkg_version": "0.1.6",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -36,12 +36,12 @@
     {
       "path": ".mdkg/core/rule-3-cli-contract.md",
       "category": "core",
-      "sha256": "4ec25c6936eefe0857a2946b47f0b65c9481bd65f1159fd5456bec6cce9de7ea"
+      "sha256": "0b72a2448cc91779278fed6e011c3936c31c5b11a7365a4145941dcc90f805a3"
     },
     {
       "path": ".mdkg/core/rule-4-repo-safety-and-ignores.md",
       "category": "core",
-      "sha256": "2374e8684dfb32d24d560c83c99c33ff655cfdfe6811372dc3959ec93318a6db"
+      "sha256": "d8aff39af7a00e63db51831d4324856bbf49d3e3434141416903bad42c7d5380"
     },
     {
       "path": ".mdkg/core/rule-5-release-and-versioning.md",
@@ -51,7 +51,7 @@
     {
       "path": ".mdkg/core/rule-6-templates-and-schemas.md",
       "category": "core",
-      "sha256": "5181e2e8a025cb6b9d160c1232c425bfc426fd8fd1ae3f75ce5052981807fc5f"
+      "sha256": "3ae20e1a925154ddc69bfc79495b169500aa5158db2134336890b00e64750c2f"
     },
     {
       "path": ".mdkg/core/SOUL.md",
@@ -61,22 +61,27 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "5ee6c141c0052e78671762e69c111f7f0a5d7f79b35c8f78c5b3b41901bd6959"
+      "sha256": "f733792daa2b0f3318fd7b39fa2f812c61b8a3f5f630dba2f271cdcb10af9927"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
       "category": "default_skill",
       "sha256": "3e240cb844b22e5e4c0046a4f839ac3c0d771a62d00a72719fc449477564b1ae"
     },
+    {
+      "path": ".mdkg/skills/pursue-mdkg-goal/SKILL.md",
+      "category": "default_skill",
+      "sha256": "fd64f666fb1329c392ff0979ed9999b71ad948cbca6a191502eb2cdfd76ec825"
+    },
     {
       "path": ".mdkg/skills/select-work-and-ground-context/SKILL.md",
       "category": "default_skill",
-      "sha256": "c8c04134532deda079f9ee290a66b2423892f9789fa946e44db4c89c05b8e1bf"
+      "sha256": "e50fc3b1a2c79a9a3544ca9df1bf4ca9c312e7c3a51d5e4c6f3314341eca268b"
     },
     {
       "path": ".mdkg/skills/verify-close-and-checkpoint/SKILL.md",
       "category": "default_skill",
-      "sha256": "67fc3d7e3c59b53add62306624391c1a416d0c66077729d79e1be0a303538f42"
+      "sha256": "f85ffa4a139db10c3bc3203cde0e4f41603fbc7f3925e6fdaba821346ffa28b8"
     },
     {
       "path": ".mdkg/templates/default/archive.md",
@@ -123,6 +128,11 @@
       "category": "template",
       "sha256": "61ad7b8b717d17736ba505f814fa6e4f9ec61f7fe4ae6622359304620a99d649"
     },
+    {
+      "path": ".mdkg/templates/default/goal.md",
+      "category": "template",
+      "sha256": "710252d8a2dc35be71661d6988007af127052fa8ad24b1fb00374c975ae117a2"
+    },
     {
       "path": ".mdkg/templates/default/prd.md",
       "category": "template",
@@ -176,7 +186,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "abde8671d34fcc7abd8570cf8c10b940cbe8f339edb369bd046045aa5626c0fc"
+      "sha256": "7676e534b2f161a19764de666d9362b9ee1c6cdec6ec9fdfacab2eb52ce0e80d"
     },
     {
       "path": "AGENTS.md",
@@ -191,7 +201,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "14deecded057a99284d2dc147855d12dedffec049da51fed3b1ebdae3105d537"
+      "sha256": "a2f59afae403fff7335b0cf0109ee550c7a864b9ef6744b39a645096432e5206"
     },
     {
       "path": "llms.txt",