@chorus-aidlc/chorus-openclaw-plugin 0.17.2 → 0.18.0

package/skills/proposal-reviewer/SKILL.md

@@ -4,7 +4,7 @@ description: Adversarial read-only review of a submitted Chorus proposal — doc
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.2"
+  version: "0.18.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -19,7 +19,8 @@ You have been asked to **review a submitted Chorus proposal**. Your job is **not
 
 ## Hard rules (READ-ONLY)
 
-- **You are READ-ONLY.** Do NOT edit, write, or create files. Do NOT run Bash. Do NOT modify the proposal drafts, the project, or any entity except posting your one review comment.
+- **You are READ-ONLY.** Do NOT edit, write, or create files. Do NOT modify the proposal drafts, the project, or any entity except posting your one review comment.
+- **Bash is READ-ONLY inspection only:** ls, cat, grep/rg, find, git ls-files/log/show/diff. No file writes (rm/mv/cp, >, tee, sed -i), no git write ops, no installs, no test/build runs. Use it to confirm a file or directory exists before flagging it as missing.
 - **Keep your comment under 800 characters.** PASS items: names only. NOTE items: one-line description. BLOCKER items: evidence + expected/actual.
 - **Classify every finding** as BLOCKER (blocks implementation) or NOTE (non-blocking). Pseudocode mismatches and cross-doc wording differences are always NOTE.
 - **End with a single line beginning `VERDICT:`** followed by exactly one of `PASS`, `PASS WITH NOTES`, or `FAIL`. Has BLOCKERs → FAIL. Only NOTEs → PASS WITH NOTES. Nothing → PASS.
@@ -66,6 +67,7 @@ chorus_get_elaboration({ ideaUuid: "<idea-uuid>" })
 - Do tasks cover ALL requirements from the documents?
 - Are there scope additions not in the original idea?
 - Are there contradictions between documents and tasks?
+- **Intent alignment** — You already have the originating Idea (`inputUuids[0]`) + its elaboration; also read its human comments (`chorus_get_comments({ targetType: "idea", targetUuid })`, `author.type == "user"`). Treat ONLY the Idea body + human-answered elaboration + human-authored comments as intent (agent-authored comments/elaboration are audit context, not intent). Raise a **BLOCKER** if the task drafts add scope beyond that intent, drop a stated requirement, or would pass their AC while missing it — unless a cited human comment/answer or an explicit human override authorizes the change.
 
 ## Finding classification
 

package/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
 ---
