mdkg 0.1.3 → 0.1.5

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]`
@@ -92,6 +95,7 @@ Capability discovery:
 - `mdkg capability list [--kind <skill|spec|work|core|design>] [--visibility <private|internal|public>] [--json]`
 - `mdkg capability search "<query>" [--kind <kind>] [--visibility <level>] [--json]`
 - `mdkg capability show <id-or-qid-or-slug> [--json]`
+- `mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]`
 - capability records are deterministic cache projections from Markdown
 - records include source hash, headings, refs, and `indexed_at`
 - normal task, epic, feat, bug, test, and checkpoint nodes are intentionally excluded
@@ -114,16 +118,24 @@ Graph snapshot bundles:
 - `mdkg bundle verify [bundle-path] [--json]`
 - `mdkg bundle show <bundle-path> [--json]`
 - `mdkg bundle list [--json]`
-- `mdkg bundle import add/list/rm/enable/disable/verify ...`
-- `mdkg bundle import add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--json]`
-- `mdkg bundle import verify [alias|--all] [--json]`
 - default output is `.mdkg/bundles/<profile>/<workspace-or-all>.mdkg.zip`
 - private bundles are explicit local graph transport artifacts
-- bundle imports are read-only planning views and use import-alias qids such as `child_repo:task-1`
 - repos that track archive caches or bundles should run `mdkg archive compress --all`, `mdkg archive verify --json`, `mdkg bundle create --profile private`, and `mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip` before commit
 - public bundles include only public workspace content and public archive sidecars
-- public bundle creation fails when public records reference private graph, archive, or imported records
-- public/internal imports require public bundle profiles
+- public bundle creation fails when public records reference private graph, archive, or subgraph records
+
+Subgraph orchestration:
+- `mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--json]`
+- `mdkg subgraph list [--json]`
+- `mdkg subgraph show <alias> [--json]`
+- `mdkg subgraph rm <alias> [--json]`
+- `mdkg subgraph enable <alias> [--json]`
+- `mdkg subgraph disable <alias> [--json]`
+- `mdkg subgraph verify [alias|--all] [--json]`
+- `mdkg subgraph refresh [alias|--all] [--json]`
+- subgraphs are read-only planning views and use subgraph-alias qids such as `child_repo:task-1`
+- subgraph refresh reloads configured bundle sources only and never mutates child repos
+- public/internal subgraphs require public bundle profiles
 
 Work semantic mirrors:
 - `mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--required-capabilities <...>] [--pricing-model <...>] [--json]`
@@ -135,7 +147,31 @@ Work semantic mirrors:
 - work commands mutate mdkg semantic mirror files only; production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg
 - do not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in work 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; imported bundle qids are read-only and must be changed in their source workspace
+- 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`

package/dist/init/README.md

@@ -26,11 +26,11 @@ mdkg pack <id>
 mdkg capability search "..."
 mdkg archive list
 mdkg bundle create --profile private
-mdkg bundle import list --json
+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 archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors, `mdkg bundle ...` to create full graph snapshot bundles and read-only child graph imports, `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:
 
@@ -87,16 +87,17 @@ mdkg bundle create --profile private
 mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip
 ```
 
-Use this as a pre-commit recommendation only when the repo tracks archive caches or `.mdkg/bundles/`. Private bundles are local graph transport artifacts and may be tracked in private repos when configured. Public bundles require selected workspaces with `visibility: public` and fail closed when public records reference private graph, archive, or imported records.
+Use this as a pre-commit recommendation only when the repo tracks archive caches or `.mdkg/bundles/`. Private bundles are local graph transport artifacts and may be tracked in private repos when configured. Public bundles require selected workspaces with `visibility: public` and fail closed when public records reference private graph, archive, or subgraph records.
 
-Register child bundle snapshots as read-only imports with:
+Register child bundle snapshots as read-only subgraphs with:
 
 ```bash
-mdkg bundle import add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
-mdkg bundle import verify child_repo --json
+mdkg subgraph add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
+mdkg capability resolve "child capability" --json
+mdkg subgraph verify child_repo --json
 ```
 
-Imported nodes use the import alias as their qid prefix and can be inspected or packed, but mutations must happen in the owning child repo.
+Subgraph nodes use the subgraph alias as their qid prefix and can be inspected or packed, but mutations must happen in the owning child repo.
 
 ## Archive and Work Mirrors
 
