@open-agent-toolkit/cli 0.0.26 → 0.0.28

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

@@ -52,6 +52,24 @@ What each command is for:
 - `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.
 
+### Source labels
+
+`oat config get --json` and `oat config list` emit a `source` field identifying which config surface a resolved value came from. The current labels are:
+
+| Label     | Meaning                                                                            |
+| --------- | ---------------------------------------------------------------------------------- |
+| `env`     | Value came from an environment variable override (e.g. `OAT_PROJECTS_ROOT`)        |
+| `local`   | Value came from `.oat/config.local.json` (per-developer repo state)                |
+| `shared`  | Value came from `.oat/config.json` (team-shared repo settings)                     |
+| `user`    | Value came from `~/.oat/config.json` (user-level fallback)                         |
+| `default` | No surface set the key; value is the CLI's built-in default (or `null` when unset) |
+
+These labels match what `oat config dump` emits, so tooling that consumes either command can rely on the same vocabulary.
+
+:::note Upgrade note
+Earlier CLI versions returned `config.json` / `config.local.json` / `env` / `default` as the `source` strings. External scripts that previously matched on `"source":"config.json"` or `"source":"config.local.json"` should update to match the new `shared` / `local` labels. This change was made to align the `oat config get` / `oat config list` output with `oat config dump` and to avoid confusing users about which file was consulted.
+:::
+
 ## Shared repo config you will touch most often
 
 Common keys in `.oat/config.json`:
@@ -110,6 +128,96 @@ oat config get lastPausedProject
 oat config describe activeIdea
 ```
 
