@chorus-aidlc/chorus 0.18.1 → 0.19.1

package/.next/standalone/public/skill/task-reviewer-chorus/SKILL.md

@@ -107,6 +107,19 @@ Pick 2-3 probes that fit the specific task — boundary values, missing fields,
 
 **Hallucination check:** Flag anything that looks LLM-fabricated as a **NOTE** — API signatures, CLI flags, config keys, model IDs, endpoint URLs, package names, or any external detail the developer likely wrote from memory rather than referencing docs.
 
+**Code quality and correctness beyond the AC — checked by default**
+
+The AC were written before the code existed: they describe what to build, never how well it was built. Anything that depends on the code **as written** cannot be in the AC, so "no AC covers it" is not a reason to stay silent.
+
+- **Correctness without an AC.** Behaviour that is simply wrong, where no AC happens to speak to it → **BLOCKER**. You do not need an acceptance criterion to report a bug.
+- **Reimplementation.** Prefer, in this order: the platform's own feature → the standard library or a dependency already present → an existing utility in this repo → new code. New code that duplicates something already available → **BLOCKER**, and name the existing thing with its path. "This could be shorter" with nothing named is not a finding.
+- **Security in this task's own code.** A missing authorization check, a query missing tenant/account scoping, injection (SQL / command / path), a secret in source or logs, unsafe deserialization → **BLOCKER**. Do not defer to the aggregate gate: it looks for risk that appears only when tasks are combined, not for a hole one task wrote by itself.
+- **Tests that cannot fail.** Ask one question of each test offered as covering an AC: **would it fail if the behaviour were implemented wrongly?** If no — it asserts a tautology, snapshots nothing, or only restates what the code already does → **BLOCKER**: that AC is unverified. Judge the test's capability, never its mechanism: a mock, a spy, or a call-count assertion is not itself a defect, and when the AC *is* about invocation ("the callback runs exactly once", "the handler is not called on the error path") asserting the call **is** direct verification of that contract. Thin-but-real tests → NOTE.
+- **Silent failure.** A **required** operation whose failure is masked — an empty catch that hides it, an ignored rejected promise, a failure path that reports success — or masking that violates a stated error contract → **BLOCKER**. Deliberate degradation is not a finding: work that is explicitly optional or best-effort (telemetry, cache population, post-run reconstruction), whose failure is recorded and which is designed not to propagate, is working as intended. Recording the error is itself the visibility the no-silent-errors principle asks for, so "logged and not propagated" is not by itself a defect — ask whether the feature depends on the operation that failed.
+- **Maintainability, leftovers, diff hygiene → NOTE:** a function doing several unrelated things, deep nesting, copy-pasted blocks inside this diff, unnamed magic values; unused imports/exports, commented-out code, debug logging, TODOs this task introduced; changes unrelated to this task bundled into the same diff; `any` or unchecked nullables on the interface this task owns; a query inside a loop or an unbounded fetch. Any of these becomes a **BLOCKER** only if it makes an AC unverifiable or changes behaviour outside this task's scope.
+
+**Severity rule.** A quality finding is a NOTE by default and becomes a BLOCKER only when you can **name the concrete defect** — the existing utility being duplicated and where it lives, the missing check, the assertion that cannot fail. Taste never blocks: if you cannot point at it, it is a NOTE or it is nothing. Report the cheapest concrete change, never a redesign.
+
 ### Step 6: 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.
@@ -140,16 +153,64 @@ Classify **every** finding as exactly one of:
 - Style / naming suggestions.
 - Hallucination-risk specifics (SDK versions, API paths, CLI flags, model IDs).
 
-**Rules:** Pseudocode inconsistencies → **always NOTE**. Cross-document wording differences → **always NOTE**. Only functional / behavioral issues → BLOCKER.
+**Rules:** Style, naming, and pseudocode inconsistencies → **always NOTE**. Functional, security, and verification-integrity issues → BLOCKER. A quality finding blocks only when you can name the concrete defect.
+
+Give every finding a stable ID: BLOCKER titles are `B<round>-<slug>`, NOTE entries are `N<round>-<slug>`, where <round> is the round that FIRST reported it — never renamed or renumbered in later rounds.
+Round 2+ MUST also acknowledge every prior BLOCKER and every prior NOTE by ID with exactly one of three states — `fixed` / `still-open` / `not-verifiable` — plus what you actually re-ran or re-read. Silence is not a fix: only an explicit `fixed` closes a finding. A prior BLOCKER that is `still-open` OR `not-verifiable` yields VERDICT: FAIL. An unresolved NOTE never yields worse than PASS WITH NOTES.
 
 ---
 
+## What to report / what NOT to report
+
+This list is specific to the task gate. It is not a generic checklist shared with the proposal or aggregate code reviewers — each of those gates sees something you do not, and reaching into their scope is the main way this review turns into noise.
+
+**DO report:**
+- The result of running this task's tests/build, quoting the real output — exact command, exit code, the relevant lines.
+- **Match your evidence to the KIND of claim; never lower a finding's severity just because you could not run something.** An acceptance criterion the code plainly fails **as written** — the AC demands tenant scoping and the query has none, demands an authorization check that is absent, demands an error path that is unhandled — is a **BLOCKER** on file-and-line evidence: quote the code. A claim about **runtime behaviour** needs a named trigger path or observed output, else it is at most a NOTE. Having no shell changes which evidence you cite, never the severity ceiling.
+- Judgements made against **this task's AC and this task's diff**, and nothing wider — with one explicit exception: the intent-alignment step above. Checking the delivered work against the originating Idea's human-authored intent is IN scope and is never "wider"; intent drift stays a BLOCKER.
+- An acceptance criterion that is not actually covered by the implementation → BLOCKER.
+- Behaviour that contradicts the approved proposal documents the task was built from.
+
+**DO NOT report:**
+- **Never report something as missing without first confirming its absence with read-only Bash** (`ls` / `grep` / `rg` / `find` / `git ls-files`), and cite the command you ran. An unverified "X is missing" is the single most common false BLOCKER.
+- **Do not re-litigate decisions inside an already-approved proposal.** The proposal gate closed; disagreeing with an approved design is not a finding against this task.
+- **Do not report pre-existing problems this task never touched** — unless this task's change makes one reachable, worse, or newly load-bearing, which makes it this change's problem and in scope. If the task's diff did not introduce it, it is not this review's finding.
+- **Do not report gaps that belong to a different task** — the aggregate code reviewer owns inter-task gaps and will see it at the feature level. Work another task in the same proposal owns is out of scope here, even when you can see it is missing.
+- **Never raise a BLOCKER for absent end-to-end integration tests.** Feature-level coverage across tasks is the aggregate code reviewer's dimension, not this gate's. This task's own AC is the standard here.
+
 ## Round 2+ Awareness
 
 You may receive the current review round number in your context.
 
 - **Round 1** — Full review at normal strictness.
