@unbrained/pm-cli 2026.6.12 → 2026.6.16

package/dist/core/governance/content-fields.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Content-field governance & utilization primitives.
+ *
+ * "Project management = context management": these primitives let agents query
+ * which items carry context (notes/learnings/files/docs/tests/comments/deps/
+ * body, plus whether a linked test carries a runnable command) and which do
+ * not. The surface powers content-field selection (pm list / pm update-many)
+ * and field-utilization reporting (pm stats --field-utilization).
+ *
+ * The module is pure: it performs no IO and imports no heavy runtime
+ * dependencies. Callers pass plain structural item shapes so the logic stays
+ * trivially testable.
+ */
+/** The content fields an item can carry context in. */
+export type ContentField = "notes" | "learnings" | "files" | "docs" | "tests" | "comments" | "deps" | "body" | "linked_command";
+/** Stable rendering / iteration order for content fields. */
+export declare const CONTENT_FIELD_ORDER: readonly ContentField[];
+/** Minimal structural shape needed: the collection arrays + optional body. */
+export interface ContentFieldItem {
+    notes?: unknown[];
+    learnings?: unknown[];
+    files?: unknown[];
+    docs?: unknown[];
+    tests?: unknown[];
+    comments?: unknown[];
+    dependencies?: unknown[];
+    body?: string;
+    [key: string]: unknown;
+}
+/**
+ * True when the given content field carries context on this item.
+ * - collection fields: `Array.isArray && length > 0`
+ * - "deps": maps to the `dependencies` array
+ * - "body": `typeof body === "string" && body.trim().length > 0`
+ * - "linked_command": `tests` array has at least one entry with a non-empty
+ *   string `command`
+ */
+export declare function isContentFieldPresent(item: ContentFieldItem, field: ContentField): boolean;
+/** Per-field selection: 'present' requires the field populated, 'absent' requires it empty. */
+export type ContentFieldSelection = "present" | "absent";
+/** Map of content fields to a present/absent requirement. */
+export type ContentFieldFilters = Partial<Record<ContentField, ContentFieldSelection>>;
+/** True when at least one content-field selection is requested. */
+export declare function hasContentFieldFilter(filters: ContentFieldFilters): boolean;
+/**
+ * Does a single item satisfy the requested content-field filters?
+ *
+ * AND semantics across all requested fields: each requested field must match
+ * its present/absent requirement. When no filter is requested the item passes.
+ */
+export declare function itemMatchesContentFilters(item: ContentFieldItem, filters: ContentFieldFilters): boolean;
+/** Filter a list of items by the requested content-field selections. */
+export declare function filterByContentFields<T extends ContentFieldItem>(items: readonly T[], filters: ContentFieldFilters): T[];
+/**
+ * Whether a content-field filter set requires the heavy collections to be
+ * loaded. True when any non-body field is requested (collections + tests'
+ * linked command all live in the heavy front-matter arrays).
+ */
+export declare function contentFiltersNeedCollections(filters: ContentFieldFilters): boolean;
+/** Whether a content-field filter set requires the item body to be loaded. */
+export declare function contentFiltersNeedBody(filters: ContentFieldFilters): boolean;
+/** Utilization of a single content field: present vs total, with a rounded percent. */
+export interface ContentFieldUtilization {
+    present: number;
+    total: number;
+    /** present/total * 100, rounded to one decimal; 100 when total is 0. */
+    percent: number;
+}
+/** Per-field utilization report for pm stats --field-utilization. */
+export interface ContentFieldUtilizationReport {
+    total_items: number;
+    /** Utilization keyed by content field (includes body and linked_command). */
+    fields: Record<ContentField, ContentFieldUtilization>;
+    /** Convenience alias mirroring GH-241: identical to `fields.body`. */
+    body_populated: ContentFieldUtilization;
+    /** Items with an empty body; `present` counts the empty-bodied items. */
+    empty_body: ContentFieldUtilization;
+}
+/**
+ * Compute content-field utilization across a list of items. For each field we
+ * report how many items populate it out of the total, plus a rounded
+ * percentage. Convenience `body_populated`/`empty_body` aliases mirror GH-241.
+ */
+export declare function computeContentFieldUtilization(items: readonly ContentFieldItem[]): ContentFieldUtilizationReport;

package/dist/core/governance/content-fields.js

