@chorus-aidlc/chorus-pi 0.17.3 → 0.18.1

package/agents/chorus-code-reviewer.md

@@ -89,6 +89,7 @@ These are the dimensions that per-task review structurally cannot catch. Cover e
 4. **Regression risk / impact on untouched areas / performance** — Does the change break or degrade code no single task "owned"? N+1s, hot-path cost, shared-state contention introduced by the aggregate.
 5. **Feature-level test coverage adequacy** — Across the whole feature, are the integration seams and end-to-end paths tested, or only per-task units? Gaps between tasks.
 6. **Code soundness, simplicity, correctness** — Is the aggregate change correct, reasonably simple, and free of obvious defects when read as one body of work?
+7. **Intent alignment (whole-feature)** — Also read the Idea's resolved elaboration (`chorus_get_elaboration`); using ONLY human-authored intent (Idea body + human-answered elaboration + human-authored comments; agent-authored entries are audit context, not intent) as the baseline, judge whether the aggregate change still serves the original intent. Flag scope creep, dropped requirements, or intent missed despite passing AC as a **BLOCKER**, unless a cited human entry / human override authorizes it.
 
 **Step 4: Run feature-level build/test**
 

package/agents/chorus-proposal-reviewer.md

@@ -5,7 +5,7 @@ tools: read, grep, find, ls, bash, mcp, mcpScript
 acceptance: { level: "none", reason: "read-only chorus reviewer; verdict is posted via chorus_add_comment to Chorus, not returned to parent; suppress acceptance-report injection" }
 ---
 
