@open-agent-toolkit/cli 0.2.65 → 0.2.67

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.65"
+  "oatVersion": "0.2.67"
 }

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

@@ -15,6 +15,7 @@ For the deep file-by-file reference, see:
 - [File Locations](../reference/file-locations.md)
 - [`.oat` Directory Structure](../reference/oat-directory-structure.md)
 - [Sync Config (`.oat/sync/config.json`)](../provider-sync/config.md)
+- [Remote Project Management](remote-project-management.md)
 
 ## The five config surfaces
 
@@ -51,7 +52,7 @@ What each command is for:
 - `oat config list` shows the currently resolved command-surface values for shared and repo-local keys.
 - `oat config get <key>` reads one supported key value.
 - `oat config set <key> <value>` updates supported shared or repo-local keys.
-- `oat config unset <key>` removes a supported key from one surface, using the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. The resolved value then falls back to the next surface down, or to the built-in default. A key the surface does not hold exits 0 as already-unset (`--json` adds a `removed` boolean to tell the two apart). Unknown keys, lifecycle state, `tools.*` pack intent, the `workflow.dispatchCeiling` aggregate read views, and environment-shadowed keys with nothing stored are refused with exit 1 — see [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags).
+- `oat config unset <key>` removes a supported key from one surface, using the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. The resolved value then falls back to the next surface down, or to the built-in default. A key the surface does not hold exits 0 as already-unset (`--json` adds a `removed` boolean to tell the two apart). Unknown keys, lifecycle state, `tools.*` pack intent, aggregate read views, read-only remote-policy structure, and environment-shadowed keys with nothing stored are refused with exit 1 — see [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags).
 - `oat config describe` shows the supported config catalog across shared repo, repo-local, user, and sync/provider surfaces.
 - `oat config describe <key>` shows file, scope, default, mutability, owning command, and description for one key.
 
@@ -92,7 +93,7 @@ Common keys in `.oat/config.json`:
 - `git.defaultBranch` — base branch fallback for PR workflows
 - `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership
 - `documentation.excludes` — a JSON array of globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. `oat config set` takes the list as one comma-separated value (`"a/**,b.md"`) and stores it as an array; repeated `--exclude` flags extend it, and an empty value clears the key
-- `documentation.instructionPointerExcludes` — a JSON array of repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip by default (see [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees)). `oat config set` takes the list as one comma-separated value (`"vendor/generated,apps/oat-docs/docs"`) and stores it as an array of repository-relative POSIX paths, trimmed and de-duplicated; an empty value clears the key, and `oat config unset documentation.instructionPointerExcludes` removes it. An entry that could never exclude anything — an absolute path, or one escaping the repository with `..` — is rejected with exit code `1` rather than stored. A structurally malformed value already on disk (a non-array, or an empty or non-string entry) is rejected with exit code `2` and a repair message, and `oat config set` can still replace it. Entries that are well formed but cannot exclude anything — among them absolute paths, paths escaping the repository, paths that match no directory (matching is case-sensitive), and the unexcludable `.oat/repo` carve-in root — never abort the command; they are reported as warnings and are not counted as protection. Warnings go to stderr in human mode and to the `exclusionWarnings` field under `--json`
+- `documentation.instructionPointerExcludes` — a JSON array of repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip by default (see [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees)). `oat config set` takes the list as one comma-separated value (`"vendor/generated,apps/oat-docs/docs"`) and stores it as an array of repository-relative POSIX paths, trimmed and de-duplicated; an empty value clears the key, and `oat config unset documentation.instructionPointerExcludes` removes it. An entry that could never exclude anything — an absolute path, or one escaping the repository with `..` — is rejected with exit code `1` rather than stored. A structurally malformed value already on disk (a non-array, or an empty or non-string entry) is rejected with exit code `2` and a repair message, and `oat config set` can still replace it. Entries that are well formed but cannot exclude anything — among them absolute paths, paths escaping the repository, paths that match no directory (matching is case-sensitive, and the warning names the on-disk spelling when the path differs only in case), paths that resolve elsewhere through a symlink (the warning names the resolved target instead of blaming case-sensitivity), and the unexcludable `.oat/repo` carve-in root — never abort the command; they are reported as warnings and are not counted as protection. Warnings go to stderr in human mode and to the `exclusionWarnings` field under `--json`
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
 - `archive.s3Uri` — base S3 archive prefix
 - `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
@@ -101,10 +102,27 @@ Common keys in `.oat/config.json`:
 - `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-scope intent for a bundled tool pack (`true` or absent)
+- `pjm.remote.storage.state` — `local` by default; `shared` requires an
+  explicit preview and fresh approval and is unavailable to local projects
+- `pjm.remote.policy.description` — `none`, `managed-section`, or `replace`;
+  the default is `none`
+- `pjm.remote.policy.authority.*` — repository defaults and operation-specific
+  authority for remote creates, field updates, transitions, annotations,
+  deletion, relink, detach, and recreate; the default is `read-only`
+- `pjm.remote.policy.providers.<provider>.*` — optional GitHub, Linear, or Jira
+  replacement policy; its operation override or default may broaden the
+  repository result before later restrictions apply
 - `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
 
