session-orchestrator 3.20.0 → 3.22.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
-    "version": "3.20.0"
+    "version": "3.22.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "session-orchestrator",
-  "version": "3.20.0",
+  "version": "3.22.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "3.20.0+codex.20260813195914",
+  "version": "3.22.0+codex.20260822193811",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "keywords": [
     "session",

package/.cursor/rules/000-session-orchestrator.mdc

@@ -33,10 +33,11 @@ You have Session Orchestrator capabilities. This plugin provides structured sess
 **No AskUserQuestion tool**: Present choices as numbered Markdown lists:
 ```
 Choose one:
-1. Option A — description
-2. Option B — description
+1. Option A (Recommended) — what it does, and why it is the safe default here.
+2. Option B — when B applies instead, and what it costs.
 Reply with the number of your choice.
 ```
+Two rules the example above follows. `(Recommended)` goes on option 1, in the label — an operator skims labels, so a recommendation hidden in the description is a recommendation he never sees. And every option names a reason, a cost, or a consequence: a recommendation without one is a claim he can only believe or ignore.
 
 **No TaskCreate/Update**: Use plain-text checklists to track progress:
 ```

package/.cursor/rules/030-wave-execution.mdc

@@ -73,17 +73,19 @@ Role-specific scope rules:
 - **Quality Phase 1 (Simplification)**: production files changed this session only (no test files)
 - **Quality Phase 2 (Tests)**: test file patterns only (`**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`)
 
-**Test-sibling expansion (#970):** a scope entry naming a production file but not its test sibling makes the task's own regression test unwritable — the guard then enforces exactly the inconsistency the quality gate exists to catch. Before writing `allowedPaths`, expand the union through the shared helper — do not hand-derive the paths:
+**`allowedPaths` is COMPUTED, never hand-transcribed (#1020).** Hand-transcribing the union produced 5 scope divergences in one session. Three steps, in this order:
 
-```js
-import { expandTestSiblings } from '$CURSOR_RULES_DIR/../scripts/lib/scope-gate.mjs';
-// Pass this wave's role verbatim — the helper GATES on it.
-const allowedPaths = expandTestSiblings(unionScopes, { role });
-```
+1. Write each task's file scope verbatim as a JSON array of strings to `.cursor/filescopes/wave-<N>/<task-id>.json` — that path IS `$TASK_FILESCOPE_JSON`, reused verbatim by the subset assertion below; never a `$TMPDIR` temp file, which no later step can address. Expect a `bash-write-verify … OUTSIDE the wave's allowedPaths` notice here: `.cursor/filescopes/` is control state like `.cursor/wave-scope.json`, and this step runs before the union exists. Your OWN planned direct edits go into `coordinator.json` in the same directory and take part in both steps below (2 of those 5 divergences were coordinator-direct edits, for which no task scope file exists by construction).
+2. Build the sidecar — an ARRAY of `{id, files}` records, never an object map, so a duplicated id stays visible — and assert disjointness **before** the union, or the union launders a double assignment into the artefact meant to prevent it: `node "$CURSOR_RULES_DIR/../scripts/validate-wave-scope.mjs" --assert-disjoint "$WAVE_SCOPES_SIDECAR" < .cursor/wave-scope.json`. Exit 1 = two tasks were handed the same file; fix the plan, never widen the union.
+3. `--union <sidecar>` is a QUERY MODE that still needs a schema-valid manifest on stdin: write the skeleton with `"allowedPaths": []`, run `node "$CURSOR_RULES_DIR/../scripts/validate-wave-scope.mjs" --union "$WAVE_SCOPES_SIDECAR" < .cursor/wave-scope.json`, and insert the printed array as `allowedPaths`. It prints that array **instead of** the manifest echo — one JSON document per run. It already applies test-sibling expansion, so do not run the helper by hand as well.
+
+After the final wave, delete `.cursor/wave-scope.json` **and** `.cursor/filescopes/`.
+
+**Test-sibling expansion (#970):** a scope entry naming a production file but not its test sibling makes the task's own regression test unwritable — the guard then enforces exactly the inconsistency the quality gate exists to catch. Step 3 above expands it for you via `expandTestSiblings(unionFileScopes(scopes), { role })`; do not hand-derive the paths.
 
-It emits a **glob** from the production basename (`foo.mjs` → `tests/**/foo*.test.mjs`), skips absolute entries, and is a strict no-op on Discovery's `[]`. **Which roles it fires for is decided inside the helper** — `TEST_SIBLING_EXPANSION_ROLES` in `scripts/lib/scope-gate.mjs` (currently Impl-Core / Impl-Polish; Quality Phase 1 is off, Phase 2 inert). Pass the role; do not pre-filter by role here. An absent or unrecognised role does **not** expand (fail-closed). Expand before the overlap check and before the file is written, in one pass. Full rule, the measured hit-rate and its ~15% residual, and the per-repo configurability: `skills/wave-executor/wave-loop.md` § Scope Manifest #3.
+It emits a **glob** from the production basename (`foo.mjs` → `tests/**/foo*.test.mjs`), skips absolute entries, and is a strict no-op on Discovery's `[]`. **Which roles it fires for is decided inside the helper** — `TEST_SIBLING_EXPANSION_ROLES` in `scripts/lib/scope-gate.mjs` (currently Impl-Core / Impl-Polish; Quality Phase 1 is off, Phase 2 inert). Pass the role; do not pre-filter by role here. An absent or unrecognised role does **not** expand (fail-closed). The disjointness check (step 2) runs on the declared scopes, before the union expands anything; expansion happens before the file is written, in one pass. Full rule, the measured hit-rate and its ~15% residual, and the per-repo configurability: `skills/wave-executor/wave-loop.md` § Scope Manifest #3.
 
-Validate with: `node "$CURSOR_RULES_DIR/../scripts/validate-wave-scope.mjs" < .cursor/wave-scope.json` — fix JSON if it exits 1. Before each task batch, also assert the task's file scope against the manifest, carrying the mechanical half of the rule above (gated on the manifest's `role`, so it self-skips where expansion does not fire):
+Validate with: `node "$CURSOR_RULES_DIR/../scripts/validate-wave-scope.mjs" < .cursor/wave-scope.json` — fix JSON if it exits 1. Before each task batch, also assert the task's file scope — `$TASK_FILESCOPE_JSON`, i.e. the step-1 file itself — against the manifest, carrying the mechanical half of the rule above (gated on the manifest's `role`, so it self-skips where expansion does not fire). This assertion is unchanged by #1020 and keeps running: it checks scope ⊆ union, a different property than disjointness — a file claimed twice is a subset twice over, so a double assignment is structurally invisible to it.
 
 ```bash
 node "$CURSOR_RULES_DIR/../scripts/validate-wave-scope.mjs" \

package/.cursor/rules/040-discovery.mdc

@@ -186,9 +186,9 @@ Options:
 1. [title] — [file_path]:[line] ([severity])
 
 Options:
-1. Accept all (Recommended) — create issues for all
-2. Review individually
-3. Dismiss all
+1. Accept all (Recommended) — one issue per finding. Fastest, and you can still close any of them later.
+2. Review individually — decide finding by finding. Costs about a minute per item.
+3. Dismiss all — no issues created, and the findings are gone when this session ends.
 ```
 
 ### Step 4: Batch Confirmation