@@ -0,0 +1,182 @@
+/**
+ * Content-field governance & utilization primitives.
+ *
+ * "Project management = context management": these primitives let agents query
+ * which items carry context (notes/learnings/files/docs/tests/comments/deps/
+ * body, plus whether a linked test carries a runnable command) and which do
+ * not. The surface powers content-field selection (pm list / pm update-many)
+ * and field-utilization reporting (pm stats --field-utilization).
+ *
+ * The module is pure: it performs no IO and imports no heavy runtime
+ * dependencies. Callers pass plain structural item shapes so the logic stays
+ * trivially testable.
+ */
+/** Stable rendering / iteration order for content fields. */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9104a56e-e446-53c0-83fe-fcf651a45a49")}catch(e){}}();
+export const CONTENT_FIELD_ORDER = [
+    "notes",
+    "learnings",
+    "files",
+    "docs",
+    "tests",
+    "comments",
+    "deps",
+    "body",
+    "linked_command",
+];
+/** True when `value` is a non-empty array. */
+function hasEntries(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+/** True when the body string carries non-whitespace content. */
+function hasBody(body) {
+    return typeof body === "string" && body.trim().length > 0;
+}
+/**
+ * True when at least one entry in the `tests` array carries a non-empty string
+ * `command`. Tolerant of non-object / non-string entries.
+ */
+function hasLinkedCommand(tests) {
+    if (!Array.isArray(tests)) {
+        return false;
+    }
+    return tests.some((entry) => {
+        if (typeof entry !== "object" || entry === null) {
+            return false;
+        }
+        const command = entry.command;
+        return typeof command === "string" && command.trim().length > 0;
+    });
+}
+/**
+ * True when the given content field carries context on this item.
+ * - collection fields: `Array.isArray && length > 0`
+ * - "deps": maps to the `dependencies` array
+ * - "body": `typeof body === "string" && body.trim().length > 0`
+ * - "linked_command": `tests` array has at least one entry with a non-empty
+ *   string `command`
+ */
+export function isContentFieldPresent(item, field) {
+    switch (field) {
+        case "notes":
+            return hasEntries(item.notes);
+        case "learnings":
+            return hasEntries(item.learnings);
+        case "files":
+            return hasEntries(item.files);
+        case "docs":
+            return hasEntries(item.docs);
+        case "tests":
+            return hasEntries(item.tests);
+        case "comments":
+            return hasEntries(item.comments);
+        case "deps":
+            return hasEntries(item.dependencies);
+        case "body":
+            return hasBody(item.body);
+        case "linked_command":
+            return hasLinkedCommand(item.tests);
+    }
+    // No default: every ContentField has an explicit case above, so TypeScript
+    // enforces exhaustiveness here — adding a new field without a case is a
+    // compile error rather than a silent fall-through (and no unreachable branch
+    // to dent the literal-100% coverage gate).
+}
+/** True when at least one content-field selection is requested. */
+export function hasContentFieldFilter(filters) {
+    return CONTENT_FIELD_ORDER.some((field) => filters[field] !== undefined);
+}
+/**
+ * Does a single item satisfy the requested content-field filters?
+ *
+ * AND semantics across all requested fields: each requested field must match
+ * its present/absent requirement. When no filter is requested the item passes.
+ */
+export function itemMatchesContentFilters(item, filters) {
+    for (const field of CONTENT_FIELD_ORDER) {
+        const selection = filters[field];
+        if (selection === undefined) {
+            continue;
+        }
+        const present = isContentFieldPresent(item, field);
+        if (selection === "present" && !present) {
+            return false;
+        }
+        if (selection === "absent" && present) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Filter a list of items by the requested content-field selections. */
+export function filterByContentFields(items, filters) {
+    if (!hasContentFieldFilter(filters)) {
+        return [...items];
+    }
+    return items.filter((item) => itemMatchesContentFilters(item, filters));
+}
+/**
+ * Whether a content-field filter set requires the heavy collections to be
+ * loaded. True when any non-body field is requested (collections + tests'
+ * linked command all live in the heavy front-matter arrays).
+ */
+export function contentFiltersNeedCollections(filters) {
+    return CONTENT_FIELD_ORDER.some((field) => field !== "body" && filters[field] !== undefined);
+}
+/** Whether a content-field filter set requires the item body to be loaded. */
+export function contentFiltersNeedBody(filters) {
+    return filters.body !== undefined;
+}
+/**
+ * Round present/total into a one-decimal percentage. Matches the convention in
+ * metadata-coverage.ts: a zero population reports 100 (nothing missing).
+ */
+function roundPercent(present, total) {
+    if (total === 0) {
+        return 100;
+    }
+    return Math.round((present / total) * 1000) / 10;
+}
+function emptyUtilizationFields() {
+    const record = {};
+    for (const field of CONTENT_FIELD_ORDER) {
+        record[field] = { present: 0, total: 0, percent: 100 };
+    }
+    return record;
+}
+/**
+ * Compute content-field utilization across a list of items. For each field we
+ * report how many items populate it out of the total, plus a rounded
+ * percentage. Convenience `body_populated`/`empty_body` aliases mirror GH-241.
+ */
+export function computeContentFieldUtilization(items) {
+    const fields = emptyUtilizationFields();
+    const total = items.length;
+    for (const item of items) {
+        for (const field of CONTENT_FIELD_ORDER) {
+            if (isContentFieldPresent(item, field)) {
+                fields[field].present += 1;
+            }
+        }
+    }
+    for (const field of CONTENT_FIELD_ORDER) {
+        fields[field].total = total;
+        fields[field].percent = roundPercent(fields[field].present, total);
+    }
+    const bodyPopulated = fields.body;
+    const emptyBodyCount = total - bodyPopulated.present;
+    const emptyBody = {
+        present: emptyBodyCount,
+        total,
+        percent: roundPercent(emptyBodyCount, total),
+    };
+    return {
+        total_items: total,
+        fields,
+        body_populated: bodyPopulated,
+        empty_body: emptyBody,
+    };
+}
+//# sourceMappingURL=content-fields.js.map
+//# debugId=9104a56e-e446-53c0-83fe-fcf651a45a49

package/dist/core/governance/content-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-fields.js","sources":["core/governance/content-fields.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Content-field governance & utilization primitives.\n *\n * \"Project management = context management\": these primitives let agents query\n * which items carry context (notes/learnings/files/docs/tests/comments/deps/\n * body, plus whether a linked test carries a runnable command) and which do\n * not. The surface powers content-field selection (pm list / pm update-many)\n * and field-utilization reporting (pm stats --field-utilization).\n *\n * The module is pure: it performs no IO and imports no heavy runtime\n * dependencies. Callers pass plain structural item shapes so the logic stays\n * trivially testable.\n */\n\n/** The content fields an item can carry context in. */\nexport type ContentField =\n  | \"notes\"\n  | \"learnings\"\n  | \"files\"\n  | \"docs\"\n  | \"tests\"\n  | \"comments\"\n  | \"deps\"\n  | \"body\"\n  | \"linked_command\";\n\n/** Stable rendering / iteration order for content fields. */\nexport const CONTENT_FIELD_ORDER: readonly ContentField[] = [\n  \"notes\",\n  \"learnings\",\n  \"files\",\n  \"docs\",\n  \"tests\",\n  \"comments\",\n  \"deps\",\n  \"body\",\n  \"linked_command\",\n] as const;\n\n/** Minimal structural shape needed: the collection arrays + optional body. */\nexport interface ContentFieldItem {\n  notes?: unknown[];\n  learnings?: unknown[];\n  files?: unknown[];\n  docs?: unknown[];\n  tests?: unknown[];\n  comments?: unknown[];\n  dependencies?: unknown[];\n  body?: string;\n  [key: string]: unknown;\n}\n\n/** True when `value` is a non-empty array. */\nfunction hasEntries(value: unknown): boolean {\n  return Array.isArray(value) && value.length > 0;\n}\n\n/** True when the body string carries non-whitespace content. */\nfunction hasBody(body: unknown): boolean {\n  return typeof body === \"string\" && body.trim().length > 0;\n}\n\n/**\n * True when at least one entry in the `tests` array carries a non-empty string\n * `command`. Tolerant of non-object / non-string entries.\n */\nfunction hasLinkedCommand(tests: unknown): boolean {\n  if (!Array.isArray(tests)) {\n    return false;\n  }\n  return tests.some((entry) => {\n    if (typeof entry !== \"object\" || entry === null) {\n      return false;\n    }\n    const command = (entry as { command?: unknown }).command;\n    return typeof command === \"string\" && command.trim().length > 0;\n  });\n}\n\n/**\n * True when the given content field carries context on this item.\n * - collection fields: `Array.isArray && length > 0`\n * - \"deps\": maps to the `dependencies` array\n * - \"body\": `typeof body === \"string\" && body.trim().length > 0`\n * - \"linked_command\": `tests` array has at least one entry with a non-empty\n *   string `command`\n */\nexport function isContentFieldPresent(item: ContentFieldItem, field: ContentField): boolean {\n  switch (field) {\n    case \"notes\":\n      return hasEntries(item.notes);\n    case \"learnings\":\n      return hasEntries(item.learnings);\n    case \"files\":\n      return hasEntries(item.files);\n    case \"docs\":\n      return hasEntries(item.docs);\n    case \"tests\":\n      return hasEntries(item.tests);\n    case \"comments\":\n      return hasEntries(item.comments);\n    case \"deps\":\n      return hasEntries(item.dependencies);\n    case \"body\":\n      return hasBody(item.body);\n    case \"linked_command\":\n      return hasLinkedCommand(item.tests);\n  }\n  // No default: every ContentField has an explicit case above, so TypeScript\n  // enforces exhaustiveness here — adding a new field without a case is a\n  // compile error rather than a silent fall-through (and no unreachable branch\n  // to dent the literal-100% coverage gate).\n}\n\n/** Per-field selection: 'present' requires the field populated, 'absent' requires it empty. */\nexport type ContentFieldSelection = \"present\" | \"absent\";\n\n/** Map of content fields to a present/absent requirement. */\nexport type ContentFieldFilters = Partial<Record<ContentField, ContentFieldSelection>>;\n\n/** True when at least one content-field selection is requested. */\nexport function hasContentFieldFilter(filters: ContentFieldFilters): boolean {\n  return CONTENT_FIELD_ORDER.some((field) => filters[field] !== undefined);\n}\n\n/**\n * Does a single item satisfy the requested content-field filters?\n *\n * AND semantics across all requested fields: each requested field must match\n * its present/absent requirement. When no filter is requested the item passes.\n */\nexport function itemMatchesContentFilters(item: ContentFieldItem, filters: ContentFieldFilters): boolean {\n  for (const field of CONTENT_FIELD_ORDER) {\n    const selection = filters[field];\n    if (selection === undefined) {\n      continue;\n    }\n    const present = isContentFieldPresent(item, field);\n    if (selection === \"present\" && !present) {\n      return false;\n    }\n    if (selection === \"absent\" && present) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/** Filter a list of items by the requested content-field selections. */\nexport function filterByContentFields<T extends ContentFieldItem>(\n  items: readonly T[],\n  filters: ContentFieldFilters,\n): T[] {\n  if (!hasContentFieldFilter(filters)) {\n    return [...items];\n  }\n  return items.filter((item) => itemMatchesContentFilters(item, filters));\n}\n\n/**\n * Whether a content-field filter set requires the heavy collections to be\n * loaded. True when any non-body field is requested (collections + tests'\n * linked command all live in the heavy front-matter arrays).\n */\nexport function contentFiltersNeedCollections(filters: ContentFieldFilters): boolean {\n  return CONTENT_FIELD_ORDER.some((field) => field !== \"body\" && filters[field] !== undefined);\n}\n\n/** Whether a content-field filter set requires the item body to be loaded. */\nexport function contentFiltersNeedBody(filters: ContentFieldFilters): boolean {\n  return filters.body !== undefined;\n}\n\n// ---------------------------------------------------------------------------\n// Field utilization\n// ---------------------------------------------------------------------------\n\n/** Utilization of a single content field: present vs total, with a rounded percent. */\nexport interface ContentFieldUtilization {\n  present: number;\n  total: number;\n  /** present/total * 100, rounded to one decimal; 100 when total is 0. */\n  percent: number;\n}\n\n/** Per-field utilization report for pm stats --field-utilization. */\nexport interface ContentFieldUtilizationReport {\n  total_items: number;\n  /** Utilization keyed by content field (includes body and linked_command). */\n  fields: Record<ContentField, ContentFieldUtilization>;\n  /** Convenience alias mirroring GH-241: identical to `fields.body`. */\n  body_populated: ContentFieldUtilization;\n  /** Items with an empty body; `present` counts the empty-bodied items. */\n  empty_body: ContentFieldUtilization;\n}\n\n/**\n * Round present/total into a one-decimal percentage. Matches the convention in\n * metadata-coverage.ts: a zero population reports 100 (nothing missing).\n */\nfunction roundPercent(present: number, total: number): number {\n  if (total === 0) {\n    return 100;\n  }\n  return Math.round((present / total) * 1000) / 10;\n}\n\nfunction emptyUtilizationFields(): Record<ContentField, ContentFieldUtilization> {\n  const record = {} as Record<ContentField, ContentFieldUtilization>;\n  for (const field of CONTENT_FIELD_ORDER) {\n    record[field] = { present: 0, total: 0, percent: 100 };\n  }\n  return record;\n}\n\n/**\n * Compute content-field utilization across a list of items. For each field we\n * report how many items populate it out of the total, plus a rounded\n * percentage. Convenience `body_populated`/`empty_body` aliases mirror GH-241.\n */\nexport function computeContentFieldUtilization(\n  items: readonly ContentFieldItem[],\n): ContentFieldUtilizationReport {\n  const fields = emptyUtilizationFields();\n  const total = items.length;\n  for (const item of items) {\n    for (const field of CONTENT_FIELD_ORDER) {\n      if (isContentFieldPresent(item, field)) {\n        fields[field].present += 1;\n      }\n    }\n  }\n  for (const field of CONTENT_FIELD_ORDER) {\n    fields[field].total = total;\n    fields[field].percent = roundPercent(fields[field].present, total);\n  }\n  const bodyPopulated = fields.body;\n  const emptyBodyCount = total - bodyPopulated.present;\n  const emptyBody: ContentFieldUtilization = {\n    present: emptyBodyCount,\n    total,\n    percent: roundPercent(emptyBodyCount, total),\n  };\n  return {\n    total_items: total,\n    fields,\n    body_populated: bodyPopulated,\n    empty_body: emptyBody,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"9104a56e-e446-53c0-83fe-fcf651a45a49"}

package/dist/core/governance/issue-codes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Logical issue-code governance primitives (GH-235).
+ *
+ * Trackers frequently adopt a title convention that embeds a logical issue
+ * code at the START of the title, e.g. `ISSUE-004: ...`, `BUG-12 ...`,
+ * `TASK-7 — ...`, `ADR-001`, `RFC-9`. When two distinct items share the same
+ * logical code, auditability and duplicate detection both suffer: a human or
+ * agent searching for "ISSUE-004" can no longer assume a single canonical item.
+ *
+ * These primitives detect that condition. They are pure: no IO, no heavy
+ * runtime dependencies. Callers pass plain structural item shapes so the logic
+ * stays trivially unit-testable.
+ */
+/** Minimal structural shape needed to detect duplicate issue codes. */
+export interface IssueCodeItem {
+    id: string;
+    title?: string | null;
+}
+/** A logical issue code shared by two or more items. */
+export interface DuplicateIssueCode {
+    /** The canonical (normalized, upper-case) issue code, e.g. `ISSUE-004`. */
+    code: string;
+    /** How many items carry this code. */
+    count: number;
+    /** The ids of the items carrying this code, sorted ascending. */
+    ids: string[];
+    /** The titles of the items carrying this code, in the same order as `ids`. */
+    titles: string[];
+}
+/**
+ * Extract the leading logical issue code from a title, or `null` when the title
+ * does not begin with one. The title is trimmed and upper-cased before matching
+ * so case differences (`issue-004` vs `ISSUE-004`) collapse to one logical
+ * code; the returned code is therefore always normalized upper-case.
+ *
+ * Accepts unknown-ish input defensively (exported helper SDK consumers may call
+ * from untyped JS): a non-string or empty title resolves to `null`.
+ */
+export declare function extractIssueCode(title: string | null | undefined): string | null;
+/**
+ * Find logical issue codes used by 2+ items. Any item whose title begins with a
+ * conventional issue code contributes; codes used by a single item are not
+ * reported. Status is intentionally NOT considered — a closed item and an open
+ * item sharing a code still collide for audit purposes, so both are flagged.
+ *
+ * Results are deterministic: duplicate groups are sorted by code, and the
+ * `ids`/`titles` within each group are sorted by id. The first-seen title for a
+ * given (id) is used; duplicate ids (should not occur for a valid corpus) are
+ * de-duplicated so an item never inflates its own code's count.
+ */
+export declare function findDuplicateIssueCodes(items: readonly IssueCodeItem[]): DuplicateIssueCode[];

package/dist/core/governance/issue-codes.js

@@ -0,0 +1,95 @@
+/**
+ * Logical issue-code governance primitives (GH-235).
+ *
+ * Trackers frequently adopt a title convention that embeds a logical issue
+ * code at the START of the title, e.g. `ISSUE-004: ...`, `BUG-12 ...`,
+ * `TASK-7 — ...`, `ADR-001`, `RFC-9`. When two distinct items share the same
+ * logical code, auditability and duplicate detection both suffer: a human or
+ * agent searching for "ISSUE-004" can no longer assume a single canonical item.
+ *
+ * These primitives detect that condition. They are pure: no IO, no heavy
+ * runtime dependencies. Callers pass plain structural item shapes so the logic
+ * stays trivially unit-testable.
+ */
+/**
+ * Match a conventional leading logical issue code: an upper-case alphanumeric
+ * prefix (starting with a letter) followed by a `-` separator and a number, at
+ * the very start of the title (after optional leading whitespace).
+ *
+ * Examples that match: `ISSUE-004`, `BUG-12`, `TASK-7`, `ADR-001`, `RFC-9`,
+ * `GH-235`, `PM2-14`. The trailing `\b` requires the digit run to end at a word
+ * boundary, so `ISSUE-004-extra` extracts `ISSUE-004` while `ISSUE-004foo`
+ * (digit immediately followed by a letter — no boundary) does not match.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="54a05400-cb4b-54af-990a-287fd34789f8")}catch(e){}}();
+const ISSUE_CODE_PATTERN = /^([A-Z][A-Z0-9]*-\d+)\b/;
+/**
+ * Extract the leading logical issue code from a title, or `null` when the title
+ * does not begin with one. The title is trimmed and upper-cased before matching
+ * so case differences (`issue-004` vs `ISSUE-004`) collapse to one logical
+ * code; the returned code is therefore always normalized upper-case.
+ *
+ * Accepts unknown-ish input defensively (exported helper SDK consumers may call
+ * from untyped JS): a non-string or empty title resolves to `null`.
+ */
+export function extractIssueCode(title) {
+    if (typeof title !== "string") {
+        return null;
+    }
+    const normalized = title.trim().toUpperCase();
+    if (normalized.length === 0) {
+        return null;
+    }
+    const match = ISSUE_CODE_PATTERN.exec(normalized);
+    return match ? match[1] : null;
+}
+/**
+ * Find logical issue codes used by 2+ items. Any item whose title begins with a
+ * conventional issue code contributes; codes used by a single item are not
+ * reported. Status is intentionally NOT considered — a closed item and an open
+ * item sharing a code still collide for audit purposes, so both are flagged.
+ *
+ * Results are deterministic: duplicate groups are sorted by code, and the
+ * `ids`/`titles` within each group are sorted by id. The first-seen title for a
+ * given (id) is used; duplicate ids (should not occur for a valid corpus) are
+ * de-duplicated so an item never inflates its own code's count.
+ */
+export function findDuplicateIssueCodes(items) {
+    const byCode = new Map();
+    for (const item of items) {
+        // A non-string title can never carry a code, so skip it before extraction;
+        // this also guarantees every stored title below is a real string.
+        if (typeof item.title !== "string") {
+            continue;
+        }
+        const code = extractIssueCode(item.title);
+        if (code === null) {
+            continue;
+        }
+        let entries = byCode.get(code);
+        if (!entries) {
+            entries = [];
+            byCode.set(code, entries);
+        }
+        if (!entries.some((entry) => entry.id === item.id)) {
+            entries.push({ id: item.id, title: item.title });
+        }
+    }
+    const duplicates = [];
+    for (const [code, entries] of byCode) {
+        if (entries.length < 2) {
+            continue;
+        }
+        const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id));
+        duplicates.push({
+            code,
+            count: sorted.length,
+            ids: sorted.map((entry) => entry.id),
+            titles: sorted.map((entry) => entry.title),
+        });
+    }
+    return duplicates.sort((left, right) => left.code.localeCompare(right.code));
+}
+//# sourceMappingURL=issue-codes.js.map
+//# debugId=54a05400-cb4b-54af-990a-287fd34789f8

package/dist/core/governance/issue-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-codes.js","sources":["core/governance/issue-codes.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Logical issue-code governance primitives (GH-235).\n *\n * Trackers frequently adopt a title convention that embeds a logical issue\n * code at the START of the title, e.g. `ISSUE-004: ...`, `BUG-12 ...`,\n * `TASK-7 — ...`, `ADR-001`, `RFC-9`. When two distinct items share the same\n * logical code, auditability and duplicate detection both suffer: a human or\n * agent searching for \"ISSUE-004\" can no longer assume a single canonical item.\n *\n * These primitives detect that condition. They are pure: no IO, no heavy\n * runtime dependencies. Callers pass plain structural item shapes so the logic\n * stays trivially unit-testable.\n */\n\n/** Minimal structural shape needed to detect duplicate issue codes. */\nexport interface IssueCodeItem {\n  id: string;\n  title?: string | null;\n}\n\n/** A logical issue code shared by two or more items. */\nexport interface DuplicateIssueCode {\n  /** The canonical (normalized, upper-case) issue code, e.g. `ISSUE-004`. */\n  code: string;\n  /** How many items carry this code. */\n  count: number;\n  /** The ids of the items carrying this code, sorted ascending. */\n  ids: string[];\n  /** The titles of the items carrying this code, in the same order as `ids`. */\n  titles: string[];\n}\n\n/**\n * Match a conventional leading logical issue code: an upper-case alphanumeric\n * prefix (starting with a letter) followed by a `-` separator and a number, at\n * the very start of the title (after optional leading whitespace).\n *\n * Examples that match: `ISSUE-004`, `BUG-12`, `TASK-7`, `ADR-001`, `RFC-9`,\n * `GH-235`, `PM2-14`. The trailing `\\b` requires the digit run to end at a word\n * boundary, so `ISSUE-004-extra` extracts `ISSUE-004` while `ISSUE-004foo`\n * (digit immediately followed by a letter — no boundary) does not match.\n */\nconst ISSUE_CODE_PATTERN = /^([A-Z][A-Z0-9]*-\\d+)\\b/;\n\n/**\n * Extract the leading logical issue code from a title, or `null` when the title\n * does not begin with one. The title is trimmed and upper-cased before matching\n * so case differences (`issue-004` vs `ISSUE-004`) collapse to one logical\n * code; the returned code is therefore always normalized upper-case.\n *\n * Accepts unknown-ish input defensively (exported helper SDK consumers may call\n * from untyped JS): a non-string or empty title resolves to `null`.\n */\nexport function extractIssueCode(title: string | null | undefined): string | null {\n  if (typeof title !== \"string\") {\n    return null;\n  }\n  const normalized = title.trim().toUpperCase();\n  if (normalized.length === 0) {\n    return null;\n  }\n  const match = ISSUE_CODE_PATTERN.exec(normalized);\n  return match ? match[1] : null;\n}\n\n/**\n * Find logical issue codes used by 2+ items. Any item whose title begins with a\n * conventional issue code contributes; codes used by a single item are not\n * reported. Status is intentionally NOT considered — a closed item and an open\n * item sharing a code still collide for audit purposes, so both are flagged.\n *\n * Results are deterministic: duplicate groups are sorted by code, and the\n * `ids`/`titles` within each group are sorted by id. The first-seen title for a\n * given (id) is used; duplicate ids (should not occur for a valid corpus) are\n * de-duplicated so an item never inflates its own code's count.\n */\nexport function findDuplicateIssueCodes(items: readonly IssueCodeItem[]): DuplicateIssueCode[] {\n  const byCode = new Map<string, Array<{ id: string; title: string }>>();\n  for (const item of items) {\n    // A non-string title can never carry a code, so skip it before extraction;\n    // this also guarantees every stored title below is a real string.\n    if (typeof item.title !== \"string\") {\n      continue;\n    }\n    const code = extractIssueCode(item.title);\n    if (code === null) {\n      continue;\n    }\n    let entries = byCode.get(code);\n    if (!entries) {\n      entries = [];\n      byCode.set(code, entries);\n    }\n    if (!entries.some((entry) => entry.id === item.id)) {\n      entries.push({ id: item.id, title: item.title });\n    }\n  }\n\n  const duplicates: DuplicateIssueCode[] = [];\n  for (const [code, entries] of byCode) {\n    if (entries.length < 2) {\n      continue;\n    }\n    const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id));\n    duplicates.push({\n      code,\n      count: sorted.length,\n      ids: sorted.map((entry) => entry.id),\n      titles: sorted.map((entry) => entry.title),\n    });\n  }\n  return duplicates.sort((left, right) => left.code.localeCompare(right.code));\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH;;;;;;;;;GASG;;;AACH,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAgC;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAA+B;IACrE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgD,CAAC;IACvE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,2EAA2E;QAC3E,kEAAkE;QAClE,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACnC,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,SAAS;QACX,CAAC;QACD,IAAI,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAyB,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QACnF,UAAU,CAAC,IAAI,CAAC;YACd,IAAI;YACJ,KAAK,EAAE,MAAM,CAAC,MAAM;YACpB,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YACpC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;SAC3C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/E,CAAC","debugId":"54a05400-cb4b-54af-990a-287fd34789f8"}

