@open-agent-toolkit/cli 0.3.18 → 0.3.20

package/README.md

@@ -62,7 +62,8 @@ Use these commands when you want structured runtime/project state out of the CLI
 - `oat config dump --json` - emit merged OAT config with per-key source attribution
 - `oat project status --json` - emit the active project's full parsed control-plane state
 - `oat project list --json` - emit summary state for tracked projects under the configured projects root
-- `oat project closeout-check <project-path> --json` - report whether a configured, autonomous, or lite closeout's `oat_post_implement_sequence` snapshot permits terminal completion, and which step or approval owns it next (read-only)
+- `oat project closeout-check <project-path> --json` - report whether a configured, autonomous, or lite closeout's `oat_post_implement_sequence` snapshot permits terminal completion and, for a goal project, whether the declaration, outcome audit, and delivery coverage boundary holds, and which step, approval, or skill owns it next (read-only)
+- `oat project delivery check --project <path> --subject <mNN|dNN> --json` - read-only goal delivery evidence report for a milestone or registered delivery (`status: ok`, or `undeliverable` with exit 1)
 - `oat project complete-state <project-path>` - emit the canonical completed lifecycle shape into a tracked project's `state.md`; refuses the same incomplete closeout `closeout-check` reports
 
 ## Requirements

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.1.7
+version: 1.1.9
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -29,7 +29,7 @@ The root supplies:
 - `mode`: `implement`, `fix`, or `recover`;
 - `artifact_paths`: available plan, design, spec, discovery, implementation,
   and imported-plan paths;
-- `workflow_mode`: `spec-driven`, `quick`, `import`, or `lite`;
+- `workflow_mode`: `spec-driven`, `quick`, `import`, `lite`, `brief`, or `goal`;
 - `commit_convention`: exact task/fix commit convention;
 - `phase_base_head`: root-recorded HEAD before phase dispatch;
 - `worktree`: assigned phase worktree or orchestration checkout;
@@ -125,9 +125,22 @@ Read each required artifact once at phase start:
   Criteria, and the Product Behavior and/or Technical Design selected by its
   recorded `minimal`, `product`, `technical`, or `both` content shape.
   Discovery, spec, and design are absent by design.
+- `brief`: read the assigned `## Phase pNN:` block (`**Intent:**`,
+  `**Exit evidence:**`, `**Provisional:**`) and the brief's Goal, Outcomes,
+  Approach, Constraints and Out of Scope, Decisions, Known Unknowns, and
+  Delivery endpoint and authority sections in `plan.md`; the phase's section of
+  `implementation.md`; and sections 3, 6, 7, and 10 of
+  `oat-project-brief/references/brief-contract.md`. Discovery, spec, and design
+  are absent by design.
+- `goal`: everything `brief` reads, plus the `## Milestones` table and
+  section 12 of the brief contract. The Phase Scope names the milestone,
+  recovery, or terminal scope the phase belongs to.
 
 Extract all phase tasks, dependency order, file boundaries, verification
-commands, commit messages, and phase-wide verification before editing.
+commands, commit messages, and phase-wide verification before editing. In
+`brief` and `goal` modes there are no planned tasks to extract: extract the phase's Intent,
+its Exit evidence as the phase-wide verification, and the Phase Scope's commit
+convention, and follow `## Brief Mode` below.
 
 ## Artifact Hygiene
 
@@ -348,6 +361,91 @@ disposition:
 - Reason: {eligibility or stop-boundary evidence}
 ```
 
+## Brief Mode
+
+This section applies only when `workflow_mode` is `brief`. It replaces task
+extraction and adapts the task loop; every other rule in this contract,
+including recovery, still applies. The brief contract wins where this section
+restates it.
+
+**Requirement source.** The phase's Intent and Exit evidence plus the brief's
+Outcomes, Constraints and Out of Scope, and Decisions. A provisional phase is
+never executed: return `NEEDS_CONTEXT` naming it, because the root makes
+phases concrete before dispatch.
+
+**Execution records replace planned tasks.** Work in coherent units, each tied
+to one implementation commit. For each unit:
+
+1. Open `### Task pNN-tNN: <name>` under the phase's section of
+   `implementation.md` with `**Status:** in_progress`,
+   `**Executor:** phase-implementer:<original_request_id>`, intent, files,
+   proof command, and your handle. Use the next free ordinal in the phase
+   (`prevN-tNN` in a revision phase); never reuse an ID. Lookahead is allowed:
+   you may open several independent records before working them.
+2. Implement the unit and run its proof command plus the Prevention checks.
+3. Create its one implementation commit through `oat internal commit-paths`
+   with identity `${ORIGINAL_REQUEST_ID}:${RECORD_ID}`, a message carrying
+   `(pNN-tNN)`, and an owned-file list that excludes the journal.
+4. Close the record with `**Status:** completed` and `**Commit:** <full SHA>`,
+   or with `failed`, `cancelled`, or `no-change` and no fabricated commit, and
+   commit only `implementation.md` as `chore(oat): record {pNN-tNN}` with
+   identity `${ORIGINAL_REQUEST_ID}:${RECORD_ID}:record`.
+
+Step 2's per-task verification then expects exactly one implementation commit
+inside the record's effective boundary followed by one journal-only record
+commit; a record closed with a terminal status and no implementation commit
+produces only the journal-only commit. A request for a maintained up-front task
+plan is a promotion question for the root, never lookahead.
+
+**Journal ownership.** You write only your phase's section of
+`implementation.md`: its execution records and, in a sequential phase, its
+`**Head:**` line and verification summary. Never write `**Base:**` (the root
+records it before dispatch and passes it as `anchor_base`), never write the
+phase's `**Status:** completed` (acceptance is root-owned), and never edit
+`state.md`, `plan.md`, the `## Reviews` table, or another phase's section. In a
+parallel-group worktree, write the records but no anchors; the root writes the
+group's fork base and integration-merge heads at fan-in. Report your worktree
+head: it is the review head of your phase's per-phase review, which runs on
+`EXPECTED_HEAD..<that head>` before the merge.
+
+**Phase head.** After the last record closes and phase-wide verification
+passes, in a sequential phase write `**Head:** <full SHA of the last commit of
+the phase>` plus a short verification summary under the phase heading and
+commit only the journal as `chore(oat): record {pNN} head`. Report the head.
+
+**Nested workers never commit.** An optional nested worker returns edits on
+owned paths; you, the committing owner, create every commit.
+
+**Fix mode.** Record each review fix as a record whose name starts with
+`(review)` and that carries `**Source review:**` with the review filename and
+finding IDs, through the same open, commit, close sequence. While no later
+phase has a `**Base:**`, also advance `**Head:**` to the new last commit in the
+closing journal commit; otherwise stop and report, because the correction
+belongs to a revision phase the root appends.
+
+**Report.** In the Task Outcomes table, list one row per execution record in
+the Task column with its terminal status and commit, and add
+`**Phase anchors:** {anchor_base}..{head}` below the header fields.
+
+## Goal Mode
+
+This section applies only when `workflow_mode` is `goal`. Every `## Brief Mode`
+rule applies unchanged, and section 12 of the brief contract wins where this
+section restates it.
+
+- **Scope.** Execute only the dispatched phase. Its milestone, recovery, or
+  terminal scope is context, never permission to touch another milestone's
+  phases.
+- **Root-owned goal records.** Never write `oat_milestone`,
+  `oat_milestone_status`, `oat_goal_status`, `oat_goal_outcome_audit`,
+  `oat_goal_recovery`, `oat_milestone_gates`, `oat_deliveries`, or the
+  `## Milestones` table. Milestone closeout, the exit-gate carrier, recovery
+  stages, delivery registration, and the declaration are root and skill
+  transitions, not phase work.
+- **Recovery phases.** A recovery scope's phase (often a `p-revN` that
+  corrects an older milestone's phase) follows the brief late-fix and revision
+  rules; report its head like any sequential phase.
+
 ## Mode: Implement
 
 ### 1. Verify Phase Base
