orchid-sdd 0.2.0 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "orchid-sdd",
   "displayName": "orchid-sdd",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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/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
 ```
 
@@ -1369,7 +1370,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

@@ -121,6 +121,15 @@ A gate passes only with evidence. Never pass a gate on a promise.
 
 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
@@ -241,11 +250,15 @@ 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
 
@@ -255,10 +268,12 @@ Artifacts: `reviews/logic-review.md`, `reviews/steering-review.md`.
   `execution.release_strategy`; tag/freeze the iteration.
 - 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`.

package/cli/phases.mjs

@@ -96,8 +96,8 @@ function nextAction(phase) {
     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/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

@@ -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
 
@@ -944,6 +946,8 @@ plan/                  # the prompt folder for this spec
 
 **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.
@@ -973,7 +977,8 @@ plan/                  # the prompt folder for this spec
 - 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);
 - 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchid-sdd",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",