+Remote authority resolves the repository operation override, repository
+default, or built-in read-only fallback first. Matching provider policy replaces
+that result. Binding defaults and operation restrictions then clamp authority,
+and purpose field grants intersect to narrow outbound fields. No configured
+layer bypasses hard approval floors or current caller-owned authority evidence;
+missing, stale, or mismatched evidence fails closed.
+
 Tool-pack intent example:
 
 ```bash
@@ -256,6 +274,19 @@ packaged `assets/` directory next to the installed CLI. Setting a non-empty
   unset the override, never to rebuild or reinstall the CLI; a packaged-bundle
   failure keeps the rebuild/reinstall guidance. A directory that exists but
   cannot be read reports the underlying error code.
+- The published npm tarball is held to the same seven-directory shape. The
+  CLI's public-package contract names a concrete file under each of the seven
+  directories, and release validation requires each one in the build workspace
+  and again in the packed tarball. The tarball check is the stronger of the two,
+  because a path can exist in the workspace and still never reach the tarball —
+  an empty directory that `npm pack` drops, or a `files`/symlink exclusion. So a
+  published package cannot ship a bundle whose top-level shape would fail
+  `validateBundleStructure`. That is a narrower promise than the exit-2 list
+  above: release validation does not check bundle metadata beyond its presence,
+  so a malformed or version-mismatched `bundle-metadata.json` is not covered.
+  The regression evidence is the negative pack control in
+  `packages/cli/src/release/public-package-contract.test.ts`:
+  `fails release validation when a required bundle directory is empty in the tarball`.
 - Produce a matching bundle with `bash packages/cli/scripts/bundle-assets.sh`
   while `OAT_ASSETS_DIR` points at the target directory (the script already
   honors the variable as its destination).

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

@@ -14,6 +14,7 @@ Use this section when you want bootstrap guidance, tool-pack lifecycle details,
 - [CLI Bootstrap](bootstrap.md) - Foundational `oat init` guidance outside provider-sync-specific onboarding.
 - [Tool Packs and Installed Assets](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
 - [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
+- [Remote Project Management](remote-project-management.md) - Provider-neutral remote bindings, policy, previews, approvals, storage, and recovery.
 - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
 - [Project Log](project-log.md) - Append-only project observations, synthesis, inspection, and durable roll-up.
 - [Backlog Lifecycle](backlog-lifecycle.md) - Backlog item states, atomic close-out with `oat backlog archive`, and lifecycle drift detection in `oat pjm doctor`.
@@ -51,6 +52,7 @@ Use CLI Utilities when:
 - Use [CLI Bootstrap](bootstrap.md) when you are starting with `oat init`.
 - Go to [Tool Packs](tool-packs.md) when you are managing bundled OAT packs and installed assets.
 - Read [Configuration](configuration.md) for config semantics, or [Config and Local State](config-and-local-state.md) for inspection and diagnostic command groups.
+- Read [Remote Project Management](remote-project-management.md) before binding local planning records to GitHub, Linear, or Jira.
 - Use [Workflow Gates](workflow-gates.md) when you want a skill to run a configured final command before it is considered done.
 
 ## Common Tasks
@@ -66,5 +68,6 @@ Use CLI Utilities when:
 - [CLI Bootstrap](bootstrap.md) - Foundational `oat init` guidance outside provider-sync-specific onboarding.
 - [Tool Packs](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
 - [Configuration](configuration.md) - OAT configuration guidance.
+- [Remote Project Management](remote-project-management.md) - Safely operate explicit remote planning-record bindings.
 - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
 - [Workflow Gates](workflow-gates.md) - Per-skill final commands and cross-runtime review dispatch.

package/assets/docs/cli-utilities/project-log.md

@@ -77,8 +77,10 @@ Two optional flags let an interrupted append be replayed safely:
 
 - `--idempotency-key <key>` — skip the append when an existing entry body
   already carries `key`, reporting `already-appended` instead of writing a
-  duplicate. The key must appear in `--body`, since that is how a replay
-  recognizes the entry it already wrote.
+  duplicate. The key must appear in `--body` as its own whitespace-delimited
+  word, since that is how a replay recognizes the entry it already wrote; a key
+  glued to varying text such as a timestamp never matches its earlier self.
+  Deduplication does not require `--commit`.
 - `--commit` — stage and commit the log after appending, retrying a bounded
   three attempts when the failure is a transient `.git/index.lock`.
 
@@ -101,6 +103,14 @@ instead.
 
 Run `oat project log append --help` for the complete entry contract.
 
+Bodies may use line feeds or CRLF line endings. A CRLF body is accepted and
+stored normalized to line feeds, and the result then carries
+`normalizedLineEndings: true`, so the bytes on disk are known to differ from the
+bytes passed. A lone carriage return, U+2028, or U+2029 anywhere in a body — including
+at its very start or end — is refused, because those are the terminators the
+log's readers do not all agree about. Structural entries take one line and
+accept no line terminator at all.
+
 ## Automatic workflow integration
 
 When project logging is enabled, OAT lifecycle surfaces append structural
@@ -149,6 +159,25 @@ oat project log check --project .oat/projects/shared/example --json
 entry counts by class, type, and scope; the last entry date; and invalid
 hand-written headings. It reads only `project-log.md`.
 
+It also reports whether the log carries a completion seal:
+
+- `sealed`: `true` once the log holds a structural entry whose producer is
+  `oat-project-complete` and whose ref is `seal`. Both halves are required — a
+  `seal` ref from another producer is an ordinary entry.
+- `seal`: `null` when unsealed, otherwise the first seal's `heading` and
+  `date`, whether it is `keyed`, and the `count` of seal entries. A `count`
+  above one is a log sealed twice before the seal append became idempotent.
+
+`status` keeps its `ok` / `absent` / `synthesis_pending` values on a sealed log;
+sealing is reported alongside the status, not as a status value. The one
+additional status is `ambiguous`: a `##` heading, or a dated `###` entry
+heading, starts a line after a lone carriage return, U+2028, or U+2029 rather
+than a line feed, so the log's structure can be read two ways; or a seal is
+physically present outside the parseable `## Entries` region. `check` then
+exits 1 and reports an `ambiguity` reason instead of a clean verdict, every
+writing command (`append`, `synthesize`, `rollup`) refuses the same file, and
+the lifecycle skills stop rather than treat the log as empty.
+
 Use `--require-synthesis` to exit with status 1 while synthesis is pending:
 
 ```bash
@@ -156,7 +185,8 @@ oat project log check --require-synthesis
 ```
 
 Without that flag, normal `absent`, `ok`, and `synthesis_pending` results exit