+## Workflow preferences (`workflow.*`)
+
+Workflow preferences let power users answer repetitive confirmation prompts once and have OAT workflow skills respect those answers automatically. They are the highest-value escape hatch from interactive friction when you always make the same choices.
+
+### Preference keys
+
+All six workflow preference keys live under the `workflow.*` namespace:
+
+- `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement`: pause after every phase or only after the last phase. When unset, the skill prompts.
+- `workflow.archiveOnComplete` — boolean. Skip the "Archive after completion?" prompt in `oat-project-complete`. When unset, the skill prompts.
+- `workflow.createPrOnComplete` — boolean. Skip the "Open a PR?" prompt in `oat-project-complete`; when true, completion auto-triggers PR creation. When unset, the skill prompts.
+- `workflow.postImplementSequence` — `wait`, `summary`, `pr`, or `docs-pr`. Controls what `oat-project-implement` chains after final review passes. `wait` stops without auto-chaining, `summary` runs only `oat-project-summary`, `pr` runs `oat-project-pr-final` (which auto-generates summary), `docs-pr` runs `oat-project-document` then `oat-project-pr-final`. When unset, the skill prompts.
+- `workflow.reviewExecutionModel` — `subagent`, `inline`, or `fresh-session`. Default final-review execution model in `oat-project-implement`. `subagent` and `inline` run automatically. `fresh-session` is a soft preference: the skill prints guidance to run the review in another session but still offers escape hatches to `subagent` or `inline` if you change your mind. When unset, the skill prompts.
+- `workflow.autoNarrowReReviewScope` — boolean. Auto-narrow re-review scope to fix-task commits only in `oat-project-review-provide`. When unset, the skill prompts.
+
+### Three-layer resolution
+
+Workflow preferences resolve through three config surfaces, with `env > local > shared > user > default` precedence per key. This is the same generic resolution used by `oat config dump`:
+
+- **User-level** (`~/.oat/config.json`): personal defaults that apply to every repo. This is where most power users should start — set preferences once, never worry about them again.
+- **Shared repo** (`.oat/config.json`): team decisions for this repo. Overrides user defaults when present.
+- **Repo-local** (`.oat/config.local.json`): personal override for this specific repo. Highest precedence per key.
+
+### Setting preferences
+
+`oat config set` supports mutually exclusive surface flags for workflow keys:
+
+```bash
+# User-level: applies to all repos on this machine
+oat config set workflow.hillCheckpointDefault final --user
+oat config set workflow.archiveOnComplete true --user
+oat config set workflow.createPrOnComplete true --user
+oat config set workflow.postImplementSequence pr --user
+oat config set workflow.reviewExecutionModel subagent --user
+oat config set workflow.autoNarrowReReviewScope true --user
+
+# Shared repo: team decision for this repo
+oat config set workflow.createPrOnComplete false --shared
+
+# Repo-local: personal override for this repo (default when no flag)
+oat config set workflow.hillCheckpointDefault every
+```
+
+Default (no flag) targets `.oat/config.local.json` for workflow keys. Pass at most one of `--user`, `--shared`, or `--local`. Structural keys (`projects.root`, `worktrees.root`, `git.*`, `documentation.*`, `archive.*`, `tools.*`) are still shared-only regardless of flag.
+
+### Choosing the right surface (personal vs per-repo)
+
+Not every workflow preference belongs at user level, even though "set once, applies everywhere" is tempting. The guiding principle:
+
+> **If a workflow preference's correctness depends on other repo-level settings, it belongs at shared (per-repo) level, not user level.**
+
+Some preferences are **genuinely personal** — their correct value is the same for you regardless of which repo you're in. These are safe to set at `--user`:
+
+- `workflow.hillCheckpointDefault` — your personal tolerance for mid-implementation interruption
+- `workflow.reviewExecutionModel` — depends on your provider environment (Claude Code, Cursor, Codex), not the repo
+- `workflow.autoNarrowReReviewScope` — pure personal workflow preference, no per-repo interaction
+
+Other preferences **depend on per-repo configuration** to be safe. These should be set at `--shared` (in each repo where they apply), not `--user`:
+
+- `workflow.archiveOnComplete` — correctness depends on the repo's `archive.s3Uri` / `archive.s3SyncOnComplete` being configured. A user-level `true` would try to archive in repos that aren't set up for it.
+- `workflow.postImplementSequence` — correctness depends on `documentation.requireForProjectCompletion`. Setting `pr` at user level would foot-gun you in any repo that requires docs, because completion would later block on the docs gate while the PR is already open.
+- `workflow.createPrOnComplete` — this key is almost always redundant with `postImplementSequence`-driven flows. When it's meaningful, its correctness depends on the same per-repo docs and PR gates. Prefer shared scope, or omit it entirely and rely on `postImplementSequence: pr` or `docs-pr` to handle PR creation at the end of implement.
+
+**Cross-repo foot-gun example:** If you set `workflow.createPrOnComplete: true --user`, it applies to every repo you work on. In a repo with `documentation.requireForProjectCompletion: true` and `postImplementSequence: pr` (no docs step), running `oat-project-complete` would try to auto-create a PR, then immediately hit the docs gate and block you — leaving you with an open PR and a stuck completion. Your user-level preference silently asserted something that only holds in a specific shared-config shape.
+
+**Recommended split for most users:**
+
+```bash
+# Personal defaults (apply everywhere)
+oat config set workflow.hillCheckpointDefault final --user
+oat config set workflow.reviewExecutionModel subagent --user
+oat config set workflow.autoNarrowReReviewScope true --user
+
+# Per-repo team decisions (set in each repo where they apply)
+oat config set workflow.archiveOnComplete true --shared
+oat config set workflow.postImplementSequence docs-pr --shared  # or "pr" if docs aren't required
+```
+
+If you want to override a shared team decision for this specific checkout, use `--local`:
+
+```bash
+oat config set workflow.archiveOnComplete false --local  # "I don't want to archive on this specific branch checkout"
+```
+
+### Relationship to `autoReviewAtCheckpoints`
+
+The existing `autoReviewAtCheckpoints` key (top-level in `.oat/config.json`) was **not** migrated under the `workflow.*` namespace to preserve backward compatibility. It remains shared-scope-only and controls whether `oat-project-implement` auto-triggers code reviews at plan phase checkpoints. That is a separate behavioral toggle from the workflow preferences above — it affects when reviews happen, not which prompt-skipping defaults apply.
+
+If you enable both, you get a near-uninterrupted lifecycle: auto-review runs at checkpoints, fix tasks are converted automatically, and the workflow preferences skip every remaining confirmation prompt.
+
 ## Provider sync config is different
 
 Provider sync settings are intentionally documented in the same discovery flow, but they are not owned by `oat config set`.

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