@@ -196,9 +196,9 @@ Options:
 ```
 Ready to create [N] issues? ([X] critical, [Y] high, [Z] medium, [W] low)
 
-1. Create all [N] issues (Recommended)
-2. Review list first
-3. Cancel
+1. Create all [N] issues (Recommended) — the list is already filtered, so nothing here is noise. You can close any of them later.
+2. Review list first — read the titles before anything is written. Costs one extra step.
+3. Cancel — nothing is written, and this run's findings are not kept.
 ```
 
 ## Phase 5: Issue Creation

package/.cursor/rules/050-plan.mdc

@@ -29,9 +29,9 @@ If no mode specified, ask via numbered list:
 ```
 Which planning mode?
 
-1. new (Recommended) — Project kickoff (full PRD, repo setup, issue creation)
-2. feature — Feature PRD (compact scope, acceptance criteria, issues)
-3. retro — Retrospective (metrics analysis, reflection, improvement actions)
+1. new (Recommended) — Project kickoff: full PRD, repo setup, issue creation. Fits a repo that has no PRD yet.
+2. feature — One feature: compact scope, acceptance criteria, issues. Cheaper, but assumes the project context already exists.
+3. retro — Retrospective on finished work: metrics, reflection, improvement actions. Defines no new scope.
 ```
 
 ## Phase 2: Q&A Engine (Shared Core)
@@ -154,9 +154,9 @@ If any criterion fails, revise and re-review. Maximum **3 iterations**. After 3
 The PRD reviewer flagged these remaining issues:
 [list]
 
-1. Accept as-is (Recommended) — issues are minor, proceed
-2. Manual edit — I'll edit the PRD myself before continuing
-3. Re-run review — try one more revision round
+1. Accept as-is (Recommended) — the flagged issues are minor, so the PRD is usable now. You can still edit it later.
+2. Manual edit — you edit the PRD yourself before continuing. Costs a round-trip.
+3. Re-run review — one more revision round. Costs another review pass and may surface nothing new.
 ```
 
 Then present the saved PRD path and ask for final approval:
@@ -164,8 +164,8 @@ Then present the saved PRD path and ask for final approval:
 ```
 PRD saved to [path]. Ready for your review.
 
-1. Approve PRD (Recommended) — proceed to issue creation
-2. Request changes — describe what to change
+1. Approve PRD (Recommended) — proceed to issue creation. You can still edit the PRD afterwards; the issues link to it rather than copy it.
+2. Request changes — describe what to change. Costs one more revision round.
 ```
 
 ## Phase 5: Issue Creation