@open-agent-toolkit/cli 0.0.52 → 0.0.53

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.52",
-  "docs-config": "0.0.52",
-  "docs-theme": "0.0.52",
-  "docs-transforms": "0.0.52"
+  "cli": "0.0.53",
+  "docs-config": "0.0.53",
+  "docs-theme": "0.0.53",
+  "docs-transforms": "0.0.53"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.5
+version: 2.0.6
 description: Use when plan.md is ready for execution. Dispatches phase-level subagents with bounded fix loops; supports plan-declared parallel phase groups with worktree-isolated execution and ordered fan-in.
 argument-hint: '[--retry-limit <N>] [--dry-run]'
 disable-model-invocation: true
@@ -525,13 +525,17 @@ When the current schedule entry is a multi-phase group, execute as follows.
 **Tier 1 parallel execution:**
 
 1.  **Bootstrap worktrees:** for each phase in the group, invoke `oat-worktree-bootstrap-auto` with branch name `{project-name}/{pNN}` and base = orchestration branch.
+
+    > ⚠️ **CRITICAL — DO NOT substitute host-native worktree primitives.** Bootstrap MUST go through `oat-worktree-bootstrap-auto` with an explicit `--base` set to the current orchestration branch HEAD (capture `EXPECTED_HEAD=$(git rev-parse HEAD)` from the orchestration cwd before dispatching). Do not use Claude Code's `Agent({ isolation: "worktree" })`, Cursor's equivalent, or any other host-native isolation primitive in lieu of this skill — those mechanisms may use the primary repo's checkout (often `main`) as the base regardless of the orchestrator's current branch, silently producing a worktree that cannot see prior phase commits and forcing the entire group to degrade to sequential.
     - If **any** bootstrap fails, cancel any worktrees that bootstrapped successfully for this group and degrade the whole group to sequential inline execution. Log the degradation reason to `implementation.md` Outstanding Items.
 
-2.  **Concurrent dispatch:** for each successfully bootstrapped worktree, dispatch `oat-phase-implementer` (with the worktree as working directory) concurrently. Each dispatch runs the per-phase loop internally (implementer → reviewer → fix-loop).
+2.  **Verify worktree HEAD before dispatch (base-mismatch gate):** After bootstrap, verify each worktree is at the expected orchestration HEAD. From the orchestration cwd, capture `EXPECTED_HEAD=$(git rev-parse HEAD)` _before_ invoking bootstrap. After bootstrap, for each new worktree path, run `git -C {worktree-path} rev-parse HEAD` and confirm it matches `EXPECTED_HEAD`, or run `git -C {worktree-path} merge-base --is-ancestor "$EXPECTED_HEAD" HEAD` and confirm it succeeds (exit 0). If either check fails for any phase, treat the bootstrap as failed for that phase, cancel any successful sibling worktrees in this group, and degrade the entire group to sequential inline execution — same mechanism as a primary bootstrap failure. Log the mismatch to `implementation.md` Outstanding Items, including the observed and expected SHAs (`expected={EXPECTED_HEAD}, observed={observed-head-sha}, phase={pNN}, worktree={path}`).
+
+3.  **Concurrent dispatch:** for each successfully bootstrapped worktree (passing the base-mismatch gate above), dispatch `oat-phase-implementer` (with the worktree as working directory) concurrently. Each dispatch runs the per-phase loop internally (implementer → reviewer → fix-loop).
 
-3.  **Wait for all phases:** do not proceed until every phase in the group reports a terminal verdict (pass or excluded).
+4.  **Wait for all phases:** do not proceed until every phase in the group reports a terminal verdict (pass or excluded).
 
-4.  **Fan-in reconciliation (merge back in plan order):**
+5.  **Fan-in reconciliation (merge back in plan order):**
 
     For each phase in the group, in plan order (p02 before p03, etc.), if its verdict is pass:
 
