@open-agent-toolkit/cli 0.3.17 → 0.3.19

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

@@ -150,7 +150,7 @@ 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, and lite accept their mode-appropriate reduced artifacts. The latest
+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`.
 Autonomous execution stops if it is not passed. Interactive execution warns
 and asks before proceeding anyway.
@@ -378,7 +378,9 @@ 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 projects do not require discovery, spec, or design.
+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.
 
 **Example scenario:** Export filters shipped, but the user guide still describes
 only unfiltered exports. Document verifies the actual endpoint and CLI behavior,
@@ -430,7 +432,10 @@ Summarize the delivered export filters, the date-format decision, and the audit-
 completed task. Missing implementation tracking blocks summary generation.
 With no completed tasks, the process warns that the summary will be minimal.
 Lite uses its plan contract and implementation results without requiring
-discovery, spec, or design artifacts.
+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.
 
 **Example scenario:** The first export phase is delivered, and another engineer
 will own the reporting phase next week. Summary records the shipped filter

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

@@ -18,11 +18,13 @@ Expected artifacts:
 - Required (spec-driven mode): `spec.md`, `design.md`
 - 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
 - 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`
 
 ## Output

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

@@ -92,14 +92,26 @@ 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 project, the first run lists
+**Questions on the first run:** Except in a lite or brief 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
 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.
+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.
+
+**Brief projects:** Each `## Phase pNN:` block in the brief is one
+phase-unit with Intent and Exit evidence instead of planned tasks. The root
+records the phase's `**Base:**` in a phase-start commit before dispatch, the
+committing owner opens `### Task pNN-tNN` execution records in
+`implementation.md` as work happens and writes `**Head:**` when the phase's
+work ends, a fresh reviewer reviews the anchored `Base..Head` range, and only
+the root writes `**Status:** completed` once review dispositions and selected
+gates settle. Progress and the next-phase decision count phase-units, never
+records.
 
 **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,

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

@@ -16,6 +16,10 @@ 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
+  evidence instead of tasks; execution records are opened in the journal as
+  work happens, and the phase's `**Base:**`/`**Head:**` anchors scope its
+  review.
 - **Prevention boundary:** formatting, declared task verification, and
   applicable cheap checks run before the task commit.
 - **Recovery boundary:** an eligible post-commit defect may produce a separate
@@ -514,6 +518,17 @@ and declare no parallel groups, so lite implementation is always sequential;
 `oat project validate-plan` enforces both rules. Work that needs more than one
 phase should promote to quick rather than declare a parallel group.
 
+Brief plans may declare parallel groups of taskless phases once those phases
+are concrete and pass the independence test (no shared files, state,
+generated output, fixtures, or services, and no sequential dependency). A
+group member's per-phase review runs before fan-in on
+`EXPECTED_HEAD..<worktree head>`. At fan-in the root writes every member's
+`**Base:**` as the group's fork commit and its `**Head:**` as the member's
+integration head, which is normally a merge commit but may be the last
+cherry-picked commit; review scope checks only the shared fork base and that
+member heads advance in document order. The fan-in anchors govern the
+`pNN-pMM` and `final` review scopes.
+
 ## Synced projects in worktrees
 
 A tracked `.oat/projects/synced/<project>.json` record lets every repository

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 and imported projects never
+   whatever the project's mode; quick, lite, brief 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
@@ -81,6 +81,15 @@ durable `## Reviews` disposition, and a substantive task; only then do they
 recommend `oat-project-implement`. Recommendations for lite, spec-driven, and
 import projects are unchanged, because the predicate is quick-workflow policy.
 