@@ -484,6 +582,9 @@ After all task commits:
   - `spec-driven`: `plan.md`, `design.md`, and `spec.md`;
   - `quick`: `plan.md` and `discovery.md`, plus design/spec when present; and
   - `import`: `plan.md` and the imported plan, plus design/spec when present;
+  - `brief`: the phase's Intent and Exit evidence plus the brief's Outcomes,
+    Constraints and Out of Scope, and Decisions;
+  - `goal`: as `brief`, within the dispatched milestone's scope;
 - confirm no task boundary or dependency was missed; and
 - report Medium/Low concerns without launching a reviewer.
 

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.2.11
+version: 1.2.13
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
@@ -50,9 +50,10 @@ You will be given a "Review Scope" block including:
 - **commits/range**: Git commits or SHA range for changed files. For code review, this is the authoritative review surface.
 - **files_changed**: Optional orientation hint listing files believed to be modified in scope. If this disagrees with the commit range, trust the commit range.
 - **analysis_artifact**: For `type: analysis`, path to the severity-rated analysis artifact to fact-check.
-- **workflow_mode**: `spec-driven` | `quick` | `import` | `lite` (default to `spec-driven` if absent)
+- **workflow_mode**: `spec-driven` | `quick` | `import` | `lite` | `brief` | `goal` (default to `spec-driven` if absent)
 - **artifact_paths**: Paths to available artifacts (spec/design/plan/implementation/discovery/import reference)
-- **tasks_in_scope**: Task IDs being reviewed (if task/phase scope)
+- **tasks_in_scope**: Task IDs being reviewed (if task/phase scope). In `brief` mode these are the execution-record IDs under the phases in scope; they label commits and never narrow the range.
+- **Brief anchor record**: For `brief` code reviews, the caller supplies `oat_review_requested_scope`, `oat_review_phase_ids` (ordered), `oat_review_base_sha`, `oat_review_scope_source` (`anchors` | `merge-base-range` | `explicit` | `merge-base` | `narrowed`), and, when they apply, `oat_review_fallback_reason`, `oat_review_integration_commits`, and `oat_review_narrowed_from`. Copy them verbatim into artifact frontmatter (Step 8). In `goal` mode the same record applies; for an integrated milestone or delivery review `oat_review_requested_scope` is the milestone or delivery ID (`mNN` or `mNN/dNN`) and `oat_review_phase_ids` is the explicit ordered phase set.
 - **oat_output_mode**: Optional output-sink selector. Absent (or any value other than `structured`) means **artifact mode** — write the review artifact to disk per Step 8. `structured` means **structured-output mode** — return a `StructuredFindings` object in-memory and write NO artifact file (see **Structured-Output Mode**). This key parallels the existing `oat_review_invocation` dispatch-payload naming.
 - **oat_review_invocation**: Optional provenance selector for artifact-mode reviews. Use `manual`, `auto`, or `gate`; default to `manual` when absent.
 - **Code-review provenance**: For artifact-mode code reviews, resolve the authoritative range head with `git rev-parse <authoritative-range-head>^{commit}` and record the resulting full 40-character commit SHA as `oat_review_head_sha`. If the review is narrowed, also record the resolved range, prior artifact path, and prior reviewed head supplied by the caller.
@@ -129,6 +130,8 @@ Use workflow mode to determine required evidence:
 - **quick**: `discovery.md` + `plan.md` are expected (`spec.md`/`design.md` optional if present).
 - **import**: `plan.md` is expected (`references/imported-plan.md` preferred; `spec.md`/`design.md` optional).
 - **lite**: `plan.md` and `implementation.md` are expected; discovery, spec, and design are absent by design.
+- **brief**: `plan.md` (a Project Brief) and `implementation.md` (the per-phase journal) are expected; discovery, spec, and design are absent by design. `oat-project-brief/references/brief-contract.md` defines the brief sections, phase grammar, journal markers, and anchor rules, and the caller supplies it with the Review Scope.
+- **goal**: as **brief**, plus the canonical `## Milestones` table in `plan.md` and the goal state in `state.md`; section 12 of the brief contract defines milestones, explicit review scopes, the delivery registry, and the terminal audit.
 
 Do not mark missing optional artifacts as findings.
 If required artifacts for the mode are unexpectedly missing, record a workflow contract gap.