-- **Round 2+** — Focus ONLY on whether the previous BLOCKERs were fixed. Do NOT introduce new NOTEs on areas not flagged in earlier rounds. Round 1 already did the full-depth review. In Round 2+, re-read only the specific files and re-run only the specific tests/commands tied to previous BLOCKERs — do not re-scan unrelated code, do not rerun the full suite, and do not probe new areas. If all previous BLOCKERs are resolved → `VERDICT: PASS` (or `VERDICT: PASS WITH NOTES` if old NOTEs remain). Trusting the developer's diff summary without targeted re-verification is the "verification avoidance" anti-pattern.
+- **Round 2+** — Focus ONLY on whether the previous BLOCKERs were fixed. Do NOT introduce new NOTEs on areas not flagged in earlier rounds. Round 1 already did the full-depth review. In Round 2+, re-read only the specific files and re-run only the specific tests/commands tied to prior findings (BLOCKERs and NOTEs alike — a prior NOTE you may not re-read is a NOTE you can never close) — do not re-scan unrelated code, do not rerun the full suite, and do not probe new areas. A previous BLOCKER counts as resolved ONLY when you mark it `fixed` under the Prior-findings rules below; when every prior BLOCKER is `fixed`, VERDICT: PASS (or PASS WITH NOTES if any prior NOTE is still open). Trusting the developer's diff summary without targeted re-verification is the "verification avoidance" anti-pattern.
+
+## Prior findings: stable IDs and cross-round acknowledgement
+
+**Stable IDs.** Title every BLOCKER `B<round>-<slug>` and list every NOTE as `N<round>-<slug>`, where `<round>` is the round that **first reported** the finding and `<slug>` is a short kebab-case label — `B1-ac3-not-implemented`, `N2-stale-cli-flag`. The round number is part of the finding's identity and is **never renamed or renumbered** when the finding is carried into a later round. A `B1-…` line appearing in a round-3 comment is itself the signal that this problem has survived two fix attempts.
+
+**Acknowledgement.** In round 2 and later, list **every** prior BLOCKER and **every** prior NOTE by ID under a `**Prior findings:**` block, each with exactly one of these three states and with the command you actually re-ran this round:
+
+- `fixed` — re-verified this round; cite the command and its result.
+- `still-open` — re-checked, and the problem is still there.
+- `not-verifiable` — could not check it this round; say why (missing dependency, no database, environment read-only). Never counts as fixed.
+
+Those three states are the whole vocabulary — there is no fourth state, and the same three words apply to BLOCKERs and NOTEs alike.
+
+Three rules govern what the states mean for the verdict:
+
+- **Silence is not a fix.** Not re-reporting a finding does not close it. Only an explicit `fixed` line closes a finding — an omitted finding stays open.
+- **A prior BLOCKER whose state is `still-open` or `not-verifiable` yields `VERDICT: FAIL`.** Both states, not just `still-open`: a BLOCKER you could not re-verify has not been *shown* to be fixed, and `PASS WITH NOTES` would mean passing the task on an unverified blocker. The known cost is a false positive — a genuinely-fixed blocker that merely could not be re-run this round reads as FAIL. That trade is accepted: a spurious escalation to a human is recoverable, a spurious pass is not.
+- **NOTEs never escalate.** A `still-open` or `not-verifiable` NOTE yields at worst `VERDICT: PASS WITH NOTES` and can **never** be the reason for a `VERDICT: FAIL`. Only BLOCKERs block.
+
+**How the NOTE limit composes with the round-2+ rule above.** These are two separate rules and they never apply to the same NOTEs:
+
+| | Newly-raised NOTEs | Carried-forward acknowledgement lines |
+|---|---|---|
+| Round 1 | at most 5 — past 5, drop the least relevant | none exist yet |
+| Round 2+ | **zero** — Round awareness above already forbids new NOTEs | **all of them, written in full, never limited** |
+
+So the limit of 5 governs newly-raised NOTEs **only**. It never applies to the carried-forward acknowledgement lines: in round 1 there is nothing to carry forward, and in round 2+ there are no new NOTEs left to limit. Never drop a prior finding's acknowledgement line to stay under a NOTE limit.
 
 ---
 
@@ -177,19 +238,24 @@ Do NOT invent other verdicts like "APPROVE" or "OK" — automation greps for the
 
 ## Output Format (Required)
 
