@open-agent-toolkit/cli 0.3.19 → 0.3.21

package/assets/docs/workflows/approvals-and-automation.md

@@ -15,15 +15,16 @@ to the detail.
 A HiLL (human-in-the-loop lifecycle) checkpoint is a point where the agent
 stops and waits for a person to approve before it continues.
 
-| Mode           | A person approves before code is written                                                                                                                                                   | Pauses during implementation                                                       | Reviews that run automatically                         | At the end                                                                   | Never                  |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- | ---------------------- |
-| No project     | You direct each step yourself                                                                                                                                                              | None                                                                               | None; run `oat-review-provide` when you want a review  | OAT opens no pull request                                                    | Not applicable         |
-| Lite           | Once: the requirements and the single-phase plan                                                                                                                                           | None                                                                               | Plan review, phase review, final review                | Opens a pull request by itself; no setting removes this step                 | Merges a pull request  |
-| Brief          | Once: the reviewed Project Brief, after you have agreed its design in the interview                                                                                                        | None by default; a pause happens only for a phase listed in `oat_plan_hill_phases` | Brief review, a review after every phase, final review | Same as quick                                                                | Merges a pull request  |
-| Quick          | You confirm the requirements (or the lightweight design). No plan-approval prompt: the plan is marked ready after an automatic review                                                      | First run lists the phases and asks where to stop; suggested: after every phase    | Plan review, a review after every phase, final review  | Opens a pull request by itself only if `workflow.postImplementSequence` asks | Merges a pull request  |
-| Spec-driven    | Discovery, then the requirements and design. Planning asks you in chat to confirm the task breakdown, but no plan approval is recorded; the plan is marked ready after an automatic review | Same as quick                                                                      | Same as quick                                          | Same as quick                                                                | Merges a pull request  |
-| Imported plan  | No approval step; OAT normalizes your plan and reviews it automatically                                                                                                                    | Same as quick                                                                      | Same as quick                                          | Same as quick                                                                | Merges a pull request  |
-| Autonomous run | None; it answers its own questions and stops only at defined boundaries                                                                                                                    | None; it approves the final checkpoint itself after a passing final review         | All of the above, plus a review at every checkpoint    | Opens a pull request by default                                              | Merges or force-pushes |
+| Mode           | A person approves before code is written                                                                                                                                                   | Pauses during implementation                                                                         | Reviews that run automatically                                               | At the end                                                                                                                                     | Never                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| No project     | You direct each step yourself                                                                                                                                                              | None                                                                                                 | None; run `oat-review-provide` when you want a review                        | OAT opens no pull request                                                                                                                      | Not applicable         |
+| Lite           | Once: the requirements and the single-phase plan                                                                                                                                           | None                                                                                                 | Plan review, phase review, final review                                      | Opens a pull request by itself; no setting removes this step                                                                                   | Merges a pull request  |
+| Brief          | Once: the reviewed Project Brief, after you have agreed its design in the interview                                                                                                        | None by default; a pause happens only for a phase listed in `oat_plan_hill_phases`                   | Brief review, a review after every phase, final review                       | Same as quick                                                                                                                                  | Merges a pull request  |
+| Goal           | The reviewed Project Brief with its milestone split, then each later milestone's amendment, and finally your declaration that the goal is met                                              | None by default inside a milestone; the agent stops at each re-alignment and waits for your approval | Brief review, a review after every phase, an integrated review per milestone | Each milestone opens its own pull request when `oat-project-pr-progress` delivers it; completion opens none when the deliveries cover the work | Merges a pull request  |
+| Quick          | You confirm the requirements (or the lightweight design). No plan-approval prompt: the plan is marked ready after an automatic review                                                      | First run lists the phases and asks where to stop; suggested: after every phase                      | Plan review, a review after every phase, final review                        | Opens a pull request by itself only if `workflow.postImplementSequence` asks                                                                   | Merges a pull request  |
+| Spec-driven    | Discovery, then the requirements and design. Planning asks you in chat to confirm the task breakdown, but no plan approval is recorded; the plan is marked ready after an automatic review | Same as quick                                                                                        | Same as quick                                                                | Same as quick                                                                                                                                  | Merges a pull request  |
+| Imported plan  | No approval step; OAT normalizes your plan and reviews it automatically                                                                                                                    | Same as quick                                                                                        | Same as quick                                                                | Same as quick                                                                                                                                  | Merges a pull request  |
+| Autonomous run | None; it answers its own questions and stops only at defined boundaries                                                                                                                    | None; it approves the final checkpoint itself after a passing final review                           | All of the above, plus a review at every checkpoint                          | Opens a pull request by default                                                                                                                | Merges or force-pushes |
 
 Phase reviews need no person. The final review always runs, but an interactive
 run first asks how to run it unless `workflow.reviewExecutionModel` is set. If
@@ -51,6 +52,12 @@ What does and does not give a person a say on the plan:
   interview reaches explicit design alignment first, so approval confirms a
   design you already agreed to; the artifact review and any configured
   `oat-project-brief` gate run on the committed brief before you approve.
+- **Goal:** the first approval covers the reviewed Project Brief and its
+  milestone split. Each later milestone is approved separately, at
+  re-alignment, after its amendment is reviewed and gated; the approval is
+  recorded as that milestone's `plan` gate carrier in `state.md`. The goal ends
+  only when you declare it met, and the declaration records an audit of every
+  outcome. Autonomous runs never start or continue a goal project.
 - **Spec-driven:** `/oat-project-plan` asks "Does this breakdown make sense? Any
   tasks missing?" in the chat and revises until you confirm. That confirmation
   is not recorded as an approval, and the automatic review that follows can
