@open-agent-toolkit/cli 0.3.8 → 0.3.10

package/assets/skills/subagent-orchestration/references/provider-codex.md

@@ -1,7 +1,7 @@
 ---
-guidance_version: 2026-09-24
-last_verified: 2026-09-24
-review_after: 2026-12-22
+guidance_version: 2026-10-01
+last_verified: 2026-10-01
+review_after: 2026-12-30
 ---
 
 # Codex and OpenAI Model Selection
@@ -13,16 +13,19 @@ model examples below. Launch mechanics for OAT dispatch live in
 
 ## Current Families
 
-Use verified GPT-6 Sol/Luna model IDs for routine new Codex work. GPT-6 Astra
+Use `gpt-6.1-sol` for new Sol routes and `gpt-6-luna` for bounded Luna work.
+This Sol selector migration preserves the existing task-class effort guidance;
+it does not claim a newly measured workload advantage. GPT-6 Astra
 is a supported Frontier candidate:
 
 - `gpt-6-astra`: Frontier candidate for especially demanding work; the bundled
   recommendation uses high and xhigh, while the supported catalogue also
   permits low, medium, and max;
-- `gpt-6-sol`: high-capability implementation and reasoning route;
+- `gpt-6.1-sol`: high-capability implementation and reasoning route;
 - `gpt-6-luna`: cost-sensitive, bounded work.
 
-Public engineering benchmarks show task-dependent Astra gains over Sol, with
+The earlier public engineering benchmarks show task-dependent Astra gains
+over GPT-6 Sol, with
 cost and runtime tradeoffs; they do not establish a universal replacement. The
 September frontier-release comparison remains review-pending in the separate
 model-selection vault, and no matched OAT workload evaluation has qualified a
@@ -30,8 +33,8 @@ routine default change. Astra's Frontier inclusion is a user-directed
 preference. Keep the Sol task-class defaults below while that evidence is
 reconciled and local task fit is evaluated.
 
-The GPT-5.6 Sol/Luna/Terra targets remain supported for explicit configurations
-and established workloads. Re-evaluate economics and qualitative routing on
+GPT-6 Sol (`gpt-6-sol`) and the GPT-5.6 Sol/Luna/Terra targets remain supported
+for explicit configurations and established workloads. Re-evaluate economics and qualitative routing on
 representative work before carrying over GPT-5.6-specific comparisons.
 
 Direct API specialist routes:
@@ -48,18 +51,24 @@ name includes `codex`.
 ## Dated Task-Class Matrix
 
 These are current task-class starting points, not an evaluated ordering across
-providers or a promise about relative GPT-6 latency and price. All shown
+providers or a promise about relative GPT-6 or GPT-6.1 latency and price. All shown
 model/effort pairs are in the local Codex catalogue.
 
