@joekytc/dsh-swarm 0.3.7 → 0.3.8

package/README.md

@@ -19,10 +19,10 @@ dsh-swarm is a DSH plugin that turns one requirement into a strict, evidence-ver
 Swarm mode turns your main session into a **team lead**: **you state the requirement, it clarifies, plans, confirms, delegates and follows through** — entirely in natural language, no commands to remember.
 
 - **No commands to memorize** — just state your requirement; no `/plan:` or `/openspec:` prefixes needed.
-- **Automatic intent recognition** — development requests → clarify/plan and build a chain; lessons & retrospectives → persist to memory; group notifications → deliver to WeCom; Q&A / chit-chat → answered directly.
-- **Free delivery** — `/sms <intent>` (e.g. "post current progress to the group"): facts are grounded via kanban lookup, then the body is composed per intent and delivered; `-s` or wording like "private chat" targets the DM. Group and private-chat targets must each be exactly one (0 or 2+ targets error out; clean up in dsh-im settings or set `imDelivery.dmTargetId`).
-- **Confirmation gate against accidental chains** — after the checklist is saved, a chain is only built once you reply with an explicit affirmative (`确认` / `开干` / `开跑` / `开始` / `go`, etc.); vague replies, topic switches, or edit-only feedback count as *not confirmed*.
-- **The lead is read-only** — the main session cannot write/edit repo sources, nor run git mutations (push/commit/checkout…); writing code is done by the executor (D) in an isolated workspace by design.
+- **Automatic intent recognition** — development requests → clarify/plan and build a chain; lessons & retrospectives → persist to memory; group notifications → deliver to WeCom; Q&A / chit-chat → answered directly. Intent is judged by the model, not by a code-level classifier — the confirmation gate below is what stops a misjudged chain.
+- **Free delivery** — `/sms <intent>` (e.g. "post current progress to the group"): facts are grounded via kanban lookup, then the body is composed per intent and delivered; `-s` or wording like "private chat" targets the DM. A bare `/sms` re-sends the latest completed-chain report and `/sms blocked [chainId]` the block notice — those two bodies are rendered by system code from kanban facts, never rewritten by the lead. Group and private-chat targets auto-resolve to the single saved target (0 or 2+ targets error out; clean up in dsh-im settings, or pin `imDelivery.targetId` / `imDelivery.dmTargetId`, which skips the count check — though with `imDelivery.botId` empty the pinned target must still belong to the auto-discovered bot, or it errors out).
+- **Confirmation gate against accidental chains** — after the checklist is saved, the lead is instructed to build a chain only once you reply with an explicit affirmative (`确认` / `开干` / `开跑` / `开始` / `go`, etc.). The gate is judged by the model, not enforced by a code-level check; vague replies, topic switches, or edit-only feedback count as *not confirmed*.
+- **The lead is read-only** — the main session cannot write/edit repo sources, nor run git mutations (push/commit/reset…); a bare `git checkout`/`git switch` of an existing branch is allowed. Writing code is done by the executor (D) in an isolated workspace by design.
 - **Progress is always actually queried** — ask "how is it going?" anytime and the lead reports from real kanban lookups, never fabricated.
 
 ### Why it's designed this way
@@ -33,7 +33,7 @@ Coordinating several agents on one task typically fails in three ways:
 - **Unverifiable handoffs** — an agent claims "done" with no reproducible evidence, and the next agent builds on sand.
 - **Silent deadlocks** — an agent stops without finishing and the pipeline hangs, or bad code is merged before anyone reviewed it.
 
-dsh-swarm encodes a *contract* against all three: one machine-enforced responsibility per role;
+dsh-swarm encodes a *contract* against all three: one responsibility per role, enforced by the permission matrix, tool faces and task-body instructions;
 every handoff must carry structured evidence or the phase will not close; every stall or review
 failure lands in a visible, recoverable state — with you (the human) as the final trust anchor.
 It is built correctness-first: deterministic state machines, append-only event sourcing, idempotent
