@mstar-harness/dsh 2.4.1 → 3.1.0

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # Blob hashes (git hash-object) of each side as of the last confirmation that
 # both languages say the same thing (dsh i18n contract: a pair is three
 # sibling files; editing either side obligates re-confirming and re-recording).
-README.md: d942e880bbc5c8dc34940251df7666cf81345042
-README.zh.md: 7a3e913084e5d79271828b5f3f5f27e41aca85fe
+README.md: c328842bbac14e2a1540209a5339369ec390a40e
+README.zh.md: da5d2a839fd39c3b9a58a1a4d2648f638da5c1f3

package/README.md

@@ -2,6 +2,8 @@
 
 English | [中文](README.zh.md)
 
+![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.8-4B32C3.svg)
+
 [Morning Star](https://github.com/btspoony/mstar-harness) as a first-class dsh (DeepSeek Harness) host — a cordis function plugin that mounts the mstar engine in-process, implements the engine `HostAdapter` (`host: 'dsh'`), guards `{HARNESS_DIR}/status.json` writes (validate + advisory; repair-escape under hard), blocks disallowed subagent dispatches when `Enforcement: hard` is on, lints `SKILL.md` writes under the mounted skill roots, mounts the mstar `skills/` mirror through the dsh skill-filesystem provider (single canonical mount), and appends a durable `mstar-engine-status` catalog row to every composed agent step. Boot with a dsh Loader app; everything acts through the seam's refusal/advisory channels, never by patching the tools.
 
 ## Usage
@@ -45,8 +47,8 @@ The **two-command install is the contract** — folding a `dsh-llm-fallbacks` ro
 
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `harnessDir` | `string` | per-session workspace probe (`.mstar/` → `.agents/` → `.plans/` → `plans/`, from the session workspace root — **never the launch cwd**) | Explicit harness root; wins over engine probing. **Required for repos whose harness root is not a probed name** — e.g. this mstar-workflow repo itself uses `.harness/` (maintenance root, deliberately NOT probed); the probe starts from the session workspace root (never the launch cwd) and STOPS there — it never walks above the session workspace, so a harness dir above it (e.g. a global `~/.mstar`) is never adopted. |
-| `enforcement` | `'hard' \| 'soft'` | compass, else warn-only | Per-deployment override. Precedence: Config wins; else the Assignment's own `**Enforcement**: hard` header flag (dispatch gate only); else the iteration compass frontmatter; else warn-only. Config `soft` is the ONLY local rollback — an Assignment-level `soft` does NOT override a hard compass. |
+| `harnessDir` | `string` | repo `.mstarc` `[config] harness_dir`, else per-session workspace probe (`.mstar/` → `.agents/` → `.plans/` → `plans/`, from the session workspace root — **never the launch cwd**) | Explicit harness root; wins over engine probing. **Required for repos whose harness root is not a probed name**; the probe starts from the session workspace root (never the launch cwd) and STOPS there — it never walks above the session workspace, so a harness dir above it (e.g. a global `~/.mstar`) is never adopted. |
+| `enforcement` | `'hard' \| 'soft'` | compass, else warn-only | Per-deployment override. Precedence: Config wins; else the Assignment's own `**Enforcement**: hard` header flag (dispatch gate only); else the repo `.mstarc` `[config] enforcement`; else the iteration compass frontmatter; else warn-only. Config / `.mstarc` `soft` are the ONLY local rollbacks — an Assignment-level `soft` does NOT override a hard compass. |
 | `dispatchTools` | `string[]` | `['subagent', 'subagent_fork']` | Delegation tool names the dispatch gate matches — the dsh preset's TWO delegation tools, `subagent` and its fork sibling `subagent_fork` (both carry Assignment-shaped `{ description, prompt }` args; a `toolName` config may rename instances). |
 | `dispatchBinding` | `string` | unset (precheck skipped) | The dispatching agent's own harness role; an Assignment whose `Execute as` equals it is self-recursion. |
 | `roleMap` | `Record<string, string>` | unset | mstar role id (`Execute as`) → dsh-llm-fallbacks role id. A taxonomy bridge for logging + future rule-driven interop ONLY — never consulted by the decoration (see LLM fallbacks integration). |
@@ -74,11 +76,11 @@ The registry rows mount before the plugin so `ctx.skills` / `ctx.tools` / `ctx.c
 
 ### What the plugin does when mounted
 
-- **Status gate** — `fs/write-intent` + `fs/edit-intent` listeners validate `{HARNESS_DIR}/status.json` writes (engine `validateStatus` + per-plan `findingsCleanupGate` over the pre-write document).
+- **Status gate** — `fs/write-intent` + `fs/edit-intent` listeners validate the v3 coordination-document target set — the v2 root `{HARNESS_DIR}/status.json`, `workflows/<id>/snapshot.json` and `projects/<id>/residuals.json` — each with its matching engine validator (`validateStatus` = v2 root / `validateWorkflowSnapshot` / `validateProjectRegister`, the P2-fixed `harnessDocKindOfTarget` shape), plus the snapshot-target `findingsCleanupGate` extension per plan row that configures a mode (residuals read from the project registers).
 - **Dispatch gate** — a `tools/pre-execute` listener on the delegation tool(s) validates subagent Assignment text through the engine's single `composeDispatchGate` composition (field gate, anti-recursion precheck, default-branch gate — opencode/omp/CLI parity, so violation codes are identical by construction) plus the dsh lease gate and worktree L1/L2 checks.
 - **Skill-authoring lint** — `SKILL.md` writes under the configured skill roots run the engine skill-authoring lints (`lintFrontmatter` + `lintFiveQuestion`).
 - **Seam lints** — `DESIGN.md` / audit-plan / knowledge-doc / roles-dir writes under the harness get their artifact-specific engine lints.
-- **Model-facing tools** — `mstar_sdd_workspace`, `mstar_sdd_task_brief`, `mstar_iteration_gate`, `mstar_design_md_validate`, `mstar_audit_validate`, `mstar_compound_validate`, `mstar_roles_validate` register on `ctx.tools`.
+- **Model-facing tools** — `mstar_sdd_workspace`, `mstar_sdd_task_brief`, `mstar_iteration_gate`, `mstar_design_md_validate`, `mstar_audit_validate`, `mstar_compound_validate`, `mstar_roles_validate` register on `ctx.tools`. The `mstar_iteration_gate` mirror takes the v3 input `snapshot_path` (`{HARNESS_DIR}/workflows/<id>/snapshot.json` — mirror of `mstar iteration gate --workflow <id>`; the old `status_path` root input is gone with the v1 read path).
 - **Bundled commands** — `ctx.commands` registrations for `/iteration-start`, `/iteration-drive`, `/iteration-loop`, `/codebase-audit` (from the packaged `harness-commands/` mirror; each declares a frontmatter `input` hint so the web client claims `/name ` and waits for the user's follow-up args instead of executing immediately; handlers steer the command body + user args into the receiving agent).
 - **Pre-step catalog row** — every composed agent step appends ONE unified `mstar-engine-status` catalog message: the watermark (unified mstar version, harness dir, enforcement), the iteration phase-gate section (when a steering compass resolves) and the workspace-state digest (plan registry, open residuals, branch/policy anchors, active leases, knowledge digest, compass direction — when the workspace has a `status.json`). The row is digest-gated (injected once per turn, re-injected only when it changed) and shares one TTL-cached per-workspace build (`catalogTtlMs`, default 60 s).
 
@@ -90,7 +92,7 @@ Warn-only by default: gate violations log and emit advisory events (`mstar/statu
 
 ### Status gate
 
-`fs/write-intent` + `fs/edit-intent` listeners (registered `prepend` so they run before dsh-fs-policy) gate writes to `{HARNESS_DIR}/status.json`: `validateStatus` + per-plan `findingsCleanupGate` over the current on-disk document (parsed exactly once — no TOCTOU double read). The gate **never throws**: every decision surfaces as the `mstar/status-gate` advisory and the intent waterfall is delegated via `next()`. Warn mode (default) logs + emits on violations. Hard mode allows an **already-invalid** document as a **repair escape** (error-level log + advisory with `hard: true, repair: true`) — the intent waterfall carries no incoming content, so a hard veto on an invalid document would deadlock the very write that repairs it. Unexpected internal errors degrade to allow in BOTH modes with a `degraded: true` advisory (error-containment envelope); the corrupting write itself cannot be vetoed on this seam (see Known Limitations).
+`fs/write-intent` + `fs/edit-intent` listeners (registered `prepend` so they run before dsh-fs-policy) gate writes to the v3 harness coordination-document target set — the v2 root `status.json`, `workflows/<id>/snapshot.json` and `projects/<id>/residuals.json` — each validated by its matching engine validator (`harnessDocKindOfTarget` classification; the snapshot kind additionally runs the `findingsCleanupGate` extension per plan row that configures a mode, over the project registers), against the current on-disk document (parsed exactly once — no TOCTOU double read). The gate **never throws**: every decision surfaces as the `mstar/status-gate` advisory and the intent waterfall is delegated via `next()`. Warn mode (default) logs + emits on violations. Hard mode allows an **already-invalid** document as a **repair escape** (error-level log + advisory with `hard: true, repair: true`) — the intent waterfall carries no incoming content, so a hard veto on an invalid document would deadlock the very write that repairs it. Unexpected internal errors degrade to allow in BOTH modes with a `degraded: true` advisory (error-containment envelope); the corrupting write itself cannot be vetoed on this seam (see Known Limitations).
 
 ### Dispatch gate
 
@@ -98,7 +100,7 @@ Warn-only by default: gate violations log and emit advisory events (`mstar/statu
 
 ### Lease gate
 
-Additive beyond the opencode field set: for writable dispatches whose Assignment declares `Execution mode: sdd` or whose plan row is `InProgress`, `verifyPlanExecutionLease` + dispatch-context comparisons (`holder`, `worktree_path`, `working_branch`) run against `{HARNESS_DIR}/status.json`. Violations use the dsh-side `lease.dispatch.*` namespace; read-only roles skip the check entirely. A **missing** `status.json` on an sdd dispatch is NOT a silent fail-open: it surfaces `lease.dispatch.unverifiable` (advisory in warn, deny under hard) — the execution_lease cannot be confirmed without the status file. Non-SDD dispatches keep the degrade-allow (no lease obligation). All Assignment field reads are scoped to the engine `assignmentHeaderRegion` (body-quoted examples never leak into header fields).
+Additive beyond the opencode field set: for writable dispatches whose Assignment declares `Execution mode: sdd` or whose plan row is `InProgress`, `verifyPlanExecutionLease` + dispatch-context comparisons (`holder`, `worktree_path`, `working_branch`) run against the ACTIVE workflow snapshot's plan rows (`workflows/<id>/snapshot.json` — the v3 lease home; the root v2 `status.json` supplies the active `workflows[]`). Violations use the dsh-side `lease.dispatch.*` namespace; read-only roles skip the check entirely. A **missing** `status.json` on an sdd dispatch is NOT a silent fail-open: it surfaces `lease.dispatch.unverifiable` (advisory in warn, deny under hard) — the execution_lease cannot be confirmed without the status file. Non-SDD dispatches keep the degrade-allow (no lease obligation). All Assignment field reads are scoped to the engine `assignmentHeaderRegion` (body-quoted examples never leak into header fields).
 
 ### Skill lint gate
 
@@ -470,8 +472,8 @@ Verified locally (install-verification guide): the boot graph contains the
 client entry (`@mstar-harness/dsh` with the declared inject faces), the
 `/plugins/<id>/client.js` route serves the exact built bundle (rev = content
 sha1), and the browser handoff materializes the plugin entry (`inject` +
-`apply` + CSS injection under classic-script semantics) — see
-`.mstar/iterations/iter-20260809-mstar-panel-beautify/guides/install-verification.md`.
+`apply` + CSS injection under classic-script semantics) — see the
+`install-verification.md` guide of the panel-beautify iteration (local harness root).
 
 **Known Limitations** (this iteration): the iteration stepper's Step 1
 (iteration-start) IS the current step while the steering compass is

package/README.zh.md

@@ -2,6 +2,8 @@
 
 [English](README.md) | 中文
 
+![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.8-4B32C3.svg)
+
 让 [Morning Star](https://github.com/btspoony/mstar-harness) 成为一等公民的 dsh（DeepSeek Harness）宿主——一个 cordis 函数插件，将 mstar engine 进程内挂载，实现 engine `HostAdapter`（`host: 'dsh'`），守护 `{HARNESS_DIR}/status.json` 写入（校验 + 咨询；hard 下按修复逃生放行），在 `Enforcement: hard` 开启时阻止被禁止的 subagent 派发，对挂载技能根下的 `SKILL.md` 写入执行技能撰写 lint，通过 dsh skill-filesystem 提供者挂载 mstar `skills/` 镜像（单一规范挂载），并向每个组合后的 agent 步骤追加一条持久化的 `mstar-engine-status` catalog 行。随 dsh Loader 应用启动；一切均通过 seam 的拒绝/咨询通道行使职责，从不改动工具本身。
 
 ## Usage
@@ -45,8 +47,8 @@ dsh plugin --profile web add dsh-llm-fallbacks
 
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `harnessDir` | `string` | 按会话工作区探测（`.mstar/` → `.agents/` → `.plans/` → `plans/`，从会话工作区根目录开始——**绝不从启动 cwd**） | 显式 harness 根目录；优先于 engine 探测。**harness 根不在探测名列表中的仓库必须配置**——例如本 mstar-workflow 仓库自身用 `.harness/`（维护根，刻意不探测）；探测从会话工作区根开始（绝不从启动 cwd）并在那里**停止**——永不越过会话工作区向上，因此其上方的 harness 目录（如全局 `~/.mstar`）永远不会被采纳。 |
-| `enforcement` | `'hard' \| 'soft'` | compass，否则仅告警 | 按部署覆盖。优先级：Config 优先；否则取 Assignment 自身的 `**Enforcement**: hard` 头字段（仅派发闸门）；否则取迭代 compass frontmatter；否则仅告警。Config `soft` 是唯一的本地回滚——Assignment 级 `soft` 不能覆盖 hard compass。 |
+| `harnessDir` | `string` | 仓库 `.mstarc` `[config] harness_dir`，否则按会话工作区探测（`.mstar/` → `.agents/` → `.plans/` → `plans/`，从会话工作区根目录开始——**绝不从启动 cwd**） | 显式 harness 根目录；优先于 engine 探测。**harness 根不在探测名列表中的仓库必须配置**；探测从会话工作区根开始（绝不从启动 cwd）并在那里**停止**——永不越过会话工作区向上，因此其上方的 harness 目录（如全局 `~/.mstar`）永远不会被采纳。 |
+| `enforcement` | `'hard' \| 'soft'` | compass，否则仅告警 | 按部署覆盖。优先级：Config 优先；否则取 Assignment 自身的 `**Enforcement**: hard` 头字段（仅派发闸门）；否则取仓库 `.mstarc` `[config] enforcement`；否则取迭代 compass frontmatter；否则仅告警。Config / `.mstarc` `soft` 是仅有的本地回滚——Assignment 级 `soft` 不能覆盖 hard compass。 |
 | `dispatchTools` | `string[]` | `['subagent', 'subagent_fork']` | 派发闸门匹配的委派工具名——dsh preset 的**两个**委派工具：`subagent` 及其 fork 兄弟 `subagent_fork`（两者都携带 Assignment 形态的 `{ description, prompt }` 参数；`toolName` 配置可重命名实例）。 |
 | `dispatchBinding` | `string` | 未设置（跳过预检） | 派发方 agent 自身的 harness 角色；Assignment 的 `Execute as` 等于它即自我递归。 |
 | `roleMap` | `Record<string, string>` | 未设置 | mstar 角色 id（`Execute as`）→ dsh-llm-fallbacks 角色 id。**仅**作日志与未来规则驱动互操作的分类桥——装饰从不读取它（见 LLM fallbacks integration）。 |
@@ -74,11 +76,11 @@ profile bundle 组合出以下行——注册表行来自 `@deepseek-ai/dsh-base
 
 ### What the plugin does when mounted
 
-- **状态闸门**——`fs/write-intent` + `fs/edit-intent` 监听器校验 `{HARNESS_DIR}/status.json` 写入（对写入前文档运行 engine `validateStatus` + 按 plan 的 `findingsCleanupGate`）。
+- **状态闸门**——`fs/write-intent` + `fs/edit-intent` 监听器校验 v3 协调文档目标集——v2 根 `{HARNESS_DIR}/status.json`、`workflows/<id>/snapshot.json` 与 `projects/<id>/residuals.json`——各自使用匹配的 engine 校验器（`validateStatus` = v2 根 / `validateWorkflowSnapshot` / `validateProjectRegister`，即 P2 修复的 `harnessDocKindOfTarget` 形态），外加快照目标的 `findingsCleanupGate` 扩展（按配置模式的计划行，从项目注册表读取残留）。
 - **派发闸门**——`tools/pre-execute` 监听器作用于委派工具，通过 engine 的单一 `composeDispatchGate` 组合（字段闸门、反递归预检、默认分支闸门——与 opencode/omp/CLI 对齐，违规码按构造即相同）校验 subagent Assignment 文本，外加 dsh 租约闸门与 worktree L1/L2 检查。
 - **技能撰写 lint**——已配置技能根下的 `SKILL.md` 写入运行 engine 技能撰写 lint（`lintFrontmatter` + `lintFiveQuestion`）。
 - **seam lint**——harness 下 `DESIGN.md` / audit plan / 知识文档 / roles 目录的写入运行各自的 artifact 级 engine lint。
-- **模型可见工具**——`mstar_sdd_workspace`、`mstar_sdd_task_brief`、`mstar_iteration_gate`、`mstar_design_md_validate`、`mstar_audit_validate`、`mstar_compound_validate`、`mstar_roles_validate` 注册到 `ctx.tools`。
+- **模型可见工具**——`mstar_sdd_workspace`、`mstar_sdd_task_brief`、`mstar_iteration_gate`、`mstar_design_md_validate`、`mstar_audit_validate`、`mstar_compound_validate`、`mstar_roles_validate` 注册到 `ctx.tools`。`mstar_iteration_gate` 镜像改用 v3 输入 `snapshot_path`（`{HARNESS_DIR}/workflows/<id>/snapshot.json`——镜像 `mstar iteration gate --workflow <id>`；旧的根 `status_path` 输入随 v1 读取路径移除）。
 - **bundled 命令**——向 `ctx.commands` 注册 `/iteration-start`、`/iteration-drive`、`/iteration-loop`、`/codebase-audit`（来自打包的 `harness-commands/` 镜像；每条声明 frontmatter `input` hint，使 web 客户端 claim `/name ` 并等待用户后续输入而非立即执行；handler 把命令正文 + 用户输入 steer 进接收 agent）。
 - **pre-step catalog 行**——每个组合后的 agent 步骤都会追加**一条**统一的 `mstar-engine-status` catalog 消息：水印（统一 mstar 版本、harness 目录、enforcement）、迭代相位闸门段（解析到 steering compass 时）与工作区状态摘要段（工作区有 `status.json` 时：plan 注册表、open residual、分支/政策锚点、活跃 lease、知识摘要、compass 方向）。该行是 digest 门控的（每 turn 注入一次、变化时才重发），并共享一次按工作区 TTL 缓存的构建（`catalogTtlMs`，默认 60 秒）。
 
@@ -272,7 +274,7 @@ dsh plugin --profile web add <abs packages/dsh path>   # 同一 profile bundle
 dsh web                     # 启动 → 服务 /plugins/@mstar-harness/dsh/client.js
 ```
 
-本地已验证（install-verification guide）：boot 图包含客户端 entry（`@mstar-harness/dsh` 携声明的 inject 面）、`/plugins/<id>/client.js` 路由服务的正是构建产物（rev = 内容 sha1）、浏览器握手 materialize 出插件入口（`inject` + `apply` + CSS 注入，经典脚本语义）——见 `.mstar/iterations/iter-20260809-mstar-panel-beautify/guides/install-verification.md`。
+本地已验证（install-verification guide）：boot 图包含客户端 entry（`@mstar-harness/dsh` 携声明的 inject 面）、`/plugins/<id>/client.js` 路由服务的正是构建产物（rev = 内容 sha1）、浏览器握手 materialize 出插件入口（`inject` + `apply` + CSS 注入，经典脚本语义）——见 panel-beautify 迭代的 `install-verification.md` guide（本地 harness root）。
 
 **Known Limitations**（本迭代）：迭代 stepper 的 Step 1（iteration-start）在 steering compass `status: active`（Phase 1 进行中——catalog `compassStatus` 字段）时为**当前步**，且不携带 PASS/FAIL 徽标（Phase 1 无 gate 判定）；Step 5（merge-ready）**永远不会是当前步**——engine 相位门只评估 Phase 2→3→4（merge-ready 从不是 gate transition）；仅当 Step 4（pr-delivery）为当前步时渲染 `next`，其余为 idle；当前步跟随 TTL 刷新的 `compassStatus`——会话中途 `active`→`locked` 翻转后最多落后一个 catalog 间隔（60 秒）（有界、已记录的陈旧；绝不给出错误判定）；代理实体状态按**精确配对**派生（paired settle 携带的 `(agent, role, planId, taskId)` 标识精确配对到对应派发——QC tri N=3 并发下各卡各自结算；未配对派发保持 running，绝不捏造）；无 steering compass 时的「当前迭代」过滤按 plan id（8 位日期前缀）+ doneAt 推导迭代——确定性、已记录的启发式，且只丢弃可证明跨迭代的事件）；不回溯 resumed 长日志的历史行（服务端每 turn 首步必重发，digest 门控）；无自定义顶层槽位（不改 dsh-private 布局的前提下，`conversation.view` tab 是唯一的会话级面板位——spec §1）。面板验收为双轨：in-loop 浏览器 harness 验证（对重建 bundle，见迭代 guides `iter-20260810-panel-zones/guides/`）+ 用户重启后 GUI 终验——重跑步骤见 install-verification guide §8。R1（浏览器观察）已于 2026-08-10 关闭归档。
 

package/bundle/README.md

@@ -76,8 +76,8 @@ The `mstar` row accepts the plugin `Config` (see `src/index.ts`):
 
 | Field | Shipped default | Meaning |
 |---|---|---|
-| `harnessDir` | unset (resolved per session workspace) | explicit `{HARNESS_DIR}` root — **required for repos whose harness root is not a probed name** (`.mstar/` → `.agents/` → `.plans/` → `plans/`): e.g. the mstar-workflow maintenance repo itself uses `.harness/` (deliberately not probed), so set `harnessDir: <repo>/.harness` in the profile layer. Without the config the probe starts from the SESSION workspace root (the session cwd — **never the process/launch cwd**) and **stops there** — it never walks above the session workspace, so a global `~/.mstar` is never adopted |
-| `enforcement` | **unset — default OFF** | `hard` / `soft` override; absent → the iteration compass decides, warn-only when no compass hardens (never a global always-on hard gate) |
+| `harnessDir` | unset (resolved per session workspace) | explicit `{HARNESS_DIR}` root — **required for repos whose harness root is not a probed name** (`.mstar/` → `.agents/` → `.plans/` → `plans/`); set it to the absolute root in the profile layer (or declare `[config] harness_dir` in a repo `.mstarc` — gitignored local config, honored above probing). Without either, the probe starts from the SESSION workspace root (the session cwd — **never the process/launch cwd**) and **stops there** — it never walks above the session workspace, so a global `~/.mstar` is never adopted |
+| `enforcement` | **unset — default OFF** | `hard` / `soft` override; absent → the repo `.mstarc` `[config] enforcement`, else the iteration compass decides, warn-only when no compass hardens (never a global always-on hard gate) |
 | `dispatchTools` | unset (plugin default `['subagent', 'subagent_fork']`) | delegation tool names the dispatch gate matches — the dsh preset's TWO delegation tools (`subagent` + its fork sibling `subagent_fork`, both Assignment-shaped); a custom list overrides the default wholesale, so it must include `subagent_fork` to keep fork dispatches gated |
 | `dispatchBinding` | unset | the dispatching agent's role for the anti-recursion precheck |
 | `skillRoots` | unset | additional skill roots (custom mirrors) |
@@ -268,8 +268,8 @@ web loader executes plugin bundles as classic `<script>`s); the full `bun run
 build` runs it after the node half. Verified locally: boot graph entry, the
 `/plugins/<id>/client.js` route serving the exact built bundle, and the
 browser-handoff materialization (`inject`/`apply`/CSS injection under
-classic-script semantics) — see
-`.mstar/iterations/iter-20260809-mstar-panel-beautify/guides/install-verification.md`.
+classic-script semantics) — see the
+`install-verification.md` guide of the panel-beautify iteration (local harness root).
 
 Known limitations (this iteration): the iteration stepper's Step 1
 (iteration-start) IS the current step while the steering compass is

package/dist/client/panel/graph/project-graph.d.ts

@@ -70,11 +70,14 @@
  * steps + `degraded.iteration` (the old `degraded.transition` is merged into
  * `iteration.active === false` — `degraded.iteration ⟺ !active`); `state`
  * null → 5-column skeleton (count 0) + `degraded.state`; `state.plans`
- * missing → same skeleton + `degraded.plans`; `state.agentFlow`
+ * `state.plans` missing → same skeleton + `degraded.plans`; `state.agentFlow`
  * missing/unreadable → agents roster + `degraded` (full KNOWN_AGENTS idle
  * cards, no executing/pending claims); 0 events → `empty` (idle roster +
- * pending skeleton). `iteration.compassStatus` missing, non-union (old
- * catalog rows / fixtures — the field is OPTIONAL, spec D5), or `'active'`
+ * pending skeleton). `state.project` missing/malformed → the additive
+ * project rollup zone (compass AC-4) degrades to empty aggregates — the
+ * four existing ZoneView shapes are unaffected. `iteration.compassStatus`
+ * missing, non-union (old catalog rows / fixtures — the field is OPTIONAL,
+ * spec D5), or `'active'`
  * with a transition past Phase 2 (an inconsistent harness state — QC wave
  * F-001) degrades to the existing transition-driven current-step logic
  * (Step 2→4) — backward compatible, `active` semantics unchanged.
@@ -387,6 +390,25 @@ export interface AgentZoneView {
      * kanban overflow hint; never hides the count behind the first id). */
     activePlanCount: number;
 }
+/**
+ * The additive project rollup zone (plan `20260819-workflow-dsh-viz`
+ * Task 3 — compass v3.0.0 AC-4: "Additive project rollup (roadmap +
+ * residuals) renders without changing the four existing ZoneView shapes"):
+ * roadmap milestones + open-residual severity counts from the project layer
+ * (`state.project` — produced by the catalog from `projects/<id>/roadmap.md`
+ * frontmatter `milestones[]` + `projects/<id>/residuals.json` registers).
+ * Total function: `state.project` missing/malformed → empty aggregates,
+ * never a throw and never a fabricated value.
+ */
+export interface ProjectRollupZoneView {
+    /** Roadmap milestones (non-empty strings, roadmap order). */
+    milestones: string[];
+    /** Open residual severity counts (non-zero severities only). */
+    openResiduals: {
+        severity: string;
+        count: number;
+    }[];
+}
 export interface ZoneView {
     iteration: {
         /** Iteration exists AND `gate.transition` resolves (spec §3; `degraded.iteration ⟺ !active`). */
@@ -416,6 +438,10 @@ export interface ZoneView {
         truncated: boolean;
     };
     agents: AgentZoneView;
+    /** The additive project rollup zone (compass AC-4 — roadmap milestones +
+     * open residual severity counts from `state.project`; additive, the four
+     * existing ZoneView shapes stay byte-compatible). */
+    project: ProjectRollupZoneView;
     /** Current-step gate verdict — footer gate-summary seat (spec §3). */
     verdict: PhaseVerdict;
     /** Gate violations (str()-guarded), for the footer list. */

package/dist/client/panel/locale.d.ts

@@ -122,7 +122,7 @@ import type { LocaleDictOf } from '@deepseek-ai/dsh-client-ui-slots';
 /** Locale namespace id for the workflow-viz panel. */
 export declare const NS = "mstar-panel";
 /** Panel dictionary keys (union of every translatable string the panel renders). */
-export type PanelKey = 'view.mstar-workflow' | 'tab.tasks' | 'tab.agents' | 'tab.events' | 'page.iteration.not-started' | 'page.iteration.expand' | 'page.iteration.collapse' | 'event-log.section.events' | 'event-log.section.violations' | 'event-log.empty' | 'event-log.empty.events' | 'event-log.empty.violations' | 'event-log.field.role' | 'event-log.field.agent' | 'event-log.field.stage' | 'event-log.field.plan' | 'event-log.field.task' | 'event-log.field.category' | 'event-log.field.time' | 'event-log.field.kind' | 'event-log.field.status' | 'event-log.field.expected' | 'event-log.field.settled' | 'event-log.field.duration' | 'event-log.field.run-id' | 'event-log.field.name' | 'event-log.field.members' | 'event-log.field.stop-reason' | 'event-log.field.severity' | 'event-log.field.code' | 'event-log.field.message' | 'event-log.kind.dispatch' | 'event-log.kind.settle' | 'event-log.yes' | 'event-log.no' | 'empty.waiting' | 'empty.no-harness' | 'empty.no-harness-hint' | 'watermark.version' | 'watermark.harness' | 'watermark.none' | 'panel.unknown' | 'graph.pass' | 'graph.fail' | 'zone.legend.title' | 'zone.legend.agent-running' | 'zone.legend.agent-settled' | 'zone.legend.agent-idle' | 'zone.iteration.step-label' | 'zone.iteration.step-badge' | 'zone.iteration.step.current' | 'zone.iteration.step.next' | 'zone.iteration.step.done' | 'zone.iteration.step.idle' | 'zone.phase.iteration-start' | 'zone.phase.autonomous-execute' | 'zone.phase.iteration-close' | 'zone.phase.pr-delivery' | 'zone.phase.merge-ready' | 'zone.branches.title' | 'zone.branches.iteration-base' | 'zone.branches.target' | 'zone.branches.spec-integration' | 'zone.tasks.title' | 'zone.tasks.total' | 'zone.tasks.no-plans' | 'zone.tasks.more' | 'zone.tasks.collapse' | 'zone.state.Todo' | 'zone.state.InProgress' | 'zone.state.InReview' | 'zone.state.Done' | 'zone.state.blocked-unknown' | 'zone.agents.title' | 'zone.agents.summary' | 'zone.agents.on-demand' | 'zone.agents.unknown-sub' | 'zone.agents.bucket.implementor' | 'zone.agents.bucket.reviewer' | 'zone.agents.group.phase-1' | 'zone.agents.group.phase-2' | 'zone.agents.group.phase-n' | 'zone.agents.group.plan' | 'zone.agents.group.no-plan' | 'zone.agents.group.plan-more' | 'flow.empty' | 'flow.settle-only' | 'flow.degraded' | 'flow.unexpected' | 'flow.in-flight' | 'flow.settled-ok' | 'flow.error' | 'flow.advisory' | 'flow.denied' | 'state.title' | 'state.plans' | 'state.residuals' | 'state.policy' | 'state.leases' | 'state.knowledge' | 'state.direction' | 'state.none' | 'state.enforcement' | 'state.enforcement.hard' | 'state.enforcement.soft' | 'state.plans.more' | 'state.residual.more' | 'state.policy.push' | 'state.policy.worktree' | 'state.policy.control-worktree' | 'state.knowledge.docs' | 'freshness.last-updated' | 'freshness.refresh-note';
+export type PanelKey = 'view.mstar-workflow' | 'tab.tasks' | 'tab.agents' | 'tab.events' | 'page.iteration.not-started' | 'page.iteration.expand' | 'page.iteration.collapse' | 'event-log.section.events' | 'event-log.section.violations' | 'event-log.empty' | 'event-log.empty.events' | 'event-log.empty.violations' | 'event-log.field.role' | 'event-log.field.agent' | 'event-log.field.stage' | 'event-log.field.plan' | 'event-log.field.task' | 'event-log.field.category' | 'event-log.field.time' | 'event-log.field.kind' | 'event-log.field.status' | 'event-log.field.expected' | 'event-log.field.settled' | 'event-log.field.duration' | 'event-log.field.run-id' | 'event-log.field.name' | 'event-log.field.members' | 'event-log.field.stop-reason' | 'event-log.field.severity' | 'event-log.field.code' | 'event-log.field.message' | 'event-log.kind.dispatch' | 'event-log.kind.settle' | 'event-log.yes' | 'event-log.no' | 'empty.waiting' | 'empty.no-harness' | 'empty.no-harness-hint' | 'watermark.version' | 'watermark.harness' | 'watermark.none' | 'panel.unknown' | 'graph.pass' | 'graph.fail' | 'zone.legend.title' | 'zone.legend.agent-running' | 'zone.legend.agent-settled' | 'zone.legend.agent-idle' | 'zone.iteration.step-label' | 'zone.iteration.step-badge' | 'zone.iteration.step.current' | 'zone.iteration.step.next' | 'zone.iteration.step.done' | 'zone.iteration.step.idle' | 'zone.phase.iteration-start' | 'zone.phase.autonomous-execute' | 'zone.phase.iteration-close' | 'zone.phase.pr-delivery' | 'zone.phase.merge-ready' | 'zone.branches.title' | 'zone.branches.iteration-base' | 'zone.branches.target' | 'zone.branches.spec-integration' | 'zone.tasks.title' | 'zone.tasks.total' | 'zone.tasks.no-plans' | 'zone.tasks.more' | 'zone.tasks.collapse' | 'zone.project.title' | 'zone.project.milestones' | 'zone.project.residuals' | 'zone.project.none' | 'zone.state.Todo' | 'zone.state.InProgress' | 'zone.state.InReview' | 'zone.state.Done' | 'zone.state.blocked-unknown' | 'zone.agents.title' | 'zone.agents.summary' | 'zone.agents.on-demand' | 'zone.agents.unknown-sub' | 'zone.agents.bucket.implementor' | 'zone.agents.bucket.reviewer' | 'zone.agents.group.phase-1' | 'zone.agents.group.phase-2' | 'zone.agents.group.phase-n' | 'zone.agents.group.plan' | 'zone.agents.group.no-plan' | 'zone.agents.group.plan-more' | 'flow.empty' | 'flow.settle-only' | 'flow.degraded' | 'flow.unexpected' | 'flow.in-flight' | 'flow.settled-ok' | 'flow.error' | 'flow.advisory' | 'flow.denied' | 'state.title' | 'state.selection' | 'state.selection.history' | 'state.plans' | 'state.residuals' | 'state.policy' | 'state.leases' | 'state.knowledge' | 'state.direction' | 'state.none' | 'state.enforcement' | 'state.enforcement.hard' | 'state.enforcement.soft' | 'state.plans.more' | 'state.residual.more' | 'state.policy.push' | 'state.policy.worktree' | 'state.policy.control-worktree' | 'state.knowledge.docs' | 'freshness.last-updated' | 'freshness.refresh-note';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
         'mstar-panel': PanelKey;

package/dist/client/panel/zones/ProjectRollup.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ProjectRollup (plan `20260819-workflow-dsh-viz` Task 3 — compass v3.0.0
+ * AC-4/AC-P3): the ADDITIVE project rollup zone of the tasks page — roadmap
+ * milestones + open-residual severity counts from the project layer
+ * (`state.project`, produced by the catalog from `projects/<id>/roadmap.md`
+ * frontmatter `milestones[]` + `projects/<id>/residuals.json` registers).
+ *
+ * Additive-only contract (compass AC-4): this zone renders BELOW the kanban
+ * inside the tasks scroll body and never touches the four existing ZoneView
+ * shapes (iteration stepper / kanban / agent flow / event log) — the
+ * projection's `project` field is the only addition.
+ *
+ * Degradation (same philosophy as TaskBoard): empty `milestones` /
+ * `openResiduals` (no roadmaps / no registers / no open entries) render the
+ * muted "none" note — never an orange warn box, never a throw.
+ */
+import * as React from 'react';
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ZoneView } from '../graph/project-graph.ts';
+export interface ProjectRollupProps {
+    view: ZoneView['project'];
+    t: TranslateNS<'mstar-panel'>;
+}
+export declare function ProjectRollup({ view, t }: ProjectRollupProps): React.JSX.Element;