dsh-tower 2.1.0 → 2.3.0

package/scripts/generate-events-reference.mjs

@@ -0,0 +1,83 @@
+// Generate docs/reference/events.md from the event table (#75) so event names
+// and payloads cannot drift from the runtime. Usage:
+//   node scripts/generate-events-reference.mjs [--check]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  EVENT_COUNT,
+  LEGACY_TOOL_EVENT_TABLE,
+  MISSION_EVENT_TABLE,
+} from '../domain/events.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const target = path.join(root, 'docs', 'reference', 'events.md')
+
+const payloadCell = (entry) => `\`{ ${entry.payload.join(', ')} }\``
+const missionRows = MISSION_EVENT_TABLE.map(
+  (entry) => `| \`${entry.name}\` | ${payloadCell(entry)} | ${entry.description} |`,
+).join('\n')
+const legacyRows = LEGACY_TOOL_EVENT_TABLE.map((entry) => `| \`${entry.name}\` | ${entry.description} |`).join('\n')
+
+const expected = `# Tower events
+
+> Generated by \`npm run docs:generate:events\` from \`domain/events.js\`. Do not edit by hand.
+
+Tower emits process-local Cordis events after successful tool calls (mutations and read-only tools), so
+other plugins can observe a repository without polling. This release defines ${EVENT_COUNT} process-local events:
+${MISSION_EVENT_TABLE.length} stable domain events and ${LEGACY_TOOL_EVENT_TABLE.length} deprecated tool-shaped
+aliases. Events are **not** sent over the network and carry no telemetry.
+
+## Domain events (stable)
+
+Domain events describe what changed, not which tool ran. They are emitted only after the state write
+succeeds, so \`revision\` is the revision a reader can load back from \`state.json\`; a failed tool emits
+no domain event. \`at\` is the transition timestamp in epoch milliseconds. \`state.json\` stays
+authoritative: these events are an observation channel, not an event-sourced log, and are never
+replayed.
+
+| Event | Payload | Emitted after |
+|---|---|---|
+${missionRows}
+
+\`\`\`js
+ctx.on('tower.mission.merged', ({ missionId, revision, at, commit }) => {
+  // the merge is already durable; commit is the merge commit that landed
+})
+\`\`\`
+
+## Tool-shaped aliases (deprecated)
+
+The older \`tower/<tool>\` events are kept for one minor release as a **deprecated** alias for the
+tool-shaped observation channel; prefer the domain events above and expect the alias to be removed in
+the next minor. They carry \`{ tool, repoRoot, value }\`, fire after a successful tool call, and never
+fail a tool when a listener throws. For \`tower_merge\` the alias also fires for a gate failure whose
+\`value.ok\` is false.
+
+| Event | Emitted after |
+|---|---|
+${legacyRows}
+
+\`\`\`js
+ctx.on('tower/merge', (payload) => {
+  // deprecated: prefer tower.mission.merged
+  // payload.tool, payload.repoRoot, payload.value (the tool's JSON result)
+})
+\`\`\`
+
+For a durable audit trail use \`<git-common-dir>/dsh-tower/activity.jsonl\` and \`MISSIONS.md\` instead;
+events are process-local and are not replayed.
+`
+
+if (process.argv.includes('--check')) {
+  const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+  if (actual !== expected) {
+    console.error('events reference is stale; run npm run docs:generate:events')
+    process.exit(1)
+  }
+  console.log(`events reference: ${EVENT_COUNT} events in sync`)
+} else {
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, expected)
+  console.log(`wrote ${path.relative(root, target)} (${EVENT_COUNT} events)`)
+}

package/scripts/generate-tools-reference.mjs

