@open-agent-toolkit/cli 0.1.40 → 0.1.42

package/dist/commands/backlog/archive.js

@@ -0,0 +1,229 @@
+import { execFile } from 'node:child_process';
+import { access, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { getFrontmatterBlock } from '../shared/frontmatter.js';
+import YAML from 'yaml';
+import { regenerateBacklogIndex } from './regenerate-index.js';
+import { BACKLOG_ITEM_STATUSES, extractBacklogStatus, isValidBacklogStatus, } from './shared/item-status.js';
+const execFileAsync = promisify(execFile);
+const COMPLETED_HEADING = '## Completed Items';
+const TODO_SUMMARY = 'TODO: summarize outcome';
+const STARTER_COMPLETED = [
+    '# OAT Backlog Completed',
+    '',
+    '> Summary archive for completed backlog work. Keep newest entries first. Use `backlog/archived/` for full file-per-item historical records when a completed item still needs rich context.',
+    '',
+    '## Entry Format',
+    '',
+    '- `YYYY-MM-DD — BL-YYMMDD-slug — Title — one-line outcome summary`',
+    '',
+    COMPLETED_HEADING,
+    '',
+].join('\n');
+/**
+ * Actionable close-out failure (unknown id, invalid current status). The
+ * command wrapper maps `exitCode` onto `process.exitCode` and logs `message`.
+ */
+export class BacklogArchiveError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'BacklogArchiveError';
+        this.exitCode = exitCode;
+    }
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' && 'code' in error
+            ? String(error.code)
+            : null;
+        if (code !== 'ENOENT') {
+            throw error;
+        }
+        return false;
+    }
+}
+async function isInsideGitWorkTree(cwd) {
+    try {
+        await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { cwd });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the item `title` from its frontmatter. Parses the YAML block (rather
+ * than a line regex) so a legitimate `#` inside a quoted title — e.g.
+ * `title: 'Fix #123 crash'` — is preserved instead of being stripped as an
+ * inline comment.
+ */
+function readItemTitle(content) {
+    const block = getFrontmatterBlock(content);
+    if (!block) {
+        return '';
+    }
+    const parsed = YAML.parse(block);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return '';
+    }
+    return String(parsed.title ?? '').trim();
+}
+/**
+ * Minimal-diff frontmatter rewrite: replace only the `status:` value (keeping
+ * any inline enum comment) and the `updated:` value, leaving all surrounding
+ * formatting untouched.
+ */
+function rewriteFrontmatter(content, status, updatedIso) {
+    let next = content.replace(/^(status:[ \t]*)(\S+)([ \t]*#.*)?$/m, (_match, prefix, _value, comment) => `${prefix}${status}${comment ?? ''}`);
+    next = next.replace(/^(updated:)[ \t]*.*$/m, (_match, prefix) => `${prefix} '${updatedIso}'`);
+    return next;
+}
+/**
+ * Insert `entryLine` as the first bullet beneath the `## Completed Items`
+ * heading. When the heading is absent it is scaffolded (with a warning). The
+ * returned flag distinguishes a plain append from one that had to scaffold the
+ * section.
+ */
+function insertCompletedEntry(completed, entryLine) {
+    const lines = completed.split('\n');
+    const headingIndex = lines.findIndex((line) => line.trim() === COMPLETED_HEADING);
+    if (headingIndex === -1) {
+        const trimmed = completed.replace(/\s*$/, '');
+        const content = `${trimmed}\n\n${COMPLETED_HEADING}\n\n${entryLine}\n`;
+        return {
+            content,
+            scaffolded: true,
+            warning: `Completed log was missing a \`${COMPLETED_HEADING}\` heading; a new section was scaffolded and the entry appended.`,
+        };
+    }
+    let insertAt = headingIndex + 1;
+    while (insertAt < lines.length && lines[insertAt].trim() === '') {
+        insertAt += 1;
+    }
+    lines.splice(insertAt, 0, entryLine);
+    // Guarantee exactly one blank line between the heading and the first entry.
+    if (lines[headingIndex + 1] !== '') {
+        lines.splice(headingIndex + 1, 0, '');
+    }
+    let content = lines.join('\n');
+    if (!content.endsWith('\n')) {
+        content += '\n';
+    }
+    return { content, scaffolded: false, warning: null };
+}
+async function moveItemFile(backlogRoot, fromPath, toPath, warnings) {
+    if (await isInsideGitWorkTree(backlogRoot)) {
+        try {
+            await execFileAsync('git', ['mv', fromPath, toPath], {
+                cwd: backlogRoot,
+            });
+            return;
+        }
+        catch {
+            warnings.push(`\`git mv\` failed for ${fromPath}; falling back to a plain filesystem rename (the move is no longer staged).`);
+        }
+    }
+    await rename(fromPath, toPath);
+}
+/**
+ * Atomic backlog close-out. Validates the current status, sets the terminal
+ * status and `updated`, records a canonical `completed.md` entry, moves the
+ * item file into `archived/`, and regenerates the index. Idempotent when the
+ * item is already archived.
+ */
+export async function archiveBacklogItem(backlogRoot, id, options = {}) {
+    const itemsPath = join(backlogRoot, 'items', `${id}.md`);
+    const archivedPath = join(backlogRoot, 'archived', `${id}.md`);
+    const warnings = [];
+    // Idempotent no-op: already archived.
+    if (await pathExists(archivedPath)) {
+        // Conflicting duplicate: the same id lives in BOTH `items/` and
+        // `archived/`. Treating this as a clean no-op would silently leave the live
+        // `items/` copy unarchived, while auto-archiving would clobber the existing
+        // archived record. Refuse and make the user reconcile the duplicate.
+        if (await pathExists(itemsPath)) {
+            throw new BacklogArchiveError(`Backlog item ${id} exists in both \`items/\` (${itemsPath}) and \`archived/\` (${archivedPath}). Auto-archiving would clobber the existing archived record, so this is left untouched. Fix: reconcile the duplicate manually — decide which of the two files is authoritative and remove the other — then re-run \`oat backlog archive ${id}\`.`);
+        }
+        let status = null;
+        try {
+            const extracted = extractBacklogStatus(await readFile(archivedPath, 'utf8'));
+            status = extracted && isValidBacklogStatus(extracted) ? extracted : null;
+        }
+        catch {
+            status = null;
+        }
+        warnings.push(`Backlog item ${id} is already archived at ${archivedPath}; nothing to do.`);
+        return {
+            id,
+            result: 'noop',
+            status,
+            completedEntry: 'skipped',
+            movedTo: archivedPath,
+            indexRegenerated: false,
+            warnings,
+        };
+    }
+    if (!(await pathExists(itemsPath))) {
+        throw new BacklogArchiveError(`Backlog item ${id} not found at ${itemsPath}. Confirm the id and that the file lives under \`items/\`, then re-run \`oat backlog archive ${id}\`.`);
+    }
+    const content = await readFile(itemsPath, 'utf8');
+    const currentStatus = extractBacklogStatus(content);
+    if (currentStatus === null || !isValidBacklogStatus(currentStatus)) {
+        throw new BacklogArchiveError(`Backlog item ${itemsPath} has invalid status "${currentStatus ?? ''}". Valid statuses: ${BACKLOG_ITEM_STATUSES.join(', ')}. Fix: correct the \`status\` field manually, then re-run \`oat backlog archive ${id}\`.`);
+    }
+    const targetStatus = options.wontDo ? 'wont_do' : 'closed';
+    const now = options.now ?? new Date();
+    const updatedIso = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const entryDate = updatedIso.slice(0, 10);
+    const title = readItemTitle(content);
+    // 4. Rewrite frontmatter in place (before the move) so a crash leaves the
+    //    detectable "terminal status still in items/" drift, never corruption.
+    await writeFile(itemsPath, rewriteFrontmatter(content, targetStatus, updatedIso), 'utf8');
+    // 5. completed.md entry — always for `closed`; only with a summary for
+    //    `wont_do`.
+    let completedEntry = 'skipped';
+    const shouldWriteEntry = targetStatus === 'closed' || Boolean(options.summary);
+    if (shouldWriteEntry) {
+        const summary = options.summary?.trim()
+            ? options.summary.trim()
+            : TODO_SUMMARY;
+        const entryLine = `- ${entryDate} — ${id} — ${title} — ${summary}`;
+        const completedPath = join(backlogRoot, 'completed.md');
+        let scaffoldedFile = false;
+        let existing;
+        if (await pathExists(completedPath)) {
+            existing = await readFile(completedPath, 'utf8');
+        }
+        else {
+            existing = STARTER_COMPLETED;
+            scaffoldedFile = true;
+        }
+        const inserted = insertCompletedEntry(existing, entryLine);
+        if (inserted.warning) {
+            warnings.push(inserted.warning);
+        }
+        await writeFile(completedPath, inserted.content, 'utf8');
+        completedEntry =
+            scaffoldedFile || inserted.scaffolded ? 'scaffolded' : 'written';
+    }
+    // 6. Move items/<id>.md -> archived/<id>.md (git mv with rename fallback).
+    await moveItemFile(backlogRoot, itemsPath, archivedPath, warnings);
+    // 7. Regenerate the index via the exported core.
+    const regeneration = await regenerateBacklogIndex(backlogRoot);
+    warnings.push(...regeneration.warnings);
+    return {
+        id,
+        result: 'archived',
+        status: targetStatus,
+        completedEntry,
+        movedTo: archivedPath,
+        indexRegenerated: true,
+        warnings,
+    };
+}

package/dist/commands/backlog/index.d.ts

@@ -1,6 +1,7 @@
 import { buildCommandContext } from '../../app/command-context.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
+import { archiveBacklogItem } from './archive.js';
 import { initializeBacklog } from './init.js';
 import { regenerateBacklogIndex } from './regenerate-index.js';
 interface BacklogCommandDependencies {
@@ -8,6 +9,7 @@ interface BacklogCommandDependencies {
     resolveProjectRoot: typeof resolveProjectRoot;
     initializeBacklog: typeof initializeBacklog;
     regenerateBacklogIndex: typeof regenerateBacklogIndex;
+    archiveBacklogItem: typeof archiveBacklogItem;
     pathExists: (path: string) => Promise<boolean>;
 }
 export declare function createBacklogCommand(overrides?: Partial<BacklogCommandDependencies>): Command;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAe5D,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAyCD,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAgIT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAuB,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAqB5D,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AA0CD,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAiMT"}

package/dist/commands/backlog/index.js

@@ -4,6 +4,7 @@ import { buildCommandContext } from '../../app/command-context.js';
 import { readGlobalOptions } from '../shared/shared.utils.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
+import { archiveBacklogItem, BacklogArchiveError } from './archive.js';
 import { initializeBacklog } from './init.js';
 import { regenerateBacklogIndex } from './regenerate-index.js';
 import { generateBacklogId } from './shared/generate-id.js';
@@ -27,6 +28,7 @@ const DEFAULT_DEPENDENCIES = {
     resolveProjectRoot,
     initializeBacklog,
     regenerateBacklogIndex,
+    archiveBacklogItem,
     pathExists: pathExistsDefault,
 };
 async function resolveBacklogRoot(context, configuredRoot, dependencies = DEFAULT_DEPENDENCIES) {
@@ -65,15 +67,67 @@ export function createBacklogCommand(overrides = {}) {
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         const backlogRoot = await resolveBacklogRoot(context, options.backlogRoot, dependencies);
-        await dependencies.regenerateBacklogIndex(backlogRoot);
+        const { itemCount, warnings } = await dependencies.regenerateBacklogIndex(backlogRoot);
         if (context.json) {
-            context.logger.json({ status: 'ok', backlogRoot });
+            context.logger.json({ status: 'ok', backlogRoot, itemCount, warnings });
         }
         else {
+            for (const warning of warnings) {
+                context.logger.warn(warning);
+            }
             context.logger.info(`Regenerated backlog index at ${backlogRoot}`);
         }
         process.exitCode = 0;
     });
+    cmd
+        .command('archive')
+        .description('Close out a backlog item: set a terminal status, record it in completed.md, move it to archived/, and regenerate the index')
+        .argument('<id>', 'Backlog item id (`BL-YYMMDD-slug`)')
+        .option('--wont-do', 'Close the item as `wont_do` instead of `closed`')
+        .option('--summary <text>', 'One-line outcome summary for completed.md')
+        .option('--backlog-root <path>', 'Backlog root directory (defaults to .oat/repo/pjm/backlog)')
+        .action(async (id, options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        const backlogRoot = await resolveBacklogRoot(context, options.backlogRoot, dependencies);
+        try {
+            const result = await dependencies.archiveBacklogItem(backlogRoot, id, {
+                wontDo: options.wontDo,
+                summary: options.summary,
+            });
+            if (context.json) {
+                context.logger.json(result);
+            }
+            else {
+                for (const warning of result.warnings) {
+                    context.logger.warn(warning);
+                }
+                if (result.result === 'noop') {
+                    context.logger.info(`Backlog item ${id} is already archived.`);
+                }
+                else {
+                    context.logger.success(`Archived ${id} as ${result.status} (moved to ${result.movedTo}).`);
+                }
+            }
+            process.exitCode = 0;
+        }
+        catch (error) {
+            if (error instanceof BacklogArchiveError) {
+                if (context.json) {
+                    context.logger.json({
+                        result: 'error',
+                        id,
+                        message: error.message,
+                    });
+                }
+                else {
+                    context.logger.error(error.message);
+                }
+                process.exitCode = error.exitCode;
+                return;
+            }
+            throw error;
+        }
+    });
     cmd
         .command('generate-id')
         .description('Generate a backlog item identifier (`BL-YYMMDD-slug`) from a title or slug')

package/dist/commands/backlog/regenerate-index.d.ts

@@ -1,2 +1,6 @@
-export declare function regenerateBacklogIndex(backlogRoot: string): Promise<void>;
+export interface RegenerateBacklogIndexResult {
+    itemCount: number;
+    warnings: string[];
+}
+export declare function regenerateBacklogIndex(backlogRoot: string): Promise<RegenerateBacklogIndexResult>;
 //# sourceMappingURL=regenerate-index.d.ts.map

package/dist/commands/backlog/regenerate-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regenerate-index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/regenerate-index.ts"],"names":[],"mappings":"AAmGA,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CA+Cf"}
+{"version":3,"file":"regenerate-index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/regenerate-index.ts"],"names":[],"mappings":"AAwGA,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,CAAC,CAsDvC"}

package/dist/commands/backlog/regenerate-index.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { getFrontmatterBlock } from '../shared/frontmatter.js';
 import { computeManagedIndexUpdate } from '../shared/managed-index.js';
 import YAML from 'yaml';
+import { BACKLOG_ITEM_STATUSES, isValidBacklogStatus, } from './shared/item-status.js';
 const INDEX_START = '<!-- OAT BACKLOG-INDEX -->';
 const INDEX_END = '<!-- END OAT BACKLOG-INDEX -->';
 const PRIORITY_ORDER = {
@@ -71,10 +72,14 @@ export async function regenerateBacklogIndex(backlogRoot) {
         .map((entry) => entry.name)
         .sort();
     const items = [];
+    const warnings = [];
     for (const entry of entries) {
         const filePath = join(itemsDir, entry);
         const item = parseItemFrontmatter(await readFile(filePath, 'utf8'), filePath);
         if (item) {
+            if (item.status !== '' && !isValidBacklogStatus(item.status)) {
+                warnings.push(`Backlog item ${filePath} has invalid status "${item.status}". Valid statuses: ${BACKLOG_ITEM_STATUSES.join(', ')}.`);
+            }
             items.push(item);
         }
     }
@@ -91,7 +96,8 @@ export async function regenerateBacklogIndex(backlogRoot) {
     // write. Only rewrite on a genuine content change.
     const { content: updated } = computeManagedIndexUpdate(content, startIndex, endIndex + INDEX_END.length, renderManagedSection(items));
     if (updated === null) {
-        return;
+        return { itemCount: items.length, warnings };
     }
     await writeFile(indexPath, updated, 'utf8');
+    return { itemCount: items.length, warnings };
 }

package/dist/commands/backlog/shared/item-status.d.ts

@@ -0,0 +1,13 @@
+export declare const BACKLOG_ITEM_STATUSES: readonly ["open", "in_progress", "closed", "wont_do"];
+export type BacklogItemStatus = (typeof BACKLOG_ITEM_STATUSES)[number];
+export declare const TERMINAL_BACKLOG_STATUSES: readonly BacklogItemStatus[];
+export declare function isValidBacklogStatus(value: string): value is BacklogItemStatus;
+export declare function isTerminalBacklogStatus(value: string): boolean;
+/**
+ * Extract the `status` value from backlog item content. Accepts either full
+ * item content (with `---` fences) or a bare frontmatter block. Inline enum
+ * comments (`status: closed # ...`) are stripped. Returns `null` when no
+ * `status` field is present.
+ */
+export declare function extractBacklogStatus(frontmatterContent: string): string | null;
+//# sourceMappingURL=item-status.d.ts.map

package/dist/commands/backlog/shared/item-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-status.d.ts","sourceRoot":"","sources":["../../../../src/commands/backlog/shared/item-status.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,qBAAqB,uDAKxB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,eAAO,MAAM,yBAAyB,EAAE,SAAS,iBAAiB,EAGjE,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,kBAAkB,EAAE,MAAM,GACzB,MAAM,GAAG,IAAI,CAUf"}

package/dist/commands/backlog/shared/item-status.js

@@ -0,0 +1,34 @@
+// Single source of truth for backlog item statuses. Kept dependency-free so
+// cross-directory consumers (archive, regenerate-index, pjm doctor) can import
+// it via the `@commands/...` alias without pulling in a dependency chain.
+export const BACKLOG_ITEM_STATUSES = [
+    'open',
+    'in_progress',
+    'closed',
+    'wont_do',
+];
+export const TERMINAL_BACKLOG_STATUSES = [
+    'closed',
+    'wont_do',
+];
+export function isValidBacklogStatus(value) {
+    return BACKLOG_ITEM_STATUSES.includes(value);
+}
+export function isTerminalBacklogStatus(value) {
+    return TERMINAL_BACKLOG_STATUSES.includes(value);
+}
+/**
+ * Extract the `status` value from backlog item content. Accepts either full
+ * item content (with `---` fences) or a bare frontmatter block. Inline enum
+ * comments (`status: closed # ...`) are stripped. Returns `null` when no
+ * `status` field is present.
+ */
+export function extractBacklogStatus(frontmatterContent) {
+    const fenced = frontmatterContent.match(/^---\n([\s\S]*?)\n---/);
+    const block = fenced ? fenced[1] : frontmatterContent;
+    const match = block.match(/^status:\s*(.+)$/m);
+    if (!match) {
+        return null;
+    }
+    return match[1].replace(/\s*#.*$/, '').trim();
+}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAQL,KAAK,UAAU,EAIf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,CACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,iBAAiB,KACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AA0CD,UAAU,iBAAiB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,OAAO,EAAE,gBAAgB,GAAG,cAAc,GAAG,SAAS,CAAC;IACvD,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC7B;AAED,UAAU,gBAAgB;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,kBAAkB,GAAG,cAAc,GAAG,MAAM,CAAC;AAMlD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;CACpB;AAyZD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,EAC9C,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,GAAG,IAAI,CAE3B;AAo6BD,wBAAgB,iBAAiB,CAC/B,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAwKT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,EAQL,KAAK,UAAU,EAIf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,CACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,iBAAiB,KACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AA0CD,UAAU,iBAAiB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,OAAO,EAAE,gBAAgB,GAAG,cAAc,GAAG,SAAS,CAAC;IACvD,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC7B;AAED,UAAU,gBAAgB;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,kBAAkB,GAAG,cAAc,GAAG,MAAM,CAAC;AAMlD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;CACpB;AAyZD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,EAC9C,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,GAAG,IAAI,CAE3B;AAu7BD,wBAAgB,iBAAiB,CAC/B,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAwKT"}

package/dist/commands/gate/index.js

@@ -1,9 +1,9 @@
 import { spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { readdir, readFile } from 'node:fs/promises';
 import { basename, 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 { BUILTIN_EXEC_TARGETS, readOatConfig, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
 import { resolveEffectiveConfig, resolveExecTargets, resolveGate, } from '../../config/resolve.js';
@@ -502,7 +502,7 @@ async function readReviewGateArtifactCandidate(repoRoot, relativePath) {
     if (!generatedAt) {
         return null;
     }
-    const generatedTime = Date.parse(generatedAt);
+    const generatedTime = parseGeneratedTime(generatedAt);
     if (Number.isNaN(generatedTime)) {
         return null;
     }
@@ -616,6 +616,7 @@ function writeReviewGateResult(context, payload) {
     else {
         context.logger.info('Review completed and gate passed.');
     }
+    context.logger.info(`Run: ${payload.runId} (generated ${payload.generatedAt})`);
     context.logger.info(`Review artifact: ${payload.artifactPath}`);
     if (payload.normalization) {
         context.logger.info(`Artifact normalized: inserted ${payload.normalization.insertedSeverities.map((severity) => severityDisplayName(severity)).join(', ')} empty Findings section(s).`);
@@ -629,6 +630,7 @@ function writeReviewGateExecutionFailure(context, payload) {
         context.logger.json({
             status: 'review_failed',
             outcome: 'review_did_not_complete',
+            runId: payload.runId,
             target: payload.target,
             project: payload.project,
             exitCode: payload.exitCode,
@@ -643,9 +645,11 @@ function writeReviewGateArtifactValidationFailure(context, payload) {
         context.logger.json({
             status: 'artifact_validation_failed',
             outcome: 'review_completed_artifact_validation_failed',
+            runId: payload.runId,
             target: payload.target,
             project: payload.project,
             artifactPath: payload.artifactPath,
+            generatedAt: payload.generatedAt,
             message: payload.message,
             recovery: payload.recovery,
         });
@@ -755,6 +759,7 @@ async function runCrossProviderExec(prompt, options, context, dependencies) {
     }
 }
 async function runReviewGate(prompt, options, context, dependencies) {
+    const runId = randomUUID();
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const userConfigDir = join(context.home, '.oat');
@@ -785,6 +790,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
         const childExitCode = await executeTarget(selected, [reviewPrompt], context, dependencies);
         if (childExitCode !== 0) {
             writeReviewGateExecutionFailure(context, {
+                runId,
                 target: selected.id,
                 project: projectPath,
                 exitCode: childExitCode,
@@ -799,9 +805,11 @@ async function runReviewGate(prompt, options, context, dependencies) {
         const producedArtifact = findProducedReviewArtifact(before, after);
         if (!producedArtifact) {
             writeReviewGateArtifactValidationFailure(context, {
+                runId,
                 target: selected.id,
                 project: projectPath,
                 artifactPath: null,
+                generatedAt: null,
                 message: `No new review artifact was detected for project ${projectPath}.`,
                 recovery: 'Ensure the review provider wrote a project review artifact. If it did, fix or attach that artifact and run oat-project-review-receive before treating the review as consumed.',
             });
@@ -817,9 +825,11 @@ async function runReviewGate(prompt, options, context, dependencies) {
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);
             writeReviewGateArtifactValidationFailure(context, {
+                runId,
                 target: selected.id,
                 project: projectPath,
                 artifactPath: producedArtifact.path,
+                generatedAt: producedArtifact.generatedAt,
                 message: detail,
                 recovery: `The review artifact was created at ${producedArtifact.path} but could not be consumed. Fix the artifact format, then run oat-project-review-receive for ${producedArtifact.path}; if the only issue is a missing zero-count severity heading, rerun the gate to normalize the same artifact instead of creating a new review version.`,
             });
@@ -835,9 +845,11 @@ async function runReviewGate(prompt, options, context, dependencies) {
         });
         writeReviewGateResult(context, {
             status: blocking ? 'blocked' : 'ok',
+            runId,
             target: selected.id,
             project: projectPath,
             artifactPath: producedArtifact.path,
+            generatedAt: producedArtifact.generatedAt,
             threshold,
             blocking,
             counts: verdict.counts,

package/dist/commands/instructions/instructions.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,iCAAiC,EAAE,uBACrC,CAAC;AAKZ,UAAU,4BAA4B;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;CACpC;AAqBD,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,uBAAuB,CAEzB;AAoLD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiO7B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,uBAAuB,EAAE,GACjC,mBAAmB,CAoBrB;AAgBD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,OAAO,EACP,OAAO,GACR,EAAE,4BAA4B,GAAG,uBAAuB,CAWxD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAmCR"}
+{"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,iCAAiC,EAAE,uBACrC,CAAC;AAcZ,UAAU,4BAA4B;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;CACpC;AAiCD,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,uBAAuB,CAEzB;AA2LD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiO7B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,uBAAuB,EAAE,GACjC,mBAAmB,CAoBrB;AAgBD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,OAAO,EACP,OAAO,GACR,EAAE,4BAA4B,GAAG,uBAAuB,CAWxD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAmCR"}

package/dist/commands/instructions/instructions.utils.js

@@ -4,6 +4,23 @@ export const EXPECTED_CLAUDE_CONTENT = '@AGENTS.md\n';
 export const DEFAULT_INSTRUCTION_SYNC_STRATEGY = 'pointer';
 const ROOT_EXCLUDED_DIRECTORIES = new Set(['.git', '.oat', '.worktrees']);
 const GLOBAL_EXCLUDED_DIRECTORIES = new Set(['node_modules']);
+// The only excluded-subtree re-entry points: a root-level directory is excluded
+// wholesale, but a named subdirectory holds tracked instruction files that
+// sync/validate must manage, so it is carved back into the scan. `.oat` is
+// excluded at the repo root, yet `.oat/repo/**` carries AGENTS.md/CLAUDE.md
+// pairs; `.oat/templates`, `.oat/projects`, and `.oat/sync` stay unscanned.
+const ROOT_EXCLUDED_DIRECTORY_CARVE_INS = new Map([
+    ['.oat', 'repo'],
+]);
+async function directoryExists(dependencies, directoryPath) {
+    try {
+        const stats = await dependencies.stat(directoryPath);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function getErrorCode(error) {
     return error && typeof error === 'object' && 'code' in error
         ? String(error.code)
@@ -97,6 +114,13 @@ async function scanInstructionDirectories(repoRoot, dependencies, debug) {
                     continue;
                 }
                 if (isRootLevel && ROOT_EXCLUDED_DIRECTORIES.has(entry.name)) {
+                    const carveIn = ROOT_EXCLUDED_DIRECTORY_CARVE_INS.get(entry.name);
+                    if (carveIn) {
+                        const carveInPath = join(entryPath, carveIn);
+                        if (await directoryExists(dependencies, carveInPath)) {
+                            queue.push(carveInPath);
+                        }
+                    }
                     continue;
                 }
                 queue.push(entryPath);

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/doctor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA0I9C,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,sBAAsB,IAAI,WAAW,CAQpD;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,WAAW,EAAE,CAAC,CAyJxB"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/doctor.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA6L9C,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,sBAAsB,IAAI,WAAW,CAQpD;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,WAAW,EAAE,CAAC,CAoTxB"}