mdkg 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,98 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
+## 0.5.0 - 2026-07-11
+
+### Added
+
+- Added `loop` as a first-class mdkg work node for reusable, durable agentic
+  processes that can coordinate goals, tasks, tests, spikes, proposals,
+  decisions, checkpoints, receipts, evidence, and repeated attempts.
+- Added the semantic `mdkg loop list`, `show`, `fork`, `plan`, `next`, and
+  `runs` command family, plus deterministic `mdkg new loop` guidance for raw
+  loops versus bundled templates.
+- Added identity-bound loop readiness metadata for pre-run questions, action
+  approvals, evidence lanes, and paired decision/approval waivers.
+- Added immutable template provenance, content hashes, stale-fork warnings,
+  default child materialization, and an explicit planning-only fork mode.
+- Added seven bundled read-only or planning loop templates for security,
+  frontend design, backend/API/CLI design, tech-stack practices, duplication
+  and linting, test/CI/skill infrastructure, and user-story audits.
+- Added the reusable `pursue-mdkg-loop` agent skill to keep authorized child
+  lanes moving, recover blockers through grounded spikes and proposals, and
+  close only against the loop definition of done.
+- Added a gated mdkg.dev announcement and top-level Loops documentation with a
+  purpose-built read-only security audit walkthrough. Public promotion remains
+  controlled by the shared source release manifest.
+
+### Changed
+
+- Integrated loops into parser/template validation, generic discovery,
+  SQLite/JSON indexes, search/show/list output, deterministic pack traversal,
+  generated help, command contracts, init assets, and upgrade fallback paths.
+- Made loop fork dry-runs observational across JSON and SQLite backends: no ID
+  reservation, event write, index persistence, or graph/filesystem mutation.
+- Made read-only loop commands use non-persisting index projections and made
+  `loop next` exhaust authorized nested work and blocker-recovery lanes before
+  reporting the whole loop blocked.
+- Kept loop templates, scoped forks, and run-bearing state under one `loop`
+  node type; mdkg preserves orchestration state while the coding-agent harness
+  remains responsible for executing agents and tools.
+- Added installed-package smoke coverage for every bundled loop template and a
+  public-repository release-readiness workflow across the minimum supported
+  Node version and current Node line.
+- Cleaned mdkg.dev/docs public copy and demo proof surfaces while preserving
+  the existing quickstart-first product journey and Pre-v1 public-alpha scope.
+
+### Fixed
+
+- Fixed readiness projection so unrelated decisions, approvals, evidence, and
+  waivers cannot satisfy a different question, action, or evidence lane.
+- Fixed loop routing so one blocked child does not halt other authorized work,
+  and whole-loop blocking occurs only after useful work and recovery paths are
+  exhausted.
+- Fixed stale-template handling to warn from recorded template identity and
+  content hash without silently rewriting scoped forks.
+
+### Security
+
+- Hardened graph target writes against symlink containment escapes before any
+  destination mutation.
+- Bounded ZIP entry count, compressed size, declared output, total output, and
+  expansion ratio before bundle or subgraph inflation.
+
+## 0.4.2 - 2026-07-05
+
+### Added
+
+- Added the low-level `mdkg git` command family for Git-backed project
+  lifecycle primitives: `inspect`, `clone`, `fetch`, `closeout`,
+  `push-ready`, and approval-gated real `push` execution.
+- Added Git source descriptors and accepted-revision evidence in command
+  receipts, including sanitized remote refs, branch, commit SHA, tree hash, and
+  the external-auth boundary.
+- Added `mdkg git closeout` static JSON/Markdown receipts, plus sealed project
+  DB snapshot and deterministic dump evidence when SQLite project state
+  participated in the run.
+
+### Changed
+
+- Made push readiness a high-bar preflight: explicit remote and branch,
+  credential-free remote config, clean worktree, passing mdkg validation, and a
+  valid DB snapshot when DB state participated.
+- Documented Git auth as external to mdkg through system Git, credential
+  helpers, SSH, `gh`, CI/runtime env, or shell state; mdkg stores only refs,
+  hashes, policy names, and receipts.
+- Deferred project-memory semantic query UX (`history`, `why`, and
+  `next-work`) to a separate CocoIndex-grounded design lane instead of shipping
+  it in the `0.4.2` Git lifecycle release.
+
+### Security
+
+- Rejects embedded URL credentials for repository refs and push remotes, and
+  redacts any userinfo that appears in inspected remote URLs before writing
+  receipts or JSON output.
+
 ## 0.4.1 - 2026-07-04
 
 ### Added
