mdkg 0.1.9 → 0.2.0

package/dist/core/project_db_queue.js

@@ -10,6 +10,14 @@ exports.failProjectQueueMessage = failProjectQueueMessage;
 exports.deadLetterProjectQueueMessage = deadLetterProjectQueueMessage;
 exports.releaseExpiredProjectQueueLeases = releaseExpiredProjectQueueLeases;
 exports.readProjectQueueStats = readProjectQueueStats;
+exports.createProjectQueue = createProjectQueue;
+exports.pauseProjectQueue = pauseProjectQueue;
+exports.resumeProjectQueue = resumeProjectQueue;
+exports.readProjectQueue = readProjectQueue;
+exports.listProjectQueues = listProjectQueues;
+exports.readProjectQueueMessage = readProjectQueueMessage;
+exports.listProjectQueueMessages = listProjectQueueMessages;
+exports.readProjectQueueSnapshotSummary = readProjectQueueSnapshotSummary;
 const crypto_1 = __importDefault(require("crypto"));
 function loadDatabaseCtor() {
     try {
@@ -91,12 +99,44 @@ function toMessage(row) {
         last_error: row.last_error === null || row.last_error === undefined ? null : String(row.last_error),
     };
 }
+function toQueue(row) {
+    return {
+        queue_name: String(row.queue_name),
+        status: String(row.status),
+        paused_reason: row.paused_reason === null || row.paused_reason === undefined ? null : String(row.paused_reason),
+        created_at_ms: Number(row.created_at_ms),
+        updated_at_ms: Number(row.updated_at_ms),
+    };
+}
 function getMessage(db, queueName, messageId) {
     const row = db
         .prepare("SELECT * FROM project_queue_message WHERE queue_name = ? AND message_id = ?")
         .get(queueName, messageId);
     return row ? toMessage(row) : null;
 }
+function getQueue(db, queueName) {
+    const row = db.prepare("SELECT * FROM project_queue WHERE queue_name = ?").get(queueName);
+    return row ? toQueue(row) : null;
+}
+function ensureQueue(db, queueName, currentNow) {
+    const existing = getQueue(db, queueName);
+    if (existing) {
+        return existing;
+    }
+    db
+        .prepare("INSERT INTO project_queue (queue_name, status, paused_reason, created_at_ms, updated_at_ms) VALUES (?, 'active', NULL, ?, ?)")
+        .run(queueName, currentNow, currentNow);
+    const queue = getQueue(db, queueName);
+    if (!queue) {
+        throw new Error(`queue could not be loaded after create: ${queueName}`);
+    }
+    return queue;
+}
+function requireQueueActive(queue, action) {
+    if (queue.status === "paused") {
+        throw new Error(`queue ${queue.queue_name} is paused; cannot ${action}`);
+    }
+}
 function withDb(databasePath, fn) {
     const DatabaseSync = loadDatabaseCtor();
     const db = new DatabaseSync(databasePath);
@@ -139,6 +179,7 @@ function enqueueProjectQueueMessage(databasePath, input) {
     const payloadJson = stableJson(input.payload);
     const hash = payloadHash(payloadJson);
     return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        requireQueueActive(ensureQueue(db, input.queue_name, currentNow), "enqueue");
         if (input.dedupe_key) {
             const duplicate = db
                 .prepare("SELECT * FROM project_queue_message WHERE queue_name = ? AND dedupe_key = ?")
@@ -167,6 +208,7 @@ function claimProjectQueueMessage(databasePath, input) {
     assertPositiveInteger(input.lease_ms, "lease_ms");
     const currentNow = nowMs(input.now_ms);
     return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        requireQueueActive(ensureQueue(db, input.queue_name, currentNow), "claim");
         const row = db
             .prepare([
             "SELECT * FROM project_queue_message",
@@ -315,3 +357,147 @@ function readProjectQueueStats(databasePath, input = {}) {
         };
     });
 }
+function createProjectQueue(databasePath, input) {
+    assertNonEmpty(input.queue_name, "queue_name");
+    const currentNow = nowMs(input.now_ms);
+    if (input.reason !== undefined && input.reason !== null) {
+        assertNonEmpty(input.reason, "reason");
+    }
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        const existing = getQueue(db, input.queue_name);
+        if (existing) {
+            return { created: false, queue: existing };
+        }
+        const status = input.paused ? "paused" : "active";
+        db
+            .prepare("INSERT INTO project_queue (queue_name, status, paused_reason, created_at_ms, updated_at_ms) VALUES (?, ?, ?, ?, ?)")
+            .run(input.queue_name, status, input.paused ? input.reason ?? null : null, currentNow, currentNow);
+        const queue = getQueue(db, input.queue_name);
+        if (!queue) {
+            throw new Error(`queue could not be loaded after create: ${input.queue_name}`);
+        }
+        return { created: true, queue };
+    }));
+}
+function pauseProjectQueue(databasePath, input) {
+    assertNonEmpty(input.queue_name, "queue_name");
+    if (input.reason !== undefined && input.reason !== null) {
+        assertNonEmpty(input.reason, "reason");
+    }
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        ensureQueue(db, input.queue_name, currentNow);
+        db
+            .prepare("UPDATE project_queue SET status = 'paused', paused_reason = ?, updated_at_ms = ? WHERE queue_name = ?")
+            .run(input.reason ?? null, currentNow, input.queue_name);
+        const queue = getQueue(db, input.queue_name);
+        if (!queue) {
+            throw new Error(`queue could not be loaded after pause: ${input.queue_name}`);
+        }
+        return queue;
+    }));
+}
+function resumeProjectQueue(databasePath, input) {
+    assertNonEmpty(input.queue_name, "queue_name");
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        ensureQueue(db, input.queue_name, currentNow);
+        db
+            .prepare("UPDATE project_queue SET status = 'active', paused_reason = NULL, updated_at_ms = ? WHERE queue_name = ?")
+            .run(currentNow, input.queue_name);
+        const queue = getQueue(db, input.queue_name);
+        if (!queue) {
+            throw new Error(`queue could not be loaded after resume: ${input.queue_name}`);
+        }
+        return queue;
+    }));
+}
+function readProjectQueue(databasePath, queueName) {
+    assertNonEmpty(queueName, "queue_name");
+    return withDb(databasePath, (db) => getQueue(db, queueName));
+}
+function listProjectQueues(databasePath) {
+    return withDb(databasePath, (db) => db.prepare("SELECT * FROM project_queue ORDER BY queue_name ASC").all().map(toQueue));
+}
+function readProjectQueueMessage(databasePath, queueName, messageId) {
+    assertNonEmpty(queueName, "queue_name");
+    assertNonEmpty(messageId, "message_id");
+    return withDb(databasePath, (db) => getMessage(db, queueName, messageId));
+}
+function listProjectQueueMessages(databasePath, input) {
+    assertNonEmpty(input.queue_name, "queue_name");
+    const limit = input.limit ?? 50;
+    assertPositiveInteger(limit, "limit");
+    if (input.status && input.status !== "all" && !["ready", "leased", "acked", "dead_letter"].includes(input.status)) {
+        throw new Error("status must be ready, leased, acked, dead_letter, or all");
+    }
+    return withDb(databasePath, (db) => {
+        const sql = input.status && input.status !== "all"
+            ? [
+                "SELECT * FROM project_queue_message",
+                "WHERE queue_name = ? AND status = ?",
+                "ORDER BY available_at_ms ASC, created_at_ms ASC, message_id ASC",
+                "LIMIT ?",
+            ].join(" ")
+            : [
+                "SELECT * FROM project_queue_message",
+                "WHERE queue_name = ?",
+                "ORDER BY available_at_ms ASC, created_at_ms ASC, message_id ASC",
+                "LIMIT ?",
+            ].join(" ");
+        const params = input.status && input.status !== "all" ? [input.queue_name, input.status, limit] : [input.queue_name, limit];
+        return db.prepare(sql).all(...params).map(toMessage);
+    });
+}
+function readProjectQueueSnapshotSummary(databasePath) {
+    return withDb(databasePath, (db) => {
+        const rows = db
+            .prepare([
+            "SELECT q.queue_name, q.status, q.paused_reason,",
+            "COUNT(m.message_id) AS total,",
+            "SUM(CASE WHEN m.status = 'ready' THEN 1 ELSE 0 END) AS ready,",
+            "SUM(CASE WHEN m.status = 'leased' THEN 1 ELSE 0 END) AS leased,",
+            "SUM(CASE WHEN m.status = 'acked' THEN 1 ELSE 0 END) AS acked,",
+            "SUM(CASE WHEN m.status = 'dead_letter' THEN 1 ELSE 0 END) AS dead_letter",
+            "FROM project_queue q",
+            "LEFT JOIN project_queue_message m ON m.queue_name = q.queue_name",
+            "GROUP BY q.queue_name, q.status, q.paused_reason",
+            "ORDER BY q.queue_name ASC",
+        ].join(" "))
+            .all();
+        const queues = rows.map((row) => ({
+            queue_name: String(row.queue_name),
+            status: String(row.status),
+            paused_reason: row.paused_reason === null || row.paused_reason === undefined ? null : String(row.paused_reason),
+            total: Number(row.total ?? 0),
+            ready: Number(row.ready ?? 0),
+            leased: Number(row.leased ?? 0),
+            acked: Number(row.acked ?? 0),
+            dead_letter: Number(row.dead_letter ?? 0),
+        }));
+        const summary = {
+            queues,
+            total: 0,
+            ready: 0,
+            leased: 0,
+            acked: 0,
+            dead_letter: 0,
+            paused_ready: 0,
+            active_ready: 0,
+        };
+        for (const queue of queues) {
+            summary.total += queue.total;
+            summary.ready += queue.ready;
+            summary.leased += queue.leased;
+            summary.acked += queue.acked;
+            summary.dead_letter += queue.dead_letter;
+            if (queue.status === "paused") {
+                summary.paused_ready += queue.ready;
+            }
+            else {
+                summary.active_ready += queue.ready;
+            }
+        }
+        return summary;
+    });
+}

