mdkg 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -8,6 +8,38 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
+## 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

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-05
+package_version_in_source: 0.4.2
 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,6 +42,7 @@ Primary commands:
 - `archive`
 - `bundle`
 - `graph`
+- `git`
 - `subgraph`
 - `work`
 - `goal`
@@ -72,6 +73,7 @@ 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 ...`.
@@ -746,6 +748,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:

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.4.2`
 
 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:
 

package/dist/cli.js

@@ -29,6 +29,7 @@ const spec_1 = require("./commands/spec");
 const archive_1 = require("./commands/archive");
 const bundle_1 = require("./commands/bundle");
 const graph_1 = require("./commands/graph");
+const git_1 = require("./commands/git");
 const subgraph_1 = require("./commands/subgraph");
 const checkpoint_1 = require("./commands/checkpoint");
 const init_1 = require("./commands/init");
@@ -76,6 +77,7 @@ function printUsage(log) {
     log("  archive     Add, list, show, verify, and compress archive sidecars");
     log("  bundle      Create, list, show, and verify full graph snapshot bundles");
     log("  graph       Clone, fork, import, and inspect mdkg graph references");
+    log("  git         Clone, fetch, inspect, close out, and push Git-backed mdkg projects");
     log("  subgraph    Register, audit, plan, sync, materialize, and verify read-only child graph snapshots");
     log("  work        Create and update work contracts, orders, receipts, and artifacts");
     log("  goal        Inspect and advance recursive goal nodes");
@@ -653,6 +655,70 @@ function printGraphHelp(log, subcommand) {
     }
     printGlobalOptions(log);
 }
+function printGitHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "inspect":
+            log("Usage:");
+            log("  mdkg git inspect [--json]");
+            log("\nNotes:");
+            log("  - read-only Git worktree, remote, branch, status, descriptor, and accepted-revision receipt");
+            log("  - remote URLs are redacted when userinfo is present");
+            break;
+        case "clone":
+            log("Usage:");
+            log("  mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]");
+            log("\nNotes:");
+            log("  - uses the system Git CLI and external Git auth");
+            log("  - --target must be empty or absent and stay inside the current repo");
+            log("  - repository refs must not embed credentials");
+            break;
+        case "fetch":
+            log("Usage:");
+            log("  mdkg git fetch [--remote <name>] [--branch <name>] [--json]");
+            log("\nNotes:");
+            log("  - defaults to remote origin");
+            log("  - auth stays external through Git credential helpers, SSH, gh, CI env, or shell state");
+            break;
+        case "closeout":
+            log("Usage:");
+            log("  mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]");
+            log("\nNotes:");
+            log("  - validates mdkg state before writing closeout receipts");
+            log("  - when the project DB participated, seals SQLite state and writes a deterministic dump");
+            log("  - writes static JSON and Markdown receipts under .mdkg/git/closeouts by default");
+            break;
+        case "push-ready":
+            log("Usage:");
+            log("  mdkg git push-ready --remote <name> --branch <name> [--json]");
+            log("\nNotes:");
+            log("  - read-only high-bar preflight for explicit Git remote/branch push");
+            log("  - requires clean worktree, valid mdkg graph, external auth boundary, and valid DB snapshot when DB state participated");
+            break;
+        case "push":
+            log("Usage:");
+            log("  mdkg git push --remote <name> --branch <name> [--json]");
+            log("  mdkg git push --remote <name> --branch <name> --stage-all --message <text> [--queue-policy drain|paused] [--json]");
+            log("\nNotes:");
+            log("  - real Git push via system Git; requires explicit remote and branch");
+            log("  - --stage-all writes closeout evidence, stages all changes, commits with --message, then runs push-ready before pushing");
+            log("  - no raw credentials, tokens, SSH keys, prompts, payloads, or provider auth are stored in receipts");
+            break;
+        default:
+            log("Usage:");
+            log("  mdkg git inspect [--json]");
+            log("  mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]");
+            log("  mdkg git fetch [--remote <name>] [--branch <name>] [--json]");
+            log("  mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]");
+            log("  mdkg git push-ready --remote <name> --branch <name> [--json]");
+            log("  mdkg git push --remote <name> --branch <name> [--stage-all --message <text>] [--json]");
+            log("\nBoundaries:");
+            log("  - mdkg git is a low-level Git lifecycle surface, not project-memory semantic search");
+            log("  - system Git is the v1 execution backend");
+            log("  - authentication stays external; mdkg records only refs, hashes, policy names, and receipts");
+            log("  - real push operations require explicit remote and branch and should be approval-gated by the caller");
+    }
+    printGlobalOptions(log);
+}
 function printSubgraphHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "add":