-| Task class               | Default                                    | Escalation                                                            | Floor notes                                                                   |
-| ------------------------ | ------------------------------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `mechanical-recon`       | `gpt-6-luna`, high                         | `gpt-6-sol`, medium                                                   | Lower effort is suitable only when a miss is cheap and mechanically detected. |
-| `intelligent-recon`      | `gpt-6-sol`, medium                        | Sol high                                                              | Preserve verification for silent-miss-prone reconnaissance.                   |
-| `default-implementation` | `gpt-6-sol`, medium                        | Sol high                                                              | Luna is for independently bounded, strongly verified work.                    |
-| `hard-reasoning`         | `gpt-6-sol`, high                          | Sol xhigh                                                             | Narrow the problem before raising effort.                                     |
-| `consequential`          | `gpt-6-sol`, high, plus independent review | Sol xhigh for a reasoning-depth bottleneck; max only after evaluation | The root retains consequential authorization.                                 |
-
-The bundled Frontier ladder ends with Astra xhigh after Sol xhigh and Astra
+| Task class               | Default                                      | Escalation                                                            | Floor notes                                                                   |
+| ------------------------ | -------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `mechanical-recon`       | `gpt-6-luna`, high                           | `gpt-6.1-sol`, medium                                                 | Lower effort is suitable only when a miss is cheap and mechanically detected. |
+| `intelligent-recon`      | `gpt-6.1-sol`, medium                        | Sol high                                                              | Preserve verification for silent-miss-prone reconnaissance.                   |
+| `default-implementation` | `gpt-6.1-sol`, medium                        | Sol high                                                              | Luna is for independently bounded, strongly verified work.                    |
+| `hard-reasoning`         | `gpt-6.1-sol`, high                          | Sol xhigh                                                             | Narrow the problem before raising effort.                                     |
+| `consequential`          | `gpt-6.1-sol`, high, plus independent review | Sol xhigh for a reasoning-depth bottleneck; max only after evaluation | The root retains consequential authorization.                                 |
+
+[OpenAI's GPT-6.1 Sol model reference](https://developers.openai.com/api/docs/models/gpt-6.1-sol)
+identifies `gpt-6.1-sol` and the supported efforts `low`, `medium`, `high`,
+`xhigh`, and `max`. Do not emit `none` or `minimal` for this family. For direct
+API tool calls, use the Responses API. Verify the launching Codex runtime
+independently of API availability.
+
+The bundled Frontier ladder ends with Astra xhigh after Sol 6.1 xhigh and Astra
 high. The supported Astra and Sol effort sets both end at max, so Sol max
 remains available for explicit configuration even though it is no longer in
 the bundled Frontier recommendation.

package/assets/skills/subagent-orchestration/references/provider-cursor.md

@@ -1,12 +1,14 @@
 ---
-guidance_version: 2026-09-25
-last_verified: 2026-09-25
-review_after: 2026-12-24
+guidance_version: 2026-10-01
+last_verified: 2026-10-01
+review_after: 2026-12-30
 catalog_basis:
   Cursor desktop 3.21.18 resolved Grok 4.6 and Fable 5.1 effort selectors in
   native subagent hooks, and Grok 4.7 only as bare flat IDs; Cursor desktop
   3.20.14 resolved all five Opus 5.5 effort selectors; GPT-6 Sol/Luna were
-  absent from the observed Cursor catalog
+  absent from the observed Cursor catalog; the 2026-10-01 CLI catalog lists
+  Sonnet 5.5 flat IDs; Cursor desktop 3.22.12 matched five exact-ID Sonnet
+  5.5 pins while every bracket-form Sonnet 5.5 probe fell back
 ---
 
 # Cursor Model Selection
@@ -51,8 +53,8 @@ Cursor desktop 3.20.14 resolved all five `claude-opus-5-5[effort=...]`
 selectors to corresponding flat IDs in native hooks; on 2026-09-25, Cursor
 desktop 3.21.18 did the same for Grok 4.6 and Fable 5.1. See the
 probe records at `packages/cli/src/providers/cursor/codec/__fixtures__/README.md`.
-GPT-6 Sol/Luna were absent from the observed Cursor catalogue, so their Codex
-availability does not authorize Cursor routes.
+GPT-6 Sol/Luna and GPT-6.1 Sol were absent from the 2026-10-01 Cursor CLI
+catalogue, so their Codex availability does not authorize Cursor routes.
 
 | Task class               | Default                                                             | Economy                                            | Escalation                                                  | Floor notes                                                                                                      |
 | ------------------------ | ------------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
@@ -90,8 +92,34 @@ Grok 4.7 has no approved mapping. Every bracket spelling tried
 (`grok-4.7[effort=...]` with and without `fast`, `reasoning=`, and
 `grok-4-7[...]`) fell back to that same account default, which is easy to
 mistake for success because it is itself a Grok 4.7 model. Only bare flat IDs
-such as `grok-4.7-medium` resolved as requested, and the approved catalogue
-does not emit bare IDs. Do not pin Grok 4.7 until a mapping is approved.
+such as `grok-4.7-medium` resolved as requested, but Grok 4.7 still lacks
+its own approved registry entry and complete per-pin evidence. It stays outside
+the shipped catalogue. This is a family-specific admission gap, not a blanket
+prohibition of exact-ID pins.
+
+## Sonnet 5.5 Exact-ID Pin Evidence
+
+The 2026-10-01 Cursor CLI catalogue lists
+`claude-sonnet-5-5-low|medium|high|xhigh|max`. In Cursor desktop 3.22.12,
+every `claude-sonnet-5-5[effort=...]` probe fell back to the account default,
+`grok-4.7-high-fast`. Exact-ID pins
+`claude-sonnet-5-5-low|medium|high|xhigh|max` instead matched their requested
+rungs in `subagentStart`, Shell `preToolUse`, and `subagentStop`. The Opus 5.5
+low positive control matched its established mapping; unknown-family and
+Sonnet 5.5 `ultra` exact-ID controls both fell back to `grok-4.7-high-fast`.
+Catalog visibility or a subagent self-report does not establish those results.
+The 16 correlated summary rows and 64 native events from both rounds live in
+`packages/cli/src/providers/cursor/codec/__fixtures__/cursor-pin-probe-2026-10-01.jsonl`
+and `cursor-pin-probe-2026-10-01-events.jsonl`; the adjacent `README.md` records
+provenance and excludes unrelated discovery calls.
+
+Sonnet 5.5 mappings write the verified exact ID as frontmatter `model`.
+Existing Sonnet 5, Opus, Fable, GPT, and Grok mappings retain their independently
+verified selectors. Neither selector form is universally valid: every exact-ID
+mapping requires native hook evidence, non-default-rung and invalid-selector
+controls, and an explicit approved registry entry. There is no generic
+pass-through of flat CLI IDs. See the
+[probe runbook](../../../../apps/oat-docs/docs/contributing/verifying-cursor-pins.md).
 
 ## Historical Opus Cursor Probe Evidence (Retired)
 
@@ -177,8 +205,10 @@ and non-thinking variants.
 - `claude-fable-5-1-thinking-high`: eligible specialist for hard reasoning and
   the bundled Frontier terminal target; xhigh only for evaluated long-horizon
   work. Cursor lists Fable as "NO ZDR"; confirm retention eligibility.
-- `claude-sonnet-5-thinking-high`: strong provider-diversity alternative for
-  normal implementation and agentic work when available.
+- `claude-sonnet-5-5-high`: exact-ID provider-diversity option for normal
+  implementation and agentic work; qualify task performance separately.
+- `claude-sonnet-5-thinking-high`: supported compatibility option for
+  established workflows.
 - `gpt-5.4-mini-medium`: economical general tool and coding worker.
 - `gpt-5.4-nano-medium`: strict extraction, classification, ranking, and simple
   read-only tool calls. Not a semantic repository worker.

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