package/dist/core/project_db_snapshot.js

@@ -18,6 +18,7 @@ const version_1 = require("./version");
 const atomic_1 = require("../util/atomic");
 const errors_1 = require("../util/errors");
 const project_db_migrations_1 = require("./project_db_migrations");
+const project_db_queue_1 = require("./project_db_queue");
 function loadDatabaseCtor() {
     try {
         const loaded = require("node:sqlite");
@@ -170,7 +171,7 @@ function readManifest(filePath) {
     }
     return manifest;
 }
-function buildManifest(root, config, snapshotFile, runtimeHash) {
+function buildManifest(root, config, snapshotFile, runtimeHash, queuePolicy, queueSummary) {
     const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
     const metadata = collectSnapshotMetadata(snapshotFile, config.db.migration_table);
     return {
@@ -188,17 +189,39 @@ function buildManifest(root, config, snapshotFile, runtimeHash) {
         byte_size: fs_1.default.statSync(snapshotFile).size,
         table_counts: metadata.table_counts,
         migrations: metadata.migrations,
+        queue_policy: queuePolicy,
+        queue_summary: queueSummary,
     };
 }
+function assertQueueSnapshotPolicy(policy, summary) {
+    if (policy === "drain") {
+        if (summary.ready > 0 || summary.leased > 0) {
+            throw new errors_1.ValidationError(`db snapshot seal requires drained queues; found ready=${summary.ready}, leased=${summary.leased}`);
+        }
+        return;
+    }
+    if (policy === "paused") {
+        if (summary.leased > 0) {
+            throw new errors_1.ValidationError(`db snapshot seal --queue-policy paused requires no leased messages; found leased=${summary.leased}`);
+        }
+        if (summary.active_ready > 0) {
+            throw new errors_1.ValidationError(`db snapshot seal --queue-policy paused requires ready messages to be in paused queues; found active_ready=${summary.active_ready}`);
+        }
+        return;
+    }
+    throw new errors_1.ValidationError(`unsupported queue snapshot policy: ${policy}`);
+}
 function warningListFromVerify(root, config) {
     return (0, project_db_migrations_1.verifyProjectDb)(root, config).warnings;
 }
-function sealProjectDbSnapshot(root, config) {
+function sealProjectDbSnapshot(root, config, queuePolicy = "drain") {
     const verification = (0, project_db_migrations_1.verifyProjectDb)(root, config);
     if (!verification.ok) {
         throw new errors_1.ValidationError(`db snapshot seal requires a valid project DB; run mdkg db verify`);
     }
     const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    const queueSummary = (0, project_db_queue_1.readProjectQueueSnapshotSummary)(layout.runtimeFile);
+    assertQueueSnapshotPolicy(queuePolicy, queueSummary);
     const oldHash = fs_1.default.existsSync(layout.stateFile) ? sha256File(layout.stateFile) : null;
     fs_1.default.mkdirSync(layout.stateDir, { recursive: true });
     const tempSnapshot = path_1.default.join(layout.stateDir, `.project.sqlite.${process.pid}-${Date.now()}.tmp`);
@@ -228,7 +251,7 @@ function sealProjectDbSnapshot(root, config) {
     }
     try {
         const runtimeHash = sha256File(layout.runtimeFile);
-        const manifest = buildManifest(root, config, tempSnapshot, runtimeHash);
+        const manifest = buildManifest(root, config, tempSnapshot, runtimeHash, queuePolicy, queueSummary);
         (0, atomic_1.atomicWriteFile)(tempManifest, `${JSON.stringify(manifest, null, 2)}\n`);
         fs_1.default.renameSync(tempSnapshot, layout.stateFile);
         fs_1.default.renameSync(tempManifest, layout.stateManifest);
@@ -243,6 +266,8 @@ function sealProjectDbSnapshot(root, config) {
             byte_size: manifest.byte_size,
             table_counts: manifest.table_counts,
             migrations: manifest.migrations,
+            queue_policy: queuePolicy,
+            queue_summary: queueSummary,
             warnings: warningListFromVerify(root, config),
         };
     }

package/dist/init/AGENT_START.md

@@ -34,15 +34,17 @@ Agent operating prompt:
 - Treat `.mdkg/db` as project application state; use `mdkg db init` to create
   the generic scaffold and enable `db.enabled` without creating an active
   runtime SQLite database. Use `mdkg db migrate` after init to create or update
-  the runtime SQLite database with mdkg-owned foundation plus internal local
-  node:sqlite queue, event/receipt/reducer, and writer lease/CAS foundation
-  migrations. Queue state is delivery infrastructure, not canonical event
-  history. Event rows are durable local project DB history; receipts, reducers,
-  and writer leases are internal local helper surfaces, and there is no public
-  `mdkg db queue`, `mdkg db event`, `mdkg db reducer`, or `mdkg db lease` CLI
-  yet. Use `mdkg db verify` and `mdkg db stats` for
+  the runtime SQLite database with mdkg-owned foundation plus public local
+  node:sqlite queue delivery, internal event/receipt/reducer, writer lease/CAS,
+  and queue control migrations. Queue state is delivery infrastructure, not
+  canonical event history; use `mdkg db queue ...` to create, pause, enqueue,
+  claim, settle, inspect, and drain local queues. Event rows are durable local
+  project DB history; receipts, reducers, writer leases, and materializers are
+  internal local helper surfaces, with no public `mdkg db event`,
+  `mdkg db reducer`, `mdkg db lease`, or `mdkg db materializer` CLI yet. Use `mdkg db verify` and `mdkg db stats` for
   non-mutating health and summary receipts. Use `mdkg db snapshot seal` for
-  explicit sealed checkpoints,
+  explicit sealed checkpoints; default queue policy is drain, and
+  `--queue-policy paused` is only for intentionally paused queues,
   `mdkg db snapshot verify/status` for checkpoint health, and
   `mdkg db snapshot dump/diff` for deterministic review aids. Keep
   `.mdkg/db/runtime/` and WAL/SHM/journal/lock/temp files ignored unless a

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -39,7 +39,8 @@ Project database commands:
 - `mdkg db migrate [--json]`
 - `mdkg db verify [--json]`
 - `mdkg db stats [--json]`
-- `mdkg db snapshot seal [--json]`
+- `mdkg db queue create|pause|resume|enqueue|claim|ack|fail|dead-letter|release-expired|stats|list|show ... [--json]`
+- `mdkg db snapshot seal [--queue-policy drain|paused] [--json]`
 - `mdkg db snapshot verify [--json]`
 - `mdkg db snapshot status [--json]`
 - `mdkg db snapshot dump [--snapshot <path>] [--output <path>] [--json]`
@@ -53,19 +54,23 @@ Project database commands:
   queue, event/receipt/reducer, and writer lease/CAS foundation migrations
 - `mdkg db migrate` records migration order, checksums, and applied timestamps
   in the configured migration table
-- queue tables are durable local delivery state, not canonical event history;
-  there is no public `mdkg db queue` CLI yet
+- `mdkg db queue ...` exposes durable local delivery operations backed by
+  node:sqlite; queue rows are delivery state, not canonical event history
+- paused queues reject enqueue and claim, but ack/fail/dead-letter and
+  release-expired remain available so leased work can settle
 - event tables are durable local history for project DB state transitions;
-  receipts, typed reducers, and writer leases remain internal helper surfaces in
-  this release, with no public `mdkg db event`, `mdkg db reducer`, or
-  `mdkg db lease` CLI yet
+  receipts, typed reducers, writer leases, and materializers remain internal
+  helper surfaces in this release, with no public `mdkg db event`,
+  `mdkg db reducer`, `mdkg db lease`, or `mdkg db materializer` CLI yet
 - `mdkg db verify` checks config, layout, runtime SQLite integrity, migration
   metadata, receipt directory policy, and transient runtime files
 - `mdkg db stats` reports table counts, database size, migration state,
   transient runtime files, receipt-file count, and state snapshot presence
 - `mdkg db snapshot seal` writes an opt-in sealed checkpoint and manifest under
-  `.mdkg/db/state`; `snapshot verify/status/dump/diff` inspect and review that
-  checkpoint without treating raw binary diffs as human-readable truth
+  `.mdkg/db/state`; default `--queue-policy drain` requires no ready or leased
+  messages, while `--queue-policy paused` allows ready messages only in paused
+  queues. `snapshot verify/status/dump/diff` inspect and review that checkpoint
+  without treating raw binary diffs as human-readable truth
 - active `.mdkg/db/runtime/` files and `.mdkg/db` WAL/SHM/journal/lock/temp files are ignored by default
 
 Validation commands:

package/dist/init/README.md

@@ -75,17 +75,19 @@ Fresh mdkg workspaces default to `index.backend: sqlite`; `.mdkg/index/mdkg.sqli
 `.mdkg/index`. Run `mdkg db init` to create the generic scaffold, write
 `.mdkg/db/project-db.json`, and enable `db.enabled`; it does not create an
 active runtime SQLite database. Run `mdkg db migrate` after init to create or
-update the active runtime SQLite database with mdkg-owned foundation plus
-internal local node:sqlite queue, event/receipt/reducer, and writer lease/CAS
-foundation migrations. Queue state is delivery infrastructure, not canonical
-event history. Event rows are durable local project DB history; receipts,
-reducers, and writer leases are internal local helper surfaces, and there is no
-public `mdkg db queue`, `mdkg db event`, `mdkg db reducer`, or `mdkg db lease`
-CLI yet. Use `mdkg db verify` for non-mutating health checks and
+update the active runtime SQLite database with mdkg-owned foundation plus public
+local node:sqlite queue delivery, internal event/receipt/reducer, writer
+lease/CAS, and queue control migrations. Queue state is delivery
+infrastructure, not canonical event history; use `mdkg db queue ...` to create,
+pause, enqueue, claim, settle, inspect, and drain local queues. Event rows are
+durable local project DB history; receipts, reducers, writer leases, and
+materializers are internal local helper surfaces, with no public `mdkg db event`,
+`mdkg db reducer`, `mdkg db lease`, or `mdkg db materializer` CLI yet. Use `mdkg db verify` for non-mutating health checks and
 `mdkg db stats` for table counts, DB size, migration state, and receipt-file
 counts. Use `mdkg db snapshot seal` to create an opt-in sealed checkpoint under
-`.mdkg/db/state`, then use `mdkg db snapshot verify/status` for integrity and
-freshness checks. Use `mdkg db snapshot dump/diff` as deterministic review aids
+`.mdkg/db/state`; the default queue policy is drain, and
+`--queue-policy paused` is only for intentionally paused queues. Then use
+`mdkg db snapshot verify/status` for integrity and freshness checks. Use `mdkg db snapshot dump/diff` as deterministic review aids
 for SQLite snapshots. Keep active runtime DB files and transient
 WAL/SHM/journal, lock, and temp files ignored. Commit schema files, manifests,
 receipts, and sealed state snapshots only by explicit repo policy.

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.1.9",
+  "mdkg_version": "0.2.0",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "b692c05fcfa1eaaa90edcd3f7a39042615f90e8915c7d447801c93284ed7463e"
+      "sha256": "14ba3fa0657a43345ae81631024519955868fa34081b7517cb253b0be96cf163"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -81,7 +81,7 @@
     {
       "path": ".mdkg/skills/verify-close-and-checkpoint/SKILL.md",
       "category": "default_skill",
-      "sha256": "f85ffa4a139db10c3bc3203cde0e4f41603fbc7f3925e6fdaba821346ffa28b8"
+      "sha256": "3e4137b7b6a71f088dee79b5ee2f4743aefa3b43adae07337307db89a24416b6"
     },
     {
       "path": ".mdkg/templates/default/archive.md",
@@ -183,10 +183,65 @@
       "category": "template",
       "sha256": "9d8b971ded7a587105fb8b14bb79f68b612fa6e1962cf06859bab82e2aee57c7"
     },
+    {
+      "path": ".mdkg/templates/skills/base.SKILL.md",
+      "category": "template",
+      "sha256": "08a1bd65297173a1dc9df95776775d406337a419d4bc51863593b6f28777ebdb"
+    },
+    {
+      "path": ".mdkg/templates/specs/agent.SPEC.md",
+      "category": "template",
+      "sha256": "6facd5a424fa91d23f7df3e357c98ca4d31691410fad024d5bc8ff3781b0f571"
+    },
+    {
+      "path": ".mdkg/templates/specs/api.SPEC.md",
+      "category": "template",
+      "sha256": "42f6119478241a3c7dd12a2a25bd03b30d9c2bc60528287136ea044f20b215c4"
+    },
+    {
+      "path": ".mdkg/templates/specs/base.SPEC.md",
+      "category": "template",
+      "sha256": "cff1ee53e9369184e2d92194f165f131254d4439bc79bcbbaaae4a13d616c97b"
+    },
+    {
+      "path": ".mdkg/templates/specs/capability.SPEC.md",
+      "category": "template",
+      "sha256": "755c24dea04f687da4714d0a12489e1ae36c5f17b838c2e24bb993378a7d9510"
+    },
+    {
+      "path": ".mdkg/templates/specs/integration.SPEC.md",
+      "category": "template",
+      "sha256": "990005a805bc6e6397f03e0de1ca69d536ae9d55719782a3075781289b44b941"
+    },
+    {
+      "path": ".mdkg/templates/specs/model.SPEC.md",
+      "category": "template",
+      "sha256": "eb73ed195139cf5655ba70c948aaaa28fc2c85d2db1b6258d703f10e73bf3713"
+    },
+    {
+      "path": ".mdkg/templates/specs/omniruntime-agent.SPEC.md",
+      "category": "template",
+      "sha256": "343c7c148faae0c2b24364c276ce345757b5725a750cfebeee4cdeb3dde55009"
+    },
+    {
+      "path": ".mdkg/templates/specs/project.SPEC.md",
+      "category": "template",
+      "sha256": "5ade0aa05907b9ec418c41ee051493d8ecc8ad3d45608ab74fc3cbe2974e79a4"
+    },
+    {
+      "path": ".mdkg/templates/specs/runtime-image.SPEC.md",
+      "category": "template",
+      "sha256": "24c1b2fb0bd0d63bbce41ee36b43f9edf531b26438bca2706ad1ab556eaabbf0"
+    },
+    {
+      "path": ".mdkg/templates/specs/tool.SPEC.md",
+      "category": "template",
+      "sha256": "18340481891bba180dd077d82b86248ede885131fb75675b775ea0c3749ee5c0"
+    },
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "1e1d9d94e2aa761b1a7978ab4b44e8bb7c3f0d33e94ed2d98cb06d641f4c42c6"
+      "sha256": "5948ed5222b2cbce0468191d00287ce5dbc1aaa434640f4daa676afb92d48d4b"
     },
     {
       "path": "AGENTS.md",
@@ -201,7 +256,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "9f90882d698d0ad1b16bad0fbe37065e4ff9f2b79b27373ef7dce74b78e99265"
+      "sha256": "baf9792f0bd50ce44de2dc16babc73f631a1191acff853fdc4caa7d452f50561"
     },
     {
       "path": "llms.txt",

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

@@ -46,13 +46,14 @@ 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. Use a clean npm cache: `export NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache`.
-3. 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`.
-4. Run `npm pack --dry-run --json` and confirm the tarball includes `dist/cli.js`, compiled folders, `dist/init/`, release docs, and `scripts/postinstall.js`.
-5. Confirm registry state with `npm view mdkg version --registry=https://registry.npmjs.org/`.
-6. Publish only after the registry still shows the previous version and npm auth is known to have write access.
-7. If publishing fails with 2FA or token policy errors, do not commit; fix npm auth or package policy, then rerun publish.
-8. After successful publish, verify `npm view mdkg version` and `npm view mdkg dist-tags`, then commit the release changes.
+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.
 
 ## Bundle-Aware Commit Gate
 

package/dist/init/templates/skills/base.SKILL.md

@@ -0,0 +1,66 @@
+---
+name: {{skill_slug}}
+description: {{description}}
+tags: [stage:plan, writer:orchestrator]
+version: 0.1.0
+authors: [{{owner}}]
+links: []
+---
+
+# Purpose
+
+Describe the repeatable workflow and the durable outcome this skill produces.
+
+## When To Use
+
+- Trigger condition.
+
+## Inputs
+
+- Required context or artifacts.
+
+## Outputs
+
+- Result, patch, artifact, report, or handoff.
+
+## Required Capabilities
+
+- Capability needed by the worker or orchestrator.
+
+## Resources Touched
+
+- Files, repos, services, or mdkg nodes the skill may inspect or mutate.
+
+## Steps
+
+1. Ground in source and mdkg truth.
+2. Execute the smallest deterministic workflow.
+3. Record evidence.
+
+## Validation Checks
+
+- Command or review gate.
+
+## Closeout Evidence
+
+- Evidence required before work can be considered done.
+
+## Failure Modes
+
+- Known blocker or ambiguity.
+
+## Safety Rules
+
+- No secrets or unrelated broad mutation.
+
+## Related SPECs
+
+- SPEC refs.
+
+## Projection Targets
+
+- Runtime or agent config projections, if any.
+
+## Open Questions
+
+- Question to resolve before implementation.

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

@@ -0,0 +1,39 @@
+---
+extends: base.SPEC.md
+template_kind: agent
+---
+
+# Agent Role
+
+Define the durable agent role and trigger conditions.
+
+# Allowed Resources
+
+- Resources the agent may read or write.
+
+# 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.
+
+# Escalation Behavior
+
+- When to stop, ask, or return a blocker.
+
+# Projection Targets
+
+- `.codex/agents` TOML
+- future OmniRuntime AgentManifest
+- future OmniTx capability object
+- future OmniPL agent definition