@@ -128,7 +135,11 @@ and any budget that runs out adds one read-only complexity-review run.
   pushes your branch after archiving a synced project, whether or not it opens
   a pull request. Autonomous runs also push the branch, without force, after
   each lifecycle step such as planning and implementation. See
-  [Autonomous Project Execution](advanced/autonomy.md).
+  [Autonomous Project Execution](advanced/autonomy.md). In a goal project,
+  `oat-project-pr-progress` pushes the branch and opens each milestone's pull
+  request once the milestone's evidence checks fresh, and
+  `oat-project-complete` opens none when the registered deliveries already
+  cover every accepted phase, even with `workflow.createPrOnComplete` set.
 
 ## Set it up the way you want
 

package/assets/docs/workflows/choose-workflow.md

@@ -1,6 +1,6 @@
 ---
 title: Choose a Workflow
-description: Choose how to run tracked, resumable work in OAT, from no project to lite, brief, quick, spec-driven, or imported projects, and what each mode does at the end.
+description: Choose how to run tracked, resumable work in OAT, from no project to lite, brief, goal, quick, spec-driven, or imported projects, and what each mode does at the end.
 ---
 
 # Choose a Workflow
@@ -49,6 +49,7 @@ Stay with direct CLI usage when:
 - CLI only: direct commands, no tracked project artifacts
 - Lite mode: a batched interview and one approval produce a single-phase `plan.md` for a single-sitting change
 - Brief mode: a design-aligned interview produces one reviewed Project Brief whose phases carry intent and exit evidence instead of tasks
+- Goal mode: a brief whose phases are grouped into milestones, each delivered as its own pull request and followed by a re-alignment, closed by an explicit declaration audited against the brief's outcomes
 - Quick mode: tracked work with a lighter upfront planning path
 - Spec-driven mode: explicit discovery, requirements, design, and plan artifacts
 - Import mode: an externally-authored plan imported into OAT for tracked execution
@@ -79,14 +80,15 @@ it by running that mode's entry skill, and the skill creates the project for
 you. An OAT project is a folder of tracked files (plan, state, reviews) that lets
 an agent pick the work up again in a later session.
 
-| Mode        | Start it with                                   | Choose it when                                                                  | What you give up                                                                                                                     | At the end                                                                                                                  |
-| ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
-| No project  | No skill; ask your agent or run CLI commands    | The work is small, or is just provider sync or a single CLI command             | Resuming later, a tracked plan, and lifecycle reviews. Ad-hoc reviews still work                                                     | OAT pushes nothing and opens no pull request                                                                                |
-| Lite        | `/oat-project-lite`                             | The change fits in one sitting and the outcome is clear                         | Discovery and design documents, multiple phases, and approval pauses between phases. You approve one plan, once                      | Always pushes your current branch and opens a pull request by itself; no setting removes this step                          |
-| Brief       | `/oat-project-brief`                            | The work is one delivery whose outcome and design you can agree in conversation | Discovery and design documents and an up-front task list. Phases state intent and exit evidence; tasks are recorded as the work runs | Same as quick                                                                                                               |
-| Quick       | `/oat-project-quick-start`                      | The work is bounded and the requirements are clear                              | A formal requirements document (`spec.md`). Design is optional                                                                       | Pushes your branch and opens a pull request only when `workflow.postImplementSequence` asks for it, or in an autonomous run |
-| Spec-driven | `/oat-project-new`                              | The requirements are unclear, or the change cuts across many parts of the code  | Speed: you approve discovery and design before any planning or code                                                                  | Same as quick                                                                                                               |
-| Import      | `/oat-project-import-plan` with the plan's path | A plan already exists in another tool or document                               | OAT's own discovery and design steps                                                                                                 | Same as quick                                                                                                               |
+| Mode        | Start it with                                   | Choose it when                                                                                        | What you give up                                                                                                                     | At the end                                                                                                                                                                                      |
+| ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No project  | No skill; ask your agent or run CLI commands    | The work is small, or is just provider sync or a single CLI command                                   | Resuming later, a tracked plan, and lifecycle reviews. Ad-hoc reviews still work                                                     | OAT pushes nothing and opens no pull request                                                                                                                                                    |
+| Lite        | `/oat-project-lite`                             | The change fits in one sitting and the outcome is clear                                               | Discovery and design documents, multiple phases, and approval pauses between phases. You approve one plan, once                      | Always pushes your current branch and opens a pull request by itself; no setting removes this step                                                                                              |
+| Brief       | `/oat-project-brief`                            | The work is one delivery whose outcome and design you can agree in conversation                       | Discovery and design documents and an up-front task list. Phases state intent and exit evidence; tasks are recorded as the work runs | Same as quick                                                                                                                                                                                   |
+| Goal        | `/oat-project-goal`                             | The outcome needs several deliveries over time, and you can agree the first milestone in conversation | The same as brief, plus an approval per milestone and a final declaration that the goal is met                                       | Each milestone's pull request opens when `oat-project-pr-progress` delivers it; any phases no delivery covers go out through `oat-project-pr-final`, and completion opens no extra pull request |
+| Quick       | `/oat-project-quick-start`                      | The work is bounded and the requirements are clear                                                    | A formal requirements document (`spec.md`). Design is optional                                                                       | Pushes your branch and opens a pull request only when `workflow.postImplementSequence` asks for it, or in an autonomous run                                                                     |
+| Spec-driven | `/oat-project-new`                              | The requirements are unclear, or the change cuts across many parts of the code                        | Speed: you approve discovery and design before any planning or code                                                                  | Same as quick                                                                                                                                                                                   |
+| Import      | `/oat-project-import-plan` with the plan's path | A plan already exists in another tool or document                                                     | OAT's own discovery and design steps                                                                                                 | Same as quick                                                                                                                                                                                   |
 
 Type the skill names in your coding agent's chat, not a terminal; Codex uses
 `$` instead of `/`. No mode ever merges a pull request. Separately,
