@open-agent-toolkit/cli 0.3.12 → 0.3.14

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

@@ -1,191 +0,0 @@
----
-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/guide/index.md

@@ -1,31 +0,0 @@
----
-title: User Guide
-description: User-facing guide for operating OAT across provider sync, docs tooling, workflow execution, skills, and ideas.
----
-
-# User Guide
-
-This page is now a compatibility router.
-
-The old catch-all User Guide is being split into clearer adoption lanes so new users can choose the part of OAT that matches what they actually need.
-
-## Contents
-
-- [Core Concepts](concepts.md) - High-level mental model while concept material is being redistributed.
-
-## Status
-
-This guide bucket remains visible so older links have a stable landing page. New docs should go into the canonical top-level sections below instead of adding more pages under `guide/`.
-
-## Canonical Sections
-
-- [Provider Sync](../provider-sync/index.md) - Provider interoperability, drift, sync, and config behavior.
-- [Agentic Workflows](../workflows/index.md) - Tracked projects, ideas, workflow skills, and lifecycle execution.
-- [Docs Tooling](../docs-tooling/index.md) - Docs app setup, docs commands, and docs workflow entry points.
-- [CLI Utilities](../cli-utilities/index.md) - Bootstrap, tool packs, configuration, and general CLI surfaces.
-- [Reference](../reference/index.md) - Durable contracts and reference material.
-
-## Legacy Pages Still Under Guide
-
-- [Core Concepts](concepts.md) - High-level mental model while concept material is being redistributed.
-- This guide bucket is being retired. Use the canonical top-level sections above for active documentation.

package/assets/docs/guide/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "User Guide",
-  "pages": ["concepts"]
-}

package/assets/docs/quickstart.md

@@ -1,88 +0,0 @@
----
-title: Quickstart
-description: 'Start-here guide for choosing the right OAT adoption path.'
----
-
-# Quickstart
-
-Use this page to choose the OAT path that matches what you are actually trying to do.
-
-This page is intentionally lightweight. It is not the full command manual. Once you choose a path, continue into the owning section for the deeper operational detail.
-
-## Prerequisites
-
-- Node.js 22.17 or newer
-- Git 2.31 or newer
-
-OAT does not run an up-front Git version check. Git compatibility is evaluated
-best-effort by each command, and a missing or unsupported Git operation exits as
-a system error.
-
-## Choose a Path
-
-### Provider Sync
-
-Use this path when you want canonical skills, agents, and rules to stay aligned across provider surfaces such as Claude, Cursor, Copilot, Gemini, or Codex.
-
-Best fit:
-
-- you want cross-provider sync and drift checks
-- you care about canonical-to-provider asset management
-- you do not necessarily need tracked project workflows
-
-Continue here:
-
-- [Provider Sync](provider-sync/index.md)
-
-### Agentic Workflows
-
-Use this path when you want tracked, resumable implementation work with explicit lifecycle artifacts, reviews, and handoff-friendly state.
-
-Best fit:
-
-- you want structured project execution
-- you want lifecycle artifacts like `state.md`, `plan.md`, and `implementation.md`
-- you want a workflow layer on top of the base CLI/tooling
-
-Continue here:
-
-- [Agentic Workflows](workflows/index.md)
-
-### Docs Tooling
-
-Use this path when you are bootstrapping or maintaining a documentation surface with OAT.
-
-Best fit:
-
-- you need docs app setup or maintenance workflows
-- you care about docs navigation, docs commands, and docs-specific analysis/apply flows
-- you want the docs-system contract rather than the broader workflow layer
-
-Continue here:
-
-- [Docs Tooling](docs-tooling/index.md)
-
-### CLI Utilities
-
-Use this path when you want general OAT CLI help outside the dedicated provider-sync, workflows, and docs-tooling lanes.
-
-Best fit:
-
-- you want bootstrap/setup guidance
-- you want tool-pack, configuration, local-state, or utility command guidance
-- you want a general CLI surface map rather than one specific product lane
-
-Continue here:
-
-- [CLI Utilities](cli-utilities/index.md)
-
-## If You Are Unsure
-
-Start with the path that best matches the primary thing you need right now.
-
-- If you are trying to sync canonical assets across tools, choose Provider Sync.
-- If you are trying to run a tracked implementation workflow, choose Agentic Workflows.
-- If you are working on the docs system itself, choose Docs Tooling.
-- If you mainly need command-line setup or utility guidance, choose CLI Utilities.
-
-You can adopt more than one lane over time. OAT is designed so these sections can be used together or independently.