@@ -31,33 +123,29 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
   `resource_profile`, WORK `kind`, WORK_ORDER `artifact_policy`, RECEIPT
   `redaction_policy`, `receipt_kind`, `redaction_class`, and pack/bundle
   `--profile` flags.
-- Expanded release-readiness documentation and checks for `0.4.1` so the
-  implementation can hand off to a separate approval-gated publish goal.
+- Expanded documentation and validation checks for `0.4.1` so package readiness
+  can be verified before publication.
 
 ## 0.4.0 - 2026-06-27
 
 ### Added
 
-- Added the `0.4.0` public launch-readiness lane for mdkg.dev and
-  docs.mdkg.dev with explicit source metadata, changelog, generated-doc,
-  npm prepublish, npm postpublish, Vercel production, and Chrome live-validation
-  blockers.
-- Added public release-note and docs coverage for the `0.4.0` launch surface,
-  including per-release changelog cards, launch-track copy, and source-backed
-  currentness requirements.
-- Added Vercel production currentness and Chrome postpublish validation as
-  required evidence before mdkg.dev or docs.mdkg.dev can claim the `0.4.0`
-  launch is live.
+- Added public release cards and changelog detail pages for recent public-alpha
+  versions.
+- Added docs coverage for config overlays, custom skill mirrors,
+  `COLLABORATION.md`, MANIFEST naming, and public-alpha customization guidance.
+- Added mdkg.dev and docs.mdkg.dev copy updates that keep public claims bounded
+  to documented capabilities.
 
 ### Changed
 
-- Updated mdkg.dev and docs.mdkg.dev source copy for the `0.4.0` release target,
+- Updated mdkg.dev and docs.mdkg.dev source copy for the `0.4.0` public alpha,
   including config overlays, custom skill mirrors, `COLLABORATION.md`,
-  MANIFEST/SPEC compatibility, and Plan -> Work -> Evidence launch messaging.
+  MANIFEST/SPEC compatibility, and Plan -> Work -> Evidence messaging.
 - Updated public docs and examples to use the current `mdkg pack --profile
   concise` syntax instead of stale `--pack-profile concise` examples.
 - Aligned source-visible package references, generated release-note data, and
-  generated CLI docs with the `0.4.0` release target.
+  generated CLI docs with `0.4.0`.
 
 ### Fixed
 

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
-as_of: 2026-07-03
-package_version_in_source: 0.4.1
+as_of: 2026-07-11
+package_version_in_source: 0.5.0
 source: live help from `src/cli.ts`, runtime command handlers, and `dec-15`..`dec-18`
 status: canonical single-source command and flag reference for mdkg
 
@@ -42,9 +42,11 @@ Primary commands:
 - `archive`
 - `bundle`
 - `graph`
+- `git`
 - `subgraph`
 - `work`
 - `goal`
+- `loop`
 - `task`
 - `next`
 - `validate`
@@ -72,10 +74,16 @@ Reusable manifest capability records are accessed through `mdkg manifest ...`;
 Archive sidecars are accessed through `mdkg archive ...`.
 Full graph snapshot bundles are accessed through `mdkg bundle ...`.
 Whole-graph clone, fork, and same-repo template import workflows are accessed through `mdkg graph ...`.
+Low-level Git remote lifecycle primitives are accessed through `mdkg git ...`.
 Read-only child graph orchestration is accessed through `mdkg subgraph ...`.
 Work contract/order/receipt semantic mirrors are accessed through `mdkg work ...`.
 Recursive long-running objective contracts are accessed through `mdkg goal ...`.
+Reusable process-state loops are accessed through `mdkg loop ...`; mdkg stores loop graph state while runtimes execute agents and tools.
 Fresh init workspaces default to the SQLite access cache backend; existing migrated configs stay on JSON until opted in.
+Graph discovery enforces configurable `index.limits` for file count, per-file
+bytes, total bytes, and directory depth before reading Markdown. ZIP, pack, and
+local MCP surfaces apply additional fixed protocol-safe ceilings and return
+deterministic errors when a request or graph exceeds them.
 Project application database foundation commands are accessed through `mdkg db ...`; `mdkg index` remains the compatibility shortcut for graph index rebuilds.
 Operator health summaries are accessed through read-only `mdkg status ...`; deeper diagnostics remain under `mdkg doctor ...`.
 Repair planning is accessed through read-only `mdkg fix plan ...`; duplicate-ID graph repairs can be applied through `mdkg fix apply --family ids ...` or the convenience `mdkg fix ids --apply ...`. Index/cache and graph-reference findings remain plan/manual-review only.