-Keep total output **under ~800 characters** — be concise. No preamble, no trailing summary paragraph. PASS items: names only. NOTE items: one-line descriptions. BLOCKER items: full evidence (command + output + expected vs actual).
+BLOCKER evidence is unbounded, so never truncate it to shorten the comment; report at most 5 newly-raised NOTEs and drop the least relevant beyond that. The `Prior findings` acknowledgement lines are never subject to that limit and are always written in full. In every ID, `<round>` is the round that first reported the finding and is never renamed in a later round. No preamble, no trailing summary paragraph. PASS items: names only. NOTE items: one-line descriptions. BLOCKER items: full evidence (command + output + expected vs actual).
 
 ```
 ### Review Summary
 
+**Prior findings:** (round 2+ only — omit this block in round 1)
+- B1-<slug>: fixed — `<what you re-ran or re-read>` → <result observed>
+- B1-<other-slug>: still-open — `<what you re-ran or re-read>` → <problem still present>
+- B2-<slug>: not-verifiable — <why you could not check it this round>
+- N1-<slug>: still-open
 **PASS (N):** AC-1 name, AC-2 name, ...
 
 **NOTE (M):**
-- Note-1: [one-line description]
-- Note-2: [one-line description]
+- N<round>-<slug>: [one-line description]
+- N<round>-<slug>: [one-line description]
 
 **BLOCKER (K):**
-### Blocker-1: name
+### B<round>-<slug>
 **Command run:** [exact command executed]
 **Output observed:** [actual output — copy-paste, not paraphrased]
 **Evidence:** [specific finding with file paths, line numbers]

package/.next/standalone/public/skill/yolo-chorus/SKILL.md

@@ -112,6 +112,10 @@ Keep the prompt detailed: the richer the input, the better the auto-generated pr
 
 ---
 
+## Research routing
+
+During planning, follow the Idea and Proposal routes to `research-chorus` (`<BASE_URL>/skill/research-chorus/SKILL.md`) ([shared rules](../research-chorus/SKILL.md)): Idea before formal clarification once focused, Proposal after reusing evidence and only for new gaps or an explicit request. Carry findings and the request context across wakes and brainstorm; do not restart the same investigation on resume. Preserve the existing yolo decision/review gates. A Tracker Research action is research-only even inside a yolo-associated conversation: use the Idea research-only branch, save/report, and return without advancing to elaboration, proposal submission, or development. A yolo request alone does not prove development started; use actual execution facts.
+
 ## Workflow
 
 ### Phase 1: Planning

package/README.ja.md

@@ -38,22 +38,16 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 
 ## 最近の更新
 
+**[v0.19.1](https://chorus-ai.dev/blog/chorus-v0.19.1-release/)** — 軽量 Research を追加し、Idea の要件整理や Proposal の設計時に重要な事実を確認できるようになりました。インライン引用で根拠となる資料を示せるほか、開発開始前なら Tracker から追加調査を依頼できます。
+
+**[v0.19.0](https://chorus-ai.dev/blog/chorus-v0.19.0-release/)** — Cloudflare を参考にレビューの範囲を明確化し、問題の根拠を省略せず、固定 ID で再レビュー時も追跡。タスクレビューでは受け入れ基準に加え、コード品質も標準で確認します。
+
 **[v0.18.0](https://chorus-ai.dev/blog/chorus-v0.18.0-release/)** — OpenSpec を補う、軽量で Git ネイティブなローカル Spec 管理として `spec-lite` を内蔵しました。live session anchor により、デーモンエージェントからの返信が、起点となったエージェントの既存 Idea セッションへ戻ります。
 
 **[v0.17.2](https://chorus-ai.dev/blog/chorus-v0.17.2-release/)** — Pi が正式配布とデーモンウェイクに対応し、`chorus agents run` でローカルのエージェントプロファイルをすぐ切り替えられます。
 
 **[v0.17.0–0.17.1](https://github.com/Chorus-AIDLC/Chorus/releases/tag/v0.17.1)** — 1 つの CLI で各コーディングエージェントに Chorus を導入・更新できるようになりました。Tracker、Graph、Idea 詳細ではデーモンの活動をリアルタイムに確認できます。
 
-**[v0.16.4](https://chorus-ai.dev/blog/chorus-v0.16.4-release/)** — DeepSeek Harness（dsh）が 6 つ目の接続方法に。`@chorus-aidlc/chorus-dsh` バンドルが Chorus のスキル・ペルソナ・MCP 設定を任意の dsh プロファイルに追加します。現時点は対話的な利用のみ、デーモンウェイクは後日対応。
-
-**[v0.16.1](https://chorus-ai.dev/blog/chorus-v0.16.1-release/)** — 1 つの `chorus daemon` が、互いに独立した複数のエージェントを同時に扱えるようになりました。各エージェントは `agents[]` 配列で自分のキー・作業ディレクトリ・バックエンド・権限を持ちます。エージェント同士は @メンションで作業を渡し合え、各ウェイクはそのエージェント自身のプロジェクトディレクトリに届きます。
-
-**[v0.16.0](https://chorus-ai.dev/blog/chorus-v0.16.0-release/)** — エージェントをドキュメントサイト（[doc.chorus-ai.dev](https://doc.chorus-ai.dev)）へ案内する `docs` スキルを追加し、記憶に頼らず現在のドキュメントを読んで回答するようにしました。
-
-**[v0.15.0](https://chorus-ai.dev/blog/chorus-v0.15.0-release/)** — プロジェクト単位の Agent 作業ディレクトリ：各ユーザーがプロジェクト内の Agent ごとにホストと cwd を設定し、デーモンが許可したルートだけを参照できます。割り当て、ウェイク、再開、後続ターンで同じ実行先を使い、進行中のセッションは移動しません。Codex は再開可能なバックエンド thread ID を別に保存し、不要になった Chorus の session 管理手順を削除しました。
-
-**[v0.14.1](https://chorus-ai.dev/blog/chorus-v0.14.1-release/)** — Amazon Kiro CLI が 4 つ目の接続方法になりました（Kiro CLI v2）：`chorus agents add` によるワンコマンドの Kiro プラグイン導入と `--agent kiro` デーモンバックエンド、加えていくつかのデーモン修正。
-
 > 完全な変更履歴：[CHANGELOG.md](CHANGELOG.md)
 
 ---
@@ -63,7 +57,7 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 2 つのコマンドだけです — データベースも Docker も設定ファイルも不要です。
 
 ```bash