package/assets/docs/workflows/projects/autonomy.md

@@ -1,196 +0,0 @@
----
-title: Autonomous Project Execution
-description: 'Session-scoped autonomy signals, gate boundaries, review requirements, and execution-learnings behavior for OAT projects.'
----
-
-# Autonomous Project Execution
-
-OAT autonomy is an explicit session policy for driving a project through its
-lifecycle without waiting at ordinary interactive gates. It does not bypass the
-gate-owning skills: each skill still applies its own checks, records provenance,
-and either resolves the gate or reports a boundary.
-
-The provider-agnostic entry point is `oat-project-autonomous`. Invoke it
-deliberately with a goal, project slug, ticket reference, or active project. A
-restart does not silently resume autonomy; invoke the skill again and it resumes
-from the persisted project state.
-
-## Activation contract
-
-An autonomous session uses both signals:
-
-```bash
-export OAT_AUTONOMOUS=1
-export OAT_NON_INTERACTIVE=1
-```
-
-`OAT_AUTONOMOUS=1` implies and sets `OAT_NON_INTERACTIVE=1` for the current
-run. The distinction is intentional:
-
-- `OAT_NON_INTERACTIVE=1` selects existing safe no-prompt paths for one
-  workflow.
-- `OAT_AUTONOMOUS=1` additionally enables lifecycle chaining, defined gate
-  resolutions, boundary stops, and provenance requirements.
-
-Both signals are session-scoped. Never write them to `state.md`, `plan.md`,
-repository config, user config, or any other durable artifact. A later
-interactive session therefore needs no autonomy cleanup and behaves
-interactively around the state the autonomous run left behind.
-
-## Gate outcomes
-
-Every interactive lifecycle gate has one of two autonomous outcomes:
-
-1. **Auto-resolve** using an existing safe path, then record the decision and
-   evidence.
-2. **Boundary stop** with a structured blocker and a resumable next step.
-
-The main boundary classes are:
-
-- **Product judgment** — repository evidence cannot resolve material scope or
-  requirements ambiguity.
-- **Destructive-change risk** — an action could discard work, delete data,
-  rewrite history, or broadly restructure an unapproved surface.
-- **Unresolved Critical findings** — a blocking review has not passed.
-- **Repository-policy approval** — protected operations require authority the
-  session does not have.
-- **Missing credentials** — a required external action has no authenticated
-  route or offline equivalent.
-
-A boundary is a successful fail-closed outcome, not permission to continue with
-a guessed answer. The run reports what stopped, the evidence, and the operator
-action needed to resume.
-
-The canonical autonomy contract and exhaustive gate inventory
-(`.agents/docs/autonomy-contract.md`, vendored into each consuming skill at
-`references/docs/autonomy-contract.md`) map each prompt to its autonomous
-resolution and provenance.
-
-### Dispatch-ladder scope selection
-
-An incomplete reusable dispatch ladder is auto-resolvable when an authorized
-adoption-compatible config scope is available. Autonomous planning checks
-config-file existence in this fixed order without prompting or reordering from
-effective value or matrix-cell provenance:
-
-1. user config (`~/.oat/config.json`);
-2. repo-local config (`.oat/config.local.json`);
-3. shared config (`.oat/config.json`), only when repository policy already
-   authorizes that write.
-
-Before writing, planning rejects a candidate that would preserve a
-provider-level scalar in that scope or remain shadowed by one at higher
-precedence. It always tries the next authorized compatible candidate and stops
-without mutation only when none remains.
-
-The planner runs exactly one matching `oat config adopt dispatch-matrix --keep-existing`
-command, records file-existence and compatibility evidence plus the selected
-scope, and re-runs dispatch preflight. Existing explicit cells remain unchanged;
-their provenance does not select the persistence scope. No authorized
-compatible scope, or a ladder that remains incomplete after adoption, is still
-a repository-policy boundary. `OAT_NON_INTERACTIVE=1` without
-`OAT_AUTONOMOUS=1` does not select a scope and continues to fail closed.
-
-## Review contract
-
-Autonomous execution preserves independent review:
-
-- Discovery, design, and plan artifacts run their configured exit gates.
-  Quick-start reviews the discovery, optional lightweight design, and plan as
-  one bundle when those artifacts exist.
-- Review routing is selected before launch through the dispatch substrate.
-  A configured gate target is preferred when available; otherwise policy may
-  choose a target-preserving subagent route. Any reduced independence is
-  explicit in the dispatch record.
-- Once a launch is accepted, it is terminal for route selection. Failures use
-  bounded recovery with the same payload; they do not silently fall through to
-  a cheaper or less independent reviewer.
-- Eligible review artifacts are received immediately. Fix tasks use the normal
-  bounded implement-and-re-review loop.
-- Critical findings and failed blocking reviews stop progression. High
-  findings follow the configured gate policy.
-- A normal phase or final lifecycle review cannot satisfy a configured
-  implementation exit gate. Only gate invocation provenance with the matching
-  run ID can authorize that boundary.
-
-Project review artifacts and review rows reference launcher-owned dispatch
-records. The configured invocation is authoritative evidence; child
-self-reporting is optional corroboration. See [Evidence
-Layers](evidence-layers.md) and [Reviews](reviews.md).
-
-## HiLL and lifecycle closeout
-
-If checkpoint selection is unconfirmed when autonomy starts implementation,
-OAT takes the existing `workflow.hillCheckpointDefault: final` path explicitly:
-
-```yaml
-oat_plan_hill_phases: ['<final-phase-id>']
-oat_auto_review_at_hill_checkpoints: true
-```
-
-An existing valid explicit list is preserved. An existing `[]` is also
-preserved and means every phase, never no phases. At each configured checkpoint,
-autonomy runs and receives the review without waiting.
-
-At final closeout, autonomy follows the same authoritative order as an
-interactive run: final verification, mandatory final lifecycle review,
-configured implementation exit gate, pre-approval sequence, final HiLL
-approval, post-approval sequence, then implementation completion and success
-output. A `not_configured` resolution persists an explicit no-gate allowance
-before the sequence starts; a null, missing, or unrecognized resolver result
-fails closed as unresolved. A gate this project disabled persists an
-`allowed/configured` result with `disposition: project_disabled` and never
-launches the configured command.
-
-Autonomy does not turn an ordinary independent review into configured-gate
-provenance. A configured review must produce a gate-originated artifact with
-the matching run ID, and eligible receive must be durably reconciled. Blocked,
-ambiguous, malformed, or stale gate state is a boundary stop: the run remains
-resumable through `oat-project-implement` and cannot continue to approval,
-completion, or output.
-
-The default autonomous tail is summary, documentation, and final PR when no
-post-implementation sequence is configured; stored legacy or structured
-sequences retain their documented meaning.
-
-## Execution-learnings loop
-
-Autonomous runs keep an append-only project-local
-`oat-execution-learnings.md`. Dated entries record an observation, impact, and
-recommendation under the source taxonomy: `gotcha`, `efficiency`,
-`documentation-gap`, `candidate-skill-content`, `decision`, or
-`environment-limited`.
-
-When the file exists, `oat-project-summary` synthesizes actionable
-recommendations into `## Autonomous Execution Learnings`, grouped as:
-
-- agent-instruction updates;
-- cloud-environment improvements;
-- code follow-ups;
-- workflow issues.
-
-Each recommendation links back to its source entry. Projects without the
-learnings file render normal summaries with no autonomous-learnings section.
-The summary export keeps the synthesized recommendations after project
-archival.
-
-## Taking over interactively
-
-After an autonomous session ends:
-
-1. Start a normal session without the autonomy environment signals.
-2. Open the same project from its repository-local `.oat` directory.
-3. Resume the owning lifecycle skill.
-
-Persisted review rows, task state, explicit HiLL checkpoints, and dispatch
-provenance remain valid. Interactive prompts and checkpoint pauses return
-normally because autonomy itself was never persisted.
-
-## Related
-
-- [HiLL Checkpoints](hill-checkpoints.md) — checkpoint field semantics and
-  interactive behavior.
-- [Implementation Execution](implementation-execution.md) — phase execution,
-  review, fixes, and closeout.
-- [Cursor Cloud](cursor-cloud.md) — project-home and environment-readiness
-  guidance for cloud runs.

