@chorus-aidlc/chorus 0.17.3 → 0.18.0

package/.next/standalone/public/chorus-plugin/bin/tests/test-skill-harness-fidelity.sh

@@ -0,0 +1,372 @@
+#!/usr/bin/env bash
+# test-skill-harness-fidelity.sh — keep shipped skill/manifest/hook text from
+# re-asserting claims that are false about the harnesses we ship to:
+#
+#   1. `TeamCreate` — a tool no harness in this repo exposes.
+#   2. Five literal phrases promising a reviewer runs in the foreground / returns
+#      its VERDICT inline, on the surfaces where that is untrue.
+#   3. `.chorus/specs/TEMPLATE` — a path that exists nowhere on disk.
+#   4. A proposal-reviewer definition — or the Kiro orchestrator/steering prose that
+#      DESCRIBES the reviewers' tool grants — claiming the shell/Bash is unavailable:
+#      false on all seven surfaces, and the claim that produced the "file is
+#      missing" false positive this guard's check 4-6 exist to prevent.
+#   5. A proposal-reviewer definition that does NOT carry the canonical read-only
+#      shell rule (allowed commands + the confirm-before-flagging obligation).
+#   6. Tool grants contradicting that rule: `Bash` back in the Claude Code agent's
+#      `disallowedTools`, or `shell` dropped from Kiro's `tools`.
+#
+# SCOPE — read this before extending the guard. Checks 1-3 are a string blacklist,
+# nothing more. They do NOT verify that the reviewer-wait contract or the
+# round-qualified "read THIS round's VERDICT" instruction is present, correct, or
+# even still in the file: deleting those paragraphs outright leaves all three checks
+# green. That gate is held by review and by the acceptance criteria of the changes
+# that write those paragraphs, not here. It also does NOT check that the spec-lite
+# templates are inlined anywhere — deliberately, by owner decision.
+#
+# Checks 4-6 go one step further for the proposal-reviewer only (4 also covers the
+# two Kiro docs that describe its grant to the orchestrator): 4 is a blacklist,
+# but 5 REQUIRES two marker substrings and 6 inspects the two manifests that
+# actually gate the capability. They still do not verify the full three-sentence
+# wording — a surface could keep both markers while mangling the forbidden list.
+#
+# 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)"
+# This guard and its negative-case harness both have to spell every blacklisted
+# literal out in order to forbid / plant it, so both are excluded from their own
+# scans. Nothing else is exempt — a violation hidden in these two files would go
+# unseen, which is the same tradeoff every self-excluding linter makes.
+SELF_REL="public/chorus-plugin/bin/tests/test-skill-harness-fidelity.sh"
+SELF_REL2="public/chorus-plugin/bin/tests/test-skill-harness-fidelity-negative.sh"
+
+if [ ! -d "$ROOT/public/chorus-plugin" ]; then
+  echo "FATAL: repo root looks wrong (no public/chorus-plugin under $ROOT)" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+
+# --exclude-dir matches a directory BASENAME, not a path, so `worktrees` covers
+# `.claude/worktrees/` (and any other worktrees dir) — intentionally broader.
+EXCLUDES="--exclude-dir=node_modules --exclude-dir=dist --exclude-dir=cdk.out --exclude-dir=worktrees --exclude-dir=.git"
+
+# Scan-error flag. This is a FILE, not a shell variable, on purpose: every call
+# site invokes hits() inside `$( )`, which runs it in a subshell — a variable
+# assignment there is discarded when the substitution ends, so the guard would
+# print the error and still exit 0. A file survives the subshell.
+SCAN_ERR_FILE="$(mktemp)"
+trap 'rm -f "$SCAN_ERR_FILE"' EXIT
+
+# hits <literal> <path>... — print repo-relative files containing the literal,
+# minus this guard's own source (it necessarily spells every pattern out).
+#
+# A grep that cannot scan is NOT a pass. grep exits 0 on match, 1 on no match and
+# >=2 on error (unreadable path, missing directory, a path mangled by word
+# splitting). Swallowing stderr and treating >=2 like "no match" is how a guard
+# reports PASS while having searched nothing — so the rc is inspected and recorded
+# in SCAN_ERR_FILE, which fails the run at the end. Every call site must pass each
+# path as its own quoted argument for the same reason.
+hits() {
+  local _lit _out _rc _err
+  _lit="$1"; shift
+  _err="$(mktemp)"
+  # shellcheck disable=SC2086
+  _out="$(grep -rlIF $EXCLUDES -- "$_lit" "$@" 2>"$_err")"
+  _rc=$?
+  if [ "$_rc" -ge 2 ]; then
+    echo "$_lit" >> "$SCAN_ERR_FILE"
+    echo "  ERROR scan failed for \"$_lit\" (grep rc=$_rc) — a failed scan is not a PASS:" >&2
+    sed 's/^/          /' "$_err" >&2
+  fi
+  rm -f "$_err"
+  [ -n "$_out" ] || return 0
+  printf '%s\n' "$_out" \
+    | sed "s|^$ROOT/||" \
+    | grep -v "^$SELF_REL\$" \
+    | grep -v "^$SELF_REL2\$" \
+    | sort
+}
+
+# file_has <literal> <abs-path> — rc 0 when the file contains the literal, rc 1
+# when it does not, rc>=2 when grep could not scan (missing/unreadable file).
+#
+# Unlike hits(), this is called DIRECTLY in an `if`, never inside `$( )`: a scan
+# error has to be recorded for the parent shell, and an assignment made inside a
+# command substitution is discarded when it ends. SCAN_ERR_FILE is a file for the
+# same reason (see above) and works either way; the `if` form also keeps the rc
+# distinction between "absent" (1) and "could not look" (>=2), which matters here
+# because checks 5-6 REQUIRE a substring — an unreadable file would otherwise be
+# indistinguishable from a file that legitimately lacks it.
+file_has() {
+  local _lit _path _rc _err
+  _lit="$1"; _path="$2"
+  _err="$(mktemp)"
+  grep -qIF -- "$_lit" "$_path" 2>"$_err"
+  _rc=$?
+  if [ "$_rc" -ge 2 ]; then
+    echo "$_lit @ $_path" >> "$SCAN_ERR_FILE"
+    echo "  ERROR scan failed for \"$_lit\" in $_path (grep rc=$_rc) — a failed scan is not a PASS:" >&2
+    sed 's/^/          /' "$_err" >&2
+  fi
+  rm -f "$_err"
+  return "$_rc"
+}
+
+report() {
+  local _label _found
+  _label="$1"; _found="$2"
+  if [ -z "$_found" ]; then
+    PASS=$((PASS + 1)); echo "  PASS  $_label"
+  else
+    FAIL=$((FAIL + 1)); echo "  FAIL  $_label — found in:"
+    echo "$_found" | sed 's/^/          /'
+  fi
+}
+
+echo "skill/harness fidelity guard (checks 1-4 blacklist, 5-6 require — see header for what it does NOT cover):"
+echo ""
+
+# ── Check 1 — no TeamCreate anywhere in shipped files ────────────────────────
+# packages/chorus-pi/test/{static.sh,README.md} name it in order to forbid it.
+echo "Check 1 — no \`TeamCreate\` (no harness in this repo exposes it)"
+FOUND=$(hits 'TeamCreate' "$ROOT/public" "$ROOT/plugins" "$ROOT/packages" \
+  | grep -v '^packages/chorus-pi/test/static\.sh$' \
+  | grep -v '^packages/chorus-pi/test/README\.md$')
+report "no TeamCreate reference" "$FOUND"
+echo ""
+
+# ── Check 2 — no foreground / inline-VERDICT reviewer promise ────────────────
+# Scoped to the surfaces where the promise is false: on Claude Code the sub-agent
+# launch result is never the verdict, and Kiro/dsh word their waiting differently.
+# packages/chorus-pi/ is EXCLUDED on purpose — its bundled `subagent` genuinely
+# blocks and returns the VERDICT, so its skill says so truthfully.
+# Literal phrases only. Do NOT add a proximity rule pairing `run_in_background`
+# with "foreground"/"synchronous"/"inline": dsh legitimately keeps
+# `run_in_background: false`, so such a rule would fail a correct tree.
+echo "Check 2 — no foreground/inline-VERDICT reviewer promise (chorus-plugin, kiro-plugin, chorus-dsh)"
+# Three separate quoted arguments, NOT one space-joined string: a repo checked out
+# under a path containing a space (e.g. /Users/me/My Repos/Chorus) would have that
+# string word-split into non-existent paths, grep would error, and the guard would
+# have reported PASS having scanned nothing. Bash 3.2 has indexed arrays (only
+# associative ones are 4+), so an array is fine here.
+SCOPE2=("$ROOT/public/chorus-plugin" "$ROOT/public/kiro-plugin" "$ROOT/packages/chorus-dsh")
+CHECK2_FAILED=0
+# Bash 3.2: no arrays / no readarray — one literal per line, split on newlines.
+PATTERNS_2='reviewer synchronously
+returns the VERDICT inline
+waits and returns the VERDICT
+in **foreground**
+(do NOT set run_in_background)'
+OLD_IFS="$IFS"
+IFS='
+'
+for pat in $PATTERNS_2; do
+  IFS="$OLD_IFS"
+  FOUND=$(hits "$pat" "${SCOPE2[@]}")
+  if [ -n "$FOUND" ]; then
+    CHECK2_FAILED=1
+    echo "  FAIL  literal \"$pat\" — found in:"
+    echo "$FOUND" | sed 's/^/          /'
+  fi
+  IFS='
+'
+done
+IFS="$OLD_IFS"
+if [ "$CHECK2_FAILED" -eq 0 ]; then
+  PASS=$((PASS + 1)); echo "  PASS  none of the 5 blacklisted literals present"
+else
+  FAIL=$((FAIL + 1))
+fi
+echo ""
+
+# ── Check 3 — no dangling .chorus/specs/TEMPLATE path ───────────────────────
+echo "Check 3 — no \`.chorus/specs/TEMPLATE\` path (no such directory is shipped)"
+FOUND=$(hits '.chorus/specs/TEMPLATE' "$ROOT/public" "$ROOT/plugins" "$ROOT/packages" "$ROOT/docs/SPEC_LITE.md")
+report "no .chorus/specs/TEMPLATE reference" "$FOUND"
+echo ""
+
+# ── The seven proposal-reviewer definitions ─────────────────────────────────
+# Enumerated explicitly and NOT globbed, on purpose: shipping an eighth surface
+# without adding it here is then a visible omission in this list rather than a
+# silent pass by a glob that never saw the new file. A path listed here but absent
+# on disk is a FAILURE, never a skip.
+#
+# Checks 4-6 are file-scoped, so this script spelling its own literals out cannot
+# self-match the way checks 1-3 could — no SELF_REL exemption is needed or wanted.
+PR_FILES='public/chorus-plugin/agents/proposal-reviewer.md
+plugins/chorus/skills/chorus-proposal-reviewer/SKILL.md
+public/kiro-plugin/.kiro/agents/chorus-proposal-reviewer.json
+packages/chorus-pi/agents/chorus-proposal-reviewer.md
+packages/chorus-dsh/skills/proposal-reviewer-chorus/SKILL.md
+packages/openclaw-plugin/skills/proposal-reviewer/SKILL.md
+public/skill/proposal-reviewer-chorus/SKILL.md'
+
+# ── Files in check 4's scope ONLY ────────────────────────────────────────────
+# The Kiro orchestrator's own prompt and the Kiro steering doc are not reviewer
+# definitions — they DESCRIBE the reviewers' tool grants to the main agent that
+# spawns them. A false "the reviewer has no shell" claim here misleads the
+# orchestrator just as badly as one in the reviewer's own file, so they belong in
+# the blacklist check. They must NOT be added to PR_FILES: check 5 requires the
+# canonical rule verbatim, which is a reviewer-definition obligation, and check 6
+# reads manifests neither of these files is.
+# Same contract as PR_FILES: enumerated, not globbed, and a missing path FAILS.
+CHECK4_EXTRA_FILES='public/kiro-plugin/.kiro/agents/chorus.md
+public/kiro-plugin/.kiro/steering/chorus.md'
+
+# ── Check 4 — no surface claims the reviewer's shell is unavailable ──────────
+# These are the exact assertions the seven files carried before the fix. Each is
+# long enough to be unambiguous: the truthful prose every surface DOES keep —
+# "Any shell command beyond read-only inspection — no file writes …" — must not
+# match, so no bare "shell"/"Bash" substring appears in this list.
+echo "Check 4 — no proposal-reviewer surface (or Kiro orchestrator/steering doc) claims shell/Bash is unavailable"
+PATTERNS_SHELL_DISABLED='Bash is disabled
+no `shell`
+cannot run shell
+Do NOT run Bash
+or run Bash commands
+Running any shell commands'
+CHECK4_FAILED=0
+CHECK4_FILES=0
+while IFS= read -r _rel; do
+  [ -n "$_rel" ] || continue
+  CHECK4_FILES=$((CHECK4_FILES + 1))
+  _abs="$ROOT/$_rel"
+  if [ ! -f "$_abs" ]; then
+    CHECK4_FAILED=1
+    echo "  FAIL  enumerated surface MISSING (not skipped): $_rel"
+    continue
+  fi
+  while IFS= read -r _pat; do
+    [ -n "$_pat" ] || continue
+    if file_has "$_pat" "$_abs"; then
+      CHECK4_FAILED=1
+      echo "  FAIL  shell-disabled claim \"$_pat\" — found in:"
+      echo "          $_rel"
+    fi
+  done <<PATS4
+$PATTERNS_SHELL_DISABLED
+PATS4
+done <<FILES4
+$PR_FILES
+$CHECK4_EXTRA_FILES
+FILES4
+if [ "$CHECK4_FAILED" -eq 0 ]; then
+  PASS=$((PASS + 1))
+  echo "  PASS  none of the 6 shell-disabled literals present in $CHECK4_FILES enumerated files"
+else
+  FAIL=$((FAIL + 1))
+fi
+echo ""
+
+# ── Check 5 — every surface carries the canonical read-only shell rule ───────
+# Two markers, both required:
+#   * "READ-ONLY inspection only" — NOT "Bash is READ-ONLY", because Kiro's tool is
+#     named `shell` and its prompt reads "Shell is READ-ONLY inspection only".
+#   * "no installs, no test/build runs" — the forbidden list. Proposal review runs
+#     before any implementation exists, so test/build execution is out of scope here
+#     even though the task- and code-reviewer are allowed it.
+#   * "before flagging it as missing" — the existence-check obligation. Without it
+#     the capability grant alone does not stop the false positive this change fixes,
+#     since nothing obliges the reviewer to look before asserting a file is absent.
+echo "Check 5 — every proposal-reviewer surface carries the canonical read-only rule"
+CHECK5_FAILED=0
+CHECK5_FILES=0
+MARKERS_CANONICAL='READ-ONLY inspection only
+no installs, no test/build runs
+before flagging it as missing'
+while IFS= read -r _rel; do
+  [ -n "$_rel" ] || continue
+  CHECK5_FILES=$((CHECK5_FILES + 1))
+  _abs="$ROOT/$_rel"
+  if [ ! -f "$_abs" ]; then
+    CHECK5_FAILED=1
+    echo "  FAIL  enumerated surface MISSING (not skipped): $_rel"
+    continue
+  fi
+  while IFS= read -r _marker; do
+    [ -n "$_marker" ] || continue
+    if ! file_has "$_marker" "$_abs"; then
+      CHECK5_FAILED=1
+      echo "  FAIL  canonical rule marker \"$_marker\" MISSING from:"
+      echo "          $_rel"
+    fi
+  done <<MARK5
+$MARKERS_CANONICAL
+MARK5
+done <<FILES5
+$PR_FILES
+FILES5
+if [ "$CHECK5_FAILED" -eq 0 ]; then
+  PASS=$((PASS + 1))
+  echo "  PASS  all 3 canonical markers present in all $CHECK5_FILES enumerated surfaces"
+else
+  FAIL=$((FAIL + 1))
+fi
+echo ""
+
+# ── Check 6 — the two manifests that actually gate the capability ────────────
+# Prose granting read-only shell is a lie if the harness never hands the tool over.
+# Claude Code and Kiro are the only two surfaces that enforce tool access; the other
+# five have no enforcement mechanism, so there is nothing to assert about them.
+echo "Check 6 — tool grants match the rule (Claude Code \`disallowedTools\`, Kiro \`tools\`)"
+CHECK6_FAILED=0
+CC_AGENT="$ROOT/public/chorus-plugin/agents/proposal-reviewer.md"
+if [ ! -f "$CC_AGENT" ]; then
+  CHECK6_FAILED=1
+  echo "  FAIL  Claude Code agent MISSING: public/chorus-plugin/agents/proposal-reviewer.md"
+elif ! file_has 'disallowedTools:' "$CC_AGENT"; then
+  CHECK6_FAILED=1
+  echo "  FAIL  no \`disallowedTools:\` key in public/chorus-plugin/agents/proposal-reviewer.md"
+  echo "        (the guard cannot certify Bash is absent from a list it cannot find)"
+else
+  # The frontmatter list runs from `disallowedTools:` to the first line that is not
+  # a `  - item` entry. awk, not a YAML parser — this is a 6-line literal block.
+  # The key line itself is kept so YAML flow style (`disallowedTools: [Bash, Edit]`)
+  # is covered too, and the match is word-boundary rather than a whole-line `- Bash`
+  # so a quoted entry (`- "Bash"`) cannot slip through either.
+  # Blank lines and `#` comments INSIDE the list are skipped rather than treated as
+  # the end of it: YAML allows both, so exiting on one let `- Bash` placed after a
+  # comment sit in the deny list while this check reported PASS.
+  CC_BLOCK="$(awk '/^disallowedTools:/{f=1;print;next}
+                   f&&/^[[:space:]]*$/{next}
+                   f&&/^[[:space:]]*#/{next}
+                   f&&/^[[:space:]]*-[[:space:]]/{print;next} f{exit}' "$CC_AGENT")"
+  if printf '%s\n' "$CC_BLOCK" | grep -qw 'Bash'; then
+    CHECK6_FAILED=1
+    echo "  FAIL  \`- Bash\` is back in \`disallowedTools\` of:"
+    echo "          public/chorus-plugin/agents/proposal-reviewer.md"
+  fi
+fi
+KIRO_AGENT="$ROOT/public/kiro-plugin/.kiro/agents/chorus-proposal-reviewer.json"
+if [ ! -f "$KIRO_AGENT" ]; then
+  CHECK6_FAILED=1
+  echo "  FAIL  Kiro agent MISSING: public/kiro-plugin/.kiro/agents/chorus-proposal-reviewer.json"
+else
+  # From the `"tools"` key to the line closing its array.
+  KIRO_BLOCK="$(awk '/"tools"[[:space:]]*:/{f=1} f{print; if (/\]/) exit}' "$KIRO_AGENT")"
+  if ! printf '%s\n' "$KIRO_BLOCK" | grep -qF '"shell"'; then
+    CHECK6_FAILED=1
+    echo "  FAIL  \`\"shell\"\` is not in the \`tools\` array of:"
+    echo "          public/kiro-plugin/.kiro/agents/chorus-proposal-reviewer.json"
+  fi
+fi
+if [ "$CHECK6_FAILED" -eq 0 ]; then
+  PASS=$((PASS + 1))
+  echo "  PASS  Claude Code does not disallow Bash; Kiro grants \`shell\`"
+else
+  FAIL=$((FAIL + 1))
+fi
+echo ""
+
+if [ -s "$SCAN_ERR_FILE" ]; then
+  FAIL=$((FAIL + 1))
+  echo "  FAIL  at least one grep could not scan its paths — see the ERROR lines above."
+  echo "        A scan that never ran cannot certify anything; fix the paths and re-run."
+  echo ""
+fi
+
+echo "Results: $PASS check(s) passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/.next/standalone/public/chorus-plugin/bin/tests/test-spec-mode-resolution.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# test-spec-mode-resolution.sh — unit test for resolve-spec-mode.sh.
+#
+# resolve-spec-mode.sh is pure (env + filesystem only), so we drive it directly
+# in subshells across the resolution matrix: explicit CHORUS_SPEC_MODE
+# {lite, openspec, off, <invalid>} × OpenSpec {usable, missing, disabled} + unset.
+# We simulate "OpenSpec usable" with a temp PROJECT_ROOT containing an openspec/
+# dir plus a fake `openspec` on PATH; "missing" by dropping one of those; and
+# "disabled" via CHORUS_OPENSPEC_MODE=off / CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC=false.
+#
+# Owner contract: explicit mode wins; UNSET → OpenSpec when usable, else lite.
+# Bash 3.2 compatible (no associative arrays, no ${var,,}).
+set -u
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+RESOLVER="${HERE}/../resolve-spec-mode.sh"
+[ -f "$RESOLVER" ] || { echo "FATAL: resolver not found at $RESOLVER" >&2; exit 1; }
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# A repo root WITH an openspec/ dir, and one WITHOUT.
+ROOT_WITH="$TMP/with"; mkdir -p "$ROOT_WITH/openspec"
+ROOT_WITHOUT="$TMP/without"; mkdir -p "$ROOT_WITHOUT"
+
+# A fake `openspec` CLI on PATH; and a clean PATH that lacks openspec.
+FAKEBIN="$TMP/bin"; mkdir -p "$FAKEBIN"
+printf '#!/bin/sh\nexit 0\n' > "$FAKEBIN/openspec"; chmod +x "$FAKEBIN/openspec"
+CLEAN_PATH="/usr/bin:/bin"
+command -v openspec >/dev/null 2>&1 && [ -x "$(command -v openspec)" ] # informational only
+# Sanity: ensure the clean PATH really lacks openspec, else the "missing CLI"
+# cases would be invalid on this machine.
+if PATH="$CLEAN_PATH" command -v openspec >/dev/null 2>&1; then
+  echo "FATAL: openspec is on the clean PATH ($CLEAN_PATH); cannot simulate missing CLI" >&2
+  exit 1
+fi
+PATH_WITH_CLI="$FAKEBIN:$CLEAN_PATH"
+
+PASS=0; FAIL=0
+
+# run <label> <expect_mode> <expect_active> <expect_fail:ok|fail> -- env assignments...
+run() {
+  label="$1"; exp_mode="$2"; exp_active="$3"; exp_fail="$4"; shift 4
+  [ "$1" = "--" ] && shift
+  out="$(env -i HOME="$HOME" "$@" bash -c '
+    . "'"$RESOLVER"'" >/dev/null 2>&1
+    if [ -n "${SPEC_FAIL:-}" ]; then f=fail; else f=ok; fi
+    printf "%s|%s|%s" "${SPEC_MODE:-}" "${CHORUS_OPENSPEC_ACTIVE:-}" "$f"
+  ')"
+  want="${exp_mode}|${exp_active}|${exp_fail}"
+  if [ "$out" = "$want" ]; then
+    PASS=$((PASS+1)); printf '  PASS  %s\n' "$label"
+  else
+    FAIL=$((FAIL+1)); printf '  FAIL  %s\n        want [%s] got [%s]\n' "$label" "$want" "$out"
+  fi
+}
+
+echo "spec-mode resolution matrix:"
+
+# --- unset ---
+run "unset + usable → openspec"          openspec 1 ok -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITH"
+run "unset + no openspec dir → lite"     lite 0 ok     -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITHOUT"
+run "unset + dir but no CLI → lite"      lite 0 ok     -- PATH="$CLEAN_PATH"   PROJECT_ROOT="$ROOT_WITH"
+run "unset + disabled(off) → lite"       lite 0 ok     -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITH" CHORUS_OPENSPEC_MODE=off
+run "unset + disabled(toggle) → lite"    lite 0 ok     -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITH" CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC=false
+
+# --- explicit lite / off ---
+run "lite + usable → lite"               lite 0 ok     -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITH" CHORUS_SPEC_MODE=lite
+run "off + usable → off"                 off 0 ok      -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITH" CHORUS_SPEC_MODE=off
+
+# --- explicit openspec ---
+run "openspec + usable → openspec"       openspec 1 ok   -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITH" CHORUS_SPEC_MODE=openspec
+run "openspec + no dir → FAIL"           openspec 0 fail -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITHOUT" CHORUS_SPEC_MODE=openspec
+run "openspec + no CLI → FAIL"           openspec 0 fail -- PATH="$CLEAN_PATH"   PROJECT_ROOT="$ROOT_WITH" CHORUS_SPEC_MODE=openspec
+run "openspec + disabled → FAIL"         openspec 0 fail -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITH" CHORUS_SPEC_MODE=openspec CHORUS_OPENSPEC_MODE=off
+
+# --- invalid value falls back to default resolution ---
+run "invalid + usable → openspec"        openspec 1 ok -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITH" CHORUS_SPEC_MODE=bogus
+run "invalid + no dir → lite"            lite 0 ok     -- PATH="$PATH_WITH_CLI" PROJECT_ROOT="$ROOT_WITHOUT" CHORUS_SPEC_MODE=bogus
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/.next/standalone/public/chorus-plugin/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.0"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/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.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -344,9 +344,13 @@ To disable, reconfigure the plugin via `/plugin` settings or manually edit `~/.c
 
 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 `/chorus: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)
+**First-principles alignment (a stage-tailored instruction in all three reviewers).** Each reviewer also checks, top-down, that the work still serves the *original Idea's intent*. It resolves the Idea from the entity under review (proposal-reviewer → the proposal's `inputUuids[0]`; task-reviewer → its proposal's `inputUuids[0]`; code-reviewer → the given `ideaUuid`), reads it with the existing `chorus_get_idea` + `chorus_get_elaboration` + `chorus_get_comments`, and builds the intent **baseline** from **human input only** — the Idea content + elaboration answers where `answeredBy.type == "user"` + comments where `author.type == "user"`. Agent-answered elaboration and agent-authored comments are audit context only: they cannot expand, shrink, or override the baseline. It flags **scope creep** (work beyond intent), **requirement loss / shrink** (intent dropped or reduced), or **semantic drift** (passes AC but misses the point). Unauthorized drift is a **BLOCKER → VERDICT: FAIL / reject**, downgraded to a cited `NOTE` only when traceable to a **human** authorization: a human-authored Idea comment (`author.type == "user"`), a human-answered elaboration entry (`answeredBy.type == "user"`), or an explicit human override at the gate. **An agent's own comment never authorizes**, so a drifting agent cannot self-clear. The alignment finding folds into the existing VERDICT; the dimension is skipped when the entity has no attached Idea.
 
-Opt-in spec-driven path: `/proposal`, `/develop`, `/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: the `enableOpenSpec` toggle is on (default) and `CHORUS_OPENSPEC_MODE` ≠ `off`, an `openspec/` directory exists at the project root, and the `openspec` CLI is on `PATH`.
+### 6. Spec mode: OpenSpec (default when usable) vs spec-lite (fallback)
+
+The SessionStart hook resolves one **spec mode** per session and prints a `## Spec Mode` section stating it. Resolution: an explicit `CHORUS_SPEC_MODE` (`lite`/`openspec`/`off`) wins; when unset, **OpenSpec is the default whenever it is usable** — the `enableOpenSpec` toggle on (default) and `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: a durable local spec `.chorus/specs/<slug>/spec.md` per capability (edited in place, **never synced** to Chorus), plus one dated folder per change effort `.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` of plain-markdown docs named by Document type (`prd.md`, `tech_design.md`, …), each of those dated-folder docs mirrored 1:1 into a persistent Chorus Document (see the `spec-lite` skill). `CHORUS_SPEC_MODE=off` selects free-form (no spec artifact).
+
+OpenSpec spec-driven path: `/proposal`, `/develop`, `/yolo` write `proposal.md` / `design.md` / spec deltas on disk and mirror them into Chorus drafts.
 
 **When the user wants it on** (e.g. they ran `/chorus enable openspec` after the `(OpenSpec off — …)` banner), actually **enable it for them** — run whichever steps are missing, don't just describe them:
 
@@ -355,9 +359,9 @@ npm i -g @fission-ai/openspec       # 1. install the CLI if it's not on PATH (gl
 openspec init --tools claude        # 2. scaffold openspec/ + wire up Claude Code's native commands/skills
 ```
 
