mdkg 0.0.3 → 0.0.4

package/dist/graph/skills_indexer.js

@@ -0,0 +1,160 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_SLUG_RE = exports.SKILLS_INDEX_RELATIVE_PATH = void 0;
+exports.resolveSkillsRoot = resolveSkillsRoot;
+exports.resolveSkillsIndexPath = resolveSkillsIndexPath;
+exports.buildSkillIndexEntry = buildSkillIndexEntry;
+exports.buildSkillsIndex = buildSkillsIndex;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const frontmatter_1 = require("./frontmatter");
+exports.SKILLS_INDEX_RELATIVE_PATH = ".mdkg/index/skills.json";
+exports.SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function listSkillMarkdownFiles(dir) {
+    if (!fs_1.default.existsSync(dir)) {
+        return [];
+    }
+    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const slug = entry.name.toLowerCase();
+        const skillDir = path_1.default.join(dir, entry.name);
+        const canonicalPath = path_1.default.join(skillDir, "SKILL.md");
+        const compatPath = path_1.default.join(skillDir, "SKILLS.md");
+        if (fs_1.default.existsSync(canonicalPath) && fs_1.default.existsSync(compatPath)) {
+            throw new Error(`${skillDir}: both SKILL.md and SKILLS.md exist`);
+        }
+        if (fs_1.default.existsSync(canonicalPath)) {
+            files.push({ slug, filePath: canonicalPath });
+            continue;
+        }
+        if (fs_1.default.existsSync(compatPath)) {
+            files.push({ slug, filePath: compatPath });
+        }
+    }
+    files.sort((a, b) => a.slug.localeCompare(b.slug));
+    return files;
+}
+function requireString(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${filePath}: ${key} is required and must be a non-empty string`);
+    }
+    return value;
+}
+function optionalString(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${filePath}: ${key} must be a non-empty string when set`);
+    }
+    return value;
+}
+function optionalList(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${filePath}: ${key} must be a list`);
+    }
+    return value;
+}
+function toLowercaseList(values) {
+    return values.map((value) => value.toLowerCase());
+}
+function extractOchatr(frontmatter) {
+    const keys = Object.keys(frontmatter)
+        .filter((key) => key.startsWith("ochatr_"))
+        .sort();
+    const extracted = {};
+    for (const key of keys) {
+        extracted[key] = frontmatter[key];
+    }
+    return extracted;
+}
+function hasDirectory(dirPath) {
+    if (!fs_1.default.existsSync(dirPath)) {
+        return false;
+    }
+    return fs_1.default.statSync(dirPath).isDirectory();
+}
+function rootWorkspaceMdkgPath(root, config) {
+    const rootWs = config.workspaces.root;
+    if (rootWs && rootWs.enabled) {
+        return path_1.default.resolve(root, rootWs.path, rootWs.mdkg_dir);
+    }
+    return path_1.default.resolve(root, ".mdkg");
+}
+function resolveSkillsRoot(root, config) {
+    return path_1.default.join(rootWorkspaceMdkgPath(root, config), "skills");
+}
+function resolveSkillsIndexPath(root) {
+    return path_1.default.resolve(root, exports.SKILLS_INDEX_RELATIVE_PATH);
+}
+function buildSkillIndexEntry(root, slug, filePath) {
+    if (!exports.SKILL_SLUG_RE.test(slug)) {
+        throw new Error(`${filePath}: skill slug must be kebab-case`);
+    }
+    const content = fs_1.default.readFileSync(filePath, "utf8");
+    const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, filePath);
+    const name = requireString(frontmatter, "name", filePath);
+    const description = requireString(frontmatter, "description", filePath);
+    const version = optionalString(frontmatter, "version", filePath);
+    const tags = toLowercaseList(optionalList(frontmatter, "tags", filePath));
+    const authors = toLowercaseList(optionalList(frontmatter, "authors", filePath));
+    const links = optionalList(frontmatter, "links", filePath);
+    const skillDir = path_1.default.dirname(filePath);
+    return {
+        slug,
+        id: `skill:${slug}`,
+        qid: `root:skill:${slug}`,
+        ws: "root",
+        type: "skill",
+        name,
+        description,
+        tags,
+        version,
+        authors,
+        links,
+        path: path_1.default.relative(root, filePath),
+        has_scripts: hasDirectory(path_1.default.join(skillDir, "scripts")),
+        has_references: hasDirectory(path_1.default.join(skillDir, "references")),
+        ochatr: extractOchatr(frontmatter),
+    };
+}
+function buildSkillsIndex(root, config) {
+    const skillsRoot = resolveSkillsRoot(root, config);
+    const files = listSkillMarkdownFiles(skillsRoot);
+    const skills = {};
+    for (const file of files) {
+        const { slug, filePath } = file;
+        if (skills[slug]) {
+            throw new Error(`${filePath}: duplicate skill slug ${slug}`);
+        }
+        skills[slug] = buildSkillIndexEntry(root, slug, filePath);
+    }
+    const sortedSkills = {};
+    for (const slug of Object.keys(skills).sort()) {
+        sortedSkills[slug] = skills[slug];
+    }
+    return {
+        meta: {
+            tool: config.tool,
+            schema_version: config.schema_version,
+            generated_at: new Date().toISOString(),
+            root,
+            skills_root: path_1.default.relative(root, skillsRoot),
+            skill_count: Object.keys(sortedSkills).length,
+        },
+        skills: sortedSkills,
+    };
+}

package/dist/init/core/rule-1-mdkg-conventions.md

@@ -10,7 +10,7 @@ relates: []
 refs: []
 aliases: []
 created: 2026-01-06
-updated: 2026-01-22
+updated: 2026-03-05
 ---
 
 # mdkg conventions
@@ -87,6 +87,11 @@ Canonical ID format:
 
 `<prefix>-<number>`
 
+Reserved rule IDs allowed by contract:
+- `rule-guide`
+- `rule-soul`
+- `rule-human`
+
 Examples:
 - `task-183`
 - `edd-14`
@@ -153,11 +158,12 @@ All nodes MUST include:
 - `created` (YYYY-MM-DD)
 - `updated` (YYYY-MM-DD)
 
-Work items (`epic/feat/task/bug/chk/test`) MUST include:
+Work items (`epic/feat/task/bug/checkpoint/test`) MUST include:
   - `status`
 
 Work items MAY include:
   - `priority`
+  - `skills: [slug, ...]` (kebab-case skill references)
 
 Optional searchable metadata
 
@@ -222,6 +228,7 @@ They SHOULD include:
 The cache is enabled by default.
 
 - Root global index lives at `.mdkg/index/global.json`
+- Root skills index lives at `.mdkg/index/skills.json`
 - Index is rebuilt automatically when stale unless disabled by flag/config.
 - `.mdkg/index/` is generated and MUST be gitignored.
 

package/dist/init/core/rule-3-cli-contract.md

@@ -10,7 +10,7 @@ relates: []
 refs: []
 aliases: []
 created: 2026-01-06
-updated: 2026-01-22
+updated: 2026-03-08
 ---
 
 # mdkg CLI contract
@@ -88,7 +88,7 @@ If a user provides an unqualified ID and it is ambiguous globally:
 - Commands should be script-friendly:
   - concise outputs for single items
   - predictable formatting
-  - optional `--json` output later (not required for v1)
+  - `--json` output for supported discovery/show commands
   - when printing node summaries (e.g., `show`/list results), outputs SHOULD surface key searchable frontmatter fields such as `links` and `artifacts`
 
 ## Command set (v1 target)
@@ -99,10 +99,17 @@ If a user provides an unqualified ID and it is ambiguous globally:
   - creates `.mdkg/config.json` if missing
   - creates core docs and templates if missing
   - does NOT overwrite existing docs unless `--force`
-  - optional agent files:
-    - `--agents` creates `AGENTS.md`
-    - `--claude` creates `CLAUDE.md`
-  - `--llm` creates both
+  - updates `.gitignore` and `.npmignore` by default
+  - `--no-update-ignores` disables default ignore writes
+  - explicit flags (`--update-gitignore`, `--update-npmignore`, `--update-dockerignore`) force writes even with global opt-out
+  - `--llm` is the canonical documented path for creating `AGENTS.md` and `CLAUDE.md`
+  - `--agents` / `--claude` remain compatibility flags, but are not part of the primary onboarding story
+  - `--omni` adds strict-node bootstrap docs and scaffolding:
+    - `.mdkg/core/SOUL.md` (`id: rule-soul`)
+    - `.mdkg/core/HUMAN.md` (`id: rule-human`)
+    - `.mdkg/skills/registry.md`
+    - `.mdkg/work/events/events.jsonl`
+    - deterministic `core.md` pin insertion (`rule-soul`, then `rule-human`)
 
 ### Guide
 - `mdkg guide`
@@ -116,6 +123,9 @@ If a user provides an unqualified ID and it is ambiguous globally:
 ### Indexing
 - `mdkg index`
   - rebuild global cache `.mdkg/index/global.json`
+  - rebuild skills cache `.mdkg/index/skills.json` from `.mdkg/skills/<slug>/SKILL.md`
+  - tolerate `.mdkg/skills/<slug>/SKILLS.md` on read with warning
+  - fail validation if both `SKILL.md` and `SKILLS.md` exist in one skill directory
   - strict by default (fails on invalid frontmatter)
   - optional `--tolerant` to skip invalid nodes (escape hatch)
 
@@ -140,24 +150,56 @@ Common flags:
 - `--artifacts <ref,ref,...>`
 - `--refs <id,id,...>`
 - `--aliases <text,text,...>`
+- `--skills <slug,slug,...>` (work items)
 - `--template <set>` (default from config)
 
 ### Read/search
-- `mdkg show <id-or-qid>`
-- `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>]`
+- `mdkg show <id-or-qid> [--meta] [--json]`
+  - default behavior shows the full node body
+  - `--meta` is the compact card-only view
+- `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
   - search SHOULD match on IDs, titles, tags, path tokens, and searchable frontmatter lists (`links`, `artifacts`, `refs`, `aliases`)