+For a brief project, the router counts phase-units from the journal. While the
+brief is not yet approved, it recommends `oat-project-brief`. After
+implementation, while any phase is provisional or not yet accepted with
+`**Status:** completed`, it recommends `oat-project-implement` ("Incomplete
+phase-units remain in the active scope") before every later check. The
+`.oat/state.md` dashboard does not read phase-units, so at the end of
+implementation it prints a note that `oat project status` and
+`oat-project-next` are the authority for brief projects.
+
 ## What travels
 
 - The project ref carries the complete active artifact tree and its history.

package/assets/docs/workflows/projects/execution/project-log.md

@@ -71,6 +71,28 @@ oat project log append \
 Structural entries require `--structural`, `--producer`, `--ref`, and `--body`.
 Do not combine structural flags with judgment flags.
 
+### Preview an append
+
+Validate an entry against the current project state before appending it:
+
+```bash
+oat project log append --dry-run \
+  --project .oat/projects/shared/example \
+  --type friction --scope project --area "gate review handoff" \
+  --body "The gate passed but the handoff was missing, so review receipt stopped."
+```
+
+The preview reports whether it would append, create the log, recognize a replay,
+or skip a disabled missing log. It writes no files, acquires no locks, and makes
+no Git changes. `--dry-run --commit` also validates an existing recovery receipt
+without committing or removing it. A would-create preview checks compatible
+bundled assets and validates the template in memory; an existing log does not
+need assets. Sealed logs and invalid entries retain normal append diagnostics.
+
+This is advisory validation of current state. It reserves nothing and does not
+guarantee later permissions, disk space, hook success, or the absence of other
+writers. A normal append validates again under its required lock.
+
 ### Idempotent append and commit
 
 Two optional flags let an interrupted append be replayed safely:

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, and import paths.'
+description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, lite, brief, 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, and import lanes.
+- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick, lite, brief, 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-import-plan`, `oat-project-implement`
+- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-lite`, `oat-project-brief`, `oat-project-import-plan`, `oat-project-implement`
 
 ## Lifecycle Map
 
@@ -51,9 +51,9 @@ 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, import, and capture
-lanes each skip part of it — see [Lane diagrams](#lane-diagrams) below. Lite in
-particular has no discovery, spec, or design step at all.
+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.
 
 ## Post-implementation flow
 
@@ -337,6 +337,14 @@ See [Implementation Execution](execution/implementation-execution.md) for the fu
 3. Pass the mandatory final review, then route directly to `oat-project-pr-final`
 4. Optional `oat project promote <project-path> --to quick` when the work no longer fits one sitting
 
+### Brief lane steps
+
+1. `oat-project-brief` runs a design-aligned interview in readiness rounds, writes one Project Brief in `plan.md` (Goal, numbered Outcomes, Approach, Constraints and Out of Scope, Decisions, Known Unknowns, Delivery endpoint and authority, and `## Phase pNN:` blocks with Intent and Exit evidence), commits it, runs the independent artifact review and any configured `oat-project-brief` gate, and asks for one approval
+2. Implement: `oat-project-implement` executes one phase-unit at a time (or a declared parallel group), opening `### Task pNN-tNN` execution records in `implementation.md` as work happens and recording each phase's `**Base:**` and `**Head:**` anchors
+3. A fresh independent review of each phase on its anchored range, then the final review, whose scope comes from the anchors; completion is audited against the brief's Outcomes
+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
+
 ### 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)
@@ -495,6 +503,62 @@ sections, an unresolved scope, or an unreadable template each return a stable
 categorical `reason` and exit non-zero. See
 [CLI Reference](../../reference/cli-reference.md) for the full refusal contract.
 
+### Brief lane
+
+=== "Diagram"
+
+    ![Brief lane: a design-aligned interview, one reviewed and approved Project Brief, phase-units executed with execution records and anchors, a fresh review per phase, final review audited against Outcomes, and PR, with promotion to quick when a task plan is wanted](/diagrams/project-lifecycle-8-brief-lane-light.svg)
+    ![Brief lane: a design-aligned interview, one reviewed and approved Project Brief, phase-units executed with execution records and anchors, a fresh review per phase, final review audited against Outcomes, and PR, with promotion to quick when a task plan is wanted](/diagrams/project-lifecycle-8-brief-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      A["Alignment interview\n(readiness rounds)"] --> B["Project Brief\n(review, gate, one approval)"]
+      B --> I["Phase-units\n(oat-project-implement)"]
+      I --> PR["Per-phase review\n(anchored range)"]
+      PR -->|Next phase| I
+      PR --> F["Final review\n(audited against Outcomes)"]
+      F --> P["PR (oat-project-pr-final)"]
+      B -->|Task plan wanted| Q["Promote to Quick"]
+    ```
+
+A brief project has one authored artifact: the Project Brief in `plan.md`.
+Each `## Phase pNN:` block is one **phase-unit** with `**Intent:**`,
+`**Exit evidence:**`, and `**Provisional:**` lines; only the next phase must
+be concrete, and the agent may add, split, or reorder phases inside the
+approved outcomes, constraints, and authority. Progress counts phase-units, and
+a phase counts as complete only when the root writes `**Status:** completed`
+under it in `implementation.md` after its review and any selected gate settle.
+Tasks are execution records written as work happens, never a plan, so they
+never change progress totals.
+
+Each phase records `**Base:**` before work starts and `**Head:**` when its work
+ends. Reviews take their range from those anchors rather than from commit
+messages; invalid or contradictory anchors stop and route to
+`oat-project-reconcile`. A fix after a later phase has started becomes an
+appended `p-revN` revision phase. The shared rules live in the bundled brief
+contract (`oat-project-brief/references/brief-contract.md`).
+
+### Promoting a brief project to quick
+
+`oat project promote <project-path> --to quick` converts a brief in place, and
+there is no reverse direction. Accepted phases keep their completed execution
+records as quick tasks (or get one synthesized `Accepted via phase evidence`
+task against the phase head), active phases keep their completed records, and
+pending or provisional phases stay taskless. The command lists the phases that
+still need tasks in `oat_promotion_pending_phases`, and quick plan readiness
+stays false until `oat-project-quick-start` authors them. The brief's
+sections are rendered into `discovery.md` and the original is archived to
+`references/brief-archive.md`.
+
+Promotion writes nothing and refuses with a categorical reason when
+`references/brief-archive.md` already exists (`brief-archive-exists`), a
+journal phase is `extracted` (`extracted-phases`), the brief has no parseable
+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).
+
 ### Import lane
 
 === "Diagram"
@@ -604,15 +668,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 three modes: `lite`, `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`.
+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`.
 
-This is a parallel entry path into all three 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.
+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.
 
 ### 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 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; 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,6 +60,22 @@ 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 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
+`oat-project-implement` then writes:
+
+```yaml
+oat_auto_review_at_hill_checkpoints: false # brief: no checkpoints
+```
+
+and skips the workflow preference check and the first-run checkpoint question.
+To opt in, record an explicit phase array such as `['p03']`; implementation
+keeps it without re-asking and pauses after exactly those phases. The
+per-phase reviews and the final review run either way.
+
 The rest of this section applies to `spec-driven`, `quick`, and `import`
 projects.
 
@@ -125,7 +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, so it does not apply to them.
+have no checkpoints, and brief projects have none unless they list phases
+explicitly, so it does not apply to them.
 
 | Choice             | Choose it when                                    | What you give up                             |
 | ------------------ | ------------------------------------------------- | -------------------------------------------- |

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

@@ -13,7 +13,7 @@ For a spec-driven project (one using the full workflow: discovery, design, plan,
 then implementation), the usual path is discovery, then design, then plan.
 Design confirms requirements and produces `spec.md` as well as `design.md`.
 Standalone spec is optional when you want to review requirements before
-designing. Quick, lite, and import workflows author their own plans through
+designing. Quick, lite, brief, and import workflows author their own plans through
 their entry skills. Do not send those projects through spec-driven planning
 just because they contain a file named `plan.md`.
 
@@ -55,8 +55,8 @@ A _HiLL (human-in-the-loop lifecycle) checkpoint_ is a point where a skill stops
 and waits for your explicit approval before marking a phase complete. Projects
 created with `oat-project-new` have HiLL approvals on discovery and design **by
 default**: each skill stops after writing its artifact and waits for your
-explicit approval before marking it complete. Quick, lite, and import projects
-have no workflow-phase HiLL checkpoints. Configured exit gates (optional reviews
+explicit approval before marking it complete. Quick, lite, brief, and import
+projects have no workflow-phase HiLL checkpoints. Configured exit gates (optional reviews
 or commands your repository runs before a skill marks its work complete) can
 also keep an artifact in progress. See [HiLL checkpoints](hill-checkpoints.md).
 The [skill catalog](../../../skills/index.md) lists the broader lifecycle tools.
@@ -83,7 +83,7 @@ spec-driven project. The repository knowledge index must exist at
 `oat-repo-knowledge-index` first. The skill checks knowledge staleness and asks
 whether to refresh or continue when the index is stale.
 
-Quick, import, and lite projects use their own next step instead. Mentioning a
+Quick, import, lite, and brief projects use their own next step instead. Mentioning a
 new idea does not authorize automatic discovery invocation.
 
 **Example scenario:** The webhook-delivery project is active, but the team has
@@ -270,11 +270,12 @@ skill asks for a project name and sets it as the active project. The project
 must use spec-driven mode, with `design.md` recording `oat_status: complete` and
 `oat_ready_for: oat-project-plan`.
 
-Quick, import, and lite projects never use this skill to author a plan. On a
+Quick, import, lite, and brief projects never use this skill to author a plan. On a
 quick project, it resumes quick-start if the plan is not ready, and **starts
 `oat-project-implement` immediately** if the plan is ready. On an import project
 with a plan, it points you to `oat-project-implement`. On a lite project, it
-points you to `oat-project-lite`. Do not invoke it on those projects unless you
+points you to `oat-project-lite`. On a brief project, it stops and points you
+to `oat-project-brief`, which owns the Project Brief. Do not invoke it on those projects unless you
 intend that handoff.
 
 **Example scenario:** The webhook design now defines persistence, retries, and
@@ -338,14 +339,14 @@ Promote the active cache-refresh project, keeping its imported plan and complete
 skill asks for a project name and sets it as the active project. The active
 project's `state.md` must record quick or import workflow mode. A spec-driven
 project is already promoted, so the skill reports a no-op unless you request
-artifact refresh. Lite must promote to quick first through the actual terminal
-command:
+artifact refresh. Lite and brief projects must promote to quick first through
+the actual terminal command:
 
 ```bash
-oat project promote <lite-project-path> --to quick
+oat project promote <lite-or-brief-project-path> --to quick
 ```
 
-Use the reported lite project path, for example
+Use the reported project path, for example
 `.oat/projects/synced/retry-message` in the default synced scope. Then use this
 skill against the active quick project.
 

package/assets/docs/workflows/projects/planning/starting-projects.md

@@ -7,17 +7,18 @@ description: 'Choose a project entry skill, import an existing plan, capture com
 
 Choose an entry path based on what you already know and what already exists.
 These skills do not require an existing active project. They create or import
-tracked work, although quick-start and lite resume an active project of their
-own mode, and import writes into whichever project is active.
-
-| Your situation                                                     | Entry skill               | Result                                                                         |
-| ------------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------ |
-| Requirements need discovery and a full technical design.           | `oat-project-new`         | A spec-driven scaffold, ready to begin discovery.                              |
-| The outcome is bounded, with optional design decisions to resolve. | `oat-project-quick-start` | Discovery and an executable plan, with lightweight design when needed.         |
-| The change fits one implementation sitting.                        | `oat-project-lite`        | One approved plan with requirements and validation criteria.                   |
-| You already have a Markdown plan.                                  | `oat-project-import-plan` | The original source preserved beside a normalized OAT plan.                    |
-| Implementation happened without project tracking.                  | `oat-project-capture`     | Retroactive discovery and implementation records from the session and commits. |
-| A confirmed scope contains several coordinated projects.           | `oat-project-split`       | A coordination parent and children that resume at discovery.                   |
+tracked work, although quick-start, lite, and brief resume an active project of
+their own mode, and import writes into whichever project is active.
+
+| Your situation                                                       | Entry skill               | Result                                                                            |
+| -------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------- |
+| Requirements need discovery and a full technical design.             | `oat-project-new`         | A spec-driven scaffold, ready to begin discovery.                                 |
+| The outcome is bounded, with optional design decisions to resolve.   | `oat-project-quick-start` | Discovery and an executable plan, with lightweight design when needed.            |
+| The change fits one implementation sitting.                          | `oat-project-lite`        | One approved plan with requirements and validation criteria.                      |
+| One delivery whose outcome and design you can agree in conversation. | `oat-project-brief`       | One reviewed, approved Project Brief whose phases carry intent and exit evidence. |
+| You already have a Markdown plan.                                    | `oat-project-import-plan` | The original source preserved beside a normalized OAT plan.                       |
+| Implementation happened without project tracking.                    | `oat-project-capture`     | Retroactive discovery and implementation records from the session and commits.    |
+| A confirmed scope contains several coordinated projects.             | `oat-project-split`       | A coordination parent and children that resume at discovery.                      |
 
 For the broader mode decision, see [Choose a workflow](../../choose-workflow.md).
 For an existing project's discovery, design, or plan, see
@@ -68,15 +69,15 @@ in a fresh repository.
    overrides the setting for one shell.
 
 3. **Only `oat-project-new` takes a scope.** It accepts `--scope shared|local|synced`.
-   Quick-start, lite, import, capture, and split have no scope argument.
-   Quick-start, lite, import, and capture always create projects in the
+   Quick-start, lite, brief, import, capture, and split have no scope argument.
+   Quick-start, lite, brief, import, and capture always create projects in the
    default scope. Split uses the active project's scope, or `shared` when no
    project is active. Set the default first if you do not want `synced`.
 
 4. **Build the knowledge index before spec-driven discovery.** `oat-project-discover`
    refuses to start until `.oat/repo/knowledge/project-index.md` exists. Run
    `/oat-repo-knowledge-index` once before your first spec-driven project.
-   Quick-start, lite, import, and capture do not check for it.
+   Quick-start, lite, brief, import, and capture do not check for it.
 
 5. **Know what happens when a project is already active.** Check with
    `oat config get activeProject` before you start:
@@ -88,6 +89,9 @@ in a fresh repository.
    - `oat-project-lite` resumes an active lite project and ignores the name and
      description you pass. With any other project active, it creates a new lite
      project.
+   - `oat-project-brief` resumes an active brief project at the earliest step
+     whose output is missing. With any other project active, it creates a new
+     brief project.
    - `oat-project-import-plan` writes into any active project, whatever its
      mode. It rewrites that project's `plan.md` and switches it to import mode.
    - `oat-project-split` makes its first child the active project.
@@ -106,14 +110,14 @@ Project creation normally activates the new project in `.oat/config.local.json`.
 Check the reported project path before continuing, especially when another
 project is already active.
 
-The new, quick-start, lite, and import skills check inherited Git changes before
+The new, quick-start, lite, brief, and import skills check inherited Git changes before
 scaffolding. Unrelated changes require an explicit disposition in interactive
 runs. One exception: if the only change is `.oat/sync/manifest.json`, it is
 committed automatically as `chore: run sync`. Capture does not run this check.
 Do not assume starting a project also authorizes implementation or a PR.
 
-**Dispatch policy.** Before a plan is marked ready, quick-start, lite, and
-import ask you to choose a _dispatch policy_: the highest tier of models and
+**Dispatch policy.** Before a plan is marked ready, quick-start, lite, brief,
+and import ask you to choose a _dispatch policy_: the highest tier of models and
 effort OAT may use when it dispatches implementation and review agents. The
 choices come from `oat project dispatch-ceiling choices`. If your configuration
 has no complete dispatch ladder (the list of models for each tier), the skill
@@ -125,9 +129,10 @@ deliberately. The plan stays not ready until this resolves. See
 **Approval checkpoints.** A _HiLL (human-in-the-loop lifecycle) checkpoint_ is
 a point where a skill stops and waits for your explicit approval before it marks
 a phase complete. Projects created by `oat-project-new` have checkpoints on
-discovery and design by default. Quick, lite, import, and captured projects have
-no workflow-phase checkpoints before implementation. Lite still asks you to
-approve its plan once. See [HiLL checkpoints](hill-checkpoints.md).
+discovery and design by default. Quick, lite, brief, import, and captured
+projects have no workflow-phase checkpoints before implementation. Lite still
+asks you to approve its plan once, and brief asks you to approve its reviewed
+brief once. See [HiLL checkpoints](hill-checkpoints.md).
 
 Several skills also run a configured _exit gate_, an optional review or command
 your repository configures to run before a skill marks its work complete. When
@@ -299,6 +304,73 @@ keeping or disabling configured gates for this project.
 **Next step:** Run `oat-project-implement` after the approved lite plan is ready.
 If the scope grows, continue through `oat-project-quick-start` after promotion.
 
+## oat-project-brief
+
+Use brief for one delivery whose outcome and design you can agree in
+conversation. Brief replaces discovery, design, and a task plan with one
+reviewed Project Brief in `plan.md`. Its phases state intent and exit evidence
+instead of tasks.
+
+**Invocation:** Provide the slug and the intended outcome.
+
+```text
+/oat-project-brief export-audit "Let administrators export the audit log as CSV from the settings page."
+```
+
+**Prerequisites:** No active project is needed. If the active project is a
+brief project, brief resumes it in place.
+
+**Example scenario:** Administrators need the audit log as CSV. Brief
+interviews you in short rounds, settling facts from the code itself and
+putting the design choices to you, such as streaming against buffering the
+export. It writes the agreed outcomes, approach, decisions, and phases into the
+brief, runs artifact review and any configured gate, and asks you to approve
+the reviewed brief once.
+
+**Expected output:** One Project Brief in `plan.md` with a Goal, numbered
+Outcomes that each name their evidence, the Approach (with an optional
+`### Design` subsection), Constraints and Out of Scope, Decisions with the
+alternatives you rejected, Known Unknowns with the phase that settles each,
+the Delivery endpoint and authority, and `## Phase pNN:` blocks. Each phase
+states its `**Intent:**`, `**Exit evidence:**`, and whether it is
+`**Provisional:**`; only the first phase has to be concrete now. The skill also
+initializes `implementation.md` as a per-phase journal with one section per
+phase and no execution records yet. There is no `discovery.md`, `spec.md`, or
+`design.md`, and no task list: tasks are recorded in the journal as the work
+runs.
+
+The interview runs in readiness rounds. The agent settles facts from the code,
+docs, or research itself and brings you only decisions, each with a
+recommendation and its tradeoff. It writes the brief once you have explicitly
+agreed the design, so the approval confirms a design you already accepted.
+Within the approved outcomes, constraints, and authority, the agent may later
+add, split, or reorder phases and make provisional phases concrete, and logs
+each change; a change to an Outcome, a Constraint, the authority, the endpoint,
+a Decision, or the Approach comes back to you first.
+
+**What it does without asking:** It creates the project through
+`oat project new --mode brief` in the default scope and makes it active,
+commits the authored brief before any review, runs the independent artifact
+review (the reviewer receives the brief and the bundled brief contract, not the
+conversation), runs any configured `oat-project-brief` gate and records its
+outcome as `oat_brief_gate` in `state.md`, and commits the approved brief and
+journal. In synced scope each commit is an `oat project push` to `origin`. It
+asks before: proceeding with a dirty working tree, the interview decisions,
+adopting a dispatch ladder into config, choosing the dispatch policy, keeping
+or disabling configured gates for this project, and the single approval
+(approve, revise, or promote to quick).
+
+**Promotion to quick.** Choose promote at the approval, or later run
+`oat project promote <project-path> --to quick`, when you want a maintained,
+approved up-front task plan. Promotion keeps completed execution records as
+quick tasks, lists phases that still need tasks in
+`oat_promotion_pending_phases`, and hands off to `oat-project-quick-start`.
+Before the brief is written and committed there is nothing to promote: abandon
+the scaffold and start `oat-project-quick-start` instead. See
+[Lifecycle](../lifecycle.md#promoting-a-brief-project-to-quick).
+
+**Next step:** Run `oat-project-implement` after the brief is approved.
+
 ## oat-project-import-plan
 
 Use import when the plan already exists, including one produced in a provider's

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

@@ -176,7 +176,7 @@ This feature is opt-in and disabled by default (missing or `enabled: false`). Fo
 
 Generated planning and analysis artifacts have a separate review loop from code/phase reviews.
 
-For plans, `oat-project-plan`, `oat-project-quick-start`, `oat-project-lite`, and `oat-project-import-plan` run a bounded `plan.md` artifact review before marking the plan ready for implementation. The loop dispatches `oat-reviewer` in structured-output artifact mode with `scope: plan`, applies unambiguous Critical and High artifact-local fixes, offers Medium and Low fixes, and re-runs until clean or the retry bound is exhausted. A clean result records the `plan` row in the plan's `## Reviews` table as `passed`.
+For plans, `oat-project-plan`, `oat-project-quick-start`, `oat-project-lite`, `oat-project-brief`, and `oat-project-import-plan` run a bounded `plan.md` artifact review before marking the plan ready for implementation. The loop dispatches `oat-reviewer` in structured-output artifact mode with `scope: plan`, applies unambiguous Critical and High artifact-local fixes, offers Medium and Low fixes, and re-runs until clean or the retry bound is exhausted. A clean result records the `plan` row in the plan's `## Reviews` table as `passed`.
 
 For analysis artifacts, `oat-docs-analyze` and `oat-agent-instructions-analyze` run a bounded accuracy review after writing their severity-rated artifacts. The reviewer checks cited evidence, severity, and recommendations before the matching apply workflow consumes the artifact. The analysis loop updates tracking metadata to mark the artifact verified.
 
@@ -220,6 +220,18 @@ See [Workflow preferences in the Configuration guide](../../../reference/configu
 
 Use phase-scoped review artifacts during implementation (`p01`, `p02`, etc), then run final review before project closeout.
 
+In a brief project, review scope comes from the journal's anchors instead of
+commit-message inference. A phase scope is its `**Base:**..**Head:**` range, a
+`pNN-pMM` run spans the first selected base through the last selected head,
+and `final` covers every accepted phase, including `p-revN` revision phases.
+The review artifact records the requested scope, the ordered phase IDs, the
+base SHA, and `oat_review_scope_source` (`anchors`, or `merge-base-range` when
+anchors are missing and the range widens to the confirmed merge-base range).
+Commit-message matches only label commits and never narrow the range. Invalid
+or contradictory anchors stop the review and route to `oat-project-reconcile`.
+A brief `final` review also audits every numbered Outcome against the
+journal's evidence.
+
 Final review `passed` gate requires:
 
 - No unresolved Critical/High/Medium findings.
@@ -455,7 +467,8 @@ An artifact review loop runs in the same agent session that wrote the artifact,
 so it is not an independent review. It retries up to the project's retry limit,
 which defaults to two; a limit of zero still allows the first review. Autonomous
 runs turn on review at HiLL checkpoints for every project except lite projects,
-which have no checkpoints.
+which have no checkpoints, and brief projects without explicitly listed
+checkpoint phases.
 
 - If you are a solo developer, or runs are unattended, and your agent tool
   supports subagents, set the final review execution to `subagent`.

package/assets/docs/workflows/projects/reviews/review-flavors.md

@@ -119,7 +119,8 @@ different things can happen, and only two of them stop the workflow:
 - **Operational failures stay blocked.** The reviewer could not start, timed
   out without writing a review, or wrote a review OAT could not validate or
   match to this run. Nothing was reviewed. `oat-project-implement` and
-  `oat-project-lite` keep these failures blocked whatever `onFailure` says.
+  `oat-project-lite` keep these failures blocked whatever `onFailure` says,
+  and so does `oat-project-brief`.
   The planning skills handle them differently; see
   [When the gate finds blocking problems](../../advanced/workflow-gates.md#when-the-gate-finds-blocking-problems).
 - **Reviewer selection falls back.** By default (`--avoid same-family`) the gate
@@ -457,8 +458,9 @@ request.
 **Prerequisites:** An initialized project must resolve from the active pointer
 or an explicitly supplied project/review target. Its core artifacts must be
 committed before review. Code review needs completed implementation work and
-the mode-appropriate requirements sources; lite review does not require absent
-discovery, spec or design artifacts. Code reviews and plan artifact reviews
+the mode-appropriate requirements sources; lite and brief reviews do not
+require absent discovery, spec or design artifacts. A brief code review takes
+its range from the journal's phase anchors. Code reviews and plan artifact reviews
 also need a resolved dispatch policy (`oat_dispatch_policy` in `state.md` or
 `workflow.dispatchPolicy.*` in config); without one the review stops before
 launching a reviewer. Discovery, spec and design artifact reviews run without

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.17",
-  "docs-config": "0.3.17",
-  "docs-theme": "0.3.17",
-  "docs-transforms": "0.3.17"
+  "cli": "0.3.19",
+  "docs-config": "0.3.19",
+  "docs-theme": "0.3.19",
+  "docs-transforms": "0.3.19"
 }