@@ -118,7 +119,7 @@ mdkg work receipt new "example receipt" --id receipt.example-1 --work-order-id o
 ```
 
 Receipt statuses are `recorded`, `verified`, `rejected`, and `superseded`.
-Update and artifact commands accept local ids or local qids; imported bundle qids are read-only and must be changed in their source workspace.
+Update and artifact commands accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace.
 
 Production orders, receipts, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg. mdkg stores committed semantic mirrors and reviewable evidence. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
 

package/dist/init/config.json

@@ -21,7 +21,7 @@
     "output_dir": ".mdkg/bundles",
     "default_profile": "private"
   },
-  "bundle_imports": {},
+  "subgraphs": {},
   "pack": {
     "default_depth": 2,
     "default_edges": [

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

@@ -69,9 +69,9 @@ Workspaces are registered in `.mdkg/config.json`.
 
 Qualified IDs may be used as input:
 - `<ws>:<id>` (example: `e2e:task-12`)
-- Imported bundle nodes use the same qualified form with the import alias:
-  - `<import-alias>:<id>` (example: `agent_image:work.generate-image`)
-  - imported nodes are read-only planning context and MUST NOT be selected by local mutation commands
+- Subgraph nodes use the same qualified form with the subgraph alias:
+  - `<subgraph-alias>:<id>` (example: `agent_image:work.generate-image`)
+  - subgraph nodes are read-only planning context and MUST NOT be selected by local mutation commands
 
 If a user provides an unqualified ID and it is ambiguous globally:
 - mdkg MUST error and suggest qualified IDs.
@@ -145,7 +145,7 @@ If a user provides an unqualified ID and it is ambiguous globally:
   - rebuild global cache `.mdkg/index/global.json`
   - rebuild skills cache `.mdkg/index/skills.json` from `.mdkg/skills/<slug>/SKILL.md`
   - rebuild capability cache `.mdkg/index/capabilities.json` from skills, `SPEC.md`, `WORK.md`, core docs, and design docs
-  - rebuild bundle import projection cache `.mdkg/index/imports.json` when bundle imports are configured
+  - rebuild subgraph projection cache `.mdkg/index/subgraphs.json` when subgraphs are configured
   - rebuild SQLite access cache `.mdkg/index/mdkg.sqlite` when `index.backend` is `sqlite`
   - tolerate `.mdkg/skills/<slug>/SKILLS.md` on read with warning
   - fail validation if both `SKILL.md` and `SKILLS.md` exist in one skill directory
@@ -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
@@ -183,10 +205,10 @@ Common flags:
 - `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
   - search SHOULD match on IDs, titles, tags, path tokens, and searchable frontmatter lists (`links`, `artifacts`, `refs`, `aliases`)
 - `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--blocked] [--priority <n>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
-- enabled bundle imports are included in `show`, `search`, `list`, `pack`, and `capability` reads by default:
-  - imported nodes surface `source.imported: true` in JSON output
-  - human output labels imported nodes as read-only and stale when applicable
-  - stale imports warn during planning reads but remain usable
+- enabled subgraphs are included in `show`, `search`, `list`, `pack`, and `capability` reads by default:
+  - subgraph nodes surface `source.imported: true` and `source.subgraph_alias` in JSON output
+  - human output labels subgraph nodes as read-only and stale when applicable
+  - stale subgraphs warn during planning reads but remain usable
 - skills are first-class under `mdkg skill ...` only:
   - `mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
   - `mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]`
@@ -197,7 +219,9 @@ Common flags:
   - `mdkg capability list [--kind <skill|spec|work|core|design>] [--visibility <private|internal|public>] [--json]`
   - `mdkg capability search "<query>" [--kind <kind>] [--visibility <level>] [--json]`
   - `mdkg capability show <id-or-qid-or-slug> [--json]`
+  - `mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]`
   - capability records are read-only derived cache entries, not source of truth
+  - `resolve` ranks local and subgraph capability candidates deterministically and degrades stale subgraphs unless `--fresh-only` is supplied
   - normal task, epic, feat, bug, test, and checkpoint nodes are not capability records
 - archives are first-class sidecar nodes under `mdkg archive ...`:
   - `mdkg archive add <file> [--id <archive.id>] [--kind source|artifact] [--visibility private|internal|public] [--title <title>] [--refs <...>] [--relates <...>] [--json]`
@@ -215,21 +239,26 @@ Common flags:
   - `mdkg bundle verify [bundle-path] [--json]`
   - `mdkg bundle show <bundle-path> [--json]`
   - `mdkg bundle list [--json]`
