mdkg 0.3.7 → 0.3.8

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.3.7",
+  "mdkg_version": "0.3.8",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "5a03de7c4602936e6108b3e8f2916ead8320a4020c335ea9cfd083d59eabf083"
+      "sha256": "e876acfbf3e9de411cd45eb86e7e9bff821f8a5dd6dc933bd6da4ac88a9686e6"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -133,6 +133,11 @@
       "category": "template",
       "sha256": "8f984580aefd02b34639fa7f5d2a834662656bbf2e12f14a285f5ae31aff74ce"
     },
+    {
+      "path": ".mdkg/templates/default/manifest.md",
+      "category": "template",
+      "sha256": "2ff2af58cae6a0381a66949d7d9e997fac6486da85171b09096c43663889da95"
+    },
     {
       "path": ".mdkg/templates/default/prd.md",
       "category": "template",
@@ -193,51 +198,101 @@
       "category": "template",
       "sha256": "08a1bd65297173a1dc9df95776775d406337a419d4bc51863593b6f28777ebdb"
     },
+    {
+      "path": ".mdkg/templates/specs/agent.MANIFEST.md",
+      "category": "template",
+      "sha256": "79fb755c95747d3f673e1333ec3f039d08f76488ba268b7fa32f457d8638ee64"
+    },
     {
       "path": ".mdkg/templates/specs/agent.SPEC.md",
       "category": "template",
       "sha256": "dab10c0ed12aa10a752ee3bd61f263065644826eb950c71a9e3458673edb0ca5"
     },
+    {
+      "path": ".mdkg/templates/specs/api.MANIFEST.md",
+      "category": "template",
+      "sha256": "dd342ab2bd331b716e4b7de9f8c7cfa503703422a4cc88c21fe90ff49b11aa83"
+    },
     {
       "path": ".mdkg/templates/specs/api.SPEC.md",
       "category": "template",
       "sha256": "aee86cadcca31a5a015d7e15ad7503c4aa30f2af0079ec03f857b82b3ecbae59"
     },
+    {
+      "path": ".mdkg/templates/specs/base.MANIFEST.md",
+      "category": "template",
+      "sha256": "056c4ccf8285db72c8befdc6acd165d625dbe892d70e89ce586f081db8e250fc"
+    },
     {
       "path": ".mdkg/templates/specs/base.SPEC.md",
       "category": "template",
       "sha256": "6d4171fac00c2f3d8f2a2ac746b8a47c59aaecebe224c3a0046dd6e6974a1d08"
     },
+    {
+      "path": ".mdkg/templates/specs/capability.MANIFEST.md",
+      "category": "template",
+      "sha256": "0ab2c2f90c6bdcddaafd77ac6cc36422d6ee10cc935942d8f80728f5b184d5cc"
+    },
     {
       "path": ".mdkg/templates/specs/capability.SPEC.md",
       "category": "template",
       "sha256": "68a91e8bbd80d1ff1972e4c31e29f26451d5a1be1d25d414170fdd670010066f"
     },
+    {
+      "path": ".mdkg/templates/specs/integration.MANIFEST.md",
+      "category": "template",
+      "sha256": "7af890bdac5515600661c241dd488c2bc270248ae6fba9afb0307d7a643022a4"
+    },
     {
       "path": ".mdkg/templates/specs/integration.SPEC.md",
       "category": "template",
       "sha256": "e907ce6ebc1fa5a455e31e39036e3f8699dccb3d9e45288c8ea025eaec4ca4a2"
     },
+    {
+      "path": ".mdkg/templates/specs/model.MANIFEST.md",
+      "category": "template",
+      "sha256": "3fe36a424b6eba8542bd08d3e2728ffd7f35d2c72037f2e565757cea15da2e1f"
+    },
     {
       "path": ".mdkg/templates/specs/model.SPEC.md",
       "category": "template",
       "sha256": "56061a241819dfda4d3022c075f744cf6650f5f52c58cd15b0af9d1f613af4f2"
     },
+    {
+      "path": ".mdkg/templates/specs/project.MANIFEST.md",
+      "category": "template",
+      "sha256": "e1f68306a9cff3d73e65a2fea38d52b49dd76921b5d7c7ea9710eb2c23cb6f89"
+    },
     {
       "path": ".mdkg/templates/specs/project.SPEC.md",
       "category": "template",
       "sha256": "386c41852cbb46e7a6ba583a7b0c4126262a56618d8e214aaa601b68d55818b9"
     },
+    {
+      "path": ".mdkg/templates/specs/runtime-agent.MANIFEST.md",
+      "category": "template",
+      "sha256": "4ba2013362597f101fb225bc6a3369a47a0c1cac3de78220efea4e53d42f0393"
+    },
     {
       "path": ".mdkg/templates/specs/runtime-agent.SPEC.md",
       "category": "template",
       "sha256": "53af7c3e172f5ed1297f340aca0be5e53302613d2e6bb9145915067d7b0004c8"
     },
