@open-agent-toolkit/cli 0.1.40 → 0.1.42

package/dist/commands/pjm/doctor.js

@@ -1,5 +1,6 @@
 import { access, readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { BACKLOG_ITEM_STATUSES, extractBacklogStatus, isTerminalBacklogStatus, isValidBacklogStatus, } from '../backlog/shared/item-status.js';
 import { getFrontmatterBlock } from '../shared/frontmatter.js';
 import { CANONICAL_REPO_REFERENCE_PATHS } from './init.js';
 const ALLOWED_TOP_LEVEL_DIRECTORIES = new Set([
@@ -108,6 +109,45 @@ function containsTemplateFrontmatter(content) {
         (/\boat_template\s*:/i.test(frontmatter) ||
             /\boat_template_name\s*:/i.test(frontmatter)));
 }
+const BACKLOG_ITEMS_DIRECTORY = 'pjm/backlog/items';
+const BACKLOG_ARCHIVED_DIRECTORY = 'pjm/backlog/archived';
+const BACKLOG_COMPLETED_FILE = 'pjm/backlog/completed.md';
+// Best-effort backlog id scan: `BL-YYMMDD-slug` (legacy lowercase `bl-`
+// matched case-insensitively). The six-digit requirement keeps the literal
+// `BL-YYMMDD-slug` format placeholder in `completed.md` from matching.
+const BACKLOG_ID_PATTERN = /\bbl-\d{6}-[a-z0-9][a-z0-9-]*/gi;
+/**
+ * Single frontmatter pass over both backlog directories. Every drift check
+ * derives from this scan so the filesystem is walked once. `index.md` is the
+ * managed index, not an item, so it is excluded.
+ */
+async function collectBacklogItems(repoRoot) {
+    const records = [];
+    const directories = [
+        { directory: 'items', relativeDir: BACKLOG_ITEMS_DIRECTORY },
+        { directory: 'archived', relativeDir: BACKLOG_ARCHIVED_DIRECTORY },
+    ];
+    for (const { directory, relativeDir } of directories) {
+        const fileNames = await listMarkdownFiles(join(repoRoot, relativeDir));
+        for (const fileName of fileNames) {
+            if (fileName === 'index.md') {
+                continue;
+            }
+            const content = await readIfExists(join(repoRoot, relativeDir, fileName));
+            records.push({
+                directory,
+                relativePath: `${relativeDir}/${fileName}`,
+                id: fileName.replace(/\.md$/, ''),
+                status: content ? extractBacklogStatus(content) : null,
+            });
+        }
+    }
+    return records;
+}
+/** Best-effort scan of completed-log content for backlog item ids. */
+function extractCompletedIds(content) {
+    return [...content.matchAll(BACKLOG_ID_PATTERN)].map((match) => match[0]);
+}
 function checkStatus(missing) {
     return missing.length === 0 ? 'pass' : 'fail';
 }
@@ -246,5 +286,126 @@ export async function runPjmDoctorChecks(repoRoot, options = {}) {
             ? undefined
             : 'Move active operational docs to pjm/ and leave reference/ for durable append-mostly artifacts.',
     });
+    const backlogItems = await collectBacklogItems(repoRoot);
+    const terminalInItems = backlogItems
+        .filter((item) => item.directory === 'items' &&
+        item.status !== null &&
+        isTerminalBacklogStatus(item.status))
+        .map((item) => item.relativePath);
+    checks.push({
+        name: 'pjm:backlog_terminal_in_items',
+        description: 'Terminal-status backlog items awaiting archive',
+        status: checkStatus(terminalInItems),
+        message: terminalInItems.length === 0
+            ? 'No terminal-status backlog items remain under items/.'
+            : `Terminal-status backlog items still under items/: ${terminalInItems.join(', ')}`,
+        fix: terminalInItems.length === 0
+            ? undefined
+            : 'Run `oat backlog archive <id>` to move each closed/wont_do item into archived/.',
+    });
+    // A missing/empty `status:` is as much a drift as an out-of-enum value: the
+    // `oat backlog archive` command rejects both, so `pjm doctor` must surface
+    // both rather than leaving status-less items silently invisible.
+    const missingStatusItems = backlogItems
+        .filter((item) => item.status === null || item.status.trim() === '')
+        .map((item) => item.relativePath);
+    const outOfEnumStatusItems = backlogItems
+        .filter((item) => item.status !== null &&
+        item.status.trim() !== '' &&
+        !isValidBacklogStatus(item.status))
+        .map((item) => item.relativePath);
+    const invalidStatus = [...outOfEnumStatusItems, ...missingStatusItems];
+    const invalidStatusDetails = [];
+    if (outOfEnumStatusItems.length > 0) {
+        invalidStatusDetails.push(`out-of-enum status: ${outOfEnumStatusItems.join(', ')}`);
+    }
+    if (missingStatusItems.length > 0) {
+        invalidStatusDetails.push(`missing status: ${missingStatusItems.join(', ')}`);
+    }
+    checks.push({
+        name: 'pjm:backlog_invalid_status',
+        description: 'Backlog items with a missing or out-of-enum status',
+        status: checkStatus(invalidStatus),
+        message: invalidStatus.length === 0
+            ? 'All backlog item statuses are within the valid enum.'
+            : `Backlog items with an invalid status (${invalidStatusDetails.join('; ')}). Valid statuses: ${BACKLOG_ITEM_STATUSES.join(', ')}.`,
+        fix: invalidStatus.length === 0
+            ? undefined
+            : `Set a valid status (${BACKLOG_ITEM_STATUSES.join(', ')}) on each listed item.`,
+    });
+    const archivedOpen = backlogItems
+        .filter((item) => item.directory === 'archived' &&
+        item.status !== null &&
+        isValidBacklogStatus(item.status) &&
+        !isTerminalBacklogStatus(item.status))
+        .map((item) => item.relativePath);
+    checks.push({
+        name: 'pjm:backlog_archived_open',
+        description: 'Archived backlog items with a non-terminal status',
+        status: warnStatus(archivedOpen),
+        message: archivedOpen.length === 0
+            ? 'No archived backlog items carry an open status.'
+            : `Archived backlog items still marked open/in_progress: ${archivedOpen.join(', ')}`,
+        fix: archivedOpen.length === 0
+            ? undefined
+            : 'Set a terminal status (closed/wont_do) on each archived item, or move it back under items/.',
+    });
+    // A single id must never live in both `items/` and `archived/`: the live copy
+    // shadows the archived record and `oat backlog archive` refuses to reconcile
+    // it automatically (auto-archiving would clobber the archived file). Derive
+    // from the same single scan so the filesystem is not re-walked.
+    const backlogPathsByIdAndDir = new Map();
+    for (const item of backlogItems) {
+        const key = item.id.toLowerCase();
+        const entry = backlogPathsByIdAndDir.get(key) ?? {};
+        entry[item.directory] = item.relativePath;
+        backlogPathsByIdAndDir.set(key, entry);
+    }
+    const duplicateIdPairs = [];
+    for (const entry of backlogPathsByIdAndDir.values()) {
+        if (entry.items && entry.archived) {
+            duplicateIdPairs.push(`${entry.items} + ${entry.archived}`);
+        }
+    }
+    checks.push({
+        name: 'pjm:backlog_duplicate_id',
+        description: 'Backlog ids present in both items/ and archived/',
+        status: checkStatus(duplicateIdPairs),
+        message: duplicateIdPairs.length === 0
+            ? 'No backlog id is present in both items/ and archived/.'
+            : `Backlog ids present in both items/ and archived/: ${duplicateIdPairs.join('; ')}`,
+        fix: duplicateIdPairs.length === 0
+            ? undefined
+            : 'Reconcile each duplicate manually: decide whether the active (items/) or archived copy is authoritative, remove the other, then re-run `oat backlog archive <id>` if the item still needs archiving.',
+    });
+    const itemPathsById = new Map();
+    for (const item of backlogItems) {
+        if (item.directory === 'items') {
+            itemPathsById.set(item.id.toLowerCase(), item.relativePath);
+        }
+    }
+    const completedContent = await readIfExists(join(repoRoot, BACKLOG_COMPLETED_FILE));
+    const completedUnarchived = [];
+    const seenUnarchived = new Set();
+    if (completedContent) {
+        for (const completedId of extractCompletedIds(completedContent)) {
+            const relativePath = itemPathsById.get(completedId.toLowerCase());
+            if (relativePath && !seenUnarchived.has(relativePath)) {
+                seenUnarchived.add(relativePath);
+                completedUnarchived.push(relativePath);
+            }
+        }
+    }
+    checks.push({
+        name: 'pjm:backlog_completed_unarchived',
+        description: 'Completed-log entries whose item file is still under items/',
+        status: warnStatus(completedUnarchived),
+        message: completedUnarchived.length === 0
+            ? 'No completed backlog entries reference an item still under items/.'
+            : `Completed log references items still under items/: ${completedUnarchived.join(', ')}`,
+        fix: completedUnarchived.length === 0
+            ? undefined
+            : 'Run `oat backlog archive <id>` to archive each completed item still under items/.',
+    });
     return checks;
 }

