@open-agent-toolkit/cli 0.2.49 → 0.2.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/assets/bundle-metadata.json +1 -1
  2. package/assets/docs/cli-utilities/tool-packs.md +35 -24
  3. package/assets/docs/reference/cli-reference.md +20 -5
  4. package/assets/docs/reference/file-locations.md +8 -2
  5. package/assets/docs/reference/oat-directory-structure.md +14 -5
  6. package/assets/docs/reference/troubleshooting.md +22 -4
  7. package/assets/docs/workflows/projects/artifacts.md +9 -4
  8. package/assets/docs/workflows/projects/lifecycle.md +17 -5
  9. package/assets/docs/workflows/projects/picking-up-projects.md +26 -9
  10. package/assets/docs/workflows/projects/pr-flow.md +5 -3
  11. package/assets/docs/workflows/projects/reviewing-oat-prs.md +12 -8
  12. package/assets/public-package-versions.json +4 -4
  13. package/assets/skills/oat-project-autonomous/references/gate-inventory.md +2 -2
  14. package/assets/skills/oat-project-complete/SKILL.md +193 -26
  15. package/assets/skills/oat-project-complete/scripts/execute-synced-archive-entry.mjs +306 -0
  16. package/assets/skills/oat-project-complete/scripts/finalize-synced-archive.mjs +125 -0
  17. package/assets/skills/oat-project-complete/scripts/parse-synced-archive-resume-fields.mjs +106 -0
  18. package/assets/skills/oat-project-complete/scripts/recover-completion-receipts.mjs +110 -0
  19. package/assets/skills/oat-project-complete/scripts/resolve-synced-archive-entry.mjs +164 -0
  20. package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +2 -2
  21. package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +2 -2
  22. package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +2 -2
  23. package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +2 -2
  24. package/dist/commands/doctor/index.d.ts +7 -0
  25. package/dist/commands/doctor/index.d.ts.map +1 -1
  26. package/dist/commands/doctor/index.js +44 -23
  27. package/dist/commands/pjm/index.d.ts +0 -2
  28. package/dist/commands/pjm/index.d.ts.map +1 -1
  29. package/dist/commands/pjm/index.js +5 -4
  30. package/dist/commands/pjm/migrate.d.ts +2 -1
  31. package/dist/commands/pjm/migrate.d.ts.map +1 -1
  32. package/dist/commands/pjm/migrate.js +23 -17
  33. package/dist/commands/project/archive/archive-utils.d.ts +8 -1
  34. package/dist/commands/project/archive/archive-utils.d.ts.map +1 -1
  35. package/dist/commands/project/archive/archive-utils.js +147 -50
  36. package/dist/commands/project/archive/push-runner.d.ts.map +1 -1
  37. package/dist/commands/project/archive/push-runner.js +15 -2
  38. package/dist/commands/project/links/compute.d.ts +1 -0
  39. package/dist/commands/project/links/compute.d.ts.map +1 -1
  40. package/dist/commands/project/links/compute.js +5 -4
  41. package/dist/commands/project/links/index.d.ts +9 -0
  42. package/dist/commands/project/links/index.d.ts.map +1 -1
  43. package/dist/commands/project/links/index.js +71 -2
  44. package/dist/commands/project/list.d.ts +10 -2
  45. package/dist/commands/project/list.d.ts.map +1 -1
  46. package/dist/commands/project/list.js +205 -29
  47. package/dist/commands/project/open/index.d.ts +2 -0
  48. package/dist/commands/project/open/index.d.ts.map +1 -1
  49. package/dist/commands/project/open/index.js +16 -1
  50. package/dist/commands/project/prune/index.d.ts +10 -4
  51. package/dist/commands/project/prune/index.d.ts.map +1 -1
  52. package/dist/commands/project/prune/index.js +85 -15
  53. package/dist/commands/project/pull/index.d.ts +4 -0
  54. package/dist/commands/project/pull/index.d.ts.map +1 -1
  55. package/dist/commands/project/pull/index.js +82 -3
  56. package/dist/commands/project/sync/git.d.ts +9 -0
  57. package/dist/commands/project/sync/git.d.ts.map +1 -1
  58. package/dist/commands/project/sync/git.js +18 -0
  59. package/dist/commands/project/sync/ref-sync.d.ts +16 -1
  60. package/dist/commands/project/sync/ref-sync.d.ts.map +1 -1
  61. package/dist/commands/project/sync/ref-sync.js +288 -17
  62. package/dist/commands/project/sync/resolve-target.d.ts +10 -0
  63. package/dist/commands/project/sync/resolve-target.d.ts.map +1 -1
  64. package/dist/commands/project/sync/resolve-target.js +56 -1
  65. package/dist/commands/shared/project-scope.d.ts +2 -0
  66. package/dist/commands/shared/project-scope.d.ts.map +1 -1
  67. package/dist/commands/shared/project-scope.js +5 -0
  68. package/dist/commands/state/generate.d.ts +2 -0
  69. package/dist/commands/state/generate.d.ts.map +1 -1
  70. package/dist/commands/state/generate.js +93 -28
  71. package/dist/commands/status/index.d.ts +3 -1
  72. package/dist/commands/status/index.d.ts.map +1 -1
  73. package/dist/commands/status/index.js +77 -10
  74. package/dist/commands/tools/shared/pack-inventory.d.ts +10 -0
  75. package/dist/commands/tools/shared/pack-inventory.d.ts.map +1 -1
  76. package/dist/commands/tools/shared/pack-inventory.js +71 -21
  77. package/package.json +2 -2
