@chorus-aidlc/chorus 0.17.2 → 0.18.0

package/.next/standalone/public/chorus-plugin/skills/openspec-aware/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: openspec-aware
-description: Opt-in OpenSpec-mode authoring for Chorus PM workflows in Claude Code. 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-api.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 Claude Code. 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-api.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
 ---
@@ -14,7 +14,9 @@ metadata:
 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:
 
 - 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.
+- Otherwise the calling skill follows the resolved `SPEC_MODE` — **spec-lite** (the default when OpenSpec isn't usable) or free-form (`=off`).
+
+> **See also — `spec-lite` (the lightweight fallback):** OpenSpec (this skill) stays the **default whenever it is usable** (`openspec/` dir + CLI, not disabled). When OpenSpec is absent or disabled — or when `CHORUS_SPEC_MODE=lite` is set explicitly — the mode resolves to **spec-lite**: a Chorus-native, git-tracked model with a durable local spec `.chorus/specs/<slug>/spec.md` per capability (edited in place, **never synced**), 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`, …), those dated-folder docs each mirrored 1:1 into a persistent Chorus Document via the same `--arg-file` transport, with no CLI and no strict validation. A session that resolves to OpenSpec follows everything below unchanged. See the `spec-lite` skill (`skills/spec-lite/SKILL.md`).
 
 When you reach a point in proposal / develop / yolo where this skill is referenced, **read the value of `CHORUS_OPENSPEC_ACTIVE` from the SessionStart context** (see §1) and branch on it. Do not re-run the detection block — the SessionStart hook has already done it once for this session.
 
@@ -22,7 +24,7 @@ When you reach a point in proposal / develop / yolo where this skill is referenc
 
 ## §1. Detection — already done at SessionStart
 
-The Chorus plugin's SessionStart hook (`bin/on-session-start.sh`) computes `CHORUS_OPENSPEC_ACTIVE` once when the session opens and writes a `## OpenSpec Mode` section into the plugin's injected context. The value of `CHORUS_OPENSPEC_ACTIVE` is `1` only when **all three** of these hold:
+The Chorus plugin's SessionStart hook (`bin/on-session-start.sh`) resolves the active spec mode once when the session opens and writes a `## Spec Mode` section into the plugin's injected context. When the resolved mode is a usable OpenSpec, that section also carries a `CHORUS_OPENSPEC_ACTIVE=1` line. `CHORUS_OPENSPEC_ACTIVE` is `1` only when **all three** of these hold:
 
 1. `CHORUS_OPENSPEC_MODE` is **not** set to `off` (explicit opt-out wins).
 2. The project root contains an `openspec/` directory (i.e. someone ran `openspec init` here).
@@ -32,44 +34,38 @@ Both signals (2) and (3) are required because the OpenSpec authoring path needs
 
 ### 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):
-
-```
-## OpenSpec Mode
+You should already see something like this in your context (look for the `## Spec Mode` section near the top of the conversation). This skill is only loaded when the mode resolved to a usable OpenSpec, so you should see:
 
-CHORUS_OPENSPEC_ACTIVE=1 (openspec/ directory + openspec CLI both present)
 ```
+## Spec Mode
 
-or:
+CHORUS_SPEC_MODE=openspec (explicit; openspec/ directory + openspec CLI both present)
 
-```
-## OpenSpec Mode
-
-CHORUS_OPENSPEC_ACTIVE=0 (no openspec/ directory at /path/to/repo/openspec)
+CHORUS_OPENSPEC_ACTIVE=1 (openspec/ directory + openspec CLI both present)
 ```
 
 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.
+- No `CHORUS_OPENSPEC_ACTIVE=1` line (the section shows `CHORUS_SPEC_MODE=lite` / `off`, or you were spawned without SessionStart context) → this skill is a no-op; return to the calling skill's path. **Do not** scaffold `openspec/changes/`. **Do not** add the slug line to the proposal description. (Reconstruct the value with the manual fallback below if you genuinely have no context.)
 
-### Manual fallback
+### Manual fallback (no SessionStart context)
 
-If you're in a sub-shell, sub-agent, or session that did not see SessionStart 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 you're in a sub-shell, sub-agent, or session that did not see the `## Spec Mode` section (e.g. spawned mid-session without the parent's context), **do not hand-roll the detection** — source the *same* resolver the hook uses, so there is one computation of the mode:
 
 ```bash
-if [ "${CHORUS_OPENSPEC_MODE:-}" = "off" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-elif [ ! -d "${CLAUDE_PROJECT_DIR:-$PWD}/openspec" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-elif ! openspec --version >/dev/null 2>&1; then
-  CHORUS_OPENSPEC_ACTIVE=0
+# The resolver sits beside the plugin hooks; ${CLAUDE_PLUGIN_ROOT} is the plugin
+# root Claude Code exports (the same var hooks.json uses).
+RESOLVER="${CLAUDE_PLUGIN_ROOT}/bin/resolve-spec-mode.sh"
+if [ -f "$RESOLVER" ]; then
+  . "$RESOLVER"   # sets SPEC_MODE (lite|openspec|off), SPEC_FAIL (non-empty ⇒ halt),
+                  # and CHORUS_OPENSPEC_ACTIVE (1 only for a usable openspec)
 else
-  CHORUS_OPENSPEC_ACTIVE=1
+  echo "resolve-spec-mode.sh not found; set CHORUS_SPEC_MODE explicitly and re-launch" >&2
 fi
 ```
 
-Use this only when SessionStart context is genuinely unavailable — duplicating the detection is wasteful when the hook already computed it.
+Then: if `SPEC_FAIL` is non-empty, halt and surface it; if `CHORUS_OPENSPEC_ACTIVE=1` follow §3; otherwise this skill is a no-op — return to the caller, which follows the resolved `SPEC_MODE` (spec-lite or free-form). If you genuinely cannot locate the helper, set `CHORUS_SPEC_MODE` explicitly and re-launch rather than guessing — never re-derive the rule inline (the hook/helper is the single source of truth).
 
 ---
 
@@ -376,14 +372,14 @@ 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 `CHORUS_OPENSPEC_ACTIVE` is not `1`, this skill is a **no-op** — return to the calling skill, which follows whatever the resolved `SPEC_MODE` is: **spec-lite** (the default when OpenSpec isn't usable) or **free-form** (`CHORUS_SPEC_MODE=off`). Either way, 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.
+- Document authoring is whatever the resolved mode dictates (spec-lite: mirror `.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/<type>.md`; free-form: inline `chorus_pm_add_document_draft`) — not this skill's concern.
+- Rule 1 (wrapper-only mirror) does not apply to OpenSpec here — there is no `openspec/` local file for this skill to mirror.
 - The §3.9 archive hook does nothing (no slug → silent exit).
 
 ---
@@ -468,8 +464,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 SessionStart 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 `CHORUS_OPENSPEC_ACTIVE` from the `## Spec Mode` section in the SessionStart context (§1). If it isn't there, fall back to the manual probe in §1.
+2. If `CHORUS_OPENSPEC_ACTIVE` is not `1` → no-op; return to the caller, which follows the resolved `SPEC_MODE` (spec-lite or free-form) — see §4.
 3. Otherwise:
    a. Pick `$SLUG` (§3.1).
    b. `openspec new change "$SLUG"` (§3.2).

package/.next/standalone/public/chorus-plugin/skills/orchestrate/SKILL.md

@@ -4,7 +4,7 @@ description: Multi-agent orchestration playbook — coordinate OTHER agents and
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.2"
+  version: "0.18.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -79,6 +79,8 @@ Chorus ships three read-only reviewer sub-agents. As orchestrator you spawn them
 
 Each posts exactly one `VERDICT: PASS` / `PASS WITH NOTES` / `FAIL` comment. Verdicts are **advisory** — they do not auto-approve, auto-verify, or hard-block; you read the BLOCKERs and decide. A `FAIL` means route the BLOCKERs back for a fix before advancing (for a code-review FAIL, add fix tasks to the *approved* proposal via `/quick-dev` and re-run once they are `done`). See `/review` and the plugin's Review Agent Configuration for the full pattern.
 
+**First-principles alignment (a stage-tailored instruction in each reviewer).** Every one of the three reviewers also checks, top-down, that the work still serves the *original Idea's intent* — it resolves the Idea from the entity under review, reads it via the existing `chorus_get_idea` + `chorus_get_elaboration` + `chorus_get_comments`, builds the intent baseline from **human-authored** content only, and flags scope creep, requirement loss/shrink, or semantic drift. Unauthorized drift is a **BLOCKER → FAIL / reject**, downgraded to a NOTE only when traceable to a **human-originated** authorization (a human-authored Idea comment, a human-answered elaboration entry, or an explicit human override at the gate) — an agent's own comment never authorizes, so a drifting agent cannot self-clear. As orchestrator, route an alignment FAIL back for a fix like any other BLOCKER, or record the human override at the gate.
+
 ---
 
 ## Choosing a collaboration mode
@@ -104,6 +106,14 @@ Guidance: start narrow. If a single owner can hold the whole feature in their he
 
 ---
 
+## Replying to the agent who woke you (advisory)
+
+When an agent wakes a peer on a shared idea or task — an orchestrator dispatching a worker, or any agent `@mention`-ing another — the wake surfaces the **waker's live session anchor**: a note naming the waking agent and telling the woken peer that the waker has an open conversation on this idea. If you are the woken peer, **reply on the same idea/task resource** (comment there rather than opening a brand-new session) and your reply lands back in the waker's existing live session, keeping the collaboration on one thread instead of scattering into a fresh one.
+
+This is **advisory, not routing.** There is no automatic server subscription and nothing is force-delivered — replying on the shared resource is simply *where a reply lands* (via the existing return path), not a guaranteed channel. When the waker's origin is **offline** at wake time, no live anchor is surfaced and the exchange degrades to **notify-only**: the reply reaches the waker as an ordinary notification it picks up on its next turn. Only idea/theme-anchored wakes carry this anchor; ad-hoc wakes with no shared idea do not.
+
+---
+
 ## Reversed-Conversation gates (you never auto-ship)
 
 Chorus is **AI proposes, humans verify**. As orchestrator you enforce that, you do not bypass it:

package/.next/standalone/public/chorus-plugin/skills/proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.2"
+  version: "0.18.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -69,13 +69,15 @@ Elaboration resolved --> Create Proposal --> Add drafts --> Validate --> Submit
 
 ### Step 1: Create an Empty Proposal
 
-**Recommended approach:** Create the proposal container first without any drafts, then incrementally add document and task drafts one by one.
+**Resolve the spec mode (Step 1.5) BEFORE this create.** In OpenSpec and spec-lite modes the container's `description` MUST carry a locator line (`OpenSpec change slug: <slug>` or `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/`), and `description` can only be set at creation — so decide the mode + slug/dated-path first and include that line in this single call. Do NOT create a bare container and then realize you needed the line (that would strand it without the locator or force a duplicate). Free-form mode omits any locator line.
+
+**Recommended approach:** Create the proposal container first (with the mode's locator line in `description` when applicable), then incrementally add document and task drafts one by one.
 
 ```
 chorus_pm_create_proposal({
   projectUuid: "<project-uuid>",
   title: "Implement <feature name>",
-  description: "Analysis and implementation plan for Idea #xxx",
+  description: "Analysis and implementation plan for Idea #xxx\n\n<locator line here in OpenSpec / spec-lite mode>",
   inputType: "idea",
   inputUuids: ["<idea-uuid>"]
 })
@@ -85,15 +87,20 @@ chorus_pm_create_proposal({
 
 > **A theme cannot be a proposal input** — `chorus_pm_create_proposal` rejects any input idea with `isContainer = true`. Derive a child idea from the theme and write the proposal on the child instead. (See the theme-ideas section of the `/idea` skill.)
 
-### Step 1.5: Detect OpenSpec mode
+### Step 1.5: Select spec mode
+
+The spec mode is **already computed for you** by the SessionStart hook (`bin/resolve-spec-mode.sh`) — do NOT re-derive it. Read the `## Spec Mode` section of your SessionStart context: it states `CHORUS_SPEC_MODE=<lite|openspec|off>` plus a one-line routing note. (Spawned without that context? Source the *same* `bin/resolve-spec-mode.sh` to get `SPEC_MODE`/`SPEC_FAIL` — never hand-roll the rule.) Just act on that value:
+
+- If the section says the requested mode **cannot be honored** (e.g. `CHORUS_SPEC_MODE=openspec` but OpenSpec isn't usable — it prints "cannot be honored" with a config-conflict or install-hint reason), **halt** and surface that reason; do not fall back.
+- Otherwise branch on the stated mode:
 
-Before authoring document drafts, **load the `openspec-aware` skill at `.claude/skills/openspec-aware/SKILL.md`** and run its §1 detection contract. Branch on the result:
+- **resolved = spec-lite** → load the `spec-lite` skill (`skills/spec-lite/SKILL.md`) and follow it: pick `$SLUG` (a **capability/feature** name — `.chorus/specs/<slug>/` holds the durable local spec `spec.md`, edited in place across changes, not one folder per change). Ensure the durable `spec.md` exists (local-only, **no Chorus ids** — Intent / plain-prose Requirements + `- [ ]` acceptance points / Non-goals; use the `spec-lite` skill's inline durable-spec template) and update it in place to the new truth. Create this change's **dated folder** `.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` and write its **synced** Chorus-typed docs — `prd.md` (primary), plus `tech_design.md` etc. only if warranted (shape = the `spec-lite` skill's inline dated-folder document template). Put the literal locator line `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` in the **Step 1 create** `description` (that's why the mode is resolved before creating), then mirror **each** dated-folder `<type>.md` to its persistent Document (`chorus_pm_add_document_draft --arg-file` the first time a doc is authored, `chorus_pm_update_document --arg-file` after) via `chorus mcp call … --arg-file content=.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/<type>.md`. **`spec.md` is never mirrored.** Skip Step 2 below — the file-fill mirror replaces inline drafting for these documents. (Add tasks via `chorus_pm_add_task_draft` as usual — there is no `tasks.md`.)
 
-- **`CHORUS_OPENSPEC_ACTIVE=1`** → follow `openspec-aware` §3. Pick `$SLUG`, scaffold `openspec/changes/<slug>/`, author `proposal.md` / `design.md` / `specs/<capability>/spec.md` locally, then create the proposal container (Step 1 above) with the literal line `OpenSpec change slug: <slug>` in `description`, and mirror each local file into a document draft.
+- **resolved = OpenSpec** (the `## Spec Mode` section shows `CHORUS_OPENSPEC_ACTIVE=1` — i.e. `CHORUS_SPEC_MODE=openspec` *or* unset, with OpenSpec usable) → follow `openspec-aware` §3. Pick `$SLUG`, scaffold `openspec/changes/<slug>/`, author `proposal.md` / `design.md` / `specs/<capability>/spec.md` locally, then put the literal line `OpenSpec change slug: <slug>` in the **Step 1 create** `description` (mode resolved before creating), and mirror each local file into a document draft.
 
   > **⛔ Mandatory in OpenSpec mode:** mirror calls fill `content` from the local file — prefer `chorus mcp call … --arg-file content=<file>`, falling back to the `chorus-api.sh` wrapper with `json_encode_file` when `chorus` is not on `PATH` — see `openspec-aware` §3.6. Do **not** call `chorus_pm_add_document_draft` directly from the MCP harness with a hand-typed `content` field. Re-typing thousands of lines through the LLM burns 20k+ content tokens per proposal and breaks byte-equality with the local source of truth (`openspec-aware` §2 Rule 1 explains the full reasoning). Skip Step 2 below when in OpenSpec mode — the file-fill flow in `openspec-aware` §3.6 replaces it for documents.
 
-- **`CHORUS_OPENSPEC_ACTIVE=0`** (CLI absent or `CHORUS_OPENSPEC_MODE=off`) → proceed with Step 2 unchanged. Author drafts inline as free-form Markdown via direct MCP `chorus_pm_add_document_draft`.
+- **resolved = free-form** (explicit `CHORUS_SPEC_MODE=off`) → proceed with Step 2 unchanged. Author drafts inline as free-form Markdown via direct MCP `chorus_pm_add_document_draft`.
 
 ### Step 2: Add Document Drafts
 

package/.next/standalone/public/chorus-plugin/skills/quick-dev/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.2"
+  version: "0.18.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -152,7 +152,7 @@ chorus_submit_for_verify({
 })
 ```
 
-Submitting is not final verification. Spawn the required independent task-reviewer sub-agent as described in `/develop`, wait for it, and read the newest `VERDICT:` Task comment. `PASS` and `PASS WITH NOTES` continue. On `FAIL`, do not verify or hand off: fix every unresolved BLOCKER, repeat AC self-check and submission, then run a fresh independent task review.
+Submitting is not final verification. Spawn the required independent task-reviewer sub-agent as described in `/develop`, wait for it, and read THIS round's `VERDICT:` Task comment — the one posted after your dispatch, not an older round's. `PASS` and `PASS WITH NOTES` continue. On `FAIL`, do not verify or hand off: fix every unresolved BLOCKER, repeat AC self-check and submission, then run a fresh independent task review.
 
 ### Step 8: Permission-Aware Verification
 
@@ -170,12 +170,14 @@ This handoff applies in interactive and headless daemon sessions. Do not use an
 
 ## Session Integration
 
-Quick Tasks work with Claude Code Agent Teams just like proposal-based tasks:
+Quick Tasks work with sub-agent execution just like proposal-based tasks:
 
-- **Team Lead**: create quick tasks, then assign to sub-agents via task UUIDs
+- **Main agent**: create quick tasks, then hand each to a sub-agent via its task UUID
 - **Sub-agents**: the Chorus Plugin auto-injects session context — just pass `sessionUuid` to `chorus_update_task` and `chorus_report_work`
 - **Session lifecycle** is fully automated by the plugin
 
+> There is no team object to create: to run several quick tasks in parallel, dispatch one sub-agent per task, issuing the whole batch in a single message — that is what makes them run in parallel. If sub-agent dispatch is unavailable (no sub-agent primitive, permission denied) or sub-agents fail repeatedly, work the tasks sequentially as the main agent.
+
 ---
 
 ## Tips

package/.next/standalone/public/chorus-plugin/skills/review/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.2"
+  version: "0.18.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -64,15 +64,17 @@ Key responsibilities:
 
 When reviewing proposals, tasks, or an Idea's final aggregate code change, prefer spawning an independent reviewer sub-agent over reviewing manually:
 
-1. **Try the reviewer first.** Spawn `chorus:proposal-reviewer` (for proposals), `chorus:task-reviewer` (for tasks), or `chorus:code-reviewer` (the final ship-time gateway over an Idea's aggregate code change, after its last task is verified — pass the `ideaUuid`; it posts its VERDICT on the **idea**) as a read-only sub-agent. **Run it in foreground** (do NOT set `run_in_background`) — you must wait for the VERDICT before proceeding. It posts a VERDICT comment with detailed findings.
-2. **Read the VERDICT.** After the reviewer completes, call `chorus_get_comments` and find the most recent comment containing `VERDICT:`. There are exactly three possible outcomes:
+1. **Try the reviewer first.** Spawn `chorus:proposal-reviewer` (for proposals), `chorus:task-reviewer` (for tasks), or `chorus:code-reviewer` (the final ship-time gateway over an Idea's aggregate code change, after its last task is verified — pass the `ideaUuid`; it posts its VERDICT on the **idea**) as a read-only sub-agent. Then wait for it to complete using this harness's waiting mechanism — in Claude Code, the sub-agent's completion notification. The launch result is not the verdict: these reviewer subagent types report an async launch regardless of the flag you pass, so the decision must come from the comment, not the dispatch. It posts a VERDICT comment with detailed findings.
+2. **Read THIS round's VERDICT.** After the reviewer completes, call `chorus_get_comments` for the entity under review and find the `VERDICT:` comment posted **after your dispatch** — not an older round's. Do not advance the pipeline before you have read that comment. There are exactly three possible outcomes:
    - **VERDICT: PASS** — No issues found. Approve (proposals) or mark AC passed and verify (tasks).
    - **VERDICT: PASS WITH NOTES** — Minor non-blocking notes. Still approve/verify. Notes are informational.
    - **VERDICT: FAIL** — BLOCKERs found. Reject (proposals) or reopen (tasks). Fix the specific BLOCKERs listed in the comment before resubmitting.
-3. **No new VERDICT comment?** The reviewer exhausted its `maxTurns` budget before posting. Respawn it ONCE with an explicit prompt like: *"Stay within your turn budget. Skip deep source verification — batch all MCP fetches up front, skim for obvious BLOCKERs only, and reserve your last few turns to post the VERDICT comment."* If the second attempt also fails to post, review manually using the checklists below.
-4. **Track rounds.** Count existing VERDICT comments before spawning. After 3 rounds of FAIL on the same item, stop the loop and escalate to human review.
+3. **No new VERDICT comment?** Check what the reviewer *did* post. A comment reporting that the round limit was reached, or any other explicit refusal to review, is a deliberate escalation to a human: STOP — do not respawn, do not self-review, do not post a VERDICT of your own. If it posted nothing at all, respawn it ONCE, telling it to stay within its turn budget and reserve its last turns for the VERDICT, then apply this same check again to what the retry posts. An explicit refusal from the retry still means STOP; only a second true silence lets you review the item yourself as a read-only pass using the checklists below and POST the VERDICT — **absence is never a PASS**.
+4. **Track rounds.** Count existing VERDICT comments before spawning. After 3 rounds of FAIL on the same item, stop the loop and escalate to human review: post a comment saying the round limit was reached and a human decision is needed, and post no VERDICT. Nobody — including you on a later turn — may replace that escalation with a self-reviewed VERDICT.
 5. **Fallback.** If the reviewer is unavailable (e.g., agent type not registered, sub-agent spawn fails), review the item yourself using the quality checklists in the workflows below.
 
+**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, reads it via the existing `chorus_get_idea` + `chorus_get_elaboration` + `chorus_get_comments`, builds the intent baseline from **human-authored** content only, and flags **scope creep**, **requirement loss / shrink**, or **semantic drift**. Unauthorized drift is a **BLOCKER → VERDICT: FAIL / reject**, downgraded to a NOTE only when traceable to a **human-originated** authorization (a human-authored Idea comment, a human-answered elaboration, or an explicit human override at the gate) — an agent's own comment never authorizes, so a drifting agent cannot self-clear. So a `FAIL` may come from intent drift, not just local defects; treat it the same way — reject/reopen and fix, or record a human override.
+
 ---
 
 ## Workflow
@@ -145,7 +147,7 @@ chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
 
 #### A3.5: Independent Review
 
-Spawn `chorus:proposal-reviewer` per the [Review Strategy](#review-strategy) above — foreground, not background. Read its VERDICT comment before proceeding.
+Spawn `chorus:proposal-reviewer` per the [Review Strategy](#review-strategy) above, wait for its completion notification, then read THIS round's VERDICT comment on the proposal before proceeding.
 
 #### A4: Approve or Reject
 
@@ -210,14 +212,14 @@ chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
 
 #### B2.5: Independent Review
 
-Spawn `chorus:task-reviewer` per the [Review Strategy](#review-strategy) above — foreground, not background. After it completes, read its VERDICT:
+Spawn `chorus:task-reviewer` per the [Review Strategy](#review-strategy) above. After it completes, read THIS round's VERDICT on the task:
 
 - **VERDICT: PASS** or **PASS WITH NOTES** → proceed to B3 (mark AC) and B4 (verify).
 - **VERDICT: FAIL** → skip to B4 and **reopen** the task. Do NOT mark AC as passed.
 
 #### B2.6: Final Code-Review Gateway (after an Idea's LAST task is verified)
 
-When the task you just verified is the **last** task of its idea-rooted proposal, run the ship-time code-review gateway before the Idea's code is considered shipped. The PostToolUse hook injects a reminder to spawn `chorus:code-reviewer` (gated by `enableCodeReviewer`, default on). Spawn it per the [Review Strategy](#review-strategy) — foreground, passing the `ideaUuid` + round number. It reviews the Idea's **aggregate** code change across all its tasks — cross-task integration, architecture/convention consistency, security, regression/performance, feature-level test coverage — dimensions a single-task review cannot see — and posts one `VERDICT` comment on the **idea**.
+When the task you just verified is the **last** task of its idea-rooted proposal, run the ship-time code-review gateway before the Idea's code is considered shipped. The PostToolUse hook injects a reminder to spawn `chorus:code-reviewer` (gated by `enableCodeReviewer`, default on). Spawn it per the [Review Strategy](#review-strategy), passing the `ideaUuid` + round number, and wait for its completion notification before reading THIS round's verdict. It reviews the Idea's **aggregate** code change across all its tasks — cross-task integration, architecture/convention consistency, security, regression/performance, feature-level test coverage — dimensions a single-task review cannot see — and posts one `VERDICT` comment on the **idea**.
 
 - **VERDICT: PASS** / **PASS WITH NOTES** → the feature may ship.
 - **VERDICT: FAIL** → do not reopen the verified tasks; instead add new fix tasks to the approved proposal via `/chorus:quick-dev` (`chorus_create_tasks` with `proposalUuid` set to the current approved proposal so the fix tasks attach to it). 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`.

package/.next/standalone/public/chorus-plugin/skills/spec-lite/SKILL.md

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