@@ -154,7 +154,7 @@ chorus_submit_for_verify({
 })
 ```
 
-Submitting is not final verification. Spawn the required task-reviewer skill through `sessions_spawn` 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 task-reviewer skill through `sessions_spawn` 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
 
@@ -177,7 +177,7 @@ Quick Tasks support sub-agent execution just like proposal-based tasks. **Sessio
 - **Main agent**: create quick tasks, work them yourself, or hand task UUIDs to sub-agents
 - **Sub-agents**: create your own session (`chorus_create_session`), checkin/checkout per task, pass `sessionUuid` to `chorus_update_task` / `chorus_report_work`, and close the session on exit — see `/develop` for the full manual protocol
 
-> OpenClaw has no Agent Teams / `TeamCreate` primitive; if you need to run several quick tasks, work them sequentially as the main agent (or dispatch generic sub-agents one at a time).
+> There is no team object to create: to run several quick tasks in parallel, dispatch one sub-agent per task with `sessions_spawn`, issuing them in a single message. If `sessions_spawn` is unavailable or workers fail repeatedly, work the tasks sequentially as the main agent.
 
 ---
 

package/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
 ---
@@ -67,12 +67,12 @@ Key responsibilities:
 When reviewing proposals, tasks, or an Idea's final aggregate code change, get an independent VERDICT before approving/verifying/shipping. On OpenClaw there is **no PostToolUse hook** to remind you — invoke the review yourself, inline.
 
 1. **Preferred — spawn a reviewer sub-agent.** Use the OpenClaw `sessions_spawn` tool to spawn a sub-agent whose `task` tells it to **invoke the `/proposal-reviewer` skill** (for proposals), the `/task-reviewer` skill (for tasks), or the `/code-reviewer` skill (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**) — all bundled with this plugin — against the entity. Wait for it (poll the `subagents` tool or use `sessions_yield` — do NOT detach; you must have the VERDICT before proceeding). The sub-agent inherits the plugin skills, so the reviewer skill is available to it; it posts a VERDICT comment with detailed findings. Example task prompt: `Run the /proposal-reviewer skill to review proposalUuid <uuid>; post your VERDICT comment when done.`
-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:
+2. **Read the VERDICT.** After the reviewer completes, call `chorus_get_comments` and find THIS round's `VERDICT:` comment — the one posted after your dispatch, not an older round's. 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). For a **code-review gateway** FAIL, do not reopen the verified tasks — instead fix via the **quick-dev** workflow (`/quick-dev`): `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. Fix the specific BLOCKERs listed in the comment before resubmitting.
-3. **No new VERDICT comment?** The sub-agent 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 (step 5).
-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 — review it yourself (no `sessions_spawn` on the host).** If spawning is unavailable (disabled by policy, or the spawn fails), perform the review yourself as a **focused, read-only pass** using the quality checklists in the workflows below: read the entity, its comments, and the relevant documents/code, run read-only test/build commands where applicable, and do NOT modify anything. Then record your VERDICT via `chorus_add_comment` ending with a `VERDICT:` line (PASS / PASS WITH NOTES / FAIL), classifying every finding as BLOCKER or NOTE. The `/proposal-reviewer`, `/task-reviewer`, and `/code-reviewer` skills are the authoritative checklists for this manual pass — read the relevant one and follow its procedure.
 
 ---
@@ -332,7 +332,7 @@ chorus_pm_update_document({ documentUuid: "<doc-uuid>", content: "Updated..." })
 - **Unblock the team** — Prioritize proposal reviews to keep PM and Developer work flowing
 - **Use delete sparingly** — Prefer closing over deleting; closing preserves history
 - **Document decisions** — Use comments to explain approval/rejection reasoning
-- **Verify between waves** — In sequential wave execution, verify tasks to `done` between waves to unblock downstream dependencies
+- **Verify between waves** — In wave-based execution, verify tasks to `done` between waves to unblock downstream dependencies
 
 ---
 