-successfully so lifecycle skills can decide whether to warn or enforce.
+successfully so lifecycle skills can decide whether to warn or enforce;
+`ambiguous` always exits 1.
 
 ## Complete the synthesis
 
@@ -201,15 +231,44 @@ deduplicate by date and area. The command is idempotent.
 
 The structured result contains:
 
-- `status`: `ok` or `failed`
+- `status`: `ok`, `failed`, or `ambiguous`
 - `summarySection`: `written` or `updated`
 - `ledgerOutcome`: `appended`, `deduplicated`, `skipped_permitted`, or `failed`
 - `entriesRolledUp`: number of log entries written to the summary section
 
+An `ambiguous` result carries only `status` and an `ambiguity` reason, and exits
+1: the log's structure has two readings, so no count would mean anything and
+neither `summary.md` nor the ledger is written. The other fields are absent
+rather than zeroed, because `entriesRolledUp: 0` for an unreadable log is
+indistinguishable from the same result for an empty one.
+
 `skipped_permitted` means the default repository reference layer is absent and
 no ledger path was explicitly configured; `status` remains `ok`. An explicitly
 configured ledger write failure returns `status: "failed"`. Completion must not
 seal or archive a project with entries until roll-up reports `status: "ok"`.
 
+## The completion seal
+
+The seal is the last entry a project log may ever receive, and `append`
+enforces that rather than leaving it to convention:
+
+- Replaying the seal reports `already-appended` and leaves exactly one seal
+  entry. This holds for a seal carrying the completion skill's
+  `oat-seal:<project>` key and for an unkeyed seal written before that
+  convention, which is recognized by its heading instead.
+- Every append carrying **new** content is refused with `status: "sealed"` and a
+  non-zero exit, naming the seal that closed the log.
+- A replay that `--idempotency-key` recognizes as its own earlier entry is the
+  one exception: it reports `already-appended` and exits 0 even on a sealed log.
+  Nothing is appended — the entry it finds necessarily predates the seal — so
+  the seal stays the final entry. This is what keeps a gate
+  partial-finalization receipt replayable after the project is completed. The
+  key matches a whole word in an existing entry body, so an unrelated append
+  whose key happens to occur in some earlier entry is reported the same way
+  and likewise writes nothing.
+
+A resumed completion therefore reads `sealed` from `check` and skips the
+roll-up and the seal instead of duplicating them.
+
 `rollup` requires an existing `summary.md`; summary authoring remains the
 responsibility of the project summary workflow.

package/assets/docs/cli-utilities/remote-project-management.md