package/assets/bundle-metadata.json CHANGED
@@ -1,4 +1,4 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "oatVersion": "0.2.49"
3
+ "oatVersion": "0.2.51"
4
4
  }
package/assets/docs/cli-utilities/tool-packs.md CHANGED
@@ -189,23 +189,30 @@ creates `~/.oat/ideas/backlog.md` and `~/.oat/ideas/scratchpad.md`. Only the
189
189
  `workflows` project-scaffold seeds — `.oat/projects-root`, `.oat/config.json`,
190
190
  and the project `.gitkeep` files — are pinned to project scope.
191
191
 
192
- #### User-scope agents reach no provider
193
-
194
- Canonical **agents** are installed at either scope, but only project scope
195
- materializes a provider view for them. At user scope the sync pipeline
196
- enumerates skills only, and the sole user-scope agent materialization is the
197
- bundled managed role file set (`oat-phase-implementer.md` and
198
- `oat-reviewer.md`). A pack installed at user scope therefore writes its agents
199
- to `~/.agents/agents/` where no provider can see them — for example
200
- `oat tools install workflows --scope user` leaves `oat-codebase-mapper` without
201
- a provider agent, and `oat tools install research --scope user` does the same
202
- for `skeptical-evaluator`.
192
+ #### User-scope agents have limited native materialization
193
+
194
+ Canonical **agents** are installed at either scope. At user scope, native
195
+ Codex or Cursor role materialization is active only when that adapter is active
196
+ under the resolved sync config: explicit enablement wins without filesystem
197
+ detection, explicit disablement wins despite detection, and an unset adapter
198
+ follows detection. That native materialization supplies the bundled managed
199
+ role files (`oat-phase-implementer.md` and `oat-reviewer.md`); it does not
200
+ materialize other pack-owned user agents. For example, a user-scope workflows
201
+ install leaves `oat-codebase-mapper` without a native provider role, and a
202
+ user-scope research install does the same for `skeptical-evaluator`. When no
203
+ Codex or Cursor adapter is active, even the bundled managed roles lack native
204
+ materialization.
205
+
206
+ This diagnostic concerns native provider roles only. Providers may read
207
+ canonical agent instructions through a separate loaded, user, and project
208
+ lookup contract; that read availability does not establish native
209
+ materialization and does not suppress this finding.
203
210
 
204
211
  `oat status` and `oat doctor` name the affected agents with a
205
212
  `user-agent-unmaterialized` finding rather than reporting the pack as complete
206
213
  without qualification. Install the pack at **project scope** when you need its
207
- agents; `oat tools update` cannot repair this, because it is a scope limitation
208
- rather than drift.
214
+ native provider roles; `oat tools update` cannot repair this, because it is a
215
+ scope limitation rather than drift.
209
216
 
210
217
  Repository templates under `.oat/templates/` are **owner-owned seeds**. OAT
211
218
  compares a source-backed seed with its bundled default: a byte-equivalent copy
@@ -299,12 +306,14 @@ The canonical surface splits active operational state (under `pjm/`) from durabl
299
306
 
