dsh-tower 2.4.1 → 2.5.0

package/docs/reference/tools.md

@@ -52,7 +52,7 @@ findings but not mutate them. Violations throw `[tower:not-authorized]` or
 | `tower_preflight` | `missionId` (alias `id`) | Read-only gate: returns `{ok, blockers[], branchTip, baseTip, changedFiles, review}`. |
 | `tower_merge` | `missionId` (alias `id`), `timeoutMs?` (alias `timeout_ms`) | Merge after a green gate. Records already-landed merges (`reconciled`), recovers a failed call whose commit exists (`recoveredFromFailure`), and separates `merge-hook-failed` from `merge-conflict`. |
 | `tower_rebase` | `missionId` (alias `id`) | Rebase the branch onto the base in its worktree. Refuses while the worker runs or the worktree is dirty. Already-contained branches return `alreadyMerged` untouched. |
-| `tower_teardown` | `force?`, `exclude?`, `dry_run?` (alias `dryRun`) | Remove eligible merged/abandoned worktrees and branches; running agents are always kept. The final pass applies the `archive` policy: terminal missions whose worktree is gone are moved to `<git-common-dir>/dsh-tower/archive/` once `archive.afterDays`/`archive.maxMissions` says so, and `archived` lists their ids. Nothing is deleted; `archive.afterDays:0` archives a just-torn-down mission immediately. |
+| `tower_teardown` | `force?`, `exclude?`, `dry_run?` (alias `dryRun`) | Remove eligible merged/abandoned worktrees and branches; running agents are always kept. The final pass applies the `archive` policy while the `tower-archive` component row is mounted: terminal missions whose worktree is gone are moved to `<git-common-dir>/dsh-tower/archive/` once `archive.afterDays`/`archive.maxMissions` says so, and `archived` lists their ids. Nothing is deleted; `archive.afterDays:0` archives a just-torn-down mission immediately. |
 | `tower_mode` | — | Report mode, last change, paused goal, denied tools, store path, plugin version, HMR availability, workspace-lock holder. |
 | `tower_control` | `action` (`enter`/`exit`), `reason` | Model-initiated mode change; registered by default; disable with `mode.allowAgentControl:false`; reason is mandatory. |
 | `tower_reload` | `repoRoot?` | Dev-only: ask DSH HMR to reconcile the profile and reload the Host plugin from disk. Registered while the `tower-hmr` component row is on (the row ships off); scheduled after the result (default 50 ms); fails with `reload-unavailable` without HMR. When `repoRoot` is supplied the caller must be the tower. |
@@ -77,4 +77,4 @@ Code default is off; the shipped patch is on for Kimi-compatible single-active-t
 Gate tools return `{ok:false, blockers:[{code, detail}]}`; the code list is in
 [blockers.md](blockers.md). Thrown tool errors carry a stable `[tower:<code>]` prefix
 ([errors.md](errors.md)). Successful mutations emit process-local events ([events.md](events.md)),