-npm install -g @chorus-aidlc/chorus@0.18.1
+npm install -g @chorus-aidlc/chorus@0.19.1
 chorus
 ```
 

package/README.ko.md

@@ -38,22 +38,16 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 
 ## 최근 업데이트
 
+**[v0.19.1](https://chorus-ai.dev/blog/chorus-v0.19.1-release/)** — 가벼운 Research로 Idea 구체화와 Proposal 설계 단계에서 핵심 사실을 확인할 수 있습니다. 인라인 근거 인용으로 주장과 출처를 연결하고, 개발 시작 전에는 Tracker에서 추가 조사를 요청할 수 있습니다.
+
+**[v0.19.0](https://chorus-ai.dev/blog/chorus-v0.19.0-release/)** — Cloudflare를 참고해 리뷰 범위를 명확히 하고, 문제의 근거를 온전히 남기며, 고정 ID로 재검토까지 추적합니다. 태스크 리뷰는 인수 기준 외의 코드 품질도 기본으로 검사합니다.
+
 **[v0.18.0](https://chorus-ai.dev/blog/chorus-v0.18.0-release/)** — OpenSpec을 보완하는 가볍고 Git 친화적인 로컬 Spec 관리 방식으로 `spec-lite`를 내장했습니다. live session anchor를 통해 데몬 에이전트의 응답이 작업을 시작한 에이전트의 기존 Idea 세션으로 돌아갑니다.
 
 **[v0.17.2](https://chorus-ai.dev/blog/chorus-v0.17.2-release/)** — Pi를 정식 패키지와 데몬 웨이크로 사용할 수 있으며, `chorus agents run`으로 로컬 에이전트 프로파일을 빠르게 전환할 수 있습니다.
 
 **[v0.17.0–0.17.1](https://github.com/Chorus-AIDLC/Chorus/releases/tag/v0.17.1)** — 하나의 CLI로 여러 코딩 에이전트에 Chorus를 설치하고 업데이트할 수 있습니다. 이제 Tracker, Graph, Idea 상세 화면에서 데몬 활동도 실시간으로 확인할 수 있습니다.
 
-**[v0.16.4](https://chorus-ai.dev/blog/chorus-v0.16.4-release/)** — DeepSeek Harness(dsh)가 여섯 번째 연결 방식으로 추가됩니다: `@chorus-aidlc/chorus-dsh` 번들이 Chorus의 스킬·페르소나·MCP 설정을 임의의 dsh 프로파일에 추가합니다. 현재는 대화식 사용만, 데몬 웨이크는 추후 지원.
-
-**[v0.16.1](https://chorus-ai.dev/blog/chorus-v0.16.1-release/)** — 이제 하나의 `chorus daemon`이 서로 독립적인 여러 에이전트를 동시에 서비스합니다. 각 에이전트는 `agents[]` 배열로 자신의 키·작업 디렉터리·백엔드·권한을 가집니다. 에이전트끼리 @멘션으로 작업을 넘길 수 있고, 각 웨이크는 해당 에이전트 자신의 프로젝트 디렉터리에 도착합니다.
-
-**[v0.16.0](https://chorus-ai.dev/blog/chorus-v0.16.0-release/)** — 에이전트를 문서 사이트([doc.chorus-ai.dev](https://doc.chorus-ai.dev))로 안내하는 `docs` 스킬을 추가해, 기억에 의존하지 않고 현재 문서를 읽고 답하도록 했습니다.
-
-**[v0.15.0](https://chorus-ai.dev/blog/chorus-v0.15.0-release/)** — 프로젝트별 Agent 작업 디렉터리: 각 사용자가 프로젝트의 Agent마다 호스트와 cwd를 지정하고, 데몬이 허용한 루트만 탐색할 수 있습니다. 배정, 웨이크, 재개, 후속 턴에서 같은 실행 위치를 사용하며 진행 중인 세션은 이동하지 않습니다. Codex는 재개 가능한 백엔드 thread ID를 별도로 저장하고, 더 이상 필요하지 않은 Chorus session 관리 단계를 제거했습니다.
-
-**[v0.14.1](https://chorus-ai.dev/blog/chorus-v0.14.1-release/)** — Amazon Kiro CLI가 네 번째 연결 방식이 되었습니다(Kiro CLI v2): `chorus agents add` 명령 한 줄로 설치하는 Kiro 플러그인과 `--agent kiro` 데몬 백엔드, 여기에 몇 가지 데몬 수정.
-
 > 전체 변경 이력: [CHANGELOG.md](CHANGELOG.md)
 
 ---
@@ -63,7 +57,7 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 두 개의 명령이면 됩니다. 데이터베이스도, Docker도, 설정 파일도 필요 없습니다.
 
 ```bash
-npm install -g @chorus-aidlc/chorus@0.18.1
+npm install -g @chorus-aidlc/chorus@0.19.1
 chorus
 ```
 

package/README.md

@@ -38,22 +38,16 @@ The labels under each stage are the **permissions** an actor needs there — gra
 
 ## What's New
 
+**[v0.19.1](https://chorus-ai.dev/blog/chorus-v0.19.1-release/)** — Lightweight Research checks factual gaps during Idea and Proposal preparation. Inline evidence citations put sources next to claims, and Tracker can request more research before development starts.
+
+**[v0.19.0](https://chorus-ai.dev/blog/chorus-v0.19.0-release/)** — Cloudflare-inspired reviewer rules: clearer scope, complete blocker evidence, and stable finding IDs across rounds. Task reviews now check code quality beyond acceptance criteria.
+
 **[v0.18.0](https://chorus-ai.dev/blog/chorus-v0.18.0-release/)** — Built-in `spec-lite` adds a lightweight, Git-native local spec workflow alongside OpenSpec. Live session anchors let daemon agents return replies to the initiating agent's existing Idea session.
 
 **[v0.17.2](https://chorus-ai.dev/blog/chorus-v0.17.2-release/)** — Pi is now a published, wakeable Chorus agent, and `chorus agents run` switches local agent profiles with one command.
 
 **[v0.17.0–0.17.1](https://github.com/Chorus-AIDLC/Chorus/releases/tag/v0.17.1)** — One CLI now installs and refreshes Chorus across your coding agents. Live daemon activity is visible directly on Ideas in Tracker, Graph, and detail views.
 
-**[v0.16.4](https://chorus-ai.dev/blog/chorus-v0.16.4-release/)** — DeepSeek Harness (dsh) is the sixth way to connect: the `@chorus-aidlc/chorus-dsh` bundle drops Chorus's skills, persona, and MCP config into any dsh profile. Interactive for now; daemon wake comes later.
-
-**[v0.16.1](https://chorus-ai.dev/blog/chorus-v0.16.1-release/)** — One `chorus daemon` now serves many independent agents at once — each with its own key, working directories, backend, and permissions via an `agents[]` array — and agents can hand work to each other by @-mention, with each wake landing in that agent's own project directory.
-
-**[v0.16.0](https://chorus-ai.dev/blog/chorus-v0.16.0-release/)** — A `docs` skill that points agents at the live docs site ([doc.chorus-ai.dev](https://doc.chorus-ai.dev)), so they answer from the current docs instead of reciting from memory.
-
-**[v0.15.0](https://chorus-ai.dev/blog/chorus-v0.15.0-release/)** — Project-level Agent working directories: each user can bind every Agent in a project to a host and cwd, browse only daemon-approved roots, and use the same target across assignment, wake, resume, and later turns without moving active sessions. Codex now persists its resumable backend thread ID separately and drops obsolete Chorus session-management steps.
-
-**[v0.14.1](https://chorus-ai.dev/blog/chorus-v0.14.1-release/)** — Amazon Kiro CLI is the fourth way to connect (Kiro CLI v2): a one-command Kiro plugin via `chorus agents add` and a `--agent kiro` daemon backend, plus daemon fixes.
-
 > Full changelog: [CHANGELOG.md](CHANGELOG.md)
 
 ---
@@ -63,7 +57,7 @@ The labels under each stage are the **permissions** an actor needs there — gra
 Two commands. No database, no Docker, no config files.
 
 ```bash