@@ -39,3 +39,28 @@ Notable inspection commands introduced in the current CLI surface:
 - `oat config dump --json` - merged config with source attribution
 - `oat project status --json` - full parsed state for the active tracked project
 - `oat project list --json` - summary state for tracked projects under the configured projects root
+
+## `oat config` surface flags
+
+`oat config set` supports mutually exclusive surface flags that control which config file receives the write:
+
+- `--shared` — write to `.oat/config.json` (committed team repo settings)
+- `--local` — write to `.oat/config.local.json` (per-developer repo state, gitignored)
+- `--user` — write to `~/.oat/config.json` (user-level fallback, applies across all repos)
+
+When no flag is passed, the CLI picks a sensible default per key type: structural keys (`projects.root`, `documentation.*`, etc.) go to shared, state keys (`activeProject`, etc.) go to local, workflow preferences (`workflow.*`) go to local. Pass at most one flag — the command rejects multiple surface flags.
+
+Per-key restrictions apply: structural keys can only be written at shared scope, most state keys can only be written at local scope (`activeIdea` is the exception — it accepts both local and user), and `autoReviewAtCheckpoints` remains shared-only. Workflow preference keys accept any non-auto surface.
+
+## `workflow.*` preference keys
+
+The `workflow.*` namespace holds user-facing workflow preferences that let you answer repetitive confirmation prompts once and have OAT skills respect the answer automatically. Six keys:
+
+- `workflow.hillCheckpointDefault` (`every` | `final`) — default HiLL checkpoint behavior in `oat-project-implement`
+- `workflow.archiveOnComplete` (`boolean`) — skip the archive prompt in `oat-project-complete`
+- `workflow.createPrOnComplete` (`boolean`) — skip the "Open a PR?" prompt in `oat-project-complete`
+- `workflow.postImplementSequence` (`wait` | `summary` | `pr` | `docs-pr`) — post-implementation chaining behavior
+- `workflow.reviewExecutionModel` (`subagent` | `inline` | `fresh-session`) — default final-review execution model
+- `workflow.autoNarrowReReviewScope` (`boolean`) — auto-narrow re-review scope to fix-task commits
+
+All six keys resolve through the 3-layer precedence chain (`env > local > shared > user > default`). See [Workflow preferences in the Configuration guide](../cli-utilities/configuration.md#workflow-preferences-workflow) for full descriptions, surface guidance, and cross-repo foot-gun examples.

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

@@ -46,6 +46,23 @@ It then writes the confirmed value into `plan.md`. If the field is later missing
 
 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`

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

@@ -199,6 +199,12 @@ Capture lane progression:
 - Stop at configured HiLL checkpoints.
 - Do not move lifecycle forward when required review gates are unresolved.
 
+## Reducing lifecycle friction with workflow preferences
+
+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.
+
 ## Active project resolution
 
 - Active project state is stored in `.oat/config.local.json` (`activeProject`, repo-relative path).

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

@@ -19,6 +19,12 @@ Review loop:
 - `reviews/archived/` is the local-only historical surface. Active `reviews/` content is not gitignored by default.
 - Ad-hoc review artifacts still default to local-only orphan storage under `.oat/projects/local/orphan-reviews/`.
 
+## Bookkeeping commits (required)
+
+Both `oat-project-review-receive` and `oat-project-review-receive-remote` conclude with a required atomic commit of `plan.md`, `implementation.md`, `state.md`, and the archived review artifact (when tracked). This is the safety net that prevents cross-agent bookkeeping drift: when a subagent runs a receive skill in isolation, the commit ensures the original agent sees a clean checkout on return.
+
+The commit is scoped and explicit — it stages only the project's tracking files and the project's `reviews/` directory. It never uses `git add -A` or repo-wide glob patterns. Deferring this commit requires explicit user approval and must be recorded in the receive skill's summary so the original agent knows state is uncommitted.
+
 ## Project vs ad-hoc
 
 **Provide** (request a review):
@@ -58,6 +64,24 @@ Auto-triggered reviews use `oat_review_invocation: auto` in the review artifact
 
 This feature is opt-in and disabled by default. When disabled, the manual `oat-project-review-provide` workflow applies.
 
+## Re-review scope narrowing
+
+When re-reviewing after fix tasks have been applied, `oat-project-review-provide` detects completed `(review)` fix tasks and offers to narrow the re-review scope to just the fix-task commits. This avoids re-examining already-approved code.
+
+The behavior can be set as a default via `workflow.autoNarrowReReviewScope`:
+
+- `true` — automatically narrow to fix commits, no prompt
+- `false` — always use the full scope, no prompt
+- unset (default) — prompt the user on each re-review
+
+Typically set at user scope since it's a personal workflow preference:
+
+```bash
+oat config set workflow.autoNarrowReReviewScope true --user
+```
+
+The preference only applies when there are completed fix tasks to narrow to. Initial reviews (before any fix tasks exist) always use the full scope regardless of the preference. See [Workflow preferences in the Configuration guide](../../cli-utilities/configuration.md#workflow-preferences-workflow) for the full list of preference keys.
+
 ## Phase and final review
 
 Use phase-scoped review artifacts during implementation (`p01`, `p02`, etc), then run final review before project closeout.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.26",
-  "docs-config": "0.0.26",
-  "docs-theme": "0.0.26",
-  "docs-transforms": "0.0.26"
+  "cli": "0.0.28",
+  "docs-config": "0.0.28",
+  "docs-theme": "0.0.28",
+  "docs-transforms": "0.0.28"
 }

package/assets/skills/oat-project-complete/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.3.7
+version: 1.4.0
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -64,6 +64,25 @@ Ask all user questions at once so the user can answer them in a single interacti
 
 Before asking the batched questions, read `oat_pr_status` and `oat_pr_url` from `state.md` frontmatter.
 
+**Workflow preference checks (before asking questions):**
+
+Some questions can be answered automatically from workflow preferences. Read each preference before deciding whether to include its question in the batched prompt:
+
+```bash
+ARCHIVE_PREF=$(oat config get workflow.archiveOnComplete 2>/dev/null || true)
+PR_ON_COMPLETE=$(oat config get workflow.createPrOnComplete 2>/dev/null || true)
+```
+
+- **If `ARCHIVE_PREF` is `true`:** Set `SHOULD_ARCHIVE="true"`. Skip the archive question. Print `Archive on complete: enabled (from workflow.archiveOnComplete).`
+- **If `ARCHIVE_PREF` is `false`:** Set `SHOULD_ARCHIVE="false"`. Skip the archive question. Print `Archive on complete: disabled (from workflow.archiveOnComplete).`
+- **If unset:** Include the archive question in the batched prompt as normal (backward compatible).
+- **If `PR_ON_COMPLETE` is `true` AND no tracked open PR exists:** Set `SHOULD_OPEN_PR="true"`. Skip the Open PR question. Print `PR on complete: enabled (from workflow.createPrOnComplete).`
+- **If `PR_ON_COMPLETE` is `false`:** Set `SHOULD_OPEN_PR="false"`. Skip the Open PR question. Print `PR on complete: disabled (from workflow.createPrOnComplete).`
+- **If `PR_ON_COMPLETE` is unset:** Include the Open PR question in the batched prompt as normal (backward compatible).
+- The existing tracked-PR skip still applies: if `oat_pr_status` is `open`, do not ask the Open PR question and do not honor `PR_ON_COMPLETE=true` — the PR already exists.
+
+The "Ready to mark complete?" confirmation is always asked — it is a meaningful "are you sure" moment, not a preference.
+
 Also preflight summary status using the same freshness rules as `oat-project-summary`:
 
 - `summary.md` is `missing` when `{PROJECT_PATH}/summary.md` does not exist

package/assets/skills/oat-project-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 1.2.2
+version: 1.3.0
 description: Use when plan.md is ready for execution. Implements plan tasks sequentially with TDD discipline and state tracking.
 disable-model-invocation: true
 user-invocable: true
@@ -21,6 +21,9 @@ Execute the implementation plan task-by-task with full state tracking.
 
 **Purpose:** Execute plan tasks with TDD discipline, track progress, handle blockers.
 
+**CRITICAL — Bookkeeping commits are mandatory, not optional.**
+After every code commit and after every phase/review-fix completion, you MUST commit the OAT tracking files (`implementation.md`, `state.md`, `plan.md`) as a separate bookkeeping commit. Do not defer, batch, or skip these commits under the reasoning that they "aren't related to the implementation." Skipping a bookkeeping commit is the primary cause of cross-session state drift and will cause the next implementation run to fail bookkeeping cross-checks. If bookkeeping commits feel frequent, that is the intended design — they are cheap and they prevent drift.
+
 ## Progress Indicators (User-Facing)
 
 When executing this skill, provide lightweight progress feedback so the user can tell what’s happening after they confirm.
@@ -140,6 +143,20 @@ Determine whether this is a first implementation run:
 - If `"$PROJECT_PATH/implementation.md"` does not exist, treat as first run.
 - If it exists but still has template placeholders and no completed task evidence, treat as first run.
 
+#### Workflow preference check (before prompting)
+
+Before presenting the checkpoint prompt to the user, check if a workflow preference has been configured:
+
+```bash
+HILL_DEFAULT=$(oat config get workflow.hillCheckpointDefault 2>/dev/null || true)
+```
+
+- **If `HILL_DEFAULT` is `every`:** Skip the prompt. Write `oat_plan_hill_phases: []` to plan.md frontmatter. Print: `HiLL checkpoints: every phase (from workflow.hillCheckpointDefault)`. Continue to Touchpoint A.
+- **If `HILL_DEFAULT` is `final`:** Skip the prompt. Determine the final phase ID from plan.md (e.g., `p05`) and write `oat_plan_hill_phases: ["<final_phase_id>"]` to plan.md frontmatter. Print: `HiLL checkpoints: final phase only (from workflow.hillCheckpointDefault)`. Continue to Touchpoint A.
+- **If unset, empty, or invalid:** Fall through to the standard prompt behavior below.
+
+This preference check only applies on first runs — resuming implementations should trust the existing `oat_plan_hill_phases` value in plan.md (or repair as bookkeeping drift).
+
 Prompt behavior:
 
 - **If first run:** always present a complete phase-by-phase summary and confirm checkpoint phases before any task execution. A missing `oat_plan_hill_phases` value is the normal unconfirmed state; if a value is already present, treat it as a provisional value to confirm rather than as final.
@@ -202,8 +219,8 @@ cat "$PROJECT_PATH/implementation.md" 2>/dev/null | head -20
 - Validate the task pointer:
   - If `oat_current_task_id` points at a task already marked `completed` in the body, advance to the **next incomplete** task (first `pending` / `in_progress` / `blocked` entry).
   - If all tasks are completed, skip ahead to finalization (Step 11+).
-- Resume from the resolved task
-- Ask user: "Resume from {task_id}, or start fresh (overwrite implementation.md)?"
+- **Always resume** from the resolved task. Print `Resuming from {task_id}.` Do not prompt.
+- **Fresh start is an explicit override only.** If the user invoked the skill with `fresh=true` (argument), warn `Starting fresh — this will overwrite implementation.md. Any draft logs will be lost.` and proceed with fresh initialization. Do not offer fresh start interactively; it is a rare edge case reserved for corrupt state or deliberate plan rewrites.
 
 **Stale-state reconciliation (approval required):**
 
@@ -339,6 +356,9 @@ Keep project state in sync after each task (recommended source of truth for “w
   - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
 
 **Bookkeeping commit (required):**
+
+**DO NOT SKIP.** This commit prevents state drift across sessions.
+
 After the code commit (Step 6) and state updates above, commit all modified OAT tracking files:
 
 ```bash
@@ -376,6 +396,9 @@ Do not use `git add -A` or glob patterns. Only commit the three OAT project file
      - `oat_project_state_updated: “{ISO 8601 UTC timestamp}”`
 
   **Bookkeeping commit (required):**
+
+  **DO NOT SKIP.** This commit prevents state drift across sessions.
+
   After completing the review-fix checklist above, commit all modified OAT tracking files:
 
   ```bash
@@ -449,6 +472,9 @@ When pausing:
   - Notable decisions/deviations
 
 **Bookkeeping commit (required):**
+
+**DO NOT SKIP.** This commit prevents state drift across sessions.
+
 After phase summary and task pointer advancement, commit all modified OAT tracking files:
 
 ```bash
@@ -579,6 +605,9 @@ Implementation - Tasks complete; awaiting final review.
 ```
 
 **Bookkeeping commit (required):**
+
+**DO NOT SKIP.** This commit prevents state drift across sessions.
+
 After updating state.md to reflect implementation completion, commit all modified OAT tracking files:
 
 ```bash
@@ -632,7 +661,43 @@ echo "$FINAL_ROW"
 **If final review is not marked `passed`:**
 
 - Tell user: "All tasks complete. Final review required before PR."
-- Offer review options (3-tier capability model):
+
+**Workflow preference check (before prompting):**
+
+```bash
+REVIEW_MODEL=$(oat config get workflow.reviewExecutionModel 2>/dev/null || true)
+```
+
+- **If `REVIEW_MODEL` is `subagent`:** Print `Review execution: subagent (from workflow.reviewExecutionModel).` Dispatch the review subagent directly via the Task tool. No prompt.
+- **If `REVIEW_MODEL` is `inline`:** Print `Review execution: inline (from workflow.reviewExecutionModel).` Run the review in-context per `oat-project-review-provide` skill. No prompt.
+- **If `REVIEW_MODEL` is `fresh-session`:** This is a **soft preference with escape hatch** because the agent cannot run the review in a fresh session on the user's behalf. Print the guidance block below, then handle the user's response per the three outcomes listed after it.
+- **If unset or invalid:** Fall through to the standard 3-tier prompt below.
+
+**Fresh-session guidance block (print when `REVIEW_MODEL` is `fresh-session`):**
+
+```
+Per your config (workflow.reviewExecutionModel: fresh-session), your
+preference is to run the review in a fresh session.
+
+Run `oat-project-review-provide code final` in a separate session, then
+resume this session when the review is complete.
+
+If you'd like to review here instead:
+  1) subagent
+  2) inline
+
+Enter 1 or 2 to run the review here, or press Enter to wait.
+```
+
+**Fresh-session response outcomes:**
+
+- User enters `1` → dispatch the subagent review (same behavior as `REVIEW_MODEL=subagent`).
+- User enters `2` → run the review inline (same behavior as `REVIEW_MODEL=inline`).
+- User presses Enter (or equivalent no-input confirmation) → pause the session and wait for the fresh-session review to complete before continuing.
+
+**Standard prompt (when preference is unset):**
+
+Offer review options (3-tier capability model):
 
 ```
 Implementation complete. Final review required.
@@ -673,6 +738,22 @@ To run in a separate session use: oat-project-review-provide code final
 
 After final review passes (no Critical/Important findings):
 
+**Workflow preference check (before prompting):**
+
+```bash
+POST_IMPL=$(oat config get workflow.postImplementSequence 2>/dev/null || true)
+```
+
+- **If `POST_IMPL` is `wait`:** Print `Post-implementation: wait (from workflow.postImplementSequence). Run follow-up skills manually when ready.` Exit without auto-chaining.
+- **If `POST_IMPL` is `summary`:** Print `Post-implementation: summary (from workflow.postImplementSequence).` Invoke `oat-project-summary`. Stop after summary completes.
+- **If `POST_IMPL` is `pr`:** Print `Post-implementation: pr (from workflow.postImplementSequence).` Invoke `oat-project-pr-final` (which auto-generates `summary.md` as part of its flow).
+- **If `POST_IMPL` is `docs-pr`:** Print `Post-implementation: docs-pr (from workflow.postImplementSequence).` Invoke `oat-project-document` then `oat-project-pr-final` (summary included via pr-final).
+- **If unset or invalid:** Fall through to the standard prompt below.
+
+**Rationale:** `oat-project-pr-final` already auto-generates/refreshes `summary.md` as part of its flow, so `pr` and `docs-pr` do not need a separate summary step. The `summary` value exists as a standalone option for the rare case where you want just the summary without PR.
+
+**Standard prompt (when preference is unset):**
+
 ```
 Final review passed for {project-name}.
 

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide
-version: 1.2.3
+version: 1.3.0
 description: Use when completed work in an active OAT project needs a quality gate before merge. Performs a lifecycle-scoped review after a task, phase, or full implementation, unlike oat-review-provide.
 disable-model-invocation: true
 user-invocable: true
@@ -264,7 +264,17 @@ Before resolving scope, check if this is a re-review of fixes from a prior revie
 
 1. Scan `plan.md` for tasks tagged with `(review)` in the scope being reviewed (e.g., `(p02-review)` fix tasks for a `p02` phase review or `(p02-p03-review)` for a contiguous phase-range review).
 2. If `(review)` fix tasks exist **and** their status is `completed`:
-   - This is a re-review. Offer the user a narrowed scope:
+   - This is a re-review. Before prompting, check the workflow preference:
+
+     ```bash
+     AUTO_NARROW=$(oat config get workflow.autoNarrowReReviewScope 2>/dev/null || true)
+     ```
+
+     - **If `AUTO_NARROW` is `true`:** Auto-narrow. Print `Re-review scope: narrowed to fix commits (from workflow.autoNarrowReReviewScope).` Gather only the commits for completed `(review)` fix tasks (see below). Skip the prompt.
+     - **If `AUTO_NARROW` is `false`:** Use full scope. Print `Re-review scope: full (from workflow.autoNarrowReReviewScope).` Skip the prompt and proceed with full scope resolution below.
+     - **If unset:** Fall through to the standard prompt.
+
+   - Standard prompt (when preference is unset):
 
      ```
      Detected completed review fix tasks for this scope:

package/assets/skills/oat-project-review-receive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-receive
-version: 1.2.1
+version: 1.3.0
 description: Use when review findings from oat-project-review-provide need closure. Converts review artifacts into actionable plan tasks.
 disable-model-invocation: true
 user-invocable: true
@@ -418,6 +418,27 @@ Rules:
 - If `"$ARCHIVED_REVIEW_PATH"` already exists, append a timestamp suffix before moving so history is preserved.
 - Report the archived location in the final summary.
 
+### Step 7.6: Commit Review Bookkeeping (Required)
+
+**CRITICAL — DO NOT SKIP.** When this skill runs in a separate agent session (subagent, fresh session, or different conversation), uncommitted bookkeeping updates cause state drift for the original agent. This skill modifies `plan.md`, `implementation.md`, `state.md`, and the contents of `reviews/` (via the Step 7.5 archive move) but does not commit them on its own — the commit below is the safety net.
+
+Commit all modified OAT tracking files atomically:
+
+```bash
+git add "$PROJECT_PATH/plan.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md"
+# Capture the Step 7.5 archive move: stages both the deletion of the original
+# review path and the new archived location. Scope to the project's reviews/
+# directory — never use repo-wide `git add -A`.
+git add "$PROJECT_PATH/reviews/"
+git diff --cached --quiet || git commit -m "chore(oat): record review findings and add fix tasks ({scope})"
+```
+
+Do not use `git add -A` or glob patterns that reach outside `"$PROJECT_PATH/reviews/"`. Do not include unrelated implementation or code files in this commit. Do not defer this commit without explicit user approval — if deferred, clearly state in the summary that bookkeeping is uncommitted so the original agent knows to commit on return.
+
+**Note on archived review paths:** When `reviews/archived/` matches a `localPaths` pattern (the default setup), the archived file is gitignored and `git add "$PROJECT_PATH/reviews/"` will only stage the deletion of the original (now-moved) top-level review file. When `reviews/archived/` is tracked, both the deletion and the new archived location are staged. Both cases are safe — the command handles them uniformly.
+
+**Worktree handling:** If the project was resolved via a worktree in Step 0, run the git commands scoped to the worktree (`git -C "$WORKTREE_PATH" ...`) so the commit lands on the worktree branch.
+
 ### Step 8: Check Review Cycle Count
 
 **Bounded loop protection:**
@@ -632,6 +653,7 @@ This prevents reviewing already-approved code and focuses the reviewer on just t
 - Plan.md updated with new tasks
 - Implementation.md updated with review notes
 - Consumed review artifact archived under `reviews/archived/`
+- All artifact updates (plan.md, implementation.md, state.md) committed atomically before the skill exits to prevent cross-session drift
 - Review cycle count checked (cap at 3)
 - Final-scope deferred Medium findings resurfaced and explicitly dispositioned
 - User routed to next action

package/assets/skills/oat-project-review-receive-remote/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-receive-remote
-version: 1.2.0
+version: 1.3.0
 description: Use when processing GitHub PR review comments within project context. Fetches PR comments, creates plan tasks, and updates project artifacts.
 disable-model-invocation: true
 user-invocable: true
@@ -190,6 +190,21 @@ Update `state.md`:
 - `oat_current_task: <first-new-task-id|null>`
 - `oat_project_state_updated: "{ISO 8601 UTC timestamp}"`
 
+### Step 6.5: Commit Review Bookkeeping (Required)
+
+**CRITICAL — DO NOT SKIP.** This skill modifies `plan.md`, `implementation.md`, and `state.md` when processing GitHub PR comments. When it runs in a separate agent session (subagent, fresh session, or different conversation), uncommitted bookkeeping updates cause state drift for the original agent. The commit below is the safety net.
+
+Commit all modified OAT tracking files atomically:
+
+```bash
+git add "$PROJECT_PATH/plan.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md"
+git diff --cached --quiet || git commit -m "chore(oat): record remote review findings and add fix tasks (pr-#$PR_NUMBER)"
+```
+
+Do not use `git add -A` or glob patterns. Do not include unrelated implementation or code files. Do not defer this commit without explicit user approval.
+
+**Worktree handling:** If the project was resolved via a worktree in Step 0, run the git commands scoped to the worktree (`git -C "$WORKTREE_PATH" ...`) so the commit lands on the worktree branch.
+
 ### Step 7: Enforce Review Cycle Limit and Route Next Action
 
 Track review cycles for the same scope.
@@ -232,4 +247,5 @@ At completion, report:
 - Findings triaged with explicit dispositions.
 - Plan tasks created with stable IDs when needed.
 - `plan.md`, `implementation.md`, and `state.md` updated consistently.
+- All artifact updates committed atomically before the skill exits to prevent cross-session drift.
 - Review cycle guard and next-action routing applied.

package/dist/commands/config/index.d.ts

@@ -1,5 +1,6 @@
 import { buildCommandContext, type CommandContext } from '../../app/command-context.js';
-import { type OatConfig, type OatLocalConfig } from '../../config/oat-config.js';
+import { type OatConfig, type OatLocalConfig, type UserConfig } from '../../config/oat-config.js';
+import { type ResolvedConfig } from '../../config/resolve.js';
 import { Command } from 'commander';
 interface ConfigCommandDependencies {
     buildCommandContext: (options: Parameters<typeof buildCommandContext>[0]) => CommandContext;
@@ -8,7 +9,10 @@ interface ConfigCommandDependencies {
     writeOatConfig: (repoRoot: string, config: OatConfig) => Promise<void>;
     readOatLocalConfig: (repoRoot: string) => Promise<OatLocalConfig>;
     writeOatLocalConfig: (repoRoot: string, config: OatLocalConfig) => Promise<void>;
+    readUserConfig: (userConfigDir: string) => Promise<UserConfig>;
+    writeUserConfig: (userConfigDir: string, config: UserConfig) => Promise<void>;
     resolveProjectsRoot: (repoRoot: string, env: NodeJS.ProcessEnv) => Promise<string>;
+    resolveEffectiveConfig: (repoRoot: string, userConfigDir: string, env: NodeJS.ProcessEnv) => Promise<ResolvedConfig>;
     processEnv: NodeJS.ProcessEnv;
 }
 export declare function createConfigCommand(overrides?: Partial<ConfigCommandDependencies>): Command;

package/dist/commands/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAMpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6CpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAk3BD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAwET"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAOhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmDpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AA0hCD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CA0GT"}