mdkg 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -8,6 +8,64 @@ 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
+
+- Added generic contract-profile metadata for MANIFEST, WORK, WORK_ORDER, and
+  RECEIPT semantic mirrors, including `contract_profile`, policy refs,
+  `receipt_kind`, and `redaction_class` validation.
+- Added explicit profile validation through `mdkg validate --profile
+  omni-room` and `mdkg work validate --profile omni-room`, while keeping Omni
+  Room execution semantics runtime-owned.
+- Added scaffold and helper flags for contract-profile metadata across
+  `mdkg new manifest|work|work_order|receipt` and `mdkg work
+  contract|order|receipt new`.
+
+### Changed
+
+- Updated default templates, init assets, seeded skills, and generated command
+  references to demonstrate generic contract-profile fields without adding
+  runtime-only queue, provider, billing, ledger, or final-receipt state.
+- Documented the distinction between `contract_profile`, MANIFEST
+  `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.
+
 ## 0.4.0 - 2026-06-27
 
 ### Added

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
-as_of: 2026-06-27
-package_version_in_source: 0.4.0
+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 ...`.
@@ -213,6 +215,11 @@ Primary flags:
 - `--skills <slug,slug,...>`
 - `--template <set>`
 - `--run-id <id>`
+- `--contract-profile <name>` for MANIFEST, WORK, WORK_ORDER, and RECEIPT
+- `--validation-policy-ref <ref>` for MANIFEST, WORK_ORDER, and RECEIPT
+- `--evidence-policy-ref <ref>` for MANIFEST, WORK_ORDER, and RECEIPT
+- `--receipt-kind <kind>` for RECEIPT
+- `--redaction-class <class>` for RECEIPT
 - `--json`
 
 Advanced metadata flags:
@@ -741,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:
@@ -819,17 +874,17 @@ Usage:
 - `mdkg work order new|status|update ...`
 - `mdkg work receipt new|verify|update ...`
 - `mdkg work artifact add ...`
-- `mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--required-capabilities <...>] [--pricing-model <...>] [--json]`
+- `mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--contract-profile <name>] [--required-capabilities <...>] [--pricing-model <...>] [--json]`
 - `mdkg work trigger <work-or-capability-ref> [--id <order.id>] [--title "<title>"] [--requester <ref>] [--enqueue <queue>] [--json]`
-- `mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--request-ref <ref>] [--trigger-ref <ref>] [--payload-hash <sha256:...>] [--input-refs <...>] [--queue-refs <...>] [--requested-outputs <...>] [--json]`
+- `mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--contract-profile <name>] [--validation-policy-ref <ref>] [--evidence-policy-ref <ref>] [--request-ref <ref>] [--trigger-ref <ref>] [--payload-hash <sha256:...>] [--input-refs <...>] [--queue-refs <...>] [--requested-outputs <...>] [--json]`
 - `mdkg work order status <id-or-qid> [--json]`
 - `mdkg work order update <id-or-qid> [--status <status>] [--add-input-refs <...>] [--add-queue-refs <...>] [--add-artifacts <...>] [--json]`
-- `mdkg work receipt new "<title>" --id <receipt.id> --work-order-id <order.id> --outcome success|partial|failure [--receipt-status recorded|verified|rejected|superseded] [--redaction-policy refs_and_hashes_only|redacted_summary|external_private] [--evidence-hashes <sha256:...>] [--json]`
+- `mdkg work receipt new "<title>" --id <receipt.id> --work-order-id <order.id> --outcome success|partial|failure [--receipt-status recorded|verified|rejected|superseded] [--redaction-policy refs_and_hashes_only|redacted_summary|external_private] [--contract-profile <name>] [--receipt-kind <kind>] [--redaction-class <class>] [--validation-policy-ref <ref>] [--evidence-policy-ref <ref>] [--evidence-hashes <sha256:...>] [--json]`
 - `mdkg work receipt verify <id-or-qid> [--json]`
 - `mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--add-evidence-hashes <sha256:...>] [--json]`
 - `mdkg work artifact add <order-or-receipt-id-or-qid> <file> [--id <archive.id>] [--kind source|artifact] [--json]`
-- `mdkg work validate [<id-or-qid>] [--type <workflow-type>] [--json]`
-- `mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]`
+- `mdkg work validate [<id-or-qid>] [--type <workflow-type>] [--profile <name>] [--json]`
+- `mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--profile <name>] [--json]`
 
 Notes:
 - work commands mutate semantic mirror files only