-npm install -g @chorus-aidlc/chorus@0.18.1
+npm install -g @chorus-aidlc/chorus@0.19.1
 chorus
 ```
 

package/README.zh.md

@@ -29,22 +29,16 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 
 ## 最近更新
 
+**[v0.19.1](https://chorus-ai.dev/zh/blog/chorus-v0.19.1-release/)**：新增轻量 Research，在 Idea 澄清和 Proposal 设计时查证关键事实；行内证据引用让结论直接关联来源。开发开始前，也可从 Tracker 发起补充调查。
+
+**[v0.19.0](https://chorus-ai.dev/zh/blog/chorus-v0.19.0-release/)**：借鉴 Cloudflare，明确 reviewer 职责、保留完整证据，用稳定 ID 逐轮追踪问题。任务审查默认检查验收标准之外的代码质量。
+
 **[v0.18.0](https://chorus-ai.dev/zh/blog/chorus-v0.18.0-release/)** — 内置 `spec-lite`，作为 OpenSpec 之外更轻量、可直接进 Git 的本地 Spec 管理方案。live session anchor 让 daemon Agent 的回复回到发起者已有的 Idea 会话。
 
 **[v0.17.2](https://chorus-ai.dev/zh/blog/chorus-v0.17.2-release/)** — Pi 现在可以正式安装并由 daemon 唤醒，`chorus agents run` 还能一条命令切换本地 Agent profile。
 
 **[v0.17.0–0.17.1](https://github.com/Chorus-AIDLC/Chorus/releases/tag/v0.17.1)** — 一个 CLI 即可为各类编程 Agent 安装和更新 Chorus。现在还能在 Tracker、Graph 和 Idea 详情中直接看到 daemon 的实时活动。
 
-**[v0.16.4](https://chorus-ai.dev/zh/blog/chorus-v0.16.4-release/)** — DeepSeek Harness（dsh）成为第六种接入方式：`@chorus-aidlc/chorus-dsh` bundle 把 Chorus 的 skill、persona 和 MCP 配置装进任意 dsh profile。目前仅交互式使用，daemon 唤醒稍后支持。
-
-**[v0.16.1](https://chorus-ai.dev/zh/blog/chorus-v0.16.1-release/)** — 一个 `chorus daemon` 现在可以同时服务多个互相独立的 agent，每个都有自己的密钥、工作目录、后端和权限（通过 `agents[]` 配置）；agent 之间还能通过 @ 把活递给对方，每次唤醒都落在该 agent 自己的项目目录里。
-
-**[v0.16.0](https://chorus-ai.dev/zh/blog/chorus-v0.16.0-release/)** — 新增 `docs` skill，引导 Agent 查阅文档站点（[doc.chorus-ai.dev](https://doc.chorus-ai.dev)），基于当前文档作答，而不是凭记忆复述。
-
-**[v0.15.0](https://chorus-ai.dev/zh/blog/chorus-v0.15.0-release/)** — 项目级 Agent 工作目录：每位用户可以为项目中的每个 Agent 绑定主机和 cwd，只浏览 daemon 允许的目录，并让任务分配、唤醒、恢复和后续对话使用同一个执行位置，且不迁移进行中的会话。Codex 现在会单独保存可恢复的后端 thread ID，并移除不再需要的 Chorus session 管理步骤。
-
-**[v0.14.1](https://chorus-ai.dev/zh/blog/chorus-v0.14.1-release/)** — Amazon Kiro CLI 成为第四种接入方式（Kiro CLI v2）：通过 `chorus agents add` 一条命令安装的 Kiro 插件，以及 `--agent kiro` 的 daemon 后端，另有若干 daemon 修复。
-
 > 完整更新日志：[CHANGELOG.md](CHANGELOG.md)
 
 ---
@@ -54,7 +48,7 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 两条命令即可，无需数据库、无需 Docker、无需配置文件。
 
 ```bash