@@ -0,0 +1,191 @@
+---
+title: Remote Project Management
+description: Safely bind OAT planning records to GitHub, Linear, or Jira through provider-neutral host capabilities.
+---
+
+# Remote Project Management
+
+Remote project management connects an OAT backlog item or project to a remote
+GitHub, Linear, or Jira record. OAT owns policy, previews, approvals, durable
+operation state, and authoritative read-back verification. The host agent owns
+live execution capability discovery.
+
+Remote management is deliberately explicit. It does not turn every plan task
+into a remote issue, run background synchronization, or treat a provider result
+as proof of success.
+
+## Prerequisite
+
+Confirm that file-backed project management is adopted before using a remote
+command:
+
+```bash
+oat pjm doctor --json
+```
+
+Continue only when `adoption.state` is `declared` or `inferred-legacy`. Run
+`oat pjm init` first when adoption is absent or only partially initialized.
+
+## Lifecycle operations
+
+The command family is `oat pjm remote`:
+
+```bash
+oat pjm remote intake github:example/repository#123 --to-backlog BL-123 --capability-evidence-stdin --json
+oat pjm remote publish --binding rb_example --capability-evidence-stdin --json
+oat pjm remote refresh --binding rb_example --capability-evidence-stdin --json
+oat pjm remote reconcile --binding rb_example --capability-evidence-stdin --json
+oat pjm remote closeout --project .oat/projects/shared/example --capability-evidence-stdin --json
+oat pjm remote discussion --binding rb_example --limit 20 --capability-evidence-stdin --json
+oat pjm remote resolve relink --binding rb_example github:example/repository#456 --capability-evidence-stdin --json
+oat pjm remote resolve detach --binding rb_example --json
+oat pjm remote resolve recreate --binding rb_example --capability-evidence-stdin --json
+oat pjm remote doctor --json
+oat pjm remote migrate --check --json
+```
+
+Before each provider-contacting example, the host discovers live capability and
+supplies only its bounded provider-neutral evidence on standard input. Mutation
+commands also require the current caller-owned authority evidence requested by
+their live help.
+
+- `intake` reads one remote record into a selected local backlog target and
+  creates the binding.
+- `publish` creates or updates one explicitly selected binding.
+- `refresh` updates retained snapshots without writing remotely.
+- `reconcile` classifies local, remote, and baseline changes before proposing
+  any write.
+- `closeout` prepares a reviewed batch while preserving independent per-binding
+  outcomes.
+- `discussion` returns one bounded, sanitized page as non-persisted evidence.
+- `resolve relink`, `detach`, and `recreate` handle anomalous bindings without
+  discarding identity history or retrying an uncertain create blindly.
+- `doctor` and `migrate` diagnose or repair local records without contacting a
+  provider.
+
+Use `--help` on the live command for current options. JSON output uses one
+versioned envelope and may return a nonzero shell exit for a safely persisted
+`pending`, `needs-review`, `partial`, `uncertain`, or `blocked` outcome.
+
+## Repository-owned policy
+
+Remote policy lives only in the shared repository config at `.oat/config.json`.
+The safe defaults are local operational state, no description publication, and
+read-only authority:
+
+```json
+{
+  "pjm": {
+    "remote": {
+      "schemaVersion": 1,
+      "storage": { "state": "local" },
+      "policy": {
+        "description": "none",
+        "authority": { "default": "read-only" }
+      }
+    }
+  }
+}
+```
+
+Use the config command instead of editing nested values by hand:
+
+```bash
+oat config set pjm.remote.policy.description managed-section --shared
+oat config set pjm.remote.policy.authority.operations.update-fields user-approved --shared
+oat config set pjm.remote.policy.providers.github.authority.operations.create user-approved --shared
+```
+
+Description modes are `none`, `managed-section`, and `replace`. Authority modes
+are `read-only`, `user-approved`, `user-authorized`, and `autonomous`.
+For each operation, OAT resolves the repository operation override, then its
+repository default, then the built-in read-only fallback. A matching provider
+operation override or provider default replaces that repository result and may
+broaden it. Binding defaults and operation restrictions then clamp authority,
+while purpose field grants intersect to narrow the outbound fields. Provider
+configuration never bypasses hard approval floors or the requirement for
+current caller-owned authority evidence; missing, stale, or mismatched evidence
+fails closed. Autonomous configuration is not a background grant.
+
+## Live host capability boundary
+
+At operation time, the host agent inspects currently granted MCP or connector
+descriptions for the requested semantic operation and exact account, workspace,
+site, or repository context. If no capable connector is available, it may
+inspect the live help of an already configured provider CLI before the first
+provider-contacting command.
+
+OAT does not store provider tool names, native schemas, captured catalogs,
+executable names, flags, or CLI dialects. The host returns only bounded,
+sanitized capability evidence through `--capability-evidence-stdin`. It must not
+install tools, request credential values, or switch execution surfaces after an
+attempt begins. The CLI may then emit one provider-neutral `externalAction`.
+The host executes that exact action at most once and returns one bounded
+observation with `oat pjm remote operation continue`.
+
+## Content and outbound safety
+
+Inbound provider text is retained only through an allowlist of core fields and
+adapter-approved extensions. If a retained text field triggers a conservative
+sensitive-content signal, OAT suppresses that whole field and marks the
+snapshot incomplete. This is a bounded field-safety rule, not general DLP or
+credential-value parsing.
+
+Every remote create or update consumes only an explicit normalized projection.
+The universal provider-neutral pre-write gate evaluates that projection before
+preview, approval, action, and authoritative read-back. It never scans the
+repository, worktree, Git history, or arbitrary files for secrets. Missing,
+stale, failed, or blocked safety evidence prevents execution.
+
+## Previews, approval floors, and uncertainty
+
+Mutation-capable commands persist and return a preview before execution. The
+preview digest binds the target, normalized fields, remote revision,
+capability, safety result, and effective policy. If any load-bearing input
+changes, the approval is stale.
+
+Fresh approval is always required for complete description replacement,
+relink, detach, recreate, destructive operations, and promotion to shared
+operational storage. `user-approved` authority also requires applying the exact
+persisted preview. Higher configured authority cannot bypass those floors.
+
+The host submits a bounded observation with `oat pjm remote operation continue`.
+Only an OAT `ok` envelope after authoritative read-back means success. A
+connector response, process exit, or visible remote change is evidence rather
+than a verdict. If a create or update is uncertain, do not retry it blindly;
+use the recovery guidance in the envelope so OAT can search, relink, recreate,
+or reconcile without producing duplicates.
+
+## Storage and worktrees
+
+Portable binding metadata follows its backlog or project owner. Shared backlog
+metadata lives under `.oat/repo/pjm/remote/bindings`; project metadata lives
+under that project's `remote/bindings` directory. Local projects keep their
+portable metadata in the local operational store.
+
+Operational snapshots, journals, batches, and receipts default to a
+repository-fingerprinted directory under the Git common directory:
+`.git/oat/pjm-remote/<repository-fingerprint>/`. All linked worktrees for one
+repository therefore share the same local operational state, while another
+clone gets its own store.
+
+Shared operational storage is opt-in and may expose remote planning content to
+everyone with repository access. It requires a persisted preview and fresh
+approval, and it is rejected for local projects. Preview the exact proposed
+paths through `oat pjm remote storage shared --help` before applying them.
+
+## Offline behavior
+
+OAT can inspect portable bindings, the bounded local snapshot, journals,
+receipts, and pending recovery instructions while offline. `remote doctor` and
+`migrate` are local-only. Provider refresh, publication, reconciliation writes,
+and authoritative verification remain pending or blocked until matching live
+capability evidence is available; offline state never fabricates remote
+freshness or success.
+
+## Related references
+
+- [Configuration](configuration.md)
+- [CLI Reference](../reference/cli-reference.md)
+- [File Locations](../reference/file-locations.md)
+- [Troubleshooting](../reference/troubleshooting.md)