-`openspec init` is interactive if you omit `--tools`; pass `--tools claude` to run it unattended. Chorus's detection only needs the `openspec/` directory, but wiring up Claude Code also gives OpenSpec its own commands + skills. The OpenSpec signal is read **once at SessionStart**, so it can't flip mid-session — after the steps succeed, tell the user to **re-launch the session**; the banner then reads `(OpenSpec Enabled)` and the stage skills fold in the `openspec-aware` skill automatically.
+`openspec init` is interactive if you omit `--tools`; pass `--tools claude` to run it unattended. Chorus's detection only needs the `openspec/` directory, but wiring up Claude Code also gives OpenSpec its own commands + skills. The spec mode is resolved **once at SessionStart**, so it can't flip mid-session — after the steps succeed, tell the user to **re-launch 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, flip `enableOpenSpec` to `false` or set `CHORUS_OPENSPEC_MODE=off` — the banner then reads a neutral `(OpenSpec off)`.
+To turn OpenSpec off, flip `enableOpenSpec` to `false` or 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.
 
 ### 7. Daemon auto-start via `chorus agents add`
 
@@ -438,7 +442,8 @@ This is the core overview skill. For stage-specific workflows, use:
 | **Development** | `/develop` | Claim Tasks, report work, session & sub-agent management, Agent Teams integration |
 | **Review** | `/review` | Approve/reject Proposals, verify Tasks, project governance |
 | **Docs** | `/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 `/proposal`, `/develop`, and `/yolo` whenever the user has the `openspec` CLI installed. Scaffolds `openspec/changes/<slug>/` on disk and mirrors files into Chorus document drafts via the `chorus-api.sh` wrapper. Skips silently in fallback mode. See `.claude/skills/openspec-aware/SKILL.md`. |
+| **OpenSpec mode** | `openspec-aware` | **Shared sub-procedure** invoked by `/proposal`, `/develop`, and `/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 the `chorus-api.sh` wrapper. No-op when the mode isn't a usable OpenSpec. See `.claude/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/archive. See `.claude/skills/spec-lite/SKILL.md`. |
 
 ### Getting Started
 

