@open-agent-toolkit/cli 0.3.18 → 0.3.20

package/assets/skills/oat-project-brief/references/docs/gate-approval-record.md

@@ -0,0 +1,93 @@
+# Lifecycle Gate Approval Record
+
+A configured lifecycle gate ends in an outcome the operator or a later session
+needs to see again: it passed, it warned, the operator explicitly continued
+past a failure, the project disabled it, or it blocked. Chat output does not
+survive the session, so the skill that runs the gate persists the outcome in
+project `state.md`. This document defines the record's shared core once; each
+carrier names where it lives and what it adds.
+
+## Core record
+
+```yaml
+<carrier>:
+  status: allowed # allowed | blocked
+  disposition: passed # passed | warned | prompt_approved | project_disabled; null when blocked
+  config_fingerprint: '<stable hash of the resolved gate declaration>'
+  reviewed_head: '<full SHA of the commit the gate reviewed>'
+  decided_at: '2026-10-02T15:20:00Z'
+```
+
+- `status`: `allowed` | `blocked`.
+- `disposition`: `passed`, `warned`, `prompt_approved`, or `project_disabled`
+  when `status` is `allowed`; `null` when `status` is `blocked`.
+- `config_fingerprint`: the writer's stable hash of the resolved gate
+  declaration it ran (command, description, `onFailure`, `maxAttempts`, and the
+  project override state), recorded as provenance. Implement recomputes its own
+  carrier's fingerprint under its Step 14 rules; quick-start readers do not.
+- `reviewed_head`: the full 40-character SHA of the commit the gate reviewed,
+  recorded as provenance. `null` when no gate ran.
+- `decided_at`: the ISO 8601 UTC time the outcome was decided. A record written
+  before `decided_at` existed is not malformed for that reason alone.
+
+## Write rules
+
+| Gate outcome                                                    | Record                                                      |
+| --------------------------------------------------------------- | ----------------------------------------------------------- |
+| Passed its threshold                                            | `allowed` / `passed`                                        |
+| Failed under `onFailure: warn`                                  | `allowed` / `warned`                                        |
+| Failed under `onFailure: prompt`, operator explicitly continued | `allowed` / `prompt_approved`                               |
+| Failed under `onFailure: prompt`, operator declined or deferred | `blocked` / `null`                                          |
+| `block` still failing after `maxAttempts`                       | `blocked` / `null`                                          |
+| Configured but disabled by project override (no launch)         | `allowed` / `project_disabled`                              |
+| Launch, transport, validation, or receive failure               | `blocked` / `null`                                          |
+| Not configured                                                  | no record (quick-start); implement writes `allowed/no_gate` |
+
+Only an explicit operator continuation writes `prompt_approved`. Declining,
+deferring, giving no response, or running under `OAT_AUTONOMOUS=1` writes
+`blocked`, never anything that reads as approval. A rerun of the same gate
+replaces the record.
+
+## Carriers
+
+- **`oat_implement_exit_gate`** (`oat-project-implement`,
+  `references/completion-and-closeout.md` Step 14) uses this core and keeps its
+  additional values and fields there: the `pending` and `stale` statuses, the
+  `no_gate` disposition, and the resolution, attempt, launch, receive, waiver,
+  and freshness fields. Its own effective-delta freshness rule decides whether a
+  record is current.
+- **`oat_quick_start_gate`** (`oat-project-quick-start`, Gate Execution) carries
+  exactly the core.
+- **`oat_brief_gate`** (`oat-project-brief`, Gate Execution) carries exactly the
+  core, written and read under the same rules as `oat_quick_start_gate`. It is
+  absent when no gate is configured, and nothing routes on it: it is provenance
+  only.
+- **`oat_milestone_gates[mNN].plan` and `.exit`** (goal mode;
+  `oat-project-goal` writes `plan` after each milestone's approval, and
+  `oat-project-implement`'s milestone closeout writes `exit`) carry the core
+  plus `resolution` (`configured`, `no_gate`, or `project_disabled`), a
+  `subject` binding (`plan` or `code` and the milestone's ordered phase set),
+  and derived `freshness` with `freshness_reason`. `reviewed_head` is `null`
+  for `no_gate` and `project_disabled`, and `no_gate` is written rather than
+  omitted because routing reads these carriers. `oat-project-brief`'s
+  `references/brief-contract.md` section 12.4 is their contract.
+
+## Reading a quick-start record
+
+Readers report a quick-start record as recorded and do not recompute
+`config_fingerprint`: no CLI emits a canonical fingerprint for the quick-start
+gate, so a recomputation could not be reproduced across sessions. They do not
+route on the record either.
+
+- Report `status`, `disposition`, `decided_at`, and `config_fingerprint` (as
+  provenance) exactly as stored.
+- Report the record as malformed when `status` and `disposition` do not form
+  one of the combinations in the write rules, or when a present `decided_at` is
+  not a valid ISO 8601 UTC time.
+- `reviewed_head` is provenance only and is not compared with `HEAD`, because
+  the quick-start completion step commits after the gate.
+- An absent record means none was written: no gate was configured, the gate
+  has not reached an outcome, or the plan predates the record. Readers do not
+  infer which.
+
+Readers never write, repair, or infer a record.

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.4
+  version: 1.0.6
 ---
 
 # Capture Untracked Work
@@ -29,7 +29,7 @@ Use when:
 Don't use when:
 
 - A project already exists for the current branch — use `oat-project-reconcile` instead
-- You haven't started any work yet — use `oat-project-lite` for single-sitting work, `oat-project-quick-start` for quick work, or `oat-project-new` for spec-driven work
+- You haven't started any work yet — use `oat-project-lite` for single-sitting work, `oat-project-brief` for one delivery planned as a Project Brief, `oat-project-goal` for an outcome delivered over several milestones, `oat-project-quick-start` for quick work, or `oat-project-new` for spec-driven work
 - You only need to map new commits to an existing plan — use `oat-project-reconcile`
 
 ## Prerequisites

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, AskUserQuestion
 metadata:
-  version: 1.7.15
+  version: 1.7.17
 ---
 
 # Complete Project
@@ -228,6 +228,13 @@ configured, autonomous, or lite closeout cannot complete until its
 `oat_post_implement_sequence` snapshot exists and every stored step and the
 final sign-off are recorded. A project whose implementation finished before
 closeout snapshots existed recovers the same way; there is no override.
+
+For a goal project (`oat_workflow_mode: goal`) the boundary also requires a
+valid declaration, an exhaustive outcome audit and delivery coverage
+(`oat-project-brief/references/brief-contract.md` section 12.9); a refusal
+routes to its `nextOwner.skill` (`oat-project-goal`, `oat-project-implement`,
+a review owner, `oat-project-pr-progress`, or `oat-project-pr-final`) rather
+than to implement alone.
 `oat project complete-state` refuses the same state in Step 5.
 
 The shared and synced archive resume branches above continue at Step 12 or
@@ -291,6 +298,7 @@ PROJECT_RECAP_CONFIG=$(oat config get workflow.explainers.projectRecap --json 2>
 - **If `PR_ON_COMPLETE` is `false`:** Set `SHOULD_OPEN_PR="false"`. Skip the Open PR question. Print `PR on complete: disabled (from workflow.createPrOnComplete).`
 - **If `PR_ON_COMPLETE` is unset:** Include the Open PR question in the batched prompt as normal (backward compatible).
 - The existing tracked-PR skip still applies: if `oat_pr_status` is `open`, do not ask the Open PR question and do not honor `PR_ON_COMPLETE=true` — the PR already exists.
+- **Goal mode (`oat_workflow_mode: goal`):** the completion decision consumes the validated goal coverage from Step 1.5. When the declaration and its exhaustive audit are valid, every terminal delivery is at its agreed endpoint (`status: at_endpoint`, or `endpoint_attainment` recorded), and the snapshot's `pr` step is satisfied by coverage (`satisfied_by: { pr: delivery-coverage }`), set `SHOULD_OPEN_PR="false"`, skip the Open PR question, call no `gh pr create` in Step 11, and print `PR on complete: satisfied by goal delivery coverage` — even when `PR_ON_COMPLETE` is `true`. Genuinely uncovered delivery work never reaches this step: Step 1.5 refuses it and routes to the goal registration owner (`oat-project-pr-final` for terminal registration, `oat-project-pr-progress` for a milestone delivery). A separately intended bookkeeping PR for the completion commits is not a goal delivery: open one only when the user explicitly asks for it in this run, never because of `PR_ON_COMPLETE`, and never register it in `oat_deliveries` or count it toward coverage. Every other mode is unchanged.
 
 Select archive prompt participation before assembling the batched prompt:
 
@@ -390,6 +398,12 @@ Also preflight summary status using the same freshness rules as `oat-project-sum
 - `summary.md` is `missing` when `{PROJECT_PATH}/summary.md` does not exist
 - `summary.md` is `stale` when the tracking frontmatter fields `oat_summary_last_task`, `oat_summary_revision_count`, or `oat_summary_includes_revisions` no longer match `current_last_task`, `current_rev_count`, or `current_rev_list` as defined in `oat-project-summary` Step 3
 - `summary.md` is `current` when those tracking fields still match the `oat-project-summary` Step 3 comparison inputs
+- In brief modes staleness is decided by fingerprint instead: recompute the
+  phase fingerprint with the `oat-project-summary` Step 3 brief fragment, and
+  in goal mode include the Step 3 goal fragment (the delivery IDs at
+  endpoint); `summary.md` is `stale` when its `oat_summary_phase_fingerprint`
+  is absent or differs from the recomputed value and `current` when they
+  match. `oat_summary_last_task` is not consulted for a brief or goal project.
 
 Preflight `{PROJECT_PATH}/references/project-retro.md` alongside the summary.
 The safety-net offer is governed by how this completion run executes, not by how
@@ -1088,7 +1102,7 @@ If a PR description artifact already exists at `{PROJECT_PATH}/pr/project-pr-*.m
 
 **Archive-aware References (required when `SHOULD_ARCHIVE` is `true`):**
 
-When archiving, the project artifacts at `{PROJECT_PATH}/{plan,implementation,discovery,spec,design,summary}.md` will move to a gitignored archive location in Step 8. After commit + push (Step 10), those paths no longer exist on the branch and any blob link to them returns 404 on GitHub. The PR description must anticipate this:
+When archiving, the project artifacts at `{PROJECT_PATH}/{plan,implementation,discovery,spec,design,summary}.md` will move to a gitignored archive location in Step 8. After commit + push (Step 10), those paths no longer exist on the branch and any blob link to them returns 404 on GitHub. The PR description must anticipate this. A brief project's artifact set is `plan.md` (the Project Brief), `implementation.md` (the phase journal), `summary.md`, and `references/`; it has no discovery, spec, or design artifact:
 
 - **Drop References bullets** that point to artifacts about to become local-only:
   - `plan.md`, `implementation.md`, `discovery.md`, `spec.md`, `design.md`, `summary.md`, `references/imported-plan.md`

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

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(pnpm:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 2.2.9
+  version: 2.2.11
 ---
 
 # Discovery Phase
@@ -32,7 +32,7 @@ Before acting:
 2. Confirm `{PROJECT_PATH}/state.md` exists.
 3. Confirm `oat_workflow_mode` is `spec-driven` or absent only in a legacy spec-driven project.
 
-If any check fails, decline this skill. Offer `oat-project-new` for a new spec-driven project, `oat-project-quick-start` for a quick project, `oat-project-lite` for single-sitting work, or `oat-project-open` for switching to an existing project. When the gate passes, summarize the active project and ask before continuing discovery.
+If any check fails, decline this skill. Offer `oat-project-new` for a new spec-driven project, `oat-project-quick-start` for a quick project, `oat-project-lite` for single-sitting work, `oat-project-brief` for one delivery planned as a Project Brief, `oat-project-goal` for an outcome delivered over several milestones, or `oat-project-open` for switching to an existing project. When the gate passes, summarize the active project and ask before continuing discovery.
 
 ## Mode Assertion
 
@@ -107,6 +107,8 @@ PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 - If `oat_workflow_mode` is present and not `spec-driven`, stop and route:
   - quick project: continue with `oat-project-quick-start` / `oat-project-progress`
   - lite project: continue with `oat-project-lite` / `oat-project-progress`
+  - brief project: continue with `oat-project-brief` / `oat-project-progress`
+  - goal project: continue with `oat-project-goal` / `oat-project-progress`
   - import project: continue with `oat-project-import-plan` / `oat-project-progress`
 - Ask user:
   - **Continue** with active project, or

package/assets/skills/oat-project-dispatch-subagents/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read, Bash
 metadata:
-  version: 1.1.7
+  version: 1.1.8
 ---
 
 # Dispatching OAT Project Subagents
@@ -260,6 +260,14 @@ lifecycle_outcome:
 Do not rewrite generic route, selector, acceptance, outcome, or diagnostic
 fields inside the lifecycle extension.
 
+`workflow_mode` carries the project's recorded mode, `brief` included. In a
+brief project the lifecycle scope is a phase ID: `phase_id` (such as `p02`)
+names the phase-unit, and `task_id` names the execution record the launch
+executes, or is `null` for a whole-phase launch, because brief phases have no
+planned tasks. The brief's one-committing-owner rule then sets
+`commit_policy`: a nested worker returns edits on owned paths and never
+commits.
+
 ## Failure Boundaries
 
 - Invalid or stale project state: block before generic dispatch.

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

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(jq:*), Bash(oat pjm:*), Bash(oat project push:*), Bash(oat project scope:*), Bash(oat tools:*), Glob, Grep, AskUserQuestion, Skill
 metadata:
-  version: 1.8.8
+  version: 1.8.10
 ---
 
 # Project Documentation Sync
@@ -217,6 +217,22 @@ shipped results. A lite project accepts `discovery.md`, `spec.md`, and
 `design.md` as absent; do not read or require them. Build the documentation
 delta from what actually shipped and continue with code verification.
 
+For `oat_workflow_mode: brief` or `goal`, use the brief artifact set instead
+of the numbered list below. Read `plan.md` (the Project Brief: Goal, Outcomes,
+Approach and any `### Design` subsection, Constraints and Out of Scope,
+Decisions, and the phases' Intent and Exit evidence), then `implementation.md`
+phase sections, execution records, `Brief deltas`, and `Final Summary (for
+PR/docs)` as the shipped results, plus `summary.md` and `references/research/`
+when present. A goal project adds two shipped-result sources from `state.md`:
+the outcome audit (`oat_goal_outcome_audit`, the per-outcome disposition once
+the goal is declared met) and the delivery registry (`oat_deliveries`, each
+delivery's scope, pull requests and endpoint observation); document only what
+those deliveries shipped, and name audited deferrals rather than documenting
+them as delivered. A brief or goal project accepts `discovery.md`, `spec.md`,
+and `design.md` as absent; do not read or require them. Build the
+documentation delta from what actually shipped and continue with code
+verification.
+
 For every other workflow mode, read the numbered artifact list below.
 
 **Read in order:**