orchid-sdd 0.2.0 → 0.3.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "orchid-sdd",
   "displayName": "orchid-sdd",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Memory-backed, specification-driven development for Claude Code. Explicit-only /orchid-sdd:run workflow with a local Node CLI.",
   "author": {
     "name": "orchid-sdd contributors"

package/.skill/steering/default-presets/repository-flow.md

@@ -16,17 +16,23 @@ The project must declare one repository workflow and use it consistently:
 - **XP mainline:** direct integration to main is allowed only for small, tested, reversible
   changes with the configured review or pairing evidence.
 
-If no repository preset is active, orchid-sdd's default build flow uses an integration branch and
-does not merge to the default branch during build. If `repository-trunk-based`,
-`repository-gitflow`, or `repository-xp-mainline` is active, that preset is authoritative for
-the concrete branch flow; this core rule checks that the declared workflow and the actual
-commands agree. A project selecting XP mainline must also update its execution and release
-configuration and record the decision in an ADR.
+If no repository preset is active, orchid-sdd's build flow uses the iteration's
+feature/integration branch only when the user opted in; otherwise prompt branches merge into
+the current branch. The default branch is not touched during build. If
+`repository-trunk-based`, `repository-gitflow`, or `repository-xp-mainline` is active, that
+preset is authoritative for the concrete branch flow; this core rule checks that the declared
+workflow and the actual commands agree. A project selecting XP mainline must also update its
+execution and release configuration and record the decision in an ADR.
 
 # Checks
 
 - The default branch is named and protected by policy.
 - The branch owner and merge target are clear before work starts.
+- A feature branch is created only when the user asks for one; otherwise work stays on the
+  current branch.
+- Each prompt uses one disposable worktree and temporary branch, deleted immediately after CR
+  and merge.
+- No orphan `orchid/<iteration>/<prompt-id>` branch or worktree remains at G5 or closure.
 - Changes are small enough to review and reverse.
 - Commit messages identify the requirement or prompt when the project uses traceability.
 - Direct pushes to the default branch are either explicitly allowed by the selected preset or
@@ -37,12 +43,14 @@ configuration and record the decision in an ADR.
 
 # Evidence
 
-- Discovery: record the workflow and any repository constraints in `discovery/steering.md`.
+- Discovery: record the workflow, feature-branch decision, and base branch in
+  `discovery/steering.md`.
 - Assessment: note branch/release impact and rollback strategy.
-- Build: branch names, commits, and merge target are visible in the prompt report.
+- Build: branch names, worktree path, commits, merge target, and branch deletion are visible
+  in the prompt report.
 - Code review: review the integration diff, not the implementer’s local branch.
-- Logic review: confirm the delivered change is on the expected branch and no stray merge or
-  release action occurred.
+- Logic review: confirm the delivered change is on the expected branch; no prompt branch,
+  worktree, or stray merge remains.
 
 # Exceptions
 

package/.skill/templates/artifacts/trd.md

@@ -27,5 +27,11 @@ What could break; how it is guarded.
 ## Versioning and release
 Compatibility, flags, rollout, rollback.
 
+## Branch strategy
+- Feature branch: yes/no
+- Base branch: main/develop
+- Integration target: <feature branch, or the current branch when no feature branch is used>
+- Prompt branches: one disposable worktree/branch per prompt, deleted after CR and merge
+
 ## Criticalities
 Top risks and open technical questions.

package/README.md

@@ -220,6 +220,7 @@ orchid-sdd gate pass G1 --evidence intent/prd.md
 orchid-sdd discover
 # ... assess, plan, build, review ...
 orchid-sdd close --approve
+# Agent: "Do you want to start the technical handover?"
 orchid-sdd handover --approve
 ```
 
@@ -392,6 +393,11 @@ Use `--global` for a user-wide install, `--dest DIR` for a custom directory, `--
 preview, and `--force` only after reviewing an existing installation. There is no
 `postinstall` side effect.
 
+`setup` and `skill install` are independent: `setup` initializes the project artifacts
+(`.orchid/`, `.knowledge/`, `orchid-sdd.yml`), while `skill install` writes the agent skill
+(`.opencode/skills/orchid-sdd`). Either order works; run `setup` first if you want the skill
+usable immediately. Installing the npm package does not create `.opencode/skills`.
+
 For the Vercel Agent Skills catalog:
 
 ```bash
@@ -910,7 +916,7 @@ Every referenced persona must exist and be enabled.
 | `execution.max_parallel` | `4` | Maximum simultaneous prompts/reviews | Agent |
 | `execution.isolation` | `worktree` | `worktree`, `clone`, or `branch`; `branch` requires `max_parallel: 1` | Agent/CLI (doctor) |
 | `execution.require_clean_tree` | `true` | `start` refuses a dirty root/repo | CLI |
-| `execution.integration_branch` | `orchid/{iteration}/integration` | Build merge target | Agent |
+| `execution.integration_branch` | `orchid/{iteration}/integration` | Feature/integration branch used only when the user opts in; otherwise prompts merge into the current branch | Agent |
 | `execution.release_strategy` | `squash` | `squash`, `pr`, or `none` at closure | Agent/Policy |
 | `execution.merge` | `orchestrator` | Who performs merges | Agent/Policy |
 | `execution.max_fix_loops` | `3` | CR fix attempts before escalation | Agent |
@@ -918,6 +924,12 @@ Every referenced persona must exist and be enabled.
 | `execution.test_commands.integration` | profile default | Integration test command | Agent/Setup |
 | `execution.test_commands.e2e` | profile default | End-to-end test command | Agent/Setup |
 
+At Intent, the skill asks whether to create a feature branch and which base branch to use
+(`main`/`develop`; default `project.default_branch`, or `develop` for Git-flow). If the answer
+is no, it stays on each affected repository's current branch. Every prompt uses one disposable
+worktree and temporary branch (`orchid/<iteration>/<prompt-id>`), deleted immediately after CR
+and merge; closure verifies that no prompt branch or worktree remains.
+
 ### Reviews
 
 | Key | Default | Meaning / values | Acted on by |
@@ -1183,7 +1195,7 @@ example fit (closest approved shape), and conflict check (requirements that cont
 blocking rule). Record them in `discovery/steering.md`; G2 can cite that file.
 
 **Suggested Logic Review rules.** Use `logic-review-steering`: rule coverage (every active
-blocking rule has a verdict), evidence freshness (integration branch, not a local branch),
+blocking rule has a verdict), evidence freshness (chosen integration target, not a throwaway prompt branch),
 scope integrity (no deleted tests or hidden suppressions), exception integrity (waivers name
 owner and expiry), and behavioral fit (the delivered behavior still matches the requirement).
 Record them in `reviews/steering-review.md`; G6 can cite that file.
@@ -1369,7 +1381,7 @@ gates marked below. The CLI cannot verify who invoked it, so the process must no
 The agent asks before a human gate and only runs the command after an explicit answer:
 
 ```text
-Agent: "G1 evidence is ready: intent/prd.md. Do you approve?"
+Agent: "G1 evidence is ready: intent/prd.md. Approve the changes and move forward."
 Human: "Approved."
 Agent: orchid-sdd gate pass G1 --evidence intent/prd.md
 ```

package/SKILL.md

@@ -25,7 +25,8 @@ Implementers, reviewers, and assessment lenses run as subagents with fresh conte
 - The CLI is the only writer of state, events, manifest, indexes, and the matrix.
 - Never edit `.knowledge/**`, `manifest.jsonld`, or the index files by hand.
 - Deterministic operations go through the CLI: setup, record, index, lint, gates, close.
-- Code reaches the default branch only at closure. Build merges go to the integration branch.
+- Code reaches the default branch only at closure. Build merges go to the iteration's
+  feature/integration branch, or to the current branch when no feature branch was chosen.
 
 # User-facing output
 
@@ -116,11 +117,20 @@ A gate passes only with evidence. Never pass a gate on a promise.
 | G4 Plan | valid DAG, disjoint waves, coverage, cost estimate within budget | yes |
 | G5 Prompt | acceptance met, tests green, CR passed, anchors/docblocks valid, merged to integration | per prompt, no |
 | G6 Logic review | scenarios verified; steering review complete; no open business or blocking steering findings; scope matches intent | yes |
-| G7 Closure | prompts done/waived; audit archived; integration merged; release notes | yes |
+| G7 Closure | prompts done/waived; audit archived; feature/integration merged to base or current branch already base; prompt branches deleted; release notes | yes |
 | G8 Handover | HANDOVER.md + tour.md verified | yes |
 
 Use `--evidence <iteration-relative path>` or `--note "why"`; both are logged.
 
+Before a human gate, end the message with this exact request:
+
+> **Approve the changes and move forward.**
+>
+> Evidence: `<iteration-relative paths>`. Reply `approve` to record the gate, or list
+> the changes required.
+
+Wait for an explicit answer. Do not run `gate pass` or advance the phase first.
+
 The orchestrator executes `gate pass|fail` after the required authorization. The CLI
 records the decision; it cannot verify human identity or semantic quality. Never treat a
 passing command as proof of human approval, and never auto-pass a human gate. G5 is the
@@ -147,6 +157,11 @@ before G1.
 
 Artifacts: `intent/title.md`, `intent/prd.md`, `intent/trd.md`.
 
+- Branch strategy: before implementation, ask whether to create a feature branch. If yes,
+  ask the base branch (`main`/`develop`; default `project.default_branch`, or `develop` for
+  Git-flow) and record the answer in `intent/trd.md`. Use one feature/integration branch for
+  the iteration; do not create both a feature branch and a separate integration branch. If
+  the answer is no, use the current branch of each affected repo.
 - Validate the title: ≤500 chars, names subject + change + outcome. If vague, ask at most
   five clarifying questions with examples.
 - PRD: problem, users, current behaviour, desired outcome, flows, business rules, metrics,
@@ -214,11 +229,13 @@ Artifacts: `plan/plan.json`, `plan/matrix.md`, `plan/matrix.json`, `plan/cost-es
 
 ## Phase 5 — Build and adversarial CR
 
-- Select ready prompts; create a worktree and branch `orchid/<iteration>/<prompt-id>`.
+- Select ready prompts. Create one worktree and one temporary branch
+  `orchid/<iteration>/<prompt-id>` per prompt; never reuse a prompt branch.
 - Run `orchid-sdd route --phase build --prompt <prompt-id>` before execution and alert the user
   on `unknown` or `mismatch`.
 - Record the prompt with `orchid-sdd prompt start <prompt-id> --step implement`; advance safe
-  steps with `prompt step` and finish with `prompt complete|fail|waive`.
+  steps with `prompt step`. Finish with `prompt complete|fail|waive` only after tests, CR,
+  merge, and branch cleanup.
 - Give each implementer a context pack, not the repository.
 - Keep inline comments why-only; update the anchor and docblock for significant units, with
   history in the docblock.
@@ -228,10 +245,16 @@ Artifacts: `plan/plan.json`, `plan/matrix.md`, `plan/matrix.json`, `plan/cost-es
   S-size work; independence and the rubric are unchanged. Check active steering rules and cite
   violations in `reviews/steering.md`.
 - Fix loop up to `max_fix_loops`; then `escalated`: accept with ADR, split, or revert.
-- Merge to `orchid/<iteration>/integration` in wave order. Do not merge to the default branch
-  during build unless an active repository steering rule explicitly permits direct mainline
-  integration and records the evidence.
-- A prompt is done only when acceptance, tests, CR, anchors/docblocks, and the matrix agree.
+- Merge to the iteration's feature/integration branch in wave order, or to the current branch
+  when the user chose no feature branch. Do not merge to the default branch during build
+  unless an active repository steering rule explicitly permits direct mainline integration
+  and records the evidence.
+- Immediately after CR passes and the merge lands, remove the prompt worktree
+  (`git worktree remove <path>`) and delete its temporary branch
+  (`git branch -D orchid/<iteration>/<prompt-id>`). This is mandatory: a prompt is not done
+  while its worktree or branch still exists. Clean up failed and waived prompts the same way.
+- A prompt is done only when acceptance, tests, CR, anchors/docblocks, branch cleanup, and the
+  matrix agree.
 
 ## Phase 6 — Logic review (PM)
 
@@ -241,24 +264,34 @@ Artifacts: `reviews/logic-review.md`, `reviews/steering-review.md`.
 - Review behaviour against PRD/TRD/Gherkin, the integration diff, and the steering rules.
 - Walk every scenario; check invariants, scope creep, dropped requirements, copy, error
   states, accessibility, and prior regressions.
+- Verify the change is explainable in business terms. The full human tutorial is Phase 8
+  (`HANDOVER.md` + `tour.md`); it is not a Phase 6 artifact.
 - For each steering rule, record `satisfied`, `not applicable`, `finding`, or `waived` with
   current evidence in `reviews/steering-review.md`; a blocking rule without evidence stops G6.
 - Findings become new prompts (spec version increments) or a waived risk with an ADR.
 - Loop capped at `reviews.logic.max_loops`; survivors become a follow-up iteration.
-- Pass G6, then `orchid-sdd close --approve`.
+- End with the human-gate request: **Approve the changes and move forward.** Include the
+  verdict and evidence. After explicit approval, pass G6 and run
+  `orchid-sdd close --approve`.
 
 ## Phase 7 — Closure
 
 - Confirm every prompt is `done` or `waived`; tests green; lint/index current.
+- Verify branch hygiene: no prompt worktrees and no `orchid/<iteration>/<prompt-id>`
+  branches remain.
 - Move prompts, bus, and runs to `audit/`; keep the matrix as the index.
-- Write `release-notes.md`; merge integration to the default branch per
-  `execution.release_strategy`; tag/freeze the iteration.
+- Write `release-notes.md`; merge the feature/integration branch to the chosen base per
+  `execution.release_strategy`, then delete it unless repository policy explicitly requires
+  retention and records it. If no feature branch was used, the current branch is already the
+  base.
 - Mark closed and rebuild the manifest. A closed iteration is immutable.
 - If it will not ship, use `orchid-sdd abandon "<reason>"` instead.
+- After closure, ask: **Do you want to start the technical handover?** Wait for the
+  answer before starting Phase 8.
 
 ## Phase 8 — Handover
 
-Generate `handover/HANDOVER.md` and `handover/tour.md`. Explain what changed, why, where
+On confirmation, generate `handover/HANDOVER.md` and `handover/tour.md`. Explain what changed, why, where
 to look, how to run/test, how to roll back, and what remains. The tour is 10–15 ordered
 stops with anchors and test commands. Verify links and commands, then
 `orchid-sdd handover --approve`.
@@ -280,8 +313,8 @@ explicit project decisions that must be checked and cited.
   language example and adapt it to the project’s real conventions.
 - Discovery converts applicable rules into requirements, scenarios, questions, assumptions, or
   ADR-backed exceptions. It does not review implementation style.
-- Logic review verifies every active rule against the integration branch, records a verdict and
-  evidence in `reviews/steering-review.md`, and stops on an unresolved blocking rule.
+- Logic review verifies every active rule against the chosen integration target, records a
+  verdict and evidence in `reviews/steering-review.md`, and stops on an unresolved blocking rule.
 - Do not enable competing architecture, style-tool, or repository presets. An exception is an
   ADR, not a silent waiver.
 - The CLI validates references, but the agent owns semantic compliance. `steering context`

package/cli/phases.mjs

@@ -91,13 +91,13 @@ function validateTitle(raw, maxChars) {
 
 function nextAction(phase) {
   const actions = {
-    intent: "Write intent/prd.md and intent/trd.md, then `orchid-sdd gate pass G1 --evidence intent/prd.md`.",
+    intent: "Ask whether to create a feature branch and which base (main/develop); write intent/prd.md and intent/trd.md, then `orchid-sdd gate pass G1 --evidence intent/prd.md`.",
     discovery: "Apply steering, capture discovery/Gherkin/questionnaires, write discovery/steering.md; then `orchid-sdd gate pass G2 --evidence discovery/gherkin`.",
     assessment: "Run the impact lenses and negotiation; then `orchid-sdd gate pass G3 --evidence assessment/negotiation.md`.",
     planning: "Generate the prompt DAG and cost estimate; then `orchid-sdd gate pass G4 --evidence plan/plan.json`.",
     build: "Execute ready prompts with `orchid-sdd build --all`; then `orchid-sdd gate pass G5 --note \"all prompts reviewed\"`.",
-    logic_review: "Verify steering, write reviews/steering-review.md, then `orchid-sdd gate pass G6 --evidence reviews/steering-review.md`.",
-    closed: "Run `orchid-sdd handover`, then `orchid-sdd handover --approve`.",
+    logic_review: "Verify scenarios and steering, write reviews/logic-review.md and reviews/steering-review.md; ask the human \"Approve the changes and move forward.\" Then `orchid-sdd gate pass G6 --evidence reviews/logic-review.md`.",
+    closed: "Ask \"Do you want to start the technical handover?\" If yes, run `orchid-sdd handover`, then `orchid-sdd handover --approve`.",
     handover: "Iteration complete.",
     abandoned: "Start a new iteration with `orchid-sdd start`.",
     setup: "Run `orchid-sdd setup`.",

package/cli/setup.mjs

@@ -34,6 +34,8 @@ export function agentsBlock(knowledgeFolder, constitutionFolder = ".orchid/const
 - Read \`orchid-sdd steering context --phase <phase>\` before Discovery and Logic Review; apply every active rule and cite its ID.
 - Run \`orchid-sdd route --phase <phase>\` before work; if the current model/agent is unknown or mismatched, tell the user. Never switch automatically.
 - Track development prompts with \`orchid-sdd prompt start|step|complete\`; save a checkpoint with \`orchid-sdd handoff prepare\` before changing harness.
+- Ask before starting whether to create a feature branch and from which base; record the answer in the TRD. If not, stay on the current branch.
+- Each prompt gets one disposable worktree and temporary branch; remove both immediately after CR and merge. Never leave an \`orchid/<iteration>/<prompt-id>\` branch behind.
 ${AGENTS_END}
 `;
 }

package/cli/util.mjs

@@ -2,7 +2,10 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
-export const SKILL_VERSION = "0.2.0";
+const packageJson = JSON.parse(
+  fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+export const SKILL_VERSION = packageJson.version;
 export const SCHEMA_VERSION = "1.0.0";
 
 export class OrchidError extends Error {

package/docs/orchid-sdd-design.md

@@ -21,7 +21,7 @@
 2. Keep **intent, discovery, and assessment separate**; do not ask technical personas to define business meaning, or business personas to estimate code impact.
 3. Make the manifest a **generated projection of append-only events**, not a hand-edited JSON file.
 4. Document code in **three tiers**: a one-line `ORCHID-MEM` anchor, a Markdown docblock, and the manifest graph.
-5. Turn work into **prompt contracts** with dependencies, disjoint write scopes, tests, and acceptance commands; parallelism is proven by the plan, code lands on an integration branch, and the default branch is touched only at closure unless an explicit XP-mainline steering rule permits otherwise.
+5. Turn work into **prompt contracts** with dependencies, disjoint write scopes, tests, and acceptance commands; parallelism is proven by the plan, code lands on the iteration's feature/integration branch when the user opts in (otherwise on the current branch), and the default branch is touched only at closure unless an explicit XP-mainline steering rule permits otherwise.
 6. Review with **independent, persona-routed adversarial CR**, then a separate **PM logic review** against Gherkin.
 7. Treat personas as **role contracts** (phase, authority, triggers), not chatbots; treat the constitution as a **layered, lockable source of truth** for *how* code is written.
 8. Make the skill **explicit-only, portable, and self-contained**: an explicit command (`/orchid-sdd` in OpenCode, `orchid-sdd` at the CLI) is the only entry point, and the skill package is versioned separately from project knowledge.
@@ -356,8 +356,8 @@ execution:
   max_parallel: 4
   isolation: worktree          # worktree | clone | branch (§11.2)
   require_clean_tree: true
-  integration_branch: "orchid/{iteration}/integration"
-  release_strategy: squash     # squash | pr | none — how integration reaches the default branch at G7
+  integration_branch: "orchid/{iteration}/integration"  # feature branch when the user opts in; otherwise the current branch
+  release_strategy: squash     # squash | pr | none — how the iteration branch reaches its base at G7
   merge: orchestrator
   max_fix_loops: 3
   test_commands:
@@ -503,9 +503,9 @@ The orchestrator is the primary agent session in the host harness — in OpenCod
 | **G2** | Discovery signed off | Business impact, boundaries, Gherkin, traceability, zero blocking questions or recorded `Assumption` nodes; PM sign-off | Yes, if answers changed scope |
 | **G3** | Assessment decided | Impact map, contracts, regressions, options, ADRs; go/no-go decision | Yes |
 | **G4** | Plan approved | Valid DAG, disjoint waves, complete coverage, matrix generated, cost estimate within budget or explicitly overridden | Yes |
-| **G5** | Prompt done | Acceptance met, tests pass in a clean environment, CR passed, anchors/docblocks valid, merged to the integration branch | No, per prompt |
+| **G5** | Prompt done | Acceptance met, tests pass in a clean environment, CR passed, anchors/docblocks valid, merged to the chosen integration target, prompt worktree/branch deleted | No, per prompt |
 | **G6** | Logic review passed | Scenarios verified; no open business findings; scope matches intent | Yes |
-| **G7** | Closure complete | All prompts done or waived; manifest/index rebuilt; transients archived; integration merged to the default branch; release notes written | Yes |
+| **G7** | Closure complete | All prompts done or waived; manifest/index rebuilt; transients archived; feature/integration merged to its base (or current branch already base); prompt branches deleted; release notes written | Yes |
 | **G8** | Handover accepted | Handover and tour complete; links resolve; human acknowledges | Yes |
 
 Gates are enforced by the orchestrator, not by prompt instructions alone. A command that would cross a gate without evidence fails with the missing evidence listed.
@@ -518,7 +518,9 @@ the caller or the semantic quality of the evidence. A passing command is therefo
 proof of human approval, and a human gate must never be auto-passed. G5 is the
 agent/reviewer gate; G2 requires human confirmation only when answers changed scope. When no
 agent is running, the developer runs the same command manually. The agent-facing rules are
-in `SKILL.md`.
+in `SKILL.md`. At a human gate, the agent presents the evidence and ends with the exact
+request: **Approve the changes and move forward.** It records the gate only after an explicit
+answer.
 
 ### 4.7 Right-sizing and scope constraints
 
@@ -559,7 +561,7 @@ The skill exposes one explicit entry point with subcommands. Running `/orchid-sd
 | `/orchid-sdd discover` | 2 | PM-led requirements capture, Gherkin, consistency scan, questionnaires | G2 |
 | `/orchid-sdd assess` | 3 | Parallel technical impact analysis, negotiation, ADRs, go/no-go | G3 |
 | `/orchid-sdd plan` | 4 | Decompose into prompts, validate the DAG, generate the matrix | G4 |
-| `/orchid-sdd build [--all\|--wave N\|--prompt P-003]` | 5 | Execute ready prompts, verify tests, run adversarial CR, merge to the integration branch | G5 per prompt |
+| `/orchid-sdd build [--all\|--wave N\|--prompt P-003]` | 5 | Execute ready prompts, verify tests, run adversarial CR, merge to the feature/integration or current branch, delete prompt branches | G5 per prompt |
 | `/orchid-sdd review` | 6 | PM logic review against PRD/TRD/Gherkin; generate follow-up prompts if needed | G6 |
 | `/orchid-sdd close` | 7 | Freeze, archive transients, rebuild manifest/index, write release notes | G7 |
 | `/orchid-sdd handover` | 8 | Generate and verify the human tutorial | G8 |
@@ -709,6 +711,8 @@ intent/
 | "Fix performance" | "Reduce checkout API p95 latency from 1.8s to under 600ms for carts with more than 50 items" |
 | "Add Redis" | "Introduce a shared cache for product catalog reads to remove the repeated database fan-out during peak traffic" |
 
+**Branch strategy.** Before implementation, ask whether to create a feature branch. If yes, ask the base branch (`main`/`develop`; default `project.default_branch`, or `develop` for Git-flow) and record the answer in the TRD. The feature branch is the iteration's single integration target; do not create a separate feature branch and integration branch. If no, use each affected repository's current branch. Prompt branches are always disposable and are deleted after CR and merge.
+
 **PRD contents:** problem, affected users and personas, current behaviour, desired outcome, primary and alternate flows, business rules, success metrics, non-goals, assumptions, risks, open questions. No technology choices.
 
 **TRD contents:** technical constraints, proposed architecture direction, patterns to follow (with constitution references), expected deliverables (unit, integration, e2e), infrastructure/API/data hypotheses, regression strategy, versioning and release strategy, criticalities. The TRD is explicitly a **hypothesis**: Phase 3 validates or rejects it.
@@ -911,16 +915,16 @@ plan/                  # the prompt folder for this spec
 
 1. **Select ready prompts** whose dependencies are done and whose write scopes are disjoint.
 2. **Resolve routing** with `orchid-sdd route --phase build --prompt <prompt-id>`; if the current agent/model is unknown or mismatched, notify the user and do not switch automatically.
-3. **Isolate** each prompt in a worktree and branch (`orchid/<iteration>/<prompt-id>`), following the isolation and knowledge protocol (§11.2).
+3. **Isolate** each prompt in one disposable worktree and temporary branch (`orchid/<iteration>/<prompt-id>`), following the isolation and knowledge protocol (§11.2). Never reuse a prompt branch.
 4. **Build a context pack**, not a repository dump: the prompt, relevant spec slice, constitution sections, 1-hop memory, affected code, test commands, and known constraints.
 5. **Implement** the prompt, run the tests, keep inline comments why-only, update or create the anchor and docblock (including `History`), and write run artifacts and any message to the outbox; the orchestrator copies both back when the prompt completes.
 6. **Verify independently:** the orchestrator runs the acceptance commands in a clean environment. The implementer's claim is not evidence.
 7. **Review adversarially** with a fresh-context reviewer, routed by changed paths and topics.
 8. **Fix loop** up to `max_fix_loops`. A prompt that exhausts the loop enters `escalated` (§11.5): arbitration, split, or revert. A prompt never merges on a promise to fix later.
-9. **Merge into the integration branch** (`orchid/<iteration>/integration`) in wave order, through the orchestrator; the default branch is untouched during build unless an XP-mainline steering rule explicitly permits otherwise. Update the matrix and emit events. Commit and PR metadata carry the iteration and prompt IDs, the matrix slice, test evidence, and the CR verdict.
+9. **Merge into the iteration's feature/integration branch**, or into the current branch when the user chose no feature branch, in wave order through the orchestrator; the default branch is untouched during build unless an XP-mainline steering rule explicitly permits otherwise. Immediately after the merge lands, remove the prompt worktree and delete its temporary branch. Cleanup is mandatory; a prompt is not done while either exists. Update the matrix and emit events. Commit and PR metadata carry the iteration and prompt IDs, the matrix slice, test evidence, and the CR verdict.
 10. **Refresh indexes at wave boundaries**, not on every file write.
 
-**Exit:** G5 for each prompt — acceptance met, tests green, CR passed, anchors/docblocks valid, merged to the integration branch, matrix updated. The iteration can proceed to logic review only when all prompts are done or explicitly waived.
+**Exit:** G5 for each prompt — acceptance met, tests green, CR passed, anchors/docblocks valid, merged to the chosen integration target, prompt worktree/branch deleted, matrix updated. The iteration can proceed to logic review only when all prompts are done or explicitly waived.
 
 ### Phase 6 — Logic review
 
@@ -928,7 +932,7 @@ plan/                  # the prompt folder for this spec
 
 **Lead:** PM, with any persona configured for `phases.logic_review`.
 
-**Inputs:** PRD, TRD, Gherkin, test evidence, the integration branch diff, manifest history, the active steering rules and examples, and the prompt outcomes. The PM does not replace the technical reviewer; steering verification may cite specialist evidence, but the PM owns the final coverage statement.
+**Inputs:** PRD, TRD, Gherkin, test evidence, the chosen integration target diff, manifest history, the active steering rules and examples, and the prompt outcomes. The PM does not replace the technical reviewer; steering verification may cite specialist evidence, but the PM owns the final coverage statement.
 
 **Checks:**
 
@@ -938,12 +942,14 @@ plan/                  # the prompt folder for this spec
 - error states, copy, accessibility, and edge cases match the intent;
 - prior regressions are still guarded;
 - every active steering rule has a verdict and current evidence: `satisfied`, `not applicable`, `finding`, or `waived`;
-- style gates ran on the integration branch and no new suppression hides a violation;
+- style gates ran on the chosen integration target and no new suppression hides a violation;
 - repository flow and architecture boundaries match the declared rules;
 - the implementation is explainable to a non-engineer.
 
 **Output:** `reviews/logic-review.md`, with findings by severity and a verdict, plus `reviews/steering-review.md` mapping each active rule to evidence. A blocking rule with no verdict or current evidence stops G6. Logic review must not become a second technical review; technical findings go back to CR or assessment with the right persona.
 
+The “explainable to a non-engineer” check verifies that the PM can state the behaviour in business terms. The full human tutorial — `handover/HANDOVER.md` and `handover/tour.md` — is generated and walked in Phase 8, after closure.
+
 - **Gaps or incoherences** → generate follow-up prompts in Phase 4, increment the spec version, and loop.
 - **Minor fixes** → small prompts, same loop.
 - **Loops are capped** at `reviews.logic.max_loops` (default 2): findings that survive the cap become either a **follow-up iteration** (linked `followUpTo`, planned immediately) or a **waived risk** with an ADR. G6 records which path was taken; the loop never runs unbounded.
@@ -962,6 +968,7 @@ plan/                  # the prompt folder for this spec
 - the full test suite is green in a clean environment;
 - anchors and docblocks resolve; `lint --check` and `index --check` pass;
 - the manifest matches the artifacts;
+- no prompt worktree or `orchid/<iteration>/<prompt-id>` branch remains;
 - release notes and rollback notes exist.
 
 **Actions:**
@@ -971,9 +978,11 @@ plan/                  # the prompt folder for this spec
 - freeze the archived prompts and all artifacts by hash;
 - rebuild the root `manifest.jsonld` and all indexes;
 - write `release-notes.md`: changes, breaking changes, migrations, rollback, version bump;
-- merge the integration branch into the default branch per `execution.release_strategy` (squash merge, release PR, or manual);
+- merge the feature/integration branch into the chosen base branch per `execution.release_strategy` (squash merge, release PR, or manual); when no feature branch was used, the current branch is already the base;
+- delete the feature/integration branch after a successful merge unless repository policy explicitly requires retention and records it;
 - tag or prepare the release according to project convention;
-- mark the iteration `closed`; it becomes read-only.
+- mark the iteration `closed`; it becomes read-only;
+- ask whether the human wants to start the technical handover, and wait for the answer before Phase 8.
 
 **Rule:** archive, don't destroy. A closed iteration is immutable. Reopening it creates a new iteration linked with `followUpTo` and a new spec version. An iteration that will not ship is ended with `/orchid-sdd abandon` instead: same archival, no release, and the manifest records `abandoned` plus the reason.
 
@@ -1868,6 +1877,8 @@ This is the difference between "we hope they don't collide" and "the plan proves
 
 The knowledge protocol applies in every mode: agents never write `.knowledge`, and the context pack stays authoritative regardless of where the checkout lives.
 
+**Branch lifecycle.** Prompt worktrees and temporary branches are disposable. Create one per prompt (`orchid/<iteration>/<prompt-id>`), merge it, then remove the worktree and delete the branch immediately after CR passes. A leftover prompt branch is a build failure, not cleanup debt. The iteration has at most one long-lived feature/integration branch, and only when the user asked for one; otherwise prompt branches merge into the current branch of each affected repository. At closure, verify no prompt branch or worktree remains, merge the feature/integration branch to its chosen base, and delete it unless repository policy explicitly requires retention.
+
 ```mermaid
 flowchart TB
   W["wave N ready"] --> CP["orchestrator: context pack + knowledge snapshot into worktree"]
@@ -1876,7 +1887,7 @@ flowchart TB
   TV -->|fail| IM
   TV -->|pass| RV["reviewer agent: adversarial CR, fresh context"]
   RV -->|findings| IM
-  RV -->|pass| MG["CLI: merge to integration branch"]
+  RV -->|pass| MG["CLI: merge to feature/integration or current branch"]
   MG --> UP["orchestrator: drain bus, update matrix, emit events"]
   UP --> W
 ```
@@ -2815,7 +2826,7 @@ One-line pointers to every machine-checkable rule, for implementers who should n
 | Implementer never reviews its own work | §11.5 |
 | CR blocking severities gate; escalation after `max_fix_loops` | §11.5 |
 | Logic review capped at `max_loops`; follow-up or waived risk | §11.6 |
-| Merge to the integration branch only; default branch at G7, unless an XP-mainline steering rule permits direct mainline | §6 Phases 5, 7, §9.4 |
+| Merge to the chosen integration target only; default branch at G7, unless an XP-mainline steering rule permits direct mainline | §6 Phases 5, 7, §9.4 |
 | External sources are untrusted snapshots with provenance | §10 |
 | `doctor --ci` is offline; `--online` for network probes | §10.2 |
 | Audit is permanent; deletion is a human-approved event | §7.9 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchid-sdd",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "A memory-backed, specification-driven development (SDD) skill for coding agents.",
   "type": "module",
   "bin": {
@@ -25,6 +25,7 @@
   },
   "scripts": {
     "test": "node --test tests/setup.test.mjs tests/memory.test.mjs tests/lifecycle.test.mjs tests/workspace.test.mjs tests/migration.test.mjs tests/plugin.test.mjs tests/personas.test.mjs tests/skill-install.test.mjs tests/profiles.test.mjs tests/steering.test.mjs tests/models.test.mjs tests/prompt-state.test.mjs",
+    "prepublishOnly": "npm test",
     "plugin:check": "node --test tests/plugin.test.mjs",
     "personas:check": "node --test tests/personas.test.mjs",
     "skill:check": "node --test tests/skill-install.test.mjs",
@@ -55,6 +56,7 @@
     "@commitlint/config-conventional": "^21.2.4",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^11.0.1",
     "@semantic-release/github": "^12.0.10",
     "@semantic-release/npm": "^13.2.0",