mdkg 0.3.8 → 0.3.9

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Git-native project memory for AI coding agents",
   "license": "MIT",
   "bin": {
@@ -37,8 +37,10 @@
     "smoke:handoff": "npm run build && node scripts/smoke-handoff.js",
     "smoke:warning-ux": "npm run build && node scripts/smoke-warning-ux.js",
     "smoke:integration-ux": "npm run build && node scripts/smoke-integration-ux.js",
-    "docs:generate": "npm run build && node scripts/generate-docs-reference.js --write",
-    "docs:check": "npm run build && node scripts/generate-docs-reference.js --check",
+    "docs:generate": "npm run build && node scripts/generate-docs-reference.js --write && node scripts/generate-release-notes-data.js --write",
+    "docs:release-notes": "node scripts/generate-release-notes-data.js --write",
+    "docs:release-notes:check": "node scripts/generate-release-notes-data.js --check",
+    "docs:check": "npm run build && node scripts/generate-docs-reference.js --check && node scripts/generate-release-notes-data.js --check && node scripts/check-doc-command-examples.js",
     "docs:check-commands": "npm run build && node scripts/check-doc-command-examples.js",
     "smoke:mdkg-dev": "npm run build && node scripts/smoke-mdkg-dev.js",
     "smoke:mdkg-dev-docs": "npm run build && node scripts/smoke-mdkg-dev-docs.js",
@@ -62,7 +64,7 @@
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
     "cli:contract": "npm run build && node scripts/generate-command-contract.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && npm run cli:contract && 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:operator-health && npm run smoke:fix-plan && npm run smoke:branch-conflicts && npm run smoke:id-repair && npm run smoke:command-docs && npm run smoke:spike && npm run smoke:goal-lifecycle && npm run smoke:semantic-refs && npm run smoke:checkpoint-templates && npm run smoke:handoff && npm run smoke:warning-ux && npm run smoke:integration-ux && npm run smoke:mdkg-dev && npm run smoke:mdkg-dev-docs && npm run smoke:mdkg-dev-seo && npm run smoke:mdkg-dev-polish-pass2 && npm run smoke:mdkg-dev-polish-pass3 && npm run smoke:mdkg-dev-polish-pass4 && npm run smoke:mdkg-dev-polish-pass5 && npm run smoke:mdkg-dev-a11y && npm run smoke:mdkg-dev-perf && npm run smoke:demo-graph && npm run smoke:bundle && npm run smoke:graph-clone && npm run smoke:mcp && 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 && npm run cli:contract && npm run docs: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:operator-health && npm run smoke:fix-plan && npm run smoke:branch-conflicts && npm run smoke:id-repair && npm run smoke:command-docs && npm run smoke:spike && npm run smoke:goal-lifecycle && npm run smoke:semantic-refs && npm run smoke:checkpoint-templates && npm run smoke:handoff && npm run smoke:warning-ux && npm run smoke:integration-ux && npm run smoke:mdkg-dev && npm run smoke:mdkg-dev-docs && npm run smoke:mdkg-dev-seo && npm run smoke:mdkg-dev-polish-pass2 && npm run smoke:mdkg-dev-polish-pass3 && npm run smoke:mdkg-dev-polish-pass4 && npm run smoke:mdkg-dev-polish-pass5 && npm run smoke:mdkg-dev-a11y && npm run smoke:mdkg-dev-perf && npm run smoke:demo-graph && npm run smoke:bundle && npm run smoke:graph-clone && npm run smoke:mcp && 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"
   },