@open-agent-toolkit/cli 0.1.39 → 0.1.41

package/assets/templates/repo-readme.md

@@ -0,0 +1,35 @@
+---
+oat_template: true
+oat_template_name: repo-readme
+---
+
+# OAT Repo Reference
+
+Human-facing orientation for this OAT repo-reference root — the canonical
+project-management and durable-reference surface for the repository.
+Agent-facing rules live in the `AGENTS.md` files alongside each directory.
+
+## Layout
+
+| Path                       | What it is                                               | Maintained by                                              |
+| -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
+| `pjm/current-state.md`     | Present operating picture                                | Curated                                                    |
+| `pjm/roadmap.md`           | Now / Next / Later direction                             | Curated                                                    |
+| `pjm/backlog/items/`       | Active backlog items, one file each                      | Curated + `oat backlog`                                    |
+| `pjm/backlog/archived/`    | Completed/abandoned item files                           | Moved here at close-out                                    |
+| `pjm/backlog/completed.md` | Newest-first completion summaries                        | Appended at close-out                                      |
+| `pjm/backlog/index.md`     | Curated overview + generated item table                  | Overview curated; table via `oat backlog regenerate-index` |
+| `pjm/handoffs/`            | One-shot project-kickoff prompts (deleted when consumed) | Backlog walkthroughs; removed in the shipping PR           |
+| `reference/decisions/`     | Durable decision records + generated index               | `oat decision`                                             |
+
+## Conventions
+
+- **Generated vs. curated.** Generated tables live inside `<!-- OAT ... -->`
+  marker pairs; regenerate them with the owning `oat` command instead of
+  hand-editing. Everything outside those markers is curated by hand.
+- **IDs.** Backlog items follow `BL-YYMMDD-slug` (`oat backlog generate-id`);
+  decisions follow `DR-YYMMDD-slug`. Pair every backlog item ID with its
+  human-readable title — no bare IDs in prose or handoffs.
+- **Close-out.** When work ships that satisfies a backlog item's acceptance
+  criteria, the item is closed and archived in the same commit/PR — run
+  `oat backlog archive <id>`. See the Backlog Lifecycle in `pjm/AGENTS.md`.

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

@@ -0,0 +1,33 @@
+import { type BacklogItemStatus } from './shared/item-status.js';
+/** Result of an {@link archiveBacklogItem} run. */
+export interface ArchiveBacklogItemResult {
+    id: string;
+    result: 'archived' | 'noop';
+    status: BacklogItemStatus | null;
+    completedEntry: 'written' | 'scaffolded' | 'skipped';
+    movedTo: string | null;
+    indexRegenerated: boolean;
+    warnings: string[];
+}
+export interface ArchiveBacklogItemOptions {
+    wontDo?: boolean;
+    summary?: string;
+    /** Injectable clock for deterministic tests; defaults to the current time. */
+    now?: Date;
+}
+/**
+ * Actionable close-out failure (unknown id, invalid current status). The
+ * command wrapper maps `exitCode` onto `process.exitCode` and logs `message`.
+ */
+export declare class BacklogArchiveError extends Error {
+    readonly exitCode: 1 | 2;
+    constructor(message: string, exitCode?: 1 | 2);
+}
+/**
+ * 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 declare function archiveBacklogItem(backlogRoot: string, id: string, options?: ArchiveBacklogItemOptions): Promise<ArchiveBacklogItemResult>;
+//# sourceMappingURL=archive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/archive.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,iBAAiB,EAGvB,MAAM,sBAAsB,CAAC;AAoB9B,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC;IAC5B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,CAAC,GAAG,CAAK;CAKjD;AAkID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CAkHnC"}

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/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"}