@@ -840,10 +895,13 @@ Notes:
 - example: `mdkg work trigger work.example --id order.example-1 --requester user://example --json`
 - `work trigger --enqueue <queue>` requires a valid project DB plus an explicitly created active queue, creates a submitted order mirror, and enqueues a local delivery message without executing work
 - `work order new` accepts URI-style requester/request/trigger refs, archive input refs, optional queue refs, and stable payload hashes
+- `work order new` accepts optional contract-profile and validation/evidence policy refs without executing work
 - `work order status` is read-only and reports deterministic order state plus linked receipts
 - `work receipt new` accepts URI-style cost/proof/attestation refs, explicit redaction policy, and SHA-256 evidence/input/output hash refs
+- `work receipt new` accepts optional contract-profile, receipt-kind, redaction-class, and validation/evidence policy refs without becoming canonical runtime receipt state
 - `work receipt verify` is read-only and reports linkage, evidence, archive ref, hash, outcome, and redaction-policy checks; invalid receipts print JSON before exiting nonzero
 - `work validate` is read-only and reports typed diagnostics for MANIFEST.md, legacy SPEC.md, WORK.md, WORK_ORDER.md, RECEIPT.md, FEEDBACK.md, DISPUTE.md, and PROPOSAL.md mirrors; obvious raw secret, prompt, token, or payload markers are warnings, not hard failures
+- `work validate --profile omni-room` applies explicit contract-profile validation after generic mirror validation; it is separate from `mdkg pack --profile`
 - `work artifact add` calls `mdkg archive add`, then attaches the resulting `archive://...` ref to the target order or receipt
 - `work order update`, `work receipt update`, and `work artifact add` accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace
 
@@ -990,10 +1048,11 @@ When to use:
 - run the repo trust gate before calling work done
 
 Usage:
-- `mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]`
+- `mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--profile <name>] [--json]`
 - `--changed-only` filters warning presentation to changed `.mdkg` files while full graph errors still run
 - `--summary` emits bounded warning samples for agent/CI logs; `--limit <n>` controls the sample size
 - `--out <path>` writes the compatibility text report; `--json-out <path>` writes a clean full JSON receipt
+- `--profile omni-room` applies explicit contract-profile validation after generic validation; it is separate from `mdkg pack --profile`
 - JSON receipts include `warning_summary` and `warning_diagnostics` with warning ids, categories, severity, paths, refs, and remediation text
 
 Flags:
@@ -1003,10 +1062,11 @@ Flags:
 - `--changed-only`
 - `--summary`
 - `--limit <n>`
+- `--profile <name>`
 - `--json`
 
 JSON receipt:
-- `{ action: "validated", ok, warning_count, error_count, warnings, warning_diagnostics, warning_summary, errors, report_path?, json_receipt_path? }`
+- `{ action: "validated", ok, warning_count, error_count, warnings, warning_diagnostics, warning_summary, errors, validation_profile?, report_path?, json_receipt_path? }`
 - `report_path` is included only when `--out` is used.
 - `json_receipt_path` is included only when `--json-out` is used.
 

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.0`
+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:
 
@@ -600,7 +620,11 @@ Use `mdkg new manifest|work|work_order|receipt|feedback|dispute|proposal "<title
 
 Relational templates contain editable placeholder refs. `manifest` and `work` scaffold as validation-clean standalone docs; `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
 
-For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. `mdkg work trigger` creates a deterministic submitted `WORK_ORDER.md` from a WORK contract or a MANIFEST with exactly one resolvable work contract; legacy SPEC refs remain supported during the compatibility bridge. `mdkg work order status` and `mdkg work receipt verify` are read-only review helpers for deterministic closeout. `mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] --json` is a read-only focused validator for agent workflow mirrors; it returns typed diagnostics and warns on obvious raw secret, prompt, token, or payload markers. `mdkg work trigger --enqueue <queue>` optionally writes a local project DB queue delivery message after the queue has been explicitly created and is active; it still does not execute work. Production order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
+For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. `mdkg work trigger` creates a deterministic submitted `WORK_ORDER.md` from a WORK contract or a MANIFEST with exactly one resolvable work contract; legacy SPEC refs remain supported during the compatibility bridge. `mdkg work order status` and `mdkg work receipt verify` are read-only review helpers for deterministic closeout. `mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--profile omni-room] --json` is a read-only focused validator for agent workflow mirrors; it returns typed diagnostics and warns on obvious raw secret, prompt, token, or payload markers. `mdkg validate --profile omni-room` and `mdkg work validate --profile omni-room` apply explicit profile checks after generic validation.
+
+Optional contract-profile fields are generic semantic mirrors, not runtime execution state. `contract_profile` is accepted on MANIFEST, WORK, WORK_ORDER, and RECEIPT surfaces; `validation_policy_ref` and `evidence_policy_ref` are accepted on MANIFEST, WORK_ORDER, and RECEIPT; `receipt_kind` and `redaction_class` are RECEIPT-only. These fields are separate from MANIFEST `resource_profile`, WORK `kind`, WORK_ORDER `artifact_policy`, RECEIPT `redaction_policy`, and pack/bundle `--profile` flags. Generic validation accepts well-shaped custom profile, kind, and class values with warnings; explicit `--profile omni-room` validation escalates unknown or incompatible values. Bare `profile` is intentionally ambiguous and is diagnosed rather than treated as an alias.
+
+`mdkg work trigger --enqueue <queue>` optionally writes a local project DB queue delivery message after the queue has been explicitly created and is active; it still does not execute work. Production order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Omni Room and other downstream runtimes own runtime policy, queue execution, final receipt normalization, and downstream adoption. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
 
 ## Archive sidecars
 

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");
@@ -160,6 +162,11 @@ function printNewHelp(log) {
     log("  --skills <slug,slug,...>   Skill slugs for work items");
     log("  --template <set>           Template set");
     log("  --run-id <id>              Optional event run id when event logging is enabled");
+    log("  --contract-profile <name>  Optional MANIFEST/WORK/WORK_ORDER/RECEIPT validation profile metadata");
+    log("  --validation-policy-ref <ref> Optional MANIFEST/WORK_ORDER/RECEIPT validation policy ref");
+    log("  --evidence-policy-ref <ref> Optional MANIFEST/WORK_ORDER/RECEIPT evidence policy ref");
+    log("  --receipt-kind <kind>      Optional RECEIPT kind metadata");
+    log("  --redaction-class <class>  Optional RECEIPT redaction class metadata");
     log("\nAdvanced metadata flags:");
     log("  --parent --prev --next --relates --blocked-by --blocks");
     log("  --links --artifacts --refs --aliases --owners --cases --supersedes");
@@ -648,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":
@@ -733,7 +804,7 @@ function printWorkHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "contract":
             log("Usage:");
-            log('  mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--required-capabilities <...>] [--pricing-model <...>] [--json]');
+            log('  mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--contract-profile <name>] [--required-capabilities <...>] [--pricing-model <...>] [--json]');
             break;
         case "trigger":
             log("Usage:");
@@ -747,7 +818,7 @@ function printWorkHelp(log, subcommand) {
             break;
         case "order":
             log("Usage:");
-            log('  mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--request-ref <ref>] [--trigger-ref <ref>] [--payload-hash <sha256:...>] [--input-refs <...>] [--queue-refs <...>] [--requested-outputs <...>] [--json]');
+            log('  mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--contract-profile <name>] [--validation-policy-ref <ref>] [--evidence-policy-ref <ref>] [--request-ref <ref>] [--trigger-ref <ref>] [--payload-hash <sha256:...>] [--input-refs <...>] [--queue-refs <...>] [--requested-outputs <...>] [--json]');
             log("  mdkg work order status <id-or-qid> [--json]");
             log("  mdkg work order update <id-or-qid> [--status <status>] [--add-input-refs <...>] [--add-queue-refs <...>] [--add-artifacts <...>] [--json]");
             log("\nNotes:");
@@ -755,7 +826,7 @@ function printWorkHelp(log, subcommand) {
             break;
         case "receipt":
             log("Usage:");
-            log('  mdkg work receipt new "<title>" --id <receipt.id> --work-order-id <order.id> --outcome success|partial|failure [--receipt-status recorded|verified|rejected|superseded] [--redaction-policy refs_and_hashes_only|redacted_summary|external_private] [--evidence-hashes <sha256:...>] [--json]');
+            log('  mdkg work receipt new "<title>" --id <receipt.id> --work-order-id <order.id> --outcome success|partial|failure [--receipt-status recorded|verified|rejected|superseded] [--redaction-policy refs_and_hashes_only|redacted_summary|external_private] [--contract-profile <name>] [--receipt-kind <kind>] [--redaction-class <class>] [--validation-policy-ref <ref>] [--evidence-policy-ref <ref>] [--evidence-hashes <sha256:...>] [--json]');
             log("  mdkg work receipt verify <id-or-qid> [--json]");
             log("  mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--add-evidence-hashes <sha256:...>] [--json]");
             log("\nNotes:");
@@ -767,10 +838,11 @@ function printWorkHelp(log, subcommand) {
             break;
         case "validate":
             log("Usage:");
-            log("  mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]");
+            log("  mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--profile <name>] [--json]");
             log("\nNotes:");
             log("  Read-only focused validation for agent workflow mirrors.");
             log("  Reports typed diagnostics for MANIFEST.md, legacy SPEC.md, WORK.md, WORK_ORDER.md, RECEIPT.md, FEEDBACK.md, DISPUTE.md, and PROPOSAL.md files.");
+            log("  --profile omni-room applies explicit contract-profile validation after generic mirror validation; this is separate from mdkg pack --profile.");
             log("  Obvious raw secret, prompt, token, or payload markers are warnings so humans and agents can review boundaries.");
             break;
         default:
@@ -780,7 +852,7 @@ function printWorkHelp(log, subcommand) {
             log("  mdkg work order new|status|update ...");
             log("  mdkg work receipt new|verify|update ...");
             log("  mdkg work artifact add ...");
-            log("  mdkg work validate [<id-or-qid>] [--type <workflow-type>] [--json]");
+            log("  mdkg work validate [<id-or-qid>] [--type <workflow-type>] [--profile <name>] [--json]");
             log("\nNotes:");
             log("  - work commands mutate semantic mirror files only");
             log("  - work validate is read-only and reports typed workflow diagnostics");
@@ -972,10 +1044,11 @@ function printCheckpointHelp(log) {
 }
 function printValidateHelp(log) {
     log("Usage:");
-    log("  mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]");
+    log("  mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--profile <name>] [--json]");
     log("\nNotes:");
     log("  Validates frontmatter schemas, graph references, visibility, skills, and events.");
     log("  --changed-only filters warning presentation to changed .mdkg files while full graph errors still run.");
+    log("  --profile omni-room applies explicit contract-profile validation after generic validation; this is separate from mdkg pack --profile.");
     log("  JSON output includes warning_summary plus warning_diagnostics with warning ids, categories, severity, paths, refs, and remediation text.");
     log("  --summary emits bounded warning samples for agent/CI logs; --limit controls the sample size.");
     log("  --out writes the compatibility text report; --json-out writes a clean full JSON receipt.");
@@ -1172,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;
@@ -1904,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"]);
@@ -2063,7 +2206,8 @@ function runWorkSubcommand(parsed, root) {
             throw new errors_1.UsageError("work validate accepts at most one workflow reference");
         }
         const type = requireFlagValue("--type", parsed.flags["--type"]);
-        (0, work_1.runWorkValidateCommand)({ root, ws, id, type, json });
+        const profile = requireFlagValue("--profile", parsed.flags["--pack-profile"]);
+        (0, work_1.runWorkValidateCommand)({ root, ws, id, type, profile, json });
         return 0;
     }
     if (domain === "contract" && action === "new") {
@@ -2078,6 +2222,7 @@ function runWorkSubcommand(parsed, root) {
         }
         const requiredCapabilities = requireFlagValue("--required-capabilities", parsed.flags["--required-capabilities"]);
         const pricingModel = requireFlagValue("--pricing-model", parsed.flags["--pricing-model"]);
+        const contractProfile = requireFlagValue("--contract-profile", parsed.flags["--contract-profile"]);
         (0, work_1.runWorkContractNewCommand)({
             root,
             ws,
@@ -2089,6 +2234,7 @@ function runWorkSubcommand(parsed, root) {
             outputs,
             requiredCapabilities,
             pricingModel,
+            contractProfile,
             json,
         });
         return 0;
@@ -2108,6 +2254,9 @@ function runWorkSubcommand(parsed, root) {
         const queueRefs = requireFlagValue("--queue-refs", parsed.flags["--queue-refs"]);
         const requestedOutputs = requireFlagValue("--requested-outputs", parsed.flags["--requested-outputs"]);
         const constraintRefs = requireFlagValue("--constraint-refs", parsed.flags["--constraint-refs"]);
+        const contractProfile = requireFlagValue("--contract-profile", parsed.flags["--contract-profile"]);
+        const validationPolicyRef = requireFlagValue("--validation-policy-ref", parsed.flags["--validation-policy-ref"]);
+        const evidencePolicyRef = requireFlagValue("--evidence-policy-ref", parsed.flags["--evidence-policy-ref"]);
         (0, work_1.runWorkOrderNewCommand)({
             root,
             ws,
@@ -2122,6 +2271,9 @@ function runWorkSubcommand(parsed, root) {
             queueRefs,
             requestedOutputs,
             constraintRefs,
+            contractProfile,
+            validationPolicyRef,
+            evidencePolicyRef,
             json,
         });
         return 0;
@@ -2163,6 +2315,11 @@ function runWorkSubcommand(parsed, root) {
         const evidenceHashes = requireFlagValue("--evidence-hashes", parsed.flags["--evidence-hashes"]);
         const inputHashes = requireFlagValue("--input-hashes", parsed.flags["--input-hashes"]);
         const outputHashes = requireFlagValue("--output-hashes", parsed.flags["--output-hashes"]);
+        const contractProfile = requireFlagValue("--contract-profile", parsed.flags["--contract-profile"]);
+        const receiptKind = requireFlagValue("--receipt-kind", parsed.flags["--receipt-kind"]);
+        const redactionClass = requireFlagValue("--redaction-class", parsed.flags["--redaction-class"]);
+        const validationPolicyRef = requireFlagValue("--validation-policy-ref", parsed.flags["--validation-policy-ref"]);
+        const evidencePolicyRef = requireFlagValue("--evidence-policy-ref", parsed.flags["--evidence-policy-ref"]);
         (0, work_1.runWorkReceiptNewCommand)({
             root,
             ws,
@@ -2173,6 +2330,11 @@ function runWorkSubcommand(parsed, root) {
             receiptStatus,
             costRef,
             redactionPolicy,
+            contractProfile,
+            receiptKind,
+            redactionClass,
+            validationPolicyRef,
+            evidencePolicyRef,
             artifacts,
             proofRefs,
             attestationRefs,
@@ -2657,6 +2819,11 @@ function runCommand(parsed, root, runtime) {
             const owners = requireFlagValue("--owners", parsed.flags["--owners"]);
             const supersedes = requireFlagValue("--supersedes", parsed.flags["--supersedes"]);
             const template = requireFlagValue("--template", parsed.flags["--template"]);
+            const contractProfile = requireFlagValue("--contract-profile", parsed.flags["--contract-profile"]);
+            const validationPolicyRef = requireFlagValue("--validation-policy-ref", parsed.flags["--validation-policy-ref"]);
+            const evidencePolicyRef = requireFlagValue("--evidence-policy-ref", parsed.flags["--evidence-policy-ref"]);
+            const receiptKind = requireFlagValue("--receipt-kind", parsed.flags["--receipt-kind"]);
+            const redactionClass = requireFlagValue("--redaction-class", parsed.flags["--redaction-class"]);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
@@ -2686,6 +2853,11 @@ function runCommand(parsed, root, runtime) {
                 owners,
                 supersedes,
                 template,
+                contractProfile,
+                validationPolicyRef,
+                evidencePolicyRef,
+                receiptKind,
+                redactionClass,
                 noCache,
                 noReindex,
                 runId,
@@ -2711,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":
@@ -2951,8 +3125,9 @@ function runCommand(parsed, root, runtime) {
             const changedOnly = parseBooleanFlag("--changed-only", parsed.flags["--changed-only"]);
             const summary = parseBooleanFlag("--summary", parsed.flags["--summary"]);
             const limit = parseNumberFlag("--limit", parsed.flags["--limit"]);
+            const profile = requireFlagValue("--profile", parsed.flags["--pack-profile"]);
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
-            (0, validate_1.runValidateCommand)({ root, out, jsonOut, quiet, json, changedOnly, summary, limit });
+            (0, validate_1.runValidateCommand)({ root, out, jsonOut, quiet, json, changedOnly, summary, limit, profile });
             return 0;
         }
         case "status": {