package/dist/commands/pjm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAiBnE,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA6FD,wBAAgB,gBAAgB,CAC9B,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CAsJT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAA0B,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAiBnE,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA6FD,wBAAgB,gBAAgB,CAC9B,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CAuJT"}

package/dist/commands/pjm/index.js

@@ -7,7 +7,7 @@ import { resolveProjectRoot } from '../../fs/paths.js';
 import { formatDoctorResults } from '../../ui/output.js';
 import { Command } from 'commander';
 import { runPjmDoctorChecks } from './doctor.js';
-import { initializeRepoReference } from './init.js';
+import { initializeRepoReference, INSTRUCTIONS_SYNC_HINT } from './init.js';
 import { migratePjmRepo, readPjmMigrationPrompt } from './migrate.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
@@ -111,6 +111,7 @@ export function createPjmCommand(overrides = {}) {
                 if (result.skipped.length > 0) {
                     context.logger.info(`Skipped existing: ${result.skipped.join(', ')}`);
                 }
+                context.logger.info(INSTRUCTIONS_SYNC_HINT);
             }
             process.exitCode = 0;
         }

package/dist/commands/pjm/init.d.ts

@@ -8,6 +8,7 @@ export interface RepoReferenceInitResult {
     created: string[];
     skipped: string[];
 }