300
307
  Decisions are now file-per-record under `reference/decisions/` (created and indexed with the [`oat decision`](config-and-local-state.md#oat-decision-) command group), replacing the legacy single `decision-record.md`. Repos still on the old `reference/` layout can migrate with `oat pjm migrate`.
301
308
 
302
- > **Current migration prerequisite:** In CLI `0.2.37`, `oat pjm migrate` still
303
- > requires project-scope `tools.project-management: true` in `.oat/config.json`;
304
- > a user-only pack install does not satisfy that gate. In an adopted legacy
305
- > repository, run `oat config set tools.project-management true` before the
306
- > migration preview. Removing this temporary coupling is tracked by
307
- > `BL-260827-correct-scope-and-adoption`.
309
+ Migration eligibility is independent of where the `project-management` pack is
310
+ installed. `oat pjm migrate` resolves the repository's adoption state for
311
+ diagnostic context, then inventories recognized legacy sources before writing.
312
+ A complete current layout returns `already-migrated`; recognized legacy input
313
+ can be previewed or applied from any adoption state; and a repository with
314
+ neither recognized legacy input nor a complete current layout is skipped with
315
+ an `oat pjm init` recovery. `--print-prompt` only reads the bundled prompt and
316
+ does not inspect adoption or modify the repository.
308
317
 
309
318
  Decision records still require repository PJM adoption. Run `oat pjm init` first: like every repository-mutating PJM command, `oat decision init` fails closed in an unadopted repository, writes nothing, and returns `oat pjm init` as the recovery. Once the repository is adopted, `oat decision init` scaffolds only the decision surface — the decision directory, generated index, and decision-specific AGENTS guidance — without touching current state, roadmap, or backlog artifacts. It does not require the `project-management` pack. If the pack is installed later, its root guidance is maintained as a separate managed section so the decision instructions remain independently reusable.
310
319
 
@@ -322,11 +331,13 @@ repository-mutating PJM command checks it before writing anything:
322
331
  | `partial-initialization` | Some canonical scaffold files exist but the surface is incomplete | `oat pjm init` |
323
332
  | `none` | The repository has not adopted PJM | `oat pjm init` |
324
333
 
325
- `oat pjm`, `oat backlog`, and `oat decision` mutations **fail closed** for
326
- `partial-initialization` and `none`. They write nothing and return an error
327
- naming the repository path and `oat pjm init` as the recovery. `oat backlog
328
- init` and `oat decision init` are no longer alternate adoption paths for the
329
- full PJM surface.
334
+ Normal `oat pjm`, `oat backlog`, and `oat decision` mutations **fail closed**
335
+ for `partial-initialization` and `none`. They write nothing and return an error
336
+ naming the repository path and `oat pjm init` as the recovery. The explicit
337
+ `oat pjm migrate` command is the bounded exception: recognized legacy sources
338
+ authorize that migration regardless of the adoption label. `oat backlog init`
339
+ and `oat decision init` are no longer alternate adoption paths for the full PJM
340
+ surface.
330
341
 
331
342
  Run `oat pjm doctor` to inspect an existing surface. It is read-only, reports
332
343
  missing canonical files, leftover template frontmatter, and
package/assets/docs/reference/cli-reference.md CHANGED
@@ -80,13 +80,19 @@ Notable commands introduced in the current CLI surface:
80
80
  `--no-commit` leaves the new record uncommitted for the caller to persist.
81
81
  With `--json`, the receipt includes `status`, `sha`, and `ref`, plus
82
82
  `conflicts` when applicable and per-child results when coordination children
83
- were requested.
83
+ were requested. A project whose authoritative ref is
84
+ `refs/oat/completed/<project>` is terminal and cannot be pulled or opened.
85
+ A same-SHA `refs/oat/projects/<project>` ref is only an inert alias; differing
86
+ active and completed SHAs are reported as a terminal mismatch that must be
87
+ repaired before lifecycle work continues.
84
88
  - `oat project links [project] --format markdown|json` - render SHA-pinned
85
89
  links for the linkable artifacts on the project ref. On GitHub origins the
86
90
  artifacts become full-SHA blob links; other hosts degrade to the retained ref
87
91
  and short SHA without guessing a web URL. `--durable-summary <path>` accepts
88
92
  only a path contained in the repository, normalizes it repository-relative,
89
- and renders it as a code span rather than a guessed remote link.
93
+ and renders it as a code span rather than a guessed remote link. Completed
94
+ projects resolve through `refs/oat/completed/<project>` while the rendered
95
+ artifact URLs remain pinned to the verified full source SHA.
90
96
  - `oat project pause [project]` - persist the pause state and clear the active
91
97
  project pointer. If synced publication is declined or fails after the pause
92
98
  commit is created, that clean commit is retained; address the publication
@@ -99,7 +105,10 @@ Notable commands introduced in the current CLI surface:
99
105
  commit. If remote deletion succeeds but local checkout removal fails, the
100
106
  local ref, record, and checkouts are retained. Resolve the reported local
101
107
  obstruction and retry `prune --force`; do not run `project push`, which would
102
- republish the deleted remote ref.
108
+ republish the deleted remote ref. For a completed project, explicit prune
109
+ deletes the completed ref and any same-SHA active alias but preserves durable
110
+ local and S3 archive snapshots. A differing-SHA terminal mismatch blocks
111
+ prune and retains both refs.
103
112
  - `oat project migrate <path> --to synced [--no-commit]` - migrate an existing
104
113
  shared project to synced storage while preserving its artifacts and
105
114
  retargeting the active project pointer. `--no-commit` leaves the parent
@@ -110,7 +119,13 @@ Notable commands introduced in the current CLI surface:
110
119
  parents. A malformed discovery record with no materialized checkout appears
111
120
  as a `recorded-invalid` row. When the checkout is materialized, its existing
112
121
  row instead carries the restore hint and `recordError` parse diagnostic in
113
- `--json` output.
122
+ `--json` output. Fully retired completed refs and same-SHA active aliases are
123
+ omitted from active discovery. A differing-SHA active/completed pair appears
124
+ as a `terminal-invalid` row with a recovery diagnosis. When reconciling a
125
+ local synced record or checkout, only a verified missing
126
+ `refs/oat/completed/<project>` result counts as absence. Transport,
127
+ authentication, and other lookup failures fail the command closed; they are
128
+ never converted into a `recorded-absent` row or pull guidance.
114
129
  - `oat tools migrate --pack <pack> --from <scope> --to <scope>` - move one installed pack between project and user scope. Always previews first, installs and re-inventories the destination before touching the source, and offers source removal only after the destination is verified complete. Declining or running non-interactively leaves the pack installed at both scopes rather than failing. `--dry-run` stops after the preview; there is no force flag. See [Tool Packs](../cli-utilities/tool-packs.md#oat-tools-migrate).
115
130
  - `oat pjm doctor --json` - read-only repository PJM diagnostics whose result carries an additive `adoption` object (`state` of `declared` | `inferred-legacy` | `partial-initialization` | `none`, `repoRoot`, and `recovery`). This, not `oat tools has project-management`, is the check that answers whether _this repository_ adopted PJM.
116
131
  - `oat config dump --json` - merged config with source attribution
@@ -121,7 +136,7 @@ Notable commands introduced in the current CLI surface:
121
136
  - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
122
137
  - `oat project list --json` - summary state for tracked projects under the configured projects root
123
138
  - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
124
- - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately omits the lifecycle commit receipt. Never pass it through `oat-project-complete`, which requires that receipt.
139
+ - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes `refs/oat/completed/<project>` authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. Legacy complete records receive a cleanup diagnosis rather than pull/open guidance. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt.
125
140
  - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
126
141
  - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
127
142
  - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).
package/assets/docs/reference/file-locations.md CHANGED
@@ -92,8 +92,10 @@ Config ownership note:
92
92
  - Synced checkout: `.oat/projects/synced/<project>/` (gitignored nested
93
93
  worktree)
94
94
  - Synced record: `.oat/projects/synced/<project>.json` (tracked on the parent
95
- branch)
96
- - Synced ref: `refs/oat/projects/<project>` on `origin`
95
+ branch while the project is active; removed after durable archived closeout)
96
+ - Active synced ref: `refs/oat/projects/<project>` on `origin`
97
+ - Completed synced ref: `refs/oat/completed/<project>` on `origin` (the
98
+ authoritative terminal reachability root after archive)
97
99
  - Local: `.oat/projects/local/<project>/`
98
100
  - Archived: `.oat/projects/archived/<project>/`
99
101
 
@@ -108,6 +110,10 @@ Archive sync surfaces:
108
110
  - Remote archive base: `archive.s3Uri` in `.oat/config.json`
109
111
  - Archive sync command: `oat repo archive sync` or `oat repo archive sync <project-name>`
110
112
  - Remote archive snapshot shape: `<archive.s3Uri>/<repo-slug>/projects/YYYYMMDD-<project-name>/`
113
+ - Terminal archive metadata:
114
+ `.oat/projects/archived/<project>/.oat-archive-source.json` binds the
115
+ snapshot to its synced source-ref SHA so a recordless interrupted closeout
116
+ can retry without recreating the active record or checkout.
111
117
  - Summary export target:
112
118
  `<repo>/<archive.summaryExportPath>/YYYYMMDD-<project-name>.md` when
113
119
  configured. The archive report returns this absolute filesystem path, while
package/assets/docs/reference/oat-directory-structure.md CHANGED
@@ -181,7 +181,8 @@ Each OAT project lives under:
181
181
  - `.oat/projects/synced/<project>/` for a gitignored nested worktree whose
182
182
  history is published to `refs/oat/projects/<project>`
183
183
  - `.oat/projects/synced/<project>.json` for the tracked discovery record that
184
- identifies the ref, remote, and active or complete status
184
+ identifies the ref, remote, and active transaction state; archived closeout
185
+ deletes this record after terminal durability is verified
185
186
  - `.oat/projects/local/<project>/`
186
187
  - `.oat/projects/archived/<project>/`
187
188
 
@@ -189,16 +190,24 @@ Completion and archive sync behavior:
189
190
 
190
191
  - When archiving is selected, `oat-project-complete` archives locally into
191
192
  `.oat/projects/archived/<project>/`. For a synced project, the snapshot omits
192
- the nested checkout's `.git` pointer and `reviews/`, then completion marks
193
- the tracked record complete, removes the nested worktree, and retains the
194
- project ref so pinned links keep resolving.
193
+ the nested checkout's `.git` pointer and `reviews/`. After required local and
194
+ configured S3 durability succeeds, completion makes
195
+ `refs/oat/completed/<project>` authoritative, removes the nested worktree,
196
+ and deletes the tracked JSON record. Full-SHA links remain reachable through
197
+ the completed ref.
198
+ - Both a completed-only ref and completed plus same-SHA active alias are valid
199
+ terminal shapes. The alias is inert and ignored by list, pull, and open;
200
+ differing SHAs are a hard mismatch with explicit recovery guidance.
195
201
  - When archiving is disabled or declined, completion leaves the synced
196
202
  checkout and ref in place, pushes the finalized artifacts, and exact-path
197
203
  commits the tracked record as complete.
198
- - If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, completion also uploads a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
204
+ - If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, completion must successfully upload a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/` before it retires the active record and checkout.
199
205
  - `oat repo archive sync` syncs all repo archived projects down from S3 into `.oat/projects/archived/`.
200
206
  - `oat repo archive sync <project-name>` syncs the latest dated remote snapshot for a single project into `.oat/projects/archived/<project-name>/`.
201
207
  - Default archive sync is non-destructive toward unrelated local-only archive data, but it does replace a local project archive when a newer dated remote snapshot is selected for that same project.
208
+ - `oat project prune` is separate and destructive: for a terminal project it
209
+ removes the completed ref and any matching active alias, while leaving local
210
+ and S3 archive snapshots intact. A ref mismatch blocks deletion.
202
211
 
203
212
  Typical contents:
204
213
 
package/assets/docs/reference/troubleshooting.md CHANGED
@@ -167,12 +167,30 @@ Both commands report managed pack state with a scoped recovery command:
167
167
  place and your edits are gone. The finding is informational and carries no
168
168
  recovery command for exactly that reason.
169
169
  - `user-agent-unmaterialized` — the pack installed canonical agents into
170
- `~/.agents/agents/`, but user scope materializes no provider view for them
171
- beyond the bundled managed role files. `oat tools update` cannot fix this.
172
- Install the pack at project scope (`oat tools install <pack> --scope project`)
173
- when you need its agents. See
170
+ `~/.agents/agents/`, but active native Codex/Cursor adapters materialize only
171
+ the bundled managed role files at user scope. Other pack-owned agents remain
172
+ unmaterialized; when neither adapter is active, the managed roles do too.
173
+ Provider access to canonical instructions through loaded, user, and project
174
+ reads is a separate contract and does not clear this native-role finding.
175
+ `oat tools update` cannot fix it. Install the pack at project scope
176
+ (`oat tools install <pack> --scope project`) when you need its native roles. See
174
177
  [Tool packs](../cli-utilities/tool-packs.md) for the full limitation.
175
178
 
179
+ ## `status` or `doctor` reports `packs:inventory`
180
+
181
+ OAT could not read the canonical managed-pack inventory. `oat status` keeps the
182
+ rest of the report available and returns `packs.availability.status` as
183
+ `unavailable` in JSON, with an empty `packs.states` array and a structured
184
+ diagnostic. `oat doctor` emits the same condition as a warning instead of
185
+ stopping its other checks. Reported project and home paths remain redacted.
186
+
187
+ Rebuild the CLI workspace, then rerun the command named in the diagnostic:
188
+
189
+ ```bash
190
+ pnpm build
191
+ oat status # or: oat doctor
192
+ ```
193
+
176
194
  ## `status` or `doctor` reports `legacy-false-conflict`
177
195
 
178
196
  An older repository left `tools.<pack>: false` in shared config while managed
package/assets/docs/workflows/projects/artifacts.md CHANGED
@@ -28,10 +28,15 @@ rebases it on the fetched project ref, and pushes only that ref. Arrival skills
28
28
  run `oat project pull` before reading artifacts so a record or remote ref can
29
29
  materialize the checkout first.
30
30
 
31
- The tracked JSON record is routing metadata, not a copy of the project. It
32
- identifies the slug, `origin`, ref, status, and archive snapshot when present.
33
- The project ref remains the source of truth for active artifact content and
34
- history.
31
+ The tracked JSON record is active routing metadata, not a copy of the project.
32
+ It identifies the slug, `origin`, active ref, and status. The active project ref
33
+ remains the source of truth for active artifact content and history.
34
+
35
+ Archived closeout transitions terminal identity to
36
+ `refs/oat/completed/<project>`, deletes the active record and checkout, and
37
+ persists source-ref identity in local archive metadata. Arrival and pull flows
38
+ never rematerialize a completed project as active state: the completed ref and
39
+ archive metadata own terminal reachability and retry identity.
35
40
 
36
41
  ## Core artifacts
37
42
 
package/assets/docs/workflows/projects/lifecycle.md CHANGED
@@ -84,14 +84,26 @@ On completion, OAT treats archive handling as an explicit closeout choice:
84
84
  - For a synced project, closeout first finalizes the project artifacts and
85
85
  pushes them to `refs/oat/projects/<project>`. Archive then requires a clean,
86
86
  fully pushed checkout; copies it without the `.git` pointer or `reviews/`;
87
- marks the tracked record complete; commits the record and configured durable
88
- exports on the parent branch; removes the nested checkout; and retains the
89
- ref. This order keeps SHA-pinned PR links valid after completion.
90
- - If `.oat/config.json` enables `archive.s3SyncOnComplete` and sets `archive.s3Uri`, completion also attempts an S3 upload for a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
87
+ seals configured durable exports; transitions terminal reachability to
88
+ `refs/oat/completed/<project>`; removes the nested checkout; and deletes the
89
+ tracked JSON record in the parent lifecycle commit. This order keeps
90
+ SHA-pinned PR links valid without leaving active discovery state behind.
91
+ - A completed-only ref and a completed ref plus same-SHA active alias are both
92
+ valid terminal shapes. The active alias is inert: list omits it and pull/open
93
+ reject it. Differing SHAs are a hard mismatch with recovery guidance.
94
+ - If `.oat/config.json` enables `archive.s3SyncOnComplete` and sets `archive.s3Uri`, completion requires the S3 upload of a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/` to succeed before terminal record/ref cleanup. A failed configured upload leaves retry identity intact and does not claim closeout.
91
95
  - If `.oat/config.json` sets `archive.awsProfile` and/or `archive.awsRegion`, those values are forwarded to every `aws` invocation triggered by completion (preflight checks + `aws s3 sync`) and override any ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` / `AWS_REGION` / `AWS_DEFAULT_REGION` values. The repo's archive-scoped credentials are treated as deliberate intent so users don't have to unset shell env vars before running completion. See [`config-and-local-state.md`](../../cli-utilities/config-and-local-state.md) for the full precedence chain.
92
96
  - If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
93
- - Missing or unusable AWS CLI configuration produces warnings during completion instead of blocking closeout.
97
+ - Missing or unusable AWS CLI configuration blocks synced terminal cleanup when S3 durability is configured; when S3 sync is not configured, it is not part of the durability requirement.
94
98
  - `oat repo archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
99
+ - Persisted archive metadata binds the snapshot to the source-ref SHA, allowing
100
+ an interrupted closeout or legacy complete record to resume without
101
+ rematerializing an active project. Dashboard and list surfaces omit fully
102
+ retired projects and report precise cleanup or ref-mismatch diagnoses for
103
+ remaining legacy state.
104
+ - `oat project links` continues to render full-SHA links through the completed
105
+ ref. `oat project prune` is a separate destructive choice that removes
106
+ terminal ref reachability but preserves local and S3 archive snapshots.
95
107
 
96
108
  ### Phase status: `pr_open`
97
109
 
package/assets/docs/workflows/projects/picking-up-projects.md CHANGED
@@ -25,6 +25,14 @@ the nested checkout. When the selected project is a coordination parent, pull
25
25
  also discovers and pulls its child projects by default. Pass `--no-children`
26
26
  only when you intentionally want the selected project alone.
27
27
 
28
+ Completed projects are not adoption candidates. Their authoritative ref is
29
+ `refs/oat/completed/<project>`; both `pull` and `open` return a terminal
30
+ diagnosis instead of recreating an archived checkout or record. A same-SHA
31
+ active ref may remain as an inert alias and is ignored. Differing active and
32
+ completed SHAs require repair before lifecycle work continues. The same guard
33
+ applies to coordination children: a terminal child discovered while pulling
34
+ its parent is reported and skipped rather than adopted.
35
+
28
36
  After adoption, set or open the project through the normal lifecycle command
29
37
  you are using. Arrival-aware project skills pull before reading its artifacts.
30
38
 
@@ -47,17 +55,19 @@ you are using. Arrival-aware project skills pull before reading its artifacts.
47
55
  project ref during sync operations such as `pull`; do not expect a generic
48
56
  clone or `git fetch` to materialize the checkout.
49
57
 
50
- ## Why retained refs remain durable
58
+ ## Why completed refs remain durable
51
59
 
52
- `refs/oat/projects/<project>` is a real Git ref locally and on `origin`. The
60
+ `refs/oat/completed/<project>` is a real Git ref locally and on `origin`. The
53
61
  objects reachable from it remain garbage-collection roots even when no nested
54
62
  checkout exists. Branch pruning, remote-tracking-ref pruning, and
55
- `git worktree prune` do not delete the project ref. Completion deliberately
56
- retains it so pinned PR links remain valid.
63
+ `git worktree prune` do not delete the completed ref. Completion deliberately
64
+ retains this terminal reachability root so pinned PR links remain valid.
57
65
 
58
- Only the explicit destructive operation `oat project prune` removes the local
59
- and remote project refs. Treat it as permanent project-history deletion and
60
- review its warnings before using `--force`.
66
+ Only the explicit destructive operation `oat project prune` removes the
67
+ completed ref and any matching active alias. Treat that as permanent Git
68
+ project-history reachability deletion and review its warnings before using
69
+ `--force`. Prune does not remove durable local or S3 archive snapshots, and it
70
+ refuses to delete either ref when their SHAs differ.
61
71
 
62
72
  ## Archive contents
63
73
 
@@ -65,8 +75,15 @@ When archive is selected, completion copies a synced project into
65
75
  `.oat/projects/archived/<project>/` without the nested checkout's `.git`
66
76
  pointer or `reviews/`. S3 snapshots also omit `pr/`, following the existing
67
77
  archive policy. When archive is disabled or declined, the active synced
68
- checkout remains in place. Both paths retain the project ref and commit the
69
- tracked record as `complete`; only the archive path records an archive snapshot.
78
+ checkout remains in place. Successful archived closeout instead uploads the S3
79
+ snapshot first when configured, makes the completed ref authoritative, removes
80
+ the checkout, and deletes the tracked JSON record. The local archive metadata
81
+ retains the source-ref identity needed for recordless retries and later S3
82
+ restore without recreating active state.
83
+
84
+ If closeout is interrupted after terminal archive identity exists, rerun
85
+ completion so it can resume from the completed ref and archive metadata. Do not
86
+ use `pull` or `open` to recreate an active record or checkout.
70
87
 
71
88
  ## Related
72
89
 
package/assets/docs/workflows/projects/pr-flow.md CHANGED
@@ -76,9 +76,11 @@ Both completion orderings are supported:
76
76
 
77
77
  An open PR is not a completion blocker. When completion archives project
78
78
  artifacts, the archive-aware flow regenerates and synchronizes the open PR body
79
- so its artifact links remain valid. Synced completion retains the project ref,
80
- which keeps its SHA-pinned links resolvable after the nested checkout is
81
- removed.
79
+ so its artifact links remain valid. Synced completion makes
80
+ `refs/oat/completed/<project>` authoritative at the verified source SHA. A
81
+ same-SHA `refs/oat/projects/<project>` ref may remain only as an inert alias;
82
+ the completed ref keeps the SHA-pinned links resolvable after the nested
83
+ checkout and tracked record are removed.
82
84
 
83
85
  ## Reference artifacts
84
86
 
package/assets/docs/workflows/projects/reviewing-oat-prs.md CHANGED
@@ -6,17 +6,21 @@ description: Understand synced-project records, SHA-pinned artifact links, and t
6
6
  # Reviewing OAT PRs
7
7
 
8
8
  A PR for a synced OAT project contains the implementation diff without placing
9
- the agent-facing project tree on the feature branch. Reviewers get durable
10
- project context through a small tracked record and a generated links block in
11
- the PR body.
9
+ the agent-facing project tree on the feature branch. While the project is
10
+ active, reviewers discover its context through a small tracked record and a
11
+ generated links block in the PR body.
12
12
 
13
13
  ## The synced record
14
14
 
15
- `.oat/projects/synced/<project>.json` is tracked on the feature branch. It
16
- names the project slug, `origin`, `refs/oat/projects/<project>`, whether the
17
- project is active or complete, and the archive snapshot when completion has
18
- created one. It is discovery and lifecycle metadata; the project artifacts
19
- themselves live on the project ref.
15
+ `.oat/projects/synced/<project>.json` is tracked on the feature branch while
16
+ the project is active. It names the project slug, `origin`, and
17
+ `refs/oat/projects/<project>`. The record and active ref are discovery and
18
+ lifecycle metadata; the project artifacts themselves live on the project ref.
19
+
20
+ Successful archived closeout deletes the tracked record and makes
21
+ `refs/oat/completed/<project>` the authoritative terminal reachability root.
22
+ The PR's existing SHA-pinned artifact links remain valid through that completed
23
+ ref even after the active checkout and record are gone.
20
24
 
21
25
  ## The artifact links block
22
26
 
package/assets/public-package-versions.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
- "cli": "0.2.49",
3
- "docs-config": "0.2.49",
4
- "docs-theme": "0.2.49",
5
- "docs-transforms": "0.2.49"
2
+ "cli": "0.2.51",
3
+ "docs-config": "0.2.51",
4
+ "docs-theme": "0.2.51",
5
+ "docs-transforms": "0.2.51"
6
6
  }