-  - `mdkg bundle import add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--source-repo <ref>] [--max-stale-seconds <seconds>] [--json]`
-  - `mdkg bundle import list [--json]`
-  - `mdkg bundle import rm <alias> [--json]`
-  - `mdkg bundle import enable <alias> [--json]`
-  - `mdkg bundle import disable <alias> [--json]`
-  - `mdkg bundle import verify [alias|--all] [--json]`
   - bundles are explicit transport artifacts and are not rewritten by `mdkg index`
   - default output is `.mdkg/bundles/<profile>/<workspace-or-all>.mdkg.zip`
   - public bundles must fail closed when public records reference private graph or archive records
-  - public bundles must fail closed when public records reference private/internal imported graph records
-  - bundle imports are read-only projected graph views; child repos remain owners of real mutations and commits
-  - `bundle import verify` exits nonzero for stale, missing, corrupt, profile-mismatched, or duplicate-id imports
-  - public bundle creation must not re-export imported child graph content and must fail if public local nodes reference private/internal imports
-  - public/internal imports require `expected_profile: public`; private bundle profiles cannot be promoted through import visibility
+  - public bundles must fail closed when public records reference private/internal subgraph records
+  - public bundle creation must not re-export subgraph content and must fail if public local nodes reference private/internal subgraphs
   - `mdkg pack --visibility public|internal|private` records explicit pack visibility and filters public/internal packs through the same fail-closed policy
+- subgraph orchestration lives under `mdkg subgraph ...`:
+  - `mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--source-repo <ref>] [--max-stale-seconds <seconds>] [--json]`
+  - `mdkg subgraph list [--json]`
+  - `mdkg subgraph show <alias> [--json]`
+  - `mdkg subgraph rm <alias> [--json]`
+  - `mdkg subgraph enable <alias> [--json]`
+  - `mdkg subgraph disable <alias> [--json]`
+  - `mdkg subgraph verify [alias|--all] [--json]`
+  - `mdkg subgraph refresh [alias|--all] [--json]`
+  - subgraphs are read-only projected graph views; child repos remain owners of real mutations and commits
+  - `subgraph refresh` reloads configured bundle sources only and never builds or mutates child repos
+  - `subgraph verify` exits nonzero for stale, missing, corrupt, profile-mismatched, or duplicate-id subgraphs
+  - public/internal subgraphs require `expected_profile: public`; private bundle profiles cannot be promoted through subgraph visibility
+  - legacy `mdkg bundle import ...` exits with guidance to run `mdkg upgrade --apply` and use `mdkg subgraph ...`
 - work lifecycle helpers live under `mdkg work ...`:
   - `mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--required-capabilities <...>] [--pricing-model <...>] [--json]`
   - `mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--request-ref <ref>] [--input-refs <...>] [--requested-outputs <...>] [--json]`
@@ -240,7 +269,7 @@ Common flags:
   - these commands mutate mdkg semantic mirror files only; production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg
   - work mirrors must not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state
   - `artifact://...` refs identify external/runtime-managed artifacts; `archive://...` refs identify committed mdkg archive sidecars
-  - update and artifact commands accept local ids or local qids; imported bundle qids are read-only and must be changed in their source workspace
+  - update and artifact commands accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace
 - discovery/show output flags are mutually exclusive; text mode remains the default when none are supplied
 
 ### Task lifecycle mutation
@@ -251,7 +280,7 @@ Common flags:
   - supports additive list mutation for `artifacts`, `links`, `refs`, `skills`, `tags`, and `blocked_by`
   - supports scalar replacement for `status` and `priority`
   - `--clear-blocked-by` resets blockers before optional re-add
-  - imported bundle qids fail with an explicit read-only import error
+  - subgraph qids fail with an explicit read-only subgraph error
 - `mdkg task done <id-or-qid> [--checkpoint "<title>"] [...]`
   - supports `task`, `bug`, and `test` nodes only
   - sets `status: done`