-and, with `docs.board:true`, refresh `<git-common-dir>/dsh-tower/MISSIONS.md`.
+and, with the `tower-board` component row mounted, refresh `<git-common-dir>/dsh-tower/MISSIONS.md`. The board location stays `docs.boardLocation`; the old `docs.board` switch is a component row now (#133).

package/docs/zh/guide/install-upgrade-migration.md

@@ -56,7 +56,7 @@ Host 插件在 DSH 启动时加载：**安装或更新后需要重启 DSH**。
   这是发布到 `next` dist-tag 的**预发布**，
   `latest` 仍指向 2.0.4——请用 `dsh plugin --profile web add dsh-tower@next`（或精确版本号）安装。
   运行时行为未变；本版本承载的是交付闸门（CI 中的 mount smoke、`npm run release:check`、证据约定
-  与追踪策略），而不是工具变化。本文档先于人工发布步骤合入：只有在[发布清单](release.md)执行
+  与追踪策略），而不是工具变化。本文档先于人工发布步骤合入：只有在[发布清单（英文）](../../guide/release.md)执行
   `npm publish --tag next` 之后，`next` 才会解析到 2.1.0-beta.1；`latest` 在稳定版发布前保持 2.0.4。
 - **2.0.3 → 2.0.4**：不需要迁移 state/config。本版本是安全加固与完整性修复（授权、merge SHA 绑定、
   dirty worktree 完成拒绝、stale lock 恢复、限制 test/git 进程环境、`tower_recover`、UI 0.2.2）。

package/docs/zh/reference/config.md

@@ -6,6 +6,11 @@
 `section` 与 `allowAgentControl` 是 `mode.promptSection` 与 `mode.allowAgentControl` 的兼容别名。
 兼容别名只用于补缺：同时设置两种写法时，规范的 `mode.*` 键优先。
 
+两个组件形态的开关已离开配置（#133/#135）：`docs.board` 现在是 `tower-board` 组件行，
+`archive.enabled` 现在是 `tower-archive` 组件行。仍设置其中任一个的配置会以 `config-unknown-key`
+失败，并附上指明替代行的升级提示；调优键（`docs.boardLocation`、`archive.afterDays`、
+`archive.maxMissions`）仍保留在这里。
+
 ## 层级与优先级
 
 从低到高：
@@ -73,7 +78,6 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 | `spawn.requireLease` | `''` | worker spawn 前必须持有的可选租约名。 |
 | `send.maxPerMinute` | `120` | 每个仓库的 `tower_send` 每分钟速率限制（0 关闭）；超出返回 `rate-limited`。 |
 | `send.interruptDefault` | `false`（随包 patch：`true`） | `tower_send.interrupt` 的默认值（投递前先中断运行中的回合）。 |
-| `tests.enabled` | `true` | worktree 的 `package.json` 配置了测试发现时运行它。它只调整可选的 `tower-tests` 组件：该行关闭时既没有 `tower_test` 工具也无法记录回执，`gates.requireTests:true` 会被拒绝而不是静默失效。 |
 | `tests.admission` | `off` | `spawn` 在启动 worker 前运行发现（fail-closed，不启动子代理）；`complete` 在 `tower_complete` 时运行；`off` 只在显式 `tower_test` 时运行（默认；不会自动执行仓库代码）。 |
 | `tests.timeoutMs` | `60000` | 每条发现命令的超时。 |
 | `tests.maxBytes` | `16777216`（16 MiB） | 每条命令捕获的 stdout 上限。 |
@@ -83,10 +87,8 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 | `gates.requireTests` | `false` | 要求针对当前 mission 分支 tip 的通过测试回执（`tests-missing`）；与审查门禁独立。`tower-tests` 组件行关闭时，规划/进入模式会带解释拒绝该组合。 |
 | `gates.allowReviewExemption` | `false` | 在 `review.requireReview:true` 时，允许用 `reviewPolicy:"none"` + 非空理由跳过审查 blocker；默认故意关闭；全局审查关闭时无影响。 |
 | `gates.maxReportBytes` | `32768`（32 KiB） | `tower_complete.report` 的 UTF-8 字节硬上限。超出时以 `invalid-argument` 拒绝并给出可执行的 `nextAction`（把全文写进 mission worktree 的文件并引用路径），绝不截断。已存在的超限报告仍可读取。 |
-| `docs.board` | `true` | 变更后写入 `MISSIONS.md`。 |
-| `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`；`repo` = `<repoRoot>/MISSIONS.md`。 |
-| `archive.enabled` | `true` | 在变更边界把 worktree 已移除的终态（`merged`/`abandoned`）任务移入 `<git-common-dir>/dsh-tower/archive/`。归档任务保留 tasks、reviews、findings 与完成报告；这是移动，不是删除。 |
-| `archive.afterDays` | `30` | 年龄触发：终态任务超过这么多天未更新，会在下次变更时归档（`0` 表示立即归档）。 |
+| `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`；`repo` = `<repoRoot>/MISSIONS.md`。是否写出看板由 `tower-board` 组件行决定（#133）；`docs.board` 已移除，会作为未知键被拒绝。 |
+| `archive.afterDays` | `30` | 年龄触发：终态任务超过这么多天未更新，会在下次变更时归档（`0` 表示立即归档）。归档本身由 `tower-archive` 组件行决定（#135）；`archive.enabled` 已移除，会作为未知键被拒绝。 |
 | `archive.maxMissions` | `100` | 数量触发：热状态中的终态任务超过此数时，从最旧的开始归档直到满足上限（`0` 表示归档所有符合条件的终态任务）。worktree 仍存在的任务永不归档。 |
 | `leases.ttlMs` | `900000` | 默认咨询式租约寿命；过期不会自动释放。 |
 | `dev.reloadDelayMs` | `50` | 计划中的 reload 延迟，先让工具结果送达。属于可选的 `tower-hmr` 组件。 |

package/docs/zh/reference/doctor.md

@@ -61,9 +61,14 @@ PID 存活并不等于写者存活：停止心跳的持有者会报告 `stale: t
 因此“被持有”是 `warn` 而不是失败；持有者的阶段与时长让卡住的控制塔可被诊断。`tower_status` 返回同一个
 `gitLock` 对象。
 
+`board` 报告 `MISSIONS.md` 位置（`docs.boardLocation`）以及 `tower-board` 组件行是否挂载。该行关闭时
+检查为 `warn`，说明看板不会被写出（已有看板会变陈旧）并指出该行名；所有状态工具与门禁仍然工作。
+
 `archive` 报告终态任务归档：活跃 `missions`、`archivedMissions` 与 `stateBytes`，归档目录的
-`archiveBytes`/`years`/`files`，每条 `unreadable` 诊断，以及配置的 `policy`（`enabled`、`afterDays`、
-`maxMissions`）。归档目录不存在是健康的空归档（`archive` 检查为 `pass`）；截断的 index/year 文件是
+`archiveBytes`/`years`/`files`，每条 `unreadable` 诊断，以及调优字段 `policy`（`afterDays`、
+`maxMissions`）。`policy.enabled` 反映 `tower-archive` 组件行，而不是配置键：该行关闭时策略行说明
+归档被组件禁用，终态任务留在热状态，`state.json` 持续增长。归档目录不存在是健康的空归档
+（`archive` 检查为 `pass`）；截断的 index/year 文件是
 `warn` 并附带诊断，且归档会暂停而不是覆盖它——归档不可读期间没有数据会丢失，符合条件的 mission 仍留在
 `state.json`。
 

package/docs/zh/reference/tools.md

@@ -74,5 +74,6 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 
 门禁类工具返回 `{ok:false, blockers:[{code, detail}]}`；code 列表见 [blockers.md](blockers.md)。
 抛出的工具错误带稳定的 `[tower:<code>]` 前缀（见 [errors.md](errors.md)）。成功的变更会发出进程内
-事件（见 [events.md](events.md)），并且在 `docs.board:true` 时刷新
-`<git-common-dir>/dsh-tower/MISSIONS.md`。
+事件（见 [events.md](events.md)），并在挂载 `tower-board` 组件行时刷新
+`<git-common-dir>/dsh-tower/MISSIONS.md`。看板位置仍由 `docs.boardLocation` 决定；原先的
+`docs.board` 开关现在是组件行（#133）。

package/domain/component-rules.js

@@ -0,0 +1,216 @@
+// Component-surface rules split out of `domain/components.js` (#138) so the
+// policy module stays under the architecture aggregate-size brake (800 lines).
+// These are pure checks over the parsed source of truth: a key's class must
+// match its value shape, and a row may only override config its component owns.
+// `domain/components.js` re-exports them for the gate and the tests.
+
+// A row's `config:` mapping mixes Tower's config with the row package's own
+// metadata (`id`, `name`, `description`, `order`) and its nested `plugins:` list.
+// Only the Tower config leaves are overrides of the component surface.
+const ROW_CONFIG_METADATA = new Set(['id', 'name', 'description', 'order'])
+
+function scalarText(value) {
+  const trimmed = String(value ?? '').trim()
+  const quoted = /^(['"])(.*)\1$/.exec(trimmed)
+  return quoted ? quoted[2] : trimmed
+}
+
+/**
+ * Read the scalar overrides under a row's own top-level `config:` mapping.
+ *
+ * The group rows are skipped by the parser: their `config:` is the list of
+ * nested component rows, so the overrides belong to the child row, not the group.
+ * A `plugins:` list is skipped for the same reason. This is what keeps a
+ * legitimate plugin config (`write: false`, `sampleOverCapGlobResults: false`)
+ * from being mistaken for a Tower config key, while a removed switch
+ * (`docs.board: false`) is captured as `docs.board` and refused.
+ *
+ * @param {string[]} lines
+ * @param {{ indent: number, line: number }} row
+ * @returns {Array<{ key: string, value: string }>}
+ */
+export function collectConfigOverrides(lines, row) {
+  let configIndent = null
+  let start = null
+  for (let index = row.line + 1; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (!line.trim() || /^\s*#/.test(line)) continue
+    const indent = /^(\s*)/.exec(line)?.[1].length ?? 0
+    const nextId = /^\s*-\s+id:/.exec(line)
+    if (nextId && indent <= row.indent) break
+    if (indent <= row.indent && !/^\s*-\s+/.test(line)) break
+    if (/^\s*config:\s*$/.test(line)) {
+      configIndent = indent
+      start = index + 1
+      break
+    }
+  }
+  if (start === null || configIndent === null) return []
+  /** @type {Array<{ indent: number, key: string }>} */
+  const stack = []
+  const overrides = []
+  let skipIndent = null
+  for (let index = start; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (!line.trim() || /^\s*#/.test(line)) continue
+    const indent = /^(\s*)/.exec(line)?.[1].length ?? 0
+    if (indent <= configIndent) break
+    if (skipIndent !== null) {
+      if (indent > skipIndent) continue
+      skipIndent = null
+    }
+    if (/^\s*-\s+/.test(line)) {
+      // A list item: the group config list or a `plugins:` entry. Skip its whole
+      // subtree; it does not belong to this row's config.
+      skipIndent = indent
+      continue
+    }
+    const match = /^\s*([A-Za-z0-9_.-]+):\s*(.*)$/.exec(line)
+    if (!match) continue
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop()
+    const key = match[1]
+    const value = match[2].trim()
+    if (value === '') {
+      if (key === 'plugins') {
+        skipIndent = indent
+        continue
+      }
+      stack.push({ indent, key })
+      continue
+    }
+    const parts = [...stack.map((entry) => entry.key), key]
+    if (ROW_CONFIG_METADATA.has(parts[0]) || parts[0] === 'plugins') continue
+    overrides.push({ key: parts.join('.'), value: scalarText(value) })
+  }
+  return overrides
+}
+
+/**
+ * #138.1: the class is not free text. A boolean key that removes a capability
+ * cannot file as `optional-config`; it must be `core`, `optional-component` or
+ * `forbidden-to-disable`, or carry a dated tuning-only exemption. The same rule
+ * covers the non-boolean behaviour knobs recorded in `behaviorKnobs`, so a
+ * string/union switch cannot hide on the tuning axis.
+ *
+ * @param {{ keys: Array<{ name: string, class: string, exemption?: any }>, behaviorKnobs?: string[] }} surface
+ * @param {{ keyTypes?: Record<string, string> }} live live schema key -> type
+ * @returns {Array<{ code: string, level: string, message: string }>}
+ */
+export function checkKeyClassifications(surface, live = {}) {
+  const findings = []
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+  const declared = new Map(surface.keys.map((key) => [key.name, key]))
+  const types = live.keyTypes ?? {}
+  const behavior = new Set(surface.behaviorKnobs ?? [])
+  const reviewedClasses = ['core', 'optional-component', 'forbidden-to-disable']
+  for (const name of behavior) {
+    if (!declared.has(name)) {
+      record('behavior-knob-unknown', `behaviorKnobs records ${name}, which has no component-axis class`)
+    }
+    if (types[name] === undefined) {
+      record('behavior-knob-unknown', `behaviorKnobs records ${name}, which is not a live config key`)
+    }
+  }
+  for (const key of surface.keys) {
+    const type = types[key.name]
+    const isBoolean = type === 'boolean'
+    const isBehavior = behavior.has(key.name)
+    if (isBoolean || isBehavior) {
+      if (key.class === 'optional-config') {
+        if (!key.exemption) {
+          record(
+            'boolean-class',
+            `${key.name} is a ${isBoolean ? 'boolean' : 'recorded behaviour knob'} classified optional-config; it needs core/optional-component/forbidden-to-disable or a dated tuning-only exemption`,
+          )
+        } else if (!/tuning|tune/i.test(key.exemption.reason)) {
+          record(
+            'boolean-exemption',
+            `${key.name} keeps optional-config but its exemption reason does not name a tuning-only nature: ${key.exemption.reason}`,
+          )
+        }
+      } else if (!reviewedClasses.includes(key.class)) {
+        record('boolean-class', `${key.name} is a ${isBoolean ? 'boolean' : 'behaviour knob'} with unknown class "${key.class}"`)
+      }
+    }
+    if (key.exemption) {
+      if (!isBoolean && !isBehavior) {
+        record('exemption-invalid', `${key.name} carries a tuning exemption but is neither a boolean nor a recorded behaviour knob`)
+      }
+      if (key.class !== 'optional-config') {
+        record('exemption-invalid', `${key.name} carries a tuning exemption but is classified "${key.class}", not optional-config`)
+      }
+      if (!/tuning|tune/i.test(key.exemption.reason)) {
+        record('exemption-invalid', `${key.name} exemption reason must name its tuning-only nature: ${key.exemption.reason}`)
+      }
+    }
+  }
+  return findings
+}
+
+/**
+ * #138.4: a row may only override config it owns. The parser captures the scalar
+ * leaves under the row's own `config:` mapping; each one must be a live config
+ * key (so a removed switch such as `docs.board:false` fails) and must be listed
+ * in that component's `allowedOverrides` (so a row cannot enable or disable a
+ * capability it does not own). `allowedOverrides` itself is checked in the other
+ * direction: every listed key must be live and must not be forbidden-to-disable.
+ *
+ * @param {{ keys: Array<{ name: string, class: string }>, components: Array<{ id: string, allowedOverrides?: string[] }> }} surface
+ * @param {{ configKeys?: string[], patch?: { rows?: Array<{ id: string, configOverrides?: Array<{ key: string, value: string }> }> } }} live
+ * @returns {Array<{ code: string, level: string, message: string }>}
+ */
+export function checkRowOverrides(surface, live = {}) {
+  const findings = []
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+  const rows = live.patch?.rows ?? []
+  const liveKeys = new Set(live.configKeys ?? [])
+  const keyClass = new Map(surface.keys.map((key) => [key.name, key.class]))
+  const classified = new Map(surface.components.map((component) => [component.id, component]))
+  for (const component of surface.components) {
+    const allowed = component.allowedOverrides ?? []
+    const seen = new Set()
+    for (const key of allowed) {
+      if (seen.has(key)) record('row-override-duplicate', `component "${component.id}" lists ${key} twice in allowedOverrides`)
+      seen.add(key)
+      if (!liveKeys.has(key)) {
+        record('component-override-unknown', `component "${component.id}" allows ${key}, which is not a live config key`)
+      }
+      if (keyClass.get(key) === 'forbidden-to-disable') {
+        record('row-override-forbidden', `component "${component.id}" allows ${key}, which is classified forbidden-to-disable`)
+      }
+    }
+  }
+  for (const row of rows) {
+    const component = classified.get(row.id)
+    if (!component) continue
+    const allowed = new Set(component.allowedOverrides ?? [])
+    for (const entry of row.configOverrides ?? []) {
+      const key = entry?.key
+      if (typeof key !== 'string' || !key) {
+        record('row-override-invalid', `row "${row.id}" has an override without a config key`)
+        continue
+      }
+      if (!liveKeys.has(key)) {
+        record(
+          'row-override-unknown',
+          `row "${row.id}" sets ${key}:${entry.value}; it is not a live config key (a switch removed in favour of a component must not keep working from a row config)`,
+        )
+        continue
+      }
+      if (keyClass.get(key) === 'forbidden-to-disable') {
+        record(
+          'row-override-forbidden',
+          `row "${row.id}" sets ${key}:${entry.value}; a component may not switch off a forbidden-to-disable key`,
+        )
+        continue
+      }
+      if (!allowed.has(key)) {
+        record(
+          'row-override-foreign',
+          `row "${row.id}" sets ${key}:${entry.value}; that key is outside the overrides allowed for component "${component.id}"`,
+        )
+      }
+    }
+  }
+  return findings
+}