mdkg 0.1.10 → 0.3.0

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

@@ -0,0 +1,80 @@
+---
+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.
+
+# 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.SPEC.md

@@ -0,0 +1,33 @@
+---
+extends: base.SPEC.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.SPEC.md

@@ -0,0 +1,120 @@
+---
+id: {{spec_id}}
+type: spec
+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: [spec]
+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 SPEC defines.
+
+# Authority Boundary
+
+Who or what is allowed to make decisions, mutate state, delegate work, or accept
+evidence under this SPEC.
+
+# 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 specs, 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 SPEC or implementation.
+
+# Projection Targets
+
+- Runtime manifest, package metadata, API contract, tool manifest, or protocol
+  projection.
+
+# Versioning
+
+- Compatibility rules.
+
+# Change Policy
+
+- Who can change this SPEC and what validation is required.
+
+# Open Questions
+
+- Decision needed before implementation.

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

@@ -0,0 +1,45 @@
+---
+extends: base.SPEC.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.SPEC.md

@@ -0,0 +1,25 @@
+---
+extends: base.SPEC.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.SPEC.md

@@ -0,0 +1,21 @@
+---
+extends: base.SPEC.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.SPEC.md

@@ -0,0 +1,39 @@
+---
+extends: base.SPEC.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.SPEC.md

@@ -0,0 +1,49 @@
+---
+extends: agent.SPEC.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.SPEC.md

@@ -0,0 +1,21 @@
+---
+extends: base.SPEC.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.SPEC.md

@@ -0,0 +1,25 @@
+---
+extends: base.SPEC.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

@@ -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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.1.10",
+  "version": "0.3.0",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -18,10 +18,13 @@
     "smoke:capabilities": "npm run build && node scripts/smoke-capabilities.js",
     "smoke:db": "npm run build && node scripts/smoke-db.js",
     "smoke:db-queue": "npm run build && node scripts/smoke-db-queue.js",
+    "smoke:db-queue-cli": "npm run build && node scripts/smoke-db-queue-cli.js",
     "smoke:db-events": "npm run build && node scripts/smoke-db-events.js",
     "smoke:db-materializer": "npm run build && node scripts/smoke-db-materializer.js",
     "smoke:db-snapshot": "npm run build && node scripts/smoke-db-snapshot.js",
     "smoke:archive-work": "npm run build && node scripts/smoke-archive-work.js",
+    "smoke:work-invocation": "npm run build && node scripts/smoke-work-invocation.js",
+    "smoke:cli-ux-polish": "npm run build && node scripts/smoke-cli-ux-polish.js",
     "smoke:bundle": "npm run build && node scripts/smoke-bundle.js",
     "smoke:bundle-import": "npm run smoke:subgraph",
     "smoke:visibility": "npm run build && node scripts/smoke-visibility.js",
@@ -31,7 +34,7 @@
     "cli:snapshot": "npm run build && node scripts/cli_help_snapshot.js",
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
+    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-queue-cli && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:work-invocation && npm run smoke:cli-ux-polish && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
     "postinstall": "node scripts/postinstall.js",
     "smoke:subgraph": "npm run build && node scripts/smoke-subgraph.js"
   },