@chorus-aidlc/chorus 0.17.3 → 0.18.0

package/.next/standalone/public/chorus-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "chorus",
   "description": "Chorus AI-DLC collaboration platform plugin for Claude Code. Automates session lifecycle, provides MCP tools for PM/Developer/Admin workflows, and enables multi-agent team observability.",
-  "version": "0.17.3",
+  "version": "0.18.0",
   "author": {
     "name": "Chorus-AIDLC"
   },
@@ -48,7 +48,7 @@
     "enableOpenSpec": {
       "type": "boolean",
       "title": "Enable OpenSpec Mode",
-      "description": "Opt-in spec-driven authoring path. When enabled and the repo is OpenSpec-init'd (openspec/ folder + openspec CLI both present), proposal/develop/yolo skills author proposal.md / design.md / specs/<capability>/spec.md on disk and mirror them into Chorus drafts via the wrapper script (saves ~20k tokens per proposal vs. retyping through MCP). Also enables the post-verify archive hook that reminds the agent to run `openspec archive <slug>` after the last task is verified. Silent no-op when the repo is not OpenSpec-init'd.",
+      "description": "Spec-driven authoring path, the default when usable. When enabled and the repo is OpenSpec-init'd (openspec/ folder + openspec CLI both present), proposal/develop/yolo skills author proposal.md / design.md / specs/<capability>/spec.md on disk and mirror them into Chorus drafts via the wrapper script (saves ~20k tokens per proposal vs. retyping through MCP). Also enables the post-verify archive hook that reminds the agent to run `openspec archive <slug>` after the last task is verified. When this is off — or OpenSpec isn't installed — the spec mode falls back to spec-lite (Chorus-native lightweight specs in .chorus/specs/<slug>/), unless CHORUS_SPEC_MODE overrides.",
       "default": true
     }
   },

package/.next/standalone/public/chorus-plugin/agents/code-reviewer.md

@@ -87,6 +87,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/.next/standalone/public/chorus-plugin/agents/proposal-reviewer.md

@@ -9,9 +9,11 @@ disallowedTools:
   - Edit
   - Write
   - NotebookEdit
-  - Bash
 criticalSystemReminder_EXPERIMENTAL: >
-  CRITICAL: READ-ONLY proposal review. You CANNOT edit, write, create files, or run Bash commands.
+  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.
   Keep your comment output under 800 characters. PASS items: names only. NOTE items: one-line description. BLOCKER items: evidence + expected/actual.
   Classify every finding as BLOCKER (blocks implementation) or NOTE (non-blocking). Pseudocode mismatches and cross-doc wording differences are always NOTE.
   You MUST end with VERDICT: PASS, VERDICT: PASS WITH NOTES, or VERDICT: FAIL. Has BLOCKERs → FAIL. Only NOTEs → PASS WITH NOTES. Nothing → PASS.
@@ -28,9 +30,15 @@ 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 (Bash is disabled)
+- Any shell command beyond read-only inspection (see the rule below)
 - Installing dependencies or packages
 
+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.
+
+(This repeats the `criticalSystemReminder_EXPERIMENTAL` frontmatter verbatim on purpose: that field is experimental and Claude-Code-only, so a rename or removal upstream would otherwise take the rule with it silently. Keep the two copies identical.)
+
 === WHAT YOU RECEIVE ===
 You will receive a proposalUuid. Your job is to fetch and review the full proposal.
 
@@ -73,6 +81,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/.next/standalone/public/chorus-plugin/agents/task-reviewer.md

@@ -91,6 +91,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/.next/standalone/public/chorus-plugin/bin/chorus-api.sh

