@open-agent-toolkit/cli 0.0.52 → 0.0.54

package/assets/skills/oat-project-design/references/selective-review-pass.md

@@ -0,0 +1,112 @@
+# Selective Review Pass
+
+This reference defines the prose-driven classification pass used by `oat-project-design` when `DESIGN_MODE == "selective"`. The skill body owns flow; this file owns the heuristic.
+
+## Signal Set
+
+Classify each design section as `routine` or `needs-eyes`. Bias is conservative: any one `needs-eyes` signal marks the section `needs-eyes`.
+
+Always `needs-eyes`:
+
+- `Overview + Architecture`
+- `Security Considerations`
+- `Performance Considerations`
+- `Error Handling`
+- `Migration Plan`
+
+Per-section `needs-eyes` signals:
+
+- The user flagged concern, uncertainty, or worry about this area during discovery.
+- Discovery Open Questions mention this area.
+- Three or more spec FRs/NFRs directly touch this area.
+- Component boundaries cross modules not already described in `.oat/repo/knowledge/architecture.md`.
+- The section introduces a pattern absent from `.oat/repo/knowledge/conventions.md` and `.oat/repo/knowledge/stack.md`.
+- The section changes public API, CLI, configuration, workflow semantics, defaults, or persisted state.
+- The section introduces a new dependency, provider, service, storage model, permission boundary, or external integration.
+- The section depends on knowledge files that are missing, stale, or too thin to support a low-risk classification.
+
+`routine` means the section follows established repo patterns, is low-risk, and has enough grounding to draft silently. It does not mean the section is unimportant; it still appears in the committed design and final review gate.
+
+## Adequate Grounding
+
+Grounding is adequate when at least one strong source, or two weaker sources, exists for the design surface:
+
+- Strong sources: `.oat/repo/knowledge/project-index.md`, `.oat/repo/knowledge/architecture.md`, or a configured docs app with relevant architecture/convention docs.
+- Weaker sources: non-thin `docs/`, `.oat/repo/knowledge/conventions.md`, `.oat/repo/knowledge/stack.md`, `.oat/repo/knowledge/concerns.md`, discovery notes with concrete implementation context, or existing nearby implementation patterns found in the repo.
+
+Treat grounding as broadly absent when discovery skipped solution-space exploration and the knowledge base/docs are sparse. In that case, do not recommend Selective Collaborative; prefer Collaborative.
+
+## Recommendation Rules
+
+Before the picker, run a lightweight classification preflight against the shared section list. Assign Selective Collaborative one of four states:
+
+- `recommended`: grounding is adequate and at least 3 sections, or roughly 30-40% of sections, classify as `routine`.
+- `available`: grounding is adequate but Collaborative is still the safer default.
+- `available-not-recommended`: grounding exists, but savings are marginal for this design.
+- `unavailable`: grounding is broadly absent.
+
+Default recommendation is Collaborative when in doubt. Draft-and-review is never the picker default unless explicitly selected through argument, environment, or config.
+
+## Edge Cases
+
+- If every section is `needs-eyes`, Selective Collaborative collapses to Collaborative. Emit: "All sections flagged for review — running as full collaborative."
+- If zero sections are `needs-eyes`, force `Overview + Architecture` to `needs-eyes` so the user sees the framing before silent drafting continues.
+- If a user elevates a `routine` section in the Section Review Plan, keep it `needs-eyes` for the rest of the run.
+- If the user chooses "walk me through every remaining section" during a needs-eyes confirmation, mark all remaining sections `needs-eyes`.
+- If the classification cannot explain its reason in one sentence, treat the section as `needs-eyes`.
+
+## Examples
+
+Routine example:
+
+| Section          | Classification | Reason                                                                                             | Signals hit         |
+| ---------------- | -------------- | -------------------------------------------------------------------------------------------------- | ------------------- |
+| Testing Strategy | routine        | Follows existing requirement-to-test mapping pattern and no discovery uncertainty touches testing. | established pattern |
+
+Needs-eyes example:
+
+| Section    | Classification | Reason                                                                | Signals hit                                 |
+| ---------- | -------------- | --------------------------------------------------------------------- | ------------------------------------------- |
+| API Design | needs-eyes     | Adds a new public CLI/config surface that changes workflow semantics. | public API/CLI/config, user-facing defaults |
+
+## Dogfood Notes
+
+Use this section to capture misclassifications found while dogfooding Selective Collaborative mode. Keep entries short and actionable.
+
+Template:
+
+```markdown
+- Date/project:
+- Section:
+- Classified as:
+- Should have been:
+- Missed or overweighted signal:
+- Prose adjustment:
+```
+
+### Dogfood run 2026-04-30: collaborative-design-workflow
+
+Classification pass run manually against this project's own `spec.md`, `design.md`, `discovery.md`, and `.oat/repo/knowledge/*` context. Grounding was adequate (`project-index.md`, `architecture.md`, `conventions.md`, `stack.md`, and detailed discovery/design artifacts exist). Result: Selective Collaborative would be `recommended` because 3 of 12 sections classify as `routine` while high-risk sections still receive live review.
+
+| Section                                             | Classified As | Expected? | Notes                                                                 |
+| --------------------------------------------------- | ------------- | --------- | --------------------------------------------------------------------- |
+| Overview + Architecture                             | needs-eyes    | yes       | Forced floor; user should see framing before any silent drafting.     |
+| Component Design                                    | needs-eyes    | yes       | Cross-skill workflow semantics and config/skill boundaries changed.   |
+| Data Models                                         | routine       | yes       | No database/domain model changes; config risk covered elsewhere.      |
+| API Design                                          | needs-eyes    | yes       | Public CLI/config surface changes via `workflow.designMode`.          |
+| Security Considerations                             | needs-eyes    | yes       | High-risk-by-default section.                                         |
+| Performance Considerations                          | needs-eyes    | yes       | High-risk-by-default section.                                         |
+| Error Handling                                      | needs-eyes    | yes       | High-risk-by-default section.                                         |
+| Testing Strategy (with Requirement-to-Test Mapping) | needs-eyes    | yes       | New prose-contract validation plus manual dogfood acceptance surface. |
+| Deployment Strategy                                 | routine       | yes       | No deployment-path change; release packaging validated separately.    |
+| Migration Plan                                      | needs-eyes    | yes       | High-risk-by-default section, even when no migration is expected.     |
+| Implementation Phases                               | routine       | yes       | Follows established OAT plan/task structure.                          |
+| Risks and Mitigation                                | needs-eyes    | yes       | New user-facing workflow mode and heuristic failure modes.            |
+
+No classification misfires were identified in this artifact-only pass. Live picker taxonomy, mid-flight elevation, and final recap behavior still require an interactive dogfood run because `oat-project-design` is a provider skill, not an executable CLI command.
+
+Deferred follow-up dogfood after this PR opens:
+
+- Exercise picker taxonomy live paths: `Recommended`, `Available / not recommended`, and `Unavailable`.
+- Select "walk me through every remaining section" during a needs-eyes confirmation and verify every remaining section is presented.
+- Confirm the final user-review gate lists sections drafted without live confirmation.

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-discover
-version: 1.3.0
+version: 2.0.0
 description: Use when starting a project or when requirements are still unclear. Runs structured discovery to gather requirements, constraints, and context.
 disable-model-invocation: true
 user-invocable: true