@@ -55,13 +55,21 @@ schedulers, and a red-team test suite that replays the event log and rejects any
 
 Prerequisites: a working DSH runtime (`@deepseek-ai/*`), Node.js ≥ 22.19 and npm. Optional: a wiki-vault HTTP service (KB features, see [Configuration](#configuration)).
 
+From npm (the published tarball ships the built `lib/`):
+
+```bash
+dsh plugin --profile web add @joekytc/dsh-swarm
+```
+
+From a source checkout (rebuild first so `lib/` matches the sources):
+
 ```bash
 npm install
 npm run build        # tsc -p tsconfig.build.json + client bundle (lib/client.js)
-dsh plugin --profile web add @joekytc/dsh-swarm
+dsh plugin --profile web add .
 ```
 
-> From GitHub source: `dsh plugin --profile web add github:joekytc/dsh-swarm`
+> From GitHub source: `dsh plugin --profile web add github:joekytc/dsh-swarm` — the repository tracks the built `lib/`.
 
 ### 2. Switch your main-session preset
 
@@ -91,14 +99,14 @@ Lead: Chain created (ch_…), live progress on the kanban tab (Conversation →
 ```
 
 - **Kanban**: the third tab of the conversation center (Conversation → Trajectory → Kanban). Click a card for Overview / Trajectory / Handoff / Spec / Comments.
-- **Completion**: when a chain completes, the system audits the workspace and (for D chains) automatically merges the feature branch into the spec-declared target branch; if an audit warning fires, confirm ownership in the GUI first.
+- **Completion**: when a chain completes, the system audits the workspace and (for D chains) automatically merges the feature branch into the spec-declared target branch. An audit warning blocks the final wrap-up until you confirm ownership in the GUI — it does not gate the merge.
 - **Progress**: just ask "how is it going?" — the lead reports from real kanban lookups and relays blocking reasons faithfully.
 
 ---
 
 ## What it does for you
 
-Six roles, one job each, machine-enforced boundaries — no role creep:
+Six roles, one job each — boundaries enforced by the permission matrix, trimmed tool faces and task-body instructions, so no role creep:
 
 | Role | One-line responsibility | What it never does |
 |---|---|---|
@@ -129,20 +137,40 @@ All keys are optional; schema lives in `src/config.ts`. **Most users only need t
 |---|---|---|
 | `storageDir` | `$DSH_HOME/storages/kanban` | Event log (`events.jsonl`), orchestration state, per-task workspaces, `dispatcher.log`. Value must use the unquoted `!!js dshHomePath("storages/kanban")` form — quoting degrades it into a literal string |
 | `wikiVault.baseUrl` | `''` (empty) | wiki-vault HTTP service for KB reads/writes — required for KB features; set to your own server |
+| `wikiVault.pagePrefix` | `projects/` | Namespace prefix for generated wiki pages |
 | `roles.models.<role>` | `{}` | Per-role model: `{ provider, model, reasoningEffort?, fallbacks?[] }` |
 | `roles.models.<role>.reasoningEffort` | `high` | Default reasoning effort for all roles |
 | `roles.models.<role>.fallbacks` | `[]` | Silent fallback candidates (audited via `[model-fallback]` comment) |
 | `dispatcher.staleTimeoutSeconds` | `14400` | Heartbeat timeout; running task without heartbeat is reclaimed |
 | `dispatcher.maxRetries` | `3` | Failure retries before circuit → `blocked(gave_up)` |
 | `dispatcher.heartbeatIntervalSeconds` | `300` | Watchdog heartbeat period |
-| `dispatcher.maxProtocolViolations` | `2` | Protocol-violation guardrail: after this many consecutive violations the next one is final (`gave_up`) |
+| `dispatcher.maxProtocolViolations` | `2` | Protocol-violation guardrail: once consecutive violations reach this many, the next one is final (`gave_up`) |
 | `dispatcher.maxReworksPerRole` | `{ pt: 3, dt: 3 }` | Max review rework rounds before `review/gave-up` + `[review-final]` |
-| `prefixRoutes.plan` | `/plan:` | Command-mode planning prefix |
+| `prefixRoutes.plan` | `/plan:` | Command-mode phase-0 planning prefix |
 | `prefixRoutes.openspec` | `/openspec:` | Command-mode approve-and-execute prefix |
-| `ui.enabled` | `true` | Enable the kanban web tab |
-| `ui.contentMinWidth` | `715` | Minimum kanban content width (px) |
-| `ui.contentMaxWidth` | `780` | Maximum kanban content width (px) |
+| `prefixRoutes.learning` | `/learning` | Lessons / retrospective prefix |
+| `prefixRoutes.send` | `/sms` | Free-delivery prefix (DM with `-s`) |
+| `memory.enabled` | `true` | Memory recall index; `false` makes `planning_memory_recall` return a disabled notice |
+| `memory.maxIndexEntries` | `8` | Max recalled memory entries (1–20) |
+| `ui.enabled` | `true` | Declared switch; not consumed yet — the tab registers unconditionally |
+| `ui.contentMinWidth` | `715` | Declared lower width bound (px); not consumed by the client yet — the tab follows the host conversation width |
+| `ui.contentMaxWidth` | `780` | Declared upper width bound (px); not consumed by the client yet |
 | `ui.sseHeartbeatSeconds` | `20` | SSE heartbeat interval |
+| `gates.enabled` | `true` | TDD measurement gate; `false` → silent skip (no event) |
+| `gates.timeoutMs` | `600000` | Per-command gate timeout (ms), SIGKILL at the deadline |
+| `gates.forbidden` | `['rm -rf /', 'git push']` | Command-blacklist substrings (defence in depth) |
+| `evidenceReplay.enabled` | `false` | L3 replay of model-written commands — not a sandbox, see [Issue evidence check](#issue-evidence-check-pr2-opt-in) |
+| `evidenceReplay.timeoutMs` | `600000` | Per-replay command timeout (ms) |
+| `evidenceReplay.allowPrefixes` | `['npx --no-install vitest', 'npm test', 'npm run build', 'npm run typecheck', 'tsc', 'eslint']` | Allowlisted tool prefixes (word-boundary match) |
+| `imDelivery.enabled` | `false` | WeCom delivery via dsh-im (W3 wrap-up / chain blocked / review gave-up) |
+| `imDelivery.botId` | `''` | Empty = auto-discover the only wecom bot |
+| `imDelivery.targetId` | `''` | Empty = auto-discover the only saved group target |
+| `imDelivery.dmTargetId` | `''` | DM target for `/sms -s` |
+| `imDelivery.fallbackBotId` | `''` | Bot used when preset-based matching finds nothing |
+| `reviewEngine.mode` | `delegate` | `delegate` or `managed` — see [Review engine (ocr)](#review-engine-ocr) |
+| `reviewEngine.managed.provider` | `''` | Model-chain provider id used in managed mode |
+| `reviewEngine.managed.model` | `''` | Model-chain model id used in managed mode |
+| `wikiWritePresets` | `['swarm', 'kanban-w', 'ptc']` | Presets allowed to call `wiki_write` (page paths are still whitelisted by namespace) |
 
 ---
 
@@ -150,7 +178,7 @@ All keys are optional; schema lives in `src/config.ts`. **Most users only need t
 
 Implementation reviews (the in-chain DT phase and standalone reviews) are powered by
 [open-code-review](https://open-codereview.ai) (ocr), with two modes switchable in the
-web config panel under "Swarm config → Review engine (ocr)":
+web config panel under 「Swarm 配置 → 评审引擎（ocr）」 (Swarm config → Review engine (ocr)):
 
 | Mode | How it works | Notes |
 |---|---|---|
@@ -159,21 +187,23 @@ web config panel under "Swarm config → Review engine (ocr)":
 
 ### Install
 
-- When ocr is missing, the config panel shows a red banner — click "Install ocr" for a one-click global install (async, cancellable);
+- When ocr is missing, the config panel shows a red banner — click 「安装 ocr」 (Install ocr) for a one-click global install (async, cancellable);
 - or run `npm install -g @alibaba-group/open-code-review` in a terminal, then verify with `ocr --version`.
 
 ### Standalone review (no chain needed)
 
-1. Switch the session to "Delivery Reviewer (DT)" at the top of the dsh web UI and just talk;
+1. Switch the session to 「交付评审官（DT）」 (Delivery Reviewer (DT)) at the top of the dsh web UI and just talk;
 2. State the review target: a local directory / branch range (from…to) / a single commit / uncommitted workspace diff / a public repo URL (auto-cloned into a temp dir, discarded afterwards);
 3. The report is first fully output to the conversation;
-4. Only after you confirm is it written to the wiki at `projects/<repo>/reviews/<topic>-<date>/`. Read-only throughout — reviewed code is never modified.
+4. Only after you confirm is it written to the KB at `projects/<repo>/reviews/<topic>-<date>/` — remote KB mode only; with the default empty `wikiVault.baseUrl` (local mode) no wiki page is written.
+
+Read-only in practice: bash/run_code writes and wiki writes outside the reviews namespace are blocked by the guard, while the fs `write`/`edit` tools are not blocked in a standalone DT session.
 
 ### Configuration notes
 
-- Mode, provider and model are all chosen on the "Review engine (ocr)" card; the provider/model dropdowns share the same catalog as the model chain;
-- After picking, click "Apply to ocr" — the system writes the wiring into ocr's custom config (`dsh-managed`); the API key is resolved from the dsh model config and written into ocr, never shown in plain text in the panel; if resolution fails it degrades gracefully and points you to a manual `ocr config provider` in a terminal;
-- When managed is not ready, reviews silently fall back to delegate mode — nothing is blocked.
+- Mode, provider and model are all chosen on the 「评审引擎（ocr）」 card; the provider/model dropdowns share the same catalog as the model chain;
+- After picking, click 「应用到 ocr」 (Apply to ocr) — the system writes the wiring into ocr's custom config (`dsh-managed`); the API key is resolved from the dsh model config and written into ocr, never shown in plain text in the panel; if resolution fails it degrades gracefully and points you to a manual `ocr config provider` in a terminal;
+- When managed is not ready, the ocr tool refuses the managed call and returns delegate guidance; the reviewer switches to delegate mode — nothing is blocked.
 
 Official docs: [Installation](https://open-codereview.ai/docs/installation) · [Model configuration](https://open-codereview.ai/docs/configuration) · [Delegate mode](https://open-codereview.ai/docs/delegate)
 
@@ -182,9 +212,10 @@ Official docs: [Installation](https://open-codereview.ai/docs/installation) · [
 ## Trust & guardrails (user's view)
 
 - **Read-only hard gate for the lead** — in swarm mode, main-session writes to sources and git mutations are blocked by a system gate; if blocked, just let the lead explain — execution is done by the D role.
-- **Confirmation gate** — no chain is ever built without your explicit confirmation.
+- **Confirmation gate** — the lead only builds a chain after you reply with an explicit affirmative (enforced by the lead's instructions, not by a code-level check).
 - **TDD hard gate** — implementations must ship with tests (or an explained skip); reviews machine-verify "tests really ran, and were written first".
-- **Human trust anchors** — spec approval, unblock, audit confirmation and chain deletion are human-only; neither the main session nor role agents can create chains or approve specs.
+- **Human trust anchors** — spec approval, unblock, audit confirmation and chain deletion are human-only; role agents cannot approve specs, and a chain is only created from your confirmed routing call (the main session routes as `human`).
+- **Guardrails are constraints, not a sandbox** — PT/DT write guards rely on path and command regexes (reviewers get no git credentials), and review evidence is existence-checked: fields must be present and well-formed, while replaying the commands to prove they ran happens only when `evidenceReplay.enabled` is turned on.
 - Full mechanics (permission matrix, delivery contract, review chain, rework, failure recovery) live under [Advanced / Developers](#advanced--developers).
 
 ---
@@ -195,16 +226,16 @@ Official docs: [Installation](https://open-codereview.ai/docs/installation) · [
 
 ### Roles & the execution pipeline (full table)
 
-Six roles are dispatched by the scheduler as one-shot agent sessions (deterministic session id `kbn-<taskId>`, resumed on retry/rework via `resumeSessionId`). Each role-agent session is bound to exactly one task (`boundTaskId`) and gets a trimmed tool face. V is the exception: a chain-scoped orchestrator session (`kbn-v-<chainId>`) with no `boundTaskId`.
+Six roles are dispatched by the scheduler as one-shot agent sessions (deterministic session id `kbn-<taskId>`; a retry resumes that same session — `resumeSessionId` is always null in the current implementation — while a rework task starts its own `kbn-<reworkId>` session). Each role-agent session is bound to exactly one task (`boundTaskId`) and gets a trimmed tool face. V is the exception: a chain-scoped orchestrator session (`kbn-v-<chainId>`) with no `boundTaskId`.
 
 | Role | Alias | Responsibility | Tool face (highlights) |
 |---|---|---|---|
 | **V** | Orchestrator | Drives the phase machine, creates one card per phase, posts `[blocked-review]` guidance on stalls. Never executes. | `kanban_create` + task tools + spec view |
 | **P** | Planner | Reads spec + repo facts (incl. read-only self-checks), writes an OpenSpec implementation plan, opts into PT via `pt_decision.needed`. Never executes. | Task tools + spec view, read-only (writes only `openspec/changes/`) |
 | **PT** | Plan reviewer | Read-only review of P's plan (requirements alignment, completeness, logic). Outputs verdict + issues. | Task tools + spec view, **read-only ToolGuard** |
-| **W** | Knowledge officer | W2/W3 KB sync (`w:kb`). Never touches code/git. | Task tools + `wiki_search/read/write` (remote) / `skill`→llm-wiki (local) + read-only spec view |
+| **W** | Knowledge officer | W2/W3 KB sync (`w:kb`). Never touches code/git. | Task tools + `wiki_search/read/write` (remote) / `skill`→llm-wiki (local) + `prefetch_file`/`prefetch_external`/`prefetch_kb` + read-only spec view |
 | **D** | Executor | The *only* role that writes code: worktree → implement → verify → `[AI-GEN]` commit → push feature branch (merging into the spec-declared target branch is done by the system only after DT passes). | Task tools + wiki read + bash/fs/run_code (full dev) + subagent (spawn/fork/list-agents) + goal |
-| **DT** | Implementation reviewer | Empirically verifies D's work (test/build/typecheck/diff/git + open-code-review), writes review page to KB. Read-only against the repo. | Task tools + wiki read/write (review namespace) + bash/fs/run_code, **read-only ToolGuard** |
+| **DT** | Implementation reviewer | Empirically verifies D's work (test/build/typecheck/diff/git + open-code-review), writes review page to KB. Read-only against the repo. | Task tools + wiki read/write (review namespace) + `ocr_review` + bash/fs/run_code, **read-only ToolGuard** |
 
 ### Guardrails in detail
 
@@ -234,41 +265,64 @@ Six roles are dispatched by the scheduler as one-shot agent sessions (determinis
 | prefetch | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
 | audit-confirm | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
 | create-rework-task | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| reopen-chain | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
+| waive-review | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
 
 Key guarantees (two):
 
-- **The main session cannot execute.** It only gets `kanban_show`/`kanban_list`/
-  `kanban_comment` + `spec_card_view` + `kanban_route` — never
-  `kanban_create`/`kanban_complete`/`kanban_block`. Chains/specs are created only
-  via swarm-mode intents or `/plan:`+`/openspec:`; the GUI observes and mutates task state but never
-  creates chains or tasks — "who decided to run what" stays explicit and auditable.
+- **The main session cannot execute.** Its kanban tool face is a read-only subset —
+  `kanban_show`/`kanban_chain`/`kanban_list`/`kanban_comment` plus the human-recovery pair
+  `kanban_reopen_chain`/`kanban_waive_review` — together with `spec_card_view`, `kanban_route`,
+  the `planning_*` tools and `sms_send`; never `kanban_create`/`kanban_complete`/`kanban_block`.
+  Chains/specs are created only via swarm-mode intents or `/plan:`+`/openspec:`; the GUI observes
+  and mutates task state but never creates chains or tasks — "who decided to run what" stays
+  explicit and auditable.
 - **Session binding prevents cross-task escalation** (a W agent bound to task A
   cannot complete/block task B even though both are W tasks); DT writes are
   confined to the `projects/<repoSlug>/<chain>/review/` namespace by a ToolGuard on top of
-  the matrix; and no role agent can approve specs, unblock, or confirm audits —
-  those are human trust anchors; `system` handles only mechanical bookkeeping.
+  the matrix; and no role agent can approve specs, unblock, confirm audits, waive a
+  review or reopen a chain — those are human trust anchors; `system` handles only
+  mechanical bookkeeping.
 
 #### Delivery contract (upstream owes downstream)
 
 Each phase's handoff must carry the keys its downstream actually reads
-(`src/domain/delivery-contract.ts`). Missing keys block the current role's card
-immediately (and the orchestrator never builds a downstream card on a blocked
-parent):
+(`src/domain/delivery-contract.ts`). Missing delivery keys block the W/P card
+immediately and admit no human exemption; the D/PT/DT evidence gates instead reject
+`complete` with an error (the card stays running) and are human-exempt. The
+orchestrator never builds a downstream card on a blocked parent:
 
 | Card | Required handoff keys |
 |---|---|
-| W2 / W3 (`w:kb`) | `kb_url` + `page_path` |
+| W2 / W3 (`w:kb`) | `kb_url` + `page_path` — non-empty is not enough: with a configured `wikiVault.baseUrl` the `kb_url` must start with it (and must be exactly `''` in local mode), while `page_path` must sit in the allowlisted namespaces (`wiki/**` locally) |
 | P (`p:openspec`) | `artifacts_path` + `pt_decision` (`needed` boolean required; when `needed: true`, `reason` is required) |
-| D (`d:execute`) | `changed_files` + (`commit_hash` or `push`) — `hasDeliveryEvidence`; `branch` (feature branch) is expected for the merge gate, not a hard-complete blocker; `tdd` (`test_files` or `skipped.reason`, XOR) |
+| D (`d:execute`) | `changed_files` + (`commit_hash` or `push`) — `hasDeliveryEvidence`; `branch` (feature branch) is not a delivery key, but when the TDD gate actually runs the tests it checks the branch and bounces the card if it is absent or mismatched; `tdd` (`test_files` or `skipped.reason`, XOR) |
 | PT / DT | `review_evidence` (schema-valid) — `validateReviewEvidence` |
 
 #### TDD hard gate (evidence threshold)
 
 D completes only with `tdd` — `test_files` (with `test_first`) or `skipped.reason`
-(XOR, `delivery-evidence.ts`). DT's `review_evidence` must carry `tdd`; on a
-`pass` verdict the runner must be `vitest` (`test.runner`) and `test_first === true`
-must hold (`review-evidence.ts`). This makes "tests actually ran, and were written
-first" a machine-checked property rather than a claim.
+(XOR, `delivery-evidence.ts`). DT's `review_evidence` must carry `tdd`; whenever
+`tdd.test_files` are declared the runner must be `vitest` (`test.runner`), and on a
+`pass` verdict `test_first === true` must hold (`review-evidence.ts`). This makes
+"tests actually ran, and were written first" a machine-checked property rather than
+a claim.
+
+#### Gate skip alarm & declaration cross-check 
+
+A declaration that disagrees with the diff no longer passes the gate silently
+(three silent-skip modes remain, emitting no event: `gates.enabled=false`, a handoff
+without `worktree_dir`, and non-`d:execute` cards):
+
+- **`task/gate-skipped` event** — a declared `tdd.skipped` is allowed when the diff is pure docs/config, or when the diff cannot be computed (conservative alarm-skip); both leave the event as an audit trail. Otherwise the gate **bounces** the card back (same session, agent fixes and re-completes).
+- **Declaration ↔ reality cross-check** — declaring `test_files` with no test-file change in the diff (stale-test handoff), an empty `test_files`, an invalid path, or a branch mismatch all **bounce** instead of silently skipping.
+- After 3 cumulative bounces the task is **blocked for human review** (`gave_up: gate bounced 3 times`).
+- Gate runs now archive raw output to `<storageDir>/gate-logs/<taskId>.log` (path is referenced in the gate event detail).
+- `review_evidence.lint` must be a structured object (aligning with `build`/`typecheck`); `null`/scalars are rejected.
+
+#### Issue evidence check (PR2, opt-in)
+
+Reviewer-reported issues (DT cards only — PT issues are never evidence-checked) can carry `evidence = { file, command, exit }` (raw output archive, first line `[exit code: N]`). Verification is three-tier: missing evidence → flagged (`not-provided`; critical/high → `could-not-replay` + needs-human); archive paper-check (zero execution) → `matches`; on mismatch a **replay** re-runs the command — **only if `evidenceReplay.enabled` is turned on**, and only for allowlisted tool prefixes (word-boundary match; `npm run` restricted to fixed script names). Replays execute model-written commands and are **NOT a sandbox**; keep the switch off unless you accept that risk. Results are summarized in a `review/evidence-check` event; `differs` never auto-fails a review — it surfaces to human review.
 
 #### Phase-0 planning checklist
 
@@ -280,9 +334,9 @@ blocks the save, and chain creation mounts the checklist as the `file-prefetch`
 
 #### Review quality chain
 
-- After **P** completes, **PT** is created only when P's handoff delivers
-  `pt_decision.needed = true`; the orchestrator never overrides the decision
-  (V only creates the card).
+- After **P** completes, **PT** is skipped only when P's handoff delivers
+  `pt_decision.needed = false`; `true` or an absent decision creates the PT card
+  (fail-safe) — the orchestrator never overrides the decision (V only creates the card).
 - After **D** completes, a **DT** card is *always* created.
 - **PT/DT are read-only**: a ToolGuard mechanically denies writes to the repo
   sources, git mutations, and (for DT) wiki writes outside the review namespace.
@@ -291,9 +345,10 @@ blocks the save, and chain creation mounts the checklist as the `file-prefetch`
   `review-tool-unavailable` when ocr is missing (reason notes GUI install),
   without burning retries.
 - `review_evidence` must pass `validateReviewEvidence` or the review card cannot
-  complete: PT needs verdict + issues + plan ref; DT additionally needs
-  test (exit 0 on pass), build/typecheck, lint, non-empty diff, git,
-  ocr/fallback conclusion, and `tdd`.
+  complete: PT needs verdict + issues + plan ref, and a `fail` verdict requires at
+  least one unresolved `critical`/`high` issue (otherwise it must be `pass`); DT
+  additionally needs test (exit 0 on pass), build/typecheck, lint, non-empty diff,
+  git, ocr/fallback conclusion, and `tdd`.
 
 #### Rework (review failure)
 
@@ -304,10 +359,11 @@ A failed review never mutates a `done` card. Instead the system records
 previous round's issues verbatim in a `## 本轮修复清单` (fix-this-round) section.
 A fresh review card is then dispatched for the rework.
 When `reviewAttempt` reaches `maxReworksPerRole` (PT 3 / DT 3), the system records
-`review/gave-up` and posts a `[review-final]` evidence-chain comment, and (with IM
+`review/gave-up` and posts a `[review-final]` evidence-chain comment (the same marker
+is reused by the convergence-gate downgrade below), and (with IM
 delivery enabled) sends a `[评审超限待裁决]` notification with two exit paths:
 waive the review (`kanban_waive_review` / GUI “豁免评审”) or reopen the chain
-(`kanban_reopen_chain` / GUI “人工恢复”). **Convergence gate (2026-09-15)**: on PT
+(`kanban_reopen_chain` / GUI “人工恢复”). **Convergence gate**: on PT
 rework rounds, once all legacy issues are resolved and no unresolved `critical`
 remains, a `fail` verdict is downgraded to `pass` (new findings flow downstream as
 non-blocking suggestions), so the loop always converges.
@@ -330,17 +386,19 @@ Two orthogonal failure paths, both human-recoverable:
   model candidates (primary + fallbacks, `reasoningEffort: high` default) fall
   back silently (audited via `[model-fallback]` comment); if *all* candidates fail
   it blocks `model-unavailable` for the human. A single hanging V wake cannot
-  stall the scheduler — every dispatch is wrapped in a timeout.
+  stall the scheduler — V wakes are wrapped in a 60 s timeout (role-task dispatch
+  still awaits the session's `whenIdle`).
 
 #### Chain completion: audit gate + merge gate
 
 When the mechanical chain-complete rule fires, two gates run in the
 `chain/completed` hook:
 
-1. **Completion audit gate**: the `ChainAuditor` cross-checks the chain
-   workspace for artifacts written outside the known task outputs. Orphaned writes
-   emit `chain/audit-warning`; the UI shows a warning banner and blocks the final
-   summary until the human confirms ownership (`chain/audit-confirmed`, human-only).
+1. **Completion audit gate**: the `ChainAuditor` scans live non-role sessions for
+   write-capable tool calls aimed at the chain workspace (`kanban-*` preset subagents
+   exempt), then reconciles artifact ownership as a mechanical fallback. Orphaned
+   writes emit `chain/audit-warning`; the UI shows a warning banner and blocks the
+   final summary until the human confirms ownership (`chain/audit-confirmed`, human-only).
 2. **Merge gate (post-DT system merge)**: D never merges to the target branch and
    never pushes it — it only commits to (and optionally pushes) its feature branch,
    carrying `branch` in its handoff. The target branch is the one declared in the
@@ -349,33 +407,38 @@ When the mechanical chain-complete rule fires, two gates run in the
    → git merge --no-ff <feature-branch> → git push`. Outcomes are recorded as
    idempotent comments: `[merge-done]` (with hash), `[merge-skip]` (merge input
    unresolvable), or `[merge-failed]` (checkout/merge/push failed, e.g. a conflict).
-   Failures never throw — a bad merge is never performed, which is the safe
-   direction; humans can repair afterwards.
+   Failures never throw — the gate only records `[merge-failed]`; note that a failed
+   push can leave the target branch already merged locally, and a conflicting merge
+   leaves the worktree mid-merge. Repairing is a human job.
 
 ### Event sourcing & domain model
 
 Every state change is appended to `<storageDir>/events.jsonl`, one JSON event per
-line. The `seq` is assigned by the store (re-read from the file tail on every
-append, so concurrent instances never collide). The **trajectory is the event log
-itself**; restart replays it to rebuild the board.
+line. The `seq` is assigned by the store (re-read from the file tail on every append
+as the last line's `seq` + 1) — append-only, except that a human chain delete purges
+that chain's lines and renumbers the remaining `seq` values. The **trajectory is the
+event log itself**; restart replays it to rebuild the board.
 
 ```jsonc
 // one line in events.jsonl
 { "seq": 12, "chainId": "ch_x_...", "taskId": "t_y_...",
   "kind": "task/completed",
-  "payload": { "summary": "...", "metadata": { /* handoff evidence */ } },
+  "payload": { "summary": "...", "metadata": { /* handoff evidence */ }, "completedAt": 1760000000000 },
   "author": "w", "at": 1760000000000 }
 ```
 
-Event families: `chain/*` (created, executing, completed, aborted, root-task-set,
-audit-warning, audit-confirmed, title-updated), `spec-card/*` (created, edited,
-approved), `task/*` (created, claimed, heartbeat, commented, completed, blocked,
-unblocked, failed, archived, renamed), and `review/*` (passed, failed, gave-up).
+Event families actually emitted: `chain/*` (created, executing, completed, blocked,
+reopened, root-task-set, audit-warning, audit-confirmed, title-updated,
+im-delivery-failed), `spec-card/*` (created, edited, approved), `task/*` (created,
+claimed, heartbeat, commented, completed, blocked, unblocked, failed, archived,
+renamed, gate-passed, gate-failed, gate-skipped), and `review/*` (passed, failed,
+gave-up, waived, evidence-check).
 
-Replay is **strict**: the projection applies every event through the state machine
-and throws on any illegal transition, so a corrupted or tampered log fails loudly
-instead of silently producing an inconsistent board (covered by
-`tests/redteam/anti-escalation.test.ts` and `tests/domain/projection.test.ts`).
+Replay is **strict**: the projection replays every transition event through the state
+machine and throws on any illegal transition, so a corrupted or tampered log fails
+loudly instead of silently producing an inconsistent board (non-transition kinds such
+as `task/commented` are recorded as no-ops). Covered by
+`tests/redteam/anti-escalation.test.ts` and `tests/domain/projection.test.ts`.
 
 The service emits events through a serialized queue (append-then-publish), and
 subscribers (SSE) receive every event exactly once in order. UI and dispatcher both
@@ -383,36 +446,38 @@ consume the same persisted events — there is no secondary source of truth.
 
 ### Web client (Workflow kanban tab)
 
-A browser-half React tab registered as the third `conversation.view` slot
-(`id=kanban`, `order=20`, after Conversation and Trajectory). It registers **no
+A browser-half React tab registered into `conversation.view` (`id=kanban`,
+`order=20`, so it sits after Conversation and Trajectory). It registers **no
 shell-level overlays, sidebars, or detail panes**.
 
 - **Data path**: initial snapshot (`GET /kanban/board`) → SSE stream
   (`GET /kanban/events?after=<seq>`) → board-store applies events incrementally,
   deduplicates by `seq`, and re-pulls the full snapshot on any gap. **No business
   polling.**
-- **Layout**: multi-chain vertical rails; fixed content width 715–780 px, full
-  height; the active chain is expanded, blocked chains always show a warning
-  summary. In-page rename/delete use a lightweight modal (no shell overlays);
-  no drag-and-drop, no width memory.
+- **Layout**: multi-chain vertical rails; the width follows the host conversation
+  width (`--dsh-chat-content-width`, 780 px fallback), full height; the active chain
+  is expanded, blocked chains always show a warning summary. In-page rename/delete use
+  a lightweight modal (no shell overlays); no drag-and-drop, no width memory.
 - **Cards**: compact two-line cards with profile-colored nodes; status lines are
   green solid (done) / blue solid (current) / gray dashed (pending) / red broken
   (blocked).
 - **Detail drawer**: five sections — Overview / Trajectory / Handoff / Spec /
   Comments; `Esc` or back returns to the list.
 - **Actions** (`POST /kanban/action`): block / unblock / retry / complete /
-  archive / comment, plus chain-level `confirm-audit`, `rename` (chain or task),
-  and `delete` (chain, human-only, double-confirmed in the GUI). Human actions
-  apply optimistic updates with rollback; the store reconciles against the
-  authoritative snapshot on any divergence.
+  archive / comment / `waive-review`, plus chain-level `confirm-audit`, `rename`
+  (chain or task), `reopen-chain` and `delete` (chain, human-only, double-confirmed in
+  the GUI). Status actions (block / unblock / complete / archive / retry) apply
+  optimistic updates with rollback; the rest wait for the server event, and the store
+  re-pulls the authoritative snapshot on any divergence.
 - **Build**: `npm run build:client` produces `lib/client.js` in the
   `window.__ModuleLoader__.load()` format (identical convention to `dsh-client-*`).
   Adding dsh-swarm to a web profile auto-embeds it into `__DSH_BOOT__`.
 
 ### Architecture
 
-Five layers, with the domain layer kept **free of any DSH dependency** so it can be
-fully unit-tested and replayed in isolation.
+Layers, with the domain layer kept free of **runtime** DSH dependencies (a single
+type-only import of `ObjectJsonSchema` in `prefetch-manifest.ts`) so it can be fully
+unit-tested and replayed in isolation.
 
 ```mermaid
 flowchart TB
@@ -422,7 +487,7 @@ flowchart TB
         Model["workflow-model: pure view projection"]
     end
 
-    subgraph Domain ["domain/ (pure TS, zero DSH deps)"]
+    subgraph Domain ["domain/ (pure TS; no runtime DSH deps)"]
         ES["event-store (JSONL append-only, monotonic seq)"]
         SM["state-machine (task/chain/spec transitions)"]
         PJ["projection (events → BoardState)"]
@@ -452,6 +517,14 @@ flowchart TB
         WK["wiki-worker (W prefetch worker)"]
     end
 
+    subgraph Services ["services/"]
+        PROVIDER["kanban-provider (gate + evidence wiring)"]
+        GATERUN["gate-runner / gate-evidence / evidence-replay"]
+        OCRCLI["ocr-cli"]
+        IMD["im-delivery"]
+        CFG["config-provider"]
+    end
+
     subgraph Wiki ["wiki/"]
         WVC["wiki-vault-client (search/read/write)"]
     end
@@ -471,6 +544,11 @@ flowchart TB
     MG --> KS
     KS --> ES --> PJ --> SM --> PM
     EC --> KS
+    PROVIDER --> KS
+    GATERUN --> PROVIDER
+    OCRCLI --> TOOLSETS
+    IMD --> KS
+    CFG --> VORCH
 ```
 
 #### Layer responsibilities
@@ -482,6 +560,10 @@ flowchart TB
 - **Integration** (`src/tools/`, `src/routes/`) — cordis tools and routes:
   the role tool faces, main-session tools (`kanban_route` + read-only subset), and
   the `/kanban/*` HTTP/SSE bridge.
+- **Services** (`src/services/`) — provider wiring (`kanban-provider` installs the gate
+  and evidence-check hooks), the gate runner / evidence replay, `ocr-cli`, IM delivery
+  and the config provider; the scheduler itself (`src/dispatcher/dispatcher.ts`)
+  belongs to the Dispatcher layer.
 - **Dispatcher** (`src/dispatcher/`) — event wake, phase orchestration, one-shot
   agent runner (persona preset mounting, model candidate chain, ToolGuard
   installation), watchdog, chain auditor, and merge gate.
@@ -496,7 +578,7 @@ Quality gates (see `AGENTS.md`):
 
 ```bash
 npm run typecheck   # tsc -p tsconfig.json --noEmit  (0 errors)
-npm test            # npx vitest run  (all green)
+npm test            # vitest run  (all green)
 npm run build       # tsc -p tsconfig.build.json + build:client (lib/client.js)
 ```
 
@@ -510,39 +592,6 @@ python tests/e2e/gui-check.py --url http://127.0.0.1:3080/
 > Deploying to a running DSH instance requires a plugin reload/restart; building
 > alone does not hot-reload the running plugin.
 
-### Implemented & known limitations
-
-#### Implemented (v0.1.0)
-
-- [x] **Swarm mode**: natural-language intent recognition (plan/openspec/learning/send) + confirmation gate + read-only main-session hard gate
-- [x] Event-sourced domain + deterministic state machines (red-team replay)
-- [x] 6-role phase pipeline with trimmed presets and session-bound permissions
-- [x] Delivery contract + review evidence gates + rework lifecycle
-- [x] TDD hard gate (D `tdd` handoff + DT `test_first` / `runner=vitest` verification)
-- [x] Protocol-violation recovery, heartbeat watchdog, failure circuit
-- [x] Chain completion audit gate + human confirm
-- [x] Post-DT merge gate (D pushes feature branch only)
-- [x] Phase-0 planning checklist + `file-prefetch` attachment
-- [x] GUI chain/task rename + chain delete (human-only)
-- [x] Model candidate chain with silent fallback + high reasoning effort
-- [x] Live SSE kanban tab (Conversation → Trajectory → Kanban)
-
-#### Known limitations
-
-- **Swarm-mode intent recognition relies on model self-judgment**: misjudgments are caught by the confirmation gate (no confirmation, no chain), but the risk is non-zero.
-- **Write guards are string-heuristic, not hard isolation.** PT/DT ToolGuards
-  rely on path/command regex and reviewers get no git credentials; a soft
-  constraint plus audit trail, not a mount-level sandbox.
-- **`open-code-review` (ocr) is optional per machine**: when missing, in-chain
-  reviews block `review-tool-unavailable` before DT starts, with install guidance
-  (one-click GUI install available) — no retries burned.
-- **Review evidence is existence-checked, not replay-proven.** Fields must be
-  present and well-formed; proving the tests actually ran is not yet supported.
-- **Single default wiki-vault host** in the config default — point
-  `wikiVault.baseUrl` at your deployment.
-- **PT creation depends on P's self-reported `pt_decision.needed`** —
-  system-assisted detection from repo signals is not yet implemented.
-
 ---
 
 ## License