@open-agent-toolkit/cli 0.3.18 → 0.3.20

package/assets/skills/oat-project-goal/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-implement/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(oat project log:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 2.3.18
+  version: 2.3.20
 ---
 
 # Implementation Phase

package/assets/skills/oat-project-implement/references/completion-and-closeout.md

@@ -35,10 +35,85 @@ Options:
 3. Modify plan to address blocker
 ```
 
+In brief modes `task_id` is the open execution record's ID, or the phase ID
+when no record is open. Brief record statuses have no `blocked` value: keep the
+record `**Status:** in_progress` with the `**Blocker:**` line, or close it
+`failed` when the attempt is abandoned. Option 3 edits the brief's phases under
+the `plan-and-resume.md` Step 2.2 rules.
+
+### Goal Milestone Closeout
+
+This section applies only when `oat_workflow_mode` is `goal` and the run's
+scope is a milestone or recovery scope (`plan-and-resume.md`, Goal Projects).
+`oat-project-brief/references/brief-contract.md` sections 12.4, 12.5 and 12.8
+own the carrier, ladder and freshness rules; this section states the order.
+Steps 11–16 below are the **terminal** closeout and run for goal only after a
+valid declaration, once every phase in the terminal execution scope is
+accepted.
+
+When every phase-unit in the milestone or recovery scope is accepted (the
+router's `closeout mNN: …` context), and whenever the router routes a
+missing, blocked or stale exit carrier back here, this scoped closeout is the
+recovery owner for that carrier:
+
+1. **Exit gate before the integrated review.** Resolve and run the configured
+   implement exit gate exactly as Step 14 does (`oat gate resolve
+oat-project-implement --project "$PROJECT_PATH" --json`, canonical
+   `oat --json gate review`, receive eligibility, `onFailure`, `maxAttempts`),
+   scoped to the milestone's ordered phase set. The goal ladder exception
+   applies: this gate precedes the integrated delivery review, and queued
+   fixes require it to run again.
+2. **Write the milestone carrier.** Record `oat_milestone_gates[mNN].exit`
+   with the gate approval record core, `resolution` (`configured`, `no_gate`,
+   or `project_disabled`), `subject: { kind: code, scope: [ordered phase
+set] }`, and `freshness: fresh` with `freshness_reason: null` for every
+   carrier it records, `no_gate` and `project_disabled` included. A configured
+   gate keeps the head it actually reviewed as `reviewed_head`; `no_gate` and
+   `project_disabled` record `reviewed_head: null`. A blocked outcome records
+   `status: blocked`, `disposition: null`, and no transition. This carrier is
+   never `oat_implement_exit_gate`.
+3. **Read freshness before any transition.** Run
+   `oat project delivery check --project "$PROJECT_PATH" --subject <mNN|dNN> --json`
+   and persist its `exit` result (`source: milestone-carrier`) as the
+   carrier's `freshness` and `freshness_reason`; the command exits 1 while the
+   integrated review is not yet passed, so read only `exit` here. The bounded
+   bookkeeping-successor rule (section 12.8) decides freshness: bookkeeping
+   commits after the reviewed head never force a rerun, and a substantive
+   commit does.
+4. **Transition.** For the active milestone, when the carrier is `allowed` and
+   fresh, write `oat_milestone_status: reviewing` (`implementing → reviewing`);
+   never `delivering`, which belongs to `oat-project-review-receive`. For a
+   recovery scope, advance `oat_goal_recovery.stage` instead: accepted fixes →
+   `exit_gate`, then an allowed, fresh carrier → `reviewing`; the active
+   milestone's fields stay unchanged.
+5. **Hand off.** Commit the carrier and transition as bookkeeping, then
+   report the router's next skill: `oat-project-review-provide` with the
+   explicit `code mNN: <ordered phase ids>` (or `code mNN/dNN: …`) scope.
+
+**Terminal `pr` step.** When the terminal post-implement sequence (Step 15)
+reaches the `pr` step's position, run `oat project closeout-check
+"$PROJECT_PATH" --json`. When delivery coverage holds, record the step complete
+with `satisfied_by: { pr: delivery-coverage }` in the snapshot and run every
+other configured step unchanged; never record it before that position. When an
+accepted phase is uncovered (`phase-uncovered`), the step's target
+`oat-project-pr-final` registers the terminal delivery; other refusals route to
+their `nextOwner.skill`.
+
 ### Step 11: Prepare Final Closeout Baseline
 
 When all plan tasks are complete (i.e., there is no next incomplete `pNN-tNN` task):
 
+In goal mode this step is terminal closeout: it starts only after a valid
+declaration (`oat_goal_status: declared_met`) when every phase in the terminal
+execution scope is accepted; a milestone closes through Goal Milestone Closeout
+above instead. The Outcomes audit below is the declaration's
+`oat_goal_outcome_audit`, which implement reads and never writes.
+
+In brief modes this step starts only when every phase-unit in the active scope
+is accepted (`**Status:** completed` under its journal heading), no phase is
+provisional, and no execution record is open. Closed records alone never start
+it, and extracted units are outside the active scope.
+
 **Update "Final Summary" (required):**
 
 - Before requesting final review / running `oat-project-pr-final`, update the `## Final Summary (for PR/docs)` section in `"$PROJECT_PATH/implementation.md"`:
@@ -47,6 +122,15 @@ When all plan tasks are complete (i.e., there is no next incomplete `pNN-tNN` ta
   - Verification performed (tests/lint/typecheck/build/manual)
   - Design deltas (if any)
 - This should reflect **what was actually implemented**, including any deviations from design and any review-fix work.
+- **Brief modes: completion is audited against the brief's Outcomes.** Add an
+  `**Outcomes audit:**` block to the Final Summary with one line per numbered
+  Outcome naming its observed evidence (accepted phase, commit, or
+  verification result from the journal) or the explicit scope decision that
+  defers it. An Outcome with neither blocks closeout until it is resolved or
+  the user records the deferral. Report `Brief deltas` (the journal template's
+  heading) instead of design deltas, and fill the brief's
+  `## Implementation Complete` section with one line per accepted phase and the
+  phase total.
 - Reconcile `"$PROJECT_PATH/state.md"`, `"$PROJECT_PATH/implementation.md"`,
   and `"$PROJECT_PATH/plan.md"` so task totals, phase statuses, current-task
   pointers, the final summary, and test results describe the same terminal
@@ -99,6 +183,10 @@ Implementation - Tasks complete; awaiting final review.
 - ⧗ Awaiting final review
 ```
 
+In brief modes the progress list names the brief and its phase-units instead of
+the discovery, specification, design, and plan lines: `✓ Brief approved`,
+`✓ All phase-units accepted`, `⧗ Awaiting final review`.
+
 **Baseline bookkeeping commit (required):**
 
 **DO NOT SKIP.** This commit prevents state drift across sessions.
@@ -150,6 +238,11 @@ An accepted reviewer `BLOCKED` terminal blocks final review. It does not invoke
 fallback and must not be interpreted as a pass due to absent findings. Stop and
 surface the review target and blocker reason.
 
+In brief modes the `final` scope is every accepted non-extracted phase,
+revision phases included, resolved from the recorded `**Base:**` and
+`**Head:**` anchors in document order (brief contract section 10). Invalid or
+contradictory anchors stop at `oat-project-reconcile` rather than narrowing.
+
 Before requesting final review, ensure the latest project-artifact bookkeeping is already committed. Review should evaluate the implementation state as it actually stands on the branch, not a half-tracked working tree.
 
 Check if final review already completed (preferred source of truth: plan.md Reviews table):
@@ -910,6 +1003,17 @@ phase) or when it explicitly contains that final phase ID. Defer only a
 checkpoint on the final implementation phase; non-final checkpoint behavior
 remains unchanged.
 
+Brief modes take this non-lite path. Their `[]` means none
+(`plan-and-resume.md` Step 2.5), so a final HiLL checkpoint exists for a brief
+only when `oat_plan_hill_phases` explicitly lists the final phase, which is the
+last phase-unit in document order. The generic sequence normalization, the
+autonomous lifecycle-tail default, the project recap, and the non-lite algorithm
+below then apply unchanged; with no final checkpoint, item 5 of that algorithm
+governs. In v1 the `pr` step keeps its target, `oat-project-pr-final`.
+Goal follows this path at terminal closeout, with the `pr` step satisfied by
+delivery coverage at its position (Goal Milestone Closeout, Terminal `pr`
+step).
+
 Run final verification (Step 12). Final review must be `passed` and the
 configured implementation exit gate in Step 14 must be allowed before any
 pre-approval dispatch. If final checkpoint auto-review is enabled, Step 8 has
@@ -1291,3 +1395,6 @@ Final review:
 
 Next: Create PR or run the oat-project-pr-final skill (when available)
 ```
+
+In brief modes report `Phases: {N} accepted` and `Execution records: {N}
+closed` instead of the task count, and include the Outcomes audit result.