@open-agent-toolkit/cli 0.3.15 → 0.3.17

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

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash(git:*), Bash(oat:*), AskUserQuestion
 metadata:
-  version: 1.4.3
+  version: 1.4.5
 ---
 
 # Progress Router
@@ -179,6 +179,20 @@ Read `{project}/state.md` frontmatter:
 - `oat_hill_completed` - Completed HiLL checkpoints
 - `oat_skill_gate_overrides` - Configured lifecycle gates this project
   deliberately disabled, keyed by gate-aware skill name
+- `oat_implement_exit_gate` - The implementation exit gate record
+- `oat_quick_start_gate` - The quick-start plan gate record
+
+Blockers may be legacy reason strings or structured `{task_id, reason, since}`
+records. Display strings as their reason; display records as
+`{task_id}: {reason} (since {since})`, reading each field deliberately rather
+than coercing the object to text. `oat project status --json` preserves those
+three literal string fields; `--field project.blockers` and
+`--shell BLOCKERS=project.blockers` serialize the list as JSON. Empty lists mean
+no blockers; mixed lists retain entries in order. Records missing any nonempty
+string field and other malformed entries become diagnostic legacy strings:
+`Malformed blocker entry: <JSON>`. They remain visible to blocker checks and
+human output. Legacy string normalization remains unchanged. Do not change
+state or routing merely to render blockers.
 
 **Display format:**
 
@@ -191,6 +205,8 @@ Read `{project}/state.md` frontmatter:
    Completed: {oat_hill_completed as checkmarks}
    HiLL Pending: {yes/no for current phase}
    Gate Overrides: {gate-aware skill keys from oat_skill_gate_overrides, or "None"}