@@ -570,23 +574,23 @@ When the current schedule entry is a multi-phase group, execute as follows.
               commit: <sha if RESOLVED, else null>
         ```
 
-    d. Parse the subagent's return status: - `RESOLVED` → subagent has committed the merge; orchestrator proceeds to integration verification (Step 5) and the next phase in the group. - `UNRESOLVABLE` or `VERIFICATION_FAILED` → STOP the run. Surface to user with phase ID, conflicting files, worktree path, subagent's reasoning summary. Do not merge remaining phases.
+    d. Parse the subagent's return status: - `RESOLVED` → subagent has committed the merge; orchestrator proceeds to integration verification (Step 6) and the next phase in the group. - `UNRESOLVABLE` or `VERIFICATION_FAILED` → STOP the run. Surface to user with phase ID, conflicting files, worktree path, subagent's reasoning summary. Do not merge remaining phases.
 
     **Tier 2 (inline) exception:** In Tier 2 runs, parallel groups already degrade to sequential, so fan-in conflicts don't arise from this code path. If a conflict ever surfaces in Tier 2 (e.g., from another operation), the orchestrator resolves inline since the whole run is already inline — consistent with Tier 2 semantics.
 
-5.  **Integration verification after each merge:**
+6.  **Integration verification after each merge:**
 
     After each successful merge, run project verification (tests, lint, type-check). If verification fails:
     - Attempt a tractable fix (missing import, trivial type error). If the fix succeeds and verification passes, commit the fix.
     - If the fix is not tractable → revert the merge, STOP the run. Surface to user.
 
-6.  **Worktree cleanup:**
+7.  **Worktree cleanup:**
 
     For phases that merged successfully and passed integration verification, clean up the worktree using the existing worktree cleanup mechanism (e.g., `git worktree remove`).
 
     For phases that were excluded (fix-loop exhausted), preserve the worktree and log its path in `implementation.md` Outstanding Items.
 
-7.  **Bookkeeping commit** after the group completes. Then HiLL checkpoint check.
+8.  **Bookkeeping commit** after the group completes. Then HiLL checkpoint check.
 
 ### Step 7: Artifact Updates After Each Phase (or Group)
 

package/assets/skills/oat-worktree-bootstrap-auto/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-worktree-bootstrap-auto
-version: 1.2.1
+version: 1.2.2
 description: Use when an orchestrator/subagent needs autonomous worktree bootstrap. Non-interactive companion to oat-worktree-bootstrap.
 argument-hint: '<branch-name> [--base <ref>] [--path <root>] [--baseline-policy <strict|allow-failing>]'
 disable-model-invocation: true
@@ -12,6 +12,8 @@ allowed-tools: Read, Write, Bash, Glob, Grep
 
 Non-interactive worktree bootstrap for orchestrator and subagent execution flows. Creates or reuses a worktree, runs baseline checks, and reports structured status — all without user prompts.
 
+> ⚠️ **When not to substitute.** This skill is the **only** supported mechanism for orchestrator-driven worktree creation in OAT skills. Host-native isolation primitives — Claude Code's `Agent({ isolation: "worktree" })`, Cursor's worktree-isolated agent invocations, and equivalents in other hosts — are **not** substitutes. They may use the primary repo's checkout (often `main`) as the base regardless of the caller's current branch, silently producing a worktree at the wrong base. OAT orchestrators dispatching mid-run from a feature branch MUST go through this skill with an explicit `--base` so the resulting worktree contains the orchestrator's prior commits.
+
 ## Relationship to oat-worktree-bootstrap
 
 This skill is the **autonomous companion** to `oat-worktree-bootstrap`. Key differences:
@@ -37,11 +39,12 @@ When this skill is executed, provide concise status updates:
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before major phases, print compact indicators, for example:
-  - `[1/5] Resolving worktree root…`
-  - `[2/5] Creating/reusing worktree…`
-  - `[3/5] Running baseline checks…`
-  - `[4/5] Syncing provider directories…`
-  - `[5/5] Returning structured status…`
+  - `[1/6] Resolving worktree root…`
+  - `[2/6] Creating/reusing worktree…`
+  - `[3/6] Verifying resolved base in worktree HEAD…`
+  - `[4/6] Running baseline checks…`
+  - `[5/6] Syncing provider directories…`
+  - `[6/6] Returning structured status…`
 
 ## Inputs
 
@@ -51,11 +54,11 @@ When this skill is executed, provide concise status updates:
 
 ### Optional
 
-| Parameter                    | Default                 | Description                     |
-| ---------------------------- | ----------------------- | ------------------------------- |
-| `--base <ref>`               | `origin/main`           | Base ref to branch from         |
-| `--path <root>`              | Resolved via precedence | Explicit worktree root override |
-| `--baseline-policy <policy>` | `strict`                | Baseline check failure policy   |
+| Parameter                    | Default                 | Description                                                                                                                                                                                                                                                                                                                                                                                                |
+| ---------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--base <ref>`               | `origin/main`           | Base ref to branch from. **Callers running inside a worktree-on-a-feature-branch (e.g., an `oat-project-implement` orchestrator dispatching mid-run) MUST pass `--base` explicitly** — either the orchestrator's current branch name or the resolved current HEAD SHA. The default `origin/main` is the **wrong** choice for orchestrators dispatching mid-run; using it will land the worktree at `main`. |
+| `--path <root>`              | Resolved via precedence | Explicit worktree root override                                                                                                                                                                                                                                                                                                                                                                            |
+| `--baseline-policy <policy>` | `strict`                | Baseline check failure policy                                                                                                                                                                                                                                                                                                                                                                              |
 
 ### Baseline Policy
 
