@chorus-aidlc/chorus-pi 0.17.2 → 0.18.0

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;
@@ -183,68 +183,211 @@ export function sessionWorkflow(sessionUuid: string): string {
 }
 
 /**
- * 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.
+ * True when a worker task already carries an injected session block.
+ *
+ * Matches the block header at the start of a line (`--- Chorus session`), so
+ * prose that merely mentions "Chorus session" does not suppress injection.
+ * Covers both this extension's injected block and any main-agent template.
+ * The header is exactly "--- Chorus session" followed by " (…)" or end of line;
+ * a hyphenated continuation like "--- Chorus session-notes" is not a header.
  */
-export interface OpenSpecState {
-  active: boolean;
-  reason: string;
-  optout: boolean;
-  hint: string;
+export function hasSessionMarker(task: string): boolean {
+  return /^--- Chorus session(?=[ (\u2014]|$)/m.test(task);
 }
 
 /**
- * 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
+ * Detect an async (detached) nicobailon pi-subagents `subagent` run from its
+ * tool_result EVENT, and extract the run id that its completion events will
+ * carry.
  *
- * fs and execSync are injected so tests can stub the filesystem and the CLI
- * presence check without touching the real environment.
+ * The official bundled subagent (blocking) returns at tool_result with no run
+ * id — the session lifecycle closes there. The nicobailon `pi-subagents` tool
+ * launches async (detached) by default: spawn returns immediately with
+ * `details.asyncId`, and completion arrives later on the pi event bus as
+ * `subagent:async-complete` / `subagent:process-terminal` with `{runId}`/`{id}`.
+ * Only `details.asyncId`/`details.runId` are trusted — the nicobailon contract
+ * always carries the run id in `details` for async launches (verified against
+ * pi-subagents src/runs/foreground/subagent-executor.ts: async started returns
+ * `details: { mode, results, asyncId, asyncDir }` (:1584/:1375), and nicobailon
+ * itself reads `result.details.asyncId` (:1711/:1967/:2119); `id`/`prefix`
+ * appear only in completion-event payloads, never in tool_result details), and
+ * a blocking run's worker output (even standalone JSON) must never be
+ * misclassified as an async run (which would leak the session until
+ * session_shutdown).
  */
-export function detectOpenSpec(
-  cwd: string,
-  optout: boolean,
+export function extractRunIdFromToolResultEvent(event: {
+  details?: unknown;
+}): string | null {
+  const d = (event.details ?? {}) as Record<string, unknown>;
+  for (const key of ["asyncId", "runId"]) {
+    if (typeof d[key] === "string" && (d[key] as string).length > 0) return d[key] as string;
+  }
+  return null;
+}
+
+/**
+ * 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 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;
+}
+
+/**
+ * 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.
+ *
+ * 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 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)";
+  }
+
+  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";
   }
-  const openspecDir = `${cwd}/openspec`;
-  if (!fs.existsSync(openspecDir)) {
-    return { active: false, reason: `no openspec/ directory at ${openspecDir}`, optout: false, hint: "" };
+
+  // --- 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`;
+      }
   }
-  let cliPresent = false;
+
+  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
  *
@@ -259,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).
@@ -278,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.2",
+  "version": "0.18.0",
   "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"
@@ -52,7 +52,10 @@
   },
   "pi": {
     "extensions": ["./extensions"],
-    "skills": ["./skills"]
+    "skills": ["./skills"],
+    "subagents": {
+      "agents": ["./agents"]
+    }
   },
   "//note": "Reviewer subagents use pi's official subagent pattern, bundled at extensions/subagent/ (index.ts + agents.ts, copied from earendil-works/pi's examples). The copied agents.ts discovers this package's own agents/*.md via a package-relative BUNDLED_DIR, so the 3 reviewer agents load with ZERO manual copy into ~/.pi/agent/agents/. pi auto-loads extensions/subagent/index.ts as a subdirectory-with-index extension (no manifest entry needed)."
 }

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.2"
+  version: "0.18.0"
   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.2"
+  version: "0.18.0"
   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.2"
+  version: "0.18.0"
   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.2"
+  version: "0.18.0"
   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.2"
+  version: "0.18.0"
   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.2"
+  version: "0.18.0"
   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.2"
+  version: "0.18.0"
   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).