@@ -3,9 +3,12 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { registerTowerTools } from '../tools/index.js'
+import { SURFACE_BASELINE_FILE, surfaceLine } from '../domain/surface.js'
+import { readBaseline } from './lib/surface.mjs'
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const target = path.join(root, 'docs', 'reference', 'tools.generated.md')
+const baseline = readBaseline(root)
 const tools = new Map()
 const ctx = {
   get() {
@@ -33,9 +36,17 @@ registerTowerTools(ctx)
 const rows = [...tools.values()]
   .sort((a, b) => a.name.localeCompare(b.name))
   .map((tool) => `| \`${tool.name}\` | ${String(tool.description ?? '').replace(/\s+/g, ' ').trim()} |`)
+// Live tools count, baseline config counts: `npm run surface:check` keeps the
+// two halves equal, so the generated header carries one decision record.
+const counts = {
+  configKeys: baseline.surfaces.configKeys.value,
+  sections: baseline.surfaces.sections.value,
+  tools: tools.size,
+}
 const expected = `# Tools overview (generated)
 
 > Generated by \`npm run docs:generate:tools\` from the registered tool definitions. Do not edit by hand.
+> Surface: ${surfaceLine(counts)} · baseline ${baseline.date}. Generated from \`${SURFACE_BASELINE_FILE}\`; do not edit by hand.
 
 | Tool | Description |
 |---|---|

package/scripts/issue-audit.mjs

@@ -87,7 +87,7 @@ export function selectEvidence(issue) {
   return null
 }
 
-function labelsOf(issue) {
+export function labelsOf(issue) {
   const labels = Array.isArray(issue.labels) ? issue.labels : []
   return labels.map((label) => (typeof label === 'string' ? label : label?.name ?? '')).filter(Boolean)
 }
@@ -116,7 +116,7 @@ function closedAtOf(issue) {
 
 // A pointer must stay inside the repository and name a real test file: an
 // existing script or doc is not evidence of a regression test.
-function inspectPointer(pointer, root) {
+export function inspectPointer(pointer, root) {
   const normalized = String(pointer).replace(/\\/g, '/').trim()
   if (!normalized) return { code: 'invalid-pointer', detail: 'empty' }
   if (path.isAbsolute(normalized) || /^[A-Za-z]:\//.test(normalized) || normalized.startsWith('/')) {

package/scripts/lib/surface.mjs

@@ -0,0 +1,87 @@
+// File-reading wrapper around the pure concept-budget surface (#84).
+//
+// `domain/surface.js` owns the rules; this module owns the two files they read
+// (`scripts/surface-baseline.json` and `docs/reference/surface-budget.md`) and
+// the combined check used by the CLI gate and the tests.
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  SURFACE_BASELINE_FILE,
+  SURFACE_CLASSIFICATION_FILE,
+  parseBaseline,
+  validateBaseline,
+  validateClassification,
+} from '../../domain/surface.js'
+
+/**
+ * @param {string} root repository root
+ * @returns {ReturnType<typeof parseBaseline>}
+ */
+export function readBaseline(root) {
+  const file = path.join(root, SURFACE_BASELINE_FILE)
+  return parseBaseline(fs.readFileSync(file, 'utf8'))
+}
+
+/**
+ * @param {string} root repository root
+ */
+export function readClassification(root) {
+  return fs.readFileSync(path.join(root, SURFACE_CLASSIFICATION_FILE), 'utf8')
+}
+
+/**
+ * Run both halves of the concept-budget gate against one repository root.
+ * `current` carries the live counts and the live key/tool names.
+ *
+ * @param {{ root: string, current: { configKeys: number, sections: number, tools: number, liveNames: { configKeys: string[], sections: string[], tools: string[] } } }} options
+ */
+export function checkSurfaceBudget({ root, current }) {
+  let baseline
+  try {
+    baseline = readBaseline(root)
+  } catch (error) {
+    return {
+      ok: false,
+      baseline: null,
+      classification: null,
+      findings: [
+        {
+          code: 'baseline-unreadable',
+          level: 'error',
+          message: `${SURFACE_BASELINE_FILE} is unreadable: ${String(error?.message ?? error)}`,
+        },
+      ],
+    }
+  }
+  const findings = validateBaseline(baseline, current, {
+    exists: (relative) => fs.existsSync(path.join(root, relative)),
+  })
+  let classificationText
+  try {
+    classificationText = readClassification(root)
+  } catch (error) {
+    return {
+      ok: false,
+      baseline,
+      classification: null,
+      findings: [
+        ...findings,
+        {
+          code: 'classification-unreadable',
+          level: 'error',
+          message: `${SURFACE_CLASSIFICATION_FILE} is unreadable: ${String(error?.message ?? error)}`,
+        },
+      ],
+    }
+  }
+  const classification = validateClassification(classificationText, current.liveNames, {
+    baselineDate: baseline.date,
+  })
+  const all = [...findings, ...classification.findings]
+  return {
+    ok: all.length === 0,
+    baseline,
+    classification,
+    findings: all,
+  }
+}

package/scripts/pack-manifest.txt

@@ -2,15 +2,28 @@ CHANGELOG.md
 COMPATIBILITY.md
 CONTRIBUTING.md
 LICENSE
+PRINCIPLES.md
 README.en.md
 README.md
 SECURITY.md
+adapters/archive.js
+adapters/caseSensitivity.js
 adapters/default.js
+adapters/git.js
+adapters/leases.js
+adapters/legacy.js
+adapters/persistence.js
+adapters/stateFile.js
 adapters/store-fs.js
+adapters/store.js
+adapters/tests.js
 adapters/vcs-git.js
+adapters/workspaceLock.js
+adapters/worktreeOwnership.js
 app/archive.js
 app/batch.js
 app/board.js
+app/briefing.js
 app/checkCompletion.js
 app/enrichedMissions.js
 app/findings.js
@@ -27,14 +40,22 @@ app/rebase.js
 app/recording.js
 app/review.js
 app/roster.js
+app/spawn-prechecks.js
+app/spawn-support.js
 app/spawn.js
 app/teardown.js
 app/tower.js
 cordis.patch.yml
 docs/README.md
+docs/adr/0001-ports-adapters-as-data.md
+docs/adr/0002-single-state-json.md
+docs/adr/0003-allow-agent-control-default-true.md
+docs/adr/0004-surface-budget.md
+docs/adr/README.md
 docs/agents/domain.md
 docs/agents/issue-tracker.md
 docs/agents/triage-labels.md
+docs/agents/workflow.md
 docs/architecture/overview.md
 docs/board.md
 docs/examples/first-mission.md
@@ -44,6 +65,7 @@ docs/guide/install-upgrade-migration.md
 docs/guide/quickstart.md
 docs/guide/release.md
 docs/guide/scenarios-and-philosophy.md
+docs/operations/incident.md
 docs/operations/runbook.md
 docs/operations/security.md
 docs/reference/blockers.md
@@ -54,6 +76,7 @@ docs/reference/errors.generated.md
 docs/reference/errors.md
 docs/reference/events.md
 docs/reference/operations.md
+docs/reference/surface-budget.md
 docs/reference/testing.md
 docs/reference/tools.generated.md
 docs/reference/tools.md
@@ -87,6 +110,7 @@ domain/contracts/tool-inputs/missions.js
 domain/contracts/tool-inputs/ops.js
 domain/contracts/tool-inputs/shared.js
 domain/errors.js
+domain/events.js
 domain/gate.js
 domain/integration/gate.js
 domain/integration/init.js
@@ -96,6 +120,7 @@ domain/integration/provision.js
 domain/integration/rebase.js
 domain/integration/review.js
 domain/integration/teardown.js
+domain/lockBudget.js
 domain/mission.js
 domain/missions/completion.js
 domain/missions/findings.js
@@ -115,50 +140,49 @@ domain/state/migrations.js
 domain/state/schema.js
 domain/state/semantics.js
 domain/summary.js
+domain/surface.js
 domain/vocabulary.js
+host/compatibility.js
+host/config.js
+host/doctor.js
+host/hmr.js
+host/modeState.js
+host/modeStore.js
+host/presets.js
+host/tool-registry.js
+host/tower.js
 icon.svg
 index.js
-lib/archive.js
-lib/briefing.js
-lib/caseSensitivity.js
-lib/compatibility.js
-lib/config.js
-lib/doctor.js
-lib/git.js
-lib/hmr.js
-lib/leases.js
-lib/legacy.js
-lib/modeState.js
-lib/modeStore.js
-lib/persistence.js
-lib/presets.js
-lib/spawn-prechecks.js
-lib/spawn-support.js
-lib/stateFile.js
-lib/store.js
-lib/tests.js
-lib/tool-registry.js
-lib/workspaceLock.js
-lib/worktreeOwnership.js
 locale/en.json
 locale/zh.json
 package.json
+ports/archive.js
+ports/caseSensitivity.js
 ports/clock.js
+ports/config.js
+ports/contract.js
+ports/events.js
 ports/ids.js
 ports/index.js
+ports/ownership.js
+ports/state.js
 ports/store.js
 ports/vcs.js
 reviewer.js
+scripts/architecture-waivers.json
 scripts/architecture.mjs
 scripts/check-docs.mjs
 scripts/check-pack.mjs
+scripts/check-philosophy.mjs
 scripts/domain-metrics.mjs
 scripts/enable-dev-hmr.mjs
 scripts/generate-config-reference.mjs
 scripts/generate-error-reference.mjs
+scripts/generate-events-reference.mjs
 scripts/generate-tools-reference.mjs
 scripts/issue-audit.mjs
 scripts/lib/cli.mjs
+scripts/lib/surface.mjs
 scripts/lib/tmp.mjs
 scripts/mount-smoke.mjs
 scripts/mount-smoke/fixtures.mjs
@@ -166,7 +190,10 @@ scripts/mount-smoke/host.json
 scripts/mount-smoke/probe.mjs
 scripts/mount-smoke/surface.mjs
 scripts/pack-manifest.txt
+scripts/regression-audit.mjs
 scripts/release-check.mjs
+scripts/surface-baseline.json
+scripts/surface-baseline.mjs
 skills.js
 skills/tower-recovery.md
 skills/tower-review.md
@@ -202,7 +229,16 @@ tools/test.js
 types/cordis.d.ts
 types/index.d.ts
 ui-bundle/README.md
+ui-bundle/client.cards.js
+ui-bundle/client.denied.js
+ui-bundle/client.dock.js
+ui-bundle/client.helpers.js
 ui-bundle/client.js
+ui-bundle/client.locales.js
+ui-bundle/client.mode.js
+ui-bundle/client.overlay.js
+ui-bundle/client.styles.js
+ui-bundle/client.toolview.js
 ui-bundle/cordis.patch.yml
 ui-bundle/icon.svg
 ui-bundle/index.js

package/scripts/regression-audit.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// Regression closure audit (#85): a closed `regression` issue must name a
+// `Regression test:` path that exists.
+//
+// A regression is "worked in a released version, then stopped". The project's
+// own closure standard is a pointer, not prose: the incident template
+// (docs/operations/incident.md) carries six fields and the regression test path
+// is the one that can be checked. This script reads a local tracker export, the
+// same format as `npm run audit:issues`, so it never touches the network:
+//
+//   { "issues": [ { number, title, state, labels, closedAt, body, comments } ] }
+//
+// Usage:
+//   node scripts/regression-audit.mjs [--tracker <file>] [--root <dir>] [--json]
+//
+// Exit codes: 0 all checked regressions point at an existing test; 1 at least
+// one is missing or points at a nonexistent/non-test path; 2 the export is
+// missing or malformed.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { inspectPointer, isClosed, labelsOf, parseTracker } from './issue-audit.mjs'
+import { findingRecorder, parseArgs, runMain } from './lib/cli.mjs'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const DEFAULT_TRACKER = path.join('tracker', 'issues.json')
+const USAGE = `usage: node scripts/regression-audit.mjs [--tracker <file>] [--root <dir>] [--json]
+
+  --tracker  local tracker export (default: tracker/issues.json)
+  --root     repository the Regression test paths resolve against (default: this package)
+  --json     print the report as JSON
+  --help     print this text
+
+A regression issue is closed when state is closed (or closedAt is set) and its
+labels include "regression". Its body or newest comment must carry:
+
+  Regression test: tests/<file>.test.mjs
+
+The path must exist under --root and must be a test file. Produce the export once
+with gh (see CONTRIBUTING.md, "Regressions and incidents"); the audit itself is
+offline.`
+
+function cleanValue(value) {
+  return String(value)
+    .trim()
+    .replace(/^`+|`+$/g, '')
+    .trim()
+    .replace(/^["']+|["']+$/g, '')
+    .trim()
+}
+
+/**
+ * The newest text (body first, then comments oldest to newest) that carries a
+ * `Regression test:` line is the closure evidence. Returns `{ pointer }` or
+ * `{ error: 'missing' }`.
+ * @param {any} issue
+ */
+export function selectRegressionField(issue) {
+  const sources = []
+  if (typeof issue.body === 'string' && issue.body.trim()) sources.push(issue.body)
+  const comments = Array.isArray(issue.comments) ? issue.comments : []
+  for (const comment of comments) {
+    const body = typeof comment === 'string' ? comment : comment?.body
+    if (typeof body === 'string' && body.trim()) sources.push(body)
+  }
+  for (let index = sources.length - 1; index >= 0; index -= 1) {
+    for (const rawLine of sources[index].split(/\r?\n/)) {
+      const line = rawLine.replace(/^\s*(?:[-*+]\s+|>\s*)+/, '')
+      const match = /^Regression test\s*:\s*(.+)$/i.exec(line)
+      if (!match) continue
+      const pointer = cleanValue(match[1])
+      if (pointer) return { pointer }
+    }
+  }
+  return { error: 'missing' }
+}
+
+/**
+ * Audit closed regression issues against the repository test tree.
+ * @param {any[]} issues parsed tracker issues
+ * @param {{ root?: string }} [options]
+ */
+export function auditRegressions(issues, options = {}) {
+  const root = path.resolve(options.root ?? PACKAGE_ROOT)
+  const findings = []
+  let checked = 0
+  for (const issue of issues) {
+    if (!isClosed(issue)) continue
+    const labels = labelsOf(issue).map((label) => label.toLowerCase())
+    if (!labels.includes('regression')) continue
+    checked += 1
+    const label = `#${issue.number} ${String(issue.title ?? '').trim()}`
+    const record = findingRecorder(findings, { number: issue.number, title: issue.title })
+    const field = selectRegressionField(issue)
+    if (field.error) {
+      record(
+        'missing-regression-test',
+        'error',
+        `${label}: closed regression has no "Regression test:" field (see docs/operations/incident.md)`,
+      )
+      continue
+    }
+    const problem = inspectPointer(field.pointer, root)
+    if (!problem) continue
+    if (problem.code === 'missing-test') {
+      record('missing-regression-test', 'error', `${label}: Regression test names a missing file: ${field.pointer}`)
+    } else if (problem.code === 'not-a-test') {
+      record('not-a-test', 'error', `${label}: Regression test is not a test file: ${field.pointer} (${problem.detail})`)
+    } else {
+      record(
+        'invalid-regression-test',
+        'error',
+        `${label}: Regression test must be a repository-relative path: ${field.pointer} (${problem.detail})`,
+      )
+    }
+  }
+  const errors = findings.filter((item) => item.level === 'error')
+  return { ok: errors.length === 0, checked, findings, errors: errors.length }
+}
+
+function main(argv) {
+  const options = parseArgs(argv, {
+    initial: { tracker: null, root: PACKAGE_ROOT, json: false, help: false },
+    values: {
+      '--tracker': 'tracker',
+      '--root': { key: 'root', parse: path.resolve },
+    },
+    flags: { '--json': 'json', '--help': 'help', '-h': 'help' },
+  })
+  if (options.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const tracker = options.tracker ? path.resolve(process.cwd(), options.tracker) : path.join(PACKAGE_ROOT, DEFAULT_TRACKER)
+  let text
+  try {
+    text = fs.readFileSync(tracker, 'utf8')
+  } catch (error) {
+    console.error(`regression-audit: cannot read tracker export ${tracker}: ${error?.message ?? error}`)
+    console.error('regression-audit: produce one with the gh command in CONTRIBUTING.md ("Regressions and incidents")')
+    return 2
+  }
+  let issues
+  let result
+  try {
+    issues = parseTracker(text)
+    result = auditRegressions(issues, { root: options.root })
+  } catch (error) {
+    console.error(`regression-audit: ${error.message}`)
+    return 2
+  }
+  if (options.json) {
+    console.log(JSON.stringify({ tracker, root: path.resolve(options.root), ...result }, null, 2))
+    return result.ok ? 0 : 1
+  }
+  console.log(`regression-audit: ${tracker}`)
+  console.log(`regression-audit: ${result.checked} closed regression(s) checked, ${result.errors} error(s)`)
+  for (const item of result.findings) console.log(`${item.level} [${item.code}] ${item.message}`)
+  if (result.ok) console.log('regression-audit: every closed regression names an existing test file')
+  else console.log('regression-audit: a closed regression has no verifiable test pointer; see docs/operations/incident.md')
+  return result.ok ? 0 : 1
+}
+
+await runMain(import.meta.url, () => main(process.argv.slice(2)), { errorPrefix: 'regression-audit', usage: USAGE })

package/scripts/release-check.mjs

@@ -27,7 +27,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { compareVersions } from '../lib/compatibility.js'
+import { compareVersions } from '../host/compatibility.js'
 import { findingRecorder, parseArgs, runMain, UsageError } from './lib/cli.mjs'
 
 const USAGE = `usage: node scripts/release-check.mjs [--mode pr|tag] [--tag <name>] [--json] [--help]

package/scripts/surface-baseline.json

@@ -0,0 +1,21 @@
+{
+  "schema": 1,
+  "date": "2026-10-23",
+  "surfaces": {
+    "configKeys": {
+      "seed": 64,
+      "value": 64,
+      "decisions": []
+    },
+    "sections": {
+      "seed": 15,
+      "value": 15,
+      "decisions": []
+    },
+    "tools": {
+      "seed": 27,
+      "value": 27,
+      "decisions": []
+    }
+  }
+}