@@ -160,6 +168,7 @@ Types:
 - `dec`
 - `prop`
 - `goal`
+- `loop`
 - `epic`
 - `feat`
 - `task`
@@ -193,6 +202,13 @@ Agent workflow file type creation:
 Goal node creation:
 - `mdkg new goal "<title>" [options] [--json]`
 
+Loop node creation:
+- `mdkg new loop "<title>" [options] [--json]`
+- loops are durable declarative graph process state, not runtime execution jobs
+- a loop may be a reusable template, scoped fork, or run-bearing loop through metadata and links
+- loop metadata records mode, scope, lineage, materialization, child refs, evidence/run refs, definition of done, and blocker-continuation policy
+- default seeded loops are read-only or planning-oriented audit/recommendation templates
+
 Spike node creation:
 - `mdkg new spike "<research question>" [options] [--json]`
 - spikes are actionable research/planning work nodes under `.mdkg/work/`
@@ -242,6 +258,7 @@ JSON receipt:
 Notes:
 - `--id` lets agent workflow files use semantic portable ids such as `agent.image-worker`, `work.generate-image`, or `proposal.review-loop-1`.
 - `goal` nodes capture recursive objective state and required checks, but normal `mdkg next` does not select them.
+- `loop` nodes capture reusable process state, fork lineage, child refs, run/evidence refs, blocker-continuation policy, and a high-bar definition of done; runtime execution remains outside mdkg.
 - `spec` and `work` scaffold as validation-clean standalone docs. `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` templates contain editable placeholder refs and need real graph or `skill.<slug>` refs before strict validation passes.
 
 ### `mdkg show`
@@ -746,6 +763,54 @@ JSON receipts:
 - `import-template`: `{ action: "graph.import_template", ok, mode, source, source_hash, preserved_ids: false, rewritten_ids, rewritten_refs, planned_paths, files_written, skipped_paths, start_goal?, selected_goal?, activated_goal?, paused_goals, index?, validation?, warnings }`
 - `refs`: `{ action: "graph.refs", ok, target, outgoing, incoming, warnings }`
 
+### `mdkg git`
+
+When to use:
+- inspect the current Git-backed mdkg project and accepted revision evidence
+- clone or fetch real Git remotes through the system Git CLI with external auth
+- close out mdkg state to static receipts before an agent checkpoint commit
+- prove push readiness before any approval-gated real remote push
+
+Usage:
+- `mdkg git inspect [--json]`
+- `mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]`
+- `mdkg git fetch [--remote <name>] [--branch <name>] [--json]`
+- `mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]`
+- `mdkg git push-ready --remote <name> --branch <name> [--json]`
+- `mdkg git push --remote <name> --branch <name> [--json]`
+- `mdkg git push --remote <name> --branch <name> --stage-all --message <text> [--queue-policy drain|paused] [--json]`
+- `mdkg git push --remote <name> --branch <name> [--stage-all --message <text>] [--json]`
+
+Flags:
+- `--target <path>`
+- `--branch <name>`
+- `--remote <name>`
+- `--queue-policy drain|paused`
+- `--output <path>`
+- `--stage-all`
+- `--message <text>`
+- `--json`
+
+Notes:
+- `mdkg git` is a low-level lifecycle surface, not project-memory semantic search
+- v1 uses the system Git CLI; authentication stays external through credential helpers, SSH, `gh`, CI/runtime env, or shell state
+- mdkg rejects repository refs and push remotes with embedded URL credentials; inspected remotes with userinfo are redacted before receipts are printed
+- `git inspect` is read-only and emits sanitized source descriptors plus accepted-revision hashes
+- `git clone` writes only to an empty or absent contained `--target`; use `mdkg graph clone|fork` for bundle/template graph transport
+- `git closeout` validates mdkg state and writes static JSON and Markdown receipts under `.mdkg/git/closeouts` by default
+- when the project DB participated, `git closeout` also seals `.mdkg/db/state/project.sqlite` and writes a deterministic dump
+- `git push-ready` is read-only and requires explicit remote and branch, clean worktree, passing mdkg validation, external-auth-safe remote config, and a valid DB snapshot when DB state participated
+- `git push --stage-all` writes closeout evidence, stages all changes, commits with `--message`, reruns push-ready, then pushes `HEAD` to the explicit remote branch
+- real `git push` should remain approval-gated by the calling runtime or human operator
+
+JSON receipts:
+- `inspect`: `{ action: "git.inspect", ok, root, inside_work_tree, branch, head_sha, tree_hash, remotes, status, source_descriptor, accepted_revision, warnings }`
+- `clone`: `{ action: "git.clone", ok, repository_ref, target, branch, source_descriptor, accepted_revision, inspect, warnings }`
+- `fetch`: `{ action: "git.fetch", ok, remote, branch, fetch_output, inspect, warnings }`
+- `closeout`: `{ action: "git.closeout", ok, root, output_dir, generated_at, git, validation, db_participated, db_snapshot_status, db_snapshot_seal, db_snapshot_dump, static_receipts, warnings }`
+- `push-ready`: `{ action: "git.push_ready", ok, root, remote, branch, remote_url, git, validation, db_snapshot_status, checks, warning_count, failure_count, warnings, errors }`
+- `push`: `{ action: "git.push", ok, remote, branch, head_sha, pushed_ref, stage_all, closeout, commit, push_ready, push_output, warnings }`
+
 ### `mdkg subgraph`
 
 When to use:
@@ -917,6 +982,48 @@ JSON receipts:
 - `evaluate`: `{ action: "evaluated", goal, report_only, runs_scripts, checks, completion_evidence_present }`
 - `pause|resume|done|archive`: `{ action, goal }`
 
+### `mdkg loop`
+
+When to use:
+- inspect reusable loop templates and scoped loop nodes
+- fork a reusable loop template for a concrete project scope
+- inspect loop planning state, child refs, run refs, and evidence refs without executing agents
+
+Usage:
+- `mdkg loop list [--ws <alias>] [--json]`
+- `mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--json]`
+- `mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization default_children|planning_only|manual] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--json]`
+- `mdkg loop plan <loop> [--ws <alias>] [--json]`
+- `mdkg loop next <loop> [--ws <alias>] [--json]`
+- `mdkg loop runs <loop> [--ws <alias>] [--json]`
+- `mdkg loop list [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+- `mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+- `mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization <mode>] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+- `mdkg loop plan <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+- `mdkg loop next <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+- `mdkg loop runs <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]`
+
+Behavior:
+- `loop` is one first-class node type; template, scoped fork, and run-bearing behavior is represented through metadata and links, not separate node types.
+- seed templates resolve from `.mdkg/templates/loops/<name>.loop.md`.
+- `loop list` reports indexed loop nodes plus reusable seed templates.
+- `loop show` reports either an indexed loop node or a seed template body/frontmatter.
+- `loop fork` creates a scoped loop; default materialization creates linked spike/task/test child nodes, while `planning_only` or `--no-children` creates only the scoped loop shell.
+- `loop fork --dry-run` is observational: it writes no nodes, indexes, events, or SQLite reservations, and the next real fork reuses the previewed ids.
+- forked loops retain template identity and content hash; list/show/plan report current, stale, missing-template, or unknown provenance without rewriting forks.
+- `loop plan` reports readiness state, materialization state, child/run/output refs, evidence lanes, blockers, closeout readiness, and blocker-continuation guidance without executing agents.
+- `loop next` is read-only and routes to the next actionable child, readiness lane, or blocker recovery step without claiming work.
+- `loop runs` reports linked `run_refs` and graph `evidence_refs` without executing runtime jobs.
+- mdkg defines reusable process state and graph context; omni-room-runtime or other runtimes execute agents, tools, sandboxes, traces, and model routing.
+
+JSON receipts:
+- `list`: `{ action: "listed", loops, templates, warnings }`
+- `show`: `{ action: "showed", loop, warnings }` or `{ action: "showed", template, warnings }`
+- `fork`: `{ action: "forked"|"planned", loop, template, materialization_mode, materialized_children, pending_materialization, blocker_continuation, warnings }`
+- `plan`: `{ action: "planned", loop, materialization_mode, child_refs, pending_materialization, readiness, blocker_continuation, warnings }`
+- `next`: `{ action: "selected", loop, selected, rationale, skipped, readiness, warnings }`
+- `runs`: `{ action: "listed", loop, run_refs, evidence_refs, warnings }`
+
 ### `mdkg task`
 
 When to use:

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.4.1`
+Current package version in source: `0.5.0`
 
 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.
 