package/skills/spec-lite/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: spec-lite
+description: Lightweight, Chorus-native local specs for Chorus PM workflows on OpenClaw — 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 (OpenClaw plugin)
+
+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.
+
+> **Tool namespace:** Chorus MCP tools are exposed under a `chorus__` prefix on OpenClaw (e.g.
+> `chorus__chorus_pm_add_document_draft`). Bare names are used in prose for readability — prepend
+> `chorus__` when invoking the MCP tools directly. **Document-mirror calls do NOT go through the MCP
+> harness** — they use the `chorus` CLI (`chorus mcp call`, preferred) or the `chorus-api.sh` wrapper
+> (fallback), independent of the `chorus__` namespacing (see Mirror below).
+
+## Mode (how you got here)
+
+**OpenClaw has no SessionStart hook and no injected `## Spec Mode` value** — unlike the Claude Code /
+Codex / Pi ports, nothing precomputes the mode into your context. The mode is **resolved by sourcing
+the resolver the plugin ships** (`bin/resolve-spec-mode.sh`, byte-identical to the Claude Code copy),
+the moment a stage skill reaches its spec-mode step — see `openspec-aware` §1 for the locate-and-source
+block. Never re-derive the rule from prose. You can also print the resolved mode any time with **`/chorus spec`** (or the
+`## /chorus status` block). You are here because that resolution returned **`lite`**; if it returned
+anything else, this skill is a no-op — return to the caller. (For the record, the 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` (resolved by the shipped resolver, `openspec-aware` §1; 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 the `chorus-api.sh` wrapper + `json_encode_file`
+(`openspec-aware` §3.6; the OpenClaw wrapper is invoked as `chorus-api.sh mcp-tool <tool> "$PAYLOAD"`).
+**`<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/skills/task-reviewer/SKILL.md

@@ -4,7 +4,7 @@ description: Adversarial verification of a submitted Chorus task against its AC
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.2"
+  version: "0.18.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -58,6 +58,10 @@ chorus_get_document({ documentUuid: "<doc-uuid>" })
 
 **Hallucination check:** Flag anything that looks LLM-fabricated as NOTE — API signatures, CLI flags, config keys, model IDs, endpoint URLs, package names, or any external detail the developer likely wrote from memory.
 
+**Step 7: Intent alignment**
+
+Resolve the originating Idea (this task's proposal → `inputUuids[0]`) and read its body + human-answered elaboration + human-authored comments (`answeredBy.type` / `author.type == "user"`; agent-authored entries are audit context, not intent). Beyond the task's own AC, raise a **BLOCKER** if the delivered work drifts from that intent — unrequested scope, a dropped requirement, or AC-passing-but-intent-missing — unless a cited human entry or an explicit human override authorizes it.
+
 ## Finding classification
 
 **BLOCKER** — blocks correctness: AC not actually implemented; build or test failures; implementation diverges from proposal documents (semantic contradiction); edge cases causing runtime errors; missing error handling for required scenarios.

package/skills/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
 ---
@@ -15,7 +15,7 @@ Full-auto AI-DLC pipeline. User provides a prompt; agent drives the entire lifec
 
 > **Tool namespace:** Chorus tools are exposed by the connected MCP server under a `chorus__` prefix on OpenClaw (e.g. `chorus__chorus_pm_create_proposal`). Bare names are used below for readability — prepend `chorus__` when invoking. See `/chorus` for the full rule.
 
-> **OpenClaw adaptations summarized (details inline below):** (1) elaboration is **self-answered as plain text** — no `AskUserQuestion`, no user interaction; (2) reviewers run **inline** after each submit — spawn a sub-agent with the OpenClaw `sessions_spawn` tool and tell it to run the `/proposal-reviewer` or `/task-reviewer` skill, with a read-only self-review fallback when `sessions_spawn` is unavailable; (3) sessions are **manual** if you dispatch sub-agents (no SubagentStart hook); (4) task execution is **sequential main-agent waves** — OpenClaw has no Agent Teams / `TeamCreate` primitive.
+> **OpenClaw adaptations summarized (details inline below):** (1) elaboration is **self-answered as plain text** — no `AskUserQuestion`, no user interaction; (2) reviewers run **inline** after each submit — spawn a sub-agent with the OpenClaw `sessions_spawn` tool and tell it to run the `/proposal-reviewer` or `/task-reviewer` skill, with a read-only self-review fallback when `sessions_spawn` is unavailable; (3) sessions are **manual** if you dispatch sub-agents (no SubagentStart hook); (4) task execution dispatches **one sub-agent per unblocked task via `sessions_spawn`** (whole wave in one message), falling back to **sequential main-agent waves** when `sessions_spawn` is unavailable or workers fail repeatedly — there is no team object to create first.
 
 ---
 
@@ -25,7 +25,7 @@ Full-auto AI-DLC pipeline. User provides a prompt; agent drives the entire lifec
 
 1. **Planning** -- create project, idea, self-elaboration, proposal with docs & tasks
 2. **Proposal Review** -- proposal-reviewer adversarial loop
-3. **Execution** -- sequential, dependency-ordered task execution by the main agent
+3. **Execution** -- dependency-ordered waves: one worker sub-agent per unblocked task, or sequential main-agent execution as fallback
 4. **Verification** -- task-reviewer adversarial loop + admin verify
 5. **Report** -- completion summary
 
@@ -42,7 +42,8 @@ Full-auto AI-DLC pipeline. User provides a prompt; agent drives the entire lifec
   Admin Approve --> Tasks materialize
        |
        v
-  Sequential wave execution (main agent: loop chorus_get_unblocked_tasks)
+  Wave execution (loop chorus_get_unblocked_tasks; one sessions_spawn worker
+                  per task, or sequential main-agent fallback)
        |  (implement task + task-reviewer per task)
        v
   Admin Verify each task --> unblock next
@@ -188,21 +189,19 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
 
 #### Step 1.4: Create Proposal
 
-1. **Detect OpenSpec mode (inline).** Load the `openspec-aware` skill and run its **§1 inline three-check detection** (`CHORUS_OPENSPEC_MODE != "off"`, an `openspec/` directory at the project root, and the `openspec` CLI on `PATH`).
+1. **Resolve the spec mode (inline).** OpenClaw has no SessionStart hook to precompute it — so you resolve the **whole** contract yourself, not just "is OpenSpec active". Load the `openspec-aware` skill and run its **§1 resolution block (which sources the plugin's shipped `bin/resolve-spec-mode.sh`)**, which yields one of `lite` / `openspec` / `off` (the canonical resolver, byte-identical to the Claude Code copy; `/chorus spec` prints the same result from the TS mirror `src/spec-mode.ts`). Rule: an explicit `CHORUS_SPEC_MODE` wins; when unset, **OpenSpec is the default whenever usable** (`CHORUS_OPENSPEC_MODE` ≠ `off`, an `openspec/` directory at the project root, and the `openspec` CLI on `PATH`), else **spec-lite**. Route: `openspec` (usable) → **2a**; `off` → **2b**; `lite` → **2c**. If the resolution says the mode **cannot be honored** (explicit `CHORUS_SPEC_MODE=openspec` but OpenSpec unusable), **halt** and surface it — do NOT fall back or enter 2a with no OpenSpec.
 
-   > **OpenClaw note:** there is no Claude Code SessionStart hook to precompute `CHORUS_OPENSPEC_ACTIVE`. You must run the three checks yourself, inline, here. This is mandatory — yolo runs unattended, so silently picking the wrong mode is exactly the failure scenario the detection contract exists to prevent.
+   > **OpenClaw note:** this is mandatory — yolo runs unattended, so silently picking the wrong mode is exactly the failure scenario the resolution contract exists to prevent.
 
-   - All three checks pass → spec-driven branch (sub-step 2a below).
-   - Any check fails (or `CHORUS_OPENSPEC_MODE=off`) → free-form branch (sub-step 2b below).
-
-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>"]
    })
@@ -210,7 +209,7 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
 
    Then branch:
 
-   **2a. OpenSpec mode (all three checks pass).** Follow `openspec-aware` §3 end-to-end:
+   **2a. OpenSpec mode (resolved mode = openspec, usable).** Follow `openspec-aware` §3 end-to-end:
    - Pick `$SLUG`, run `openspec new change "$SLUG"` (§3.1–§3.2).
    - Author `proposal.md`, `design.md`, and one `specs/<capability>/spec.md` per capability locally on disk (§3.3). ADDED Requirements only; per-spec fallback to free-form Markdown if MODIFIED/REMOVED is needed.
    - Define the `chorus_check_response` helper (§6); prefer `chorus mcp call … --arg-file content=<file>` for mirrors (§3.4/§3.6) — the bash-wrapper fallback's `json_encode_file` is only needed when `chorus` is not on `PATH`.
@@ -220,7 +219,7 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
 
    Then continue to step 3 (task drafts).
 
-   **2b. Free-form mode (any check fails).** 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 +230,8 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
    })
    ```
 
+   **2c. spec-lite mode (resolved mode = lite).** Load the `spec-lite` skill. 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 mcp-tool …` 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
@@ -272,6 +273,20 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
 
 ---
 