-- `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--blocked] [--priority <n>]`
-
-### Graph views
-- `mdkg tree <epic-id-or-qid> [--ws <alias>]`
-- `mdkg neighbors <id-or-qid> --depth <n> [--edges <...>]`
+- `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--blocked] [--priority <n>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+- skills are first-class under `mdkg skill ...` only:
+  - `mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+  - `mdkg skill show <slug> [--meta] [--json]`
+  - `mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+  - `mdkg skill validate [<slug>]`
+
+### Task lifecycle mutation
+- `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]`
+  - supports `task`, `bug`, and `test` nodes only
+  - sets `status: progress`
+- `mdkg task update <id-or-qid> [...]`
+  - supports additive list mutation for `artifacts`, `links`, `refs`, `skills`, `tags`, and `blocked_by`
+  - supports scalar replacement for `status` and `priority`
+  - `--clear-blocked-by` resets blockers before optional re-add
+- `mdkg task done <id-or-qid> [--checkpoint "<title>"] [...]`
+  - supports `task`, `bug`, and `test` nodes only
+  - sets `status: done`
+  - optional checkpoint creation is explicit only
 
 ### Packs (core feature)
-- `mdkg pack <id-or-qid> [--depth <n>] [--verbose] [--edges <keys>] [--format md|json|toon|xml] [--out <path>] [--ws <alias>]`
+- `mdkg pack <id-or-qid> [--profile <name>] [--verbose] [--format md|json|toon|xml] [--out <path>] [--ws <alias>]`
+  - optional skill inclusion flags:
+    - `--skills none|auto|<slug,slug,...>`
+    - `--skills-depth meta|full`
+  - advanced shaping/debug flags remain supported but de-emphasized:
+    - `--depth <n>`
+    - `--edges <keys>`
+    - `--strip-code`
+    - `--max-code-lines <n>`
+    - `--max-chars <n>`
+    - `--max-lines <n>`
+    - `--max-tokens <n>`
+    - `--truncation-report <path>`
+    - `--stats-out <path>`
   - `--edges` adds to the default edge set
   - `--out` writes to a file (create parent dirs; overwrite if exists)
   - if `--out` is omitted, write to `.mdkg/pack/pack_<kind>_<id>_<timestamp>.<ext>`
   - short flags supported: `-o`, `-f`, `-v`, `-d`, `-e`, `-w`, `-r`
+  - `--profile` is the primary documented alias for `--pack-profile`
+  - pack selection includes latest checkpoint by pack-time resolver; index hint `latest_checkpoint_qid` is optimization-only
 
 ### Next priority
 - `mdkg next [<id-or-qid>] [--ws <alias>]`
@@ -169,9 +211,26 @@ Common flags:
   - creates a `chk-*` node from template
   - designed as a phase summary / compression node
 
+### Events
+- `mdkg event enable [--ws <alias>] [--no-update-gitignore]`
+  - creates `.mdkg/work/events/events.jsonl` if missing
+  - updates `.gitignore` by default
+- `mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...> [...]`
+  - appends one JSONL provenance record
+- automatic command-level events append only when event logging is enabled for the target workspace
+- current automatic mutation events:
+  - `NODE_CREATED`
+  - `SKILL_CREATED`
+  - `CHECKPOINT_CREATED`
+  - `TASK_STARTED`
+  - `TASK_UPDATED`
+  - `TASK_DONE`
+
 ### Validation and formatting
 - `mdkg validate`
   - strict frontmatter + graph integrity checks (exit code 2 on failure)
+  - validates optional node->skill references
+  - validates optional `.mdkg/work/events/events.jsonl` record shape when file exists
 - `mdkg format`
   - normalize frontmatter formatting and casing
   - avoid destructive body edits

package/dist/init/core/rule-4-repo-safety-and-ignores.md

@@ -36,6 +36,7 @@ Recommended `.gitignore` entries:
 - `.mdkg/index/`
 - `.mdkg/index/**`
 - `.mdkg/pack/`
+- `.mdkg/work/events/*.jsonl` (when episodic logging is enabled)
 
 ## npm publish safety (required)
 
@@ -67,14 +68,18 @@ For application builds:
 
 ## mdkg init behavior
 
-`mdkg init` MAY offer optional flags to append ignore entries:
+`mdkg init` updates ignore files by default for safety:
+
+- `.gitignore` appends `.mdkg/index/`, `.mdkg/pack/`, `.mdkg/work/events/*.jsonl`
+- `.npmignore` appends `.mdkg/`, `.mdkg/index/`, `.mdkg/pack/`
+- `--no-update-ignores` disables these default writes
+
+Explicit flags remain available and take precedence:
 
 - `--update-gitignore`
 - `--update-npmignore`
 - `--update-dockerignore`
 
-In v1, mdkg should default to **not** editing user files without an explicit flag.
-
 ## Index safety
 
 - `.mdkg/index/` is generated.
@@ -92,6 +97,7 @@ Workspace-local `.mdkg/` directories (near code) should follow the same rules:
 ## Summary checklist
 
 - ✅ `.mdkg/index/` ignored
+- ✅ `.mdkg/work/events/*.jsonl` ignored when event logging is enabled
 - ✅ npm publishes only `dist/`, `README.md`, `LICENSE`
 - ✅ optional `.npmignore` excludes `.mdkg/`
 - ✅ `.dockerignore` excludes `.mdkg/` when applicable

package/dist/init/core/rule-6-templates-and-schemas.md

@@ -10,7 +10,7 @@ relates: []
 refs: []
 aliases: []
 created: 2026-01-06
-updated: 2026-01-22
+updated: 2026-03-05
 ---
 
 # Templates and schemas
@@ -65,6 +65,7 @@ Optional tokens (nice-to-have, may be empty):
 - `{{artifacts}}` (list)
 - `{{refs}}` (list)
 - `{{aliases}}` (list)
+- `{{skills}}` (list; work items)
 - `{{cases}}` (list)
 
 ## Frontmatter requirements by type
@@ -90,9 +91,10 @@ All nodes MAY include the following searchable frontmatter lists:
 List fields SHOULD be written as `[]` when empty.
 Optional scalar graph fields (like `epic`, `parent`, `prev`, `next`) should be omitted when empty.
 
-Work items (`epic/feat/task/bug/chk/test`):
+Work items (`epic/feat/task/bug/checkpoint/test`):
   - `status` (enum)
   - optional `priority` (0..9)
+  - optional `skills: [slug, ...]` (kebab-case skill slugs)
   - optional graph edges: `epic`, `parent`, `relates`, `blocked_by`, `blocks`, `prev`, `next`
 
 Decision records (`dec-*`):
@@ -182,5 +184,7 @@ Body headings are strongly recommended for agent usability but should not be har
 
 - Frontmatter: strict, hard fail if invalid.
 - Body headings: warn only (do not break indexing).
+- Node -> skill references in `skills: [...]` are validated against `.mdkg/skills/<slug>/SKILL.md`.
+- `.mdkg/work/events/events.jsonl` is optional; when present, records are schema-validated by `mdkg validate`.
 - If a template is missing:
   - `mdkg new` must fail with a helpful error (exit code 3).

package/dist/init/skills/SKILL.md.example

@@ -0,0 +1,41 @@
+---
+name: {{name}}
+description: {{description}}
+{{tags_block}}{{authors_block}}{{links_block}}---
+
+# Goal
+
+Describe the deterministic outcome this skill should achieve.
+
+## When To Use
+
+- Use this skill when the workflow is triggered and the needed outcome is clear.
+- Prefer this skill over ad-hoc instructions when the procedure should be repeatable.
+
+## Inputs
+
+- Repo root
+- Current task, node, or user goal
+- Any required references or artifacts
+
+## Steps
+
+1. Confirm the triggering task or need before acting.
+2. Load only the references and artifacts required for this run.
+3. Execute the smallest deterministic workflow that satisfies the request.
+
+## Outputs
+
+- Deterministic result, patch, or artifact
+- Evidence needed for review or orchestration
+
+## Safety
+
+- Prefer repo truth over chat memory.
+- Keep secrets out of skills, references, and generated artifacts.
+- Stop and resolve ambiguity instead of guessing.
+
+## Failure Handling
+
+- If required context or policy is unclear, stop and ask before proceeding.
+- If the procedure needs more detail, load the specific reference rather than broad context.

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

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 created: {{created}}
 updated: {{updated}}
 ---

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

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 scope: []
 created: {{created}}
 updated: {{updated}}

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

@@ -13,6 +13,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 created: {{created}}
 updated: {{updated}}
 ---

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

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 created: {{created}}
 updated: {{updated}}
 ---

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

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 created: {{created}}
 updated: {{updated}}
 ---

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

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 cases: []
 created: {{created}}
 updated: {{updated}}

package/dist/pack/export_md.js

@@ -19,6 +19,12 @@ function renderHeader(meta, nodes) {
     if (meta.body_mode) {
         lines.push(`body_mode: ${meta.body_mode}`);
     }
+    if (meta.latest_checkpoint_qid) {
+        lines.push(`latest_checkpoint_qid: ${meta.latest_checkpoint_qid}`);
+    }
+    if (meta.latest_checkpoint_qid_hint) {
+        lines.push(`latest_checkpoint_qid_hint: ${meta.latest_checkpoint_qid_hint}`);
+    }
     lines.push(`nodes: ${nodes.length}`);
     lines.push(`truncated: max_nodes=${meta.truncated.max_nodes} max_bytes=${meta.truncated.max_bytes} max_chars=${Boolean(meta.truncated.max_chars)} max_lines=${Boolean(meta.truncated.max_lines)} max_tokens=${Boolean(meta.truncated.max_tokens)}`);
     if (meta.truncated.dropped.length > 0) {

package/dist/pack/export_xml.js

@@ -35,6 +35,12 @@ function exportXml(pack) {
     if (pack.meta.body_mode) {
         lines.push(`    <body_mode>${escapeXml(pack.meta.body_mode)}</body_mode>`);
     }
+    if (pack.meta.latest_checkpoint_qid) {
+        lines.push(`    <latest_checkpoint_qid>${escapeXml(pack.meta.latest_checkpoint_qid)}</latest_checkpoint_qid>`);
+    }
+    if (pack.meta.latest_checkpoint_qid_hint) {
+        lines.push(`    <latest_checkpoint_qid_hint>${escapeXml(pack.meta.latest_checkpoint_qid_hint)}</latest_checkpoint_qid_hint>`);
+    }
     lines.push(`    <generated_at>${escapeXml(pack.meta.generated_at)}</generated_at>`);
     lines.push(`    <node_count>${pack.meta.node_count}</node_count>`);
     lines.push("    <truncated>");

package/dist/pack/pack.js

@@ -130,6 +130,24 @@ function buildPackNode(root, index, qid) {
 function mergeWarnings(warnings, message) {
     warnings.push(message);
 }
+function checkpointWorkspaceFromQid(qid) {
+    const [workspace] = qid.split(":");
+    return workspace ?? "root";
+}
+function resolveLatestCheckpointQid(index, workspace) {
+    const candidates = Object.values(index.nodes)
+        .filter((node) => node.ws === workspace && node.type === "checkpoint")
+        .sort((a, b) => {
+        if (a.updated !== b.updated) {
+            return b.updated.localeCompare(a.updated);
+        }
+        if (a.created !== b.created) {
+            return b.created.localeCompare(a.created);
+        }
+        return b.qid.localeCompare(a.qid);
+    });
+    return candidates[0]?.qid;
+}
 function applyMaxNodes(orderedQids, maxNodes, truncation) {
     if (maxNodes <= 0 || orderedQids.length <= maxNodes) {
         return { included: orderedQids, dropped: [] };
@@ -142,7 +160,22 @@ function applyMaxNodes(orderedQids, maxNodes, truncation) {
 }
 function buildPack(options) {
     const warnings = [];
+    const includeLatestCheckpoint = options.includeLatestCheckpoint ?? true;
     const { qids, depths } = collectNodes(options.index, options.rootQid, options.depth, options.edges);
+    const workspace = checkpointWorkspaceFromQid(options.rootQid);
+    const latestCheckpointHint = options.index.meta.latest_checkpoint_qid?.[workspace];
+    const latestCheckpointResolved = includeLatestCheckpoint
+        ? resolveLatestCheckpointQid(options.index, workspace)
+        : undefined;
+    if (latestCheckpointResolved && latestCheckpointResolved !== options.rootQid) {
+        qids.add(latestCheckpointResolved);
+    }
+    if (includeLatestCheckpoint &&
+        latestCheckpointHint &&
+        latestCheckpointResolved &&
+        latestCheckpointHint !== latestCheckpointResolved) {
+        mergeWarnings(warnings, `latest_checkpoint_qid hint mismatch for ${workspace}: ${latestCheckpointHint} -> ${latestCheckpointResolved}`);
+    }
     if (options.verbose) {
         const coreIds = (0, verbose_core_1.readVerboseCoreList)(options.verboseCoreListPath);
         for (const id of coreIds) {
@@ -173,6 +206,8 @@ function buildPack(options) {
             verbose: options.verbose,
             generated_at: new Date().toISOString(),
             node_count: nodes.length,
+            latest_checkpoint_qid: latestCheckpointResolved,
+            latest_checkpoint_qid_hint: latestCheckpointHint,
             truncated: truncation,
         },
         nodes,

package/dist/util/argparse.js

@@ -36,6 +36,24 @@ const VALUE_FLAGS = new Set([
     "--max-tokens",
     "--stats-out",
     "--truncation-report",
+    "--description",
+    "--authors",
+    "--links",
+    "--tags-mode",
+    "--run-id",
+    "--note",
+    "--add-artifacts",
+    "--add-links",
+    "--add-refs",
+    "--add-skills",
+    "--add-tags",
+    "--add-blocked-by",
+    "--checkpoint",
+    "--kind",
+    "--notes",
+    "--agent",
+    "--skill",
+    "--tool",
 ]);
 const BOOLEAN_FLAGS = new Set([
     "--tolerant",
@@ -44,6 +62,7 @@ const BOOLEAN_FLAGS = new Set([
     "--quiet",
     "--no-cache",
     "--no-reindex",
+    "--no-update-ignores",
     "--force",
     "--update-gitignore",
     "--update-npmignore",
@@ -51,7 +70,9 @@ const BOOLEAN_FLAGS = new Set([
     "--agents",
     "--claude",
     "--llm",
+    "--omni",
     "--body",
+    "--meta",
     "--strip-code",
     "--stats",
     "--concise",
@@ -59,10 +80,14 @@ const BOOLEAN_FLAGS = new Set([
     "--dry-run",
     "--json",
     "--list-profiles",
+    "--with-scripts",
+    "--clear-blocked-by",
+    "--no-update-gitignore",
 ]);
 const FLAG_ALIASES = {
     "--o": "--out",
     "-o": "--out",
+    "--profile": "--pack-profile",
     "--f": "--format",
     "-f": "--format",
     "--v": "--verbose",