mdkg 0.3.7 → 0.3.9

package/dist/init/skills/default/author-mdkg-skill/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: author-mdkg-skill
+description: Create or update an mdkg SKILL.md or MANIFEST.md when a repeatable workflow, capability, agent, tool, runtime, API, or projection contract should become durable mdkg-authored knowledge.
+tags: [stage:plan, writer:orchestrator, mdkg, skills, authoring]
+version: 0.2.0
+authors: [mdkg]
+links: [AGENT_START.md, CLI_COMMAND_MATRIX.md, .mdkg/design/edd-5-mdkg-skills-integration-guide-v0-4-agent-skills-standard-and-packs.md]
+---
+
+# Goal
+
+Create or update focused mdkg-authored SKILL.md and MANIFEST.md assets that make
+repeatable workflows and durable capabilities explicit without creating
+duplicated procedures or projection-only behavior.
+
+## When To Use
+
+- When a repo workflow is repeated often enough to deserve a reusable skill
+- When an existing skill no longer matches the current command surface or docs
+- When a builder asks to codify a procedure for future humans or agents
+- When a capability, agent, tool, runtime image, API, model, or integration
+  needs a durable MANIFEST before it is projected into a runtime-specific config
+- When `.codex/agents` or another projection surface contains behavior that
+  should be mirrored into durable mdkg/MANIFEST/SKILL state
+
+## Inputs
+
+- Repo root
+- Workflow trigger and desired outcome
+- Any existing related skills, docs, or command references
+- Candidate capability, resource, agent, tool, runtime, API, model, or
+  integration boundary
+- Source mdkg nodes and intended projection targets, if any
+
+## Required Output Sections
+
+For SKILL.md output, include:
+
+- Purpose
+- When to use
+- Inputs
+- Outputs
+- Required capabilities
+- Resources touched
+- Steps
+- Validation checks
+- Closeout evidence
+- Failure modes
+- Safety rules
+- Related manifests
+- Projection targets
+- Open questions
+
+For MANIFEST.md output, include:
+
+- Identity
+- Purpose
+- Scope
+- Non-goals
+- Status
+- Owners
+- Source mdkg nodes
+- Resource URIs
+- Capabilities
+- Inputs
+- Outputs
+- Dependencies
+- Security boundaries
+- Validation checks
+- Closeout evidence
+- Projection targets
+- Versioning
+- Change policy
+- Open questions
+
+## Steps
+
+1. Check for an existing fit first with `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>`.
+2. If an existing skill already covers the workflow, update it instead of creating a near-duplicate.
+3. If a manifest already covers the capability, update that MANIFEST or create a
+   repair task instead of adding behavior only to a projection file.
+4. Use existing templates from `.mdkg/templates/skills/` and
+   `.mdkg/templates/specs/` before proposing a new template family.
+5. If the workflow is really task mutation or event provenance, prefer teaching
+   `mdkg task ...` and `mdkg event ...` for structured fields while still
+   allowing markdown narrative edits where they fit better.
+6. If a new skill is justified, scaffold it with
+   `mdkg skill new <slug> "<name>" --description "..."`.
+7. Write the description so it says both what the skill does and when to use it.
+8. Add only the minimum tags needed for discovery, including the correct
+   `stage:*` tag and a single `writer:*` tag.
+9. Keep the body concise and procedural; move detailed reference material into
+   `references/` only when needed.
+10. Distinguish durable source from projection:
+    mdkg/MANIFEST/SKILL is source; `.codex/agents`, future runtime manifests, and
+    protocol resources are projections.
+11. Add validation checks and closeout evidence to every authored or revised
+    SKILL/MANIFEST.
+12. If input is incomplete, create repair tasks instead of guessing.
+13. Validate the new or updated skill with `mdkg skill validate <slug>`.
+14. If the skill changes the public workflow, update `AGENT_START.md`,
+    `CLI_COMMAND_MATRIX.md`, root onboarding docs, and the skill registry in the
+    same pass.
+15. When mirrored skill folders are enabled, run `mdkg skill sync` after broad
+    manual changes so every configured `.mdkg/config.json`
+    `customization.skill_mirrors.targets` path stays current. The default
+    targets are `.agents/skills/` and `.claude/skills/`; other agent-local
+    skill roots may be configured by the repo.
+
+## Outputs
+
+- One valid `SKILL.md` using the mdkg canonical section shape
+- One valid `MANIFEST.md` when the work is a durable capability, agent, project,
+  tool, runtime, API, model, or integration contract
+- Any needed `references/`, `assets/`, or opt-in `scripts/` scaffolding
+- Updated docs and registry entries when the workflow surface changed
+- Repair tasks for weak, missing, ambiguous, projection-only, or unsafe input
+- Validation and closeout evidence sufficient for a future agent to trust the
+  asset
+
+## Required Capabilities
+
+- mdkg skill discovery
+- mdkg capability discovery
+- Markdown frontmatter and body authoring
+- source/projection boundary review
+- validation and closeout evidence review
+
+## Resources Touched
+
+- `.mdkg/skills/<slug>/SKILL.md`
+- `.mdkg/templates/skills/`
+- `.mdkg/templates/specs/`
+- relevant `MANIFEST.md` nodes or template files, with legacy `SPEC.md`
+  references retained only for compatibility
+- configured mirrored skill roots only through `mdkg skill sync`
+
+## Validation Checks
+
+- `mdkg skill validate <slug>`
+- `mdkg skill sync --json` when mirror targets are present
+- `mdkg capability search "<skill or manifest concept>" --json`
+- `mdkg validate --changed-only --json`
+- `mdkg validate`
+- Template coverage check when template files are changed
+- Projection validation report when `.codex/agents` or another projection
+  target is involved
+
+## Closeout Evidence
+
+- Changed skill or MANIFEST paths
+- Checks run and results
+- Related mdkg nodes
+- Projection targets reviewed
+- Repair tasks created for incomplete inputs
+- Explicit note that no generator/exporter was implemented unless selected work
+  asked for it
+
+## Safety Rules
+
+- Do not create skills for one-off tasks or vague advice.
+- Prefer repo truth over chat memory when deciding the skill body and examples.
+- Do not add `scripts/` unless instructions are insufficient and deterministic execution really needs them.
+- Only the durable writer stage should commit the new or updated skill.
+- mdkg indexes and discovers skills, but does not execute skill scripts.
+- Do not treat `.codex/agents`, future runtime manifests, or package exports as
+  durable source of truth.
+- Do not create new `SPEC.md` capability docs; use `MANIFEST.md`. Keep legacy
+  `SPEC.md` references only when documenting compatibility or migration repair.
+- Do not export secrets, provider credentials, raw auth state, production
+  controls, wallet/ledger state, or local-only user paths into templates or
+  projections.
+- Do not create a skill-factory-agent until SKILL/MANIFEST templates and projection
+  doctrine are stable.
+- Optional `draft_uri` fields are future-facing hints, not finalized protocol
+  semantics. Use generic examples such as `capability://repo.inspect` or
+  `mdkg://capability/repo.inspect` in canonical mdkg templates.
+- Do not use downstream product names or product-specific URI schemes as public
+  mdkg template examples.
+
+## Failure Handling
+
+- If the trigger or writer role is unclear, stop and resolve that before authoring the skill.
+- If multiple skills overlap, merge or narrow them instead of creating redundant procedures.
+- If the workflow still feels too broad, split it into smaller skills before finalizing.
+- If durable behavior exists only in a projection file, create or update a MANIFEST
+  and record projection repair work.
+- If a requested template family is missing, propose a template backlog task
+  before inventing a one-off shape.
+- If validation cannot run, record the exact blocker and keep the work open.
+
+## Related Manifests
+
+- Future `agent.*` manifests for Codex and runtime agents
+- Future capability, tool, model, runtime image, integration, and API manifests
+- Root/child project manifests discovered through mdkg capability search
+
+## Projection Targets
+
+- `.codex/agents` TOML
+- future runtime agent manifests
+- future workflow/runtime protocol resource and capability objects
+- future workflow/runtime protocol definitions
+
+## Open Questions
+
+- Which MANIFEST template families should be promoted into public seeded assets
+  first?
+- Which projection fields should be generated versus manually maintained?
+- What validation command should become the canonical MANIFEST template coverage
+  check?

