@open-agent-toolkit/cli 0.2.36 → 0.2.37

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.36"
+  "oatVersion": "0.2.37"
 }

package/assets/docs/cli-utilities/backlog-lifecycle.md

@@ -9,6 +9,18 @@ The file-backed backlog under `.oat/repo/pjm/backlog/` tracks work as one Markdo
 
 For the flag-by-flag command reference, see [`oat backlog archive`](config-and-local-state.md#oat-backlog-archive). For the two-layer PJM surface that hosts the backlog, see [Tool Packs](tool-packs.md#install-vs-initialize).
 
+## Adoption comes first
+
+`oat backlog` mutations require this repository to have adopted PJM. Installing
+the `project-management` pack makes the capability available — including at user
+scope, which is the default — but it does not adopt PJM for a repository, and
+`oat backlog init` is not an alternate adoption path.
+
+Run `oat pjm init` once per repository. Until adoption is recorded, backlog
+mutations write nothing and return an error naming the repository path and
+`oat pjm init` as the recovery. Check the current state with
+`oat pjm doctor --json` and read its `adoption.state` field.
+
 ## Where a backlog item lives
 
 - **`items/<id>.md`** - active, file-backed records. Each carries frontmatter with a `status` and an `updated` timestamp.
@@ -58,4 +70,10 @@ The manual close-out this command replaces is exactly where the two motivating r
 - **`pjm:backlog_completed_unarchived`** (warn) - `completed.md` references an item whose file still lives in `items/`.
 - **`pjm:backlog_duplicate_id`** (fail) - the same `<id>.md` exists in both `items/` and `archived/`. `oat backlog archive` refuses to auto-resolve this (it would clobber the archived record), so the duplicate must be reconciled by hand.
 
+These backlog checks run once the repository is adopted. `oat doctor` keys the
+`pjm:*` family on repository adoption state rather than on
+`tools.project-management`, so a repository whose PJM capability lives at user
+scope still gets full backlog diagnostics. An unadopted repository reports
+`pjm:adoption` with the `oat pjm init` recovery instead of backlog drift.
+
 Doctor reports drift; it never auto-fixes. A human or agent runs `oat backlog archive` (or corrects the status) and re-runs doctor to confirm the backlog is clean again.

package/assets/docs/cli-utilities/bootstrap.md

@@ -29,6 +29,7 @@ Key behavior:
 - Interactive adoption in TTY mode
 - JSON/non-TTY contract support
 - Establishes the base structure used by `oat status`, `oat sync`, `oat init tools`, and `oat doctor`
+- Pack intent recorded during guided setup is scoped: a project-scope install writes `tools.<pack>: true` to `.oat/config.json`, a user-scope install writes it to `~/.oat/config.json`, and neither writes the other
 - For project scope, creates canonical `.agents/skills/`, `.agents/agents/`, and `.agents/rules/` directories
 
 ### Guided setup
@@ -43,9 +44,10 @@ After core initialization completes, `oat init` can enter an interactive guided
 **Steps (each independently skippable):**
 
 1. **Tool packs** — install OAT tool packs. The core pack (diagnostics, passive docs access) is checked by default and always installs at user scope. Guided setup asks whether to customize per-pack scope:
-   - choose **Yes** to run the per-pack scope selector for user-eligible packs (`ideas`, `docs`, `utility`, `research`, `brainstorm`)
+   - choose **Yes** to run the per-pack scope selector for every pack that allows both scopes (`ideas`, `docs`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`)
    - choose **No** to apply additive per-pack defaults without extra scope prompts
-   - project-only packs such as `workflows` and `project-management` remain project-scoped
+   - on a fresh install every pack defaults to **user** scope, so capabilities follow you across repositories; an existing install keeps its current placement
+   - installing `project-management` installs the capability only. Adopting it for this repository is a separate, explicit `oat pjm init` step — see [Install vs. initialize](tool-packs.md#install-vs-initialize)
 2. **Local paths** — multi-select from default gitignored artifact paths (analysis, PR, reviews, ideas). Pre-existing paths are pre-checked; only new paths are added.
 3. **Documentation** — detect or enter docs metadata for the repo when documentation exists.
 4. **Provider sync** — sync provider project views via `oat sync --scope project`.
@@ -68,6 +70,7 @@ oat init --scope project
 
 Related commands:
 
-- `oat tools ...` (tool-pack install, update, remove, list, info): `tool-packs.md`
+- `oat tools ...` (tool-pack install, update, remove, migrate, list, info): `tool-packs.md`
+- `oat pjm init` (adopt project management for this repository): `tool-packs.md#install-vs-initialize`
 - `oat local ...`, `oat doctor`, and other utility commands: `config-and-local-state.md`
 - `oat status` / `oat sync` (provider sync): `../provider-sync/index.md`

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -94,7 +94,7 @@ Pass `--context`, `--decision`, and `--consequences` together when creating a re
 
 The decision index uses managed marker pairs and is deterministic, so an index merge conflict can be resolved by re-running `oat decision regenerate-index` and staging the result. Decision records replace the legacy single `decision-record.md`; repos still on the old layout migrate with `oat decision migrate` (or the broader `oat pjm migrate`).
 
-`oat decision init` is the lightweight standalone setup path. It does not require the `project-management` tool pack and does not create current state, roadmap, or backlog artifacts. Its AGENTS guidance uses `oat decision` directly while also recognizing `oat-pjm-decision` when that optional skill is installed later.
+`oat decision init` is the lightweight standalone setup path. It does not require the `project-management` tool pack and does not create current state, roadmap, or backlog artifacts. It is also not an alternate adoption path for the broader PJM surface: repository PJM mutations still require `oat pjm init`, and `oat decision` mutations fail closed with that recovery when the repository has not adopted PJM. Its AGENTS guidance uses `oat decision` directly while also recognizing `oat-pjm-decision` when that optional skill is installed later.
 
 ## `oat local ...`
 
@@ -165,7 +165,7 @@ Archive lifecycle settings live here as shared repo config:
 
 `archive.awsProfile` and `archive.awsRegion` are forwarded as `AWS_PROFILE` / `AWS_REGION` env vars into every `aws` spawn that runs during `oat-project-complete` and `oat repo archive sync`, and they override any values already set in the parent shell — the repo's archive-scoped declaration wins so users don't have to remember to unset `AWS_PROFILE` per shell. The per-invocation `oat repo archive sync --profile <profile>` and `--region <region>` flags then override the config for a single run, giving precedence `flag > config > shell env`. When neither flag nor config is set, the parent shell's `AWS_PROFILE` / `AWS_REGION` pass through unchanged. Raw access keys (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) remain a shell-environment concern — there is no config plumbing for them.
 
-Tool-pack installation state also lives here as shared repo config:
+Project-scope tool-pack intent also lives here as shared repo config:
 
 - `tools.core`
 - `tools.brainstorm`
@@ -176,19 +176,33 @@ Tool-pack installation state also lives here as shared repo config:
 - `tools.utility`
 - `tools.workflows`
 
-This complete eight-pack map is the shared project installation snapshot.
-Lifecycle reconciliation derives it only from project-scoped canonical assets;
-user-only packs do not set these keys. Use `oat config get tools.<pack>` to
-inspect repository installation state.
+These keys record **project-scope intent only**, and only for packs actually
+installed at project scope. Intent is true-or-absent: a lifecycle mutation
+writes `true` for the scope it changed and deletes the key on removal. It never
+writes `false`, never derives one pack's key from another's, and never writes
+the full eight-pack map. A user-scope install records the same shape under
+`~/.oat/config.json` instead. Use `oat config get tools.<pack>` to inspect
+declared project intent.
+
+Declared intent is not the same as what is installed. Use `oat tools list`,
+`oat tools info <name>`, `oat status`, or `oat doctor` to see observed
+inventory — placement, completeness, missing managed assets, and drift.
 
 For workflow routing or troubleshooting that needs current effective
 availability, run `oat tools has <pack>`. It checks project plus user scope by
-default; use `--scope project` or `--scope user` to isolate one scope. The
-global `--json` flag returns the matching scopes with the boolean result.
-
-PJM diagnostics intentionally use project configuration where repository setup
-is the question. Disabled or unset repos report PJM as skipped instead of
-treating absent `.oat/repo/pjm/` files as drift.
+default; use `--scope project` or `--scope user` to isolate one scope. A scope
+counts only when the pack is **complete** there. The global `--json` flag
+returns the matching scopes plus per-scope completeness and the missing assets
+behind a `false`.
+
+Repository PJM adoption is tracked separately from pack intent, under
+`pjm.initialized` and `pjm.schemaVersion` in `.oat/config.json`. PJM
+diagnostics key on that adoption state, not on `tools.project-management`, so a
+repository whose PJM capability lives at user scope is still diagnosed
+correctly. A repository that never adopted PJM reports adoption state `none`
+with `oat pjm init` as the recovery instead of treating absent
+`.oat/repo/pjm/` files as drift. See
+[Install vs. initialize](tool-packs.md#install-vs-initialize).
 
 Workflow automation preferences are also visible through `oat config` and can be set at local, shared, or user scope. Notable review-loop keys:
 

package/assets/docs/cli-utilities/configuration.md

@@ -87,33 +87,42 @@ Common keys in `.oat/config.json`:
 - `archive.wrapUpExportPath` — optional tracked destination for `oat-wrap-up` reports; when unset, the skill falls back to `.oat/repo/reference/wrap-ups`
 - `archive.awsProfile` — optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows
 - `archive.awsRegion` — optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows
-- `tools.<pack>` — project-scoped installation state for a bundled tool pack after lifecycle reconciliation
+- `tools.<pack>` — project-scope intent for a bundled tool pack (`true` or absent)
+- `pjm.initialized` / `pjm.schemaVersion` — explicit repository PJM adoption written by `oat pjm init`
 - `workflow.gates.skills` / `workflow.gates.execTargets` — per-skill gates and cross-runtime exec targets; manage with `oat gate`
 - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — default review budgets in milliseconds
 
-Tool-pack state example:
+Tool-pack intent example:
 
 ```bash
 oat config get tools.project-management
 oat config set tools.project-management true
 ```
 
-The `tools.*` group is a shared project installation snapshot, not an
-effective project-plus-user capability signal. `oat tools install`, `oat tools
-update`, and `oat tools remove` reconcile it from project-scoped canonical
-assets only. When project state is non-empty, reconciliation writes the complete
-eight-pack boolean map. When no project packs remain, it removes the group while
-preserving unrelated shared keys. User-only assets are ignored.
+`tools.*` records **declared intent per scope**, not effective project-plus-user
+capability. Project intent lives in `.oat/config.json`; user intent lives in the
+same key shape under `~/.oat/config.json`. `oat tools install`, `oat tools
+update`, `oat tools remove`, and `oat tools migrate` write only the scope they
+changed.
 
-Use `oat config get tools.<pack>` to inspect project installation state.
+Intent is true-or-absent. Installing writes `true`; removing deletes the key.
+OAT never writes `false`, never infers one pack's key from another's, and never
+writes a full eight-pack map. A legacy `false` left over from an older release
+is diagnosed as a `legacy-false-conflict` rather than honored as an opt-out.
+
+Use `oat config get tools.<pack>` to inspect declared intent.
 `oat config set tools.<pack> ...` remains available as a shared override, but a
-later lifecycle reconciliation may replace the manual value with the canonical
-project snapshot.
+later lifecycle mutation for that scope may replace the manual value.
+
+Declared intent is not the same as installed inventory. Use `oat tools list`,
+`oat tools info <name>`, `oat status`, or `oat doctor` to see what is actually
+present, what is missing, and which scoped command repairs it.
 
 Use `oat tools has <pack>` for current effective availability. It checks project
 and user scopes by default; add `--scope project` or `--scope user` to isolate a
-scope, and use the global `--json` flag for the `{ pack, available, scopes }`
-result:
+scope. Availability is complete-only — a partially installed pack reports
+`false`. The global `--json` flag returns `pack`, `available`, `scopes`,
+`unavailableScopes`, per-scope `completeness`, and the `missing` managed assets:
 
 ```bash
 oat tools has project-management
@@ -121,6 +130,20 @@ oat tools has project-management --scope user
 oat --json tools has project-management
 ```
 
+Repository PJM adoption example:
+
+```bash
+oat config get pjm.initialized
+oat pjm doctor --json
+```
+
+`pjm.initialized` is written by `oat pjm init` after the canonical scaffold is
+verified. It is the authoritative repository adoption marker: PJM, backlog, and
+decision mutations fail closed without it, and `oat doctor` keys its `pjm:*`
+checks on adoption state rather than on `tools.project-management`. See
+[Install vs. initialize](tool-packs.md#install-vs-initialize) for the full state
+table and template precedence.
+
 ### Explainer configuration
 
 The `oat-explainer-kit` adapter owns two typed config groups. Build and publish