@@ -152,6 +155,7 @@ Read available artifacts to understand what SHOULD have been built:
    - `quick`: read `discovery.md` and `plan.md`; read `spec.md`/`design.md` only if they exist.
    - `import`: read `plan.md` and `references/imported-plan.md` (if present); read `spec.md`/`design.md` only if they exist.
    - `lite`: read `plan.md` and `implementation.md`; do not require discovery, spec, design, or an import reference.
+   - `brief`: read the brief in `plan.md`, the journal in `implementation.md`, and the brief contract when supplied; do not require discovery, spec, design, or an import reference.
 3. For `type: analysis`, read `analysis_artifact` and then inspect only the cited evidence sources needed to verify its findings:
    - `scope: docs`: consult the docs contract, docs navigation/index files, and cited docs source files relevant to the analysis.
    - `scope: agent-instructions`: consult the repo/root instruction files, provider instruction files, and cited skill/agent instruction files relevant to the analysis.
@@ -161,6 +165,10 @@ Read available artifacts to understand what SHOULD have been built:
 
 Only review files/changes within the provided scope.
 
+In `brief` mode the authoritative code-review range comes from the recorded phase anchors: `Base..Head` for one phase, or the first selected base through the last selected phase's head for a range or `final`. Commit-message `(pNN-` matches only label which commits belong to which phase and never narrow the range. When `oat_review_scope_source` is `merge-base-range`, review the entire supplied range. If an anchor is missing, does not exist, or contradicts the ordering rules in brief contract section 10, record a workflow contract gap rather than narrowing silently. Treat the listed integration commits as inside the range.
+
+In `goal` mode an integrated milestone or delivery review judges exactly the explicit ordered phase set in `oat_review_phase_ids`, never a first–last expansion. The Git range may be wider: commits of phases outside the set that the Review Scope lists under `Intervening changes:` are context, not scope, so do not record findings against them and do not treat them as covered. A parallel group member's pre-fan-in review is member evidence only; integrated delivery evidence comes from the integration heads.
+
 Do NOT:
 
 - Review unrelated work outside the scope
@@ -177,6 +185,8 @@ For each requirement in scope, use the best available requirement source by mode
 - `quick`: `discovery.md` + `plan.md`
 - `import`: normalized `plan.md` + `references/imported-plan.md` (if present)
 - `lite`: the requirements contract in `plan.md`: Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria. Also use Product Behavior and/or Technical Design when selected by the recorded `minimal`, `product`, `technical`, or `both` content shape.
+- `brief`: each phase in scope's `**Intent:**` and `**Exit evidence:**` lines plus the brief's Outcomes, Constraints and Out of Scope, and Decisions. A `final` review also audits every numbered Outcome against its observed evidence in the journal; an Outcome with neither evidence nor a recorded deferral is a finding. Execution records are evidence of committed work, not requirements.
+- `goal`: as `brief`, scoped to the milestone or delivery set under review. A plan (artifact) review of a goal brief or amendment also checks the `## Milestones` table against brief contract section 12.1: every executable phase in exactly one milestone, phase IDs never reused, and no frozen delivery phase moved or removed.
 
 Then verify:
 
@@ -267,13 +277,14 @@ Treat the artifact as a product deliverable. Verify it is:
      - `quick`: discovery (+ spec/design if present)
      - `import`: imported-plan reference (+ discovery/spec/design if present)
      - `lite`: plan.md Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria. Also review the Product Behavior and/or Technical Design required by its recorded content shape; challenge `minimal` when an observable shape trigger applies.
+     - `brief`: the brief is self-contained; review it against the brief contract and the user's request, with no upstream discovery, spec, or design.
    - For import-mode `plan` reviews, bias findings toward canonical-format conformance and completeness. Do not rewrite the imported author's intent merely to match OAT house style.
 
 4. **Actionable**
    - Clear next steps and readiness signals
    - For spec: Verification entries are meaningful (`method: pointer`)
    - For design: requirement-to-test mapping exists and includes concrete scenarios
-   - For plan: tasks have clear verification commands and commit messages
+   - For plan: tasks have clear verification commands and commit messages (for a brief, each phase has concrete Intent and Exit evidence instead; tasks are not required)
 
 5. **Plan-specific checklist**
    - Canonical-format conformance: required frontmatter and sections are present, the Reviews table exists, and artifact/code rows are shaped consistently.
@@ -283,6 +294,8 @@ Treat the artifact as a product deliverable. Verify it is:
    - Task atomicity and verifiability: each task is independently committable, has bounded file scope, and has executable verification intent. Require a proportionate implementation and proof strategy only when the applicable workflow plan contract declares it; otherwise review the task's existing verification commands and evidence.
    - Coverage of design/discovery: every in-scope design component or discovery decision is mapped to at least one task or explicitly deferred/out of scope.
    - Parallelism-claim sanity: any parallel phase group or parallelism statement is consistent with declared file boundaries and dependency order.
+   - **Goal plan review** follows the brief plan review below, except that `## Milestones` holds the canonical table (brief contract section 12.1) instead of being empty, and an amendment review judges the named milestone's appended phases and any changed Outcomes, Decisions, or authority.
+   - **Brief plan review** replaces the task-oriented items above with the brief section list: Goal; numbered Outcomes, each naming its intended evidence; Approach (optional `### Design`); Constraints and Out of Scope; Decisions with rationale and rejected alternatives; Known Unknowns, each with the phase that settles it; Delivery endpoint and authority; an empty `## Milestones` section; `## Phase pNN:` blocks with non-empty Intent and Exit evidence, a `**Provisional:**` value of `yes` or `no`, and a concrete first phase; Parallelism; Reviews (preserved rows); Implementation Complete; References. Stable, never-reused phase IDs in document order replace stable task IDs. There is no task requirement; `### Task` headings in a brief are a finding, because execution records belong in the journal. Check that every Outcome is reachable through some phase's Exit evidence and that any declared parallel group passes the independence test in brief contract section 6.
 
 6. **Necessary**
    - Evaluate whether the proposed approach materially serves the requested
@@ -307,7 +320,7 @@ Treat the artifact as a product deliverable. Verify it is:
 
 This step applies to **code reviews** only.
 