-export declare const CANONICAL_REPO_REFERENCE_PATHS: readonly [...("AGENTS.md" | "pjm/AGENTS.md" | "pjm/current-state.md" | "pjm/roadmap.md" | "reference/AGENTS.md")[], "pjm/backlog/index.md", "pjm/backlog/completed.md", "pjm/backlog/items/.gitkeep", "pjm/backlog/archived/.gitkeep", "reference/decisions/index.md"];
+export declare const INSTRUCTIONS_SYNC_HINT: string;
+export declare const CANONICAL_REPO_REFERENCE_PATHS: readonly [...("AGENTS.md" | "pjm/AGENTS.md" | "pjm/current-state.md" | "pjm/roadmap.md" | "reference/AGENTS.md" | "README.md" | "pjm/handoffs/README.md")[], "pjm/backlog/index.md", "pjm/backlog/completed.md", "pjm/backlog/items/.gitkeep", "pjm/backlog/archived/.gitkeep", "reference/decisions/index.md"];
 export declare function initializeRepoReference(options: InitializeRepoReferenceOptions): Promise<RepoReferenceInitResult>;
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/pjm/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAwBD,eAAO,MAAM,8BAA8B,wQAIjC,CAAC;AAyEX,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAgElC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAoBD,eAAO,MAAM,sBAAsB,QAEiD,CAAC;AAWrF,eAAO,MAAM,8BAA8B,iTAIjC,CAAC;AAyEX,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAgElC"}

package/dist/commands/pjm/init.js

@@ -9,7 +9,14 @@ const TEMPLATE_TARGETS = [
     { template: 'current-state.md', target: 'pjm/current-state.md' },
     { template: 'roadmap.md', target: 'pjm/roadmap.md' },
     { template: 'reference-agents.md', target: 'reference/AGENTS.md' },
+    { template: 'repo-readme.md', target: 'README.md' },
+    { template: 'pjm-handoffs-readme.md', target: 'pjm/handoffs/README.md' },
 ];