-npm install -g @chorus-aidlc/chorus@0.18.1
+npm install -g @chorus-aidlc/chorus@0.19.1
 chorus
 ```
 

package/cli/control-handler.mjs

@@ -269,6 +269,26 @@ export function createControlHandler(deps) {
         }
       }
       if (!entry || entry.status !== "running" || !entry.child) {
+        if (entry?.status === "running" && entry.operationTurnUuid) {
+          // Admission can be committed while its response is still in flight.
+          // Cancel locally before reporting, so even a lost response cannot launch.
+          waker.markInterrupting?.(killEntityType, killEntityUuid);
+          try {
+            Promise.resolve(advanceTurn?.({
+              sessionId: entry.directIdeaUuid ?? killEntityUuid,
+              turnUuid: entry.operationTurnUuid,
+              status: "interrupted",
+              interruptedReason: "user",
+              entityType: killEntityType,
+              entityUuid: killEntityUuid,
+            })).catch((err) => {
+              logger.warn(`[Chorus] control: Operation cancellation report rejected for ${killKey}: ${err}`);
+            });
+          } catch (err) {
+            logger.warn(`[Chorus] control: Operation cancellation report failed for ${killKey}: ${err}`);
+          }
+          return;
+        }
         // Either we never ran this entity, it's only queued (no child yet), or the
         // wake already finished (race: interrupt arrived after exit). There is nothing
         // to kill — but the SERVER may still hold a `running` turn for this session

package/cli/daemon-rest-client.mjs

@@ -245,14 +245,15 @@ export function createDaemonRestClient(opts) {
         // Coalesced-wake count (add-daemon-wake-coalescing): meaningful ONLY on the → running
         // edge, where the server settles the next (count − 1) same-session pending turns to
         // `merged`. Sent only when a real batch coalesced (> 1); a single wake (default 1)
-        // omits it so the wire — and every existing turn-advance test — stays byte-identical.
-        ...(status === "running" && typeof coalescedCount === "number" && coalescedCount > 1
+        // omits it; exact operation admission explicitly sends 1 with its turn UUID.
+        ...(status === "running" && typeof coalescedCount === "number" &&
+          (coalescedCount > 1 || (turnUuid && coalescedCount === 1))
           ? { coalescedCount }
           : {}),
       };
       const result = await post(
         "turn-advance",
-        "/api/daemon/turn-advance",
+        "/api/daemon/turn-advance?researchProtocol=1&operationProtocol=1",
         body,
         `advanced turn for session ${sessionId} → ${status}`,
         "",
@@ -394,7 +395,9 @@ export function createDaemonRestClient(opts) {
         // No connectionUuid yet: nothing to read against. A normal early state — skip.
         return { ok: false, status: null, skipped: true };
       }
-      const endpoint = `${url}/api/daemon/pending-turns?connectionUuid=${encodeURIComponent(connectionUuid)}`;
+      // Declare support for isolated Research turns. Legacy clients receive the
+      // same requests and acknowledge them through their existing FIFO path.
+      const endpoint = `${url}/api/daemon/pending-turns?connectionUuid=${encodeURIComponent(connectionUuid)}&researchProtocol=1&operationProtocol=1`;
       let response;
       try {
         response = await fetchImpl(endpoint, {

package/cli/event-router.mjs

@@ -8,6 +8,8 @@
 // action, resolve the root-idea key and enqueue the wake. Never throws into the
 // SSE loop.
 
+import { OPERATION_ACTIONS, validateOperation } from "./operation.mjs";
+
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
 // Map a Notification.action to its DaemonSessionTurn trigger category — the daemon-side
@@ -70,6 +72,9 @@ export class EventRouter {
     // dispatch time (before any async work) so concurrent dispatches for the
     // same uuid collapse to one wake.
     this.seen = opts.seen ?? new Set();
+    this.validatingOperations = new Set();
+    this.pendingDispatchCount = 0;
+    this.pendingDispatch = Promise.resolve();
   }
 
   /**
@@ -150,9 +155,9 @@ export class EventRouter {
     // (`notificationUuid` vs `turn:{uuid}`) — the double-execution bug — and would fan the
     // wake out to EVERY connection of the agent rather than the session's origin. So the
     // notification path explicitly defers `human_instruction` to the turn-keyed paths.
-    if (n.action === "human_instruction") {
+    if (n.action === "human_instruction" || OPERATION_ACTIONS.has(n.action)) {
       this.logger.info(
-        `[Chorus] human_instruction ${notificationUuid} is delivered via deliver_turn / pending-turn backfill — not the notification path; ignoring here`
+        `[Chorus] ${n.action} ${notificationUuid} is delivered via deliver_turn / pending-turn backfill — not the notification path; ignoring here`
       );
       return;
     }
@@ -293,6 +298,20 @@ export class EventRouter {
    *           trigger?: string, promptText?: string|null }} pending
    */
   dispatchPendingTurn(pending) {
+    // Creation identity reads are async. Keep subsequent turn deliveries behind
+    // them so validation cannot reorder the session's ordinary/operation FIFO.
+    if (OPERATION_ACTIONS.has(pending?.trigger) || this.pendingDispatchCount > 0) {
+      this.pendingDispatchCount++;
+      this.pendingDispatch = this.pendingDispatch
+        .then(() => this.#dispatchPendingTurnNow(pending))
+        .catch((err) => this.logger.warn(`[Chorus] pending-turn dispatch failed: ${err}`))
+        .finally(() => { this.pendingDispatchCount--; });
+      return this.pendingDispatch;
+    }
+    return this.#dispatchPendingTurnNow(pending);
+  }
+
+  #dispatchPendingTurnNow(pending) {
     const turnUuid = pending?.turnUuid;
     const sessionId = pending?.sessionId;
     if (typeof turnUuid !== "string" || !turnUuid) {
@@ -303,6 +322,9 @@ export class EventRouter {
       this.logger.warn(`[Chorus] pending-turn ${turnUuid} missing sessionId, skipping`);
       return;
     }
+    if (OPERATION_ACTIONS.has(pending.trigger)) {
+      return this.#dispatchOperation(pending);
+    }
     // A DIRECTED autonomous turn (mentioned / task_assigned / elaboration_verified /
     // start_development / yolo_requested) is delivered by the deliver_turn ping too (T2).
     // Its prompt must be rebuilt from the notification (promptText is null), so it takes a
@@ -377,6 +399,8 @@ export class EventRouter {
       entityType: directIdeaUuid ? "idea" : "daemon_session",
       entityUuid: directIdeaUuid ? directIdeaUuid : sessionId,
       instructionText: instruction,
+      // Research must retain its exact turn for admission immediately before spawn.
+      ...(instruction.startsWith("[Chorus Tracker Research]") ? { turnUuid, researchOnly: true } : {}),
       ...(typeof pending.runtimeCwd === "string" ? { runtimeCwd: pending.runtimeCwd } : {}),
     };
     const key = directIdeaUuid ? `idea:${directIdeaUuid}` : `entity:daemon_session:${sessionId}`;
@@ -392,7 +416,45 @@ export class EventRouter {
     // Enqueue an opaque DATA payload (add-daemon-wake-coalescing §C4), NOT a thunk: the
     // queue coalesces all same-key pending items and hands the whole batch to its runBatch
     // (wired to waker.wakeBatch in daemon.mjs). markQueued was already called per-item above.
-    this.queue.enqueue(key, { notification: n, attribution });
+    this.queue.enqueue(key, {
+      notification: n, attribution,
+      ...(n.researchOnly ? { isolated: true } : {}),
+    });
+  }
+
+  async #dispatchOperation(pending) {
+    const seenKey = `turn:${pending.turnUuid}`;
+    if (this.seen.has(seenKey) || this.validatingOperations.has(seenKey)) return;
+    this.validatingOperations.add(seenKey);
+    try {
+      const payload = { ...validateOperation(pending.trigger, pending.operationPayload, pending) };
+      // Pending DTOs carry the session's Idea anchor but no authoritative project.
+      // Read the Idea for creation before trusting the payload's project identity.
+      if (payload.kind === "idea_creation") {
+        const idea = await this.mcp.callTool("chorus_get_idea", { ideaUuid: pending.directIdeaUuid });
+        if (idea?.uuid !== pending.directIdeaUuid || idea?.project?.uuid !== payload.projectUuid) {
+          throw new Error("Operation protocol error: creation project does not match its Idea");
+        }
+      }
+      const n = {
+        action: pending.trigger, turnUuid: pending.turnUuid,
+        sessionId: pending.sessionId, directIdeaUuid: pending.directIdeaUuid,
+        entityType: "idea", entityUuid: pending.directIdeaUuid,
+        operationPayload: payload, promptText: pending.promptText,
+        ...(payload.kind === "idea_creation" ? { projectUuid: payload.projectUuid } : {}),
+        ...(typeof pending.runtimeCwd === "string" ? { runtimeCwd: pending.runtimeCwd } : {}),
+      };
+      const key = `idea:${pending.directIdeaUuid}`;
+      const attribution = { key, rootIdeaUuid: pending.directIdeaUuid, directIdeaUuid: pending.directIdeaUuid };
+      this.queue.enqueue(key, { notification: n, attribution, isolated: true });
+      this.seen.add(seenKey); // Only accepted, valid queue entries own dedup.
+      try { this.waker.markQueued?.(n, key, attribution); }
+      catch (err) { this.logger.warn(`[Chorus] markQueued failed for ${pending.turnUuid}: ${err}`); }
+    } catch (err) {
+      this.logger.warn(`[Chorus] operation turn ${pending.turnUuid} remains pending and retryable: ${err}`);
+    } finally {
+      this.validatingOperations.delete(seenKey);
+    }
   }
 
   /**

package/cli/operation-contract.mjs

@@ -0,0 +1,3 @@
+// Shared wire constraints; this dependency-free module is shipped with the CLI.
+export const CONVERSATIONAL_IDEA_DESCRIPTION_MAX_CHARS = 3000;
+export const RESEARCH_INSTRUCTION_PREFIX = "[Chorus Tracker Research]";

package/cli/operation-prompts.mjs

@@ -0,0 +1,99 @@
+// Shared by the server compatibility snapshot and payload-driven CLI execution.
+// Keep historical entry prefixes: older clients use the Research prefix for isolation.
+import { RESEARCH_INSTRUCTION_PREFIX } from "./operation-contract.mjs";
+
+const PROJECT_INSTRUCTION_LABEL_MAX_CHARS = 200;
+
+/**
+ * Compose the conversational-idea wake instruction (template v2 — the REVIEWED CONTRACT
+ * between the conversational create-idea entry and the woken daemon agent, superseding
+ * the client-side create→claim template of add-conversational-idea-entry).
+ *
+ * The idea is PRE-CREATED and already instance-assigned + elaborating, so both templates
+ * direct EDIT (never create, never claim — a claim would fail on the existing assignee).
+ *  - `elaborate` (default): edit → optional research → elaboration → panel guidance → end turn.
+ *  - `decompose`: edit the CONTAINER → keep isContainer → one lightweight scope-clarifying
+ *    elaboration → propose candidate CHILDREN as a structured elaboration round (one
+ *    single-select question per child, ≤15/round, never a multi-select) → end turn → on the
+ *    confirm re-wake create each accepted child via chorus_pm_create_idea with
+ *    parentUuid=<container>, children starting `open`, no auto-elaboration; the container's
+ *    own status stays `elaborated`. The confirm re-wake rides the EXISTING
+ *    `elaboration_answered` wake — no new wake/notification action is introduced.
+ *
+ * English (agent-facing, matching cli/prompts.mjs precedent); the user's description
+ * passes through VERBATIM under the delimiter. Exported for unit tests: the template's
+ * wording is code, and any change is a review-visible diff.
+ * @param {{ideaUuid: string, projectUuid: string, projectName?: string|null,
+ *   descriptionText: string, mode?: 'elaborate'|'decompose', researchFirst?: boolean}} params
+ */
+export function composeConversationalIdeaInstruction(params) {
+  // Name is display sugar; bound this user-controlled metadata independently of
+  // the description. The complete UUID remains the authoritative machine anchor.
+  const projectName = params.projectName?.trim();
+  const displayName = projectName && projectName.length > PROJECT_INSTRUCTION_LABEL_MAX_CHARS
+    ? `${projectName.slice(0, PROJECT_INSTRUCTION_LABEL_MAX_CHARS - 1)}…`
+    : projectName;
+  const projectLabel = displayName
+    ? `"${displayName}" (projectUuid: ${params.projectUuid})`
+    : `projectUuid: ${params.projectUuid}`;
+
+  const researchInstruction = [
+    params.researchFirst
+      ? "The user explicitly requested lightweight research before clarification."
+      : "Research is optional: use automatic judgment for a concrete, externally verifiable factual gap.",
+    "An explicit request to skip research in the user's instructions takes precedence.",
+    "Follow the shared research skill before the first formal elaboration: one bounded pass, approximately 2–5 minutes, at most 5 deeply read relevant sources; reuse existing evidence.",
+    "Save useful findings in the existing Idea content, preserving the user's meaning, and attach evidence with real ref:UUID citations. Do not create or claim this already-created Idea.",
+    "If tools are unavailable, results are empty, or the budget is exhausted, record the limitation and continue the normal steps in this turn. Do not research user preferences; ask through the elaboration panel when needed.",
+    "This initialization request applies once, not on every later wake or stage re-entry.",
+  ].join(" ");
+
+  if (params.mode === "decompose") {
+    return [
+      `[Chorus container-decompose entry] A new CONTAINER idea has been PRE-CREATED for project ${projectLabel} from the user's description below, and it is already assigned to you (status: elaborating, isContainer: true).`,
+      `  ideaUuid: ${params.ideaUuid}`,
+      ``,
+      `This conversation IS that container idea's root session. The user wants help DECOMPOSING it into child ideas. Do the following, in order:`,
+      `1. Edit the container via chorus_edit_idea: derive a concise title from the description and polish the content (keep the user's meaning). The current title is a placeholder.`,
+      `2. Ensure it stays a container: it was pre-created with isContainer=true — do NOT clear that flag (a container groups its child ideas and MUST NOT get a proposal of its own).`,
+      `Before step 3: ${researchInstruction}`,
+      `3. Run ONE lightweight elaboration round (chorus_pm_start_elaboration) to clarify the decomposition scope/dimension — how to slice the work into children. Keep it short; you may self-answer in headless or ask the user, then continue.`,
+      `4. Propose the candidate child ideas AS A STRUCTURED ELABORATION ROUND (chorus_pm_start_elaboration) for the user to review/edit/confirm — use ONE elaboration question PER proposed child (the child's title as the question text, a short rationale as its description), single-select. Elaboration questions are single-select and a round is capped at 15 questions, so propose at most 15 candidates per round and NEVER a single multi-select question; if you need more children, propose them across additional rounds. Do NOT create any child ideas yet — this round is the preview the user accepts/edits/declines per child.`,
+      `5. End the turn. The user's answers in the idea's elaboration panel will wake this same conversation (the existing elaboration-answered wake).`,
+      `6. On that re-wake, create each ACCEPTED child via chorus_pm_create_idea with parentUuid=${params.ideaUuid}. Each child starts in the "open" state — do NOT auto-elaborate them. The container's OWN status stays "elaborated"; creating children does not advance or alter it.`,
+      ``,
+      `Reference reflex: whenever an external link is evidence for this work (a precedent issue/PR, a reference implementation, official docs, a paper/blog), attach it via references — prefer the inline references[] param at creation time over a post-hoc chorus_add_reference.`,
+      ``,
+      `--- User's idea description ---`,
+      params.descriptionText,
+    ].join("\n");
+  }
+
+  return [
+    `[Chorus conversational idea entry] A new idea has been PRE-CREATED for project ${projectLabel} from the user's description below, and it is already assigned to you (status: elaborating).`,
+    `  ideaUuid: ${params.ideaUuid}`,
+    ``,
+    `This conversation IS that idea's root session — its elaboration and lifecycle wakes will continue here. Do the following, in order:`,
+    `1. Edit the idea via chorus_edit_idea: derive a concise title from the description and polish the content (keep the user's meaning; you may restructure). The current title is a placeholder.`,
+    `2. ${researchInstruction}`,
+    `3. After that optional step, start elaboration on the idea (chorus_pm_start_elaboration), following the idea skill — do NOT wait for another wake. Post a short summary of your questions in this conversation and direct the user to answer in the idea's elaboration panel.`,
+    `4. End the turn. The user's panel answers will wake this same conversation.`,
+    ``,
+    `Reference reflex: whenever an external link is evidence for this idea (a precedent issue/PR, a reference implementation, official docs, a paper/blog), attach it via references — prefer the inline references[] param at creation time over a post-hoc chorus_add_reference.`,
+    ``,
+    `--- User's idea description ---`,
+    params.descriptionText,
+  ].join("\n");
+}
+
+/** @param {string} ideaUuid */
+export function composeResearchInstruction(ideaUuid) {
+  return [
+    `${RESEARCH_INSTRUCTION_PREFIX} Explicit, one-time research request for ideaUuid: ${ideaUuid}.`,
+    "This is the existing Idea's root conversation. Before research and again before saving, re-read the Idea, ALL related proposals/tasks and execution history including theme descendants. If development has begun, report that the stage changed and STOP without research or edits.",
+    "Invoke the shared research skill for ONE bounded pass (approximately 2–5 minutes, at most 5 deeply read sources). Reuse existing evidence. An explicit user instruction to skip research takes precedence. Tools unavailable, empty results, or exhausted budget: record the limitation and stop.",
+    "Attach useful sources through existing references and obtain real UUIDs. Read the latest Idea content immediately before saving and MERGE concise findings, source citations using ref:UUID, implications, unknowns, and the stopping reason; preserve user text and existing evidence.",
+    "Preserve all elaboration rounds, questions, answers and resolved state. Do not create or claim an Idea, start elaboration, submit or modify a Proposal, change task status, or start development. If findings affect an approved proposal, only record the impact and revision needs in the Idea.",
+    "Report the findings and END this turn. This menu invocation does not resume the Idea or Proposal workflow. A later explicit Research request may run another bounded pass.",
+  ].join("\n");
+}