@@ -113,6 +115,12 @@ is what holds the planning conversation, so start with the skill.
   task as it happens rather than planning them all first. Promote it to quick
   with `oat project promote <path> --to quick` if you later want a maintained
   task plan.
+- If the outcome needs more than one delivery, such as a first version now and
+  a follow-up once you have seen it used, choose goal. You approve one brief
+  with a milestone split, then each milestone is delivered as its own pull
+  request and re-aligned before the next one starts; you declare the goal met
+  at the end. Goal is never selected by an autonomous run, because each
+  milestone approval and the final declaration need you.
 - If your team is building a feature with agreed, bounded requirements, choose
   quick. A long task list alone does not call for a formal spec.
 - If the change is high-risk or regulated, or its requirements are still being

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

@@ -37,4 +37,4 @@ If the thought is still pre-shape — you don't know whether it should land as a
 
 ## Promotion Path
 
-When an idea becomes concrete, summarize it and then start a tracked OAT project in lite, quick, or spec-driven mode depending on scope and design risk. Lite suits a single-sitting change and seeds `plan.md` directly; quick and spec-driven seed `discovery.md` instead.
+When an idea becomes concrete, summarize it and then start a tracked OAT project in lite, brief, goal, quick, or spec-driven mode depending on scope and design risk. Lite suits a single-sitting change and seeds `plan.md` directly; brief and goal write their Project Brief into `plan.md` through an interview; quick and spec-driven seed `discovery.md` instead.

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

@@ -63,8 +63,9 @@ Where to start:
 - **Worth exploring:** `oat-idea-new`. `oat-idea-ideate` resumes an idea, can
   start one from a scratchpad seed, and can reopen a summarized idea.
 - **Scoped work for later:** `oat-pjm-add-backlog-item` (needs `oat pjm init`).
-- **Ready to build:** `oat-project-lite`, `oat-project-quick-start`,
-  `oat-project-new`, or `oat-project-import-plan` for a plan written elsewhere.
+- **Ready to build:** `oat-project-lite`, `oat-project-brief`,
+  `oat-project-goal`, `oat-project-quick-start`, `oat-project-new`, or
+  `oat-project-import-plan` for a plan written elsewhere.
 
 Optional moves:
 

package/assets/docs/workflows/projects/closeout/closeout-skills.md

@@ -131,6 +131,28 @@ For a synced project, project artifacts are published to the project ref with
 refreshes project metadata. Declining leaves the description available without
 claiming a PR exists.
 
+**Goal projects:** in a goal project a progress PR is a milestone delivery,
+and this skill registers it. Its scope is the router's `deliver mNN` (or
+`deliver mNN/dNN`) context or a pending `oat_goal_recovery` record at stage
+`delivering`: the milestone's ordered phase set, or a registered delivery's
+frozen scope, never a `pNN-pMM` range or commit labels. The description's Git
+range runs from the set's first anchored base to its last anchored head and
+names any other milestone's phases that fall inside it. In place of the
+optional PR question, the skill runs `oat project delivery refresh` when
+deliveries exist and registers only when
+`oat project delivery check --subject <mNN|dNN>` reports `status: ok`. It
+commits a `registering` registry entry before creating anything, then creates
+the PR, or on resume attaches the single PR that `gh pr list` finds for the
+head branch (more than one match stops at `oat-project-reconcile`). It then
+records the member, `status: open`, and `oat_milestone_status: delivered`, and
+appends one structural project-log entry. Stale review or exit-gate evidence
+stops before registration: for the active milestone the skill writes
+`oat_milestone_status: reviewing` and an `oat_goal_recovery` record at the
+stage the missing evidence names; for an older milestone it writes only the
+recovery record. A milestone that already has a registered delivery is
+re-checked and returned to `delivered` when its evidence is fresh, never
+registered twice.
+
 **Next step:** Review the description and choose whether to open the progress
 PR. Continue remaining project tasks through `oat-project-implement`.
 
@@ -150,8 +172,9 @@ inputs select its destination and title.
 **Prerequisites:** Needs an active OAT project: yes. If no project is active,
 the skill asks for the project name and sets that project as active. The
 project needs `plan.md`. Spec-driven mode also requires `spec.md` and `design.md`. Quick,
-import, lite, and brief accept their mode-appropriate reduced artifacts. The latest
-`final` code-review event in the plan's Reviews ledger should be `passed`.
+import, lite, brief, and goal accept their mode-appropriate reduced artifacts.
+Outside goal mode, the latest `final` code-review event in the plan's Reviews
+ledger should be `passed`.
 Autonomous execution stops if it is not passed. Interactive execution warns
 and asks before proceeding anyway.
 
@@ -172,6 +195,19 @@ and base branch when you did not pass them, the only question it asks is
 whether to continue when the latest final review has not passed. It never
 merges the PR.
 