@@ -292,7 +292,7 @@ cmd_mcp_tool() {
     # Step 1: Initialize MCP session
     local init_payload
     init_payload=$(cat <<JSONEOF
-{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-hook","version":"0.17.3"}}}
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-hook","version":"0.18.0"}}}
 JSONEOF
 )
 

package/.next/standalone/public/chorus-plugin/bin/on-post-submit-for-verify.sh

@@ -48,15 +48,15 @@ Max review rounds: ${MAX_ROUNDS} (0 = unlimited).
 ACTION REQUIRED: Spawn the \`chorus:task-reviewer\` agent to perform an independent review before admin verification.
 
 Example:
-  Agent({ subagent_type: \"chorus:task-reviewer\", prompt: \"Review task ${TASK_UUID}. Max review rounds: ${MAX_ROUNDS}. First, read existing comments to count previous VERDICTs and determine your round number. If max > 0 and your round exceeds max, skip the review and post a comment saying the limit was reached — human decision needed. Otherwise, proceed with review. Post your VERDICT as a comment on the task.\" })
+  Agent({ subagent_type: \"chorus:task-reviewer\", prompt: \"Review task ${TASK_UUID}. Max review rounds: ${MAX_ROUNDS}. First, read existing comments to count previous VERDICTs and determine your round number. If max > 0 and your round exceeds max, skip the review and post a comment saying the round limit was reached and a human decision is needed, and post no VERDICT (this tells the main agent to stop rather than substitute its own verdict). Otherwise, proceed with review. Post your VERDICT as a comment on the task.\" })
 
 The reviewer is read-only and will post its VERDICT as a comment on the task.
 
-After the reviewer completes, read comments and find the most recent \`VERDICT:\` line:
+Wait for the reviewer to complete (its completion notification), then read this round's \`VERDICT:\` comment with chorus_get_comments — on THIS task, posted after you dispatched the reviewer. Do not settle for an older VERDICT from a previous round:
 - **VERDICT: PASS** — All AC verified, no issues. Proceed to mark AC and call chorus_admin_verify_task.
 - **VERDICT: PASS WITH NOTES** — All AC verified, minor non-blocking notes. Still proceed to verify.
 - **VERDICT: FAIL** — BLOCKERs found. Do NOT verify. Reopen the task (chorus_admin_reopen_task) and fix the BLOCKERs.
 
-IMPORTANT: Run the reviewer synchronously (do NOT set run_in_background). Wait for its VERDICT before proceeding."
+IMPORTANT: the launch result is not the verdict — these reviewer subagent types report an async launch regardless of the flag you pass. Do NOT verify or reopen before you have read this round's VERDICT comment. If it is missing, check what the reviewer did post: a comment reporting the round limit was reached, or any other explicit refusal to review, is a deliberate escalation — STOP: do not respawn, do not self-review, do not post a VERDICT of your own; leave it pending the human's decision. If it posted nothing at all, respawn once and apply this same check again to what the retry posts — an explicit refusal still means STOP; only a second true silence lets you review the task yourself as a read-only pass and post the VERDICT. Absence is never a PASS."
 
 "$API" hook-output "" "$CONTEXT" "PostToolUse"

package/.next/standalone/public/chorus-plugin/bin/on-post-submit-proposal.sh

@@ -48,15 +48,15 @@ Max review rounds: ${MAX_ROUNDS} (0 = unlimited).
 ACTION REQUIRED: Spawn the \`chorus:proposal-reviewer\` agent to perform an independent quality review before admin approval.
 
 Example:
-  Agent({ subagent_type: \"chorus:proposal-reviewer\", prompt: \"Review proposal ${PROPOSAL_UUID}. Max review rounds: ${MAX_ROUNDS}. First, read existing comments to count previous VERDICTs and determine your round number. If max > 0 and your round exceeds max, skip the review and post a comment saying the limit was reached — human decision needed. Otherwise, proceed with review. Post your VERDICT as a comment on the proposal.\" })
+  Agent({ subagent_type: \"chorus:proposal-reviewer\", prompt: \"Review proposal ${PROPOSAL_UUID}. Max review rounds: ${MAX_ROUNDS}. First, read existing comments to count previous VERDICTs and determine your round number. If max > 0 and your round exceeds max, skip the review and post a comment saying the round limit was reached and a human decision is needed, and post no VERDICT (this tells the main agent to stop rather than substitute its own verdict). Otherwise, proceed with review. Post your VERDICT as a comment on the proposal.\" })
 
 The reviewer is read-only and will post its VERDICT as a comment on the proposal.
 
-After the reviewer completes, read comments and find the most recent \`VERDICT:\` line:
+Wait for the reviewer to complete (its completion notification), then read this round's \`VERDICT:\` comment with chorus_get_comments — on THIS proposal, posted after you dispatched the reviewer. Do not settle for an older VERDICT from a previous round:
 - **VERDICT: PASS** — No issues found. Proceed to approve (chorus_admin_approve_proposal).
 - **VERDICT: PASS WITH NOTES** — Minor non-blocking notes. Still proceed to approve.
 - **VERDICT: FAIL** — BLOCKERs found. Do NOT approve. Reject the proposal (chorus_pm_reject_proposal), fix BLOCKERs, and resubmit.
 
-IMPORTANT: Run the reviewer synchronously (do NOT set run_in_background). Wait for its VERDICT before proceeding."
+IMPORTANT: the launch result is not the verdict — these reviewer subagent types report an async launch regardless of the flag you pass. Do NOT approve or reject before you have read this round's VERDICT comment. If it is missing, check what the reviewer did post: a comment reporting the round limit was reached, or any other explicit refusal to review, is a deliberate escalation — STOP: do not respawn, do not self-review, do not post a VERDICT of your own; leave it pending the human's decision. If it posted nothing at all, respawn once and apply this same check again to what the retry posts — an explicit refusal still means STOP; only a second true silence lets you review the proposal yourself as a read-only pass and post the VERDICT. Absence is never a PASS."
 
 "$API" hook-output "" "$CONTEXT" "PostToolUse"

package/.next/standalone/public/chorus-plugin/bin/on-post-verify-task.sh

@@ -317,8 +317,8 @@ All tasks of idea-rooted proposal ${PROPOSAL_UUID} are now done. This is the fin
 
 ACTION REQUESTED: spawn code-reviewer for this idea — an independent, read-only review of the idea's AGGREGATE code change (the whole feature across all its tasks), not a single task.
 
-1. Spawn the code-reviewer in FOREGROUND, passing it ideaUuid="${idea_uuid}" and the review round number (read prior code-review verdict comments on the idea to determine it). It reviews cross-task integration, architecture/convention consistency, security, regression/performance, feature-level test coverage, and overall code soundness, then posts ONE VERDICT comment on the idea.
-2. Read its VERDICT on the idea (chorus_get_comments targetType="idea").
+1. Spawn the code-reviewer and wait for its completion notification, passing it ideaUuid="${idea_uuid}" and the review round number (read prior code-review verdict comments on the idea to determine it). It reviews cross-task integration, architecture/convention consistency, security, regression/performance, feature-level test coverage, and overall code soundness, then posts ONE VERDICT comment on the idea.
+2. Read THIS round's VERDICT on the idea (chorus_get_comments targetType="idea") — the comment posted after your dispatch, not an earlier round's. The launch result is not the verdict; do not declare the feature shippable before you have read that comment. If it is missing, check what the reviewer did post: a comment reporting the round limit was reached, or any other explicit refusal to review, is a deliberate escalation — STOP: do not respawn, do not self-review, do not post a VERDICT of your own; leave it pending the human's decision. If it posted nothing at all, respawn once and apply this same check again to what the retry posts — an explicit refusal still means STOP; only a second true silence lets you review the idea's aggregate change yourself as a read-only pass and post the VERDICT. Absence is never a PASS.
 3. PASS / PASS WITH NOTES -> the feature may ship.
 4. FAIL -> the orchestrator invokes Quick Dev to create new tasks on the original approved proposal; never reopen completed tasks or apply untracked fixes. Group related small BLOCKERs by default and split only materially large or independently testable fixes.
 5. Re-run only after every fix task passes AC self-check, independent task review, and admin verification to done. A failed or cancelled fix stops the loop and escalates. Keep maxCodeReviewRounds authoritative.

package/.next/standalone/public/chorus-plugin/bin/on-session-start.sh

@@ -67,45 +67,17 @@ if command -v jq >/dev/null 2>&1; then
 
 fi
 
-# Detect OpenSpec mode for this repo, once per session.
-# Both conditions are required for OpenSpec mode to be usable:
-#   (a) an openspec/ directory at the project root (this repo was inited via `openspec init`), AND
-#   (b) the `openspec` CLI on PATH (so we can `openspec new change`, `validate`, `archive`).
-# Overrides (precedence high -> low, first match wins):
-#   1. enableOpenSpec userConfig toggle (default true) — UI-level switch.
-#   2. CHORUS_OPENSPEC_MODE=off env var — env-level explicit opt-out.
-# When the folder is present but the CLI is missing, surface that as a
-# specific reason so the user-visible toast can hint at the install step
-# instead of silently falling back.
+# Resolve the active spec mode for this repo, once per session. The resolution
+# logic lives in resolve-spec-mode.sh (pure: env + filesystem only) so it can be
+# unit-tested — see bin/tests/test-spec-mode-resolution.sh. It sets SPEC_MODE,
+# SPEC_REASON, SPEC_FAIL, OPENSPEC_USABLE_REASON, OPENSPEC_HINT, CHORUS_OPENSPEC_ACTIVE.
 #
-# The inactive states split into two user-facing kinds:
-#   - OPENSPEC_OPTOUT=1 — the user explicitly turned OpenSpec off (plugin
-#     toggle or env var). Respect it: show a neutral note, no nag.
-#   - OPENSPEC_OPTOUT=0 — OpenSpec is simply not set up (no folder, or folder
-#     without the CLI). Point the user at `/chorus enable openspec`, which walks
-#     the actual install/init steps — the banner stays a one-liner.
+# Summary: an explicit CHORUS_SPEC_MODE (lite|openspec|off) 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.
+# Legacy CHORUS_OPENSPEC_MODE=off still forces not-openspec (→ lite when unset).
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
-OPENSPEC_HINT=""
-OPENSPEC_OPTOUT=0
-if [ "${CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC:-true}" != "true" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-  OPENSPEC_OPTOUT=1
-  OPENSPEC_REASON="enableOpenSpec userConfig=false (plugin-level opt-out)"
-elif [ "${CHORUS_OPENSPEC_MODE:-}" = "off" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-  OPENSPEC_OPTOUT=1
-  OPENSPEC_REASON="CHORUS_OPENSPEC_MODE=off (explicit opt-out)"
-elif [ ! -d "${PROJECT_ROOT}/openspec" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-  OPENSPEC_REASON="no openspec/ directory at ${PROJECT_ROOT}/openspec"
-elif ! command -v openspec >/dev/null 2>&1; then
-  CHORUS_OPENSPEC_ACTIVE=0
-  OPENSPEC_REASON="openspec/ directory present but \`openspec\` CLI not on PATH"
-  OPENSPEC_HINT="install with: npm i -g @fission-ai/openspec"
-else
-  CHORUS_OPENSPEC_ACTIVE=1
-  OPENSPEC_REASON="openspec/ directory + openspec CLI both present"
-fi
+. "${SCRIPT_DIR}/resolve-spec-mode.sh"
 
 # Build context for Claude (additionalContext)
 CONTEXT="# Chorus Plugin — Active
@@ -116,33 +88,33 @@ Chorus is connected at ${CHORUS_URL}. Session lifecycle hooks are enabled.
 
 ${CHECKIN_RESULT}
 
-## OpenSpec Mode
+## Spec Mode
 
-CHORUS_OPENSPEC_ACTIVE=${CHORUS_OPENSPEC_ACTIVE} (${OPENSPEC_REASON})"
+CHORUS_SPEC_MODE=${SPEC_MODE} (${SPEC_REASON})"
 
-if [ "$CHORUS_OPENSPEC_ACTIVE" = "1" ]; then
+if [ "$SPEC_MODE" = "lite" ]; then
   CONTEXT="${CONTEXT}
 
-OpenSpec mode is **active** for this session. When the proposal / develop / yolo skills reach an OpenSpec-aware step, load the openspec-aware skill at \`.claude/skills/openspec-aware/SKILL.md\` and follow §3 (OpenSpec authoring) — do NOT re-run the §1 detection block, the answer is already known.
+Routing: lite → follow the spec-lite skill (\`skills/spec-lite/SKILL.md\`). Author a Chorus-native change folder \`.chorus/specs/<slug>/\` (\`prd.md\` required; \`tech_design.md\` / \`adr.md\` / \`spec.md\` / \`guide.md\` optional) and mirror each \`<type>.md\` 1:1 into a Chorus Document of that type via \`chorus mcp call … --arg-file content=<file>\`. Do NOT scaffold \`openspec/changes/\` or add an \`OpenSpec change slug:\` line."
+elif [ "$SPEC_MODE" = "off" ]; then
+  CONTEXT="${CONTEXT}
 
-Critical 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-api.sh mcp-tool\` with \`json_encode_file\` when \`chorus\` is not on PATH. Do NOT invoke these MCP tools directly with hand-typed \`content\` in OpenSpec mode."
-else
+Routing: off → free-form, no spec artifact. Do NOT create \`.chorus/specs/\` or \`openspec/changes/\` files; author document drafts inline via direct MCP."
+elif [ -n "$SPEC_FAIL" ]; then
   CONTEXT="${CONTEXT}
 
-OpenSpec mode is **inactive** for this session. The proposal / develop / yolo skills follow their free-form path; do NOT scaffold \`openspec/changes/\`, do NOT add an \`OpenSpec change slug:\` line to proposal descriptions, and do NOT route document mirror calls through the \`chorus\` CLI or \`chorus-api.sh\`."
-  if [ "$OPENSPEC_OPTOUT" = "1" ]; then
-    CONTEXT="${CONTEXT}
+Routing: openspec → **cannot be honored** — ${SPEC_FAIL}. The proposal / yolo skill MUST halt after resolving the mode; do NOT silently fall back to lite/free-form. Surface this to the user."
+  if [ -n "$OPENSPEC_HINT" ]; then
+    CONTEXT="${CONTEXT} Install hint: ${OPENSPEC_HINT}."
+  fi
+else
+  CONTEXT="${CONTEXT}
 
-OpenSpec was **explicitly turned off** (${OPENSPEC_REASON}), so this is a deliberate choice — do NOT nag the user to enable it. If they ask to turn it back on, point them at re-enabling the plugin's \`enableOpenSpec\` toggle / unsetting \`CHORUS_OPENSPEC_MODE\`, then the OpenSpec setup section in the \`/chorus\` skill."
-  elif [ -n "$OPENSPEC_HINT" ]; then
-    CONTEXT="${CONTEXT}
+CHORUS_OPENSPEC_ACTIVE=1 (${OPENSPEC_USABLE_REASON})
 
-Note: this repo has an \`openspec/\` directory, so the user likely intends to use OpenSpec mode but the \`openspec\` CLI is not installed. Surface this to the user (e.g. \"This repo is OpenSpec-init'd but the \\\`openspec\\\` CLI isn't installed locally — ${OPENSPEC_HINT}\") before authoring documents. To set it up, run \`/chorus enable openspec\` (§6 walks the install + re-launch)."
-  else
-    CONTEXT="${CONTEXT}
+Routing: openspec → load the openspec-aware skill at \`.claude/skills/openspec-aware/SKILL.md\` and follow §3 (OpenSpec authoring) — do NOT re-run the §1 detection block, the answer is already known.
 
-Note: OpenSpec is not set up in this repo (${OPENSPEC_REASON}). Spec-driven authoring is optional — free-form works fine. If the user wants spec-driven mode (proposal.md / design.md / spec deltas mirrored into Chorus), run \`/chorus enable openspec\` — §6 walks the \`npm i -g @fission-ai/openspec\` + \`openspec init\` steps and the re-launch."
-  fi
+Critical 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-api.sh mcp-tool\` with \`json_encode_file\` when \`chorus\` is not on PATH. Do NOT invoke these MCP tools directly with hand-typed \`content\` in OpenSpec mode."
 fi
 
 CONTEXT="${CONTEXT}
@@ -164,18 +136,21 @@ Resuming with existing Chorus session: ${MAIN_SESSION}"
   "$API" mcp-tool "chorus_session_heartbeat" "$(printf '{"sessionUuid":"%s"}' "$MAIN_SESSION")" >/dev/null 2>&1 || true
 fi
 
-# Build user-visible message. When OpenSpec is off-but-enable-able, point the
-# user at `/chorus enable openspec` — the skill walks the actual install/init.
-#   active            -> (OpenSpec Enabled)
-#   not set up        -> (OpenSpec off — run `/chorus enable openspec` to set it up)
-#   explicit opt-out  -> (OpenSpec off)  [neutral, no nag — respects the choice]
+# Build user-visible message. Always states the active spec mode (lite is the
+# default); an explicit openspec that can't be honored is flagged as not usable.
+#   lite              -> (Spec: lite)
+#   off               -> (Spec: off)
+#   openspec (usable) -> (Spec: openspec)
+#   openspec (broken) -> (Spec: openspec — not usable)
 USER_MSG="Chorus connected at ${CHORUS_URL}"
-if [ "$CHORUS_OPENSPEC_ACTIVE" = "1" ]; then
-  USER_MSG="${USER_MSG} (OpenSpec Enabled)"
-elif [ "$OPENSPEC_OPTOUT" = "1" ]; then
-  USER_MSG="${USER_MSG} (OpenSpec off)"
+if [ "$SPEC_MODE" = "lite" ]; then
+  USER_MSG="${USER_MSG} (Spec: lite)"
+elif [ "$SPEC_MODE" = "off" ]; then
+  USER_MSG="${USER_MSG} (Spec: off)"
+elif [ -n "$SPEC_FAIL" ]; then
+  USER_MSG="${USER_MSG} (Spec: openspec — not usable)"
 else
-  USER_MSG="${USER_MSG} (OpenSpec off — run \`/chorus enable openspec\` to set it up)"
+  USER_MSG="${USER_MSG} (Spec: openspec)"
 fi
 if [ -n "$MAIN_SESSION" ]; then
   USER_MSG="${USER_MSG} (resumed session)"

package/.next/standalone/public/chorus-plugin/bin/resolve-spec-mode.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# resolve-spec-mode.sh — resolve the active Chorus spec mode for a repo.
+#
+# Pure (env + filesystem only; no network). Sourced by on-session-start.sh and
+# driven directly by tests/test-spec-mode-resolution.sh. Bash 3.2 compatible.
+#
+# Inputs (env):
+#   CHORUS_SPEC_MODE                    explicit override: lite | openspec | off (else unset)
+#   CHORUS_OPENSPEC_MODE                legacy opt-out: "off" disables OpenSpec
+#   CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC plugin toggle: "false" disables OpenSpec (default "true")
+#   PROJECT_ROOT                        repo root to probe for openspec/ (defaults to $PWD)
+#   command -v openspec                 OpenSpec CLI presence on PATH
+#
+# Outputs (vars set in the caller's shell when sourced):
+#   SPEC_MODE              lite | openspec | off      (value surfaced to Claude)
+#   SPEC_REASON            human-readable one-liner
+#   SPEC_FAIL              non-empty => stage skill MUST halt (unsatisfiable explicit openspec)
+#   OPENSPEC_USABLE        1 | 0
+#   OPENSPEC_USABLE_REASON human-readable
+#   OPENSPEC_HINT          install hint when OpenSpec is merely missing (else empty)
+#   CHORUS_OPENSPEC_ACTIVE 1 only when the resolved mode is a USABLE openspec
+#
+# Resolution (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.
+
+: "${PROJECT_ROOT:=$PWD}"
+
+# --- Is OpenSpec usable? (needs openspec/ dir + CLI on PATH + not disabled) ---
+OPENSPEC_DISABLED=0
+OPENSPEC_DISABLED_REASON=""
+if [ "${CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC:-true}" != "true" ]; then
+  OPENSPEC_DISABLED=1
+  OPENSPEC_DISABLED_REASON="enableOpenSpec userConfig=false (plugin-level opt-out)"
+elif [ "${CHORUS_OPENSPEC_MODE:-}" = "off" ]; then
+  OPENSPEC_DISABLED=1
+  OPENSPEC_DISABLED_REASON="CHORUS_OPENSPEC_MODE=off (legacy opt-out)"
+fi
+
+OPENSPEC_USABLE=0
+OPENSPEC_USABLE_REASON=""
+OPENSPEC_HINT=""
+if [ "$OPENSPEC_DISABLED" = "1" ]; then
+  OPENSPEC_USABLE_REASON="$OPENSPEC_DISABLED_REASON"
+elif [ ! -d "${PROJECT_ROOT}/openspec" ]; then
+  OPENSPEC_USABLE_REASON="no openspec/ directory at ${PROJECT_ROOT}/openspec"
+  OPENSPEC_HINT="npm i -g @fission-ai/openspec && openspec init"
+elif ! command -v openspec >/dev/null 2>&1; then
+  OPENSPEC_USABLE_REASON="openspec/ directory present but \`openspec\` CLI not on PATH"
+  OPENSPEC_HINT="npm i -g @fission-ai/openspec"
+else
+  OPENSPEC_USABLE=1
+  OPENSPEC_USABLE_REASON="openspec/ directory + openspec CLI both present"
+fi
+
+# --- Resolve CHORUS_SPEC_MODE ---
+SPEC_FAIL=""
+case "${CHORUS_SPEC_MODE:-}" in
+  lite)
+    SPEC_MODE="lite"
+    SPEC_REASON="explicit — Chorus-native lightweight specs in .chorus/specs/<slug>/"
+    ;;
+  off)
+    SPEC_MODE="off"
+    SPEC_REASON="explicit — free-form, no spec artifact"
+    ;;
+  openspec)
+    SPEC_MODE="openspec"
+    if [ "$OPENSPEC_USABLE" = "1" ]; then
+      SPEC_REASON="explicit; ${OPENSPEC_USABLE_REASON}"
+    elif [ "$OPENSPEC_DISABLED" = "1" ]; then
+      SPEC_REASON="explicit, but OpenSpec is disabled: ${OPENSPEC_USABLE_REASON}"
+      SPEC_FAIL="config conflict — CHORUS_SPEC_MODE=openspec vs OpenSpec disabled (${OPENSPEC_USABLE_REASON}); re-enable OpenSpec or set CHORUS_SPEC_MODE=lite"
+    else
+      SPEC_REASON="explicit, but OpenSpec is not installed: ${OPENSPEC_USABLE_REASON}"
+      SPEC_FAIL="OpenSpec not usable (${OPENSPEC_USABLE_REASON})"
+    fi
+    ;;
+  "")
+    # Unset: OpenSpec is the default when usable; lite is the fallback otherwise.
+    if [ "$OPENSPEC_USABLE" = "1" ]; then
+      SPEC_MODE="openspec"
+      SPEC_REASON="default — ${OPENSPEC_USABLE_REASON}; set CHORUS_SPEC_MODE=lite for Chorus-native specs, =off to disable"
+    else
+      SPEC_MODE="lite"
+      SPEC_REASON="default — OpenSpec not usable (${OPENSPEC_USABLE_REASON}); using Chorus-native lightweight specs in .chorus/specs/<slug>/"
+    fi
+    ;;
+  *)
+    # Unrecognized value: treat like unset (OpenSpec-if-usable, else lite).
+    if [ "$OPENSPEC_USABLE" = "1" ]; then
+      SPEC_MODE="openspec"
+      SPEC_REASON="CHORUS_SPEC_MODE='${CHORUS_SPEC_MODE}' unrecognized; falling back to default (${OPENSPEC_USABLE_REASON})"
+    else
+      SPEC_MODE="lite"
+      SPEC_REASON="CHORUS_SPEC_MODE='${CHORUS_SPEC_MODE}' unrecognized; OpenSpec not usable, defaulting to lite"
+    fi
+    ;;
+esac
+
+# Back-compat flag for the openspec-aware skill: active only when the resolved
+# mode is a USABLE openspec.
+if [ "$SPEC_MODE" = "openspec" ] && [ -z "$SPEC_FAIL" ]; then
+  CHORUS_OPENSPEC_ACTIVE=1
+else
+  CHORUS_OPENSPEC_ACTIVE=0
+fi

package/.next/standalone/public/chorus-plugin/bin/tests/test-resolver-drift.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# test-resolver-drift.sh — enforce the single-source invariant for the bash
+# spec-mode resolver. resolve-spec-mode.sh is COPIED into each bash plugin port
+# (Claude Code, Codex, Kiro, …); those copies MUST stay byte-identical to the
+# canonical Claude Code copy, or the "one computation of the mode" guarantee
+# silently rots as ports diverge. The 13-case matrix test covers the canonical
+# copy; this guard makes every other copy equal to it. Bash 3.2 compatible.
+set -u
+
+# Repo root = four levels up from this script (tests → bin → chorus-plugin → public → repo).
+ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
+CANON="$ROOT/public/chorus-plugin/bin/resolve-spec-mode.sh"
+
+if [ ! -f "$CANON" ]; then
+  echo "FATAL: canonical resolver not found at $CANON" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+echo "resolver drift-guard (canonical: public/chorus-plugin/bin/resolve-spec-mode.sh):"
+
+# Every bash copy under public/, plugins/ or packages/ (excludes node_modules /
+# build output). packages/ is included because the OpenClaw plugin — which has no
+# SessionStart channel and so resolves the mode from its skill — SHIPS this
+# resolver rather than hand-rolling the rule in Markdown.
+COPIES=$(find "$ROOT/public" "$ROOT/plugins" "$ROOT/packages" -name resolve-spec-mode.sh 2>/dev/null \
+  | grep -v '/node_modules/' | grep -v '/dist/' | sort)
+
+for f in $COPIES; do
+  rel="${f#$ROOT/}"
+  if [ "$f" = "$CANON" ]; then
+    echo "  --    $rel (canonical)"
+    continue
+  fi
+  if diff -q "$CANON" "$f" >/dev/null 2>&1; then
+    PASS=$((PASS + 1)); echo "  PASS  $rel (byte-identical)"
+  else
+    FAIL=$((FAIL + 1)); echo "  FAIL  $rel DIFFERS from canonical:"
+    diff "$CANON" "$f" | sed 's/^/        /'
+  fi
+done
+
+echo ""
+echo "Results: $PASS identical copy(ies), $FAIL drifted"
+[ "$FAIL" -eq 0 ]