package/cli/operation.mjs

@@ -0,0 +1,46 @@
+import { CONVERSATIONAL_IDEA_DESCRIPTION_MAX_CHARS, RESEARCH_INSTRUCTION_PREFIX } from "./operation-contract.mjs";
+import { composeConversationalIdeaInstruction, composeResearchInstruction } from "./operation-prompts.mjs";
+
+// Canonical operations are identified by their trigger, never by prompt text.
+export const OPERATION_ACTIONS = new Set(["idea_creation_requested", "research_requested"]);
+
+const identity = (value) => typeof value === "string" && value.length > 0 && value.length <= 100;
+
+/** Validate before dedup/admission. Routing authority always comes from the session. */
+export function validateOperation(trigger, payload, { sessionId, directIdeaUuid, projectUuid }) {
+  const creation = trigger === "idea_creation_requested";
+  const fields = creation
+    ? ["version", "kind", "ideaUuid", "projectUuid", "mode", "researchFirst", "descriptionText"]
+    : ["version", "kind", "ideaUuid"];
+  if (!OPERATION_ACTIONS.has(trigger) ||
+      !payload || typeof payload !== "object" || Array.isArray(payload) ||
+      Object.keys(payload).length !== fields.length ||
+      fields.some((field) => !Object.hasOwn(payload, field)) ||
+      payload.version !== 1 || payload.kind !== (creation ? "idea_creation" : "research") ||
+      !identity(payload.ideaUuid) || payload.ideaUuid !== directIdeaUuid ||
+      sessionId !== directIdeaUuid ||
+      (creation && (!identity(payload.projectUuid) ||
+        (projectUuid !== undefined && payload.projectUuid !== projectUuid) ||
+        !["elaborate", "decompose"].includes(payload.mode) ||
+        typeof payload.researchFirst !== "boolean" ||
+        typeof payload.descriptionText !== "string" || !payload.descriptionText.trim() ||
+        payload.descriptionText.length > CONVERSATIONAL_IDEA_DESCRIPTION_MAX_CHARS))) {
+    throw new Error("Operation protocol error: invalid payload or session/Idea identity mismatch");
+  }
+  return payload;
+}
+
+export function isExactOperation(n) {
+  return OPERATION_ACTIONS.has(n?.action) ||
+    (n?.action === "human_instruction" &&
+      n.instructionText?.startsWith(RESEARCH_INSTRUCTION_PREFIX));
+}
+
+export function buildOperationPrompt(n) {
+  const p = validateOperation(n.action, n.operationPayload, {
+    sessionId: n.sessionId, directIdeaUuid: n.directIdeaUuid, projectUuid: n.projectUuid,
+  });
+  return p.kind === "research"
+    ? composeResearchInstruction(p.ideaUuid)
+    : composeConversationalIdeaInstruction(p);
+}