+### 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 `sessions_spawn` and wait by polling the `subagents` tool or via `sessions_yield` — do **not** detach. The verdict is the `VERDICT:` comment the reviewer posts, not the spawn result.
+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
 
 > **OpenClaw difference:** there is no PostToolUse hook injecting a "spawn the reviewer" reminder. Run the reviewer **inline**, right after `chorus_pm_submit_proposal`.
@@ -288,7 +303,7 @@ Then:
    ```
    chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
    ```
-   Look for the most recent comment containing `VERDICT:`.
+   Look for THIS round's `VERDICT:` comment — the one posted after your dispatch, not an older round's.
 
 2. **Act on the VERDICT:**
 
@@ -322,15 +337,15 @@ Then:
           Proposal UUID: <uuid>"
    ```
 
-4. **No new VERDICT comment after a spawned reviewer returns?** It 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 still no VERDICT, fall back to reviewing manually and post the VERDICT yourself — 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.
 
 ---
 
-### Phase 3: Task Execution (Sequential Waves)
+### Phase 3: Task Execution (Waves)
 
 After proposal approval, tasks exist in `open` status. Execute them in dependency-ordered waves.
 
-> **OpenClaw difference:** OpenClaw has **no Agent Teams / `TeamCreate` primitive**. Run waves **sequentially as the main agent**: loop `chorus_get_unblocked_tasks`, implement each ready task yourself, verify it, then loop again for the next wave. Do NOT call `TeamCreate` — it does not exist on OpenClaw. (Under the Claude Code plugin, each wave can be dispatched in parallel via `TeamCreate`; that is a Claude-Code-only optimization that degrades to the sequential loop here.)
+> **OpenClaw difference:** there is no team or group object to create — parallelism comes from dispatching **one sub-agent per unblocked task** with OpenClaw's own `sessions_spawn` tool, issuing the whole wave in a single message. If your host does not expose `sessions_spawn`, or spawned workers fail repeatedly, run waves **sequentially as the main agent**: loop `chorus_get_unblocked_tasks`, implement each ready task yourself, verify it, then loop again for the next wave. The sequential loop below is written for that fallback and is always safe; see `/develop` §"Optional: sub-agent dispatch" for the parallel form (workers need the manual session instructions, since there is no SubagentStart hook).
 
 ```
 wave = 1