package/assets/skills/oat-project-autonomous/references/gate-inventory.md CHANGED
@@ -244,7 +244,7 @@ remains immutable baseline evidence for the original p01-t01 verification.
244
244
  | `oat-project-summary/SKILL.md` | `68c197c44c18 -> NG`; `35cb2ea1d677 -> NG`; `a167d03559fa -> NG`; `cf317c17c586 -> SUMMARY-01`; `f3e49b727752 -> NG`; `f979b2342d28 -> NG`; `803bf40ec423 -> NG`; `c8fced47ef8e -> NG`; `d7ea1e2a4f5f -> NG`; `5f315ab87cb1 -> NG` |
245
245
  | `oat-project-pr-final/SKILL.md` | `601ac2b890f2 -> NG`; `c264a64398f0 -> NG`; `9efcbcee42ea -> NG`; `655d61df0a8f -> NG`; `cf317c17c586 -> PRFINAL-01`; `2de348a391c0 -> PRFINAL-03` |
246
246
  | `oat-project-pr-final/references/docs/autonomy-contract.md` | `* -> NG` |
247
- | `oat-project-complete/SKILL.md` | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `7bcbf58b54e9 -> NG`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `12f7c30a54c8 -> NG`; `fffe5eea5ebd -> NG`; `e7dc6fdc4eb3 -> COMPLETE-01`; `e5460e437299 -> NG`; `882b61c9096c -> NG`; `9ffa1c752505 -> NG` |
247
+ | `oat-project-complete/SKILL.md` | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `7bcbf58b54e9 -> NG`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `fffe5eea5ebd -> NG`; `e7dc6fdc4eb3 -> COMPLETE-01`; `e5460e437299 -> NG`; `882b61c9096c -> NG`; `9ffa1c752505 -> NG` |
248
248
  | `oat-project-review-provide/SKILL.md` | `1f4b981cac8b -> NG`; `adaeca152bb2 -> NG`; `2f7c201c3c06 -> NG`; `88f79700afdc -> NG`; `655d61df0a8f -> NG`; `efafde9ef5a0 -> NG`; `d2a3861d6323 -> REVIEWPROVIDE-02`; `65f5b9cf49cd -> REVIEWPROVIDE-04`; `962cb38d246a -> REVIEWPROVIDE-04`; `1a568483ba0b -> REVIEWPROVIDE-04`; `610e27edfe85 -> REVIEWPROVIDE-04`; `bb0096e95c47 -> REVIEWPROVIDE-06`; `55f6357a987d -> REVIEWPROVIDE-06`; `1bee61f8531c -> REVIEWPROVIDE-07`; `3d35091607a1 -> REVIEWPROVIDE-08`; `fb40c4341c4c -> NG`; `b22d16885150 -> NG`; `d2b25906242e -> REVIEWPROVIDE-08`; `fd8ebf72b3c4 -> NG`; `fcb9de611ff3 -> NG`; `d2a838dfb18d -> NG`; `c3d50ea7cf69 -> NG`; `09b1b8dd445c -> NG`; `7acc8f3718d2 -> REVIEWPROVIDE-09`; `b2fa883fc4a2 -> NG`; `fe4421531b4c -> NG` |