+    {
+      "path": ".mdkg/templates/specs/runtime-image.MANIFEST.md",
+      "category": "template",
+      "sha256": "098debed22f274c9f408defcf330ef27c760e1a3166876f2a6e16cb28cfb4757"
+    },
     {
       "path": ".mdkg/templates/specs/runtime-image.SPEC.md",
       "category": "template",
       "sha256": "37416b045cd7733d1f5e1cc629ac9b6616024d5fa52f2bdcd90110267151e593"
     },
+    {
+      "path": ".mdkg/templates/specs/tool.MANIFEST.md",
+      "category": "template",
+      "sha256": "79e45600a3b83d70e2791cbdff0138b57018a30b7e277d9017b7ba142deccb91"
+    },
     {
       "path": ".mdkg/templates/specs/tool.SPEC.md",
       "category": "template",
@@ -246,7 +301,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "d305f0e61c2401814bc51067c8129a3ad131c6217692038bc7ffad012c305451"
+      "sha256": "0d3bb2f9ea156f53c1bf68595e591578caadc18d296fa919e71ea1a3d9a968e8"
     },
     {
       "path": "AGENTS.md",
@@ -261,7 +316,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "84de4e06dd4d6d2b316e17c37bebcec373f1a9500d7107c8dd0ce5ca15048b7d"
+      "sha256": "8f426fd8da402b4b550b71e7ec3882c614ceb2d79d23c47b9c27bca7e39fadb2"
     },
     {
       "path": "llms.txt",

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

@@ -0,0 +1,45 @@
+---
+id: {{id}}
+type: manifest
+title: {{title}}
+version: 0.1.0
+spec_kind: capability
+role: tool_service
+runtime_mode: tool_service
+work_contracts: []
+requested_capabilities: []
+skill_refs: []
+tool_refs: []
+model_refs: []
+wasm_component_refs: []
+runtime_image_refs: []
+subagent_refs: []
+resource_profile: local_cli
+update_policy: manual
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Purpose
+
+Define the reusable capability surface.
+
+# Runtime
+
+Describe the role, runtime mode, resource profile, and update policy.
+
+# Work Contracts
+
+List related WORK.md contracts.
+
+# Capabilities
+
+List requested capabilities and the authority/resource constraints that govern
+use.

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

@@ -0,0 +1,80 @@
+---
+extends: base.MANIFEST.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.
+
+# Input Context
+
+- Required room, goal, task, pack, or queue context.
+
+# Output Contract
+
+- Required report, patch, receipt, or handoff.
+
+# Receipt / Evidence Contract
+
+- 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
+
+- Tool-specific agent manifest.
+- Future runtime agent manifest.
+- Future workflow/runtime capability object.
+- Future workflow/runtime agent definition.

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

@@ -0,0 +1,33 @@
+---
+extends: base.MANIFEST.md
+template_kind: api
+spec_kind: api
+---
+
+# Service Name
+
+API or service identity.
+
+# Methods
+
+- Method name, request, response, and streaming behavior.
+
+# Idempotency
+
+- Idempotency keys and replay behavior.
+
+# Auth
+
+- Required principal, policy, and capability context.
+
+# Errors
+
+- Error taxonomy and fail-closed behavior.
+
+# Versioning
+
+- Package/version and compatibility policy.
+
+# Conformance Tests
+
+- Fixture and integration proof requirements.

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

@@ -0,0 +1,120 @@
+---
+id: {{manifest_id}}
+type: manifest
+title: {{title}}
+version: 0.1.0
+spec_kind: capability
+role: {{role}}
+runtime_mode: {{runtime_mode}}
+work_contracts: []
+requested_capabilities: []
+skill_refs: []
+tool_refs: []
+model_refs: []
+wasm_component_refs: []
+runtime_image_refs: []
+subagent_refs: []
+resource_profile: builder
+update_policy: manual
+tags: [manifest]
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Identity
+
+Name, stable id, owner, status, and source mdkg nodes.
+
+# Purpose
+
+What durable capability or contract this MANIFEST defines.
+
+# Authority Boundary
+
+Who or what is allowed to make decisions, mutate state, delegate work, or accept
+evidence under this MANIFEST.
+
+# Resource Boundary
+
+Included behavior, resources, paths, graph nodes, queues, services, and
+explicit non-authorities.
+
+# Optional Resource URIs
+
+- Optional generic draft URI: `resource://...`
+- Optional mdkg draft URI: `mdkg://resource/...`
+
+# Capabilities
+
+- 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
+
+- Required input contract.
+
+# Outputs
+
+- Required output or receipt contract.
+
+# Receipts / Evidence
+
+- Attempt evidence:
+- Validation evidence:
+- Final receipt or closeout evidence:
+- Aggregate checkpoint policy:
+
+# Dependencies
+
+- Other manifests, skills, tools, models, services, or runtime images.
+
+# Security / Privacy
+
+- Authority, secret, data, and mutation boundaries.
+- No raw secrets, credentials, local auth state, or production controls.
+
+# Validation Checks
+
+- Commands or review checks.
+
+# Closeout Evidence
+
+- Evidence required to accept this MANIFEST or implementation.
+
+# Projection Targets
+
+- Runtime manifest, package metadata, API contract, tool manifest, or protocol
+  projection.
+
+# Versioning
+
+- Compatibility rules.
+
+# Change Policy
+
+- Who can change this MANIFEST and what validation is required.
+
+# Open Questions
+
+- Decision needed before implementation.

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

@@ -0,0 +1,45 @@
+---
+extends: base.MANIFEST.md
+template_kind: capability
+spec_kind: capability
+---
+
+# Capability Name
+
+Stable mdkg capability id.
+
+# Optional Capability URI
+
+Optional generic URI: `capability://...`
+
+Optional mdkg URI: `mdkg://capability/...`
+
+# Resource Types
+
+- 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.
+
+# Revocation Rules
+
+- Conditions that revoke or disable the 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.MANIFEST.md

@@ -0,0 +1,25 @@
+---
+extends: base.MANIFEST.md
+template_kind: integration
+spec_kind: integration
+---
+
+# Integration Boundary
+
+Systems, repos, protocols, and ownership split.
+
+# Data Flow
+
+- Inputs, outputs, transformations, and receipts.
+
+# Failure And Retry
+
+- Retry, idempotency, dead-letter, and cleanup policy.
+
+# Security
+
+- Auth, secret refs, network, and data minimization.
+
+# Conformance
+
+- Contract tests and fixture expectations.

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

@@ -0,0 +1,21 @@
+---
+extends: base.MANIFEST.md
+template_kind: model
+spec_kind: model
+---
+
+# Model Identity
+
+Provider, model id, version, and intended use.
+
+# Capabilities
+
+- Reasoning, coding, browsing, vision, tool-use, or structured-output needs.
+
+# Policy Context
+
+- Data classes, retention, privacy, and allowed prompts.
+
+# Evaluation Checks
+
+- Task families, quality gates, and regression criteria.

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

@@ -0,0 +1,39 @@
+---
+extends: base.MANIFEST.md
+template_kind: project
+spec_kind: project_service
+---
+
+# Project Role
+
+Describe the repo/service responsibility and non-authorities.
+
+# Canonical Repo
+
+- Local path:
+- Remote:
+- Default branch:
+
+# Owned Capabilities
+
+- 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
+
+- Upstream/downstream repos and APIs.
+
+# Validation Checks
+
+- Build, test, mdkg, security, and release gates.

package/dist/init/templates/specs/runtime-agent.MANIFEST.md

@@ -0,0 +1,49 @@
+---
+extends: agent.MANIFEST.md
+template_kind: runtime_agent
+spec_kind: runtime_agent
+---
+
+# Queue Ownership
+
+- Orchestrator queue and per-agent queue responsibilities.
+
+# Trigger Kinds
+
+- User message, scheduled job, API event, mdkg queue event, runtime event, or
+  internal retry.
+
+# Sandbox Requirements
+
+- Lease refs, workspace bounds, cleanup, and metering requirements.
+
+# SecretGrant Requirements
+
+- Opaque refs and allowed consumers only.
+
+# Single-Writer Keys
+
+- Repo, graph, branch, or room keys that serialize writes.
+
+# Receipt Lifecycle
+
+- TriggerEvent contract.
+- AgentRun contract.
+- AttemptReceipt contract.
+- ValidationReceipt contract.
+- FinalReceipt contract.
+
+# Cancellation And Retry
+
+- Cancellation, retry, backoff, dead-letter, and finalization policy.
+
+# Telemetry Policy
+
+- 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.MANIFEST.md

@@ -0,0 +1,21 @@
+---
+extends: base.MANIFEST.md
+template_kind: runtime_image
+spec_kind: runtime_image
+---
+
+# Runtime Image
+
+Image name, digest policy, base image, and supported commands.
+
+# Resource Profile
+
+- CPU, memory, storage, network, and sandbox assumptions.
+
+# Secrets And Mounts
+
+- Opaque refs only; no raw secret values.
+
+# Conformance Checks
+
+- Build, scan, smoke, and cleanup proof.

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

@@ -0,0 +1,25 @@
+---
+extends: base.MANIFEST.md
+template_kind: tool
+spec_kind: tool
+---
+
+# Tool Identity
+
+Name, command/API surface, and owner.
+
+# Allowed Operations
+
+- Operations and parameters.
+
+# Required Policy Context
+
+- Auth, sandbox, path, network, and secret boundaries.
+
+# Failure Modes
+
+- Expected errors and retry behavior.
+
+# Audit Events
+
+- Events or receipts emitted by tool use.

package/dist/util/argparse.js

@@ -15,7 +15,9 @@ const VALUE_FLAGS = new Set([
     "--edges",
     "--format",
     "--out",
+    "--json-out",
     "--output",
+    "--limit",
     "--relates",
     "--scope",
     "--blocked-by",
@@ -123,6 +125,7 @@ const BOOLEAN_FLAGS = new Set([
     "--dry-run",
     "--apply",
     "--json",
+    "--summary",
     "--xml",
     "--toon",
     "--md",