@@ -363,7 +378,7 @@ loop:
   wave += 1
 ```
 
-> **Optional sub-agent dispatch:** if your OpenClaw host supports generic worker sub-agents (not Agent Teams), you may hand one task to a sub-agent at a time. Because there is no SubagentStart hook, the worker prompt **must** include the manual session instructions explicitly — see `/develop` "Optional: sub-agent dispatch". The main agent still owns review + verification. This does not change the sequential, wave-by-wave structure above.
+> **Parallel form:** to run a wave in parallel instead of serially, dispatch one worker sub-agent per unblocked task with `sessions_spawn`, issuing the whole wave in a single message, then wait for the wave before verifying. Because there is no SubagentStart hook, each worker prompt **must** include the manual session instructions explicitly — see `/develop` "Optional: sub-agent dispatch". The main agent still owns review + verification, and the wave-by-wave dependency structure above is unchanged.
 
 ---
 
@@ -393,7 +408,7 @@ for the just-submitted task:
 
   # 3. Read task-reviewer VERDICT
   comments = chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
-  # Find the most recent comment containing "VERDICT:"
+  # Find THIS round's "VERDICT:" comment — the one posted after your dispatch, not an older round's
 
   # 4. Act on VERDICT — three possible outcomes:
   if VERDICT is "PASS":
@@ -429,7 +444,7 @@ 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 a spawned 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, run only the core tests, and post your VERDICT within the first 12 turns."* If still no VERDICT, fall back to reviewing manually and post the VERDICT yourself — 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.
 
 ---
 
@@ -450,7 +465,7 @@ ESCALATE: "Idea '{title}' failed code review after {maxCodeReviewRounds} rounds.
            Last BLOCKERs: <list>. Manual intervention needed. Idea UUID: <uuid>"
 ```
 