@@ -1179,6 +1245,9 @@ function printCommandHelp(log, command, subcommand) {
         case "graph":
             printGraphHelp(log, subcommand);
             return;
+        case "git":
+            printGitHelp(log, subcommand);
+            return;
         case "subgraph":
             printSubgraphHelp(log, subcommand);
             return;
@@ -1911,6 +1980,73 @@ function runGraphSubcommand(parsed, root) {
             throw new errors_1.UsageError("graph requires clone/fork/import-template/refs");
     }
 }
+function runGitSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    switch (subcommand) {
+        case "inspect": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git inspect does not accept positional arguments");
+            }
+            (0, git_1.runGitInspectCommand)({ root, json });
+            return 0;
+        }
+        case "clone": {
+            const repository = parsed.positionals[2];
+            if (!repository || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("git clone requires <repository-ref>");
+            }
+            const target = requireFlagValue("--target", parsed.flags["--target"]);
+            if (!target) {
+                throw new errors_1.UsageError("git clone requires --target <path>");
+            }
+            const branch = requireFlagValue("--branch", parsed.flags["--branch"]);
+            (0, git_1.runGitCloneCommand)({ root, repository, target, branch, json });
+            return 0;
+        }
+        case "fetch": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git fetch does not accept positional arguments");
+            }
+            const remote = requireFlagValue("--remote", parsed.flags["--remote"]);
+            const branch = requireFlagValue("--branch", parsed.flags["--branch"]);
+            (0, git_1.runGitFetchCommand)({ root, remote, branch, json });
+            return 0;
+        }
+        case "closeout": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git closeout does not accept positional arguments");
+            }
+            const queuePolicy = parseQueuePolicyFlag(parsed.flags["--queue-policy"]);
+            const output = requireFlagValue("--output", parsed.flags["--out"]);
+            (0, git_1.runGitCloseoutCommand)({ root, queuePolicy, output, json });
+            return 0;
+        }
+        case "push-ready": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git push-ready does not accept positional arguments");
+            }
+            const remote = requireFlagValue("--remote", parsed.flags["--remote"]);
+            const branch = requireFlagValue("--branch", parsed.flags["--branch"]);
+            (0, git_1.runGitPushReadyCommand)({ root, remote, branch, json });
+            return 0;
+        }
+        case "push": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git push does not accept positional arguments");
+            }
+            const remote = requireFlagValue("--remote", parsed.flags["--remote"]);
+            const branch = requireFlagValue("--branch", parsed.flags["--branch"]);
+            const message = requireFlagValue("--message", parsed.flags["--message"]);
+            const stageAll = parseBooleanFlag("--stage-all", parsed.flags["--stage-all"]);
+            const queuePolicy = parseQueuePolicyFlag(parsed.flags["--queue-policy"]);
+            (0, git_1.runGitPushCommand)({ root, remote, branch, message, stageAll, queuePolicy, json });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("git requires inspect/clone/fetch/closeout/push-ready/push");
+    }
+}
 function runSubgraphSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     const json = parseBooleanFlag("--json", parsed.flags["--json"]);
@@ -2747,6 +2883,8 @@ function runCommand(parsed, root, runtime) {
             return runBundleSubcommand(parsed, root);
         case "graph":
             return runGraphSubcommand(parsed, root);
+        case "git":
+            return runGitSubcommand(parsed, root);
         case "subgraph":
             return runSubgraphSubcommand(parsed, root);
         case "work":