@@ -322,7 +322,7 @@ If `"discovery"` is in `oat_hill_checkpoints`, require explicit user approval be
 
 **Approval prompt (required):**
 
-- "Discovery artifact is ready. Approve discovery and unlock `oat-project-spec`?"
+- "Discovery artifact is ready. Approve discovery and unlock `oat-project-design`?"
 
 **Optional independent review path:**
 
@@ -347,7 +347,7 @@ Update frontmatter:
 ```yaml
 ---
 oat_status: complete
-oat_ready_for: oat-project-spec
+oat_ready_for: oat-project-design
 ---
 ```
 
@@ -383,7 +383,7 @@ Key decisions:
 - {Decision 1}
 - {Decision 2}
 
-Ready for specification phase"
+Ready for design phase"
 ```
 
 ### Step 15: Output Summary
@@ -391,5 +391,9 @@ Ready for specification phase"
 ```
 Discovery phase complete for {project-name}.
 
-Next: Create specification with the oat-project-spec skill
+Next: Create design with the oat-project-design skill (which will confirm
+requirements automatically and produce both spec.md and design.md).
+
+If you'd rather formalize requirements without designing yet, run
+`oat-project-spec` as a standalone step.
 ```

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-project-quick-start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 1.3.6
+version: 2.0.2
 description: Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
 argument-hint: '<project-name> ["project description"]'
 disable-model-invocation: true
@@ -170,7 +170,7 @@ git diff --cached --quiet || git commit -m "chore(oat): capture quick-start disc
 
 ### Step 2.5: Decision Point — Design Depth
 
-**Auto-advance rule:** If the request was classified as **well-understood** in Step 2a and discovery surfaced no architecture decisions, component boundary questions, or unexpected complexity, skip this decision point entirely and continue directly to Step 3. This preserves the minimal-ceremony contract for straightforward requests.
+**Auto-advance rule:** If the request was classified as **well-understood** in Step 2a and discovery surfaced no architecture decisions, component boundary questions, or unexpected complexity, skip this decision point entirely and continue directly to Step 2.6 (the requirements gate still fires before plan generation). This preserves the minimal-ceremony contract for straightforward requests.
 
 **Otherwise**, present the user with a choice about how to proceed:
 
@@ -188,15 +188,15 @@ Use `AskUserQuestion` to present this choice.
 - If discovery surfaced architecture choices, component boundaries, or data model questions → recommend "Lightweight design first"
 - If discovery revealed the scope is larger or more complex than initially expected → recommend "Promote to spec-driven"
 
-**If user chooses "Straight to plan":** continue to Step 3.
+**If user chooses "Straight to plan":** continue to Step 2.6 (requirements gate), then Step 3.
 
-**If user chooses "Lightweight design first":** execute Step 2.75 before continuing to Step 3.
+**If user chooses "Lightweight design first":** execute Step 2.75 before continuing to Step 3. The Step 2.6 requirements gate is skipped — Step 2.75's in-conversation design validation covers that ground.
 
 **If user chooses "Promote to spec-driven":**
 
 - Update `discovery.md` frontmatter:
   - `oat_status: complete`
-  - `oat_ready_for: oat-project-spec`
+  - `oat_ready_for: oat-project-design`
   - `oat_last_updated: {today}`
 - Update `state.md`:
   - `oat_workflow_mode: spec-driven`
@@ -211,9 +211,105 @@ git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md" ".oat/state.md"
 git diff --cached --quiet || git commit -m "chore(oat): promote quick-start discovery for {project-name}"
 ```
 