+   Quick-Start Gate: {status}/{disposition}, decided {decided_at}, fingerprint {config_fingerprint} (as recorded), or "None"
+   Exit Gate: {status}/{disposition} as recorded, or "None"
    Blockers: {oat_blockers or "None"}
    Next: {recommended_skill}
 ```
@@ -203,6 +219,16 @@ even when no gate is currently configured for that skill, and never infer a
 configured gate from an override alone. This is read-only reporting: never add,
 remove, or repair the map here.
 
+Both gate records share the core defined in
+`references/docs/gate-approval-record.md`. Report a quick-start record as that
+doc describes: its stored fields as recorded, with `config_fingerprint` shown as
+provenance and never recomputed, or `malformed` when its fields do not form a
+valid record. Report the exit-gate
+record's `status` and `disposition` as recorded; its freshness belongs to the
+implementation workflow and is not re-derived here. Either record adds no route
+and no warning: quick plan readiness stays the single routing rule for quick
+plans. Show "None" for an absent record, and never write or repair one here.
+
 ### Step 5: Determine Next Skill
 
 Based on project state, recommend next action.

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

@@ -0,0 +1,80 @@
+# 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.
+
+## 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-promote-spec-driven/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.2.4
+  version: 1.2.5
 ---
 
 # Promote Project To Spec-Driven Lifecycle
@@ -15,6 +15,10 @@ Convert a quick/import workflow project into a Spec-Driven OAT lifecycle project
 
 Lite projects promote through quick first: run `oat project promote <path> --to quick`, then use this skill. This skill's direct eligibility remains quick/import only.
 
+## Hook-safe exact-path commits
+
+Before a parent-branch commit, verify `oat internal commit-paths --help` succeeds. If unavailable, stop and update the OAT CLI; never fall back to a staged-index or pathspec-only commit. Set `COMMIT_IDENTITY` to a unique operation/artifact identity before the first attempt and retain it for every retry; use a new identity for a new operation. Pass only the exact produced file list, including tracked removals and both names of a rename. A blocked/failed result stops the workflow; retain its receipt and follow its diagnostics. Hooks remain enabled. Synced project artifacts continue through `oat project push`.
+
 ## Prerequisites
 
 - Active project exists.
@@ -153,8 +157,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || {
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): promote {project-name} to spec-driven" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
-  git diff --cached --quiet || git commit -m "chore(oat): promote {project-name} to spec-driven"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/discovery.md" "$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-promote-spec-driven:1" --message "chore(oat): promote {project-name} to spec-driven" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -5,15 +5,19 @@ argument-hint: '<project-name> ["project description"]'
 oat_gateable: true
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 2.3.17
+  version: 2.3.19
 ---
 
 # Quick Start Project
 
 Create or resume a project in **quick mode** and produce a runnable `plan.md` with minimal ceremony.
 
+## Hook-safe exact-path commits
+
+Before a parent-branch commit, verify `oat internal commit-paths --help` succeeds. If unavailable, stop and update the OAT CLI; never fall back to a staged-index or pathspec-only commit. Set `COMMIT_IDENTITY` to a unique operation/artifact identity before the first attempt and retain it for every retry; use a new identity for a new operation. Pass only the exact produced file list, including tracked removals and both names of a rename. A blocked/failed result stops the workflow; retain its receipt and follow its diagnostics. Hooks remain enabled. Synced project artifacts continue through `oat project push`.
+
 ## Prerequisites
 
 - A repository initialized for OAT (`.oat/` and `.agents/` exist).
@@ -98,7 +102,7 @@ writing lifecycle artifacts does not imply unrelated full test suites.
 Before scaffolding, surface the working tree state so unrelated changes don't get carried into the project workflow's bookkeeping commits.
 
 1. Run `git status --porcelain`. If empty, continue silently to the next step.
-2. If `.oat/sync/manifest.json` is the only entry **and** its two-character status code is either `??` or made up solely of the letter `M` and blanks — a plain modification, staged, unstaged, or both — commit it without asking: `git add -- .oat/sync/manifest.json` then `git commit -m "chore: run sync"`. Report the commit in one line and continue to the next step. That file is `oat sync` output and carries no user content, so the prompt below was always answered "commit now" for it. Every other code falls through to the prompt below, including any code that pairs `M` with something else: `MD` (deleted in the worktree), `MT` (type change), `AM`, `RM`, `CM`, and every unmerged state. Auto-staging one of those would commit a deletion, a retyped file, or a half-resolved merge. Any other dirty path, in any combination, also falls through.
+2. If `.oat/sync/manifest.json` is the only entry **and** its two-character status code is either `??` or made up solely of the letter `M` and blanks — a plain modification, staged, unstaged, or both — commit it without asking: `oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-quick-start:1" --message "chore: run sync" -- .oat/sync/manifest.json`. Report the commit in one line and continue to the next step. That file is `oat sync` output and carries no user content, so the prompt below was always answered "commit now" for it. Every other code falls through to the prompt below, including any code that pairs `M` with something else: `MD` (deleted in the worktree), `MT` (type change), `AM`, `RM`, `CM`, and every unmerged state. Auto-staging one of those would commit a deletion, a retyped file, or a half-resolved merge. Any other dirty path, in any combination, also falls through.
 3. Otherwise, present the dirty list to the user.
 4. If `.oat/sync/manifest.json` or paths under `.claude/`, `.cursor/`, `.codex/` appear in the list, note: "These are generated by `oat sync` (often by `pnpm run worktree:init` or `oat-worktree-bootstrap-auto`) and are typically safe to commit as `chore: run sync`."
 5. Offer three choices via `AskUserQuestion`:
@@ -290,8 +294,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): capture quick-start discovery for {project-name}" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md"
-  git diff --cached --quiet || git commit -m "chore(oat): capture quick-start discovery for {project-name}"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-quick-start:2" --message "chore(oat): capture quick-start discovery for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 
@@ -348,8 +352,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): promote quick-start discovery for {project-name}" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md"
-  git diff --cached --quiet || git commit -m "chore(oat): promote quick-start discovery for {project-name}"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-quick-start:3" --message "chore(oat): promote quick-start discovery for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 
@@ -555,8 +559,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): capture quick-start design for {project-name}" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md"
-  git diff --cached --quiet || git commit -m "chore(oat): capture quick-start design for {project-name}"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/design.md" "$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-quick-start:4" --message "chore(oat): capture quick-start design for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 
@@ -569,8 +573,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): complete quick-start discovery for {project-name}" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md"
-  git diff --cached --quiet || git commit -m "chore(oat): complete quick-start discovery for {project-name}"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-quick-start:5" --message "chore(oat): complete quick-start discovery for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 
@@ -846,7 +850,7 @@ as the last check before plan and project completion:
 
    Handle all three `resolution` values explicitly:
    - `not_configured`: no gate is configured; proceed directly to the completion steps in Step 3.7 below.