+**Goal projects:** in a goal project this skill is the terminal delivery
+registration owner, not a second project PR. It runs its own registration step
+in place of the final-review check and PR creation described above. It
+requires `oat_goal_status: declared_met` and a valid outcome audit, read
+through `oat project closeout-check`; any refusal other than `phase-uncovered`
+routes to the skill named in `nextOwner.skill`. When no accepted phase is
+uncovered, it creates no PR and writes no state, because delivery coverage
+already satisfies the `pr` step. Otherwise it registers one terminal delivery
+per milestone that owns uncovered accepted phases, in milestone order, through
+the same registration contract as `oat-project-pr-progress`. Deliveries
+registered from one head branch share its pull request. Coverage completes
+when every terminal delivery reaches its agreed endpoint.
+
 **Example scenario:** Export filters and audit reporting are implemented, the
 latest final review has passed, and you have authorized publication. Final PR
 summarizes the complete change, including review evidence and verification.
@@ -351,6 +387,17 @@ implementation tracking, and state are updated for execution. Inline requests
 are not severity-triaged. Structured GitHub feedback and review artifacts route
 through their corresponding review-receive skills and use those contracts.
 
+**Goal projects:** inline feedback needs an explicit target before anything is
+written: a milestone or delivery identity (`mNN` or `mNN/dNN`). The skill asks
+for it when you did not name it, and never infers it from the open PR's commit
+labels. The revision is a phase-only `p-revN` appended to that milestone's
+`## Milestones` row; a registered delivery's frozen scope is never edited. The
+target's exit carrier, and a registered target delivery's integrated review,
+are marked stale. When the target is the active milestone, the skill returns
+it to `oat_milestone_status: implementing`. Feedback on an older milestone
+creates or advances an `oat_goal_recovery` record instead and leaves the
+active milestone's status and execution pointer unchanged.
+
 **Next step:** If revise did not continue into implementation on its own, run
 `oat-project-implement` to execute the revision tasks. After verification,
 update the open PR and its review evidence. Revise itself does not write code
@@ -378,9 +425,13 @@ path. The target needs `state.md` and at least `plan.md` or
 `implementation.md`. Completed
 implementation provides shipped evidence. If only a plan exists, the skill can
 proceed but must identify recommendations as based on planned work rather than
-verified implementation. Lite and brief projects do not require discovery,
-spec, or design; a brief's documentation sources are the Project Brief and the
-per-phase journal.
+verified implementation. Lite, brief, and goal projects do not require
+discovery, spec, or design; a brief's documentation sources are the Project
+Brief and the per-phase journal. A goal project adds two shipped-result
+sources from `state.md`: the outcome audit (`oat_goal_outcome_audit`) and the
+delivery registry (`oat_deliveries`). The skill documents only what those
+deliveries shipped and names audited deferrals rather than documenting them as
+delivered.
 
 **Example scenario:** Export filters shipped, but the user guide still describes
 only unfiltered exports. Document verifies the actual endpoint and CLI behavior,
@@ -435,7 +486,9 @@ Lite uses its plan contract and implementation results without requiring
 discovery, spec, or design artifacts. Brief needs at least one accepted
 phase-unit and draws on the brief's Goal, Outcomes, Approach, and Decisions
 plus the journal; its staleness fingerprint changes when a phase is accepted,
-not when execution records change.
+not when execution records change. A goal summary's fingerprint also covers
+the deliveries observed at their agreed endpoint, so a delivery newly reaching
+its endpoint makes the summary stale.
 
 **Example scenario:** The first export phase is delivered, and another engineer
 will own the reporting phase next week. Summary records the shipped filter
@@ -471,6 +524,15 @@ It only offers, and does not create without your answer, backlog items for
 follow-up entries in the project log. It does not invent tasks or silently
 rewrite the execution plan.
 
+In a goal project, while `oat project closeout-check` still reports
+`phase-uncovered` and the closeout sequence has not yet run its `pr` step, the
+skill writes only files in the project directory. It defers the repository
+ledger roll-up and decision-record promotion and reports them as deferred,
+because a repository-level commit after the terminal milestone's reviewed
+revision would make the terminal delivery undeliverable. The next summary run
+after `phase-uncovered` clears performs them: a `summary` step configured after
+`pr`, or the summary refresh at completion. Do not decline that refresh.
+
 **Next step:** Use the summary as a source for documentation, PR description,
 and later project handoff. Refresh it after revisions. Complete the project
 only when its lifecycle closeout requirements are satisfied.
@@ -497,7 +559,12 @@ you invoke it by name. Before it changes anything, it runs a read-only check
 that the project's stored closeout sequence is finished (or that the project
 has none). If an implementation closeout is still incomplete, the skill sends
 you back to `oat-project-implement`; no phase-status value bypasses that
-check.
+check. For a goal project the check also applies the goal boundary: a valid
+declaration, an exhaustive outcome audit, resolved extractions, an observation
+of every terminal delivery's pull requests, and delivery coverage of every
+accepted phase. A goal refusal routes to the skill it names in
+`nextOwner.skill`, such as `oat-project-goal`, `oat-project-pr-progress`, or
+`oat-project-pr-final`, rather than to implement alone.
 
 **What it does without asking:** the skill asks once, then acts. One combined
 prompt asks you to confirm completion and, where they apply, whether to
@@ -518,6 +585,12 @@ runs `oat-project-summary`, with its own commit and decision promotion, and an
 archive runs `oat project archive`, including an S3 upload when
 `archive.s3SyncOnComplete` is enabled.
 