-- Inform the user: "Discovery is complete. Run `oat-project-spec` next to formalize requirements."
+- Inform the user: "Discovery is complete. Run `oat-project-design` next — it will confirm requirements and produce both `spec.md` and `design.md` in one collaborative pass. If you'd rather formalize requirements without designing yet, `oat-project-spec` remains available as an optional standalone step."
 - Stop here. Do not generate a plan.
 
+### Step 2.6: Requirements Gate (Straight-to-Plan Path)
+
+Fires only when the straight-to-plan path was chosen at Step 2.5 (explicit choice or auto-advance). Skip when the user selected "Lightweight design first" (Step 2.75 handles its own in-conversation confirmation) or "Promote to spec-driven".
+
+Single conversational turn — no loop inside the gate. If the user materially redirects scope, route OUT to lightweight design or back to discovery.
+
+> **Tool availability is not the same as interactivity.** If `AskUserQuestion` is unavailable but chat is available, present this gate as a plain chat message and wait for the user's reply. Do not auto-confirm just because the structured question tool is missing.
+
+```
+# Explicit non-interactive fallback FIRST (FR9 contract; same signal as
+# design mode choice). Lack of AskUserQuestion alone is NOT non-interactive
+# — if chat with the user is available, present the gate as a plain chat
+# message and wait for their reply instead.
+if [ "${OAT_NON_INTERACTIVE:-}" = "1" ] || no_user_response_channel_exists; then
+  echo "Requirements gate auto-confirmed in non-interactive mode."
+  # proceed to Step 3
+fi
+
+# Interactive bypass (power-user opt-out).
+if [ "${OAT_NO_REQUIREMENTS_GATE:-}" = "1" ] || [ "$ARG_NO_GATE" = "1" ]; then
+  # proceed to Step 3 silently
+fi
+
+# Extract requirements from discovery.md:
+#   - Key Decisions
+#   - Success Criteria
+#   - Constraints
+# Format as bullet list and present (SINGLE TURN):
+#
+#   > "Before I generate the plan, here are the requirements I'm building against:
+#   >
+#   >    Key decisions:
+#   >    - [decision 1]
+#   >    - [decision 2]
+#   >
+#   >    Success criteria:
+#   >    - [criterion 1]
+#   >
+#   >    Constraints:
+#   >    - [constraint 1]
+#   >
+#   >  Does this match what you want?"
+
+# AskUserQuestion multi-choice:
+#   1. Yes — proceed to plan generation
+#   2. Add a minor requirement that still fits this scope (capture inline, proceed — no re-present)
+#   3. Scope needs redirecting — rework discovery or produce a lightweight design first
+#
+# On choice 1: continue to Step 3.
+# On choice 2: prompt once for the addition, append to discovery.md, proceed to Step 3 (do NOT re-present).
+# On choice 3: exit the gate cleanly. Present follow-up choice:
+#   a. Produce a lightweight design first (run Step 2.75)
+#   b. Expand discovery (return to Step 2)
+# Route the user accordingly. Do NOT loop back into the gate.
+```
+
+### Step 2.75a: Lightweight Design Mode Choice
+
+Resolve the interaction mode before drafting. Same mechanics as the full `oat-project-design` skill (Component 1): argument precedes env var, config fallback, **explicit** non-interactive fallback to draft.
+
+> **Tool availability is not the same as interactivity.** If `AskUserQuestion` is unavailable but chat is available, ask the mode-choice question as a plain chat message and wait for the user's reply. Only fall back to draft when `OAT_NON_INTERACTIVE=1` is set or there is no user-response channel at all.
+
+```
+DESIGN_MODE="${ARG_MODE:-${OAT_DESIGN_MODE:-}}"
+if [ -z "$DESIGN_MODE" ]; then
+  if [ "${OAT_NON_INTERACTIVE:-}" = "1" ] || no_user_response_channel_exists; then
+    DESIGN_MODE="draft"
+    echo "Non-interactive context detected. Falling back to draft-and-review mode."
+  else
+    # Consult persisted preference (FR15 / Component 14) before prompting
+    CONFIG_MODE=$(oat config get workflow.designMode 2>/dev/null || echo "")
+    if [ "$CONFIG_MODE" = "collaborative" ] || [ "$CONFIG_MODE" = "selective" ] || [ "$CONFIG_MODE" = "draft" ]; then
+      DESIGN_MODE="$CONFIG_MODE"
+      if [ "$DESIGN_MODE" = "selective" ]; then
+        DESIGN_MODE="collaborative"
+        echo "Using workflow.designMode = selective from config (treating as collaborative for lightweight design; Selective Collaborative is only available in full oat-project-design)."
+      else
+        echo "Using workflow.designMode = ${DESIGN_MODE} from config."
+      fi
+    else
+      # Prefer AskUserQuestion for structured multi-choice when available.
+      # If AskUserQuestion is unavailable, ask the same question as a plain
+      # chat message and wait for the user's reply. Do NOT switch to draft
+      # mode just because the structured tool is missing.
+      #
+      # Prompt (SAME text as oat-project-design Step 1.5):
+      #   "How would you like to work through the lightweight design?
+      #     1. Collaborative (recommended) — section-by-section, one approach confirmation before drafting
+      #     2. Draft-and-review — full draft up front, you review holistically"
+      :
+    fi
+  fi
+fi
+echo "Running in ${DESIGN_MODE} mode."
+```
+
 ### Step 2.75: Lightweight Design (Optional)
 
 Produce a focused `design.md` covering only what's needed for a quality plan. This is NOT the full spec-driven design — it's a quick architectural sketch.
