@open-agent-toolkit/cli 0.2.2 → 0.2.3

package/assets/docs/cli-utilities/workflow-gates.md

@@ -33,7 +33,7 @@ Gate config lives under `workflow.gates.skills` and is keyed by skill name.
     "gates": {
       "skills": {
         "oat-project-implement": {
-          "command": "oat gate review --project \"$PROJECT_PATH\" --review-type code --review-scope final \"Use oat-project-review-provide code final for the declared project\"",
+          "command": "oat --json gate review --project \"$PROJECT_PATH\" --review-type code --review-scope final \"Use oat-project-review-provide code final for the declared project\"",
           "description": "Run a fresh-runtime final review before implementation is considered done.",
           "onFailure": "block",
           "maxAttempts": 2
@@ -57,6 +57,52 @@ in skill frontmatter with `oat_gateable: true`, and
 `oat internal validate-oat-skills` warns when config targets a missing or
 non-gateable skill.
 
+### Implementation exit-gate closeout
+
+For `oat-project-implement`, the configured skill gate is a final, resumable
+closeout boundary. It is independent from the root-owned phase reviews, the
+mandatory final lifecycle review, and the optional `oat_phase_review_gate`.
+Passing or disabling one of those mechanisms never satisfies or disables the
+configured implementation gate.
+
+After final verification and the mandatory final lifecycle review pass, OAT
+persists `oat_implement_exit_gate` in project state before it launches the
+configured command. The state records:
+
+- `pending`, `allowed`, `blocked`, or `stale` status;
+- a `configured` or `no_gate` resolution;
+- `passed`, `warned`, `prompt_approved`, or `no_gate` allowed dispositions;
+- the resolved configuration fingerprint, reviewed HEAD, implementation
+  fingerprint, gate run, envelope, and receive provenance; and
+- launch and receive reconciliation data needed to resume without duplicating
+  an accepted run or completed receive.
+
+A `null` resolution is explicit success for that closeout generation:
+`allowed/no_gate` with `disposition: no_gate`. Configured success becomes
+`allowed/passed`; `warn` and an explicit `prompt` continuation persist their
+own allowed dispositions only for a validated, receive-eligible `blocked`
+envelope after eligible receive completes durably. Unresolved, malformed,
+contradictory, validation, correlation, launch, or receive failures ignore
+`onFailure` and remain blocked.
+
+Resume correlates the persisted launch intent with the gate run marker, durable
+JSON result receipt, and run-bound artifact. Eligible receive similarly
+correlates the source and archived artifact, Reviews event, and bookkeeping
+commit. Missing or ambiguous evidence fails closed instead of launching or
+receiving again.
+
+An allowed result remains fresh only while every commit after `reviewed_head`
+contains recognized closeout-only work, such as gate receipts, project
+tracking, summary/documentation/PR sequencing, final HiLL, or completion
+bookkeeping. Implementation, test, skill, template, workflow configuration, or
+unknown changed paths make the result stale and require a current final review
+and a new gate generation.
+
+Only an artifact with `oat_review_invocation: gate` and the matching
+`oat_gate_run_id` can satisfy configured-gate provenance. A normal final
+review, phase review, or manually produced independent review cannot substitute
+for it.
+
 ## Review gates
 
 `oat gate review` is intentionally stateful. It is equivalent to running
@@ -424,7 +470,7 @@ Set or clear a skill gate:
 
 ```bash
 oat gate set oat-project-implement \
-  --command 'oat gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
+  --command 'oat --json gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
   --description "Run final review in another runtime" \
   --on-failure block \
   --max-attempts 2 \
@@ -441,17 +487,18 @@ unset lets the dispatcher avoid the current runtime and choose the
 highest-priority available non-host target. Pin a target only for manual
 dispatch, debugging, or a deliberate local/user-specific override.
 
-### Migrate ambient lifecycle commands
+### Migrate legacy lifecycle commands
 
 Older user-level lifecycle commands often asked a reviewer to inspect the
-"current project" but omitted a machine-readable declaration. Migrate each
-stored `oat gate review` command by inserting `--project "$PROJECT_PATH"` and
-retaining provider-neutral target selection. For example:
+"current project", omitted a machine-readable project declaration, or emitted
+human-oriented output. Migrate each stored command to the canonical global-JSON
+shape `oat --json gate review --project "$PROJECT_PATH" ...` while retaining
+provider-neutral target selection. For example:
 
 ```bash
 export PROJECT_PATH
 oat gate set oat-project-implement \
-  --command 'oat gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
+  --command 'oat --json gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
   --description "Run final review in another runtime" \
   --on-failure block \
   --max-attempts 2 \
@@ -463,6 +510,12 @@ Apply the same command shape to `oat-project-plan`,
 skills have configured review gates. Do not add `--target`; explicit targets
 remain manual/debug or deliberate local/user-specific overrides.
 
+Implementation closeout rejects a stored review command without global
+`--json`, without `--project "$PROJECT_PATH"`, or with a shared `--target`
+before launch. It does not rewrite configuration or inject, reorder, or append
+arguments while executing. Migrate the declaration first; otherwise the
+project remains blocked and resumable through `oat-project-implement`.
+
 Set or clear an exec target:
 
 ```bash
@@ -589,7 +642,9 @@ contributor fields are absent. The achieved level is one of:
 
 ## Failure behavior
 
-Gate failure behavior is owned by the gate-aware skill:
+Gate failure behavior is owned by the gate-aware skill. The configured policy
+applies only to a validated, receive-eligible `blocked` result after its
+eligible receive completes durably:
 
 | `onFailure` | Meaning                                                                              |
 | ----------- | ------------------------------------------------------------------------------------ |
@@ -597,6 +652,12 @@ Gate failure behavior is owned by the gate-aware skill:
 | `prompt`    | Surface the failure and ask the user how to proceed.                                 |
 | `warn`      | Record the failure and continue.                                                     |
 
+`review_failed`, `artifact_validation_failed`,
+`targeting_correlation_failed`, unknown or contradictory envelopes, launch
+failures, and receive failures are operational failures rather than validated
+blocking findings. They remain blocked regardless of `onFailure`; even `warn`
+cannot turn them into an allowed disposition.
+
 `cross-provider-exec` does fallback only before dispatch, while selecting an
 available target. Once a target actually runs, its exit code is the gate result;
 OAT does not try another target after a failed review.

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

@@ -84,6 +84,9 @@ Autonomous execution preserves independent review:
   bounded implement-and-re-review loop.
 - Critical findings and failed blocking reviews stop progression. Important
   findings follow the configured gate policy.
+- A normal phase or final lifecycle review cannot satisfy a configured
+  implementation exit gate. Only gate invocation provenance with the matching
+  run ID can authorize that boundary.
 
 Project review artifacts and review rows reference launcher-owned dispatch
 records. The configured invocation is authoritative evidence; child
@@ -104,12 +107,23 @@ An existing valid explicit list is preserved. An existing `[]` is also
 preserved and means every phase, never no phases. At each configured checkpoint,
 autonomy runs and receives the review without waiting.
 
-At final closeout, pre-approval lifecycle steps run first. After a passing final
-review, autonomy records final HiLL approval and then runs post-approval steps.
-A failed blocking review stops before approval. The default autonomous tail is
-summary, documentation, and final PR when no post-implementation sequence is
-configured; stored legacy or structured sequences retain their documented
-meaning.
+At final closeout, autonomy follows the same authoritative order as an
+interactive run: final verification, mandatory final lifecycle review,
+configured implementation exit gate, pre-approval sequence, final HiLL
+approval, post-approval sequence, then implementation completion and success
+output. A null gate resolution persists an explicit no-gate allowance before
+the sequence starts.
+
+Autonomy does not turn an ordinary independent review into configured-gate
+provenance. A configured review must produce a gate-originated artifact with
+the matching run ID, and eligible receive must be durably reconciled. Blocked,
+ambiguous, malformed, or stale gate state is a boundary stop: the run remains
+resumable through `oat-project-implement` and cannot continue to approval,
+completion, or output.
+
+The default autonomous tail is summary, documentation, and final PR when no
+post-implementation sequence is configured; stored legacy or structured
+sequences retain their documented meaning.
 
 ## Execution-learnings loop
 

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

@@ -20,6 +20,9 @@ and updates project state.
   phase report.
 - **Fix boundary:** blocking findings return to the original phase handle when
   possible.
+- **Final exit-gate boundary:** after final verification and final lifecycle
+  review, the root resolves the configured implementation gate before
+  approval-aware sequencing, final HiLL, completion, or success output.
 - **Optional nesting:** a phase agent may dispatch bounded recon, fanout, or
   specialist work when that materially helps. Ordinary tasks do not require a
   third tier.
@@ -84,6 +87,49 @@ commit range, task IDs and boundaries, project artifacts, and verification
 evidence. The review passes with zero Critical and zero Important findings.
 Medium and Minor findings are recorded without blocking the phase.
 
+## Final Exit-Gate Boundary
+
+After every planned phase and review round finishes, the project root runs final
+verification and the mandatory final lifecycle review. It then resolves
+`workflow.gates.skills.oat-project-implement` and persists the result in
+`oat_implement_exit_gate`. This configured gate is separate from the phase
+reviewer, final lifecycle reviewer, and optional phase gate; none can substitute
+for another.
+
+Resolution and policy outcomes are explicit:
+
+- A null resolution persists `allowed/no_gate` for the current implementation
+  basis.
+- A configured passing review persists `allowed/passed` after any eligible
+  review receive is durably completed.
+- `warn` persists `allowed/warned`; `prompt` proceeds only after explicit
+  approval persists `allowed/prompt_approved`.
+- `block`, an unresolved prompt, invalid or contradictory output, and
+  operational or receive failures remain blocked. Remediation retries follow
+  the persisted `maxAttempts` policy.
+
+Gate execution is resumable across both launch and receive. Before launch, OAT
+persists an attempt ID, start time, and result-receipt path. It correlates those
+with the gate run marker, structured envelope, and run-bound artifact before it
+accepts a result or relaunches. Before receive, it persists the handoff and
+source/archive correlation; resume verifies the archived artifact, Reviews
+event, and bookkeeping commit before marking receive complete. Missing,
+contradictory, or ambiguous correlation fails closed. A valid accepted run or
+completed receive is never duplicated.
+
+Freshness is bound to the reviewed HEAD and an implementation fingerprint.
+Recognized closeout-only descendants preserve a valid result: gate artifacts
+and receipts, project tracking and project-log appends,
+summary/documentation/PR sequence outputs, final HiLL bookkeeping, and
+completion bookkeeping. An implementation, test, skill, template, workflow
+configuration, or unknown path change is substantive. It makes the gate result
+stale, requires a current final lifecycle review for the new basis, and starts
+a new gate generation.
+
+Only an allowed and fresh gate disposition can enter the pre-approval sequence,
+cross final HiLL, run the post-approval sequence, mark implementation complete,
+or emit success.
+
 ## Phase Scope
 
 The root supplies one scope for the whole phase:

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

@@ -44,7 +44,23 @@ flowchart LR
 
 ## Post-implementation flow
 
-After implementation and final review pass:
+Implementation closeout has one authoritative order:
+
+1. Run final implementation verification.
+2. Pass the mandatory final lifecycle review.
+3. Resolve and disposition the configured `oat-project-implement` exit gate.
+4. Run the configured pre-approval sequence.
+5. Record final HiLL approval when the final phase is a checkpoint.
+6. Run the configured post-approval sequence.
+7. Mark implementation complete and emit the implementation success output.
+
+The configured exit gate is independent from the mandatory lifecycle review,
+root-owned phase reviews, and optional `oat_phase_review_gate`. It must reach an
+allowed and fresh disposition before pre-approval work starts. A null
+configuration is recorded explicitly as `allowed/no_gate`; it is not inferred
+from missing state.
+
+After implementation closeout finishes:
 
 1. **Summary** (`oat-project-summary`) — generates `summary.md` as institutional memory from project artifacts; PR-final and completion will auto-refresh it if you have not already run it or if it is stale
 2. **Documentation** (`oat-project-document`) — optional sync of project docs; now uses the shared `tools.project-management` config signal to decide whether repo-reference refresh should run before docs analysis, and should recommend new docs pages/directories when the shipped work introduces a capability area that the docs app does not already cover
@@ -87,11 +103,18 @@ This distinction matters during completion: `oat-project-complete` can skip the
 ### Approval-aware post-implementation sequencing
 
 `workflow.postImplementSequence` can use the legacy string values or a structured
-`{ preApproval, postApproval }` value. After the final review passes, OAT
-snapshots the effective sequence, runs ordered pre-approval steps, records final
-HiLL approval, and only then runs post-approval steps. The snapshot is
-restart-safe: an incomplete sequence routes back to implementation and resumes
-from its first incomplete step.
+`{ preApproval, postApproval }` value. After final verification, final review,
+and an allowed, fresh implementation exit-gate disposition, OAT snapshots the
+effective sequence, runs ordered pre-approval steps, records final HiLL
+approval, and only then runs post-approval steps. The snapshot is restart-safe:
+an incomplete sequence routes back to implementation and resumes from its first
+incomplete step.
+
+`oat-project-next` checks `oat_implement_exit_gate` before every normal
+post-implementation route. Missing, pending, blocked, malformed, or stale state
+routes back to `oat-project-implement` even when `oat_phase_status` is
+`complete` or `pr_open`. Only an allowed, fresh disposition can continue to
+summary, documentation, PR, or project completion.
 
 When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter sets `oat_auto_review_at_hill_checkpoints`, completing a HiLL checkpoint automatically runs the extra lifecycle review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (minors auto-converted to fix tasks, no user prompts). Disabled by default. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks. This does not control Tier 1 per-phase `oat-reviewer` gates.
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.2",
-  "docs-config": "0.2.2",
-  "docs-theme": "0.2.2",
-  "docs-transforms": "0.2.2"
+  "cli": "0.2.3",
+  "docs-config": "0.2.3",
+  "docs-theme": "0.2.3",
+  "docs-transforms": "0.2.3"
 }