@chorus-aidlc/chorus 0.17.2 → 0.18.0

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

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

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-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 native task-reviewer subagent as described in `/chorus-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 native task-reviewer subagent as described in `/chorus-develop`, wait for it, and read THIS round's `VERDICT:` Task comment — the one posted after your dispatch, not an older round's. `PASS` and `PASS WITH NOTES` continue. On `FAIL`, do not verify or hand off: fix every unresolved BLOCKER, repeat AC self-check and submission, then run a fresh independent task review.
 
 ### Step 8: Permission-Aware Verification
 

package/.next/standalone/public/kiro-plugin/.kiro/skills/chorus-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,13 +64,13 @@ Key responsibilities:
 
 When reviewing proposals, tasks, or an Idea's final aggregate code change, prefer spawning an independent reviewer subagent over reviewing manually:
 
-1. **Try the reviewer first.** Spawn the `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 subagent. **Run it in the foreground** — 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 the `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 subagent. Then wait for the `subagent` call to return — that is this harness's waiting mechanism. It posts a VERDICT comment with detailed findings; the `subagent` call's own return value is not the verdict.
+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 turn budget before posting. Respawn it ONCE with an explicit prompt like: *"Stay within your turn budget. Skip deep source verification — batch all MCP fetches up front, skim for obvious BLOCKERs only, and reserve your last few turns to post the VERDICT comment."* If the second attempt also fails to post, review manually using the checklists below.
-4. **Track rounds.** Count existing VERDICT comments before spawning. After 3 rounds of FAIL on the same item, stop the loop and escalate to human review.
+3. **No new VERDICT comment?** Check what the reviewer *did* post. A comment reporting that the round limit was reached, or any other explicit refusal to review, is a deliberate escalation to a human: STOP — do not respawn, do not self-review, do not post a VERDICT of your own. If it posted nothing at all, respawn it ONCE, telling it to stay within its turn budget and reserve its last turns for the VERDICT, then apply this same check again to what the retry posts. An explicit refusal from the retry still means STOP; only a second true silence lets you review the item yourself as a read-only pass using the checklists below and POST the VERDICT — **absence is never a PASS**.
+4. **Track rounds.** Count existing VERDICT comments before spawning. After 3 rounds of FAIL on the same item, stop the loop and escalate to human review: post a comment saying the round limit was reached and a human decision is needed, and post no VERDICT. Nobody — including you on a later turn — may replace that escalation with a self-reviewed VERDICT.
 5. **Fallback.** If the reviewer is unavailable (e.g., subagent spawn fails), review the item yourself using the quality checklists in the workflows below.
 
 ---
@@ -145,7 +145,7 @@ chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
 
 #### A3.5: Independent Review
 
-Spawn the `chorus-proposal-reviewer` per the [Review Strategy](#review-strategy) above — foreground, not background. Read its VERDICT comment before proceeding.
+Spawn the `chorus-proposal-reviewer` per the [Review Strategy](#review-strategy) above, wait for the `subagent` call to return, then read THIS round's VERDICT comment on the proposal before proceeding.
 
 #### A4: Approve or Reject
 
@@ -210,14 +210,14 @@ chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
 
 #### B2.5: Independent Review
 
-Spawn the `chorus-task-reviewer` per the [Review Strategy](#review-strategy) above — foreground, not background. After it completes, read its VERDICT:
+Spawn the `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 the `chorus-code-reviewer`. 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 the `chorus-code-reviewer`. Spawn it per the [Review Strategy](#review-strategy), passing the `ideaUuid` + round number, and wait for the `subagent` call to return 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/kiro-plugin/.kiro/skills/chorus-spec-lite/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: chorus-spec-lite
+description: Lightweight, Chorus-native local specs for Chorus PM workflows in Kiro CLI — 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 chorus-openspec-aware path. Read from chorus-proposal / chorus-develop / chorus-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 `agentSpawn` 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.

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

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

package/.next/standalone/public/kiro-plugin/.kiro/steering/chorus.md

@@ -312,7 +312,7 @@ The table below shows default tool availability for each preset (no custom permi
 
 ### 5. Review Subagent Configuration
 
-The plugin ships three read-only reviewer subagents (`chorus-code-reviewer`, `chorus-proposal-reviewer`, `chorus-task-reviewer`), each scoped `tools: ["read", "@chorus"]` (no `write`/`shell`). Kiro auto-selects them by their `description`, and each is also reachable as a `/name` slash command. After proposal submission, task verification, or the last task of an idea-rooted proposal being verified, the `chorus` main agent's `postToolUse` hook injects a nudge instructing you to spawn the corresponding reviewer. You spawn it yourself — it is NOT auto-launched.
+The plugin ships three reviewer subagents (`chorus-code-reviewer`, `chorus-proposal-reviewer`, `chorus-task-reviewer`). None is granted `write`. `chorus-task-reviewer` and `chorus-code-reviewer` therefore cannot mutate the repo at all; the proposal-reviewer's shell could, so there its prompt — not the tool list — is what forbids mutation. `chorus-proposal-reviewer` is scoped `tools: ["read", "shell", "@chorus"]` — its shell is READ-ONLY inspection only (list, read, grep, git history), which lets it confirm a path exists before flagging it as missing; `chorus-task-reviewer` and `chorus-code-reviewer` are scoped `tools: ["read", "@chorus"]`. Kiro auto-selects them by their `description`, and each is also reachable as a `/name` slash command. After proposal submission, task verification, or the last task of an idea-rooted proposal being verified, the `chorus` main agent's `postToolUse` hook injects a nudge instructing you to spawn the corresponding reviewer. You spawn it yourself — it is NOT auto-launched.
 
 | Reviewer | Spawn after | Reviews |
 |----------|-------------|---------|
@@ -322,18 +322,22 @@ The plugin ships three read-only reviewer subagents (`chorus-code-reviewer`, `ch
 
 Reviewers post a VERDICT comment with one of three 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, then execute → verify and re-run the gateway.
 
-### 6. Enable OpenSpec Mode (Optional)
+### 6. Spec mode: OpenSpec (default when usable) vs spec-lite (fallback)
 
-Opt-in spec-driven path: `/chorus-proposal`, `/chorus-develop`, `/chorus-yolo` write `proposal.md` / `design.md` / spec deltas on disk and mirror them into Chorus drafts. Fully optional — free-form authoring works without it. The stage skills re-check the three activation signals inline (the Kiro spawn hook shows no OpenSpec banner): `CHORUS_OPENSPEC_MODE` ≠ `off`, an `openspec/` directory at the project root, and the `openspec` CLI on `PATH`.
+The `agentSpawn` hook (`bin/resolve-spec-mode.sh`) resolves one **spec mode** per session and injects a `## Spec Mode` plain-text block into your context stating it — the stage skills **consume** that value, they don't re-derive it. Resolution: an explicit `CHORUS_SPEC_MODE` (`lite`/`openspec`/`off`) wins; when unset, **OpenSpec is the default whenever it is usable** (`CHORUS_OPENSPEC_MODE` ≠ `off`, an `openspec/` directory at the project root, and the `openspec` CLI on `PATH`). When OpenSpec is absent or disabled, the mode falls back to **spec-lite** — a Chorus-native, git-tracked model with a durable local `.chorus/specs/<slug>/spec.md` per capability (never synced) plus dated per-change folders `<slug>/<YYYY-MM-DD>-<change-slug>/` of Chorus-typed docs mirrored 1:1 into Chorus (see `/chorus-spec-lite`). `CHORUS_SPEC_MODE=off` selects free-form (no spec artifact).
 
-**When the user wants it on**, actually **enable it for them** — run whichever steps are missing, don't just describe them:
+OpenSpec spec-driven path: `/chorus-proposal`, `/chorus-develop`, `/chorus-yolo` write `proposal.md` / `design.md` / spec deltas on disk and mirror them into Chorus drafts.
+
+**When the user wants OpenSpec on** (e.g. they saw spec-lite/off in the `## Spec Mode` block), actually **enable it for them** — run whichever steps are missing, don't just describe them:
 
 ```bash
 npm i -g @fission-ai/openspec       # 1. install the CLI if it's not on PATH (global, pure Node)
 openspec init --tools kiro          # 2. scaffold openspec/ + wire up Kiro's native integration
 ```
 
-`openspec init` is interactive if you omit `--tools`; pass `--tools kiro` to run it unattended. Chorus's detection only needs the `openspec/` directory, but wiring up Kiro also gives OpenSpec its own integration. There's no SessionStart banner on Kiro — the stage skills re-check the three signals inline, so once the directory and CLI are both present they fold in `/chorus-openspec-aware` automatically (no re-launch needed). To turn it off, set `CHORUS_OPENSPEC_MODE=off`.
+`openspec init` is interactive if you omit `--tools`; pass `--tools kiro` to run it unattended. The spec mode is resolved **once at `agentSpawn`**, so it can't flip mid-session — after the steps succeed, tell the user to **restart Kiro**; the `## Spec Mode` block then reads `CHORUS_SPEC_MODE=openspec (…)` and the stage skills fold in `/chorus-openspec-aware` automatically.
+
+To turn OpenSpec off, set `CHORUS_OPENSPEC_MODE=off` — the mode then falls back to **spec-lite** (or set `CHORUS_SPEC_MODE=off` for free-form). The `## Spec Mode` block always states the resolved mode + reason.
 
 ---
 
@@ -396,7 +400,8 @@ The `chorus` main agent owns `/chorus` and pre-loads all skills below. For stage
 | **Development** | `/chorus-develop` | Claim Tasks, report work, session & subagent management |
 | **Review** | `/chorus-review` | Approve/reject Proposals, verify Tasks, project governance |
 | **Docs** | `/chorus-docs` | Consult the live Chorus documentation site to answer product-usage questions — UI workflow, agent/plugin setup, API/MCP, deployment, operations |
-| **OpenSpec mode** | `/chorus-openspec-aware` | Opt-in **shared sub-procedure** invoked by `/chorus-proposal`, `/chorus-develop`, and `/chorus-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. |
+| **OpenSpec mode** | `/chorus-openspec-aware` | **Shared sub-procedure** invoked by `/chorus-proposal`, `/chorus-develop`, and `/chorus-yolo` when the resolved spec mode is a usable OpenSpec (the default when `openspec/` + CLI present and not disabled). Scaffolds `openspec/changes/<slug>/` on disk and mirrors files into Chorus document drafts via `chorus mcp call --arg-file` (`chorus-api.sh` wrapper as fallback). |
+| **spec-lite mode** | `/chorus-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. |
 
 ### Getting Started
 

package/.next/standalone/public/kiro-plugin/bin/chorus-api.sh

@@ -283,7 +283,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.2"}}}
+{"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/kiro-plugin/bin/on-agent-spawn.sh

@@ -48,6 +48,16 @@ if [ -z "$CHECKIN_RESULT" ]; then
   exit 0
 fi
 
+# Resolve the active spec mode via the shared resolver (single source of truth —
+# byte-identical to the Claude Code / Codex copies; enforced by the CI drift-guard).
+# It sets SPEC_MODE (lite|openspec|off), SPEC_REASON, SPEC_FAIL (non-empty ⇒ the
+# stage skill MUST halt), OPENSPEC_USABLE_REASON, OPENSPEC_HINT, CHORUS_OPENSPEC_ACTIVE.
+# Kiro delivers cwd in the event JSON; use it as PROJECT_ROOT (fallback $PWD).
+CWD_FROM_EVENT=$(printf '%s' "$EVENT" | grep -o '"cwd"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+PROJECT_ROOT="${CWD_FROM_EVENT:-$PWD}"
+# shellcheck source=./resolve-spec-mode.sh
+. "${SCRIPT_DIR}/resolve-spec-mode.sh"
+
 # Emit the startup context as plain text (Kiro adds STDOUT to context).
 # The checkin payload carries agent owner, effective permissions, the
 # active-project distribution, and working-style guidance — surfaced verbatim,
@@ -60,6 +70,37 @@ Chorus is connected at ${CHORUS_URL}. Session lifecycle hooks are enabled (check
 
 ${CHECKIN_RESULT}
 
+## Spec Mode
+
+CHORUS_SPEC_MODE=${SPEC_MODE} (${SPEC_REASON})"
+
+if [ "$SPEC_MODE" = "lite" ]; then
+  CONTEXT="${CONTEXT}
+
+Routing: lite → follow the spec-lite skill (/chorus-spec-lite). A capability's durable spec is \`.chorus/specs/<slug>/spec.md\` (edited in place, **never synced**, git history is its record); each change is a dated folder \`.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/\` of Chorus-typed docs (\`prd.md\` required; \`tech_design.md\`/\`adr.md\`/\`guide.md\`/\`spec.md\` optional) that **are** mirrored 1:1 into persistent Chorus Documents via \`chorus mcp call … --arg-file content=<file>\` (fallback \`chorus-api.sh mcp-tool\`). Put a \`Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/\` locator line in the proposal description. Do NOT scaffold \`openspec/changes/\` or add an \`OpenSpec change slug:\` line."
+elif [ "$SPEC_MODE" = "off" ]; then
+  CONTEXT="${CONTEXT}
+
+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}
+
+Routing: openspec → **cannot be honored** — ${SPEC_FAIL}. The proposal / yolo skill MUST halt after resolving the mode; do NOT silently fall back. Surface this to the user."
+  if [ -n "$OPENSPEC_HINT" ]; then
+    CONTEXT="${CONTEXT} Install hint: ${OPENSPEC_HINT}."
+  fi
+else
+  CONTEXT="${CONTEXT}
+
+CHORUS_OPENSPEC_ACTIVE=1 (${OPENSPEC_USABLE_REASON})
+
+Routing: openspec → load the openspec-aware skill (/chorus-openspec-aware) and follow §3 (OpenSpec authoring) — do NOT re-run the §1 detection block, the answer is already known.
+
+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}
+
 ## Quick Reference
 
 - **Long-horizon work**: follow AI-DLC via the Chorus skill (idea → proposal → task → verify) rather than coding ad hoc, and use chorus_search to locate the specific work the user refers to across ideas/proposals/tasks/docs.

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

@@ -56,13 +56,13 @@ Max review rounds: ${MAX_ROUNDS} (0 = unlimited).
 
 ACTION REQUIRED: spawn the read-only \`chorus-task-reviewer\` subagent to perform an independent review before admin verification.
 
-In Kiro, hand the reviewer this task (auto-selected by its description; also invokable as /chorus-task-reviewer): \"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 the review and post your VERDICT as a comment on the task.\"
+In Kiro, hand the reviewer this task (auto-selected by its description; also invokable as /chorus-task-reviewer): \"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 the review and post your VERDICT as a comment on the task.\"
 
-The reviewer is read-only (tools: read + @chorus) and posts its VERDICT as a comment on the task. After it completes, read comments and act on the most recent \`VERDICT:\` line:
+The reviewer is read-only (tools: read + @chorus) and posts its VERDICT as a comment on the task. Wait for the \`subagent\` call to return, 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 and wait for its VERDICT before proceeding."
+IMPORTANT: the \`subagent\` call's own return value is not the verdict — base the decision on the comment. 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."
 
 exit 0