-If `design.md` is absent in quick/import/lite mode, mark design alignment as "not applicable (design artifact not present for mode)" and continue.
+If `design.md` is absent in quick/import/lite/brief mode, mark design alignment as "not applicable (design artifact not present for mode)" and continue. A brief's `### Design` subsection, when present, is the design source for this step.
 
 For each design decision relevant to scope:
 
@@ -550,6 +563,8 @@ Gate parsing contract: artifact-mode reviews, including reviews spawned by `oat
 
 For every artifact-mode code review, `oat_review_head_sha` is required and must be the full 40-character commit SHA at the head of the authoritative review range. Resolve it with `git rev-parse <authoritative-range-head>^{commit}`. An abbreviated SHA, symbolic ref, or range string is invalid. When the review narrowed, `oat_review_range`, `oat_prior_review_artifact`, and `oat_prior_review_head_sha` are also required; the prior head must likewise be a full 40-character SHA. These code-review fields are independent of the gate-only block and do not apply to artifact, analysis, or structured-output reviews.
 
+For a `brief` code review, also copy the supplied anchor record fields (`oat_review_requested_scope`, `oat_review_phase_ids`, `oat_review_base_sha`, `oat_review_scope_source`, and any supplied `oat_review_fallback_reason`, `oat_review_integration_commits`, and `oat_review_narrowed_from`) verbatim into frontmatter beside `oat_review_head_sha`, which is the aggregate head of the anchored range. Never infer them from commit messages or the current HEAD.
+
 For a narrowed review, do not restate requirements-coverage claims that this pass did not itself verify. Reference the prior artifact's coverage or mark inherited coverage rows as inherited so the union of passes remains auditable.
 
 For gate-originated artifacts, all six gate-only fields are required when the prompt supplies gate context. Copy the values exactly. Do not parse the provider command, infer values from the target id, or replace configured values with observed/self-reported identity. Any optional self-report belongs in review prose and is non-authoritative; the gate validates the copied frontmatter against its immutable configured invocation record before applying severity thresholds.

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.18"
+  "oatVersion": "0.3.20"
 }

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

@@ -100,12 +100,18 @@ Lifecycle](../workflows/backlog-and-planning/backlog-lifecycle.md).
 
 Notable commands introduced in the current CLI surface:
 
-- `oat project new <slug> [--mode spec-driven|quick|import|lite] --scope shared|local|synced [--force]` - create a
+- `oat project new <slug> [--mode spec-driven|quick|import|lite|brief|goal] --scope shared|local|synced [--force]` - create a
   project in an explicit scope. `--mode` selects the workflow mode and therefore
   which artifacts are scaffolded; it defaults to `spec-driven`. Use `quick` for a
   bounded feature with clear requirements, `import` to normalize an externally
-  authored plan, and `lite` for a single-sitting change that scaffolds only
-  `plan.md`, `state.md`, and `implementation.md`. See
+  authored plan, `lite` for a single-sitting change that scaffolds only
+  `plan.md`, `state.md`, and `implementation.md`, and `brief` for one delivery
+  planned as a Project Brief, which scaffolds the `plan-brief` and
+  `implementation-brief` templates plus `references/research/`, and `goal` for
+  an outcome delivered in milestones, which scaffolds the same files with
+  `oat_plan_source: goal` and the canonical `| Milestone | Phases |` table
+  header. Start brief and goal projects with `oat-project-brief` or
+  `oat-project-goal`, which run this command themselves. See
   [Lifecycle](../workflows/projects/lifecycle.md) for the per-lane flow. Without
   `--scope`, creation uses
   `projects.defaultScope`, which defaults to `synced`. Project slugs are
@@ -190,17 +196,19 @@ Notable commands introduced in the current CLI surface:
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
 - `oat project status --project-path <path>` - read from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer. Combine it with `--field` or `--shell` when a skill has already resolved the target project path.
 - `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