@@ -117,6 +120,36 @@ oat local sync "$TARGET_PATH" 2>/dev/null || true
 - Copies configured `localPaths` (e.g., `.oat/ideas/`, `.oat/projects/local/`) into the worktree.
 - Non-blocking: if sync fails or no `localPaths` are configured, bootstrap continues.
 
+### Step 2.7: Verify Resolved Base in Worktree HEAD
+
+Before any baseline checks run, verify the worktree actually branched from the resolved base. This catches host-native or git-internal misbehavior that would otherwise silently land the worktree at the wrong base.
+
+1. Resolve the base SHA:
+
+   ```bash
+   RESOLVED_BASE_SHA=$(git -C "$REPO_ROOT" rev-parse "$BASE_REF")
+   ```
+
+2. Capture the worktree HEAD:
+
+   ```bash
+   OBSERVED_HEAD_SHA=$(git -C "$TARGET_PATH" rev-parse HEAD)
+   ```
+
+3. Confirm the resolved base is reachable from the worktree HEAD:
+
+   ```bash
+   git -C "$TARGET_PATH" merge-base --is-ancestor "$RESOLVED_BASE_SHA" "$OBSERVED_HEAD_SHA"
+   ```
+
+   - Exit `0` → base is contained in the worktree HEAD; continue to Step 3.
+   - Non-zero exit → base mismatch.
+
+**On base mismatch:** treat as a bootstrap failure. Do **not** silently land at the wrong base, do **not** proceed to baseline checks. Apply the configured baseline policy to the failure:
+
+- `strict` → return immediately with `status: failed`, `reason: base-mismatch`, populated `expected_base_sha` and `observed_head_sha`, and the worktree path. The orchestrator is expected to cancel the dispatch and degrade.
+- `allow-failing` → emit a structured warning (`reason: base-mismatch`, with `expected_base_sha` and `observed_head_sha`), append a base-mismatch entry to `implementation.md` if an active project exists, and continue to Step 3 only if the caller has explicitly opted into a degraded outcome. In all other cases prefer fail-fast — base mismatch is rarely recoverable.
+
 ### Step 3: Run Baseline Checks
 
 Execute in the target worktree directory:
@@ -162,10 +195,12 @@ oat sync --scope all
 Return a structured status object (for orchestrator consumption):
 
 ```yaml
-status: success | error | warning
+status: success | error | warning | failed
 worktree_path: '{absolute-path}'
 branch: '{branch-name}'
 base_ref: '{base-ref}'
+resolved_base_sha: '{sha resolved from base-ref}'
+observed_head_sha: '{sha of worktree HEAD after add}'
 checks:
   worktree_init: pass | fail | skip
   project_status: pass | fail | skip
@@ -174,25 +209,32 @@ checks:
   provider_sync: pass | fail | skip
 warnings: [] # List of warning messages (allow-failing mode)
 error: null # Error message (strict mode failure)
+reason: null # Structured reason on failure (e.g., base-mismatch)
+expected_base_sha: null # Populated when reason is base-mismatch
 baseline_policy: strict | allow-failing
 ```
 
+`resolved_base_sha` and `observed_head_sha` are populated on **every** terminal status (success, warning, error, failed) so callers can perform belt-and-suspenders post-verification on the success path as well as diagnose the failure path.
+
 **Status determination:**
 
-- `success`: All checks passed.
-- `warning`: Some checks failed under `allow-failing` policy.
-- `error`: A check failed under `strict` policy, or worktree creation failed.
+- `success`: All checks passed and Step 2.7 base-resolution verification passed.
+- `warning`: Some checks failed under `allow-failing` policy (Step 2.7 still passed).
+- `error`: A baseline check failed under `strict` policy, or worktree creation failed.
+- `failed` (with `reason: base-mismatch`): Step 2.7 base-resolution verification failed. Callers should treat this distinctly from a generic baseline error — it is a contract violation, not a flaky check.
 
 ## Error Handling
 
-| Scenario                             | Behavior                                        |
-| ------------------------------------ | ----------------------------------------------- |
-| Worktree creation fails              | Return error status with git error message      |
-| Branch already checked out elsewhere | Return error with worktree location info        |
-| Baseline check fails (strict)        | Return error with check name and failure output |
-| Baseline check fails (allow-failing) | Add to warnings, continue, log to artifacts     |
-| No active project                    | Skip artifact logging, use console only         |
-| Invalid branch name                  | Return error before attempting creation         |
+| Scenario                                   | Behavior                                                                                                                   |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| Worktree creation fails                    | Return error status with git error message                                                                                 |
+| Branch already checked out elsewhere       | Return error with worktree location info                                                                                   |
+| Base mismatch (Step 2.7 fails, strict)     | Return `status: failed`, `reason: base-mismatch`, with `expected_base_sha` and `observed_head_sha`. Do not run baselines.  |
+| Base mismatch (Step 2.7 fails, allow-fail) | Emit structured warning with `reason: base-mismatch`, log to artifacts, prefer fail-fast unless caller opted into degrade. |
+| Baseline check fails (strict)              | Return error with check name and failure output                                                                            |
+| Baseline check fails (allow-failing)       | Add to warnings, continue, log to artifacts                                                                                |
+| No active project                          | Skip artifact logging, use console only                                                                                    |
+| Invalid branch name                        | Return error before attempting creation                                                                                    |
 
 ## Artifact Logging
 
@@ -211,6 +253,18 @@ Append to `implementation.md` under `## Implementation Log`:
 - {check_name}: {failure summary}
 ```
 
+When a base mismatch is detected (Step 2.7) and an active project exists, append a distinct entry regardless of baseline policy so post-mortems can find it:
+
+```markdown
+### {YYYY-MM-DD} — Base Mismatch (autonomous bootstrap)
+
+**Worktree:** {path}
+**Branch:** {branch-name}
+**Expected base SHA:** {expected_base_sha}
+**Observed HEAD SHA:** {observed_head_sha}
+**Base ref:** {base-ref}
+```
+
 ## Policy Flags
 
 | Flag                | Type                        | Default  | Description                                  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.0.52",
+  "version": "0.0.53",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -33,7 +33,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.0.52"
+    "@open-agent-toolkit/control-plane": "0.0.53"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",