package/.next/standalone/public/chorus-plugin/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.0"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/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.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -142,6 +142,10 @@ Each task and proposal includes a `commentCount` field — use it to decide whic
 >
 > 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 originating proposal `description` contains a locator line `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/`, the project's `prd` / `tech_design` / … Documents are **persistent mirrors** of the Chorus-typed docs in that **dated change folder** (`prd.md`, `tech_design.md`, …, named by Chorus Document type). Load the `spec-lite` skill (`skills/spec-lite/SKILL.md`). Locate the dated folder **deterministically** from that locator line (not by title/type, which isn't unique). Edit those `<type>.md` files in place (they are the source of truth for the change) and update the capability's durable `.chorus/specs/<slug>/spec.md` in place too — but **`spec.md` is never mirrored** (local only, no ids). Tick `- [ ]` acceptance points as work completes, then re-mirror each edited dated-folder file via `chorus mcp call chorus_pm_update_document … --arg-file content=.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/<type>.md` against its `documentUuid` (each update auto-increments the Document version = its modification history). No new tool/CLI — same `--arg-file` transport as OpenSpec. **Git history is the audit trail** (`git log -- .chorus/specs/<slug>/` for the whole capability — the durable `spec.md`'s diffs + each dated folder's change docs; `git log --follow -- <file>` to trace a single renamed file) — there is no changelog section to maintain.