+In a goal project whose `pr` step is satisfied by delivery coverage, the skill
+creates no PR, even with `workflow.createPrOnComplete: true`, and reports
+`PR on complete: satisfied by goal delivery coverage`. It opens a separate
+bookkeeping PR for the completion commits only when you ask for one in that
+run, and never counts it as a goal delivery.
+
 **Example scenario:** The export project has passed final verification and its
 stored closeout sequence, but the PR is still open. Complete finalizes lifecycle
 state and, if selected, archives the durable artifacts and updates the existing

package/assets/docs/workflows/projects/closeout/pr-flow.md

@@ -10,6 +10,10 @@ Two PR paths:
 - `oat-project-pr-progress`: progress PR for one phase or partial scope
 - `oat-project-pr-final`: final project PR into `main`
 
+In a goal project both skills register deliveries instead: a progress PR is a
+milestone delivery, and pr-final registers terminal deliveries rather than a
+separate final PR.
+
 ## Inputs
 
 Expected artifacts:
@@ -19,13 +23,15 @@ Expected artifacts:
 - Optional (quick/import): `spec.md`, `design.md`
 - Not expected (lite): `discovery.md`, `spec.md`, or `design.md`
 - Not expected (brief): `discovery.md`, `spec.md`, or `design.md`; the Project Brief in `plan.md` and the per-phase journal in `implementation.md` are the sources
+- Not expected (goal): as brief; the Project Brief with its `## Milestones` table, the journal, and the goal state in `state.md` are the sources
 - Recommended (quick mode): `discovery.md`
 - Recommended (import mode): `references/imported-plan.md`
 - Recommended: `implementation.md` final summary
 - Recommended: `summary.md` — pr-final treats it as the primary source for the PR Summary section and automatically refreshes it first when missing or stale
 - Lite source row: `oat-project-pr-final` uses the plan's Summary, Decisions, and Validation Criteria plus the `implementation.md` Final Summary; it does not create `summary.md` unless lite closeout explicitly opts in
 - Brief source row: `summary.md` is required as in quick; its sources are the brief's Goal, Outcomes, Approach, and Decisions, the journal's accepted phases and Outcomes audit, and the review rows. Progress PRs scope a phase or `pNN-pMM` run from the journal's `**Base:**`/`**Head:**` anchors rather than a commit-message search
-- Required gate for final PR: review table final row should be `passed`
+- Goal source row: a progress PR is a milestone delivery. Its scope is the milestone's ordered phase set, or a registered delivery's frozen scope; its Git range runs from the set's first anchored base to its last anchored head and discloses other milestones' phases inside it. The PR is created only after `oat project delivery check` reports `status: ok` and a `registering` entry is committed to `oat_deliveries`. pr-final registers terminal deliveries for uncovered accepted phases instead of opening a separate final PR
+- Required gate for final PR: review table final row should be `passed` (goal: pr-final does not read the final row; each delivery it registers needs a passed, fresh integrated review and an allowed, fresh exit carrier instead)
 
 ## Output
 

package/assets/docs/workflows/projects/execution/execution-skills.md

@@ -92,7 +92,7 @@ choosing `Leave Unresolved` stops the run. A non-interactive run stops with
 needs your authorization, the skill asks once before any work; if you decline,
 it runs the phases inline in the current session instead.
 
-**Questions on the first run:** Except in a lite or brief project, the first run lists
+**Questions on the first run:** Except in a lite, brief, or goal project, the first run lists
 the plan's phases and asks which checkpoint behavior you want: stop after
 every phase (the default), after specific phases, or only after the final
 phase. Setting `workflow.hillCheckpointDefault` to `every` or `final` answers
@@ -100,8 +100,8 @@ this in advance. It then asks whether to run an extra lifecycle review
 automatically at each checkpoint, unless `workflow.autoReviewAtHillCheckpoints`
 is set. Both answers are written to `plan.md` and are not asked again when you
 resume. A lite project has no checkpoints and skips both questions. A brief
-project skips them too unless its `oat_plan_hill_phases` lists phases
-explicitly; for a brief, `[]` means no checkpoints.
+or goal project skips them too unless its `oat_plan_hill_phases` lists phases
+explicitly; for those modes, `[]` means no checkpoints.
 
 **Brief projects:** Each `## Phase pNN:` block in the brief is one
 phase-unit with Intent and Exit evidence instead of planned tasks. The root
@@ -113,6 +113,19 @@ the root writes `**Status:** completed` once review dispositions and selected
 gates settle. Progress and the next-phase decision count phase-units, never
 records.
 
+**Goal projects:** every brief rule above applies, and each run gets a scope
+from the router: the active milestone's ordered phase set, a recovery scope
+for an older delivery, or the terminal scope after the goal is declared met.
+Implement never widens a scope to another milestone's phases. When every phase
+in the milestone's scope is accepted, it runs the scoped milestone closeout:
+the implement exit gate, written to `oat_milestone_gates[mNN].exit`, then
+`oat_milestone_status: reviewing` and a hand-off to
+`oat-project-review-provide` with `code mNN: <ordered phase ids>`. It never
+activates a milestone, registers a delivery, or writes `declared_met`.
+Terminal closeout starts only after the declaration, and when delivery
+coverage already holds at the `pr` step's position it records that step as
+`satisfied_by: { pr: delivery-coverage }`.
+
 **What it does without asking:** After those questions, the run continues
 until a checkpoint, a blocker or the end of the plan without asking again,
 except for how to run the final code review (described after this list). It:

package/assets/docs/workflows/projects/execution/implementation-execution.md

@@ -16,7 +16,7 @@ and updates project state.
   in dependency order.
 - **Task boundary:** each task still produces exactly one bounded, verified
   commit.
