mdkg 0.2.0 → 0.3.1

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.2.0",
+  "mdkg_version": "0.3.1",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "14ba3fa0657a43345ae81631024519955868fa34081b7517cb253b0be96cf163"
+      "sha256": "0661196763bf05681523a576fcd0a29138ccc36df4f48dad7ba16a1f4b7b0418"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -151,7 +151,7 @@
     {
       "path": ".mdkg/templates/default/receipt.md",
       "category": "template",
-      "sha256": "f08753cc38e02d73a5df92df58c2d34b0d33749b298eeb31d81aa019c38d43dd"
+      "sha256": "516faf98abe421f154d162b18006c7875f1a0025ac4d35cc16df744c13548d9d"
     },
     {
       "path": ".mdkg/templates/default/rule.md",
@@ -161,7 +161,7 @@
     {
       "path": ".mdkg/templates/default/spec.md",
       "category": "template",
-      "sha256": "e3e05d8d627c478d2757451f61b5a8fda8a75da9885a9261b2f8f5cb8a3a36dc"
+      "sha256": "8c96e0b6dafa65acb83a2d84519e05a7354896aec8991c148650e9ec58196c77"
     },
     {
       "path": ".mdkg/templates/default/task.md",
@@ -176,12 +176,12 @@
     {
       "path": ".mdkg/templates/default/work_order.md",
       "category": "template",
-      "sha256": "6ee6007674f30f88153ce79ed67d8c736b4f0998ceb0c8314a3f2cf9c48ac88c"
+      "sha256": "5fe376413035f2afe406d13491a597f103a2fce29d137951fe55ae042a1082f5"
     },
     {
       "path": ".mdkg/templates/default/work.md",
       "category": "template",
-      "sha256": "9d8b971ded7a587105fb8b14bb79f68b612fa6e1962cf06859bab82e2aee57c7"
+      "sha256": "cfc53d3be1d2c31576448d071a579bc3d5d2f6851755e29c20825f6b6764c0aa"
     },
     {
       "path": ".mdkg/templates/skills/base.SKILL.md",
@@ -191,57 +191,57 @@
     {
       "path": ".mdkg/templates/specs/agent.SPEC.md",
       "category": "template",
-      "sha256": "6facd5a424fa91d23f7df3e357c98ca4d31691410fad024d5bc8ff3781b0f571"
+      "sha256": "dab10c0ed12aa10a752ee3bd61f263065644826eb950c71a9e3458673edb0ca5"
     },
     {
       "path": ".mdkg/templates/specs/api.SPEC.md",
       "category": "template",
-      "sha256": "42f6119478241a3c7dd12a2a25bd03b30d9c2bc60528287136ea044f20b215c4"
+      "sha256": "aee86cadcca31a5a015d7e15ad7503c4aa30f2af0079ec03f857b82b3ecbae59"
     },
     {
       "path": ".mdkg/templates/specs/base.SPEC.md",
       "category": "template",
-      "sha256": "cff1ee53e9369184e2d92194f165f131254d4439bc79bcbbaaae4a13d616c97b"
+      "sha256": "6d4171fac00c2f3d8f2a2ac746b8a47c59aaecebe224c3a0046dd6e6974a1d08"
     },
     {
       "path": ".mdkg/templates/specs/capability.SPEC.md",
       "category": "template",
-      "sha256": "755c24dea04f687da4714d0a12489e1ae36c5f17b838c2e24bb993378a7d9510"
+      "sha256": "68a91e8bbd80d1ff1972e4c31e29f26451d5a1be1d25d414170fdd670010066f"
     },
     {
       "path": ".mdkg/templates/specs/integration.SPEC.md",
       "category": "template",
-      "sha256": "990005a805bc6e6397f03e0de1ca69d536ae9d55719782a3075781289b44b941"
+      "sha256": "e907ce6ebc1fa5a455e31e39036e3f8699dccb3d9e45288c8ea025eaec4ca4a2"
     },
     {
       "path": ".mdkg/templates/specs/model.SPEC.md",
       "category": "template",
-      "sha256": "eb73ed195139cf5655ba70c948aaaa28fc2c85d2db1b6258d703f10e73bf3713"
+      "sha256": "56061a241819dfda4d3022c075f744cf6650f5f52c58cd15b0af9d1f613af4f2"
     },
     {
-      "path": ".mdkg/templates/specs/omniruntime-agent.SPEC.md",
+      "path": ".mdkg/templates/specs/project.SPEC.md",
       "category": "template",
-      "sha256": "343c7c148faae0c2b24364c276ce345757b5725a750cfebeee4cdeb3dde55009"
+      "sha256": "386c41852cbb46e7a6ba583a7b0c4126262a56618d8e214aaa601b68d55818b9"
     },
     {
-      "path": ".mdkg/templates/specs/project.SPEC.md",
+      "path": ".mdkg/templates/specs/runtime-agent.SPEC.md",
       "category": "template",
-      "sha256": "5ade0aa05907b9ec418c41ee051493d8ecc8ad3d45608ab74fc3cbe2974e79a4"
+      "sha256": "53af7c3e172f5ed1297f340aca0be5e53302613d2e6bb9145915067d7b0004c8"
     },
     {
       "path": ".mdkg/templates/specs/runtime-image.SPEC.md",
       "category": "template",
-      "sha256": "24c1b2fb0bd0d63bbce41ee36b43f9edf531b26438bca2706ad1ab556eaabbf0"
+      "sha256": "37416b045cd7733d1f5e1cc629ac9b6616024d5fa52f2bdcd90110267151e593"
     },
     {
       "path": ".mdkg/templates/specs/tool.SPEC.md",
       "category": "template",
-      "sha256": "18340481891bba180dd077d82b86248ede885131fb75675b775ea0c3749ee5c0"
+      "sha256": "05b827bbce4f721ea25beda62850688aff3db644aec65e71b9cf76cad8e5f46f"
     },
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "5948ed5222b2cbce0468191d00287ce5dbc1aaa434640f4daa676afb92d48d4b"
+      "sha256": "cf58e37c72be2593f1d920520dbdc6e316182bfda5c49837443a8b18024504c7"
     },
     {
       "path": "AGENTS.md",
@@ -256,7 +256,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "baf9792f0bd50ce44de2dc16babc73f631a1191acff853fdc4caa7d452f50561"
+      "sha256": "a9a7133e5a7c9a07a6814c679d04637370ea144eac19a6500980a37a2c4199f5"
     },
     {
       "path": "llms.txt",

package/dist/init/templates/default/receipt.md

@@ -7,8 +7,10 @@ work_order_id: order.example
 receipt_status: recorded
 outcome: success
 cost_ref: cost.redacted
+redaction_policy: refs_and_hashes_only
 proof_refs: []
 attestation_refs: []
+evidence_hashes: []
 input_hashes: []
 output_hashes: []
 tags: []
@@ -38,7 +40,16 @@ archive sidecars.
 
 # Proof
 
-Record non-secret proof, attestation, and hash references.
+Record non-secret proof, attestation, and hash references. `evidence_hashes`
+can hash receipt evidence bundles or redacted proof summaries that are not
+stored directly in this file.
+
+# Redaction
+
+`redaction_policy` records how this mirror avoids raw secrets and canonical
+runtime state. Use refs, hashes, archive refs, artifact refs, and redacted
+summaries instead of credentials, auth headers, live payment state, ledger
+mutations, marketplace inventory, or production runtime state.
 
 # Notes
 

package/dist/init/templates/default/spec.md

@@ -3,8 +3,9 @@ id: {{id}}
 type: spec
 title: {{title}}
 version: 0.1.0
-role: subagent
-runtime_mode: room_orchestrated
+spec_kind: capability
+role: tool_service
+runtime_mode: tool_service
 work_contracts: []
 requested_capabilities: []
 skill_refs: []
@@ -13,7 +14,7 @@ model_refs: []
 wasm_component_refs: []
 runtime_image_refs: []
 subagent_refs: []
-resource_profile: builder
+resource_profile: local_cli
 update_policy: manual
 tags: []
 owners: []
@@ -28,11 +29,11 @@ updated: {{updated}}
 
 # Purpose
 
-Define the agent, package, or runtime specification.
+Define the reusable capability surface.
 
 # Runtime
 
-Describe role, runtime mode, resource profile, and update policy.
+Describe the role, runtime mode, resource profile, and update policy.
 
 # Work Contracts
 
@@ -40,4 +41,5 @@ List related WORK.md contracts.
 
 # Capabilities
 
-List requested capabilities and relevant constraints.
+List requested capabilities and the authority/resource constraints that govern
+use.

package/dist/init/templates/default/work.md

@@ -6,7 +6,7 @@ version: 0.1.0
 agent_id: agent.example
 kind: generic
 pricing_model: quoted
-required_capabilities: []
+required_capabilities: [capability.example]
 skill_refs: []
 tool_refs: []
 model_refs: []
@@ -31,6 +31,10 @@ updated: {{updated}}
 
 Describe the reusable capability contract.
 
+Replace `capability.example` with at least one concrete required capability or
+add an explicit dependency ref such as `skill_refs`, `tool_refs`, `model_refs`,
+`wasm_component_refs`, `runtime_image_refs`, or `subagent_refs`.
+
 This file is a semantic mirror for discovery and review. Do not store raw
 secrets, credentials, live payment state, ledger mutations, marketplace
 inventory, or canonical execution state here.

package/dist/init/templates/default/work_order.md

@@ -8,7 +8,10 @@ work_version: 0.1.0
 requester: user.example
 order_status: submitted
 request_ref: request.example
+trigger_ref: trigger.manual
+payload_hash: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
 input_refs: []
+queue_refs: []
 requested_outputs: [result:text:required]
 constraint_refs: []
 artifact_policy: commit_sidecar_and_zip
@@ -27,6 +30,9 @@ updated: {{updated}}
 
 Capture the concrete request against a WORK.md version.
 
+`payload_hash` should be the stable sha256 of the redacted trigger payload or
+request mirror used to create this order.
+
 This file is a committed semantic mirror, not the canonical execution database.
 Do not store raw secrets, credentials, live payment state, ledger mutations,
 marketplace inventory, or bulky payloads here.
@@ -37,6 +43,11 @@ Record committed input references without secrets. Use `archive://...` for mdkg
 archive sidecars and `artifact://...` for external or runtime-managed artifact
 identities.
 
+# Queue refs
+
+Queue refs are optional delivery-state pointers. They are not canonical runtime
+state.
+
 # Requested Outputs
 
 Document the output descriptors requested from the work contract.

package/dist/init/templates/specs/agent.SPEC.md

@@ -1,16 +1,37 @@
 ---
 extends: base.SPEC.md
 template_kind: agent
+spec_kind: agent
 ---
 
 # Agent Role
 
 Define the durable agent role and trigger conditions.
 
+Suggested generic roles:
+
+- orchestrator agent.
+- worker agent.
+- reviewer agent.
+- summarizer agent.
+- graph/project agent.
+
+# Trigger Conditions
+
+- Human request.
+- Graph work item.
+- Queue event.
+- Scheduled check.
+- API or runtime event.
+
 # Allowed Resources
 
 - Resources the agent may read or write.
 
+# Allowed Capabilities
+
+- Capability ids and optional generic capability URIs.
+
 # Forbidden Actions
 
 - Actions this agent must never perform.
@@ -27,13 +48,33 @@ Define the durable agent role and trigger conditions.
 
 - Attempt, validation, and final evidence requirements.
 
+# Queue / Event Semantics
+
+- Accepted trigger events.
+- AgentRun claim rules.
+- AttemptReceipt requirements.
+- ValidationReceipt requirements.
+- FinalReceipt requirements.
+
+# Single-Writer Policy
+
+- The graph, repo, path, branch, queue, or work item key that serializes writes.
+
 # Escalation Behavior
 
 - When to stop, ask, or return a blocker.
 
+# Failure Modes
+
+- Ambiguous scope.
+- Conflicting writers.
+- Invalid or stale context.
+- Validation failure.
+- Missing final receipt.
+
 # Projection Targets
 
-- `.codex/agents` TOML
-- future OmniRuntime AgentManifest
-- future OmniTx capability object
-- future OmniPL agent definition
+- Tool-specific agent manifest.
+- Future runtime agent manifest.
+- Future workflow/runtime capability object.
+- Future workflow/runtime agent definition.

package/dist/init/templates/specs/api.SPEC.md

@@ -1,6 +1,7 @@
 ---
 extends: base.SPEC.md
 template_kind: api
+spec_kind: api
 ---
 
 # Service Name

package/dist/init/templates/specs/base.SPEC.md

@@ -3,8 +3,9 @@ id: {{spec_id}}
 type: spec
 title: {{title}}
 version: 0.1.0
-role: subagent
-runtime_mode: room_orchestrated
+spec_kind: capability
+role: {{role}}
+runtime_mode: {{runtime_mode}}
 work_contracts: []
 requested_capabilities: []
 skill_refs: []
@@ -34,21 +35,40 @@ Name, stable id, owner, status, and source mdkg nodes.
 
 What durable capability or contract this SPEC defines.
 
-# Scope
+# Authority Boundary
 
-Included behavior and resources.
+Who or what is allowed to make decisions, mutate state, delegate work, or accept
+evidence under this SPEC.
 
-# Non-goals
+# Resource Boundary
 
-What this SPEC explicitly does not define.
+Included behavior, resources, paths, graph nodes, queues, services, and
+explicit non-authorities.
 
-# Resource URIs
+# Optional Resource URIs
 
-- Optional draft URI: `omni://resource/...`
+- Optional generic draft URI: `resource://...`
+- Optional mdkg draft URI: `mdkg://resource/...`
 
 # Capabilities
 
-- Capability id and optional draft URI: `omni://capability/...`
+- Capability id:
+- Optional generic draft URI: `capability://...`
+- Optional mdkg draft URI: `mdkg://capability/...`
+
+# Queue / Event Semantics
+
+- Trigger events accepted:
+- Queue ownership:
+- Retry, ack, fail, and dead-letter expectations:
+- Ordering or idempotency rules:
+
+# Single-Writer Policy
+
+- Writer key:
+- Allowed write surfaces:
+- Forbidden write surfaces:
+- Conflict handling:
 
 # Inputs
 
@@ -58,13 +78,21 @@ What this SPEC explicitly does not define.
 
 - Required output or receipt contract.
 
+# Receipts / Evidence
+
+- Attempt evidence:
+- Validation evidence:
+- Final receipt or closeout evidence:
+- Aggregate checkpoint policy:
+
 # Dependencies
 
 - Other specs, skills, tools, models, services, or runtime images.
 
-# Security Boundaries
+# Security / Privacy
 
 - Authority, secret, data, and mutation boundaries.
+- No raw secrets, credentials, local auth state, or production controls.
 
 # Validation Checks
 
@@ -76,11 +104,16 @@ What this SPEC explicitly does not define.
 
 # Projection Targets
 
-- `.codex/agents`, runtime manifest, package, API, or protocol projection.
+- Runtime manifest, package metadata, API contract, tool manifest, or protocol
+  projection.
 
 # Versioning
 
-- Compatibility and change policy.
+- Compatibility rules.
+
+# Change Policy
+
+- Who can change this SPEC and what validation is required.
 
 # Open Questions
 

package/dist/init/templates/specs/capability.SPEC.md

@@ -1,24 +1,32 @@
 ---
 extends: base.SPEC.md
 template_kind: capability
+spec_kind: capability
 ---
 
 # Capability Name
 
 Stable mdkg capability id.
 
-# Draft Omni URI
+# Optional Capability URI
 
-Optional: `omni://capability/...`
+Optional generic URI: `capability://...`
+
+Optional mdkg URI: `mdkg://capability/...`
 
 # Resource Types
 
-- Optional draft resource URI: `omni://resource/...`
+- Optional generic resource URI: `resource://...`
+- Optional mdkg resource URI: `mdkg://resource/...`
 
 # Allowed Principals
 
 - Roles or agents allowed to use this capability.
 
+# Required Policy Context
+
+- Preconditions, policy refs, scopes, or approval state required before use.
+
 # Delegation Rules
 
 - Whether and how the capability can be delegated.
@@ -30,3 +38,8 @@ Optional: `omni://capability/...`
 # Audit Events
 
 - Receipts, summaries, or metrics created by use.
+
+# Validation Checks
+
+- Checks that prove capability use remains inside its authority and resource
+  boundaries.

package/dist/init/templates/specs/integration.SPEC.md

@@ -1,6 +1,7 @@
 ---
 extends: base.SPEC.md
 template_kind: integration
+spec_kind: integration
 ---
 
 # Integration Boundary

package/dist/init/templates/specs/model.SPEC.md

@@ -1,6 +1,7 @@
 ---
 extends: base.SPEC.md
 template_kind: model
+spec_kind: model
 ---
 
 # Model Identity

package/dist/init/templates/specs/project.SPEC.md

@@ -1,6 +1,7 @@
 ---
 extends: base.SPEC.md
 template_kind: project
+spec_kind: project_service
 ---
 
 # Project Role
@@ -15,7 +16,19 @@ Describe the repo/service responsibility and non-authorities.
 
 # Owned Capabilities
 
-- Capability ids and optional draft Omni URIs.
+- Capability ids and optional generic capability URIs.
+
+# Project-Agent Boundary
+
+- Graph writes owned by this project.
+- Read-only surfaces exposed to parent or sibling orchestrators.
+- Queue/event surfaces accepted from external orchestrators.
+
+# Single-Writer Policy
+
+- Project writer key.
+- Branch or graph write policy.
+- Accepted receipt before external refresh.
 
 # Integration Boundaries
 

package/dist/init/templates/specs/{omniruntime-agent.SPEC.md → runtime-agent.SPEC.md}

@@ -1,6 +1,7 @@
 ---
 extends: agent.SPEC.md
-template_kind: omniruntime_agent
+template_kind: runtime_agent
+spec_kind: runtime_agent
 ---
 
 # Queue Ownership
@@ -9,7 +10,8 @@ template_kind: omniruntime_agent
 
 # Trigger Kinds
 
-- User message, scheduled job, API event, mdkg queue event, or internal retry.
+- User message, scheduled job, API event, mdkg queue event, runtime event, or
+  internal retry.
 
 # Sandbox Requirements
 
@@ -23,8 +25,10 @@ template_kind: omniruntime_agent
 
 - Repo, graph, branch, or room keys that serialize writes.
 
-# Receipts
+# Receipt Lifecycle
 
+- TriggerEvent contract.
+- AgentRun contract.
 - AttemptReceipt contract.
 - ValidationReceipt contract.
 - FinalReceipt contract.
@@ -37,3 +41,9 @@ template_kind: omniruntime_agent
 
 - Aggregate-safe stats and improvement proposals only unless a runtime spec says
   otherwise.
+
+# Projection Targets
+
+- Local runtime agent manifest.
+- Workflow/runtime protocol manifest.
+- Downstream agent manifest owned outside mdkg canonical source.

package/dist/init/templates/specs/runtime-image.SPEC.md

@@ -1,6 +1,7 @@
 ---
 extends: base.SPEC.md
 template_kind: runtime_image
+spec_kind: runtime_image
 ---
 
 # Runtime Image

package/dist/init/templates/specs/tool.SPEC.md

@@ -1,6 +1,7 @@
 ---
 extends: base.SPEC.md
 template_kind: tool
+spec_kind: tool
 ---
 
 # Tool Identity

package/dist/util/argparse.js

@@ -61,20 +61,28 @@ const VALUE_FLAGS = new Set([
     "--work-id",
     "--requester",
     "--request-ref",
+    "--trigger-ref",
+    "--payload-hash",
     "--input-refs",
+    "--queue-refs",
     "--requested-outputs",
     "--constraint-refs",
+    "--add-queue-refs",
+    "--enqueue",
     "--receipt-status",
     "--work-order-id",
     "--outcome",
     "--cost-ref",
+    "--redaction-policy",
     "--proof-refs",
     "--attestation-refs",
+    "--evidence-hashes",
     "--input-hashes",
     "--output-hashes",
     "--add-input-refs",
     "--add-proof-refs",
     "--add-attestation-refs",
+    "--add-evidence-hashes",
     "--notes",
     "--agent",
     "--skill",
@@ -86,6 +94,7 @@ const VALUE_FLAGS = new Set([
     "--requires",
     "--target",
     "--snapshot",
+    "--family",
 ]);
 const BOOLEAN_FLAGS = new Set([
     "--tolerant",