dsh-tower 2.1.0 → 2.4.0

package/locale/zh.json

@@ -4,25 +4,45 @@
     "description": "多代理任务规划、隔离工作树与审查门禁合并。"
   },
   "components": {
-    "tower-bundle": {
+    "tower": {
       "title": "Tower 控制塔",
-      "summary": "任务规划、隔离工作树、执行/审查代理与合并门禁。",
-      "disables": "关闭后整个 Tower 一起停用；不会留下孤立的代理预设或技能。"
+      "summary": "任务规划、隔离工作树、模式守卫、健康契约与恢复逃生口。",
+      "disables": "关闭强制主组件等同于卸载 Tower：不再保留任何工具、preset 或技能。"
     },
     "tower-skills": {
       "title": "Tower 技能包",
       "summary": "执行与审查代理的操作手册，以及失败后的恢复指南。",
-      "disables": "内部 section；随 Tower 整体启停。"
+      "disables": "三个 Tower 技能从目录中移除；执行/审查协议段落与所有 mission 工具继续工作。"
     },
-    "preset-tower-worker": {
-      "title": "Tower 执行代理",
-      "summary": "在独立分支里写代码、跑验证并提交，只改分给它的文件。",
-      "disables": "内部 section；缺失时会在规划/进入模式前被拒绝。"
+    "tower-batch": {
+      "title": "证据批次",
+      "summary": "把 mission 归入有限证据批次，并按必需检查与回执关闭批次。",
+      "disables": "不再注册 tower_batch；mission、门禁与合并不受影响。"
+    },
+    "tower-import": {
+      "title": "旧版导入",
+      "summary": "导入 Tower Codex 旧状态文件，并审计快照到 mission 的映射。",
+      "disables": "不再注册 tower_import_legacy 与 tower_legacy_map；新状态不受影响。"
+    },
+    "tower-leases": {
+      "title": "咨询式租约",
+      "summary": "用咨询式资源租约协调每个仓库中的重型工作。",
+      "disables": "不再注册 tower_resource；其他能力不依赖租约。"
+    },
+    "tower-tests": {
+      "title": "测试发现",
+      "summary": "运行 worktree 声明的测试发现，并为 mission tip 记录回执。",
+      "disables": "不再注册 tower_test，也无法记录回执；若 gates.requireTests:true，规划/进入模式会以解释性错误拒绝。"
+    },
+    "tower-hmr": {
+      "title": "开发热重载",
+      "summary": "为联动开发 profile 注册 tower_reload 与 /tower reload。",
+      "disables": "tower_reload 与 /tower reload 不可用；非 HMR profile 的行为与之前完全相同。随包默认关闭。"
     },
     "preset-tower-reviewer": {
       "title": "Tower 审查代理",
-      "summary": "只读检查改动是否越界、是否达标，给出通过或问题清单。",
-      "disables": "内部 section；缺失且强制审查时会在规划/进入模式前被拒绝。"
+      "summary": "只读独立审查：检查 mission diff、核对范围与验收，给出结论。",
+      "disables": "无法派发审查代理。review.requireReview 为 false 时允许关闭；强制审查开启时规划/进入模式会被锁定并给出解释。"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "2.1.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -31,6 +31,11 @@
     "./worker": "./worker.js",
     "./reviewer": "./reviewer.js",
     "./skills": "./skills.js",
+    "./batch": "./host/capability-batch.js",
+    "./import": "./host/capability-import.js",
+    "./leases": "./host/capability-leases.js",
+    "./tests": "./host/capability-tests.js",
+    "./hmr": "./host/capability-hmr.js",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg",
     "./package.json": "./package.json"
@@ -41,7 +46,7 @@
     "reviewer.js",
     "skills.js",
     "skills/",
-    "lib/*.js",
+    "host/*.js",
     "domain/**/*.js",
     "app/*.js",
     "tools/*.js",
@@ -58,6 +63,7 @@
     "LICENSE",
     "CONTRIBUTING.md",
     "SECURITY.md",
+    "PRINCIPLES.md",
     "docs/",
     "ui-bundle/",
     "ports/*.js"
@@ -71,22 +77,36 @@
     "test": "node --test tests/*.test.mjs",
     "test:watch": "node --test --watch tests/*.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage tests/*.test.mjs",
+    "test:live": "node tests/live/run.cjs",
     "smoke:mount": "node scripts/mount-smoke.mjs",
     "smoke:fixtures": "node scripts/mount-smoke/fixtures.mjs",
     "release:check": "node scripts/release-check.mjs",
     "audit:issues": "node scripts/issue-audit.mjs",
+    "audit:regressions": "node scripts/regression-audit.mjs",
+    "surface:check": "node scripts/surface-baseline.mjs",
     "dev:hmr": "node scripts/enable-dev-hmr.mjs",
     "docs:check": "node scripts/check-docs.mjs",
+    "docs:check:philosophy": "node scripts/check-philosophy.mjs",
     "docs:generate:errors": "node scripts/generate-error-reference.mjs",
     "docs:check:generated": "node scripts/generate-error-reference.mjs --check",
     "docs:generate:tools": "node scripts/generate-tools-reference.mjs",
     "docs:check:generated:tools": "node scripts/generate-tools-reference.mjs --check",
     "docs:generate:config": "node scripts/generate-config-reference.mjs",
     "docs:check:generated:config": "node scripts/generate-config-reference.mjs --check",
+    "docs:generate:events": "node scripts/generate-events-reference.mjs",
+    "docs:check:generated:events": "node scripts/generate-events-reference.mjs --check",
+    "types:generate": "node scripts/generate-types.mjs",
+    "docs:check:generated:types": "node scripts/generate-types.mjs --check",
+    "docs:generate:components": "node scripts/generate-component-surface.mjs",
+    "docs:check:generated:components": "node scripts/generate-component-surface.mjs --check",
+    "docs:check:components": "node scripts/check-components.mjs",
     "pack:check": "node scripts/check-pack.mjs",
     "architecture:check": "node scripts/architecture.mjs",
-    "types:check": "tsc --noEmit",
-    "check": "npm test && npm run docs:check && npm run pack:check && npm run architecture:check && npm run types:check && npm run domain:check",
+    "types:check": "tsc --noEmit && tsc -p tsconfig.strict.json",
+    "types:coverage": "node scripts/types-coverage.mjs",
+    "types:strict:check": "node scripts/types-strict.mjs",
+    "types:strict:write": "node scripts/types-strict.mjs --write",
+    "check": "npm test && npm run docs:check && npm run docs:check:philosophy && npm run docs:check:generated && npm run docs:check:generated:tools && npm run docs:check:generated:config && npm run docs:check:generated:events && npm run docs:check:generated:types && npm run docs:check:generated:components && npm run docs:check:components && npm run surface:check && npm run pack:check && npm run architecture:check && npm run types:coverage && npm run types:strict:check && npm run types:check && npm run domain:check",
     "domain:metrics": "node scripts/domain-metrics.mjs",
     "domain:check": "node scripts/domain-metrics.mjs --check"
   },

package/ports/archive.js

@@ -0,0 +1,18 @@
+// Terminal-mission archive port (#69). The readers/writers are store-agnostic:
+// they take the store port and the Tower paths, so the same archive logic runs
+// on the filesystem adapter and on an in-memory store.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} ArchivePort
+ * @property {(store: unknown, paths: { dir: string }) => Promise<{ ok: boolean, file: string, missions: any[], error?: string, exists: boolean }>} readIndex
+ * @property {(store: unknown, paths: { dir: string }, missionId: string) => Promise<any>} readEntry
+ * @property {(store: unknown, paths: { dir: string }, input: { entries: any[], now?: number }) => Promise<any>} writeEntries
+ */
+
+export const ARCHIVE_PORT = definePort('ArchivePort', ['readIndex', 'readEntry', 'writeEntries'])
+
+/** @param {unknown} impl */
+export function assertArchivePort(impl) {
+  return /** @type {ArchivePort} */ (assertPort(impl, ARCHIVE_PORT, 'archive'))
+}

package/ports/caseSensitivity.js

@@ -0,0 +1,15 @@
+// Case-sensitivity probe port (#69). tower_init probes the checkout filesystem
+// once; a composition without a real filesystem injects its own answer.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} CaseSensitivityPort
+ * @property {(root: string) => Promise<boolean | null>} detect
+ */
+
+export const CASE_SENSITIVITY_PORT = definePort('CaseSensitivityPort', ['detect'])
+
+/** @param {unknown} impl */
+export function assertCaseSensitivityPort(impl) {
+  return /** @type {CaseSensitivityPort} */ (assertPort(impl, CASE_SENSITIVITY_PORT, 'caseSensitivity'))
+}

package/ports/clock.js

@@ -1,6 +1,14 @@
-// Clock port (#56).
+// Clock port (#69).
+import { assertPort, definePort } from './contract.js'
+
 /**
  * @typedef {object} ClockPort
  * @property {() => number} now
  */
-export {}
+
+export const CLOCK_PORT = definePort('ClockPort', ['now'])
+
+/** @param {unknown} impl */
+export function assertClockPort(impl) {
+  return /** @type {ClockPort} */ (assertPort(impl, CLOCK_PORT, 'clock'))
+}

package/ports/config.js

@@ -0,0 +1,19 @@
+// Config port (#69).
+//
+// App use cases read the effective Tower config through this port. They do not
+// import host/config.js, so the process-level config store stays a property of
+// the composition root rather than a module-global dependency of the app.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} ConfigPort
+ * @property {() => import('../types/index.js').TowerConfig} runtimeConfig
+ * @property {(repo: { root: string, commonDir: string, branch?: string|null }) => Promise<import('../types/index.js').TowerConfig>} resolveRepoConfig
+ */
+
+export const CONFIG_PORT = definePort('ConfigPort', ['runtimeConfig', 'resolveRepoConfig'])
+
+/** @param {unknown} impl */
+export function assertConfigPort(impl) {
+  return /** @type {ConfigPort} */ (assertPort(impl, CONFIG_PORT, 'config'))
+}

package/ports/contract.js

@@ -0,0 +1,38 @@
+// Port contract primitives (#69).
+//
+// A port is a runtime-checkable contract, not only a JSDoc typedef: the
+// contract object is importable, and `assertPort` rejects a dependency object
+// that does not implement it. That is what makes the seam substitutable at
+// runtime instead of merely documented.
+export function definePort(name, methods) {
+  return Object.freeze({ name, methods: Object.freeze([...methods]) })
+}
+
+/**
+ * @param {unknown} impl
+ * @param {{ name: string, methods: readonly string[] }} contract
+ * @param {string} [label]
+ */
+export function assertPort(impl, contract, label = contract.name) {
+  if (!impl || typeof impl !== 'object') {
+    throw new TypeError(`${label}: expected an object implementing ${contract.name}`)
+  }
+  const missing = contract.methods.filter((method) => typeof (/** @type {any} */ (impl))[method] !== 'function')
+  if (missing.length > 0) {
+    throw new TypeError(`${label} does not implement ${contract.name}; missing: ${missing.join(', ')}`)
+  }
+  return impl
+}
+
+/**
+ * @param {unknown} impl
+ * @param {{ name: string, methods: readonly string[] }} contract
+ */
+export function implementsPort(impl, contract) {
+  try {
+    assertPort(impl, contract)
+    return true
+  } catch {
+    return false
+  }
+}

package/ports/events.js

@@ -0,0 +1,24 @@
+// Domain-event port (#75).
+//
+// The app layer persists a transition and then emits the domain events it
+// described through this port. The host binds it to Cordis `ctx.emit`; tests
+// bind it to a recorder. `emit` is best effort by contract: a listener (or a
+// missing service) must never fail the tool that produced the fact.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} EventPort
+ * @property {(name: string, payload: Record<string, any>) => void} emit
+ */
+
+export const EVENT_PORT = definePort('EventPort', ['emit'])
+
+/** @param {unknown} impl */
+export function assertEventPort(impl) {
+  return /** @type {EventPort} */ (assertPort(impl, EVENT_PORT, 'events'))
+}
+
+/** The no-op default: embedders without an event channel still get a Tower. */
+export const NOOP_EVENT_PORT = Object.freeze({
+  emit() {},
+})

package/ports/ids.js

@@ -1,7 +1,15 @@
-// Ids port (#56).
+// Ids port (#69).
+import { assertPort, definePort } from './contract.js'
+
 /**
  * @typedef {object} IdsPort
  * @property {() => string} uuid
  * @property {(text: string) => string} shortHash
  */
-export {}
+
+export const IDS_PORT = definePort('IdsPort', ['uuid', 'shortHash'])
+
+/** @param {unknown} impl */
+export function assertIdsPort(impl) {
+  return /** @type {IdsPort} */ (assertPort(impl, IDS_PORT, 'ids'))
+}

package/ports/index.js

@@ -1,2 +1,54 @@
-// Explicit ports consumed by app use cases (#56).
-export {}
+// Explicit ports consumed by app use cases (#69).
+//
+// `assertPorts` is the injection check the app layer runs on the dependency
+// object it receives: a composition root that forgets a port fails at
+// construction, not in the middle of a mission.
+import { assertPort } from './contract.js'
+import { STORE_PORT, assertStorePort } from './store.js'
+import { VCS_PORT, assertVcsPort } from './vcs.js'
+import { CLOCK_PORT, assertClockPort } from './clock.js'
+import { IDS_PORT, assertIdsPort } from './ids.js'
+import { CONFIG_PORT, assertConfigPort } from './config.js'
+import { STATE_PORT, assertStatePort } from './state.js'
+import { OWNERSHIP_PORT, assertOwnershipPort } from './ownership.js'
+import { CASE_SENSITIVITY_PORT, assertCaseSensitivityPort } from './caseSensitivity.js'
+import { ARCHIVE_PORT, assertArchivePort } from './archive.js'
+import { EVENT_PORT, assertEventPort } from './events.js'
+
+/** Every port the Tower app layer depends on, keyed by deps member. */
+export const PORTS = Object.freeze({
+  store: { contract: STORE_PORT, assert: assertStorePort },
+  vcs: { contract: VCS_PORT, assert: assertVcsPort },
+  clock: { contract: CLOCK_PORT, assert: assertClockPort },
+  ids: { contract: IDS_PORT, assert: assertIdsPort },
+  config: { contract: CONFIG_PORT, assert: assertConfigPort },
+  state: { contract: STATE_PORT, assert: assertStatePort },
+  ownership: { contract: OWNERSHIP_PORT, assert: assertOwnershipPort },
+  caseSensitivity: { contract: CASE_SENSITIVITY_PORT, assert: assertCaseSensitivityPort },
+  archive: { contract: ARCHIVE_PORT, assert: assertArchivePort },
+  events: { contract: EVENT_PORT, assert: assertEventPort },
+})
+
+/** @param {unknown} deps */
+export function assertPorts(deps) {
+  if (!deps || typeof deps !== 'object') {
+    throw new TypeError('Tower requires an injected deps object assembled by the composition root (see adapters/default.js)')
+  }
+  for (const [name, port] of Object.entries(PORTS)) {
+    if (typeof port.assert === 'function') port.assert(deps[name])
+    else assertPort(deps[name], port.contract, name)
+  }
+  return deps
+}
+
+export { STORE_PORT, assertStorePort } from './store.js'
+export { VCS_PORT, assertVcsPort } from './vcs.js'
+export { CLOCK_PORT, assertClockPort } from './clock.js'
+export { IDS_PORT, assertIdsPort } from './ids.js'
+export { CONFIG_PORT, assertConfigPort } from './config.js'
+export { STATE_PORT, assertStatePort } from './state.js'
+export { OWNERSHIP_PORT, assertOwnershipPort } from './ownership.js'
+export { CASE_SENSITIVITY_PORT, assertCaseSensitivityPort } from './caseSensitivity.js'
+export { ARCHIVE_PORT, assertArchivePort } from './archive.js'
+export { EVENT_PORT, assertEventPort, NOOP_EVENT_PORT } from './events.js'
+export { definePort, assertPort, implementsPort } from './contract.js'

package/ports/ownership.js

@@ -0,0 +1,17 @@
+// Worktree-ownership port (#69). The default implementation verifies a stored
+// worktree against the real filesystem and Git; an in-memory composition can
+// substitute a verifier that matches its own virtual paths.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} OwnershipPort
+ * @property {(input: { storedPath: string, storedRealPath?: string, branch: string, commonDir: string, missionId?: string }) => Promise<{ path: string, realPath: string }>} assertOwnership
+ * @property {(target: string) => Promise<string>} canonicalPath
+ */
+
+export const OWNERSHIP_PORT = definePort('OwnershipPort', ['assertOwnership', 'canonicalPath'])
+
+/** @param {unknown} impl */
+export function assertOwnershipPort(impl) {
+  return /** @type {OwnershipPort} */ (assertPort(impl, OWNERSHIP_PORT, 'ownership'))
+}

package/ports/state.js

@@ -0,0 +1,16 @@
+// State-load port (#69): schema inspection, migration, and the one persisted
+// migration result. The implementation is store-agnostic and receives the
+// store port, so an in-memory store can drive the same load path.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} StatePort
+ * @property {(input: { store: unknown, paths: unknown, now?: number, persist?: boolean, migrations?: readonly unknown[] }) => Promise<any>} loadStateFile
+ */
+
+export const STATE_PORT = definePort('StatePort', ['loadStateFile'])
+
+/** @param {unknown} impl */
+export function assertStatePort(impl) {
+  return /** @type {StatePort} */ (assertPort(impl, STATE_PORT, 'state'))
+}

package/ports/store.js

@@ -1,11 +1,60 @@
-// Store port (#56). Implementation: adapters/store-fs.js.
+// Store port (#69). Implementation: adapters/store-fs.js.
+//
+// App use cases depend on this contract, not on adapters/store.js: they receive the
+// implementation through the composition root and never import the adapter.
+// The contract lists every method app/** and tools/** call, so an implementation
+// that is missing one fails `assertPorts` at construction instead of mid-mission.
+import { assertPort, definePort } from './contract.js'
+
 /**
  * @typedef {object} StorePort
+ * @property {(commonDir: string) => { dir: string, state: string, lock: string, gitLock: string, activity: string }} pathsFor
  * @property {(file: string) => Promise<boolean>} exists
  * @property {(dir: string) => Promise<void>} ensureDir
  * @property {(file: string) => Promise<any>} readJson
  * @property {(file: string, value: unknown) => Promise<void>} writeJsonAtomic
  * @property {(file: string, value: unknown) => Promise<void>} appendJsonl
- * @property {(paths: object, fn: () => Promise<any>, options?: object) => Promise<any>} withLock
+ * @property {(paths: object, fn: (paths: object) => Promise<any>, options?: object) => Promise<any>} withLock
+ * @property {(paths: object, fn: (paths: object) => Promise<any>, options?: object) => Promise<any>} withGitLock
+ * @property {(file: string, limit?: number) => Promise<any[]>} readActivityTail
+ * @property {(file: string) => Promise<string>} readText
+ * @property {(file: string, text: string, encoding?: string) => Promise<void>} writeText
+ * @property {(file: string, text: string, encoding?: string) => Promise<void>} appendText
+ * @property {(from: string, to: string) => Promise<void>} rename
+ * @property {(from: string, to: string) => Promise<void>} renameWithRetry
+ * @property {(file: string) => Promise<{ mtimeMs: number }>} stat
+ * @property {(file: string) => Promise<void>} unlink
+ * @property {(paths: object, options?: object) => Promise<{ record: any, raw: string | null }>} readGitLock
+ * @property {(lock: { record: any } | null, options?: object) => { held: boolean, pid?: number | null, phase?: string | null, heldMs?: number }} gitLockView
  */
-export {}
+
+// `rename` and `renameWithRetry` are both declared because they are not
+// interchangeable: `renameWithRetry` has temp-file semantics and on a terminal
+// failure it unlinks its source, which is right for a disposable temp file but
+// would delete the bytes `tower_recover` must keep auditable. The audit rename
+// therefore uses the plain `rename` primitive (see tools/recover.js).
+export const STORE_PORT = definePort('StorePort', [
+  'pathsFor',
+  'exists',
+  'ensureDir',
+  'readJson',
+  'writeJsonAtomic',
+  'appendJsonl',
+  'withLock',
+  'withGitLock',
+  'readActivityTail',
+  'readText',
+  'writeText',
+  'appendText',
+  'rename',
+  'renameWithRetry',
+  'stat',
+  'unlink',
+  'readGitLock',
+  'gitLockView',
+])
+
+/** @param {unknown} impl */
+export function assertStorePort(impl) {
+  return /** @type {StorePort} */ (assertPort(impl, STORE_PORT, 'store'))
+}

package/ports/vcs.js

@@ -1,11 +1,32 @@
-// Vcs port (#56). Implementation: adapters/vcs-git.js.
+// Vcs port (#69). Implementation: adapters/vcs-git.js.
+import { assertPort, definePort } from './contract.js'
+
 /**
  * @typedef {object} VcsPort
  * @property {(cwd: string, args: string[], options?: object) => Promise<string>} git
  * @property {(cwd: string, args: string[], options?: object) => Promise<string|null>} tryGit
  * @property {(cwd: string, ref: string) => Promise<string>} revParse
  * @property {(cwd: string) => Promise<boolean>} isClean
- * @property {(cwd: string, a: string, b: string) => Promise<boolean>} isAncestor
- * @property {(repoRoot: string) => Promise<{root:string, commonDir:string, branch:string|null}>} resolveRepo
+ * @property {(cwd: string, ancestor: string, descendant: string) => Promise<boolean>} isAncestor
+ * @property {(repoRoot: string) => Promise<{ root: string, commonDir: string, branch: string|null }>} resolveRepo
+ * @property {(cwd: string) => Promise<string|null>} currentBranch
+ * @property {(cwd: string, fromRef: string) => Promise<number>} countCommits
+ * @property {(cwd: string) => Promise<Array<{ path: string, branch?: string, head?: string }>>} listWorktrees
  */
-export {}
+
+export const VCS_PORT = definePort('VcsPort', [
+  'git',
+  'tryGit',
+  'revParse',
+  'isClean',
+  'isAncestor',
+  'resolveRepo',
+  'currentBranch',
+  'countCommits',
+  'listWorktrees',
+])
+
+/** @param {unknown} impl */
+export function assertVcsPort(impl) {
+  return /** @type {VcsPort} */ (assertPort(impl, VCS_PORT, 'vcs'))
+}

package/scripts/architecture-waivers.json

@@ -0,0 +1,19 @@
+{
+  "$comment": "Justified architecture-gate exemptions (#80). Every entry needs rule, path, reason, and owner or ref. Scripts/architecture.mjs fails with waiver-contract when an entry is not justified. domain-pure, host-scope and no-lib-from-core cannot be waived at all, and domain/** accepts no waiver. Since #70 the retired lib/ layer has no waivers: host/** owns ambient state by rule, and only the two I/O adapters below are exempt.",
+  "waivers": [
+    {
+      "rule": "child-process-surface",
+      "path": "adapters/vcs-git.js",
+      "reason": "The git adapter is the single process-spawning boundary; no other module implements VcsPort with a child process.",
+      "owner": "louifinn",
+      "ref": "#50"
+    },
+    {
+      "rule": "fs-surface",
+      "path": "adapters/store-fs.js",
+      "reason": "The filesystem adapter is the single node:fs boundary; the store port needs atomic writes, lock files, and raw store reads.",
+      "owner": "louifinn",
+      "ref": "#50"
+    }
+  ]
+}