+>
+> **Single-writer:** the folder is shared — in a multi-task wave, only the **orchestrator / main agent** edits + re-mirrors it; parallel workers report via `chorus_report_work` only. A non-orchestrator that must update it re-reads immediately before writing to detect conflicts.
+
 ### Step 5: Start Working
 
 **Sub-agent**: checkin to the task first:
@@ -223,21 +227,21 @@ chorus_submit_for_verify({
 
 > `to_verify` does NOT unblock downstream tasks — only `done` (after admin verification) does.
 
-> **Review Agent:** After `chorus_submit_for_verify`, the Chorus plugin's PostToolUse hook injects context instructing you to spawn `chorus:task-reviewer` — an independent, read-only review agent. You MUST spawn it yourself (it is NOT auto-launched). **Run it in foreground** (do NOT set `run_in_background`) — wait for the VERDICT before proceeding. The reviewer posts a VERDICT comment on the task.
+> **Review Agent:** After `chorus_submit_for_verify`, the Chorus plugin's PostToolUse hook injects context instructing you to spawn `chorus:task-reviewer` — an independent, read-only review agent. You MUST spawn it yourself (it is NOT auto-launched). Wait for it to complete — in Claude Code, that means waiting for the sub-agent's completion notification; the launch result itself is never the verdict. The reviewer posts a VERDICT comment on the task.
 
-After the reviewer completes, read its VERDICT:
+After the reviewer completes, read **this round's** VERDICT:
 ```
 chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
 ```
-Find the most recent comment containing `VERDICT:` and act on it:
+Find the `VERDICT:` comment posted **after you dispatched the reviewer** — not an older round's — and act on it. Do not advance the pipeline (verify or reopen) before you have read that comment:
 
 - **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 `maxTurns` 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 PostToolUse hook injects a reminder to spawn `chorus:code-reviewer` (gated by `enableCodeReviewer`, default on). Spawn it yourself in **foreground**, 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 `/chorus: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 `maxCodeReviewRounds`. Advisory/behavioral, like the other reviewers. Run it **before** any idea-completion report.
+> **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 PostToolUse hook injects a reminder to spawn `chorus:code-reviewer` (gated by `enableCodeReviewer`, default on). Spawn it yourself and wait for its completion notification, passing the `ideaUuid` + round number; then read THIS round's `VERDICT` comment on the idea before deciding. 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 `/chorus: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 `maxCodeReviewRounds`. Advisory/behavioral, like the other reviewers. Run it **before** any idea-completion report.
 
 ### Step 9: Handle Review Feedback
 
@@ -293,9 +297,8 @@ When using Claude Code's Agent Teams to run multiple sub-agents in parallel, Cho
 chorus_checkin()
 chorus_list_tasks({ projectUuid: "<project-uuid>" })
 
-# 2. Create Claude Code team and spawn sub-agents
-TeamCreate({ team_name: "feature-x" })
-
+# 2. Dispatch one sub-agent per unblocked task, issuing the whole wave in a
+#    SINGLE message so they run in parallel. There is no team object to create.
 # Pass only task UUIDs — plugin auto-injects session workflow
 Task({
   name: "frontend-worker",
@@ -307,6 +310,8 @@ Task({
 - Task UUID(s)
 - NO session UUID, NO workflow boilerplate — plugin auto-injects everything
 
+> **Fallback:** if sub-agent dispatch is unavailable (no sub-agent primitive, permission denied) or sub-agents fail repeatedly, execute the wave's tasks sequentially as the main agent following Steps 1-9 above. Slower, same pipeline.
+
 ### Sub-Agent Workflow
 
 The plugin injects session UUID and workflow into the sub-agent's context automatically.

package/.next/standalone/public/chorus-plugin/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.0"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/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.0"
   category: project-management
   mcp_server: chorus
 ---