@@ -283,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,...>]`
@@ -303,13 +333,16 @@ Common flags:
   - `TASK_STARTED`
   - `TASK_UPDATED`
   - `TASK_DONE`
+  - `GOAL_PAUSE`
+  - `GOAL_RESUME`
+  - `GOAL_DONE`
 
 ### Validation and formatting
 - `mdkg validate`
   - strict frontmatter + graph integrity checks (exit code 2 on failure)
   - validates optional node->skill references
-  - validates configured bundle imports and fails on missing/corrupt enabled bundles, malformed import config, duplicate projected ids, and invalid import refs
-  - warns, but does not fail, on stale imports
+  - validates configured subgraphs and fails on missing/corrupt enabled bundles, malformed subgraph config, duplicate projected ids, and invalid subgraph refs
+  - warns, but does not fail, on stale subgraphs
   - validates optional `.mdkg/work/events/events.jsonl` record shape when file exists
   - warns when `.agents/skills/` or `.claude/skills/` drift from canonical `.mdkg/skills/`
 - `mdkg format`

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,13 +105,14 @@ 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
 
 - `.mdkg/bundles/` stores explicit snapshot artifacts and is not ignored by default.
 - Private bundles may include sensitive authored mdkg content and should stay in private repos.
-- Public bundles must be created with `mdkg bundle create --profile public` so private graph, archive, and imported bundle refs fail closed.
+- Public bundles must be created with `mdkg bundle create --profile public` so private graph, archive, and subgraph refs fail closed.
 - Public-safe packs must be created with `mdkg pack <id> --visibility public`; internal-safe packs use `--visibility internal`. These filters do not redact Markdown body text.
 - Bundle ZIPs must exclude `.mdkg/pack/`, existing `.mdkg/index/`, nested `.mdkg/bundles/`, and raw `.mdkg/archive/**/source/` files.
 - Repos that track archive caches or bundles should refresh in this order before commit: `mdkg archive compress --all`, `mdkg archive verify --json`, `mdkg bundle create --profile private`, then bundle verify.
@@ -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,12 +1,12 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.1.3",
+  "mdkg_version": "0.1.5",
   "files": [
     {
       "path": ".mdkg/config.json",
       "category": "config",
-      "sha256": "0319f2e92ae0030d67816c025802be50ec5eecc3274e75a4e0ded3e753d945b3"
+      "sha256": "5d2cf5e773353a59178fe86f8528413a00a73e2879fb1e020d01b49c0715a9ce"
     },
     {
       "path": ".mdkg/core/core.md",
@@ -36,12 +36,12 @@
     {
       "path": ".mdkg/core/rule-3-cli-contract.md",
       "category": "core",
-      "sha256": "4ff22c60e3b4093492f00c8ddd738f7241192c7b1edbfdcbdc4ed09d95192aa6"
+      "sha256": "0b72a2448cc91779278fed6e011c3936c31c5b11a7365a4145941dcc90f805a3"
     },
     {
       "path": ".mdkg/core/rule-4-repo-safety-and-ignores.md",
       "category": "core",
-      "sha256": "4edf0efa29ec470e96cad3e0abc7b8f44e2e718d7a9959f9cefc5e1db7e02b6c"
+      "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": "6ff69157098b5cc780f063ffadabff36b70e8567cec7fc406d7550385c467d0e"
+      "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": "cf9d7f01eb78a3cf669b6303c2f22c7c08529fe0181e008a7b45c5e5b70ceb49"
+      "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": "e5bd54a4321443216645b11fd5f27aff2e8f6c760f21dad12b6d0dbe634b0986"
+      "sha256": "bb8654d11adb2ed6cb45f3514bbf7fad8fe6cda8a2e0e1676462542563df0df9"
     },
     {
       "path": "AGENTS.md",
@@ -191,7 +201,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "6e347620120c93eb9f330d137087f9e6b3279c629fcc24b65af561bd3cf385a0"
+      "sha256": "a2f59afae403fff7335b0cf0109ee550c7a864b9ef6744b39a645096432e5206"
     },
     {
       "path": "llms.txt",

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
 
@@ -46,7 +47,7 @@ Use this local repo-only checklist before publishing mdkg:
 
 1. Confirm package intent and version in `package.json`, `package-lock.json`, `README.md`, `CLI_COMMAND_MATRIX.md`, and `CHANGELOG.md`.
 2. Use a clean npm cache: `export NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache`.
-3. Run `npm ci`, `npm run build`, `node scripts/assert-publish-ready.js`, `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`, and `npm run smoke:visibility`.
+3. Run `npm ci`, `npm run build`, `node scripts/assert-publish-ready.js`, `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`, and `npm run smoke:visibility`.
 4. Run `npm pack --dry-run --json` and confirm the tarball includes `dist/cli.js`, compiled folders, `dist/init/`, release docs, and `scripts/postinstall.js`.
 5. Confirm registry state with `npm view mdkg version --registry=https://registry.npmjs.org/`.
 6. Publish only after the registry still shows the previous version and npm auth is known to have write access.