@@ -242,6 +242,26 @@ Subgraph nodes are projected under the subgraph alias, for example `child_repo:t
 
 Use `mdkg graph refs <id-or-qid> --json` to inspect inbound and outbound scope, context, evidence, blocker, related, and structural links for local or read-only subgraph qids without mutating either graph.
 
+Use low-level Git lifecycle receipts when an agent run needs to close out local
+mdkg state and prove push readiness before an explicit remote update:
+
+```bash
+mdkg git inspect --json
+mdkg git clone git@github.com:org/repo.git --target worktrees/repo --branch main --json
+mdkg git fetch --remote origin --branch main --json
+mdkg git closeout --json
+mdkg git push-ready --remote origin --branch main --json
+mdkg git push --remote origin --branch main --stage-all --message "agent checkpoint" --json
+```
+
+`mdkg git` uses the system Git CLI. Authentication stays external through SSH,
+credential helpers, `gh`, CI/runtime environment, or shell state; mdkg rejects
+embedded URL credentials and records only sanitized refs, hashes, policy names,
+and receipts. `closeout` validates mdkg state before writing static JSON and
+Markdown receipts, and when the project DB participated it also seals the
+SQLite state and writes a deterministic dump. Treat real `mdkg git push` as an
+approval-gated operation in agent runtimes.
+
 Launch a local read-only MCP server when an MCP-capable agent should inspect a
 specific mdkg graph without receiving mutation tools:
 
@@ -474,10 +494,12 @@ Current source behavior:
 - `mdkg skill sync` refreshes the product-specific mirrors from canonical `.mdkg/skills/`
 - mirrored skill folders are append-focused outputs; preserve unrelated existing folders and fail on same-slug collisions unless explicitly forced
 
-This repo now dogfoods three internal skills:
+This repo now dogfoods mdkg-authored internal skills:
 - `author-mdkg-skill`
 - `select-work-and-ground-context`
 - `build-pack-and-execute-task`
+- `pursue-mdkg-goal`
+- `pursue-mdkg-loop`
 - `verify-close-and-checkpoint`
 
 Optional skill metadata with prefixes such as `ochatr_*` is treated as vendor extension data. Structured skill output exposes it under `extensions.ochatr` while keeping the top-level `ochatr` field as a compatibility alias introduced in 0.0.9. ochatr.ai is a pioneering adopter of this extension pattern, not the name of the base mdkg standard.
@@ -501,6 +523,13 @@ Fresh `mdkg init` workspaces default to `index.backend: sqlite`, which writes `.
 
 `mdkg index` still writes JSON compatibility caches (`global.json`, `skills.json`, `capabilities.json`, and subgraph projections when configured). In SQLite mode it also rebuilds the SQLite cache with nodes, edges, skills, capabilities, archive metadata, subgraphs, source hashes, and schema metadata. Deleting the SQLite file is recoverable with `mdkg index`.
 
+Graph ingestion is bounded before Markdown bodies are read. New workspaces expose
+`index.limits.max_files`, `max_file_bytes`, `max_total_bytes`, and `max_depth` in
+`.mdkg/config.json`; older configs receive the same conservative defaults in
+memory. Pack traversal and body reads are bounded before construction, ZIP input
+is bounded before allocation and inflation, and the local read-only MCP server
+rejects oversized lines, batches, nesting, bodies, tool payloads, and responses.
+
 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.
 
 ## Project DB Layout
@@ -564,6 +593,14 @@ Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after cho
 
 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.
 
+## Loop nodes
+
+Loop nodes are durable declarative process state for reusable agentic workflows. Use `mdkg new loop "<process>"` for a loop record, or `mdkg loop fork <template> --scope <scope>` to instantiate a seeded template for a concrete repo, folder, or goal.
+
+`loop` is one first-class node type. A loop can act as a reusable template, scoped fork, or run-bearing loop through metadata and links; mdkg does not create separate `loop_template` or `loop_run` node types in this release. Loop metadata records mode, scope, lineage, materialization mode, child refs, run/evidence refs, definition of done, and blocker-continuation policy.
+
+`mdkg loop list|show|plan|runs` inspect loop state without executing agents. `mdkg loop fork` creates graph state; by default it materializes linked spike/task/test child nodes, while `--planning-only` or `--no-children` creates only the scoped loop shell. mdkg defines reusable process state and graph context; omni-room-runtime or another runtime owns agent/tool execution, sandboxes, traces, and model routing.
+
 ## Research spikes
 
 Spikes are first-class actionable work nodes for research and planning. Use
@@ -630,6 +667,7 @@ This release includes:
 - 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`
+- first-class `loop` nodes and `mdkg loop list/show/fork/plan/runs`
 - optional `skills: [...]` on work items
 - pack-time skill inclusion
 - latest-checkpoint resolver + index hint