-   - `configured_disabled_by_project`: the operator disabled this configured gate for this project. Do not launch any process. Emit `configured but disabled by project override`, including the project path and the `projectOverride` source from the envelope, then proceed directly to the completion steps in Step 3.7 below. A project-disabled gate never enters the passed, missing, or failed branches, and its `configuredGate` is evidence only, never executed.
+   - `configured_disabled_by_project`: the operator disabled this configured gate for this project. Do not launch any process. Emit `configured but disabled by project override`, including the project path and the `projectOverride` source from the envelope, write `oat_quick_start_gate` as `allowed/project_disabled` with `reviewed_head: null` per **Persist the gate outcome** below, then proceed directly to the completion steps in Step 3.7 below. A project-disabled gate never enters the passed, missing, or failed branches, and its `configuredGate` is evidence only, never executed.
    - `configured`: continue with the steps below, executing `effectiveGate` exactly as configured.
 
    A null, missing, malformed, or unrecognized result is an operational failure
@@ -891,6 +895,17 @@ as the last check before plan and project completion:
    - `prompt`: surface the gate failure and ask the human how to proceed.
    - `warn`: record the gate failure and continue.
 
+   **Complexity review at `maxAttempts`.** When `block` attempts are exhausted,
+   dispatch the complexity review that
+   `references/docs/complexity-review-fallback.md` defines for the plan bundle
+   before escalating, then show its decision message with the accumulated
+   feedback; under `OAT_AUTONOMOUS=1`, put the same content in the boundary
+   report instead. Record the operator's choice with the report path in
+   `implementation.md`. Agents never select the disposition. Only exhausted
+   `block` attempts trigger the review. To launch it, load the current
+   `oat-project-dispatch-subagents/SKILL.md` and follow it, resolving the route
+   as that doc's "Routing outside implement" section describes.
+
 7. Runtime selection note: the review-only declaration carries producer
    identity, not reviewer runtime identity. By default, `oat gate review` and
    `oat gate cross-provider-exec` resolve the current host from built-in
@@ -905,6 +920,23 @@ A gate that ends in `block` after attempts are exhausted, or at an unresolved
 `prompt` boundary, means the completion steps below MUST NOT run; the phase
 stays `in_progress` and resumable.
 
+**Persist the gate outcome.** For a configured gate, including one disabled by
+project override, write `oat_quick_start_gate` to `$PROJECT_PATH/state.md` with
+the core fields defined in `references/docs/gate-approval-record.md` once the
+gate reaches its outcome, and commit it with the next quick-start bookkeeping
+commit or before stopping:
+
+- passed: `allowed/passed`;
+- `warn` failure: `allowed/warned`;
+- a `prompt` failure the operator explicitly continues past: `allowed/prompt_approved`;
+- a `prompt` failure declined or deferred (every `prompt` failure under
+  `OAT_AUTONOMOUS=1`), `block` exhausted after `maxAttempts`, or a launch,
+  validation, or receive failure: `blocked` with `disposition: null`;
+- `configured_disabled_by_project`: `allowed/project_disabled` with `reviewed_head: null` and no launch.
+
+`not_configured` writes no record. `reviewed_head` is the plan commit the gate
+reviewed and `decided_at` the decision time. A rerun replaces the record. Step 3.7 stays gated by the control flow above and does not read this record back.
+
 ### Step 3.7: Record Review Disposition and Mark Plan Complete
 
 Reach this completion boundary only after the configured gate passes or resolves
@@ -1153,15 +1185,16 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): update quick-start artifacts for {project-name}" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
+  OWNED_COMMIT_PATHS=()
   for path in \
     "$PROJECT_PATH/discovery.md" \
     "$PROJECT_PATH/design.md" \
     "$PROJECT_PATH/plan.md" \
     "$PROJECT_PATH/implementation.md" \
     "$PROJECT_PATH/state.md"; do
-    [ -e "$path" ] && git add "$path"
+    [ -e "$path" ] && OWNED_COMMIT_PATHS+=("$path")
   done
-  git diff --cached --quiet || git commit -m "chore(oat): update quick-start artifacts for {project-name}"
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-quick-start:6" --message "chore(oat): update quick-start artifacts for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```