@@ -242,14 +338,37 @@ Copy template: `.oat/templates/design.md` → `"$PROJECT_PATH/design.md"`
 - Dependencies (captured in discovery instead)
 - Risks and Mitigation (captured in discovery instead)
 
-**Present design incrementally for validation:**
-
-1. Draft architecture overview → present to user for validation
-2. Draft component design → present to user for validation
-3. Draft data flow + testing approach → present to user for validation
-4. Finalize `design.md`
+**Draft the design based on `DESIGN_MODE` (resolved in Step 2.75a):**
 
-After each chunk, ask: "Does this look right, or should we adjust before continuing?"
+```
+IF DESIGN_MODE == "collaborative":
+  For SECTION in [Overview, Architecture, Component Design, Testing Strategy
+                  (required); Data Models, API Design, Error Handling
+                  (include only when relevant); SKIP Security, Performance,
+                  Deployment, Migration]:
+    Draft section content. Scale each section to its complexity:
+      a few sentences if straightforward, up to 200-300 words if nuanced.
+    Not-applicable sections: state as a single sentence, not empty.
+    Present:
+      "Here's what I have for [section]: [content].
+       Does this look right, or should we adjust before continuing?"
+    Use AskUserQuestion for the validation prompt.
+    Revise inline on feedback. Be ready to go back and clarify if something
+      doesn't make sense. Re-present if substantive.
+    Mark section approved. Move to next.
+
+IF DESIGN_MODE == "draft":
+  Draft all required sections (Overview, Architecture, Component Design,
+    Testing Strategy) and any applicable optional sections (Data Models,
+    API Design, Error Handling) in ONE pass (same reduced section set).
+  Scale each section to its complexity — no per-section prompts fire.
+  Run the FULL 4-check self-review (placeholder + internal consistency +
+    scope + ambiguity). No scaled-down variant — identical to the full
+    oat-project-design self-review.
+  Present the user-review gate wording (adapted for quick-start:
+    no HiLL gate by default; commits-first is still in effect).
+  Produce design.md only — NO spec.md is written by lightweight design.
+```
 
 If `design.md` or `state.md` was updated before one of these validation pauses, commit those artifact changes before waiting for the user response.
 

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