package/dist/core/governance/metadata-coverage.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Metadata governance & coverage observability primitives.
+ *
+ * One dependency-light module that powers the whole metadata-governance
+ * surface: missing-field selection (pm list / pm update-many), coverage
+ * percentages (pm stats --metadata-coverage / pm validate), and grouped
+ * lifecycle breakdowns (pm stats --by-assignee/--by-tag/--by-priority,
+ * pm aggregate explicit labels).
+ *
+ * The module is pure: it performs no IO and imports no heavy runtime
+ * dependencies. Lifecycle semantics are injected via a {@link LifecycleClassifier}
+ * so callers map their runtime status registry to lifecycle buckets while the
+ * pure logic here stays trivially testable with a fake classifier.
+ */
+/** Minimal structural shape this module needs from an item's front matter. */
+export interface CoverageItem {
+    type: string;
+    status: string;
+    assignee?: string;
+    tags?: string[];
+    parent?: string;
+    priority?: number;
+    acceptance_criteria?: string;
+    estimated_minutes?: number;
+    resolution?: string;
+    reviewer?: string;
+    risk?: string;
+    /** Confidence is a string-like enum or a numeric score depending on workspace. */
+    confidence?: string | number;
+    sprint?: string;
+    release?: string;
+    [key: string]: unknown;
+}
+/** Lifecycle buckets used by grouped breakdowns and distributions. */
+export type LifecycleBucket = "open" | "in_progress" | "blocked" | "draft" | "closed" | "canceled" | "other";
+/** Stable rendering order for lifecycle buckets. */
+export declare const LIFECYCLE_BUCKET_ORDER: readonly LifecycleBucket[];
+/**
+ * Classifies a raw status string into a lifecycle bucket and reports whether a
+ * status is terminal (closed/canceled). Callers build this from their resolved
+ * runtime status registry via {@link lifecycleClassifierFromStatusRegistry}.
+ */
+export interface LifecycleClassifier {
+    classify(status: string): LifecycleBucket;
+    isTerminal(status: string): boolean;
+}
+/** The subset of a resolved runtime status registry this module consumes. */
+export interface StatusRegistryLike {
+    alias_to_id: Map<string, string>;
+    terminal_statuses: Set<string>;
+    terminal_canceled_statuses: Set<string>;
+    blocked_statuses: Set<string>;
+    draft_statuses: Set<string>;
+    active_statuses: Set<string>;
+    open_status: string;
+}
+/**
+ * Adapt a resolved runtime status registry into a {@link LifecycleClassifier}.
+ *
+ * Precedence is deliberate and disjoint: canceled → closed → blocked → draft →
+ * open → in_progress (active but not the default open status) → other.
+ */
+export declare function lifecycleClassifierFromStatusRegistry(registry: StatusRegistryLike): LifecycleClassifier;
+/** True when an item has no non-empty acceptance_criteria. */
+export declare function isAcMissing(item: CoverageItem): boolean;
+/** True when an item has no finite estimated_minutes. */
+export declare function isEstimateMissing(item: CoverageItem): boolean;
+/**
+ * True when a terminal (closed/canceled) item has no non-empty resolution.
+ * Resolution is only expected on terminal items, so open items are never
+ * considered "resolution-missing".
+ */
+export declare function isResolutionMissing(item: CoverageItem, classifier: LifecycleClassifier): boolean;
+/** True when an item has no non-empty reviewer. */
+export declare function isReviewerMissing(item: CoverageItem): boolean;
+/** True when an item has no non-empty risk level. */
+export declare function isRiskMissing(item: CoverageItem): boolean;
+/**
+ * True when an item has no confidence value. Confidence is a string-like enum
+ * or a numeric score depending on workspace, so a finite number counts as
+ * present and only blank/absent values are treated as missing.
+ */
+export declare function isConfidenceMissing(item: CoverageItem): boolean;
+/** True when an item has no non-empty sprint. */
+export declare function isSprintMissing(item: CoverageItem): boolean;
+/** True when an item has no non-empty release. */
+export declare function isReleaseMissing(item: CoverageItem): boolean;
+/** Selection flags for {@link filterMissingMetadata}. */
+export interface MissingMetadataFilters {
+    acMissing?: boolean;
+    estimatesMissing?: boolean;
+    resolutionMissing?: boolean;
+    reviewerMissing?: boolean;
+    riskMissing?: boolean;
+    confidenceMissing?: boolean;
+    sprintMissing?: boolean;
+    releaseMissing?: boolean;
+    /** Match items missing ANY of the tracked metadata fields (union). */
+    metadataMissing?: boolean;
+}
+/** True when any missing-metadata filter is requested. */
+export declare function hasMissingMetadataFilter(filters: MissingMetadataFilters): boolean;
+/**
+ * Does a single item satisfy the requested missing-metadata filters?
+ *
+ * Specific flags (acMissing/estimatesMissing/resolutionMissing plus the
+ * governance flags reviewerMissing/riskMissing/confidenceMissing/sprintMissing/
+ * releaseMissing) are ANDed together so callers can narrow precisely.
+ * `metadataMissing` is ORed in as a union shortcut for "missing any of the
+ * core tracked fields" (acceptance_criteria/estimated_minutes/resolution); it
+ * deliberately excludes the governance fields so the long-standing flag keeps
+ * its original meaning. When no filter is requested the item passes.
+ */
+export declare function itemMatchesMissingMetadata(item: CoverageItem, filters: MissingMetadataFilters, classifier: LifecycleClassifier): boolean;
+/** Filter a list of items by the requested missing-metadata predicates. */
+export declare function filterMissingMetadata<T extends CoverageItem>(items: readonly T[], filters: MissingMetadataFilters, classifier: LifecycleClassifier): T[];
+/** Coverage-tracked metadata fields. */
+export type CoverageField = "acceptance_criteria" | "estimated_minutes" | "resolution" | "tags" | "parent";
+/** Stable ordering of coverage fields for rendering. */
+export declare const COVERAGE_FIELD_ORDER: readonly CoverageField[];
+/** Coverage of a single field: present vs applicable, with a rounded percent. */
+export interface FieldCoverage {
+    present: number;
+    /** Items for which the field is expected (all items, except resolution = terminal only). */
+    applicable: number;
+    /** present/applicable * 100, rounded to one decimal; 100 when applicable is 0. */
+    percent: number;
+}
+export interface MetadataCoverageReport {
+    overall: Record<CoverageField, FieldCoverage>;
+    by_type: Record<string, Record<CoverageField, FieldCoverage>>;
+}
+/**
+ * Compute metadata coverage overall and per item type. For each tracked field
+ * we report present/applicable counts and a rounded percentage. Resolution is
+ * scoped to terminal items (its only applicable population).
+ */
+export declare function computeMetadataCoverage(items: readonly CoverageItem[], classifier: LifecycleClassifier): MetadataCoverageReport;
+/** Dimensions a breakdown can group by. */
+export type GroupDimension = "assignee" | "priority" | "tag" | "parent" | "type" | "status";
+/** Explicit label for an empty/blank group value for a given dimension. */
+export declare function emptyGroupLabel(dimension: GroupDimension): string;
+export interface GroupRow {
+    /** Display label; explicit "(unassigned)"-style label for blank keys. */
+    label: string;
+    /** Stable structured key (null for the empty/blank group). */
+    key: string | null;
+    buckets: Record<LifecycleBucket, number>;
+    total: number;
+}
+export interface GroupedBreakdown {
+    dimension: GroupDimension;
+    rows: GroupRow[];
+    /** Distinct items observed (an item can contribute to multiple tag rows). */
+    total_items: number;
+}
+export interface GroupOptions {
+    /** For dimension="tag": only consider tags starting with this prefix. */
+    tagPrefix?: string;
+}
+/**
+ * Group items by a dimension into lifecycle-bucketed rows. Blank keys render
+ * with an explicit "(unassigned)"-style label. Rows are sorted by total
+ * descending, then label ascending, with the empty group sorted last on ties.
+ */
+export declare function groupItemsByDimension(items: readonly CoverageItem[], dimension: GroupDimension, classifier: LifecycleClassifier, options?: GroupOptions): GroupedBreakdown;
+/** Lifecycle-bucket distribution across all items (for stats lifecycle section). */
+export declare function computeLifecycleDistribution(items: readonly CoverageItem[], classifier: LifecycleClassifier): Record<LifecycleBucket, number>;