-- `oat project promote <project-path> --to quick [--json]` - promote an authored lite project to quick mode. The command derives `discovery.md` from the lite plan's Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria; carries Product Behavior into Success Criteria and Technical Design into a carried-forward discovery section when those adaptive sections are present; preserves the original as `references/lite-plan.md`; and scaffolds a fresh quick `plan.md`. It refuses unsupported targets, non-lite or unreadable projects, an existing lite-plan reference, invalid authored sections, unresolved scope, unavailable templates, failed writes, or failed persistence. JSON output is `{ status: "promoted" | "refused", reason, files }`; `reason` is the stable categorical contract and refused results exit non-zero.
+- `oat project promote <project-path> --to quick [--json]` - promote an authored lite, brief, or settled goal project to quick mode. For a lite project, the command derives `discovery.md` from the lite plan's Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria; carries Product Behavior into Success Criteria and Technical Design into a carried-forward discovery section when those adaptive sections are present; preserves the original as `references/lite-plan.md`; and scaffolds a fresh quick `plan.md`. For a brief project, it migrates each phase by state: accepted phases keep their completed execution records as quick tasks or get one synthesized `Accepted via phase evidence` task against the phase's `**Head:**`, active phases keep their completed records, and pending or provisional phases stay taskless and are listed in `oat_promotion_pending_phases` (quick plan readiness stays false until that list is empty); it renders the brief's sections into `discovery.md`, archives the original as `references/brief-archive.md`, and sets `oat_promoted_from` to the source mode (`brief`, or `goal` for a goal project). There is no reverse direction. A goal project promotes like a brief, but only at a settled delivery boundary: the active milestone is `delivered`, every `oat_deliveries` entry is `at_endpoint` or `superseded`, and no `oat_goal_recovery` is pending; otherwise it refuses with `goal-milestone-active`, `goal-recovery-pending`, or `goal-delivery-unsettled` (with a `deliveries` array naming the unsettled entries; an empty registry is also unsettled), and its archive appends the delivery history after the original brief. It refuses unsupported targets, projects that are neither lite, brief, nor goal, unreadable projects, an existing lite-plan reference, invalid authored sections, an existing brief archive (`brief-archive-exists`), an extracted journal phase (`extracted-phases`), a brief with no parseable phases (`invalid-brief-plan`), an accepted brief phase with no completed record and no `**Head:**` anchor (`missing-phase-head`), unresolved scope, unavailable templates, failed writes, or failed persistence. JSON output is `{ status: "promoted" | "refused", reason, files }`, plus an optional `phases` array naming the refused phases when `reason` is `missing-phase-head`; `reason` is the stable categorical contract and refused results exit non-zero.
 - `oat template resolve <name> [--output <path>] [--json]` - resolve a template in repository (`<repo>/.oat/templates/`), user (`~/.oat/templates/`), then bundled order and report `name`, `found`, `tier` (`repository` | `user` | `bundle`), and `path`. `path` is set only for the repository and user tiers; it is `null` for the bundled tier, so callers never depend on a package-manager path. `<name>` accepts `plan` or `plan.md` and rejects path separators and `..`. `--output <path>` copies the resolved content to that file, replacing an existing file, and does not create missing parent directories; JSON output adds the absolute `output` path. A template missing from every tier exits 1 with `found: false`. Lifecycle skills use `--output` to copy their artifact templates, so a user-scope-only install works without a repository `.oat/templates/` directory.
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
-- `oat project closeout-check <project-path> [--autonomous] [--json]` - read-only check of the closeout invariant: a closeout that must snapshot its post-implementation sequence cannot reach terminal completion until its `oat_post_implement_sequence` snapshot exists, every stored step is recorded complete, approval is recorded, and the snapshot reached `status: complete`. A snapshot is required when the effective layered `workflow.postImplementSequence` is configured, when the closeout is autonomous (`--autonomous`, or `OAT_AUTONOMOUS=1` in the environment even without the flag), or when `oat_workflow_mode` is `lite`. Once a snapshot exists its recorded state is authoritative and current configuration is not consulted. JSON output reports `status` (`complete`, `not_required`, or `incomplete`), the missing `invariant` (`snapshot_missing`, `snapshot_malformed`, `sequence_failed`, `pre_approval_step_pending`, `approval_pending`, `post_approval_step_pending`, or `sequence_not_complete`), `route` (`oat-project-implement` when incomplete), `nextOwner` (the next stored step and its skill, or the approval), and the evaluated `inputs`. An incomplete or malformed result exits 1.
-- `oat project complete-state <project-path> [--archived] [--autonomous]` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout. It first evaluates the same closeout invariant as `oat project closeout-check` and refuses, with the same message and without writing, a configured, autonomous, or lite closeout whose snapshot is absent, malformed, or incomplete. A project whose implementation finished before closeout snapshots existed recovers by running `oat-project-implement`, which persists the snapshot (`completion-and-closeout.md` Step 15) and completes its stored steps; there is no override flag. An unconfigured, interactive, non-lite closeout without a snapshot completes as before.
+- `oat project closeout-check <project-path> [--autonomous] [--json]` - read-only check of the closeout invariant: a closeout that must snapshot its post-implementation sequence cannot reach terminal completion until its `oat_post_implement_sequence` snapshot exists, every stored step is recorded complete, approval is recorded, and the snapshot reached `status: complete`. A snapshot is required when the effective layered `workflow.postImplementSequence` is configured, when the closeout is autonomous (`--autonomous`, or `OAT_AUTONOMOUS=1` in the environment even without the flag), or when `oat_workflow_mode` is `lite`. Once a snapshot exists its recorded state is authoritative and current configuration is not consulted. JSON output reports `status` (`complete`, `not_required`, or `incomplete`), the missing `invariant` (`snapshot_missing`, `snapshot_malformed`, `sequence_failed`, `pre_approval_step_pending`, `approval_pending`, `post_approval_step_pending`, or `sequence_not_complete`), `route` (`oat-project-implement` when incomplete), `nextOwner` (the next stored step and its skill, or the approval), and the evaluated `inputs`. An incomplete or malformed result exits 1. For a goal project (`oat_workflow_mode: goal`) the goal boundary is checked first and read-only: it requires `oat_goal_status: declared_met`, a valid exhaustive `oat_goal_outcome_audit`, resolved extractions, a successful `gh pr view` observation of every terminal delivery member, and delivery coverage of every accepted phase (each in a terminal delivery's effective scope with a passed, fresh integrated review and its persisted `exit_gate`); refusals report `goal_inputs_unreadable`, `goal_not_declared`, `goal_audit_invalid`, `goal_extraction_unresolved`, `goal_observation_failed`, or `goal_coverage_incomplete`, and `nextOwner` is `{ kind: "goal", skill, reasons }`, where each reason is `{ code, message, subject? }` and `skill` is the owner of the first reason: for example `not-declared` and `audit-invalid` route to `oat-project-goal`, `review-not-fresh` to `oat-project-review-provide`, `exit-carrier-not-fresh` to `oat-project-implement`, delivery and endpoint reasons such as `endpoint-unmet` to `oat-project-pr-progress`, and `phase-uncovered` to `oat-project-pr-final`. A goal snapshot may record its `pr` step as satisfied by delivery coverage (`satisfied_by: { pr: delivery-coverage }`) only once `pr` is in the completed prefix.
+- `oat project delivery refresh --project <path> [--json]` - goal only. Observes every registered delivery member with `gh pr view <url> --json state,headRefOid,baseRefOid` and persists, in `state.md`, only the observations (`observed_head`, `observed_base`, member `status`), the delivery `status` (`open` or `at_endpoint`), the first observed `endpoint_attainment`, and derived staleness (`integrated_review.disposition: stale`, the milestone exit carrier's `freshness: stale` with `freshness_reason`). It never rewrites a reviewed revision, a member base, or the first endpoint attainment, never writes `oat_milestone_status` or `oat_goal_recovery`, and never manufactures a passed review or a fresh carrier. `oat-project-pr-progress` and `oat-project-goal` run it before registration and re-alignment.
+- `oat project delivery check --project <path> --subject <mNN|dNN> [--json]` - goal only, read-only. Reports whether a milestone (before registration, against the branch head) or a registered delivery (against its observed member revisions) is deliverable: a passed integrated review that is still fresh under the bookkeeping-successor rule and an allowed, fresh milestone exit carrier (reported as `exit.source: milestone-carrier`; the closeout boundary judges each delivery's persisted `exit_gate` instead). Evidence reviewed at R covers a later head only when every intervening commit changes permitted bookkeeping in this project's tracking files (`state.md`, `plan.md`, `implementation.md`, `project-log.md`, `summary.md`) and review artifacts (including those of deliveries sharing the same member pull request); any change to `summary.md` is bookkeeping because it is derived memory, never the authority for the brief's content; code changes, edits to approved brief content, and a substantive change followed by its revert fail. JSON output carries `status` (`ok` or `undeliverable`), the subject, its ordered `scope`, `publishedHeads`, `review`, `exit`, and `deliverable`; an undeliverable subject exits 1 with the full report. A stale `review` or `exit` result carries a `reason` that starts with a code, such as `review-missing`, `review-scope-narrow`, `member-unobserved`, `base-changed`, `bound-revision-mismatch` (a bound revision differs from its member's set-once `reviewed_head`), `subject-changed`, `configuration-changed`, or a bookkeeping-successor failure: `missing-revision`, `missing-object`, `not-ancestor`, `inspection-failed`, `disallowed-path`, or `substantive-change`.
+- `oat project complete-state <project-path> [--archived] [--autonomous]` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout. It first evaluates the same closeout invariant as `oat project closeout-check` and refuses, with the same message and without writing, a configured, autonomous, or lite closeout whose snapshot is absent, malformed, or incomplete. A project whose implementation finished before closeout snapshots existed recovers by running `oat-project-implement`, which persists the snapshot (`completion-and-closeout.md` Step 15) and completes its stored steps; there is no override flag. An unconfigured, interactive, non-lite closeout without a snapshot completes as before. A goal project is also refused, without writing, by the goal boundary that `closeout-check` describes.
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive verifies the complete selected package and every immutable file byte, then atomically exports one self-contained `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>.html` page before deleting the active project. The full original package remains in the archived project. JSON `projectRecapExport` identifies `runId`, `page.sourceRelativePath`, `page.originalSha256`, `page.exportedSha256`, `verifiedArtifactCount`, and the flat `exportRoot`. No tracked sidecar is created. Matching dated pages are adopted on retry; conflicting destinations, incomplete inventory coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. Summary and PR links point to the tracked page. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes `refs/oat/completed/<project>` authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project dispatch record --event-file <json-file-or-dash>` - validate one generic dispatch record plus its namespaced OAT evidence event and print the result with `status: validated-only`. The command writes nothing; launches are recorded in the calling workflow's run record. Managed, effort-pinned Claude launches run it before launch: the input carries `claudeLaunch` with the real resolver result, generated definition, and proposed payload, plus `recordBase` and `event`. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into `recordBase`. One validation run reports every violation across `claudeLaunch`, `recordBase`, and `event` in a single error message, one `stage path: message` line each; the `recordBase` cross-field rules run even when a required field is missing, checks that need a value that failed to parse are skipped and named on a final line, secret-shaped values and absolute paths are scrubbed from the message, and the exit code stays 1. A validated input per role is published at `.agents/skills/oat-dispatch-subagents/references/managed-claude-example.json`. The command validates evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never echoed in the output, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/advanced/evidence-layers.md).
 - `oat project dispatch canonical-role --role <name> --request-id <id> --skill-dir <dir> [--json]` - resolve a canonical role through the loaded, user (`$HOME/.agents`), and project (`<repo>/.agents`) tiers and print the `canonical-role-resolution` event that `oat project dispatch record` accepts unchanged: redacted `canonicalPath` and `selectedPath` in the form `<loaded|user|project>/agents/<name>.md`, the role's `contentDigest`, and `candidateMisses`. `--skill-dir` is required because the loaded tier is derived from the loaded skill's directory; a missing or invalid directory exits 1 with a redacted error. An unknown role prints `missing` evidence with its recovery commands. Read-only; the dependency is the `workflows` pack.
-- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. See [Implementation Execution](../workflows/projects/execution/implementation-execution.md#parallel-phase-groups).
+- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. Brief plans (`oat_workflow_mode: brief`) are validated with the brief profile: phases need non-empty `**Intent:**` and `**Exit evidence:**`, a `**Provisional:**` value of `yes` or `no`, unique IDs, and a concrete first phase; `### Task` headings in a brief are reported as a warning, and taskless parallel groups are valid. Goal plans add the goal profile: `oat_plan_source: goal`, a valid `## Milestones` table (`goal-milestones-missing`, `goal-milestones-malformed`, `goal-duplicate-milestone`, `goal-milestone-empty`, `goal-milestone-unknown-phase`, `goal-phase-in-multiple-milestones`, `goal-phase-without-milestone`), no parallel group spanning milestones (`goal-group-crosses-milestone`), canonical persisted phase IDs (`goal-noncanonical-phase-id`), and no change to a shipped milestone or a registered delivery's frozen scope (`goal-shipped-milestone-changed`, `goal-delivered-scope-changed`); phases the journal marks `extracted` need no milestone. See [Implementation Execution](../workflows/projects/execution/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../workflows/projects/execution/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
 - `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews and artifact reviews default to 30 minutes, while task code reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. When post-selection work fails after the reviewer already committed a run-correlated artifact, the gate re-validates that selected snapshot through the same eligibility path rather than re-parsing whatever the path now holds, never re-dispatching, and returns the ordinary `ok` or `blocked` envelope with additive `postSelectionRecovery: true`; the artifact must still be present and unchanged for re-validation to succeed. When nothing recovers, `review_failed` names the failing sub-step in `postSelection.step` and its cause in `postSelection.code`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../workflows/advanced/workflow-gates.md).

package/assets/docs/reference/oat-directory-structure.md

@@ -322,6 +322,8 @@ Not all workflow modes require every artifact:
 - `quick`: discovery + plan + implementation (spec/design optional)
 - `import`: imported plan + implementation (spec/design optional)
 - `lite`: single-phase plan + implementation (summary/documentation optional at closeout)
+- `brief`: Project Brief in `plan.md` + per-phase journal in `implementation.md` (`references/research/` scaffolded; no discovery, spec, or design)
+- `goal`: the brief artifact set, with a `## Milestones` table in `plan.md` and the milestone state, gate carriers, delivery registry and outcome audit in `state.md`
 
 ## `.oat/repo/` structure
 

package/assets/docs/reference/project-artifacts.md

@@ -50,7 +50,7 @@ archive metadata own terminal reachability and retry identity.
 
 Mode-sensitive notes:
 
-- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`, `lite`) for routing.
+- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`, `lite`, `brief`, `goal`) for routing.
 - `plan.md` remains the canonical execution artifact across all modes.
 
 | Mode          | Core authored artifacts                                                                                                                | Optional artifacts                         |
@@ -59,6 +59,8 @@ Mode-sensitive notes:
 | `quick`       | `discovery.md`, `plan.md`                                                                                                              | Lightweight `design.md`, `spec.md`         |
 | `import`      | `references/imported-plan.md`, `plan.md`                                                                                               | `spec.md`, `design.md`                     |
 | `lite`        | Single-phase `plan.md` with Summary, Decisions, Assumptions, Out of Scope, Validation Criteria, and an explicit adaptive content shape | `summary.md` and documentation at closeout |
+| `brief`       | `plan.md` as a Project Brief (phases with Intent and Exit evidence) and `implementation.md` as the per-phase journal                   | `references/research/`, `project-log.md`   |
+| `goal`        | The brief artifacts, with a `## Milestones` table in `plan.md` and the goal fields in `state.md`                                       | `references/research/`, `project-log.md`   |
 
 Every Lite plan keeps Summary, Decisions, Assumptions, Out of Scope, and
 Validation Criteria. User-visible changes add numbered, testable Product
@@ -75,6 +77,75 @@ implementation-then-regression, static/build, or manual/visual. Static or build
 checks alone fit only changes that cannot affect runtime behavior; every
 behavioral change needs evidence that fails without the change.
 
+In brief mode, `plan.md` is the Project Brief: Goal, numbered Outcomes (each
+naming its intended evidence), Approach with an optional `### Design`,
+Constraints and Out of Scope, Decisions, Known Unknowns, Delivery endpoint and
+authority, an empty `## Milestones` section reserved for goal mode, and
+`## Phase pNN:` blocks with `**Intent:**`, `**Exit evidence:**`, and
+`**Provisional:**` lines instead of tasks. `implementation.md` is the
+per-phase journal: each phase section carries exact `**Status:**`,
+`**Base:**`, `**Head:**`, and `**Executor:**` marker lines, followed by
+`### Task pNN-tNN` execution records opened as work happens. Progress counts
+phase-units, and `**Status:** completed` under a phase heading is what accepts
+it. The journal's Final Summary adds an `**Outcomes audit:**` block with one
+line per numbered Outcome. When a brief artifact gate is configured,
+`state.md` records its outcome as `oat_brief_gate`, with the same core fields
+as `oat_quick_start_gate`.
+
+In goal mode, `plan.md` is the same Project Brief with a filled
+`## Milestones` table: one `| Milestone | Phases |` row per milestone listing
+its ordered phase IDs, every phase (revision phases included) in exactly one
+milestone. Later milestones are appended at re-alignment, and a phase frozen in
+a registered delivery is never removed or reassigned. `state.md` adds the
+goal fields:
+
+- `oat_milestone` and `oat_milestone_status` (`aligning`, `implementing`,
+  `reviewing`, `delivering`, `delivered`), the active milestone;
+- `oat_goal_status` (`active` or `declared_met`) and
+  `oat_goal_outcome_audit`, the exhaustive per-phase and per-outcome audit
+  written at the terminal declaration;
+- `oat_goal_recovery`, the record of an interrupted recovery, which may target
+  an older milestone without moving the active one;
+- `oat_milestone_gates`, one `plan` and one `exit` gate carrier per
+  milestone; and
+- `oat_deliveries`, the delivery registry: one entry per delivery (`dNN`) with
+  its milestone, frozen phase scope, agreed endpoint, status, member pull
+  requests and their observed revisions, the integrated review it was
+  delivered on, its exit-gate binding and the first observed endpoint
+  attainment. A delivery's `status` is `registering`, `open`, `at_endpoint`,
+  or `superseded`, and its agreed `endpoint` is `open` or `merged`. A
+  replacement delivery names its one direct predecessor in `covers_scope_of`,
+  and the predecessor's `superseded_by` points back; only a delivery that never
+  reached its agreed endpoint may be replaced. A correction of a delivery that
+  did reach it is additive (`corrects_delivery_id`, new phase IDs, no inherited
+  coverage). `oat_pr_status` and `oat_pr_url` project the latest member pull
+  request.
+
+Delivery evidence stays fresh across later commits that change only bookkeeping:
+`state.md`, `plan.md` (outside its approved content), `implementation.md`,
+`project-log.md` appends, `summary.md`, and the review artifacts of the
+delivery and of any delivery sharing its pull request.
+
+A delivery's evidence identity is set once: its `exit_gate`, its
+`integrated_review` identity (`artifact`, `scope`, `bound_revisions`), and each
+member's `reviewed_head`. They change only in a commit that records a new
+review artifact of that delivery, one its own `## Reviews` rows name and never
+a sharing delivery's; any other change to them is not bookkeeping. A bound
+revision that disagrees with its member's `reviewed_head` is not fresh
+(`bound-revision-mismatch`).
+
+`oat project delivery refresh` writes only observations and derived staleness
+into `oat_deliveries` and the milestone carriers. The terminal declaration is
+recorded as one `**Goal declared met:**` line in the journal's Final Summary.
+
+Extraction of goal work into another project is manual. A phase moved to a
+linked project gets `**Extracted to:** <slug>` in the brief and the marker pair
+`**Status:** extracted` / `**Extracted to:** <slug>` in the journal, and the
+child project records `oat_extracted_from: <goal slug>` in its `state.md`. The
+brief and journal targets must match. The outcome audit requires the child to
+be complete or its outstanding obligation to carry an approved deferral, and
+promotion of the goal to quick refuses any extracted phase.
+
 ## Blockers in state.md
 
 `oat_blockers` accepts legacy reason strings and structured workflow records:

package/assets/docs/reference/project-state-machine.md

@@ -17,8 +17,8 @@ This page is the compact contract for how project lifecycle state and review sta
 
 === "Diagram"
 
-    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite enters at planning](/diagrams/project-state-machine-light.svg)
-    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite enters at planning](/diagrams/project-state-machine-dark.svg)
+    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite, brief and goal enter at planning](/diagrams/project-state-machine-light.svg)
+    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite, brief and goal enter at planning](/diagrams/project-state-machine-dark.svg)
 
 === "Mermaid source"
 