249
249
  | `oat-project-review-receive/SKILL.md` | `9b8a3743d626 -> NG`; `df49c8c6f192 -> NG`; `4ee8730382d3 -> NG`; `655d61df0a8f -> NG`; `765f897d67ac -> NG`; `53b58d16dd32 -> NG`; `fb8755a3bdf4 -> NG`; `c8ab5dd90075 -> NG`; `1f7dd98dff2f -> NG`; `56f78c6740e6 -> NG`; `76f5fb5a88cd -> NG`; `085abfa3599f -> REVIEWRECEIVE-01`; `3ad3aadb8c60 -> NG`; `a7d114059bb6 -> NG`; `ac88cfaa83d9 -> NG`; `594bbf70346c -> REVIEWRECEIVE-08`; `f31f07284718 -> REVIEWRECEIVE-02`; `aba178a21441 -> REVIEWRECEIVE-04`; `a37e601cd731 -> REVIEWRECEIVE-05`; `20e05e1a4381 -> REVIEWRECEIVE-06`; `90001dadf75f -> REVIEWRECEIVE-07`; `f8fd58180ecf -> NG`; `c3abcdc02d9f -> NG`; `f2ebdd6abb9b -> NG` |
250
250
  | `oat-project-review-provide/SKILL.md` | `2e794bf4fc4a -> REVIEWPROVIDE-08`; `5441ab977b46 -> REVIEWPROVIDE-08` |