package/dist/init/skills/default/pursue-mdkg-goal/SKILL.md

@@ -46,6 +46,16 @@ Move one durable mdkg goal forward without losing scope, evidence, or user inten
 - Edit `SKILL.md` files only when the active node is explicitly skill-maintenance work.
 - After intentional skill edits, run `mdkg skill sync`, `mdkg skill validate`, `mdkg index`, and `mdkg validate`.
 
+## Multi-Repo And Subgraph Goals
+
+- Gather read-only baselines before mutating any repo: git status, mdkg status, validation, doctor, and subgraph audit where relevant.
+- Require one explicit matrix approval before applying coordinated upgrades across multiple repos.
+- Apply and verify upgrades one repo at a time.
+- Commit accepted child repo mdkg-only changes locally before refreshing a root-owned subgraph bundle.
+- Refresh root-owned bundles only from clean, accepted child commits; avoid `--allow-dirty` unless the user explicitly approves that risk.
+- Keep root-qualified qids in cross-repo planning so overlapping child ids stay unambiguous.
+- Do not store raw secrets, tokens, provider payloads, raw prompts, or unrelated runtime payloads in graph state, checkpoints, or handoffs.
+
 ## Outputs
 
 - One active scoped work item at a time.

package/dist/init/skills/default/select-work-and-ground-context/SKILL.md

