@open-agent-toolkit/cli 0.3.8 → 0.3.9

package/assets/skills/oat-project-progress/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash(git:*), Bash(oat:*), AskUserQuestion
 metadata:
-  version: 1.4.2
+  version: 1.4.3
 ---
 
 # Progress Router
@@ -276,7 +276,7 @@ Routing matrix by mode:
 | oat_phase | oat_phase_status | Next Skill                                                                                                                          |
 | --------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
 | discovery | in_progress      | Continue `oat-project-discover`                                                                                                     |
-| discovery | complete         | `oat-project-plan`                                                                                                                  |
+| discovery | complete         | `oat-project-quick-start`                                                                                                           |
 | plan      | in_progress      | Continue `oat-project-quick-start` when the plan is not implementation-ready; otherwise `oat-project-implement`                     |
 | plan      | complete         | `oat-project-implement` when the plan is implementation-ready; otherwise `oat-project-quick-start`                                  |
 | implement | in_progress      | Continue `oat-project-implement`. If drift detected (see drift detection above), also mention `oat-project-reconcile` as an option. |

package/assets/templates/docs-app-mkdocs/docs/contributing.md

@@ -102,9 +102,8 @@ Extends fenced code support and enables custom fences such as Mermaid:
 ```mermaid
 flowchart LR
   A[Read index.md] --> B[Generate nav]
-````
-
 ```
+````
 
 ### `pymdownx.tabbed`
 
@@ -119,4 +118,3 @@ Adds table-of-contents anchors and permalinks for headings.
 - Treat `index.md` plus its `## Contents` section as the local discovery source of truth.
 - Prefer linking to source files and commands explicitly when documenting behavior.
 - When adding a new plugin or extension, update this guide with what it does and how to use it.