@@ -41,11 +41,14 @@ This page is the compact contract for how project lifecycle state and review sta
       PASSED --> I
 
       LITE["Lite: batched interview\n(no discovery/spec/design)"] -. entry point .-> P
+      BRIEF["Brief or goal: interview\n(one Project Brief)"] -. entry point .-> P
     ```
 
-The solid chain is the spec-driven progression. Lite enters at **Plan in
-progress** and never sets `oat_phase` to `discovery`, `spec`, or `design`;
-quick and import projects also skip part of the leading chain.
+The solid chain is the spec-driven progression. Lite, brief and goal enter at
+**Plan in progress** and never set `oat_phase` to `discovery`, `spec`, or
+`design`; quick and import projects also skip part of the leading chain. Goal
+adds a milestone state machine inside implementation, described under
+[Goal progression](#goal-progression).
 
 ## Phase status values
 
@@ -92,6 +95,52 @@ project promote <project-path> --to quick`, which flips `oat_workflow_mode` to
 `quick` and sets `oat_phase: discovery` with `oat_phase_status: complete`. See
 [Lifecycle](../workflows/projects/lifecycle.md#promoting-a-lite-project-to-quick).
 
+Brief progression:
+
+1. Plan in progress (`oat_workflow_mode: brief`, `oat_phase: plan`) — `oat-project-brief` owns the interview, the artifact review, any configured gate, and the single approval
+2. Ready for implement (`plan.md` complete and pointing to `oat-project-implement`)
+3. Implement in progress — progress counts phase-units; a phase is accepted only by `**Status:** completed` under its heading in `implementation.md`
+4. Implement complete (final review passed). While any phase-unit is provisional or unaccepted, the router's brief-unit guard sends the project back to `oat-project-implement` ("Incomplete phase-units remain in the active scope") before every later check
+5. PR open (`pr_open`) through the same post-implementation sequence as quick
+6. Complete
+
+A brief project can move to the quick chain with `oat project promote
+<project-path> --to quick`; quick plan readiness stays false while
+`oat_promotion_pending_phases` lists phases that still need tasks. See
+[Lifecycle](../workflows/projects/lifecycle.md#promoting-a-brief-project-to-quick).
+
+### Goal progression
+
+A goal project runs the brief chain once per milestone. `oat_phase` and
+`oat_phase_status` keep their meaning; the milestone loop lives in its own
+`state.md` fields, owned as follows:
+
+| `oat_milestone_status` | Meaning                                                  | Next owner and transition                                                                                                                                                                                                                                                                                        |
+| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `aligning`             | The next milestone is being planned or awaits activation | `oat-project-goal` activates it (`implementing`) after review, its `plan` carrier, approval, and the previous delivery observed at its agreed endpoint                                                                                                                                                           |
+| `implementing`         | The milestone's phase-units are executing                | Implement's milestone closeout runs the `exit` gate and writes `reviewing`                                                                                                                                                                                                                                       |
+| `reviewing`            | The exit carrier is fresh; the integrated review is next | `oat-project-review-receive` writes `delivering` on a clean receive of the integrated review, or `implementing` when fixes are queued                                                                                                                                                                            |
+| `delivering`           | A passed, fresh integrated review and exit carrier       | `oat-project-pr-progress` registers the delivery (`dNN`) and writes `delivered`; stale evidence sends it back to `reviewing`; `oat-project-review-receive` returns it to `implementing` when a delivery-time review queues fixes                                                                                 |
+| `delivered`            | The delivery is registered, open and review-ready        | `oat-project-goal` re-aligns (`aligning` for the next milestone) once the delivery reaches its endpoint, or records the terminal declaration; `oat-project-pr-progress` returns it to `reviewing` when `oat-project-goal` hands back a stale delivery whose integrated review or exit carrier is no longer fresh |
+
+`oat_goal_status` is `active` until the user declares the goal met
+(`declared_met`) with an exhaustive `oat_goal_outcome_audit`. Recovery of an
+older milestone's delivery is recorded in `oat_goal_recovery` and never moves
+`oat_milestone` or its status. `oat-project-revise` may return the active
+milestone from `delivered` or `delivering` to `implementing` for inline
+feedback. The router reads only these persisted fields; delivery freshness
+comes from `oat project delivery refresh` and `oat project delivery check`.
+
+`delivered` and the registry's `at_endpoint` are different: `delivered` means
+the pull request is registered and open, `at_endpoint` means it has reached
+the agreed endpoint (`open` or `merged`). Re-alignment may draft and approve
+the next milestone while a `merged` endpoint is pending, but activation waits
+for it. Terminal closeout (`oat project closeout-check`,
+`oat project complete-state`) requires the declaration, the audit and delivery
+coverage of every accepted phase. A goal project can move to quick at a settled
+delivery boundary; see
+[Lifecycle](../workflows/projects/lifecycle.md#promoting-a-goal-project-to-quick).
+
 ## Review progression
 
 In `plan.md` Reviews table:
@@ -105,5 +154,5 @@ Do not move to the next lifecycle state if review/state artifacts indicate unres
 ## Reference artifacts
 
 - `.oat/projects/<scope>/<project>/state.md`
-- `.oat/projects/<scope>/<project>/plan.md` (`## Reviews`)
+- `.oat/projects/<scope>/<project>/plan.md` (`## Reviews`, and `## Milestones` for goal)
 - `.oat/projects/<scope>/<project>/implementation.md`

package/assets/docs/skills/brainstorm.md

@@ -47,7 +47,9 @@ instead). Saving a brainstorming reference file under the active project also
 commits or pushes that file. Promoting to a new project runs
 `oat project new`, which scaffolds the project and makes it your active
 project, and then writes a completed `discovery.md` (or, for a lite project,
-fills in its `plan.md`). Capturing a new idea also sets it as your active
+fills in its `plan.md`; for a brief or goal project, writes a research note
+under `references/research/` and leaves the brief to `oat-project-brief` or
+`oat-project-goal`). Capturing a new idea also sets it as your active
 idea in local OAT config. Each destination is confirmed before anything is
 written.