package/assets/docs/contributing/code.md

@@ -56,8 +56,8 @@ pnpm build:docs               # builds docs site and its dependencies
 ```
 
 `pnpm test` is composite: it runs the workspace vitest suites, then
-`test:smoke` (`tools/smoke`), `test:skills` (`.agents/skills/*/tests`), and
-the named-file `test:release` set. Steps 5 and 6 are the version-lockstep
+`test:smoke` (`tools/smoke`), `test:skills` (`.agents/skills/*/tests`), the
+named-file `test:release` set, and last `test:scripts` (`scripts/worktree`). Steps 5 and 6 are the version-lockstep
 gates; they are in the local list because they previously ran only in CI and
 version-bump drift twice reached review with no local gate to surface it.
 
@@ -73,8 +73,12 @@ checkout with neither `origin/main` nor `main` skips the whole gate (CI uses
 `fetch-depth: 0`). Test files under `packages/cli/src/` count as publishable
 changes for this gate.
 
-CI runs neither `pnpm lint` nor `pnpm format` — run both whenever a change
-touches `tools/smoke` or `.agents/skills`, since nothing else covers them.
+CI runs neither `pnpm lint` nor `pnpm format`. `pnpm check` now covers the
+formatting of `.agents/skills/**`, `apps/oat-docs/docs`, and `tools/smoke`
+through `format:root`, but `pnpm lint`'s root `oxlint` pass over `tools/smoke`
+and `.agents/skills`, and `packages/control-plane`'s `format` (it defines no
+`check` script), still run in no CI gate — run both whenever a change touches
+those paths.
 For narrower changes, use package-specific checks when possible, but do not
 merge without passing the relevant workspace gates.
 

package/assets/docs/contributing/skills.md

@@ -203,15 +203,19 @@ resolution. `resolveSkillVersion` in
 `packages/cli/src/commands/shared/frontmatter.ts` owns that order, so the
 runtime helper and the validators cannot disagree.
 
-The top-level `version` field remains supported as a deprecated alias. Every
-bundled skill now declares `metadata.version` and carries no top-level
-`version`, so `pnpm oat:validate-skills` reports no alias warnings on the
-bundled tree. The alias is retained for third-party skills installed from
-packs, which may still carry it; it retires on the schedule recorded in
-`DR-260908-bundled-skills-declare` — the warning becomes an error in the first
-release after 0.2.65 that changes the validator, and the resolver's top-level
-read is removed one release after that error has produced no findings on the
-bundled tree.
+The top-level `version` field remains supported as a deprecated alias, and a
+skill that declares it is now reported as an **error**. Every bundled skill
+declares `metadata.version` and carries no top-level `version`, so
+`pnpm oat:validate-skills` reports no alias findings on the bundled tree. The
+alias is still read for third-party skills installed from packs, which may
+carry it; it retires on the schedule recorded in
+`DR-260908-bundled-skills-declare`. Step 1 of that schedule — promoting the
+alias finding from a warning to an error — ships in the first release after
+0.2.65 that changes the validator. Step 2 removes the resolver's top-level read
+one release after that error has produced no findings on the bundled tree; it
+is tracked by `BL-260908-remove-the-top-level-skill` and must account for the
+canonical agent roles, which the bump gate now enforces while they still
+declare the top-level field.
 
 A skill that carries both fields with different values is a conflict. The
 resolver reports the `metadata.version` value together with the conflict, and
@@ -220,7 +224,7 @@ than silently picking one, and canonical role resolution treats the identity as
 invalid. The runtime version readers still return the `metadata.version` value,
 so an installed-versus-bundled comparison keeps working while the conflict is
 being fixed. Carrying both with the _same_ value resolves without a conflict and
-without an alias warning, because `metadata.version` wins. A bundled skill must
+without an alias finding, because `metadata.version` wins. A bundled skill must
 still carry `metadata.version` alone: the corpus sweep in
 `packages/cli/src/validation/skills.test.ts` fails on any column-0 `version:`
 line under `.agents/skills`, which is the only check that catches the
@@ -228,16 +232,24 @@ same-value case.
 
 ### The version is gated
 
-Changing any canonical skill's `SKILL.md` requires bumping its frontmatter
-version in the same PR — one bump per changed skill in the final PR diff,
-even if the skill was edited multiple times on the branch. The gate reads the
-resolved version, so it enforces the bump whether the skill declares
+Changing any bundled file of a canonical skill — anything under
+`.agents/skills/<name>/` except `tests/`, because `tests/` is the one subtree
+the bundle strips — requires bumping that skill's `metadata.version` in the
+same PR, one bump per changed skill in the final PR diff, even if the skill was
+edited multiple times on the branch. A change to a skill's `scripts/` or
+`references/` therefore needs the bump just as an edit to `SKILL.md` does: both
+ship to every `oat tools install` consumer. Changing a canonical agent role
+under `.agents/agents/*.md` requires bumping that file's top-level `version:`;
+agent roles deliberately keep the top-level field, so the gate accepts either
+declaration shape and never demands `metadata.version` of them. The gate reads
+the resolved version, so it enforces the bump whether the file declares
 `metadata.version` or the top-level alias. The rule is enforced by
 `pnpm run check:skill-bumps`, which runs locally (root `AGENTS.md` Definition
 of Done) and in CI; a changed skill whose version matches `origin/main` fails
-the gate. The deprecation warning above is deliberately not part of that gate:
-`check:skill-bumps` fails on any finding it receives, so an alias warning
-routed through it would fail every changed skill that still carried one.
+the gate. The alias finding above is deliberately not part of that gate:
+`check:skill-bumps` fails on any finding it receives regardless of severity, so
+an alias finding routed through it would fail every changed skill that still
+carried one.
 
 ## Practical Authoring Flow
 

package/assets/docs/docs-tooling/commands.md

@@ -132,11 +132,13 @@ Key behavior:
 - treats explicitly supplied `--docs-dir` / `--output` paths as overrides resolved from the current directory
 - fails with exit code `2` before generating or writing anything when an omitted path has no non-empty `documentation.root` to resolve against, or when the configured root is not a directory
 - refuses unsafe output targets with exit code `1` before generation, for derived and explicit paths alike, comparing symlink-resolved paths: inside the docs directory it indexes, equal to `documentation.config`, or ending in `.yml` / `.yaml` in any case. A derived output whose existing file lacks the `AUTOGENERATED` header is refused too; naming that path with `--output` overwrites it explicitly. A refused target is an actionable flag error (`1`); unusable path configuration is a separate condition and exits `2`, so scripts can branch on the two
+- refuses a symlink chain that exceeds its own 32-hop cap, naming the path you supplied or the CLI derived rather than an intermediate link, and addressing the flag that owns it: an unusable **output** chain names `--output` and exits `1`; an unusable **docs directory** chain names `--docs-dir` and, when the directory was derived from `documentation.root` rather than passed explicitly, also names the `oat config set documentation.root <path>` repair and exits `2` as unusable path configuration. That cap governs the dangling links the command walks itself; a chain the operating system refuses first surfaces as its own `ELOOP` error with exit `1`, which is what a too-deep chain reports on a platform whose own limit is 32 or lower
 - writes configuration only for the Fumadocs manifest transition — recording the manifest it just wrote inside `documentation.root` in `documentation.index`, when `documentation.tooling` is `fumadocs` or the config declares neither `tooling` nor `config`. MkDocs configurations are never written, and `documentation.root` and `documentation.config` are never modified
 - prepends an `AUTOGENERATED` warning comment to the output and rewrites the file on every run; do not hand-edit the generated `index.md`
 - should be freshness-checked against authored `docs/**/index.md` `## Contents` maps before treating it as navigation evidence
 - sorting: `index.md` first, then directories before files, then lexical
-- reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`
+- reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`, alongside `excludes` — the effective exclusion list, `documentation.excludes` merged with the `--exclude` flags exactly as it was handed to the generator
+- says where to look when a manifest is empty rather than reporting a bare `0 entries`: which exclusion patterns were active, or that the docs directory held no indexable pages. The wording is observational — the command reports indexed entries, not pattern matches, so it names the exclusions without asserting they are the cause. An empty manifest is a report, not a failure — the file is still written, so a stale index is never left behind, and the command still exits `0`
 - omits pages matching the exclusion list. Nothing is excluded by default; once listed, non-page Markdown such as `CLAUDE.md` or `AGENTS.md` stops reaching the manifest. Patterns come from `documentation.excludes` in `.oat/config.json` and from repeated `--exclude` flags, and the flags **extend** the configured list rather than replacing it. A directory left empty by exclusion emits no heading, and an empty list produces byte-identical output to no exclusions at all
 
 Supported flags:

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -95,8 +95,8 @@ the manifest.
 
 - `missing-additive` — active, supported, no manifest entry, nothing at the expected path: the only true projection gap
 - `removed` — a manifest entry exists but the provider file is gone
-- `modified` — a manifest entry exists and the view no longer agrees with what the last sync recorded, or its version has fallen behind canonical. A `copy` view also reaches this class through the known limitation below, where the difference may be nothing but the generated banner
-- `in-sync` — a symlinked, collection-aliased, or natively read view _is_ the canonical file; a `copy` view matches the content recorded at its last sync
+- `modified` — a manifest entry exists and the view no longer agrees with what the last sync recorded, or its version has fallen behind canonical
+- `in-sync` — a symlinked, collection-aliased, or natively read view _is_ the canonical file; a `copy` view matches the content recorded at its last sync. A managed directory copy is compared with its OAT-managed banner and its `.oat-generated` sentinel excluded, so a freshly synced copy reads `in_sync` rather than drifted (owned by `skill-view-convergence.integration.test.ts`, "converges a copy-strategy skill directory")
 - `untracked` — something exists at the expected path that no manifest entry tracks; stray detection skips provider entries whose name matches a canonical entry, so `oat status` does not report it as a stray and reports the untracked projection as `missing` instead
 - `unverified` — the view's state is unknown: either a manifest entry arrived with no drift observation, or reading that one view failed and the row carries the redacted reason
 - `inactive`, `unsupported`, `excluded` — no projection is expected in this scope, so none of them is reported as missing