-CRITICAL: READ-ONLY proposal review. You CANNOT edit, write, create files, or run Bash commands beyond read-only inspection.
+CRITICAL: READ-ONLY proposal review. You CANNOT edit, write, or create files. Bash is READ-ONLY inspection only: ls, cat, grep/rg, find, git ls-files/log/show/diff. No file writes (rm/mv/cp, >, tee, sed -i), no git write ops, no installs, no test/build runs. Use it to confirm a file or directory exists before flagging it as missing.
 USE THE chorus_* MCP TOOLS for all Chorus data access — do NOT use curl or raw HTTP. The mcp gateway tool is available (the tool name prefix may be chorus_chorus_* or chorus_* depending on the session's MCP exposure mode; probe with a checkin if unsure).
 - chorus_get_proposal({ proposalUuid, section: "full" }) — fetch the full proposal (docs + tasks)
 - chorus_get_comments({ targetType: "proposal", targetUuid }) — prior review comments (check for Round 2+)
@@ -28,7 +28,7 @@ You have two failure patterns. **Rubber-stamping**: skimming the proposal and wr
 === CRITICAL: DO NOT MODIFY THE PROJECT ===
 You are STRICTLY PROHIBITED from:
 - Creating, modifying, or deleting any files
-- Running any shell commands beyond read-only inspection (git diff/log/show only)
+- Any shell command beyond read-only inspection (the read-only Bash rule in the CRITICAL line above is the full list)
 - Installing dependencies or packages
 
 === WHAT YOU RECEIVE ===
@@ -73,6 +73,7 @@ For each task draft, check:
 - Do tasks cover ALL requirements from the documents?
 - Are there scope additions not in the original idea?
 - Are there contradictions between documents and tasks?
+- **Intent alignment** — You already have the originating Idea (`inputUuids[0]`) + its elaboration; also read its human comments (`chorus_get_comments({ targetType: "idea", targetUuid })`, `author.type == "user"`). Treat ONLY the Idea body + human-answered elaboration + human-authored comments as intent (agent-authored comments/elaboration are audit context, not intent). Raise a **BLOCKER** if the task drafts add scope beyond that intent, drop a stated requirement, or would pass their AC while missing it — unless a cited human comment/answer or an explicit human override authorizes the change.
 
 === FINDING CLASSIFICATION ===
 

package/agents/chorus-task-reviewer.md

@@ -93,6 +93,10 @@ Pick 2-3 probes that fit the specific task: boundary values, missing fields, err
 
 **Hallucination check**: Flag anything that looks like it could be LLM-fabricated as NOTE — API signatures, CLI flags, config keys, model IDs, endpoint URLs, package names, or any external detail the developer likely wrote from memory rather than referencing docs.
 
+**Step 7: Intent alignment**
+
+Resolve the originating Idea (this task's proposal → `inputUuids[0]`) and read its body + human-answered elaboration + human-authored comments (`answeredBy.type` / `author.type == "user"`; agent-authored entries are audit context, not intent). Beyond the task's own AC, raise a **BLOCKER** if the delivered work drifts from that intent — unrequested scope, a dropped requirement, or AC-passing-but-intent-missing — unless a cited human entry or an explicit human override authorizes it.
+
 === FINDING CLASSIFICATION ===
 
 Every finding MUST be classified as one of:

package/bin/chorus-mcp-call.sh

@@ -143,7 +143,7 @@ ACCEPT="Accept: application/json, text/event-stream"
 CT="Content-Type: application/json"
 
 INIT=$(cat <<JSON
-{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-codex-hook","version":"0.17.3"}}}
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-codex-hook","version":"0.18.1"}}}
 JSON
 )
 

package/extensions/chorus.ts

@@ -46,7 +46,7 @@ import {
   sessionWorkflow,
   hasSessionMarker,
   extractRunIdFromToolResultEvent,
-  detectOpenSpec,
+  resolveSpecMode,
   buildSessionBanner,
   parseMaxCodeReviewRounds,
   resolveChorusBin,
@@ -77,7 +77,18 @@ const _mcp = _envUrl && _envKey
     })();
 const CHORUS_URL = _envUrl || _mcp.url;
 const CHORUS_API_KEY = _envKey || _mcp.apiKey;
-const OPENSPEC_OPTOUT = process.env.CHORUS_OPENSPEC_MODE === "off";
+
+// A neutral SpecModeResult for the not-configured / connection-failed banners,
+// where buildSessionBanner returns before reading the spec fields.
+const NO_SPEC = {
+  specMode: "off" as const,
+  specReason: "",
+  specFail: "",
+  openspecUsable: false,
+  openspecUsableReason: "",
+  openspecHint: "",
+  chorusOpenspecActive: false,
+};
 
 // Reviewer toggle envs (mirror Claude Code plugin userConfig; Pi has no plugin
 // settings UI, so env vars drive them). Defaults: all enabled.
@@ -265,11 +276,14 @@ async function closeCallSessions(
 // ─── Extension ────────────────────────────────────────────────────────────
 export default function (pi: ExtensionAPI) {
   // SessionStart → checkin + build context (replaces Claude's on-session-start.sh)
-  // Emits a user-visible one-line banner (ctx.ui.notify) mirroring the Claude
-  // plugin's SessionStart `systemMessage` / the Codex `$chorus` toast (#442):
-  //   connected + active   -> "Chorus connected at <url> (OpenSpec Enabled)"
-  //   connected + opt-out   -> "Chorus connected at <url> (OpenSpec off)"
-  //   connected + unset     -> "Chorus connected at <url> (OpenSpec off — run /skill:chorus enable openspec to set it up)"
+  // Resolves the spec mode once (resolveSpecMode, the TS mirror of the bash
+  // resolver) and injects a `## Spec Mode` block, plus a user-visible one-line
+  // banner (ctx.ui.notify) mirroring the Claude plugin `systemMessage` / Codex
+  // `$chorus` toast:
+  //   connected + openspec -> "Chorus connected at <url> (spec: OpenSpec)"
+  //   connected + lite      -> "Chorus connected at <url> (spec: spec-lite)"
+  //   connected + off       -> "Chorus connected at <url> (spec: off — free-form)"
+  //   connected + openspec-requested-but-unusable -> warning "(spec: OpenSpec requested but unusable — …)"
   //   not configured        -> warning (env vars missing)
   //   connection failed     -> error (checkin couldn't reach Chorus)
   pi.on("session_start", async (event, ctx) => {
@@ -279,7 +293,7 @@ export default function (pi: ExtensionAPI) {
         configured: false,
         connected: false,
         chorusUrl: CHORUS_URL,
-        openspec: { active: false, reason: "not configured", optout: false, hint: "" },
+        spec: NO_SPEC,
       });
       ctx.ui.notify(banner.message, banner.level);
       return;
@@ -288,13 +302,30 @@ export default function (pi: ExtensionAPI) {
     try {
       const checkin = await mcpCall("chorus_checkin");
       connected = true;
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      const os = detectOpenSpec(
-        ctx.cwd,
-        OPENSPEC_OPTOUT,
+      // Resolve the spec mode once per session (single source of truth — the TS
+      // reimplementation of the bash resolver). Rule: explicit CHORUS_SPEC_MODE
+      // wins; unset → OpenSpec when usable, else spec-lite.
+      const spec = resolveSpecMode(
+        {
+          specMode: process.env.CHORUS_SPEC_MODE,
+          openspecMode: process.env.CHORUS_OPENSPEC_MODE,
+          enableOpenSpec: process.env.CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC,
+          projectRoot: ctx.cwd,
+        },
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
         require("node:fs"),
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
         require("node:child_process").execSync,
       );
+      // Route note per resolved mode (mirrors the bash/Codex `## Spec Mode` block).
+      const specRoute =
+        spec.specMode === "lite"
+          ? "Routing: lite → follow the `spec-lite` skill (/skill:spec-lite). A capability's durable spec is `.chorus/specs/<slug>/spec.md` (edited in place, **never synced**, git history is its record); each change is a dated folder `.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` of Chorus-typed docs (`prd.md` required; `tech_design.md` / `adr.md` / `guide.md` / `spec.md` optional) that **are** mirrored 1:1 into persistent Chorus Documents via `chorus mcp call … --arg-file content=<file>` (fallback `chorus-mcp-call.sh`). Put a `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` locator line in the proposal description. Do NOT scaffold `openspec/changes/` or add an `OpenSpec change slug:` line."
+          : spec.specMode === "off"
+            ? "Routing: off → free-form, no spec artifact. Do NOT create `.chorus/specs/` or `openspec/changes/` files; author document drafts inline via direct MCP."
+            : spec.specFail
+              ? `Routing: openspec → **cannot be honored** — ${spec.specFail}. The proposal / yolo skill MUST halt after resolving the mode; do NOT silently fall back to lite/free-form. Surface this to the user.${spec.openspecHint ? ` Install hint: ${spec.openspecHint}.` : ""}`
+              : `CHORUS_OPENSPEC_ACTIVE=1 (${spec.openspecUsableReason})\n\nRouting: openspec → load the openspec-aware skill (/skill:openspec-aware) and follow §3 (OpenSpec authoring) — do NOT re-run the §1 detection block, the answer is already known.\n\nCritical rule (openspec-aware §2 Rule 1): document mirror calls (\`chorus_pm_add_document_draft\` / \`chorus_pm_update_document_draft\` / \`chorus_pm_update_document\`) MUST fill \`content\` from the local file — prefer \`chorus mcp call <tool> '<json>' --arg-file content=<file>\`, falling back to \`chorus-mcp-call.sh\` when \`chorus\` is not on PATH. Do NOT invoke these MCP tools directly with hand-typed \`content\` in OpenSpec mode.`;
       checkinContext = [
         "# Chorus Plugin — Active",
         "",
@@ -306,16 +337,11 @@ export default function (pi: ExtensionAPI) {
         JSON.stringify(checkin, null, 2),
         "```",
         "",
-        "## OpenSpec Mode",
+        "## Spec Mode",
+        "",
+        `CHORUS_SPEC_MODE=${spec.specMode} (${spec.specReason})`,
         "",
-        `CHORUS_OPENSPEC_ACTIVE=${os.active} (${os.reason})`,
-        os.active
-          ? "OpenSpec mode is **active**. proposal/develop/yolo skills follow the openspec-aware path."
-          : os.optout
-            ? "OpenSpec was **explicitly turned off** — do not nag."
-            : os.hint
-              ? `Note: this repo has an \`openspec/\` directory but the \`openspec\` CLI is not installed — ${os.hint}. Run \`/skill:chorus enable openspec\` to set it up.`
-              : "OpenSpec is not set up in this repo. Spec-driven authoring is optional — free-form works fine. If the user wants spec-driven mode, run `/skill:chorus enable openspec` (§6 walks the install + re-launch).",
+        specRoute,
         "",
         "## Quick Reference",
         "- **Sessions**: auto-managed. When you dispatch a WORKER via the `subagent` tool (single/parallel/chain), the extension creates a Chorus session per worker task and injects its UUID + the session workflow into that task automatically; the session is closed when the `subagent` tool call returns (children are ephemeral). Do NOT call chorus_create_session/close_session yourself.",
@@ -325,13 +351,13 @@ export default function (pi: ExtensionAPI) {
         (CHORUS_BIN
           ? "- **OpenSpec wrapper**: `bin/chorus-mcp-call.sh` is at `" + CHORUS_BIN + "` — the CLI-absent fallback for OpenSpec-mode document mirrors. Prefer `chorus mcp call <tool> '<json>' --arg-file content=<file>` (chorus >= 0.17.0); use this wrapper only when `chorus` is not on PATH (a bare `chorus-mcp-call.sh` will NOT be on PATH for local-path installs). See /skill:openspec-aware §2."
           : "- **OpenSpec wrapper**: `bin/chorus-mcp-call.sh` was not resolved relative to the extension — it is the CLI-absent fallback for OpenSpec-mode document mirrors (prefer `chorus mcp call <tool> '<json>' --arg-file content=<file>`). If you need it, locate it with `find ~/.pi/agent/npm -path '*chorus-pi/bin/chorus-mcp-call.sh'`. See /skill:openspec-aware §2."),
-        "- **Skills**: /skill:chorus, /skill:idea, /skill:proposal, /skill:develop, /skill:review, /skill:quick-dev, /skill:yolo",
+        "- **Skills**: /skill:chorus, /skill:idea, /skill:proposal, /skill:develop, /skill:review, /skill:quick-dev, /skill:yolo, /skill:spec-lite, /skill:openspec-aware",
       ].join("\n");
       const banner = buildSessionBanner({
         configured: true,
         connected: true,
         chorusUrl: CHORUS_URL,
-        openspec: os,
+        spec,
       });
       ctx.ui.notify(banner.message, banner.level);
     } catch (e) {
@@ -340,7 +366,7 @@ export default function (pi: ExtensionAPI) {
         configured: true,
         connected: false,
         chorusUrl: CHORUS_URL,
-        openspec: { active: false, reason: "connection failed", optout: false, hint: "" },
+        spec: NO_SPEC,
       });
       ctx.ui.notify(banner.message, banner.level);
     }

package/lib/lib.ts

@@ -1,7 +1,7 @@
 /**
  * Pure helpers extracted from the chorus-pi extension for unit testing.
  *
- * These functions hold no mutable state and (except for detectOpenSpec, which
+ * These functions hold no mutable state and (except for resolveSpecMode, which
  * takes injectable fs/execSync) have no I/O — so they can be tested without a
  * running Pi session or a live Chorus instance. The extension imports them
  * from here; tests import the same functions.
@@ -11,7 +11,7 @@ import { dirname, join } from "node:path";
 
 /**
  * Minimal fs surface needed by the config readers below.
- * (detectOpenSpec already uses FsLike; keep this as the shared type.)
+ * (resolveSpecMode already uses FsLike; keep this as the shared type.)
  */
 export interface FsLike {
   existsSync(p: string): boolean;
@@ -226,68 +226,168 @@ export function extractRunIdFromToolResultEvent(event: {
 }
 
 /**
- * Resolved OpenSpec mode for a repo. `active` is the effective on/off; `reason`
- * is a human-readable explanation; `optout` marks an explicit opt-out (so the
- * banner does not nag); `hint` is an optional install hint when the directory
- * exists but the CLI is missing.
+ * The resolved spec mode surfaced to the agent. `openspec` = the OpenSpec
+ * (openspec-aware) path; `lite` = Chorus-native lightweight specs
+ * (`.chorus/specs/<slug>/`); `off` = free-form, no spec artifact.
  */
-export interface OpenSpecState {
-  active: boolean;
-  reason: string;
-  optout: boolean;
-  hint: string;
+export type SpecMode = "lite" | "openspec" | "off";
+
+/**
+ * Inputs to the spec-mode resolver (env values + repo root). Mirrors the
+ * canonical bash resolver `public/chorus-plugin/bin/resolve-spec-mode.sh`.
+ */
+export interface SpecModeInputs {
+  /** CHORUS_SPEC_MODE — explicit override: "lite" | "openspec" | "off" (else unset/""). */
+  specMode?: string;
+  /** CHORUS_OPENSPEC_MODE — legacy opt-out: "off" disables OpenSpec. */
+  openspecMode?: string;
+  /** CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC — plugin toggle: "false" disables OpenSpec (default "true"). */
+  enableOpenSpec?: string;
+  /** Repo root to probe for openspec/. */
+  projectRoot: string;
 }
 
 /**
- * Detect OpenSpec mode for a repo. Active only when all three hold:
- *   (1) not explicitly opted out (CHORUS_OPENSPEC_MODE != "off")
- *   (2) an openspec/ directory exists at the project root
- *   (3) the `openspec` CLI is on PATH
+ * Resolved spec mode for a repo — the TS mirror of the bash resolver's output
+ * vars. `specFail` non-empty ⇒ a stage skill MUST halt (an explicit
+ * `CHORUS_SPEC_MODE=openspec` that cannot be honored); `chorusOpenspecActive`
+ * is true only when the resolved mode is a USABLE openspec.
+ */
+export interface SpecModeResult {
+  specMode: SpecMode;
+  specReason: string;
+  specFail: string;
+  openspecUsable: boolean;
+  openspecUsableReason: string;
+  openspecHint: string;
+  chorusOpenspecActive: boolean;
+}
+
+/**
+ * Resolve the active Chorus spec mode for a repo — the TypeScript reimplementation
+ * of `public/chorus-plugin/bin/resolve-spec-mode.sh` (which the bash ports copy
+ * byte-identically; the TS ports reimplement + ship a same-contract test). Pure
+ * given injectable fs + execSync.
  *
- * fs and execSync are injected so tests can stub the filesystem and the CLI
- * presence check without touching the real environment.
+ * Rule (per owner): an explicit `CHORUS_SPEC_MODE` wins; when unset, OpenSpec stays
+ * the default whenever it is usable (openspec/ dir + CLI, not disabled), and lite
+ * is the fallback only when OpenSpec is absent or disabled. An explicit
+ * `=openspec` that isn't usable fails fast (`specFail`).
  */
-export function detectOpenSpec(
-  cwd: string,
-  optout: boolean,
+export function resolveSpecMode(
+  inputs: SpecModeInputs,
   fs: FsLike,
   execSync: ExecSync,
-): OpenSpecState {
-  if (optout) {
-    return { active: false, reason: "CHORUS_OPENSPEC_MODE=off (explicit opt-out)", optout: true, hint: "" };
+): SpecModeResult {
+  const projectRoot = inputs.projectRoot || "";
+
+  // --- Is OpenSpec usable? (needs openspec/ dir + CLI on PATH + not disabled) ---
+  // enableOpenSpec toggle is checked BEFORE the legacy CHORUS_OPENSPEC_MODE, so a
+  // plugin-level opt-out wins the reason string (matches the bash resolver order).
+  let openspecDisabled = false;
+  let disabledReason = "";
+  if ((inputs.enableOpenSpec ?? "true") !== "true") {
+    openspecDisabled = true;
+    disabledReason = "enableOpenSpec userConfig=false (plugin-level opt-out)";
+  } else if (inputs.openspecMode === "off") {
+    openspecDisabled = true;
+    disabledReason = "CHORUS_OPENSPEC_MODE=off (legacy opt-out)";
   }
-  const openspecDir = `${cwd}/openspec`;
-  if (!fs.existsSync(openspecDir)) {
-    return { active: false, reason: `no openspec/ directory at ${openspecDir}`, optout: false, hint: "" };
+
+  let openspecUsable = false;
+  let openspecUsableReason = "";
+  let openspecHint = "";
+  if (openspecDisabled) {
+    openspecUsableReason = disabledReason;
+  } else if (!fs.existsSync(`${projectRoot}/openspec`)) {
+    openspecUsableReason = `no openspec/ directory at ${projectRoot}/openspec`;
+    openspecHint = "npm i -g @fission-ai/openspec && openspec init";
+  } else if (!openspecCliPresent(execSync)) {
+    openspecUsableReason = "openspec/ directory present but `openspec` CLI not on PATH";
+    openspecHint = "npm i -g @fission-ai/openspec";
+  } else {
+    openspecUsable = true;
+    openspecUsableReason = "openspec/ directory + openspec CLI both present";
   }
-  let cliPresent = false;
+
+  // --- Resolve CHORUS_SPEC_MODE (unset and "" are treated the same, as in bash) ---
+  let specMode: SpecMode;
+  let specReason: string;
+  let specFail = "";
+  const raw = inputs.specMode ?? "";
+  switch (raw) {
+    case "lite":
+      specMode = "lite";
+      specReason = "explicit — Chorus-native lightweight specs in .chorus/specs/<slug>/";
+      break;
+    case "off":
+      specMode = "off";
+      specReason = "explicit — free-form, no spec artifact";
+      break;
+    case "openspec":
+      specMode = "openspec";
+      if (openspecUsable) {
+        specReason = `explicit; ${openspecUsableReason}`;
+      } else if (openspecDisabled) {
+        specReason = `explicit, but OpenSpec is disabled: ${openspecUsableReason}`;
+        specFail = `config conflict — CHORUS_SPEC_MODE=openspec vs OpenSpec disabled (${openspecUsableReason}); re-enable OpenSpec or set CHORUS_SPEC_MODE=lite`;
+      } else {
+        specReason = `explicit, but OpenSpec is not installed: ${openspecUsableReason}`;
+        specFail = `OpenSpec not usable (${openspecUsableReason})`;
+      }
+      break;
+    case "":
+      // Unset: OpenSpec is the default when usable; lite is the fallback otherwise.
+      if (openspecUsable) {
+        specMode = "openspec";
+        specReason = `default — ${openspecUsableReason}; set CHORUS_SPEC_MODE=lite for Chorus-native specs, =off to disable`;
+      } else {
+        specMode = "lite";
+        specReason = `default — OpenSpec not usable (${openspecUsableReason}); using Chorus-native lightweight specs in .chorus/specs/<slug>/`;
+      }
+      break;
+    default:
+      // Unrecognized value: treat like unset (OpenSpec-if-usable, else lite).
+      if (openspecUsable) {
+        specMode = "openspec";
+        specReason = `CHORUS_SPEC_MODE='${raw}' unrecognized; falling back to default (${openspecUsableReason})`;
+      } else {
+        specMode = "lite";
+        specReason = `CHORUS_SPEC_MODE='${raw}' unrecognized; OpenSpec not usable, defaulting to lite`;
+      }
+  }
+
+  const chorusOpenspecActive = specMode === "openspec" && specFail === "";
+  return {
+    specMode,
+    specReason,
+    specFail,
+    openspecUsable,
+    openspecUsableReason,
+    openspecHint,
+    chorusOpenspecActive,
+  };
+}
+
+function openspecCliPresent(execSync: ExecSync): boolean {
   try {
     execSync("command -v openspec", { stdio: "ignore" });
-    cliPresent = true;
+    return true;
   } catch {
-    cliPresent = false;
+    return false;
   }
-  if (!cliPresent) {
-    return {
-      active: false,
-      reason: "openspec/ directory present but `openspec` CLI not on PATH",
-      optout: false,
-      hint: "install with: npm i -g @fission-ai/openspec",
-    };
-  }
-  return { active: true, reason: "openspec/ directory + openspec CLI both present", optout: false, hint: "" };
 }
 
 /**
  * Build the user-visible one-line startup banner (the Pi equivalent of the
- * Claude plugin's SessionStart `systemMessage` / Codex `$chorus` toast).
- *
- * Mirrors the three OpenSpec states from upstream (#442):
- *   - active            -> "(OpenSpec Enabled)"
- *   - explicit opt-out  -> "(OpenSpec off)"            [neutral, no nag]
- *   - not set up        -> "(OpenSpec off — run /skill:chorus enable openspec to set it up)"
+ * Claude plugin's SessionStart `systemMessage` / Codex `$chorus` toast). The
+ * suffix reflects the resolved spec mode:
+ *   - openspec (usable) -> "(spec: OpenSpec)"
+ *   - lite              -> "(spec: spec-lite)"
+ *   - off               -> "(spec: off — free-form)"
+ *   - openspec requested but unusable (specFail) -> warning, "(spec: OpenSpec unusable — …)"
  *
- * Plus two non-OpenSpec states:
+ * Plus two non-connected states:
  *   - not configured    -> warning that CHORUS_URL / CHORUS_API_KEY are missing
  *   - connection failed -> error that the checkin couldn't reach Chorus
  *
@@ -302,7 +402,7 @@ export function buildSessionBanner(args: {
   configured: boolean;
   connected: boolean;
   chorusUrl: string;
-  openspec: OpenSpecState;
+  spec: SpecModeResult;
 }): SessionBanner {
   // Not configured at all — env vars missing. Warn once so the user knows
   // the plugin loaded but is inert (Claude's hook emits the same warning).
@@ -321,18 +421,23 @@ export function buildSessionBanner(args: {
     };
   }
 
-  // Connected. Append the OpenSpec status suffix.
+  // Connected. Append the resolved spec-mode suffix.
+  const spec = args.spec;
   let suffix: string;
-  if (args.openspec.active) {
-    suffix = "(OpenSpec Enabled)";
-  } else if (args.openspec.optout) {
-    suffix = "(OpenSpec off)";
+  let level: "info" | "warning" = "info";
+  if (spec.specFail) {
+    suffix = `(spec: OpenSpec requested but unusable — ${spec.openspecUsableReason}; spec authoring will halt)`;
+    level = "warning";
+  } else if (spec.specMode === "openspec") {
+    suffix = "(spec: OpenSpec)";
+  } else if (spec.specMode === "lite") {
+    suffix = "(spec: spec-lite)";
   } else {
-    suffix = "(OpenSpec off — run /skill:chorus enable openspec to set it up)";
+    suffix = "(spec: off — free-form)";
   }
   return {
     message: `Chorus connected at ${args.chorusUrl} ${suffix}`,
-    level: "info",
+    level,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-aidlc/chorus-pi",
-  "version": "0.17.3",
+  "version": "0.18.1",
   "description": "Chorus AI-DLC collaboration platform extension for the Pi coding agent. Provides skills for every stage of the AI-DLC lifecycle, read-only reviewer subagents, and session-aware extension hooks. The Chorus MCP server is auto-discovered from the repo's .mcp.json by pi-mcp-adapter — no installer required.",
   "author": {
     "name": "Chorus-AIDLC"

package/skills/brainstorm/SKILL.md

@@ -4,7 +4,7 @@ description: Optional divergent-then-convergent dialogue for fuzzy ideas. Invoke
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---

package/skills/chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus AI Agent collaboration platform — overview, common tools,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---
@@ -350,20 +350,22 @@ export CHORUS_MAX_CODE_REVIEW_ROUNDS=5   # 0 = unlimited
 
 When enabled, reviewers run as read-only sub-agents and post a VERDICT comment on the proposal/task/idea. Three possible outcomes: **PASS** (no issues), **PASS WITH NOTES** (minor non-blocking notes), or **FAIL** (BLOCKERs found). Results are advisory — they do not block approval, verification, or ship; the code-review gateway in particular is behavioral (it does not change the Idea's stored status). On a code-review FAIL, fix it via the `/skill:quick-dev` workflow: `chorus_create_tasks` with `proposalUuid` set to the current approved proposal so the fix tasks attach to it. Group related small BLOCKERs into one cohesive task by default; split only materially large or independently testable fixes. Each fix task must self-check its acceptance criteria and pass independent task review plus admin verification. Re-run the gateway only after every fix task is successfully `done`; if there is a failed or cancelled fix task, stop and escalate instead. Disabling reduces token usage but removes the independent quality gate.
 
-### 6. Enable OpenSpec Mode (Optional)
+### 6. Spec mode: OpenSpec (default when usable) vs spec-lite (fallback)
 
-Opt-in spec-driven path: `/skill:proposal`, `/skill:develop`, and `/skill:yolo` write `proposal.md` / `design.md` / spec deltas on disk and mirror them into Chorus drafts. Fully optional — free-form authoring works without it. Activates only when all three hold: `CHORUS_OPENSPEC_MODE` ≠ `off`, an `openspec/` directory exists at the project root, and the `openspec` CLI is on `PATH`. The extension detects this at `session_start` and reports it in the injected context.
+The extension's `session_start` handler resolves one **spec mode** per session (via the TS `resolveSpecMode`, the single source of truth) and injects a `## Spec Mode` section stating it — the stage skills **consume** that value, they don't re-derive it. Resolution: an explicit `CHORUS_SPEC_MODE` (`lite`/`openspec`/`off`) wins; when unset, **OpenSpec is the default whenever it is usable** (`CHORUS_OPENSPEC_MODE` ≠ `off`, an `openspec/` directory at the project root, and the `openspec` CLI on `PATH`). When OpenSpec is absent or disabled, the mode falls back to **spec-lite** — a Chorus-native, git-tracked model with a durable local `.chorus/specs/<slug>/spec.md` per capability (never synced) plus dated per-change folders `<slug>/<YYYY-MM-DD>-<change-slug>/` of Chorus-typed docs mirrored 1:1 into Chorus (see `/skill:spec-lite`). `CHORUS_SPEC_MODE=off` selects free-form (no spec artifact).
 
-**When the user wants it on** (e.g. they ran `/skill:chorus enable openspec` after the `(OpenSpec off — …)` banner), actually **enable it for them** — run whichever steps are missing, don't just describe them:
+OpenSpec spec-driven path: `/skill:proposal`, `/skill:develop`, and `/skill:yolo` write `proposal.md` / `design.md` / spec deltas on disk and mirror them into Chorus drafts.
+
+**When the user wants OpenSpec on** (e.g. they saw `(spec: spec-lite)` / `(spec: off …)` in the banner), actually **enable it for them** — run whichever steps are missing, don't just describe them:
 
 ```bash
 npm i -g @fission-ai/openspec       # 1. install the CLI if it's not on PATH (global, pure Node)
 openspec init                        # 2. scaffold openspec/ (interactive; pick your editor tooling)
 ```
 
-The OpenSpec signal is read **once at session start**, so it can't flip mid-session — after the steps succeed, tell the user to **restart the session**; the banner then reads `(OpenSpec Enabled)` and the stage skills fold in the `openspec-aware` skill automatically.
+The spec mode is resolved **once at session start**, so it can't flip mid-session — after the steps succeed, tell the user to **restart the session**; the `## Spec Mode` section then reads `CHORUS_SPEC_MODE=openspec (…)` and the stage skills fold in the `openspec-aware` skill automatically.
 
-To turn it off, set `CHORUS_OPENSPEC_MODE=off` — the banner then reads a neutral `(OpenSpec off)`.
+To turn OpenSpec off, set `CHORUS_OPENSPEC_MODE=off` — the mode then falls back to **spec-lite** (or set `CHORUS_SPEC_MODE=off` for free-form). The `## Spec Mode` section always states the resolved mode + reason.
 
 ---
 
@@ -426,7 +428,8 @@ This is the core overview skill. For stage-specific workflows, use:
 | **Development** | `/skill:develop` | Claim Tasks, report work, session & parallel sub-agent integration |
 | **Review** | `/skill:review` | Approve/reject Proposals, verify Tasks, project governance |
 | **Docs** | `/skill:docs` | Consult the live Chorus documentation site to answer product-usage questions — UI workflow, agent/plugin setup, API/MCP, deployment, operations |
-| **OpenSpec mode** | `openspec-aware` | Opt-in **shared sub-procedure** invoked by `/skill:proposal`, `/skill:develop`, and `/skill:yolo` whenever the user has the `openspec` CLI installed. Scaffolds `openspec/changes/<slug>/` on disk and mirrors files into Chorus document drafts. Skips silently in fallback mode. See `skills/openspec-aware/SKILL.md`. |
+| **OpenSpec mode** | `openspec-aware` | **Shared sub-procedure** invoked by `/skill:proposal`, `/skill:develop`, and `/skill:yolo` when the resolved spec mode is a usable OpenSpec (the default when `openspec/` + CLI present and not disabled). Scaffolds `openspec/changes/<slug>/` on disk and mirrors files into Chorus document drafts via `chorus mcp call --arg-file` (`chorus-mcp-call.sh` wrapper as fallback). See `skills/openspec-aware/SKILL.md`. |
+| **spec-lite mode** | `spec-lite` | **Shared sub-procedure** and the fallback when OpenSpec isn't usable (or `CHORUS_SPEC_MODE=lite`). Durable local `.chorus/specs/<slug>/spec.md` (never synced) + dated per-change folders of Chorus-typed docs mirrored 1:1 into Chorus via `--arg-file`. No CLI/validation. See `skills/spec-lite/SKILL.md`. |
 
 ### Getting Started
 

package/skills/chorus-cli/SKILL.md

@@ -4,7 +4,7 @@ description: How to install, configure, and use the `chorus` CLI — install it,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---

package/skills/develop/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, manage se
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---
@@ -140,7 +140,9 @@ Each task and proposal includes a `commentCount` field — use it to decide whic
 >
 > When the LAST task of an OpenSpec idea is verified, the extension injects an archive reminder (`openspec-aware` §3.9) — run `openspec archive <slug> --yes`, then mirror each emitted `openspec/specs/<capability>/spec.md` back via §3.8.
 >
-> In the no-OpenSpec fallback (no slug line, or no `openspec` CLI), edit the Document content directly via the existing MCP tool with no wrapper, no local file step.
+> **Document update flow (spec-lite mode):** if the proposal `description` contains a line `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/`, the project's PRD / tech_design / … Documents are **mirrors** of the files in that dated folder. To update such a Document, load the `spec-lite` skill (`/skill:spec-lite`) and follow its Mirror section: edit the local `<type>.md` file first, then mirror it via `chorus mcp call chorus_pm_update_document "{\"documentUuid\":\"<uuid>\"}" --arg-file content=<file>` (recorded `documentUuid` from the file's frontmatter), falling back to the `chorus-mcp-call.sh` wrapper when `chorus` is not on `PATH`, `chorus_check_response` halting on error. Same **⛔ do-not-hand-type-`content`** rule as OpenSpec. The durable `.chorus/specs/<slug>/spec.md` is edited in place too but is **never mirrored** (git history is its record). No archive flow — spec-lite has no CLI/validate/archive; on delivery just set `spec.md` `status: done`.
+>
+> In the no-OpenSpec, no-spec-lite fallback (free-form: no locator line), edit the Document content directly via the existing MCP tool with no wrapper, no local file step.
 
 ### Step 5: Start Working
 
@@ -229,13 +231,13 @@ After the reviewer completes, read its VERDICT:
 ```
 chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
 ```
-Find the most recent comment containing `VERDICT:` and act on it:
+Find THIS round's `VERDICT:` comment — the one posted after your dispatch, not an older round's — and act on it:
 
 - **VERDICT: PASS** — All AC verified, no issues. Proceed to admin verification.
 - **VERDICT: PASS WITH NOTES** — All AC verified, minor notes. Proceed to admin verification (notes are non-blocking).
 - **VERDICT: FAIL** — BLOCKERs found. Do NOT verify. Fix the BLOCKERs listed in the reviewer's comment, then resubmit.
 
-If no new `VERDICT:` comment appears after the reviewer returns, it exhausted its turn budget before posting. Respawn it ONCE with a concise-budget hint in the prompt: *"Stay within turn budget. Skip deep verification. Fetch task/proposal/comments, run only the core tests, and post your VERDICT comment within the first 12 turns."* If the second attempt still produces no VERDICT, review manually using the checklist and proceed.
+If no new `VERDICT:` comment appears after the reviewer returns, check what it *did* post. A comment reporting that the round limit was reached, or any other explicit refusal to review, is a deliberate escalation to a human: STOP — do not respawn, do not self-review, do not post a VERDICT of your own. If it posted nothing at all, respawn it ONCE, telling it to stay within its turn budget and reserve its last turns for the VERDICT, then apply this same check again to what the retry posts. An explicit refusal from the retry still means STOP; only a second true silence lets you review the task yourself as a read-only pass using the checklist and POST the VERDICT comment. **Absence is never a PASS.**
 
 > **Final code-review gateway (after the Idea's LAST task is verified):** when the task you just verified is the **last** task of its idea-rooted proposal, the feature is about to ship — the extension nudges you to spawn `chorus-code-reviewer` (gated by `CHORUS_ENABLE_CODE_REVIEWER`, default on). Spawn it yourself via the blocking `subagent` tool, passing the `ideaUuid` + round number; it reviews the Idea's **aggregate** code change across all its tasks (cross-task integration, architecture, security, regression, feature-level coverage) and posts one `VERDICT` comment on the **idea**. `PASS` / `PASS WITH NOTES` → ship; `FAIL` → fix via `/skill:quick-dev` (`chorus_create_tasks` with `proposalUuid` set to the current approved proposal so the fix tasks attach to it — do NOT reopen the verified tasks). Group related small BLOCKERs by default; split only materially large or independently testable fixes. Require AC self-check, independent task review, and admin verification for every fix task. Re-run aggregate review only after every fix is successfully `done`; a failed or cancelled fix stops the loop and escalates, bounded by `CHORUS_MAX_CODE_REVIEW_ROUNDS` (env, default 3; 0 = unlimited). Advisory/behavioral, like the other reviewers. Run it **before** any idea-completion report.
 

package/skills/docs/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus documentation router — consult the live Chorus docs site t
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---

package/skills/idea/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---

package/skills/openspec-aware/SKILL.md

@@ -1,75 +1,67 @@
 ---
 name: openspec-aware
-description: Opt-in OpenSpec-mode authoring for Chorus PM workflows in Pi. Detects the local `openspec` CLI, scaffolds `openspec/changes/<slug>/` on disk, and mirrors Markdown files into Chorus document drafts via `chorus mcp call --arg-file` (bash `chorus-mcp-call.sh` wrapper as fallback). Required reading for the proposal, develop, and yolo skills whenever the user has the `openspec` CLI installed.
+description: OpenSpec-mode authoring for Chorus PM workflows in Pi. The default whenever OpenSpec is usable; consumes the resolved `## Spec Mode` (never re-detects). Scaffolds `openspec/changes/<slug>/` on disk, and mirrors Markdown files into Chorus document drafts via `chorus mcp call --arg-file` (bash `chorus-mcp-call.sh` wrapper as fallback). Required reading for the proposal, develop, and yolo skills. When OpenSpec is not the resolved mode, this skill no-ops and the caller follows the resolved mode (spec-lite or free-form).
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---
 
 # OpenSpec-aware Authoring (Pi plugin)
 
-This skill is a **shared sub-procedure** invoked by the Chorus stage skills (proposal, develop, yolo) whenever the user wants spec-driven authoring through the [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec). It is opt-in:
+This skill is a **shared sub-procedure** invoked by the Chorus stage skills (proposal, develop, yolo) when the resolved spec mode is a **usable OpenSpec** — spec-driven authoring through the [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec):
 
-- Activates when **all three** signals hold (see §1): `CHORUS_OPENSPEC_MODE` is not `off`, an `openspec/` directory exists at the project root, and the `openspec` CLI is on `PATH`.
-- Otherwise the calling skill falls back to its existing free-form behavior.
+- Activates when the resolved spec mode is a **usable OpenSpec** (see §1): `CHORUS_SPEC_MODE=openspec` *or* unset, **and** `CHORUS_OPENSPEC_MODE` not `off`, an `openspec/` directory exists at the project root, and the `openspec` CLI is on `PATH`.
+- Otherwise the calling skill follows the resolved mode — **spec-lite** (the default when OpenSpec isn't usable) or free-form (`CHORUS_SPEC_MODE=off`).
 
-When you reach a point in proposal / develop / yolo where this skill is referenced, **read the value of `CHORUS_OPENSPEC_ACTIVE` from the session_start context** (see §1) and branch on it. Do not re-run the detection block — the session_start handler has already done it once for this session.
+> **See also — `spec-lite` (the lightweight fallback):** OpenSpec (this skill) stays the default whenever usable. When OpenSpec is absent or disabled — or `CHORUS_SPEC_MODE=lite` — the mode resolves to **spec-lite**: a durable local `.chorus/specs/<slug>/spec.md` (never synced) + per-change dated folders `<slug>/<YYYY-MM-DD>-<change-slug>/` of Chorus-typed docs mirrored 1:1 into Chorus via the same `--arg-file` transport. See `/skill:spec-lite`.
+
+When you reach a point in proposal / develop / yolo where this skill is referenced, **read the resolved mode from the `## Spec Mode` section** (see §1) and branch on it. Do not re-derive the detection — the `session_start` handler has already resolved it once for this session.
 
 ---
 
-## §1. Detection — already done at session_start
+## §1. Spec mode — already resolved at session_start
 
-The Chorus extension's `session_start` handler computes `CHORUS_OPENSPEC_ACTIVE` once when the session opens and writes a `## OpenSpec Mode` section into the extension's injected context. The value of `CHORUS_OPENSPEC_ACTIVE` is `1` only when **all three** of these hold:
+The chorus-pi extension's `session_start` handler resolves the spec mode once when the session opens (via the TS `resolveSpecMode`, the single source of truth — the reimplementation of the canonical bash resolver) and writes a `## Spec Mode` section into the injected context stating `CHORUS_SPEC_MODE=<lite|openspec|off>`; when the resolved mode is a usable OpenSpec it also carries a `CHORUS_OPENSPEC_ACTIVE=1` line. That line is present only when `CHORUS_SPEC_MODE` is `openspec` **or unset**, **and all three** of these hold:
 
-1. `CHORUS_OPENSPEC_MODE` is **not** set to `off` (explicit opt-out wins).
+1. OpenSpec is not disabled (`CHORUS_OPENSPEC_MODE` not `off`, `enableOpenSpec` not `false`).
 2. The project root contains an `openspec/` directory (i.e. someone ran `openspec init` here).
 3. The `openspec` CLI is on `PATH`.
 
-Both signals (2) and (3) are required because the OpenSpec authoring path needs the working directory **and** the CLI — having one without the other leaves the workflow unrunnable. If signal (2) holds but (3) does not, the session_start handler surfaces a "OpenSpec repo detected — install with: `npm i -g @fission-ai/openspec`" hint to the user; the agent should pass this through if asked rather than silently choosing free-form.
+Both signals (2) and (3) are required because the OpenSpec authoring path needs the working directory **and** the CLI. If signal (2) holds but (3) does not, the `## Spec Mode` section carries an install hint (`npm i -g @fission-ai/openspec`); pass it through if asked.
 
 ### How to read the value
 
-You should already see something like this in your context (look for the `## OpenSpec Mode` section near the top of the conversation):
+You should already see something like this in your context (look for the `## Spec Mode` section near the top of the conversation):
 
 ```
-## OpenSpec Mode
+## Spec Mode
+
+CHORUS_SPEC_MODE=openspec (default — openspec/ directory + openspec CLI both present)
 
 CHORUS_OPENSPEC_ACTIVE=1 (openspec/ directory + openspec CLI both present)
 ```
 
-or:
+or (resolved to lite / off — no `CHORUS_OPENSPEC_ACTIVE=1` line):
 
 ```
-## OpenSpec Mode
+## Spec Mode
 
-CHORUS_OPENSPEC_ACTIVE=0 (no openspec/ directory at /path/to/repo/openspec)
+CHORUS_SPEC_MODE=lite (default — OpenSpec not usable: no openspec/ directory at /path/to/repo/openspec)
 ```
 
 Branch:
 
-- `CHORUS_OPENSPEC_ACTIVE=1` → follow §3 (OpenSpec authoring).
-- `CHORUS_OPENSPEC_ACTIVE=0` → return to the calling skill's free-form path. **Do not** scaffold `openspec/changes/`. **Do not** add the slug line to the proposal description.
-
-### Manual fallback
+- `CHORUS_OPENSPEC_ACTIVE=1` line present → follow §3 (OpenSpec authoring).
+- No `CHORUS_OPENSPEC_ACTIVE=1` line → this skill is a no-op; return to the caller, which follows the resolved `CHORUS_SPEC_MODE` (**spec-lite** or free-form). **Do not** scaffold `openspec/changes/`. **Do not** add the slug line to the proposal description.
 
-If you're in a sub-shell, sub-agent, or session that did not see session_start context (e.g. you were spawned mid-session and the parent's context was not forwarded), reconstruct the value yourself with the same three checks:
+If the `## Spec Mode` section shows an explicit `CHORUS_SPEC_MODE=openspec` that **cannot be honored** (OpenSpec disabled or not installed — it carries a config-conflict / not-installed reason and no `CHORUS_OPENSPEC_ACTIVE=1` line), the caller MUST **halt** and surface it — do not silently fall back.
 
-```bash
-if [ "${CHORUS_OPENSPEC_MODE:-}" = "off" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-elif [ ! -d "$PWD/openspec" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-elif ! openspec --version >/dev/null 2>&1; then
-  CHORUS_OPENSPEC_ACTIVE=0
-else
-  CHORUS_OPENSPEC_ACTIVE=1
-fi
-```
+### Manual fallback
 
-Use this only when session_start context is genuinely unavailable — duplicating the detection is wasteful when the hook already computed it.
+The mode is resolved by the extension in TypeScript (`resolveSpecMode`) at `session_start` — there is no separate bash resolver to source, and you must **not** hand-roll the rule (a hand-rolled OpenSpec-only check ignores `CHORUS_SPEC_MODE` and the lite/off cases). If the `## Spec Mode` section is genuinely absent (e.g. the checkin/connection failed, or you are a forwarded sub-agent whose parent context was not carried), set `CHORUS_SPEC_MODE` explicitly (`lite` | `openspec` | `off`) and relaunch so the extension re-resolves it — rather than guessing.
 
 ---
 
@@ -393,15 +385,15 @@ The hook is read-only; you (the agent) perform the archive:
 
 ---
 
-## §4. Fallback authoring (no openspec)
+## §4. When OpenSpec is not the resolved mode
 
-When detection puts the agent in fallback mode (`CHORUS_OPENSPEC_ACTIVE=0`), this skill is a **no-op**. Return to the calling skill's free-form path:
+When the resolved mode is not a usable OpenSpec (no `CHORUS_OPENSPEC_ACTIVE=1` line), this skill is a **no-op** — return to the calling skill, which follows the resolved `CHORUS_SPEC_MODE`: **spec-lite** (the default when OpenSpec isn't usable) or free-form (`=off`). From this skill's side:
 
 - No `openspec/changes/` folder is created or referenced.
 - No `OpenSpec change slug: …` line is added to the proposal description.
-- Document drafts are authored via direct MCP `chorus_pm_add_document_draft` calls with inline `content` — same as before this skill existed.
-- Rule 1 (wrapper-only mirror) does not apply — there is no local file source of truth.
-- The §3.9 archive hook does nothing (no slug → silent exit).
+- In **spec-lite**, the caller follows `/skill:spec-lite` (durable `.chorus/specs/<slug>/spec.md` + dated per-change folders mirrored via `--arg-file`); in **free-form**, document drafts are authored via direct MCP `chorus_pm_add_document_draft` calls with inline `content` — same as before this skill existed.
+- Rule 1 (wrapper-only mirror) still applies in spec-lite (mirror from the local file); in free-form there is no local file source of truth.
+- The §3.9 archive hook does nothing (no slug → silent exit); spec-lite has no archive step at all.
 
 ---
 
@@ -485,8 +477,8 @@ This is project-wide policy: no silent errors.
 
 When invoked from a stage skill (proposal / develop / yolo):
 
-1. Read `CHORUS_OPENSPEC_ACTIVE` from the `## OpenSpec Mode` section in the session_start context (§1). If it isn't there, fall back to the manual probe in §1.
-2. If `CHORUS_OPENSPEC_ACTIVE=0` → return to caller's free-form path (§4).
+1. Read the `## Spec Mode` section in the session_start context (§1) — proceed only if it carries the `CHORUS_OPENSPEC_ACTIVE=1` line. If the section is absent, use the fallback in §1 (set `CHORUS_SPEC_MODE` explicitly + relaunch).
+2. No `CHORUS_OPENSPEC_ACTIVE=1` line → no-op; return to the caller per the resolved `CHORUS_SPEC_MODE` (spec-lite or free-form) — see §4.
 3. Otherwise:
    a. Pick `$SLUG` (§3.1).
    b. `openspec new change "$SLUG"` (§3.2).

package/skills/orchestrate/SKILL.md

@@ -4,7 +4,7 @@ description: Multi-agent orchestration playbook — coordinate OTHER agents and
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---
@@ -104,6 +104,14 @@ Guidance: start narrow. If a single owner can hold the whole feature in their he
 
 ---
 
+## Replying to the agent who woke you (advisory)
+
+When an agent wakes a peer on a shared idea or task — an orchestrator dispatching a worker, or any agent `@mention`-ing another — the wake surfaces the **waker's live session anchor**: a note naming the waking agent and telling the woken peer that the waker has an open conversation on this idea. If you are the woken peer, **reply on the same idea/task resource** (comment there rather than opening a brand-new session) and your reply lands back in the waker's existing live session, keeping the collaboration on one thread instead of scattering into a fresh one.
+
+This is **advisory, not routing.** There is no automatic server subscription and nothing is force-delivered — replying on the shared resource is simply *where a reply lands* (via the existing return path), not a guaranteed channel. When the waker's origin is **offline** at wake time, no live anchor is surfaced and the exchange degrades to **notify-only**: the reply reaches the waker as an ordinary notification it picks up on its next turn. Only idea/theme-anchored wakes carry this anchor; ad-hoc wakes with no shared idea do not.
+
+---
+
 ## Reversed-Conversation gates (you never auto-ship)
 
 Chorus is **AI proposes, humans verify**. As orchestrator you enforce that, you do not bypass it:

package/skills/proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---
@@ -69,7 +69,9 @@ Elaboration resolved --> Create Proposal --> Add drafts --> Validate --> Submit
 
 ### Step 1: Create an Empty Proposal
 
-**Recommended approach:** Create the proposal container first without any drafts, then incrementally add document and task drafts one by one.
+**Resolve the spec mode (Step 1.5) BEFORE this create.** In OpenSpec and spec-lite modes the container's `description` MUST carry a locator line (`OpenSpec change slug: <slug>` or `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/`), and `description` can only be set at creation — decide the mode + slug/dated-path first and include that line in this single call. Free-form mode omits any locator line.
+
+**Recommended approach:** Create the proposal container first (with the mode's locator line in `description` when applicable), then incrementally add document and task drafts one by one.
 
 ```
 chorus_pm_create_proposal({
@@ -85,15 +87,20 @@ chorus_pm_create_proposal({
 
 > **A theme cannot be a proposal input** — `chorus_pm_create_proposal` rejects any input idea with `isContainer = true`. Derive a child idea from the theme and write the proposal on the child instead. (See the theme-ideas section of the `/idea` skill.)
 
-### Step 1.5: Detect OpenSpec mode
+### Step 1.5: Select spec mode
+
+The spec mode is **already computed** by the chorus-pi extension's `session_start` handler (`resolveSpecMode`) — do NOT re-derive it. Read the `## Spec Mode` section of your injected context: it states `CHORUS_SPEC_MODE=<lite|openspec|off>` + a routing note. (No `## Spec Mode` in context? See `openspec-aware` §1 manual fallback — never hand-roll the rule.) Act on that value:
+
+- If the section says the mode **cannot be honored** (explicit `CHORUS_SPEC_MODE=openspec` but OpenSpec unusable — config-conflict or install-hint reason), **halt** and surface it; do not fall back.
+- Otherwise branch on the resolved mode:
 
-Before authoring document drafts, **load the `openspec-aware` skill at `skills/openspec-aware/SKILL.md`** and run its §1 detection contract. Branch on the result:
+- **resolved = spec-lite** → load the `spec-lite` skill (`/skill:spec-lite`) and follow it: pick `$SLUG` (a **capability**, not one change). Ensure the durable `.chorus/specs/<slug>/spec.md` exists (local-only, **no Chorus ids**; use the `spec-lite` skill's inline durable-spec template) and update it in place. Create this change's **dated folder** `.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` with its **synced** Chorus-typed docs (`prd.md` primary, optional `tech_design.md`…; use the `spec-lite` skill's inline dated-folder document template). Put the literal locator line `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` in the **Step 1 create** `description`, then mirror **each** dated-folder `<type>.md` to its persistent Document (`chorus_pm_add_document_draft --arg-file` first time, `chorus_pm_update_document --arg-file` after) via `chorus mcp call … --arg-file content=.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/<type>.md`. **`spec.md` is never mirrored.** Skip Step 2 below. (Tasks via `chorus_pm_add_task_draft`; no `tasks.md`.)
 
-- **`CHORUS_OPENSPEC_ACTIVE=1`** → follow `openspec-aware` §3. Pick `$SLUG`, scaffold `openspec/changes/<slug>/`, author `proposal.md` / `design.md` / `specs/<capability>/spec.md` locally, then create the proposal container (Step 1 above) with the literal line `OpenSpec change slug: <slug>` in `description`, and mirror each local file into a document draft.
+- **resolved = OpenSpec** (the `## Spec Mode` section shows `CHORUS_OPENSPEC_ACTIVE=1` — i.e. `CHORUS_SPEC_MODE=openspec` *or* unset, with OpenSpec usable) → follow the `openspec-aware` skill §3. Pick `$SLUG`, scaffold `openspec/changes/<slug>/`, author `proposal.md` / `design.md` / `specs/<capability>/spec.md` locally, then put the literal line `OpenSpec change slug: <slug>` in the **Step 1 create** `description`, and mirror each local file into a document draft.
 
-  > **⛔ Mandatory in OpenSpec mode:** mirror calls fill `content` from the local file — prefer `chorus mcp call … --arg-file content=<file>`, falling back to the `chorus-mcp-call.sh` wrapper with `json_encode_file` when `chorus` is not on `PATH` — see `openspec-aware` §3.6. Do **not** call `chorus_pm_add_document_draft` directly from the MCP harness with a hand-typed `content` field. Re-typing thousands of lines through the LLM burns 20k+ content tokens per proposal and breaks byte-equality with the local source of truth (`openspec-aware` §2 Rule 1 explains the full reasoning). Skip Step 2 below when in OpenSpec mode — the file-fill flow in `openspec-aware` §3.6 replaces it for documents.
+  > **⛔ Mandatory in OpenSpec mode:** mirror calls fill `content` from the local file — prefer `chorus mcp call … --arg-file content=<file>`, falling back to the `chorus-mcp-call.sh` wrapper with `json_encode_file` when `chorus` is not on `PATH` — see `openspec-aware` §3.6. Do **not** call `chorus_pm_add_document_draft` directly with a hand-typed `content` field. Re-typing thousands of lines burns 20k+ content tokens per proposal and breaks byte-equality (`openspec-aware` §2 Rule 1). Skip Step 2 when in OpenSpec mode — the file-fill flow replaces it for documents.
 
-- **`CHORUS_OPENSPEC_ACTIVE=0`** (CLI absent or `CHORUS_OPENSPEC_MODE=off`) → proceed with Step 2 unchanged. Author drafts inline as free-form Markdown via direct MCP `chorus_pm_add_document_draft`.
+- **resolved = free-form** (explicit `CHORUS_SPEC_MODE=off`) → proceed with Step 2 unchanged. Author drafts inline as free-form Markdown via direct MCP `chorus_pm_add_document_draft`.
 
 ### Step 2: Add Document Drafts
 

package/skills/quick-dev/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---
@@ -152,7 +152,7 @@ chorus_submit_for_verify({
 })
 ```
 
-Submitting is not final verification. Spawn the required task-reviewer agent with `subagent_spawn` as described in `/skill:develop`, wait for it, and read the newest `VERDICT:` Task comment. `PASS` and `PASS WITH NOTES` continue. On `FAIL`, do not verify or hand off: fix every unresolved BLOCKER, repeat AC self-check and submission, then run a fresh independent task review.
+Submitting is not final verification. Spawn the required task-reviewer agent with `subagent_spawn` as described in `/skill:develop`, wait for it, and read THIS round's `VERDICT:` Task comment — the one posted after your dispatch, not an older round's. `PASS` and `PASS WITH NOTES` continue. On `FAIL`, do not verify or hand off: fix every unresolved BLOCKER, repeat AC self-check and submission, then run a fresh independent task review.
 
 ### Step 8: Permission-Aware Verification
 

package/skills/review/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---
@@ -65,12 +65,12 @@ Key responsibilities:
 When reviewing proposals, tasks, or an Idea's final aggregate code change, prefer spawning an independent reviewer sub-agent over reviewing manually:
 
 1. **Try the reviewer first.** Spawn `chorus-proposal-reviewer` (for proposals), `chorus-task-reviewer` (for tasks), or `chorus-code-reviewer` (the final ship-time gateway over an Idea's aggregate code change, after its last task is verified — pass the `ideaUuid`; it posts its VERDICT on the **idea**) as a read-only sub-agent. **Use the blocking `subagent` tool** (it waits for the VERDICT and returns it) — you must wait for the VERDICT before proceeding. It posts a VERDICT comment with detailed findings.
-2. **Read the VERDICT.** After the reviewer completes, call `chorus_get_comments` and find the most recent comment containing `VERDICT:`. There are exactly three possible outcomes:
+2. **Read the VERDICT.** After the reviewer completes, call `chorus_get_comments` and find THIS round's `VERDICT:` comment — the one posted after your dispatch, not an older round's. There are exactly three possible outcomes:
    - **VERDICT: PASS** — No issues found. Approve (proposals) or mark AC passed and verify (tasks).
    - **VERDICT: PASS WITH NOTES** — Minor non-blocking notes. Still approve/verify. Notes are informational.
    - **VERDICT: FAIL** — BLOCKERs found. Reject (proposals) or reopen (tasks). Fix the specific BLOCKERs listed in the comment before resubmitting.
-3. **No new VERDICT comment?** The reviewer exhausted its turn budget before posting. Respawn it ONCE with an explicit prompt like: *"Stay within your turn budget. Skip deep source verification — batch all MCP fetches up front, skim for obvious BLOCKERs only, and reserve your last few turns to post the VERDICT comment."* If the second attempt also fails to post, review manually using the checklists below.
-4. **Track rounds.** Count existing VERDICT comments before spawning. After 3 rounds of FAIL on the same item, stop the loop and escalate to human review.
+3. **No new VERDICT comment?** Check what the reviewer *did* post. A comment reporting that the round limit was reached, or any other explicit refusal to review, is a deliberate escalation to a human: STOP — do not respawn, do not self-review, do not post a VERDICT of your own. If it posted nothing at all, respawn it ONCE, telling it to stay within its turn budget and reserve its last turns for the VERDICT, then apply this same check again to what the retry posts. An explicit refusal from the retry still means STOP; only a second true silence lets you review the item yourself as a read-only pass using the checklists below and POST the VERDICT — **absence is never a PASS**.
+4. **Track rounds.** Count existing VERDICT comments before spawning. After 3 rounds of FAIL on the same item, stop the loop and escalate to human review: post a comment saying the round limit was reached and a human decision is needed, and post no VERDICT. Nobody — including you on a later turn — may replace that escalation with a self-reviewed VERDICT.
 5. **Fallback.** If the reviewer is unavailable (e.g., agent type not registered, sub-agent spawn fails), review the item yourself using the quality checklists in the workflows below.
 
 ---

package/skills/spec-lite/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: spec-lite
+description: Lightweight, Chorus-native local specs for Chorus PM workflows in Pi — a durable local spec `.chorus/specs/<slug>/spec.md` (one per capability/feature) edited in place and NEVER synced (git history is its record), plus one dated folder per change effort `.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` holding Chorus-typed docs (prd.md, tech_design.md, …) that ARE mirrored 1:1 into persistent Chorus Documents via `--arg-file`. The fallback when OpenSpec isn't in use; a low-token alternative to the heavier openspec-aware path. Read from proposal / develop / yolo when the spec mode resolves to `lite`.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.18.1"
+  category: project-management
+  mcp_server: chorus
+---
+
+# spec-lite — durable local spec + per-change synced docs
+
+A **shared sub-procedure** for the Chorus stage skills (proposal, develop, yolo) — the lightweight
+spec mode, modelled on **superpowers** (a durable spec that lives on, plus per-effort artifacts):
+one **durable local spec** per capability (`<slug>/spec.md`, edited in place, **never synced** — git
+history is its 留痕), plus one **dated folder per change effort** (`<slug>/<YYYY-MM-DD>-<change-slug>/`
+of Chorus-typed docs — `prd.md`, … — that **are** mirrored 1:1 into persistent Chorus Documents).
+No new CLI, MCP tool, backend, or schema — mirroring reuses the existing document tools.
+
+## Mode (how you got here)
+
+The spec mode is computed by the chorus-pi extension's `session_start` handler (`resolveSpecMode`),
+**not by you** — the `## Spec Mode` section of your injected context states the resolved
+`CHORUS_SPEC_MODE`. You are here because it resolved to `lite`; if it is anything else, this skill is a
+no-op — return to the caller. (For the record, the rule: an explicit `CHORUS_SPEC_MODE` wins, else
+OpenSpec when usable, else lite.)
+
+## The durable local spec — `<slug>/spec.md`
+
+`.chorus/specs/<slug>/spec.md` — `<slug>` (kebab-case) names a **capability/feature, not one change**.
+This is the single, cumulative, human-readable "current truth" of the capability: **edited in place**
+by every change, **never mirrored to Chorus, carries no Chorus ids**. Minimal frontmatter only
+(`slug`, `title`, `status: draft|active|done`, `created`), then plain prose — `## Intent`,
+`## Requirements` (prose + `- [ ]` acceptance points, no `SHALL`/scenario grammar), `## Non-goals`.
+Start from the inline **durable `spec.md` template** below. Its git history is the whole record — no changelog
+section, no Chorus round-trip. **This file NEVER enters the mirror loop.**
+
+`status` describes the **capability**, not a single change: `active` while any change is in flight,
+`done` when the current change delivers and none is open. A **new** change against a `done` capability
+reopens it to `active`, back to `done` on delivery.
+
+### Template — the durable `spec.md`
+
+```markdown
+---
+slug: <kebab-case-capability>
+title: <Capability title>
+status: draft            # draft | active | done
+created: <YYYY-MM-DD>
+---
+
+## Intent
+<what this capability is for, in prose>
+
+## Requirements
+<prose, no SHALL/scenario grammar>
+- [ ] <acceptance point>
+
+## Non-goals
+- <explicitly out of scope>
+```
+
+## Per-change dated folders — `<slug>/<YYYY-MM-DD>-<change-slug>/`
+
+Each change effort is **one dated folder directly under `<slug>/`** (no `changes/` wrapper), e.g.
+`.chorus/specs/<slug>/2026-09-08-add-export/`. Date + slug so same-day changes don't collide and
+folders sort by date. It holds the **Chorus-typed** docs for THAT change — one file per Document type:
+
+| File | `Document.type` | Required? |
+|---|---|---|
+| `prd.md` | `prd` | **yes** — the primary per-change doc |
+| `tech_design.md` | `tech_design` | optional — the "how" |
+| `adr.md` / `guide.md` / `spec.md` | `adr` / `guide` / `spec` | optional |
+
+These files **ARE synced** — each maps to **one persistent Chorus Document** of its type. Their
+frontmatter carries the sync ids `proposalUuid` and `documentUuid` (the type is implied by the
+filename). Start from the inline **dated-folder document template** below. A different change to the same
+capability is a different dated folder. The **current change's** folder is edited and re-mirrored
+throughout its effort (until delivery); only **previously-delivered** dated folders are left frozen —
+you don't reach back and rewrite a past change.
+
+> **Two files named `spec.md`, different roles.** The durable `<slug>/spec.md` (local only, no ids) is
+> NOT the same as a per-change `spec`-type doc, which would live at `<slug>/<date>-<slug>/spec.md`
+> (synced, carries ids). Prefer `prd.md` as the per-change primary doc to avoid the confusion.
+
+### Template — a dated-folder document
+
+The document **type is implied by the filename** (`prd.md` → `prd`, `tech_design.md` → `tech_design`, …),
+**NOT** a frontmatter key.
+
+```markdown
+---
+title: <Document title as it appears in Chorus>
+proposalUuid: <uuid>      # written on first mirror
+documentUuid:             # empty until the draft materializes on approval
+---
+
+# <Document title>
+<body — this file's bytes are the source of truth for the Chorus Document>
+```
+
+## Flow (one change)
+
+1. Confirm mode = `lite` (else no-op).
+2. Create the dated folder `<slug>/<YYYY-MM-DD>-<change-slug>/` and write its **synced** change docs —
+   `prd.md` (required), `tech_design.md` etc. only if warranted (use the **dated-folder document template** above).
+3. **Update `<slug>/spec.md` in place** to the new cumulative truth (Requirements, acceptance points,
+   `status`) — local only, no sync.
+4. Create the proposal container with one literal locator line in `description` (own line, no trailing
+   punctuation) so develop finds the change:
+   `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/`
+5. **Mirror the dated folder's docs** to Chorus (below). Add tasks via `chorus_pm_add_task_draft` —
+   **no `tasks.md`**, no CLI / validate / archive, no delta grammar. **Tasks live in Chorus.**
+6. Develop → keep editing `spec.md` + the change docs, re-mirroring the change docs as work lands and
+   ticking acceptance points. On delivery set the durable `spec.md` `status: done`.
+
+## Mirror — only the dated-folder docs (never `spec.md`)
+
+Every dated-folder `<type>.md` maps to **one persistent Chorus Document** of that `type`, tracked by
+`documentUuid` in the file's frontmatter. Fill `content` from the file's bytes with `--arg-file` —
+never re-type the body (drifts, burns ~20k tokens). One call per file; resolve identity by
+`documentUuid` / `(proposalUuid, type)`, **never by `title` alone** (a lookup finding zero or >1 MUST
+**halt**). Guard every call with the `chorus_check_response` halt-on-error helper (`openspec-aware`
+§6). No `chorus` on `PATH`? Fall back to `chorus-mcp-call.sh` + `json_encode_file` (`openspec-aware` §3.6);
+the extension resolves the bundled wrapper and surfaces its path in the session_start context.
+**`<slug>/spec.md` is NEVER in this loop.**
+
+- **First time a doc is authored** (its dated folder is new): write `proposalUuid` into frontmatter,
+  mirror into a proposal **draft** —
+  `chorus mcp call chorus_pm_add_document_draft "{\"proposalUuid\":\"$P\",\"type\":\"prd\",\"title\":\"PRD: $TITLE\"}" --arg-file content=".chorus/specs/$SLUG/$DATED/prd.md"`.
+  Edit the draft via `chorus_pm_update_document_draft` (returned `draftUuid`) before approval. On
+  approval it materializes into a persistent Document — resolve by `(proposalUuid, type)` via
+  `chorus_get_documents`, record `documentUuid` in frontmatter, re-mirror once so local == Chorus.
+- **Later edits** (a doc that already has a `documentUuid`): edit the file, then
+  `chorus mcp call chorus_pm_update_document "{\"documentUuid\":\"$D\"}" --arg-file content=".chorus/specs/$SLUG/$DATED/<type>.md"`.
+  Each update **auto-increments the Document version** — that version history is the change doc's
+  record in Chorus, alongside git.
+
+## 留痕: git history + Document versions
+
+`git log -- .chorus/specs/$SLUG/` is the audit trail — the durable `spec.md`'s in-place diffs plus each
+dated folder's change docs; the mirrored Documents' auto-incremented versions are the parallel record
+in Chorus. No changelog section to maintain. Only `.chorus/specs/` is version-controlled (`.chorus/*` +
+`!.chorus/specs/`).
+
+**Single-writer:** the folder is shared — in a multi-task wave only the **orchestrator / main agent**
+edits + re-mirrors; parallel workers report via `chorus_report_work` only, re-reading before any write.
+**Task state lives in Chorus**, not the docs — the `- [ ]` points are acceptance intent, not a tracker.

package/skills/yolo/SKILL.md

@@ -4,7 +4,7 @@ description: Full-auto AI-DLC pipeline — from prompt to done. Automates the en
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.3"
+  version: "0.18.1"
   category: project-management
   mcp_server: chorus
 ---
@@ -188,21 +188,17 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
 
 #### Step 1.4: Create Proposal
 
-1. **Detect OpenSpec mode.** Load the `openspec-aware` skill at `skills/openspec-aware/SKILL.md` and run its §1 detection contract. The result determines how the rest of this step authors documents:
+1. **Read the spec mode (already computed).** The chorus-pi extension's `session_start` handler (`resolveSpecMode`) has already resolved it — do NOT re-derive. Read the `## Spec Mode` section: `CHORUS_SPEC_MODE=<lite|openspec|off>` + a routing note. Act on it: `openspec` (usable, shows `CHORUS_OPENSPEC_ACTIVE=1`) → **2a**; `off` → **2b**; `lite` → **2c**. If it says the mode **cannot be honored** (explicit `openspec` but unusable), **halt** and surface it — do NOT fall back or enter 2a with no OpenSpec. (No `## Spec Mode`? See `openspec-aware` §1 manual fallback.) This matters because yolo runs unattended.
 
-   - `CHORUS_OPENSPEC_ACTIVE=1` → spec-driven branch (sub-step 2a below).
-   - `CHORUS_OPENSPEC_ACTIVE=0` → free-form branch (sub-step 2b below).
-
-   This is mandatory — yolo runs unattended, so silently picking the wrong mode is exactly the failure scenario the detection contract exists to prevent.
-
-2. **Create the empty proposal container.** In OpenSpec mode, the `description` MUST contain the literal line `OpenSpec change slug: <slug>` (use the `$SLUG` you'll pick in 2a); in free-form mode, omit that line.
+2. **Create the empty proposal container.** The `description` MUST carry the mode's locator line — OpenSpec: `OpenSpec change slug: <slug>`; spec-lite: `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/`; free-form: none. `description` is only settable at creation, so decide the slug/dated-path first.
 
    ```
    chorus_pm_create_proposal({
      projectUuid: "<project-uuid>",
      title: "<feature name>",
-     description: "<summary>\n\nOpenSpec change slug: <slug>",   // OpenSpec mode
-     // description: "<summary>",                                 // free-form mode
+     description: "<summary>\n\nOpenSpec change slug: <slug>",                          // OpenSpec (2a)
+     // description: "<summary>\n\nSpec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/", // spec-lite (2c)
+     // description: "<summary>",                                                        // free-form (2b)
      inputType: "idea",
      inputUuids: ["<idea-uuid>"]
    })
@@ -220,7 +216,7 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
 
    Then continue to step 3 (task drafts).
 
-   **2b. Free-form mode (`CHORUS_OPENSPEC_ACTIVE=0`).** Add a tech design document draft directly via MCP, content authored inline:
+   **2b. Free-form mode (resolved mode = free-form).** Only when step 1 resolved to free-form — i.e. explicit `CHORUS_SPEC_MODE=off` (unset never comes here: it resolves to OpenSpec when usable, else spec-lite/2c). Add a tech design document draft directly via MCP, content authored inline:
 
    ```
    chorus_pm_add_document_draft({
@@ -231,6 +227,8 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
    })
    ```
 
+   **2c. spec-lite mode (resolved mode = lite).** Load the `spec-lite` skill (`/skill:spec-lite`). Pick `$SLUG` (a **capability**). Ensure the durable `.chorus/specs/<slug>/spec.md` exists (local-only, no ids; use the `spec-lite` skill's inline durable-spec template) and update it in place. Create this change's **dated folder** `.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` with its **synced** Chorus-typed docs (shape = the `spec-lite` skill's inline dated-folder document template) — `prd.md` (primary), optional `tech_design.md`… The `description` carries the `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` locator (step 2). Mirror **each** dated-folder `<type>.md` to its persistent Document byte-exact — first time `chorus mcp call chorus_pm_add_document_draft "{\"proposalUuid\":\"<uuid>\",\"type\":\"prd\",\"title\":\"PRD: <feature>\"}" --arg-file content=.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/prd.md`, later edits via `chorus_pm_update_document` against the recorded `documentUuid` (`chorus-mcp-call.sh` fallback when `chorus` not on `PATH`). **`spec.md` is never mirrored.** No `openspec/changes/` scaffold; no `tasks.md`. Then continue to step 3.
+
 3. **Add task drafts incrementally** (use returned `draftUuid` for dependency chaining). `acceptanceCriteriaItems` is **required** on every draft — at least one non-blank criterion, or the call is rejected:
    ```
    # First task
@@ -272,6 +270,20 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
 
 ---
 
+### Reviewer contract (applies to every review gate below)
+
+Every gate in Phases 2, 4 and 4.5 follows the same three steps. They are written once here; the phases below only name their entity and their stage-specific actions.
+
+1. **Spawn and wait.** Spawn the reviewer as a read-only sub-agent, then wait for it: spawn it via the blocking `subagent` tool, which waits for the reviewer to finish. Read the verdict from the reviewer's `VERDICT:` comment on the entity.
+2. **Read THIS round's VERDICT.** Call `chorus_get_comments` on the entity and find the `VERDICT:` comment posted **after your dispatch**, not an older round's. Do not advance the gate before you have read it.
+3. **No VERDICT for this round?** Check what the reviewer *did* post:
+   - **A reported round limit, or any other explicit refusal to review** — a deliberate escalation to a human. STOP: do not respawn, do not self-review, do not post a VERDICT of your own.
+   - **Nothing at all** — respawn ONCE, telling it to stay within its turn budget and reserve its last turns for the VERDICT, then apply this same check again to what the retry posts. An explicit refusal from the retry still means STOP; only a second true silence lets you review the entity yourself as a read-only pass and POST the VERDICT, then proceed on what you posted rather than looping forever.
+
+**Absence is never a PASS**, and a round limit reached by someone else is never yours to clear.
+
+---
+
 ### Phase 2: Proposal Review Loop
 
 After `chorus_pm_submit_proposal`, the extension nudges you to spawn `chorus-proposal-reviewer`. You MUST manually spawn it as a read-only sub-agent via the blocking `subagent` tool (it waits for the VERDICT). Wait for it to complete, then:
@@ -280,7 +292,7 @@ After `chorus_pm_submit_proposal`, the extension nudges you to spawn `chorus-pro
    ```
    chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
    ```
-   Look for the most recent comment containing `VERDICT:`.
+   Look for THIS round's `VERDICT:` comment — the one posted after your dispatch, not an older round's.
 
 2. **Act on the VERDICT:**
 
@@ -314,7 +326,7 @@ After `chorus_pm_submit_proposal`, the extension nudges you to spawn `chorus-pro
           Proposal UUID: <uuid>"
    ```
 
-4. **No new VERDICT comment after reviewer returns?** The reviewer exhausted its turn budget. Respawn it ONCE with a concise-budget hint: *"Stay within turn budget. Skip deep source verification. Fetch proposal + comments + idea only, skim for obvious BLOCKERs, and post your VERDICT within the first 10 turns."* If the second attempt still produces no VERDICT, treat the proposal as PASS WITH NOTES and proceed — the pipeline cannot loop forever on a silent reviewer.
+4. **No new VERDICT for this round?** Apply step 3 of the **Reviewer contract**, reviewing the proposal yourself if the reviewer stays silent.
 
 ---
 
@@ -411,7 +423,7 @@ for each task in wave_tasks:
 
   # 3. Read task-reviewer VERDICT
   comments = chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
-  # Find the most recent comment containing "VERDICT:"
+  # Find THIS round's "VERDICT:" comment — the one posted after your dispatch, not an older round's
 
   # 4. Act on VERDICT — three possible outcomes:
   if VERDICT is "PASS":
@@ -449,7 +461,7 @@ ESCALATE: "Task '{title}' failed review after {maxRounds} rounds.
 
 Continue with remaining tasks -- do not halt the entire pipeline for one stuck task.
 
-**No new VERDICT comment after the task-reviewer returns?** It exhausted its turn budget. Respawn it ONCE with a concise-budget hint: *"Stay within turn budget. Skip deep verification. Fetch task/proposal/comments, run only the core tests, and post your VERDICT within the first 12 turns."* If the second attempt also produces no VERDICT, treat as PASS WITH NOTES and proceed — do not loop indefinitely.
+**No new VERDICT for this round?** Apply step 3 of the **Reviewer contract**, reviewing the task yourself if the reviewer stays silent.
 
 ---
 
@@ -465,7 +477,7 @@ subagent({ agent: "chorus-code-reviewer",
 
 # Read its VERDICT on the idea
 comments = chorus_get_comments({ targetType: "idea", targetUuid: "<idea-uuid>" })
-# Find the most recent comment containing "VERDICT:"
+# Find THIS round's "VERDICT:" comment — the one posted after your dispatch, not an older round's
 ```
 
 Act on the VERDICT:
@@ -479,7 +491,7 @@ ESCALATE: "Idea '<title>' failed code review after {CHORUS_MAX_CODE_REVIEW_ROUND
            Last BLOCKERs: <list>. Manual intervention needed. Idea UUID: <uuid>"
 ```
 
-**No new VERDICT comment after the code-reviewer returns?** It exhausted its turn budget (the code-reviewer runs with a larger budget than the task-reviewer because it reviews the whole feature). Respawn it ONCE with a concise-budget hint, then if still silent treat as PASS WITH NOTES and proceed — do not loop forever on a silent reviewer.
+**No new VERDICT for this round?** Apply step 3 of the **Reviewer contract**, reviewing the idea's aggregate change yourself if the reviewer stays silent.
 
 > The code-review gateway is **behavioral**, consistent with the proposal/task reviewers: its verdict is advisory and does not change the Idea's stored status. The /yolo orchestrator honors it — PASS to ship, FAIL to loop. It runs **before** the completion report so the report is never written for a feature with an outstanding FAIL.