-**No VERDICT comment after the code-reviewer returns?** It exhausted its turn budget (larger than the task-reviewer's because it reviews the whole feature). Respawn ONCE with a concise-budget hint; if still silent, fall back to a manual read-only pass and post the VERDICT yourself.
+**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 gateway is **behavioral** like the other two reviewers: its verdict is advisory and does not change the Idea's stored status; the orchestrator honors it. It runs **before** the completion report so the report is never written while a FAIL is outstanding.
 

package/src/commands.ts

@@ -1,4 +1,5 @@
 import type { ChorusMcpClient } from "./mcp-client.js";
+import { resolveSpecModeFromEnv, type SpecModeResult } from "./spec-mode.js";
 
 // ===== Response types from Chorus MCP tools =====
 //
@@ -62,7 +63,7 @@ interface AssignmentsResponse {
 
 // ===== Skill catalog =====
 //
-// All 9 skills bundled with the Chorus OpenClaw plugin
+// All 11 skills bundled with the Chorus OpenClaw plugin
 // (packages/openclaw-plugin/skills/*/SKILL.md). The `name` here matches each
 // skill's SKILL.md frontmatter `name`, which is exactly the slash command
 // OpenClaw exposes (see invocation hint below).
@@ -76,7 +77,8 @@ const PLUGIN_SKILLS = [
   { name: "quick-dev", description: "Skip Idea→Proposal — create tasks directly, execute, verify" },
   { name: "review", description: "Approve/reject proposals, verify tasks, project governance" },
   { name: "yolo", description: "Full-auto AI-DLC pipeline — from prompt to done" },
-  { name: "openspec-aware", description: "Opt-in OpenSpec authoring for PM workflows when the openspec CLI is present" },
+  { name: "openspec-aware", description: "OpenSpec-mode authoring for PM workflows (the default when openspec/ + CLI present)" },
+  { name: "spec-lite", description: "Chorus-native lightweight local specs (.chorus/specs/<slug>/) — the fallback when OpenSpec isn't usable" },
   { name: "chorus-cli", description: "Install, configure agents (chorus agents add|remove|list), env vars, and chorus mcp operations" },
 ] as const;
 
@@ -104,7 +106,28 @@ function formatSkillsList(): string {
   ].join("\n");
 }
 
-function formatStatus(checkin: CheckinResponse, connectionStatus: string): string {
+// Spec-mode lines for the status block. Since OpenClaw has no SessionStart hook
+// to precompute the mode, `/chorus` is the resolver's real runtime caller and the
+// user-visible surface: it prints `CHORUS_SPEC_MODE=<mode> (<reason>)`, the
+// `CHORUS_OPENSPEC_ACTIVE=1` line only for a usable OpenSpec, and a halt warning
+// when an explicit `=openspec` cannot be honored. The stage skills resolve the
+// SAME contract inline (see src/spec-mode.ts — the single source of truth).
+function specModeLines(spec: SpecModeResult): string[] {
+  const lines = [`CHORUS_SPEC_MODE=${spec.specMode} (${spec.specReason})`];
+  if (spec.chorusOpenspecActive) {
+    lines.push(`CHORUS_OPENSPEC_ACTIVE=1 (${spec.openspecUsableReason})`);
+  }
+  if (spec.specFail) {
+    lines.push(`WARNING: spec-mode halt — ${spec.specFail}`);
+  }
+  return lines;
+}
+
+function formatStatus(
+  checkin: CheckinResponse,
+  connectionStatus: string,
+  spec: SpecModeResult,
+): string {
   const projects = Object.values(checkin?.activeProjects ?? {});
   const activeIdeaTotal = projects.reduce(
     (total, p) => total + (p.activeIdeaCount ?? 0),
@@ -116,11 +139,26 @@ function formatStatus(checkin: CheckinResponse, connectionStatus: string): strin
     `Active projects: ${projects.length} (${activeIdeaTotal} active idea(s))`,
     ...projects.map((p) => `  - ${p.name ?? "(unnamed)"}: ${p.activeIdeaCount ?? 0}`),
     `Notifications: ${checkin?.notifications?.unread ?? 0} unread`,
+    ...specModeLines(spec),
     `Skills: ${PLUGIN_SKILLS.map((s) => s.name).join(", ")}`,
   ];
   return lines.join("\n");
 }
 
+// Detailed spec-mode view for `/chorus spec` — the mode + reason, the openspec
+// usability breakdown, and the install hint when OpenSpec is merely missing.
+function formatSpec(spec: SpecModeResult): string {
+  const lines = [
+    "Spec mode (resolved inline — OpenClaw has no SessionStart hook):",
+    ...specModeLines(spec).map((l) => `  ${l}`),
+    `  OpenSpec usable: ${spec.openspecUsable ? "yes" : "no"} (${spec.openspecUsableReason})`,
+  ];
+  if (spec.openspecHint) {
+    lines.push(`  Enable OpenSpec: ${spec.openspecHint}`);
+  }
+  return lines.join("\n");
+}
+
 function formatTaskList(taskTracker: Record<string, TaskTrackerProject> | undefined): string {
   const lines: string[] = [];
   let total = 0;
@@ -159,6 +197,7 @@ const HELP_TEXT = [
   "Chorus commands:",
   "  /chorus           Show connection status and summary",
   "  /chorus status    Same as above",
+  "  /chorus spec      Show the resolved spec mode (OpenSpec / spec-lite / off)",
   "  /chorus tasks     List assigned tasks",
   "  /chorus ideas     List assigned ideas",
   "  /chorus skills    List available Chorus skills",
@@ -171,28 +210,40 @@ function errorText(prefix: string, err: unknown): string {
 
 // ===== Registration =====
 
+// Default spec-mode resolver: wires the real env + cwd. Injectable so the
+// command test can pass a deterministic result without touching the disk/PATH.
+function defaultResolveSpec(): SpecModeResult {
+  return resolveSpecModeFromEnv(process.env, process.cwd());
+}
+
 export function registerChorusCommands(
   api: { registerCommand: (command: unknown) => void },
   mcpClient: ChorusMcpClient,
-  getStatus: () => string
+  getStatus: () => string,
+  resolveSpec: () => SpecModeResult = defaultResolveSpec,
 ): void {
   api.registerCommand({
     name: "chorus",
-    description: "Chorus plugin commands: status, tasks, ideas, skills",
+    description: "Chorus plugin commands: status, spec, tasks, ideas, skills",
     acceptsArgs: true,
     async handler(ctx: { args?: string }) {
       const sub = (ctx.args ?? "").trim().toLowerCase();
 
-      // /chorus or /chorus status — connection + checkin summary via slim client.
+      // /chorus or /chorus status — connection + checkin + spec-mode summary.
       if (!sub || sub === "status") {
         try {
           const checkin = (await mcpClient.callTool("chorus_checkin", {})) as CheckinResponse;
-          return { text: formatStatus(checkin, getStatus()) };
+          return { text: formatStatus(checkin, getStatus(), resolveSpec()) };
         } catch (err) {
           return { text: errorText("Failed to check in", err), isError: true };
         }
       }
 
+      // /chorus spec — the resolved spec mode (the resolver's user-visible surface).
+      if (sub === "spec") {
+        return { text: formatSpec(resolveSpec()) };
+      }
+
       // /chorus tasks — assigned tasks via chorus_get_my_assignments.
       if (sub === "tasks") {
         try {