-- **Brief phase-units:** in a brief project each phase carries Intent and Exit
+- **Brief phase-units:** in a brief or goal project each phase carries Intent and Exit
   evidence instead of tasks; execution records are opened in the journal as
   work happens, and the phase's `**Base:**`/`**Head:**` anchors scope its
   review.

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

@@ -30,7 +30,7 @@ instead of `/`):
    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, brief and imported projects never
+   whatever the project's mode; quick, lite, brief, goal 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
@@ -90,6 +90,16 @@ phase-units remain in the active scope") before every later check. The
 implementation it prints a note that `oat project status` and
 `oat-project-next` are the authority for brief projects.
 
+For a goal project, the router also reads the milestone status, any pending
+`oat_goal_recovery` record, the milestone gate carriers, and the delivery
+registry. It sends `aligning` and `delivered` milestones to `oat-project-goal`,
+scopes `oat-project-implement` to the active milestone's phases (or a recovery
+scope), routes the integrated review as `code mNN: …` to
+`oat-project-review-provide`, and routes registration as `deliver mNN` to
+`oat-project-pr-progress`. In the implement phase the dashboard prints a goal
+note that `oat project status` and `oat-project-next` are the authority for
+goal milestone routing.
+
 ## What travels
 
 - The project ref carries the complete active artifact tree and its history.

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

@@ -1,6 +1,6 @@
 ---
 title: Lifecycle
-description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, lite, brief, and import paths.'
+description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, lite, brief, goal, and import paths.'
 ---
 
 # Lifecycle
@@ -29,9 +29,9 @@ For a one-page view of where people approve and what runs automatically in each
 
 ## Quick Look
 
-- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick, lite, brief, and import lanes.
+- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick, lite, brief, goal, and import lanes.
 - When to use it: when you need the actual project execution model, not just a high-level overview of workflow mode.
-- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-lite`, `oat-project-brief`, `oat-project-import-plan`, `oat-project-implement`
+- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-lite`, `oat-project-brief`, `oat-project-goal`, `oat-project-import-plan`, `oat-project-implement`
 
 ## Lifecycle Map
 
@@ -51,9 +51,10 @@ For a one-page view of where people approve and what runs automatically in each
       DOC --> C["Complete"]
     ```
 
-This map shows the spec-driven default. The quick, lite, brief, import, and
-capture lanes each skip part of it — see [Lane diagrams](#lane-diagrams) below.
-Lite and brief in particular have no discovery, spec, or design step at all.
+This map shows the spec-driven default. The quick, lite, brief, goal, import,
+and capture lanes each skip part of it — see [Lane diagrams](#lane-diagrams)
+below. Lite, brief, and goal in particular have no discovery, spec, or design
+step at all.
 
 ## Post-implementation flow
 
@@ -345,6 +346,16 @@ See [Implementation Execution](execution/implementation-execution.md) for the fu
 4. `oat-project-pr-final`, through the same post-implementation sequence as quick
 5. Optional `oat project promote <project-path> --to quick` when you want a maintained task plan instead
 
+### Goal lane steps
+
+1. `oat-project-goal` runs the brief interview for the whole outcome, writes one Project Brief whose `## Milestones` table assigns every phase to exactly one milestone (`| m01 | p01, p02 |`), runs the artifact review and any configured `oat-project-goal` gate, asks for one approval, and activates the first milestone
+2. Implement: `oat-project-implement` executes the active milestone's phase-units as brief does, then runs the milestone closeout, whose `exit` gate runs before the integrated review
+3. `oat-project-review-provide` reviews the milestone as `code mNN: <ordered phases>`; `oat-project-review-receive` moves a clean review to delivery
+4. `oat-project-pr-progress` checks the evidence with `oat project delivery check`, registers the delivery (`dNN`) in `oat_deliveries`, and opens its pull request
+5. `oat-project-goal` re-aligns at `delivered`: it refreshes delivery observations, captures learnings, amends the brief with the next milestone, takes the amendment through review and approval, and activates it once the previous delivery reaches its agreed endpoint
+6. Repeat from step 2 per milestone; when the user declares the goal met, `oat-project-goal` records an exhaustive outcome audit, `oat-project-pr-final` registers terminal deliveries for any accepted phases no delivery covers, and `oat-project-complete` closes out once every accepted phase is covered
+7. Optional `oat project promote <project-path> --to quick` at a settled delivery boundary
+
 ### 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)
@@ -559,6 +570,94 @@ phases (`invalid-brief-plan`), or an accepted phase has neither a completed
 record nor a `**Head:**` anchor to synthesize from (`missing-phase-head`, which
 lists the refused phases).
 