@@ -260,7 +260,7 @@ remains immutable baseline evidence for the original p01-t01 verification.
260
260
  | `oat-project-dispatch-subagents/SKILL.md` | `eca03ad1ca12 -> PDISPATCH-01`; `59fbcdc79cea -> PDISPATCH-01` |
261
261
  | `oat-project-plan/SKILL.md` | `f99e44b39932 -> PLAN-12`; `7e6a9854504b -> NG` |
262
262
  | `oat-project-implement/references/completion-and-closeout.md` | `6909a5a5a1fa -> IMPLEMENT-19`; `a7c02ef670fd -> IMPLEMENT-19`; `9dde56d89a71 -> IMPLEMENT-16`; `13c41b2b2590 -> IMPLEMENT-16` |
263
- | `oat-project-complete/SKILL.md` | `0177956707aa -> NG`; `8305b5bb65ef -> NG`; `eb3e75663ac0 -> NG`; `8cc1fa5aab1e -> COMPLETE-01`; `4c209fbb4716 -> COMPLETE-01`; `02e4175e1171 -> COMPLETE-01`; `d698d4f98e76 -> COMPLETE-01`; `9f86a7218d93 -> COMPLETE-01`; `024713698d9a -> COMPLETE-01`; `c327995053fa -> COMPLETE-01`; `61f81d4ec7c1 -> COMPLETE-01`; `14fb2e56809f -> COMPLETE-01`; `7d4ff668744d -> COMPLETE-01`; `502a6c141784 -> COMPLETE-01`; `fb7e2db356af -> COMPLETE-01` |
263
+ | `oat-project-complete/SKILL.md` | `0177956707aa -> NG`; `8305b5bb65ef -> NG`; `eb3e75663ac0 -> NG`; `8cc1fa5aab1e -> COMPLETE-01`; `4c209fbb4716 -> COMPLETE-01`; `02e4175e1171 -> COMPLETE-01`; `d698d4f98e76 -> COMPLETE-01`; `9f86a7218d93 -> COMPLETE-01`; `024713698d9a -> COMPLETE-01`; `c327995053fa -> COMPLETE-01`; `61f81d4ec7c1 -> COMPLETE-01`; `14fb2e56809f -> COMPLETE-01`; `7d4ff668744d -> COMPLETE-01`; `502a6c141784 -> COMPLETE-01`; `fb7e2db356af -> COMPLETE-01`; `f73f8476360a -> NG`; `1e15f420039f -> NG`; `cc234032ddd7 -> NG`; `c3d25f1398bb -> NG`; `ca13a6645df2 -> NG` |
264
264
 
265
265
  ## Prompt-scan comparison
266
266