@@ -173,22 +173,6 @@ declared values and says the comparison was skipped, so the ambiguity is
 visible rather than silently resolved. When the resolver's answer happens to
 agree with canonical, nothing is withheld and the detail says so instead.
 
-### Known limitation: copy-strategy skill views
-
-A `copy` skill view is reported `modified` immediately after a successful sync,
-and stays that way. The engine writes an OAT-managed banner into the copied
-`SKILL.md` and an `.oat-generated` sentinel beside it, and neither is accounted
-for in the manifest hash, so `oat status` reports `drifted:modified` and every
-later `oat sync --dry-run` plans another `update_copy`. Because no sync clears
-that state, `oat tools info` prints no repair line when a `modified` copy's
-version still matches canonical.
-
-That suppression is a conservative heuristic rather than a proof: equal versions
-do not establish equal bodies, so an edit to the canonical source or to the copy
-that kept the version reaches the same branch, and a sync _would_ repair that
-one. The class detail says so and names the concrete scope command to run if you
-know either side was edited. Tracked as `BL-260908-make-copy-strategy-skill`.
-
 ## Stray adoption
 
 `oat init` and `oat status` can offer adoption of unmanaged provider entries into canonical `.agents`.

package/assets/docs/reference/cli-reference.md

@@ -14,6 +14,7 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 - [CLI Bootstrap](../cli-utilities/bootstrap.md) - Bootstrap a repo with `oat init`, guided setup, and initial provider adoption.
 - [Tool Packs](../cli-utilities/tool-packs.md) - Install, update, inspect, migrate, and remove bundled OAT skills and agents at project or user scope.
 - [Config and Local State](../cli-utilities/config-and-local-state.md) - Config, backlog, local paths, diagnostics, and related utility commands.
+- [Remote Project Management](../cli-utilities/remote-project-management.md) - Explicit remote bindings, policy, host handoffs, and recovery.
 - [Workflow Gates](../cli-utilities/workflow-gates.md) - Per-skill final commands, review gates, and cross-runtime prompt dispatch.
 - [Docs Tooling Commands](../docs-tooling/commands.md) - Docs app scaffolding, migration, index generation, and nav sync.
 - [Provider Sync](../provider-sync/index.md) - Sync behavior, provider capabilities, config, and drift management.