+### Goal lane
+
+=== "Diagram"
+
+    ![Goal lane: an alignment interview and one reviewed Project Brief with a Milestones table, then per milestone activation, phase-units with per-phase reviews, milestone closeout with the exit gate, the integrated review, a registered delivery through pr-progress, and re-alignment that loops to the next milestone once the previous delivery reaches its endpoint; finally the terminal declaration with an exhaustive outcome audit and coverage closeout, with promotion to quick at a settled delivery boundary](/diagrams/project-lifecycle-9-goal-lane-light.svg)
+    ![Goal lane: an alignment interview and one reviewed Project Brief with a Milestones table, then per milestone activation, phase-units with per-phase reviews, milestone closeout with the exit gate, the integrated review, a registered delivery through pr-progress, and re-alignment that loops to the next milestone once the previous delivery reaches its endpoint; finally the terminal declaration with an exhaustive outcome audit and coverage closeout, with promotion to quick at a settled delivery boundary](/diagrams/project-lifecycle-9-goal-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      A["Alignment interview\n(whole outcome, milestone split)"] --> B["Project Brief + Milestones\n(review, gate, one approval)"]
+      B --> M["Activate milestone mNN\n(oat-project-goal)"]
+      M --> I["Phase-units\n(implement, per-phase reviews)"]
+      I --> X["Milestone closeout\n(exit gate before the review)"]
+      X --> R["Integrated review\n(code mNN: ordered phases)"]
+      R --> D["Delivery dNN\n(oat-project-pr-progress)"]
+      D --> RA["Re-alignment\n(learnings, amendment, approval)"]
+      RA -->|Next milestone at endpoint| M
+      RA --> T["Terminal declaration\n(exhaustive outcome audit)"]
+      T --> C["Coverage closeout\n(pr-final for uncovered, complete)"]
+      D -->|Settled boundary| Q["Promote to Quick"]
+    ```
+
+A goal project is a brief project delivered in milestones. The Project Brief
+carries a `## Milestones` table (`| Milestone | Phases |`) in which every
+phase, including appended `p-revN` revision phases, belongs to exactly one
+milestone; `oat project validate-plan` reports membership errors as `goal-`
+codes. Each milestone is approved through its own `plan` gate carrier in
+`state.md` (`oat_milestone_gates.mNN.plan`): the first approval also marks
+`plan.md` complete, and every later amendment is approved only by the next
+milestone's carrier.
+
+**Milestone delivery.** For goal the end of the brief ladder is reordered: the
+milestone's `exit` gate runs at closeout before the integrated review, and
+queued fixes invalidate both, so the gate runs again before the next review.
+The integrated review names its milestone (or delivery) and the exact ordered
+phase set, for example `code m01: p01, p02, p-rev1`; that set is never derived
+from a first–last range. `oat-project-pr-progress` registers a delivery only
+when `oat project delivery check --subject <mNN|dNN>` reports `status: ok`,
+writing the `oat_deliveries` entry (`registering`) before it creates the pull
+request so an interrupted run resumes by `gh pr list` instead of opening a
+duplicate.
+
+**Freshness.** Evidence keeps the revision actually reviewed. Commits after it
+count as bookkeeping only when they touch the project's tracking files in
+permitted ways (routing, progress, evidence, project-log appends); a code
+change, an edit to approved brief content such as Outcomes or a phase's Intent,
+or a substantive change followed by its revert stales the delivery.
+`oat project delivery refresh` observes each member pull request with
+`gh pr view` and records staleness; it never writes milestone status or
+recovery. Because the project branch is the delivery's head branch, do not
+push a brief amendment while that delivery is still open.
+
+**Recovery.** Stale evidence on the active milestone's delivery returns it to
+`reviewing`. Fixes or inline feedback for an older milestone open an
+`oat_goal_recovery` record targeting that milestone and delivery, scheduling a
+`p-revN` phase in its row, while the active milestone, its status and the
+execution pointer stay untouched.
+
+**Re-alignment and the end.** At `delivered`, `oat-project-goal` refreshes the
+observations, writes one learnings entry, amends the brief with the next
+milestone, and runs the review, gate and approval for the amendment; it may do
+all of that while a `merged` endpoint is pending, but it activates the next
+milestone only once refresh observes the previous delivery at its endpoint.
+When the user declares the goal met, the declaration is recorded in
+`implementation.md` and `state.md` gets `oat_goal_status: declared_met` and an
+exhaustive outcome audit: every phase `accepted`, `extracted`, `deferred` or
+`retired`, every numbered outcome bound to its exact text. Terminal closeout
+requires the declaration, the audit and delivery coverage of every accepted
+phase; `oat-project-pr-final` registers one terminal delivery per milestone
+that still has uncovered phases, all sharing the head branch's pull request.
+`oat-project-complete` then opens no further pull request, even with
+`workflow.createPrOnComplete: true`, because the deliveries already cover the
+work.
+
+### Promoting a goal project to quick
+
+`oat project promote <project-path> --to quick` accepts a goal project only at
+a settled delivery boundary: the active milestone is `delivered`, every
+registry entry is `at_endpoint` or `superseded`, and no recovery is pending.
+It otherwise refuses without writing, with `goal-milestone-active`,
+`goal-recovery-pending`, or `goal-delivery-unsettled` (which lists the open or
+`registering` deliveries, and also covers an empty registry). A settled goal
+promotes like a brief, and the archive `references/brief-archive.md` carries
+the delivery history (registry, milestone gates and outcome audit) after the
+original brief. `oat-project-quick-start` resumes the promoted project.
+
 ### Import lane
 
 === "Diagram"
@@ -668,15 +767,15 @@ actionable `oat pjm init` stop instead of scaffolding implicitly. See
 
 ### Seeding a new project from a brainstorm
 
-When the brainstorming destination is "promote to a new OAT project", the dispatcher confirms a project slug and one of four modes: `lite`, `brief`, `quick`, or `spec-driven`. For Quick and Spec-Driven projects, it runs `oat project new <slug> --mode <mode>` and writes `discovery.md` directly from the brainstorming payload — Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, and Open Questions. It writes only `discovery.md` (never a partial `design.md`), then points to `oat-project-quick-start` or `oat-project-design` without auto-chaining. For Lite projects, it instead seeds the five sections in `plan.md`, leaves `discovery.md` and `design.md` absent, and points to `oat-project-lite`. For Brief projects, it writes the payload to a research note under `references/research/`, leaves the scaffolded `plan.md` for the brief interview, and points to `oat-project-brief`.
+When the brainstorming destination is "promote to a new OAT project", the dispatcher confirms a project slug and one of five modes: `lite`, `brief`, `goal`, `quick`, or `spec-driven`. For Quick and Spec-Driven projects, it runs `oat project new <slug> --mode <mode>` and writes `discovery.md` directly from the brainstorming payload — Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, and Open Questions. It writes only `discovery.md` (never a partial `design.md`), then points to `oat-project-quick-start` or `oat-project-design` without auto-chaining. For Lite projects, it instead seeds the five sections in `plan.md`, leaves `discovery.md` and `design.md` absent, and points to `oat-project-lite`. For Brief projects, it writes the payload to a research note under `references/research/`, leaves the scaffolded `plan.md` for the brief interview, and points to `oat-project-brief`. Goal projects arrive the same way and point to `oat-project-goal`, which authors the brief and its milestone split.
 
-This is a parallel entry path into all four lanes, not a new lane. Quick and Spec-Driven users arrive at `oat-project-quick-start` or `oat-project-design` with discovery already populated; Lite users arrive at `oat-project-lite` with the single-phase plan already seeded; Brief users arrive at `oat-project-brief` with the brainstorm payload saved as a research note under `references/research/` and the scaffolded `plan.md` left for the interview.
+This is a parallel entry path into all five lanes, not a new lane. Quick and Spec-Driven users arrive at `oat-project-quick-start` or `oat-project-design` with discovery already populated; Lite users arrive at `oat-project-lite` with the single-phase plan already seeded; Brief and goal users arrive at `oat-project-brief` or `oat-project-goal` with the brainstorm payload saved as a research note under `references/research/` and the scaffolded `plan.md` left for the interview.
 
 ### Folding back into an active project
 
 When `oat-brainstorm` fires while a project is active, it offers a 3-way picker before any pack-filtered destination shows up:
 
-- **Related to the project** → for Lite, fold the synthesis into `plan.md` immediately above `## Phase 1` and hand off to `oat-project-lite`; for Brief, fold it into `plan.md` immediately above the first `## Phase` heading so the receiving skill integrates it as new or amended phases; for Quick and Spec-Driven, use the most-specific upstream artifact (`design.md` if it exists, otherwise `discovery.md`) and hand off to `oat-project-quick-start` or `oat-project-plan`. Any mode with an open PR hands off to `oat-project-revise`. The fold-back commit is safety-gated: a preflight `git status --porcelain -- "$ARTIFACT_PATH"` checks for dirty state, staging is exactly `git add -- "$ARTIFACT_PATH"` (never `-A`, never globs), and the handoff prompt only prints after the scoped commit succeeds.
+- **Related to the project** → for Lite, fold the synthesis into `plan.md` immediately above `## Phase 1` and hand off to `oat-project-lite`; for Brief, fold it into `plan.md` immediately above the first `## Phase` heading so the receiving skill integrates it as new or amended phases; Goal folds into `plan.md` the same way, never editing the `## Milestones` table, and hands off to `oat-project-goal` (or `oat-project-implement` inside the active milestone's approved scope); for Quick and Spec-Driven, use the most-specific upstream artifact (`design.md` if it exists, otherwise `discovery.md`) and hand off to `oat-project-quick-start` or `oat-project-plan`. Any mode with an open PR hands off to `oat-project-revise`. The fold-back commit is safety-gated: a preflight `git status --porcelain -- "$ARTIFACT_PATH"` checks for dirty state, staging is exactly `git add -- "$ARTIFACT_PATH"` (never `-A`, never globs), and the handoff prompt only prints after the scoped commit succeeds.
 - **Independent of the project** → the active project is acknowledged but doesn't constrain the picker; brainstorm routes through its standard pack-filtered terminal-state options (new project, backlog item, idea, doc-to-path, inline).
 - **Related but supplementary** → write a brainstorming reference file at `.oat/projects/<scope>/<project>/brainstorming/YYYY-MM-DD-<topic>.md`, alongside `pr/` and `reviews/`. No lifecycle artifact is touched.
 

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

@@ -60,11 +60,11 @@ 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.
 
-### Brief checkpoint resolution
+### Brief and goal checkpoint resolution
 
-Brief projects read `oat_plan_hill_phases` with a brief meaning: `[]` and an
-absent field both mean **no checkpoints**, never "every phase". The brief
-scaffold writes `oat_plan_hill_phases: [] # [] = none for brief modes`, and
+Brief and goal projects read `oat_plan_hill_phases` with a brief meaning: `[]`
+and an absent field both mean **no checkpoints**, never "every phase". The
+brief scaffold, which goal projects share, writes `oat_plan_hill_phases: [] # [] = none for brief modes`, and
 `oat-project-implement` then writes:
 
 ```yaml
@@ -141,8 +141,8 @@ See [Workflow preferences in the Configuration guide](../../../reference/configu
 A HiLL (human-in-the-loop lifecycle) checkpoint is a point where the
 implementing agent stops and waits for a person to approve before it continues.
 This choice decides how often that happens during implementation. Lite projects
-have no checkpoints, and brief projects have none unless they list phases
-explicitly, so it does not apply to them.
+have no checkpoints, and brief and goal projects have none unless they list
+phases explicitly, so it does not apply to them.
 
 | Choice             | Choose it when                                    | What you give up                             |
 | ------------------ | ------------------------------------------------- | -------------------------------------------- |