-```

package/assets/templates/pjm-agents.md

@@ -36,8 +36,10 @@ for abandoned work and `--summary "<text>"` to record the outcome. The command
 performs the whole close-out atomically: it flips `status` to the terminal
 value and bumps `updated`, appends the canonical `backlog/completed.md` entry
 (always for `closed`; for `wont_do` only when `--summary` is given), moves the
-item file from `backlog/items/` to `backlog/archived/`, and regenerates
-`backlog/index.md`. Stage the resulting changes with the shipping commit/PR.
+item file from `backlog/items/` to `backlog/archived/`, rewrites inbound
+`.oat/repo` links and path references to the moved file (reporting each
+rewritten file), and regenerates `backlog/index.md`. Stage the resulting
+changes with the shipping commit/PR.
 
 **Manual fallback.** These are the steps the command automates — follow them, in
 order, only when closing out by hand:
@@ -46,7 +48,9 @@ order, only when closing out by hand:
 2. Append a summary entry to `backlog/completed.md` (newest first; entry format
    is documented at the top of that file). Add the entry for a `wont_do` item
    only when the abandonment itself is worth recording (an explicit summary).
-3. `git mv` the item file from `backlog/items/` to `backlog/archived/`.
+3. `git mv` the item file from `backlog/items/` to `backlog/archived/`, then
+   rewrite inbound `.oat/repo` links to `archived/` (plans, decision records,
+   other items, and repository-root paths such as `oat_external_plan_sources`).
 4. Run `oat backlog regenerate-index` and stage the regenerated
    `backlog/index.md`.
 5. If the completion changes the operating picture, refresh

package/assets/templates/state.md

@@ -50,8 +50,8 @@ oat_workflow_origin: native # native | imported
 #   max_attempts: 2
 #   attempts_completed: 0
 #   reviewed_head: null
-#   implementation_base_ref: null # exact logical base ref for effective-delta-v1
-#   implementation_fingerprint: null # new generations use sha256:effective-delta-v1:<digest>
+#   implementation_base_ref: null # exact logical base ref for the qualified effective-delta fingerprint
+#   implementation_fingerprint: null # new generations use sha256:effective-delta-v2:<digest>; stored v1 values keep v1 semantics
 #   freshness_head: null # rolling accepted tree checkpoint
 #   freshness_fingerprint: null # full effective delta at freshness_head
 #   launch_state: not_started # not_started | intent_persisted | accepted | result_persisted | not_accepted

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

@@ -7,6 +7,12 @@ export interface ArchiveBacklogItemResult {
     completedEntry: 'written' | 'scaffolded' | 'skipped';
     movedTo: string | null;
     indexRegenerated: boolean;
+    /**
+     * Markdown files under `.oat/repo/**` whose references to
+     * `items/<id>.md` were rewritten to `archived/<id>.md`, relative to the
+     * repository root.
+     */
+    rewrittenReferences: string[];
     warnings: string[];
 }
 export interface ArchiveBacklogItemOptions {
@@ -26,8 +32,10 @@ export declare class BacklogArchiveError extends Error {
 /**
  * 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.
+ * item file into `archived/`, rewrites inbound `.oat/repo` references to the
+ * moved file, and regenerates the index. Idempotent when the item is already
+ * archived: that path writes no status, completed-log, or move changes and only
+ * retries the reference rewrite and index regeneration.
  */
 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

@@ -1 +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;AAmB9B,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;IAEzB,YAAY,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,CAAC,GAAG,CAAK,EAI/C;CACF;AAkID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CAqHnC"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/archive.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,iBAAiB,EAGvB,MAAM,sBAAsB,CAAC;AAmB9B,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;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,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;IAEzB,YAAY,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,CAAC,GAAG,CAAK,EAI/C;CACF;AAkID;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CA4InC"}

package/dist/commands/backlog/archive.js

@@ -5,6 +5,7 @@ import { promisify } from 'node:util';
 import { getFrontmatterBlock } from '../shared/frontmatter.js';
 import YAML from 'yaml';
 import { regenerateBacklogIndex } from './regenerate-index.js';
+import { rewriteInboundReferences } from './rewrite-references.js';
 import { BACKLOG_ITEM_STATUSES, extractBacklogStatus, isValidBacklogStatus, } from './shared/item-status.js';
 const execFileAsync = promisify(execFile);
 const COMPLETED_HEADING = '## Completed Items';
@@ -133,14 +134,17 @@ async function moveItemFile(backlogRoot, fromPath, toPath, warnings) {
 /**
  * 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.
+ * item file into `archived/`, rewrites inbound `.oat/repo` references to the
+ * moved file, and regenerates the index. Idempotent when the item is already
+ * archived: that path writes no status, completed-log, or move changes and only
+ * retries the reference rewrite and index regeneration.
  */
 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.
+    // Already archived: no status, completed-log, or move writes; only the
+    // idempotent reference rewrite and index regeneration are retried.
     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
@@ -157,14 +161,22 @@ export async function archiveBacklogItem(backlogRoot, id, options = {}) {
         catch {
             status = null;
         }
-        warnings.push(`Backlog item ${id} is already archived at ${archivedPath}; nothing to do.`);
+        warnings.push(`Backlog item ${id} is already archived at ${archivedPath}; re-checked inbound references and regenerated the index.`);
+        // Retry the idempotent tail of a close-out: a run that failed during the
+        // reference rewrite (or an item archived before the rewrite existed)
+        // still gets its inbound links repointed and the index regenerated.
+        const references = await rewriteInboundReferences(backlogRoot, itemsPath, archivedPath, { rebaseMovedItem: false });
+        warnings.push(...references.warnings);
+        const regeneration = await regenerateBacklogIndex(backlogRoot);
+        warnings.push(...regeneration.warnings);
         return {
             id,
             result: 'noop',
             status,
             completedEntry: 'skipped',
             movedTo: archivedPath,
-            indexRegenerated: false,
+            indexRegenerated: true,
+            rewrittenReferences: references.rewritten,
             warnings,
         };
     }
@@ -214,7 +226,10 @@ export async function archiveBacklogItem(backlogRoot, id, options = {}) {
     }
     // 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.
+    // 7. Rewrite inbound references so no `.oat/repo` link dangles at items/.
+    const references = await rewriteInboundReferences(backlogRoot, itemsPath, archivedPath);
+    warnings.push(...references.warnings);
+    // 8. Regenerate the index via the exported core.
     const regeneration = await regenerateBacklogIndex(backlogRoot);
     warnings.push(...regeneration.warnings);
     return {
@@ -224,6 +239,7 @@ export async function archiveBacklogItem(backlogRoot, id, options = {}) {
         completedEntry,
         movedTo: archivedPath,
         indexRegenerated: true,
+        rewrittenReferences: references.rewritten,
         warnings,
     };
 }

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;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,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,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AA8B5D,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AA4ED,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAyRT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,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,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AA8B5D,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AA4ED,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CA6RT"}

package/dist/commands/backlog/index.js

@@ -179,7 +179,7 @@ export function createBacklogCommand(overrides = {}) {
     });
     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')
+        .description('Close out a backlog item: set a terminal status, record it in completed.md, move it to archived/, rewrite inbound .oat/repo references to it, 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')
@@ -206,6 +206,10 @@ export function createBacklogCommand(overrides = {}) {
                 else {
                     context.logger.success(`Archived ${id} as ${result.status} (moved to ${result.movedTo}).`);
                 }
+                // Both results can rewrite: a retry on an archived item re-runs it.
+                for (const path of result.rewrittenReferences) {
+                    context.logger.info(`Rewrote references in ${path}`);
+                }
             }
             process.exitCode = 0;
         }