package/assets/docs/workflows/projects/hill-checkpoints.md

@@ -1,93 +0,0 @@
----
-title: Human-in-the-Loop Lifecycle (HiLL) Checkpoints
-description: 'Checkpoint configuration and behavior for pauseable, human-in-the-loop lifecycle execution.'
----
-
-# Human-in-the-Loop Lifecycle (HiLL) Checkpoints
-
-OAT supports two checkpoint classes:
-
-- Workflow phase checkpoints
-- Plan phase checkpoints
-
-The [Phase gate review](reviews.md#phase-review-gate) (`oat_phase_review_gate`) is a separate, non-pausing mechanism — it does not pause on a passing gate and never modifies the HiLL keys below (`oat_hill_completed`, `oat_plan_hill_phases`).
-
-## Workflow checkpoints (`state.md`)
-
-Frontmatter keys:
-
-- `oat_hill_checkpoints`
-- `oat_hill_completed`
-
-Example:
-
-```yaml
-oat_hill_checkpoints: ['discovery', 'spec', 'design']
-oat_hill_completed: ['discovery']
-```
-
-## Plan phase checkpoints (`plan.md`)
-
-Frontmatter key written after implementation confirmation:
-
-- `oat_plan_hill_phases`
-
-Semantics:
-
-- Field absent: valid before the first `oat-project-implement` run confirms checkpoint selection. Planning may intentionally leave the field unset until that first execution starts.
-- Empty list: checkpoint after every phase boundary, but only after implementation has confirmed the choice and written `oat_plan_hill_phases: []` into `plan.md`.
-- Explicit list: checkpoint only after completing the named phases (`p01`, `p04`, etc).
-
-### Lite checkpoint bypass
-
-Lite projects have no HiLL checkpoints. `oat-project-implement` resolves
-`oat_workflow_mode` from project state before any checkpoint field read, and
-when the mode is `lite` it resolves checkpoint state as `none` without reading
-or interpreting `oat_plan_hill_phases`. An empty list cannot represent lite's
-policy, because for every other mode an empty list means "checkpoint after every
-phase". `oat-project-implement`'s Lite checkpoint bypass writes:
-
-```yaml
-oat_auto_review_at_hill_checkpoints: false # lite: no checkpoints
-```
-
-The workflow preference prompt, the standard checkpoint prompt, and the
-auto-review preference prompt are all skipped in both interactive and autonomous
-runs. Only HiLL approval pauses are absent — the root-owned per-phase review and
-the final review remain required.
-
-The rest of this section applies to `spec-driven`, `quick`, and `import`
-projects.
-
-On the first implementation run, `oat-project-implement` must summarize every plan phase, state the total phase count and final phase ID, and then ask an explicit three-option checkpoint question:
-
-- Stop after each phase
-- Stop after specific phases
-- Stop only after the final phase is completed
-
-It then writes the confirmed value into `plan.md`. If the field is later missing during a resumed implementation run, treat that as bookkeeping drift rather than as an implicit default.
-
-Listed phases are where you stop **after completing them**, not before. `["p03"]` means "complete p03, then pause" — not "pause before starting p03." Setting the last phase ID (e.g., `["p03"]` when p03 is final) means "stop only at the end of implementation."
-
-### Setting a default via `workflow.hillCheckpointDefault`
-
-The first-run checkpoint prompt can be skipped entirely by setting the `workflow.hillCheckpointDefault` preference:
-
-- `every` — automatically write `oat_plan_hill_phases: []` (pause after every phase) without prompting
-- `final` — automatically write `oat_plan_hill_phases: ["<final-phase-id>"]` (pause only at the end) without prompting
-
-When set, `oat-project-implement` reads the preference before the prompt and prints `HiLL checkpoints: <every|final> (from workflow.hillCheckpointDefault)`, skipping the interactive choice. When unset (default), the skill prompts as before.
-
-This is a personal preference — typically set at user scope so it applies to every repo:
-
-```bash
-oat config set workflow.hillCheckpointDefault final --user
-```
-
-See [Workflow preferences in the Configuration guide](../../cli-utilities/configuration.md#workflow-preferences-workflow) for the full list of preference keys and surface guidance.
-
-## Reference artifacts
-
-- `.oat/templates/plan.md`
-- `.oat/projects/<scope>/<project>/plan.md`
-- `.oat/projects/<scope>/<project>/state.md`