@@ -42,6 +42,14 @@ Choose the correct work item and load the smallest deterministic context needed
 - Clear understanding of the active task, related docs, and current state
 - No durable mdkg writes or commits from this stage
 
+## Multi-Repo Grounding
+
+- For root/subgraph work, inspect the root graph and each child graph read-only before choosing a mutation target.
+- Collect a small matrix with repo path, git status, mdkg version, status, validation result, doctor result, and selected goal state.
+- Treat dirty child repos as ownership boundaries; ask before mutating them or before refreshing root bundles from them.
+- Prefer root-qualified qids in packs, handoffs, and cross-repo blockers so same-number child ids cannot be confused.
+- Use compact diagnostics when available: `mdkg validate --summary --json --limit 20`, `mdkg validate --changed-only --json`, and `mdkg format --headings --dry-run --summary --json --limit 20`.
+
 ## Safety
 
 - Do not start coding from chat memory alone.

package/dist/init/skills/default/verify-close-and-checkpoint/SKILL.md

@@ -45,15 +45,67 @@ Finish work with evidence, validation, and minimal memory drift.
 
 Use this local repo-only checklist before publishing mdkg:
 
-1. Confirm package intent and version in `package.json`, `package-lock.json`, `README.md`, `CLI_COMMAND_MATRIX.md`, and `CHANGELOG.md`.
-2. Confirm release-line intent before bumping: when a change crosses a capability-track boundary, prefer the next minor release line over patch-style continuation. For the current project DB track, follow `0.1.9 -> 0.2.0` rather than naming the next planned source line `0.1.10`.
-3. Use a clean npm cache: `export NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache`.
-4. Run `npm ci`, `npm run build`, `node scripts/assert-publish-ready.js`, `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:archive-work`, `npm run smoke:bundle`, `npm run smoke:subgraph`, and `npm run smoke:visibility`.
-5. Run `npm pack --dry-run --json` and confirm the tarball includes `dist/cli.js`, compiled folders, `dist/init/`, release docs, and `scripts/postinstall.js`.
-6. Confirm registry state with `npm view mdkg version --registry=https://registry.npmjs.org/`.
-7. Publish only after the registry still shows the previous version and npm auth is known to have write access.
-8. If publishing fails with 2FA or token policy errors, do not commit; fix npm auth or package policy, then rerun publish.
-9. After successful publish, verify `npm view mdkg version` and `npm view mdkg dist-tags`, then commit the release changes.
+1. Confirm package intent and version in `package.json`, `package-lock.json`,
+   `README.md`, `CLI_COMMAND_MATRIX.md`, generated docs, and `CHANGELOG.md`.
+2. Map every publish-bound change in `origin/main..HEAD` to release notes. Treat
+   missing changelog coverage, stale public version strings, and generated-doc
+   drift as publish blockers, not cosmetic notes.
+3. Confirm release-line intent before bumping: when a change crosses a
+   capability-track boundary, prefer the next minor release line over patch-style
+   continuation.
+4. Use a clean npm cache path such as `/private/tmp/mdkg-npm-cache`.
+5. Run `npm ci`, `npm run build`, `node scripts/assert-publish-ready.js`,
+   `npm run test`, `npm run cli:check`, `npm run cli:contract`,
+   `npm run docs:check`, `node dist/cli.js validate --json`,
+   `node dist/cli.js validate --changed-only --json`, `npm run smoke:consumer`,
+   `npm run smoke:matrix`, `npm run smoke:upgrade`, `npm run smoke:init`,
+   `npm run smoke:capabilities`, `npm run smoke:archive-work`,
+   `npm run smoke:bundle`, `npm run smoke:bundle-import`,
+   `npm run smoke:subgraph`, and `npm run smoke:visibility`.
+6. Run `NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache npm pack --dry-run --json`
+   and confirm the tarball includes `dist/cli.js`, compiled folders,
+   `dist/init/`, release docs, and `scripts/postinstall.js`.
+7. Run the publish dry-run before recommending publish readiness:
+
+```bash
+NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache npm publish --dry-run --registry=https://registry.npmjs.org/
+```
+
+8. Confirm registry state with these checks; readiness requires latest below the
+   target and the target version not already published:
+
+```bash
+npm view mdkg version --registry=https://registry.npmjs.org/
+npm view mdkg@<version> version --registry=https://registry.npmjs.org/
+```
+
+9. Stop with either a publish-readiness recommendation or an exact gaps list.
+   Do not run real `npm publish`, create a tag, or push release commits without
+   explicit user approval after the dry-run gates.
+10. When publishing with an exported `NPM_TOKEN`, create a temporary npm
+   userconfig that references the environment variable literally, then verify
+   auth before publish:
+
+```bash
+printf '//registry.npmjs.org/:_authToken=${NPM_TOKEN}\nregistry=https://registry.npmjs.org/\n' > /private/tmp/mdkg-npm-publish.npmrc
+NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache npm whoami --registry=https://registry.npmjs.org/ --userconfig=/private/tmp/mdkg-npm-publish.npmrc
+```
+
+Do not print the token, do not write the expanded token into committed files,
+and do not add unsupported `always-auth` config.
+11. Publish only after explicit user approval, the registry still shows the
+    previous version, and npm auth is known to have write access. Use the
+    verified userconfig when relying on `NPM_TOKEN`:
+
+```bash
+NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache npm publish --registry=https://registry.npmjs.org/ --userconfig=/private/tmp/mdkg-npm-publish.npmrc
+```
+
+12. If publishing fails with 2FA, token policy, or permission errors, do not
+    commit; fix npm auth or package policy, then rerun publish.
+13. After successful publish, verify `npm view mdkg version`, `npm view mdkg dist-tags`,
+    and a temp-dir global install of the latest package before closing
+    post-publish validation.
 
 ## Bundle-Aware Commit Gate
 
@@ -68,6 +120,18 @@ mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip
 
 Skip `mdkg archive compress --all` only when the repo has no `.mdkg/archive` sidecars. Skip bundle refresh only when the repo intentionally does not track `.mdkg/bundles/`. Use `--profile public` or `mdkg pack --visibility public` only for explicit export-safe output after public workspace, archive, and import visibility has been reviewed.
 
+## Multi-Repo Closeout Gate
+
+Use this order for root orchestration, child repo upgrades, and subgraph refresh work:
+
+1. Gather read-only baselines for every involved repo before mutation.
+2. Get one explicit approval matrix for which repos may be updated.
+3. Apply and validate one repo at a time.
+4. Commit accepted child repo mdkg-only changes locally before root subgraph sync.
+5. Sync root-owned bundles only from clean child commits and record the child commit id in the root evidence.
+6. Run root subgraph audit or verify after bundle refresh.
+7. Keep handoffs refs-only and sanitized; never copy raw secrets, tokens, prompts, provider payloads, or unrelated raw runtime payloads into checkpoints or packs.
+
 ## Outputs
 
 - Verified mdkg graph state

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.