+// Next-step hint printed after init/backfill. `oat pjm init` never writes
+// CLAUDE.md shims itself — strategy ownership stays with `oat instructions
+// sync`, so we point the operator at it (with the `--dry-run` preview).
+export const INSTRUCTIONS_SYNC_HINT = 'Next step: run `oat instructions sync` to create CLAUDE.md shims for the ' +
+    'repo-reference AGENTS.md files (preview with `oat instructions sync --dry-run`).';
 const BACKLOG_PATHS = [
     'pjm/backlog/index.md',
     'pjm/backlog/completed.md',

package/dist/commands/review/latest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"latest.d.ts","sourceRoot":"","sources":["../../../src/commands/review/latest.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAQD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACnE;AAmID,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAqF9B;AA+CD,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CAkBT"}
+{"version":3,"file":"latest.d.ts","sourceRoot":"","sources":["../../../src/commands/review/latest.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAQD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACnE;AAsID,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAqF9B;AA+CD,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CAkBT"}

package/dist/commands/review/latest.js

@@ -1,7 +1,7 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { isAbsolute, join, relative } from 'node:path';
 import { buildCommandContext, } from '../../app/command-context.js';
-import { getFrontmatterBlock, getFrontmatterField, } from '../shared/frontmatter.js';
+import { getFrontmatterBlock, getFrontmatterField, parseGeneratedTime, } from '../shared/frontmatter.js';
 import { readGlobalOptions } from '../shared/shared.utils.js';
 import { readOatLocalConfig } from '../../config/oat-config.js';
 import { normalizeToPosixPath, resolveProjectRoot } from '../../fs/paths.js';
@@ -72,7 +72,7 @@ async function readReviewCandidate(repoRoot, relativePath, kind, priority, archi
     if (!generatedAt) {
         return null;
     }
-    const generatedTime = Date.parse(generatedAt);
+    const generatedTime = parseGeneratedTime(generatedAt);
     if (Number.isNaN(generatedTime)) {
         return null;
     }
@@ -99,6 +99,9 @@ function sortReviewCandidates(a, b) {
     if (a.lifecycleRank !== b.lifecycleRank) {
         return b.lifecycleRank - a.lifecycleRank;
     }
+    // Same scope, same generated time: fall back to a stable path order. Review
+    // artifacts carry a seconds-precision `oat_generated_at`, so distinct re-gate
+    // rounds differ on generatedTime above and never reach this branch.
     return a.path.localeCompare(b.path);
 }
 export async function findLatestReview(options) {

package/dist/commands/shared/frontmatter.d.ts

@@ -9,6 +9,17 @@ export declare function isProjectStatePhase(value: string): value is ProjectStat
 export declare function isProjectStateFrontmatterField(value: string): value is ProjectStateFrontmatterField;
 export declare function getFrontmatterBlock(content: string): string | null;
 export declare function getFrontmatterField(frontmatter: string, field: string): string | null;
+/**
+ * Parse an `oat_generated_at` value into a comparable epoch millisecond time.
+ *
+ * Review artifacts should carry a UTC, `Z`-suffixed timestamp
+ * (`YYYY-MM-DDTHH:MM:SSZ`). A bare date (`YYYY-MM-DD`) already parses as UTC,
+ * but a datetime with no timezone designator parses as *local* time, which
+ * mis-orders artifacts written by agents in different timezones. Treat such a
+ * value as UTC by appending `Z` so ordering is timezone-independent regardless
+ * of what the writer emitted. Returns `NaN` for unparseable input.
+ */
+export declare function parseGeneratedTime(value: string): number;
 export declare function parseFrontmatterField(filePath: string, field: string): Promise<string>;
 export declare function getSkillVersion(skillDir: string): Promise<string | null>;
 export declare function getAgentVersion(agentPath: string): Promise<string | null>;

package/dist/commands/shared/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/frontmatter.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,6CAA8C,CAAC;AAE/E,eAAO,MAAM,oBAAoB,gFAOvB,CAAC;AAEX,eAAO,MAAM,gCAAgC,sgBA2BnC,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE7E;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,4BAA4B,CAIvC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAKf;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/frontmatter.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,6CAA8C,CAAC;AAE/E,eAAO,MAAM,oBAAoB,gFAOvB,CAAC;AAEX,eAAO,MAAM,gCAAgC,sgBA2BnC,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE7E;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,4BAA4B,CAIvC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAKf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB"}

package/dist/commands/shared/frontmatter.js

@@ -57,6 +57,21 @@ export function getFrontmatterField(frontmatter, field) {
         return null;
     return match[1].replace(/\s*#.*$/, '').trim();
 }
+/**
+ * Parse an `oat_generated_at` value into a comparable epoch millisecond time.
+ *
+ * Review artifacts should carry a UTC, `Z`-suffixed timestamp
+ * (`YYYY-MM-DDTHH:MM:SSZ`). A bare date (`YYYY-MM-DD`) already parses as UTC,
+ * but a datetime with no timezone designator parses as *local* time, which
+ * mis-orders artifacts written by agents in different timezones. Treat such a
+ * value as UTC by appending `Z` so ordering is timezone-independent regardless
+ * of what the writer emitted. Returns `NaN` for unparseable input.
+ */
+export function parseGeneratedTime(value) {
+    const hasTime = value.includes('T');
+    const hasZone = /(?:[zZ]|[+-]\d{2}:?\d{2})$/.test(value);
+    return Date.parse(hasTime && !hasZone ? `${value}Z` : value);
+}
 export async function parseFrontmatterField(filePath, field) {
     try {
         const content = await readFile(filePath, 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.40"
+    "@open-agent-toolkit/control-plane": "0.1.42"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",