@open-agent-toolkit/cli 0.3.13 → 0.3.14

package/assets/docs/workflows/projects/execution/picking-up-projects.md

@@ -0,0 +1,376 @@
+---
+title: Picking Up Projects
+description: Continue a synced OAT project on another machine or from another user through its dedicated Git ref.
+---
+
+# Picking Up a Project on Another Machine or From Another User
+
+Synced projects travel through ordinary Git refs on `origin`. Their artifact
+history is independent from the implementation branch, so a teammate or a
+second machine can continue the project even before the branch carrying its
+record file merges.
+
+## Resume work on this machine
+
+If the project already exists in this checkout, you do not need the
+cross-machine steps on the rest of this page. Run these three agent skills in
+order (type them in your coding agent's chat, not a terminal; Codex uses `$`
+instead of `/`):
+
+1. **Open the project.** `/oat-project-open <project>` makes it the active
+   project in this checkout (the one OAT works on when you do not name one)
+   and resumes it if it was paused. See
+   [oat-project-open](#oat-project-open).
+2. **See where it stands.** `/oat-project-progress` is a read-only status
+   check: it reports the phase, blockers and recommended next skill, and does
+   not commit, push or start that skill. It only refreshes the generated
+   `.oat/state.md` dashboard and, for a synced project (one whose artifacts
+   travel on a Git ref, as described above), pulls the latest artifacts. See [oat-project-progress](#oat-project-progress).
+   Progress first checks for the repository knowledge index, the codebase
+   summary that `/oat-repo-knowledge-index` writes under
+   `.oat/repo/knowledge/`. If that folder has no Markdown file, progress tells
+   you to run `/oat-repo-knowledge-index` and stops without a project report,
+   whatever the project's mode; quick, lite and imported projects never
+   needed the index before, so this can be the first time you see it. Run
+   `/oat-repo-knowledge-index` once and then run progress again, or skip to
+   step 3: `/oat-project-next` itself does not check for the index (spec-driven
+   discovery, which it may start, does). If the index
+   exists but is more than 7 days old or more than 20 files have changed
+   since it was built, progress only warns and continues.
+3. **Continue.** `/oat-project-next` starts the next lifecycle skill without
+   asking you first, and that skill can commit, push your branch or open a
+   pull request. See [oat-project-next](#oat-project-next).
+
+## Discover and adopt
+
+From any checkout with access to `origin`:
+
+```bash
+oat project list --remote
+oat project pull <project>
+```
+
+`list --remote` discovers `refs/oat/projects/*` directly. `pull` can adopt a
+remote project that has no local record yet: it writes the record and creates
+the nested checkout. When the selected project is a coordination parent, pull
+also discovers and pulls its child projects by default. Pass `--no-children`
+only when you intentionally want the selected project alone.
+
+Completed projects are not adoption candidates. Their authoritative ref is
+`refs/oat/completed/<project>`; both `pull` and `open` return a terminal
+diagnosis instead of recreating an archived checkout or record. A same-SHA
+active ref may remain as an inert alias and is ignored. Differing active and
+completed SHAs require repair before lifecycle work continues. The same guard
+applies to coordination children: a terminal child discovered while pulling
+its parent is reported and skipped rather than adopted.
+
+After adoption, set or open the project through the normal lifecycle command
+you are using. Arrival-aware project skills pull before reading its artifacts.
+
+An adopted quick-workflow project whose `plan.md` is not implementation-ready
+resumes through `oat-project-quick-start`, which continues it in place without
+re-scaffolding, rather than through `oat-project-implement`. `oat-project-plan`,
+`oat-project-progress`, and `oat-project-next` all route by the single **quick
+plan readiness** predicate that `oat-project-quick-start` defines; readiness is
+never inferred from the presence of tasks alone.
+
+`oat project status` and `oat project list` apply the same predicate. For a
+quick project at the `plan` phase they recommend `oat-project-quick-start`, with
+the unmet clause in the reason, until the plan carries ready frontmatter, a
+durable `## Reviews` disposition, and a substantive task; only then do they
+recommend `oat-project-implement`. Recommendations for lite, spec-driven, and
+import projects are unchanged, because the predicate is quick-workflow policy.
+
+## What travels
+
+- The project ref carries the complete active artifact tree and its history.
+- The tracked JSON record travels once the branch containing it is shared or
+  merged.
+- Coordination relationships travel in the artifacts and records pulled with
+  the project.
+
+## What does not travel automatically
+
+- `local` projects never leave their original machine.
+- GitHub forks copy branches and tags, but not the `refs/oat/*` namespace. A
+  fork collaborator needs access to the upstream remote or an explicit ref
+  transfer.
+- A normal `git clone` fetches branches and tags, not custom OAT refs. OAT
+  handles remote discovery with `ls-remote` and explicitly fetches the selected
+  project ref during sync operations such as `pull`; do not expect a generic
+  clone or `git fetch` to materialize the checkout.
+
+## Why completed refs remain durable
+
+`refs/oat/completed/<project>` is a real Git ref locally and on `origin`. The
+objects reachable from it remain garbage-collection roots even when no nested
+checkout exists. Branch pruning, remote-tracking-ref pruning, and
+`git worktree prune` do not delete the completed ref. Completion deliberately
+retains this terminal reachability root so pinned PR links remain valid.
+
+Only the explicit destructive operation `oat project prune` removes the
+completed ref and any matching active alias. Treat that as permanent Git
+project-history reachability deletion and review its warnings before using
+`--force`. Prune does not remove durable local or S3 archive snapshots, and it
+refuses to delete either ref when their SHAs differ.
+
+## Archive contents
+
+When archive is selected, completion copies a synced project into
+`.oat/projects/archived/<project>/` without the nested checkout's `.git`
+pointer or `reviews/`. S3 snapshots also omit `pr/`, following the existing
+archive policy. When archive is disabled or declined, the active synced
+checkout remains in place. Successful archived closeout instead uploads the S3
+snapshot first when configured, makes the completed ref authoritative, removes
+the checkout, and deletes the tracked JSON record. The local archive metadata
+retains the source-ref identity needed for recordless retries and later S3
+restore without recreating active state.
+
+If closeout is interrupted after terminal archive identity exists, rerun
+completion so it can resume from the completed ref and archive metadata. Do not
+use `pull` or `open` to recreate an active record or checkout.
+
+For a `shared` project, archive moves the project into
+`.oat/projects/archived/<project>/` and removes the source directory, while
+completion keeps the `activeProject` pointer until the receipt validates.
+Rerunning completion after an interruption between the archive and that clear
+recognizes exactly this state — the pointer names a source directory that no
+longer exists and the archive carries `oat_lifecycle: complete` plus the
+`Lifecycle complete; archived locally` phase marker — so it validates the
+discovered archive and clears the pointer without archiving a second time or
+sealing the project log again. An interruption before the archive leaves the
+source directory in place, so completion simply reruns from the start and skips
+the work it already finished.
+
+If the archive cannot be discovered — the source directory is gone and either
+no archived project or several match the name — completion stops and leaves the
+pointer untouched. Recover manually: locate the archive directory under
+`.oat/projects/archived/`, confirm `oat_lifecycle: complete` in its `state.md`,
+then clear the pointer with `oat config set activeProject ""`.
+
+## Related
+
+- [Reviewing OAT PRs](../reviews/reviewing-oat-prs.md)
+- [Project Artifacts](../../../reference/project-artifacts.md)
+- [Implementation Execution](implementation-execution.md#synced-projects-in-worktrees)
+
+## Choosing a Resume Skill
+
+Project selection, status inspection and lifecycle execution are different
+actions. Use open to choose the project, progress to inspect it, and next when
+you want the agent to invoke the next lifecycle skill. Clearing the active
+project pauses the current context; it does not delete or complete the project.
+
+The examples below are agent skill invocations, not terminal `oat`
+subcommands. Use your host's supported skill-invocation syntax.
+
+**Terms used in this section:**
+
+- **Active project:** the project OAT works on in this checkout when you do
+  not name one. Its path is stored as `activeProject` in
+  `.oat/config.local.json`, a local file that is not committed.
+- **Synced project:** a project whose artifacts travel on their own Git ref on
+  `origin`, as described at the top of this page. OAT saves its tracking
+  changes by pushing that ref.
+- **HiLL checkpoint** (human-in-the-loop): a lifecycle point or plan phase
+  where the workflow stops and waits for your approval. See
+  [HiLL Checkpoints](../planning/hill-checkpoints.md).
+- **Review artifact:** the Markdown file a project review writes into the
+  project's `reviews/` directory. It counts as unprocessed until project
+  review-receive has recorded what to do about its findings.
+- **Gate:** a configured check, usually an independent review, that must pass
+  before the workflow continues. The _implementation exit gate_ runs after the
+  final code review. See [Workflow gates](../../advanced/workflow-gates.md).
+
+## oat-project-open
+
+Choose an existing project before continuing its lifecycle. This is useful
+both when returning to a paused project and when switching from one project to
+another. It activates the selected project; it does not start implementation.
+
+**Needs an active OAT project:** no. Open is how you set one.
+
+**Invocation:**
+
+```text
+/oat-project-open checkout-hardening
+```
+
+With no project name, the skill asks which project to open. It runs
+`oat project open` rather than editing the active pointer by hand.
+
+**Prerequisites:** No previously active project is required. The CLI checks
+that the selected project resolves and that its `state.md` exists; it checks
+the state content only when it resumes a paused project. For a synced project,
+remote access may be needed. A completed synced project is refused with a
+terminal diagnosis, and an archived project is not found. For shared and local
+projects, open does not check lifecycle state, so do not open a project that
+is already complete.
+
+**What it does without asking:** It sets `activeProject` in
+`.oat/config.local.json` and refreshes the generated `.oat/state.md`
+dashboard. If the project is paused, it rewrites the project's `state.md` to
+active and removes the pause fields; for a shared or local project that edit
+is left uncommitted. For a synced project, open may fetch the project ref,
+commit an adoption record (`chore(oat): adopt synced project <name>`) on your
+current branch when this checkout has no record yet, and push a resume commit
+to `origin` if the project was paused. If that push fails, the active pointer
+is left unchanged.
+
+**Example scenario:** You paused checkout-hardening yesterday to investigate
+an unrelated issue. Today, open checkout-hardening by name. The CLI checks
+that the project and its `state.md` exist, resumes it because it was paused and
+makes it active in this checkout without re-scaffolding the plan or marking any
+task finished.
+
+**Expected output:** Confirmation of the active project and a refreshed state
+dashboard. A paused project's pause metadata is cleared when it is resumed.
+If the CLI reports an error, address the diagnosis instead of manually pointing
+at an invalid or completed project.
+
+**Next step:** Use progress if you want to inspect the current state before
+acting, or next if you want to continue. Opening does not prove that a plan is
+implementation-ready or that earlier review feedback has been processed.
+
+## oat-project-next
+
+Invoke the next appropriate lifecycle skill using current project state. This
+is the action-oriented counterpart to progress, not merely another status
+report.
+
+**Needs an active OAT project:** yes, in practice. With no valid active
+pointer, the router lists projects across supported scopes, hands off to open
+so you can select one, then stops; invoke next again after selection. With no
+projects at all, it reports that condition and suggests a project-creation
+workflow instead of inventing a resume target.
+
+**Invocation:**
+
+```text
+/oat-project-next
+```
+
+**Prerequisites:** An existing project must be available.
+
+**What it does without asking:** Next invokes the skill it selects
+immediately, without asking you to confirm, and reported blockers do not stop
+it. Depending on state, it can start `oat-project-implement` (which dispatches
+subagents and commits), run `oat-project-pr-final` (which pushes your branch
+and opens a GitHub pull request with `gh pr create`; a lite project goes there
+directly after a passed final review), or run `oat-project-complete`. For a
+synced project, it first runs `oat project pull`, which updates the project's
+checkout. The router itself does not edit project artifacts. Use progress when
+you want to approve the route first.
+
+**Example scenario:** Checkout-hardening is mid-implementation: phase p02 just
+finished, and the review artifact from a p02 project review is still waiting
+in the project's `reviews/` directory. You invoke next expecting it to continue
+with p03. The router sees the unprocessed review and invokes project
+review-receive first rather than advancing past the feedback. When that
+workflow finishes, invoke next again to continue from the updated state.
+
+**Expected output:** The selected project, current phase, target skill and
+routing reason, followed by invocation of that skill. Pending HiLL
+checkpoints, quick-plan readiness and unprocessed reviews affect the route.
+Once implementation is marked complete, the router checks in this order: an
+unresolved or stale implementation exit gate, an unfinished closeout sequence,
+or pending revision tasks all route back to `oat-project-implement`; only then
+does it look for unprocessed reviews, a final code review that has not passed,
+a missing summary, a missing PR and finally project completion.
+
+**Next step:** Follow the invoked workflow. If you only wanted a
+recommendation, use progress instead. Blockers shown in the routing
+announcement are warnings only; the router invokes the selected skill anyway.
+
+## oat-project-progress
+
+Inspect repository knowledge and project status before deciding what to do.
+Unlike next, progress offers the recommended route rather than automatically
+starting it.
+
+**Needs an active OAT project:** no. Progress can report that none is active
+and list the available projects.
+
+**Invocation:**
+
+```text
+/oat-project-progress
+```
+
+You can also explicitly ask the agent to “check project progress.” Finishing
+another workflow step does not automatically authorize this check.
+
+**Prerequisites:** An active project is optional. The skill can report that
+none is active and inspect available projects. It checks the repository
+knowledge base first; if `.oat/repo/knowledge/` holds no Markdown file, it asks
+you to run `/oat-repo-knowledge-index` and stops before the later project
+report, in every project mode. A stale knowledge base only produces a warning. Synced-project arrival may
+pull current artifacts, and the skill refreshes the generated dashboard; a
+diagnostic invocation is not a guarantee of zero filesystem or network activity.
+
+**What it does without asking:** For a synced active project it runs
+`oat project pull`, and it regenerates the `.oat/state.md` dashboard. It does
+not commit, push or invoke another skill; it offers the recommended skill and
+waits for you.
+
+**Example scenario:** You return after several days away and do not remember
+whether checkout-hardening needs more implementation or a review. Progress
+checks knowledge freshness and, when that prerequisite is available, reports
+the project mode, phase, blockers, checkpoints and next recommended skill. If
+manual commits appear ahead of the task ledger, it can suggest reconciliation
+instead of presenting the ledger as unquestionable evidence.
+
+**Expected output:** A knowledge-base status report and, when the check can
+continue, project summaries with the active project highlighted. Configured
+project gate overrides are reported explicitly. Recommendations do not pass
+the gates or approve the next action for you.
+
+**Next step:** Choose whether to run the recommendation. For manually committed
+work missing from tracking, use
+[reconciliation](execution-skills.md#oat-project-reconcile). When you are ready
+for automatic lifecycle routing, invoke next. Progress and next can differ
+because next also inspects execution boundaries and outstanding review events.
+
+## oat-project-clear-active
+
+Pause the current project and leave the checkout without an active OAT project.
+This is a context switch, not an archive, deletion or completion action.
+
+**Needs an active OAT project:** no. With nothing active, the skill says so
+and exits successfully.
+
+**Invocation:**
+
+```text
+/oat-project-clear-active
+```
+
+**Prerequisites:** An active project is optional. With an active pointer, the
+skill delegates to `oat project pause`, which must be able to read the project
+state. A pointer to a project directory that no longer exists fails with
+“Project not found”, and the pointer is kept. With no pointer, the skill
+reports that no project is active and exits successfully without trying to
+pause a nonexistent target.
+
+**What it does without asking:** `oat project pause` writes
+`oat_lifecycle: paused` and a pause timestamp into the project's `state.md`,
+then clears the active pointer. In a shared or local project that `state.md`
+change is left uncommitted: commit it yourself, or it shows up as uncommitted
+project bookkeeping. A synced project commits the pause and pushes it to
+`origin`.
+
+**Example scenario:** Checkout-hardening is still unfinished, but you want to
+work on an untracked investigation without accidentally routing its changes
+into that project. Clear the active project: OAT pauses checkout-hardening and
+clears the pointer. Running the skill again with nothing active is a safe no-op,
+not an error or a request to create a replacement project.
+
+**Expected output:** Confirmation that the active project was cleared through
+pause, or the no-active-project message. The project's artifacts and
+implementation history remain available for later resumption. For synced
+projects, pause publication can fail; a reported publication failure is not a
+successful context switch, and the active pointer is retained for recovery.
+
+**Next step:** Open a named project when you want to resume tracked work. Do
+not use clear-active to stop a running agent or revoke work already in flight;
+pausing project state is different from interrupting an execution process.

package/assets/docs/{cli-utilities → workflows/projects/execution}/project-log.md

@@ -86,7 +86,7 @@ Two optional flags let an interrupted append be replayed safely:
 
 Together they are the recovery entry point for a gate whose project-log
 finalization could not commit. See
-[Workflow Gates](./workflow-gates.md#project-log-finalization) for the receipt
+[Workflow Gates](../../advanced/workflow-gates.md#project-log-finalization) for the receipt
 and the exact recovery command.
 
 The helper produces these heading grammars in UTC:

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

@@ -1,36 +1,25 @@
 ---
-title: Workflow & Projects
+title: Projects
 description: 'Lifecycle, project artifacts, reviews, PR flow, and repository analysis for tracked OAT projects.'
 ---
 
-# Workflow & Projects
+# Projects
 
 Use this section when you want the detailed lifecycle and artifact model behind tracked OAT projects.
 
 Projects are where the workflow layer becomes concrete: lifecycle phases, `state.md`, `plan.md`, review gates, PR flow, and repository-analysis helpers all live here.
 
+## Reference Contracts
+
+Read [Project Artifacts](../../reference/project-artifacts.md) for project file contracts and [State Machine](../../reference/project-state-machine.md) for lifecycle and review-state transitions.
+
 ## Contents
 
 - [Lifecycle](lifecycle.md) - End-to-end flow from discovery through completion.
-- [Project Retrospectives](retro.md) - Generate evidence-grounded retros, apply repo improvements, and file tracker feedback.
-- [Autonomous Project Execution](autonomy.md) - Session-scoped autonomy signals, gate boundaries, review requirements, and execution learnings.
-- [OAT in Cursor Cloud](cursor-cloud.md) - Project-home, provisioning, asset-precedence, and execution-surface guidance for cloud agents.
-- [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
-- [HiLL Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
-- [Dispatch Policy](dispatch-ceiling.md) - Managed capped tiers, managed Uncapped, Inherit Host Defaults, and provider-specific enforcement.
-- [Orchestration Model](orchestration-model.md) - The layered dispatch model: roles, selection flow, and per-harness topology.
-- [Review Flavors](review-flavors.md) - The four review flavors and who resolves each one's target.
-- [Evidence Layers](evidence-layers.md) - The three-layer dispatch evidence model behind records and smoke verification.
-- [Programmatic Execution](programmatic-execution.md) - Per-harness headless/CLI execution surfaces and where OAT uses them.
-- [Project Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
-- [Implementation Execution](implementation-execution.md) - Phase dispatch, runtime selection, review/fix loop, and dry-run behavior.
-- [Reviewing OAT PRs](reviewing-oat-prs.md) - Read synced-project records and SHA-pinned reviewer links in a PR.
-- [Picking Up Projects](picking-up-projects.md) - Continue a synced project on another machine or from another user.
-- [Project Splitting](splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.
-- [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.
-- [Reviews](reviews.md) - How review request/receive loops work inside OAT projects.
-- [PR Flow](pr-flow.md) - Progress and final PR generation expectations.
-- [Repository PR Comment Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.
+- [Reviews](reviews/index.md) - How review request/receive loops work inside OAT projects.
+- [Planning](planning/index.md) - Design modes, HiLL checkpoints and project splitting.
+- [Execution](execution/index.md) - Implementation execution, project logs and picking up shared projects.
+- [Closeout](closeout/index.md) - Retrospectives and PR flow.
 
 ## What This Section Is
 
@@ -39,39 +28,39 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 ## Start Here
 
 - Start with [Lifecycle](lifecycle.md) for the end-to-end flow.
-- Use [Autonomous Project Execution](autonomy.md) for unattended lifecycle runs and defined boundary behavior.
-- Read [OAT in Cursor Cloud](cursor-cloud.md) before running OAT in a cloud workspace.
-- Read [Artifacts](artifacts.md) once you need the file contract behind project execution.
-- Use [Project Splitting](splitting.md) when one discovery or brainstorm should become coordinated child projects.
-- Use [HiLL Checkpoints](hill-checkpoints.md) when you want to understand pause/approval behavior.
+- Use [Autonomous Project Execution](../advanced/autonomy.md) for unattended lifecycle runs and defined boundary behavior.
+- Read [OAT in Cursor Cloud](../advanced/cursor-cloud.md) before running OAT in a cloud workspace.
+- Read [Artifacts](../../reference/project-artifacts.md) once you need the file contract behind project execution.
+- Use [Project Splitting](planning/splitting.md) when one discovery or brainstorm should become coordinated child projects.
+- Use [HiLL Checkpoints](planning/hill-checkpoints.md) when you want to understand pause/approval behavior.
 
 ## Common Tasks
 
 - Understand lifecycle order and alternate lanes in [Lifecycle](lifecycle.md).
-- Learn the artifact system of record in [Artifacts](artifacts.md).
-- Split broad scopes into coordination parents and focused children in [Project Splitting](splitting.md).
-- Understand lifecycle and review transitions in [State Machine](state-machine.md).
-- Learn review and PR expectations in [Reviews](reviews.md) and [PR Flow](pr-flow.md).
-- Review a synced project's durable context in [Reviewing OAT PRs](reviewing-oat-prs.md).
-- Continue remote project work with [Picking Up Projects](picking-up-projects.md).
+- Learn the artifact system of record in [Artifacts](../../reference/project-artifacts.md).
+- Split broad scopes into coordination parents and focused children in [Project Splitting](planning/splitting.md).
+- Understand lifecycle and review transitions in [State Machine](../../reference/project-state-machine.md).
+- Learn review and PR expectations in [Reviews](reviews/index.md) and [PR Flow](closeout/pr-flow.md).
+- Review a synced project's durable context in [Reviewing OAT PRs](reviews/reviewing-oat-prs.md).
+- Continue remote project work with [Picking Up Projects](execution/picking-up-projects.md).
 
 ## Go Deeper
 
 - [Lifecycle](lifecycle.md) - End-to-end flow from discovery through completion.
-- [Autonomous Project Execution](autonomy.md) - Session activation, gate outcomes, independent review, HiLL closeout, and learnings synthesis.
-- [OAT in Cursor Cloud](cursor-cloud.md) - Repository anchoring, environment readiness, user-scope assets, and Cursor execution surfaces.
-- [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
-- [HiLL Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
-- [Dispatch Policy](dispatch-ceiling.md) - Managed capped tiers, managed Uncapped, Inherit Host Defaults, legacy dispatch-ceiling compatibility, and provider-specific enforcement.
-- [Orchestration Model](orchestration-model.md) - The layered dispatch model: roles, selection flow, and per-harness topology.
-- [Review Flavors](review-flavors.md) - The four review flavors and who resolves each one's target.
-- [Evidence Layers](evidence-layers.md) - The three-layer dispatch evidence model behind records and smoke verification.
-- [Programmatic Execution](programmatic-execution.md) - Per-harness headless/CLI execution surfaces and where OAT uses them.
-- [Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
-- [Project Splitting](splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.
-- [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.
-- [Reviews](reviews.md) - How review request/receive loops work inside OAT projects.
-- [PR Flow](pr-flow.md) - Progress and final PR generation expectations.
-- [Reviewing OAT PRs](reviewing-oat-prs.md) - Record metadata, pinned links, and editor discovery for synced projects.
-- [Picking Up Projects](picking-up-projects.md) - Remote discovery, adopting pull, coordination children, and retention boundaries.
-- [Repository PR Comment Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.
+- [Autonomous Project Execution](../advanced/autonomy.md) - Session activation, gate outcomes, independent review, HiLL closeout, and learnings synthesis.
+- [OAT in Cursor Cloud](../advanced/cursor-cloud.md) - Repository anchoring, environment readiness, user-scope assets, and Cursor execution surfaces.
+- [Design Modes](planning/design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
+- [HiLL Checkpoints](planning/hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
+- [Dispatch Policy](../advanced/dispatch-ceiling.md) - Managed capped tiers, managed Uncapped, Inherit Host Defaults, legacy dispatch-ceiling compatibility, and provider-specific enforcement.
+- [Orchestration Model](../advanced/orchestration-model.md) - The layered dispatch model: roles, selection flow, and per-harness topology.
+- [Review Flavors](reviews/review-flavors.md) - The four review flavors and who resolves each one's target.
+- [Evidence Layers](../advanced/evidence-layers.md) - The three-layer dispatch evidence model behind records and smoke verification.
+- [Programmatic Execution](../advanced/programmatic-execution.md) - Per-harness headless/CLI execution surfaces and where OAT uses them.
+- [Artifacts](../../reference/project-artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
+- [Project Splitting](planning/splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.
+- [State Machine](../../reference/project-state-machine.md) - Lifecycle and review status transitions across a project.
+- [Reviews](reviews/index.md) - How review request/receive loops work inside OAT projects.
+- [PR Flow](closeout/pr-flow.md) - Progress and final PR generation expectations.
+- [Reviewing OAT PRs](reviews/reviewing-oat-prs.md) - Record metadata, pinned links, and editor discovery for synced projects.
+- [Picking Up Projects](execution/picking-up-projects.md) - Remote discovery, adopting pull, coordination children, and retention boundaries.
+- [Repository PR Comment Analysis](../../reference/repository-pr-comments.md) - Repo-wide PR comment collection and triage workflows.

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

@@ -23,7 +23,9 @@ OAT lifecycle order:
 
 **Shortcut:** `oat-project-next` reads project state and invokes the correct next skill automatically — use it instead of remembering which skill comes next. Complements `oat-project-progress` (which is read-only diagnostic).
 
-Full spec-driven design supports three interaction modes: collaborative, selective collaborative, and draft-and-review. Selective collaborative drafts routine sections silently and presents high-risk or uncertain sections for live review. Quick-start lightweight design stays simpler and offers only collaborative or draft-and-review. See [Design Modes](design-modes.md) for details.
+Full spec-driven design supports three interaction modes: collaborative, selective collaborative, and draft-and-review. Selective collaborative drafts routine sections silently and presents high-risk or uncertain sections for live review. Quick-start lightweight design stays simpler and offers only collaborative or draft-and-review. See [Design Modes](planning/design-modes.md) for details.
+
+For a one-page view of where people approve and what runs automatically in each mode, see [Approvals and Automation](../approvals-and-automation.md).
 
 ## Quick Look
 
@@ -126,7 +128,7 @@ On completion, OAT treats archive handling as an explicit closeout choice:
   pointer immediately, as does any completion that declines archive. An archive
   failure therefore leaves the pointer intact and the completion directly
   resumable. See
-  [Picking Up a Project](picking-up-projects.md#archive-contents) for the
+  [Picking Up a Project](execution/picking-up-projects.md#archive-contents) for the
   post-archive resume and its manual recovery path.
 - When archiving is disabled or declined, durable projects remain at their
   active path. Synced completion still finalizes and pushes the project ref,
@@ -144,7 +146,7 @@ On completion, OAT treats archive handling as an explicit closeout choice:
   valid terminal shapes. The active alias is inert: list omits it and pull/open
   reject it. Differing SHAs are a hard mismatch with recovery guidance.
 - 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.
-- 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.
+- 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`](../../reference/config-and-local-state.md) for the full precedence chain.
 - If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
 - 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.
 - `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.
@@ -225,6 +227,8 @@ This distinction matters during completion: `oat-project-complete` can skip the
 
 ### Auto-review at HiLL checkpoints
 
+When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter sets `oat_auto_review_at_hill_checkpoints`, completing a HiLL checkpoint automatically runs the extra lifecycle review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (low findings auto-converted to fix tasks, no user prompts). The preference is unset by default; interactive implementation asks with "no" suggested, while autonomous non-lite implementation forces it on. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks. This does not control Tier 1 per-phase `oat-reviewer` gates.
+
 ### Approval-aware post-implementation sequencing
 
 `workflow.postImplementSequence` can use the legacy string values or a structured
@@ -264,8 +268,6 @@ registers. Non-interactive completion skips this offer, so autonomous
 generation occurs only through an explicitly configured post-approval `retro`
 step.
 
-When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter sets `oat_auto_review_at_hill_checkpoints`, completing a HiLL checkpoint automatically runs the extra lifecycle review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (low findings auto-converted to fix tasks, no user prompts). Disabled by default. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks. This does not control Tier 1 per-phase `oat-reviewer` gates.
-
 ### Phase-review setup during planning
 
 Spec-driven, quick, and import planning run one shared setup after stable phase
@@ -302,7 +304,7 @@ Within either tier, parallelism is expressed as plan metadata:
 - **Sequential (default):** plans with no `oat_plan_parallel_groups` field, or with an empty array. Phases run in plan order on the orchestration branch.
 - **Parallel groups:** phases listed together in `oat_plan_parallel_groups` run concurrently in worktrees (Tier 1 only) and merge back to the orchestration branch in plan order. Groups themselves execute sequentially.
 
-See [Implementation Execution](implementation-execution.md) for the full execution model — tier detection, bounded fix loop, fan-in, merge-conflict handling, dry-run, and resumption.
+See [Implementation Execution](execution/implementation-execution.md) for the full execution model — tier detection, bounded fix loop, fan-in, merge-conflict handling, dry-run, and resumption.
 
 ## Review receive behavior
 
@@ -312,7 +314,7 @@ See [Implementation Execution](implementation-execution.md) for the full executi
 
 ## Alternate lifecycle lanes
 
-### Quick lane diagram
+### Quick lane steps
 
 1. `oat-project-quick-start` (adaptive discovery — provide a project name and optional description; if only the name is provided, quick-start asks for the missing description before discovery. Well-understood requests synthesize quickly, exploratory requests invest in solution space exploration. Before scaffolding, the skill checks inherited git state and asks whether to commit, proceed, or abort when the worktree is already dirty.)
 2. Decision point: straight to plan, optional lightweight `design.md`, or promote to spec-driven
@@ -320,14 +322,14 @@ See [Implementation Execution](implementation-execution.md) for the full executi
 4. `oat-project-review-provide` / `oat-project-pr-final`
 5. Optional `oat-project-promote-spec-driven` to backfill spec-driven lifecycle artifacts in-place
 
-### Lite lane diagram
+### Lite lane steps
 
 1. `oat-project-lite` runs one batched interview, authors a single-phase `plan.md` with validation criteria, and pauses once for approval
 2. Implement: `oat-project-implement` runs the single phase without HiLL checkpoint prompts
 3. Pass the mandatory final review, then route directly to `oat-project-pr-final`
 4. Optional `oat project promote <project-path> --to quick` when the work no longer fits one sitting
 
-### Import lane diagram
+### Import lane steps
 
 1. `oat-project-import-plan` (checks inherited git state before import scaffolding so sync-generated or unrelated dirty files do not silently roll into project bookkeeping)
 2. Implement: `oat-project-implement` (sequential by default; parallel when `oat_plan_parallel_groups` is declared)
@@ -513,7 +515,7 @@ Capture lane progression:
 
 The lifecycle has several interactive prompts that power users often answer the same way every time — HiLL checkpoint behavior, archive on complete, auto-create PR, post-implementation chaining, final review execution model, and re-review scope narrowing. These can be configured once via `workflow.*` preference keys and respected automatically by skills.
 
-See the [Workflow preferences section in the Configuration guide](../../cli-utilities/configuration.md#workflow-preferences-workflow) for the full list of keys and how to set them. Preferences resolve through a three-layer chain (`env > repo-local > repo-shared > user > default`), so you can set personal defaults at user scope once and override per-repo only when needed.
+See the [Workflow preferences section in the Configuration guide](../../reference/configuration.md#workflow-preferences-workflow) for the full list of keys and how to set them. Workflow preferences resolve through `repo-local > repo-shared > user > default`; there is no generic workflow environment layer. Individual skills may separately read environment controls such as `OAT_DESIGN_MODE`. Set personal defaults at user scope and override per-repo when needed.
 
 ## Active project resolution
 
@@ -538,7 +540,7 @@ separate checks, and both must hold before any PJM write:
 Pack presence is never treated as evidence of repository adoption. A skill that
 finds the capability available but the repository unadopted reports the
 actionable `oat pjm init` stop instead of scaffolding implicitly. See
-[Install vs. initialize](../../cli-utilities/tool-packs.md#install-vs-initialize).
+[Install vs. initialize](../../getting-started/tool-packs.md#install-vs-initialize).
 
 ## Brainstorming integration with the project lifecycle
 
@@ -566,3 +568,37 @@ The fold-back path is what makes "we got to plan and realized the design missed
 - `.oat/projects/<scope>/<project>/design.md`
 - `.oat/projects/<scope>/<project>/plan.md`
 - `.oat/projects/<scope>/<project>/implementation.md`
+
+## Choosing lifecycle controls
+
+OAT has four separate controls that are easy to confuse. Each one adds a
+different kind of check:
+
+- **Planning checkpoints** hold a spec-driven project after discovery and after
+  design until a person approves.
+- **Implementation checkpoints** (HiLL checkpoints) pause implementation after
+  chosen phases until a person approves.
+- **Artifact review loops** have the same agent session check a generated plan
+  or analysis and fix clear problems before handing it on.
+- **Gates** send the work to a second agent CLI, preferably running a different
+  family of models, and turn its findings into a pass or a fail.
+
+None of these replaces the code reviews that run after every implementation
+phase and before closeout; those run whatever you choose here.
+
+Decide in this order: first the
+[workflow mode](../choose-workflow.md#which-mode-should-i-choose), then the
+[design interaction mode](planning/design-modes.md#choosing-an-interaction-mode),
+then the [checkpoint frequency](planning/hill-checkpoints.md#choosing-checkpoint-frequency).
+
+- If your team needs to approve the architecture before any code is written,
+  choose a spec-driven project for its planning checkpoints, or add a gate to a
+  planning skill.
+- If you want to steer implementation after risky phases, choose
+  implementation checkpoints for those phases.
+- If a plan or analysis will be handed to another workflow, keep its artifact
+  review loop on.
+- If a high-risk change needs a reviewer from a different model family, add a
+  [gate](../advanced/workflow-gates.md#choosing-gate-posture) and check which
+  reviewer it actually used. Adding more reviews makes a run slower; it does not
+  by itself make them independent.