@@ -1,7 +1,7 @@
 ---
 name: oat-project-spec
-version: 1.2.0
-description: Use when discovery is complete and the project needs a formal requirements baseline. Transforms discovery output into structured specification artifacts.
+version: 2.0.0
+description: Optional standalone skill for formalizing requirements into a structured spec.md when discovery is complete but you're not ready to design yet. Independent of the design workflow — oat-project-design confirms requirements automatically and does not require this skill to be run first.
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
@@ -450,7 +450,7 @@ Ready for design phase"
 ### Step 21: Output Summary
 
 ```
-Specification phase complete for {project-name}.
+Specification artifact created for {project-name}.
 
 Created:
 - {N} functional requirements
@@ -458,7 +458,12 @@ Created:
 - High-level design approach
 - Success metrics
 
-Next: Create detailed design with the oat-project-design skill
+Note: This skill is optional in the default workflow. `oat-project-design`
+will confirm requirements automatically when run after discovery.
+
+If you want to proceed to design now, run: `oat-project-design`
+If you're parking the project here, the spec.md is committed and ready
+to pick up later.
 ```
 
 ## Success Criteria

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/assets/templates/discovery.md

@@ -129,7 +129,16 @@ _Include this section only when the request is exploratory or multiple viable ap
 
 Use this discovery artifact to drive the next workflow step:
 
-- **Quick mode → straight to plan:** proceed directly to `plan.md` when scope is clear and no architecture decisions remain.
-- **Quick mode → optional lightweight design:** produce a focused `design.md` (architecture, components, data flow, testing) before planning. Choose this when discovery surfaced architecture choices or component boundaries.
-- **Quick mode → promote:** escalate to spec-driven if discovery revealed the scope is larger or more complex than expected.
-- **Spec-driven mode:** continue to `oat-project-spec` (after HiLL approval if configured).
+- **Spec-driven mode:** continue to `oat-project-design` (which confirms
+  requirements and produces both `spec.md` and `design.md`).
+- **Spec-driven mode → formalize-only:** use `oat-project-spec` standalone
+  if you want a formalized requirements artifact but aren't ready to
+  design yet.
+- **Quick mode → straight to plan:** proceed directly to `plan.md` when
+  scope is clear and no architecture decisions remain.
+- **Quick mode → optional lightweight design:** produce a focused
+  `design.md` (architecture, components, data flow, testing) before
+  planning. Choose this when discovery surfaced architecture choices
+  or component boundaries.
+- **Quick mode → promote:** escalate to spec-driven if discovery revealed
+  the scope is larger or more complex than expected.

package/dist/commands/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAOhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqDpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAwjCD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CA0GT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAOhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsDpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAskCD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CA0GT"}