@@ -43,6 +44,7 @@ The first practical expansion path is to keep improving the existing owners: [Do
 | `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                                                                                                        | [CLI Bootstrap](../cli-utilities/bootstrap.md)                                     |
 | `oat tools ...`                                 | Install, inspect, update, remove, and migrate bundled OAT tool packs and assets across project and user scope.                                                                                                             | [Tool Packs](../cli-utilities/tool-packs.md)                                       |
 | `oat pjm ...`                                   | Adopt PJM for a repository and record it (`init`), run read-only adoption and reference diagnostics (`doctor`), and migrate legacy layouts to `pjm/` + `reference/` (`migrate`). Adoption is separate from pack placement. | [Install vs. initialize](../cli-utilities/tool-packs.md#install-vs-initialize)     |
+| `oat pjm remote ...`                            | Intake, publish, refresh, reconcile, close out, inspect discussion, resolve anomalies, diagnose, migrate, and continue durable host actions for explicit remote bindings.                                                  | [Remote Project Management](../cli-utilities/remote-project-management.md)         |
 | `oat decision ...`                              | Create, index, and migrate file-per-record repo decisions under `reference/decisions/` (`init`, `new`, `regenerate-index`, `migrate`).                                                                                     | [Config and Local State](../cli-utilities/config-and-local-state.md#oat-decision-) |
 | `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                                                                                                          | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
 | `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                                                                                       | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
@@ -134,6 +136,12 @@ Notable commands introduced in the current CLI surface:
   never converted into a `recorded-absent` row or pull guidance.
 - `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).
 - `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.
+- `oat pjm remote ... --json` - operate one explicit provider-neutral binding.
+  The family includes `intake`, `publish`, `refresh`, `reconcile`, `closeout`,
+  `discussion`, `resolve`, `doctor`, `migrate`, `storage`, and
+  `operation continue`. An `ok` envelope exits 0, a system `failed` envelope exits 2, and
+  every safely persisted nonterminal or blocked status exits 1. A `pending`
+  envelope with `externalAction` is a durable host handoff, not remote success.
 - `oat config dump --json` - merged config with source attribution
 - `oat project status --json` - full parsed state for the active tracked project. **Stable contract for skills:** the JSON output is a typed read interface for OAT skills; the field set consumed by migrated skills is locked by `MIGRATED_FIELDS` in `packages/cli/src/commands/project/status.test.ts`. Removing or renaming any of `project.{name, path, phase, phaseStatus, workflowMode, docsUpdated, lastCommit, prStatus, prUrl}` is a breaking change and will fail the contract test.
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
@@ -171,12 +179,15 @@ Per-key restrictions apply identically to `set` and `unset`: structural keys can
 
 `oat config unset <key>` removes the key from the selected surface and prunes any parent object it empties, so the resolved value falls back through the remaining surfaces to the built-in default. Removing a key the surface does not hold is not an error: it reports an already-unset outcome and exits 0. With `--json` the envelope adds a `removed` boolean, which is the machine-readable way to tell a real removal from an already-unset no-op, since both exit 0. A stored value that fails validation is still removed, matching `oat config set`, which repairs the same file.
 
-`unset` refuses five classes of key, each with exit code 1:
+Remote settings under `pjm.remote.*` remain shared-only. Removing a mutable leaf preserves sibling settings and the required empty `policy` object, if necessary, so the remaining remote configuration stays readable. Explicit defaults are removed from disk rather than silently written back by normalization; effective values still use fail-closed defaults. Remote policy must pass strict validation before removal.
+
+`unset` refuses six classes of key, each with exit code 1:
 
 - **Unknown keys**, including keys OAT reads but does not expose in the `oat config` catalog (`documentation.index`). These are not removable by any `oat config` command.
 - **Lifecycle state** (`activeProject`, `lastPausedProject`) — cleared with `oat config set <key> ''` instead.
 - **Pack intent** (`tools.*`) — removed with `oat tools remove --pack <pack> --scope project`, which also removes the installed pack files. Clearing the intent alone would leave them behind.
 - **Aggregate read views** (`workflow.dispatchCeiling`, `workflow.dispatchCeiling.providers`) — these are assembled for `get` from the leaf keys and are not stored as such. Unset `workflow.dispatchCeiling.preset` or `workflow.dispatchCeiling.providers.<provider>` instead.
+- **Read-only remote-policy structure** (`pjm.remote`, `pjm.remote.policy`, `pjm.remote.schemaVersion`) — unset a documented mutable child key instead; removing the complete policy or its schema discriminator is not supported.
 - **Environment-shadowed keys with nothing stored on the target surface** — when `OAT_PROJECTS_ROOT`, `OAT_PROJECTS_DEFAULT_SCOPE`, or `OAT_WORKTREES_ROOT` supplies the effective value and the surface holds nothing to remove, clear the environment variable in your shell. When the surface _does_ hold a stored value, `unset` removes it (as `set` would rewrite it) and warns that the override still supplies the effective value.
 
 ## `workflow.*` preference keys