package/dist/commands/backlog/rewrite-references.d.ts

@@ -0,0 +1,41 @@
+/** Result of {@link rewriteInboundReferences}. */
+export interface RewriteInboundReferencesResult {
+    /** Files whose content was rewritten, relative to the repository root. */
+    rewritten: string[];
+    /** One warning per reference that names the item but cannot be resolved. */
+    warnings: string[];
+}
+/** Options for {@link rewriteInboundReferences}. */
+export interface RewriteInboundReferencesOptions {
+    /**
+     * Rebase the moved item's own relative links from `items/` to `archived/`.
+     * Defaults to `true`; a retry on an already-archived item passes `false`
+     * because its links were rebased (or written) against `archived/` already.
+     */
+    rebaseMovedItem?: boolean;
+}
+/** A Markdown segment: prose, an inline code span, or a fenced code block. */
+export interface MarkdownSegment {
+    kind: 'prose' | 'span' | 'fence';
+    text: string;
+}
+/**
+ * Split Markdown into prose, inline code spans, and fenced code blocks.
+ * Fences (``` or ~~~) close on a same-character run at least as long, or run
+ * to the end of the file. Inline code spans pair a backtick run with the next
+ * run of the same length inside one paragraph (a blank line ends it), so a
+ * stray backtick never swallows later paragraphs.
+ */
+export declare function splitMarkdownCode(content: string): MarkdownSegment[];
+/**
+ * After `items/<id>.md` moved to `archived/<id>.md`, rewrite every reference
+ * to the old path in Markdown under `.oat/repo/**` (links and repository-root
+ * path strings such as `oat_external_plan_sources` frontmatter). An inline code
+ * span is rewritten only when its whole content is a path to the item (the
+ * external-plan citation form); other spans and fenced code are left as
+ * written with a warning, so a recorded command keeps its meaning. References that name the item's `items/` path
+ * but cannot be resolved are reported as warnings and left untouched. The
+ * rewrite is idempotent, so a re-run on an already-archived item is safe.
+ */
+export declare function rewriteInboundReferences(backlogRoot: string, itemsPath: string, archivedPath: string, options?: RewriteInboundReferencesOptions): Promise<RewriteInboundReferencesResult>;
+//# sourceMappingURL=rewrite-references.d.ts.map

package/dist/commands/backlog/rewrite-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewrite-references.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/rewrite-references.ts"],"names":[],"mappings":"AAsCA,kDAAkD;AAClD,MAAM,WAAW,8BAA8B;IAC7C,0EAA0E;IAC1E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA0RD,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CA0EpE;AAmND;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,8BAA8B,CAAC,CAsCzC"}