ultra-builder-pro-cli 0.14.0 → 0.15.0

package/adapters/_shared/file-ops.cjs

@@ -8,7 +8,11 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 
-const DEFAULT_EXCLUDES = new Set(['.DS_Store', 'Thumbs.db']);
+const DEFAULT_EXCLUDES = new Set(['.DS_Store', 'Thumbs.db', '__pycache__']);
+
+function isExcluded(name, exclude) {
+  return exclude.has(name) || name.endsWith('.pyc') || name.endsWith('.pyo');
+}
 
 function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
@@ -27,7 +31,7 @@ function listRelative(root, { exclude = DEFAULT_EXCLUDES } = {}) {
   const out = [];
   (function walk(dir) {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      if (exclude.has(entry.name)) continue;
+      if (isExcluded(entry.name, exclude)) continue;
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (entry.isFile()) out.push(path.relative(root, full));

package/adapters/claude.js

@@ -63,8 +63,8 @@ function copySkills(repoRoot, target, names) {
           adaptedBody = adaptedBody.replaceAll("current host's user skill directory", '`~/.claude/skills`');
         }
         if (name === 'ultra-review') {
-          adaptedBody = adaptedBody.replaceAll(
-            "the current host's native bounded-worker mechanism",
+          adaptedBody = adaptedBody.replace(
+            /the current host's native bounded-worker\s+mechanism/g,
             'Claude Code Task workers using the installed review agent definitions',
           );
         }
@@ -194,6 +194,7 @@ function install(ctx = {}) {
       plugin_manifest: { root: 'plugin', path: '.claude-plugin/plugin.json' },
       mcp_registration: { root: 'plugin', path: '.mcp.json' },
       mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+      hook_event_helper: { root: 'plugin', path: 'runtime/hook-event.cjs' },
       hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
       checkpoint_hook: { root: 'plugin', path: 'hooks/workflow_checkpoint.py' },
       resume_hook: { root: 'plugin', path: 'hooks/workflow_resume.py' },

package/adapters/codex.js

@@ -375,6 +375,7 @@ function install(ctx = {}) {
       plugin_manifest: { root: 'plugin', path: '.codex-plugin/plugin.json' },
       mcp_registration: { root: 'plugin', path: '.mcp.json' },
       mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+      hook_event_helper: { root: 'plugin', path: 'runtime/hook-event.cjs' },
       hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
       hook_adapter: { root: 'plugin', path: HOOK_ADAPTER_RELATIVE },
       runtime_manifest: { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },

package/adapters/kimi.js

@@ -94,8 +94,8 @@ function kimiTextTransform(input, assetName = '') {
     text = text.replaceAll('current host', 'Kimi Code');
   }
   if (assetName === 'ultra-review') {
-    text = text.replaceAll(
-      "the current host's native bounded-worker mechanism",
+    text = text.replace(
+      /the current host's native bounded-worker\s+mechanism/g,
       'Kimi `AgentSwarm` for parallel reviewers or one foreground Kimi `Agent` for a single reviewer, using the worker prompt files under `$KIMI_PLUGIN_ROOT/agents/`',
     );
   }
@@ -349,6 +349,7 @@ function writePluginProvenance(repoRoot, target) {
     contracts: {
       plugin_manifest: { root: 'plugin', path: 'kimi.plugin.json' },
       mcp_launcher: { root: 'plugin', path: path.join('runtime', 'launch.cjs') },
+      hook_event_helper: { root: 'plugin', path: path.join('runtime', 'hook-event.cjs') },
       hook_adapter: { root: 'plugin', path: path.join('hooks', 'adapters', 'kimi.py') },
       session_bootstrap: {
         root: 'plugin', path: path.join('skills', BOOTSTRAP_SKILL, 'SKILL.md'),

package/adapters/opencode.js

@@ -86,8 +86,8 @@ function openCodeTextTransform(input, assetName = '') {
     text = text.replaceAll('current host', 'OpenCode');
   }
   if (assetName === 'ultra-review') {
-    text = text.replaceAll(
-      "the current host's native bounded-worker mechanism",
+    text = text.replace(
+      /the current host's native bounded-worker\s+mechanism/g,
       'the OpenCode `task` tool using the installed bounded review agents',
     );
   }
@@ -454,6 +454,7 @@ function install(ctx = {}) {
       host_plugin: { root: 'config', path: path.join('plugins', 'ultra-builder-pro.js') },
       mcp_config: { root: 'config', path: 'opencode.json' },
       mcp_launcher: { root: 'config', path: path.join(BUNDLE_DIR, 'runtime', 'launch.cjs') },
+      hook_event_helper: { root: 'config', path: path.join(BUNDLE_DIR, 'runtime', 'hook-event.cjs') },
     },
   });
   report.provenance.file = provenanceFile;

package/agents/review-coordinator.md

@@ -13,7 +13,8 @@ rewrite a specialist's severity.
 
 ## Required input
 
-- `SESSION_PATH`, reviewed HEAD, diff range, and expected worker list;
+- `SESSION_PATH`, review mode, reviewed HEAD, diff range, and expected worker list with
+  selection or skip rationale;
 - `SCHEMA_PATH` resolved by the parent from the active review Skill;
 - one complete `spec_fidelity` artifact;
 - every selected `engineering_standards` artifact.
@@ -24,10 +25,9 @@ rewrite a specialist's severity.
 2. Parse every expected artifact. Reject stale HEAD or range, malformed JSON, wrong
    axis, duplicate finding ids, and missing required fields. Record missing or invalid
    workers as limitations instead of silently continuing as complete.
-3. Deduplicate only findings on the same axis that describe the same root cause in the
-   same path with overlapping evidence. Preserve all source ids and agents, keep the
-   highest source severity, and retain the clearest trigger, impact, evidence, and
-   remediation. Similar symptoms with different causes remain separate.
+3. Preserve every specialist finding unchanged in `SUMMARY.json`. Group duplicate
+   root causes only in the human-readable `SUMMARY.md`; never drop, merge, rewrite, or
+   renumber their machine-readable source records.
 4. Order findings by severity, path, and line. Do not use confidence scores, reviewer
    counts, or finding-count thresholds to change severity or verdict.
 5. Set each axis to `PASS` only when its required current artifacts are complete and no
@@ -36,7 +36,10 @@ rewrite a specialist's severity.
 6. Set the overall verdict to `INCOMPLETE` when either axis is incomplete,
    `REQUEST_CHANGES` when either complete axis fails, and `APPROVE` only when both
    axes pass.
-7. Write `SUMMARY.json` as `ultra-review-summary-v2` and a concise `SUMMARY.md` with
+7. Record the review mode and every selected or skipped worker with its supplied
+   scope-specific rationale. The selection must match completed, failed, and skipped
+   worker state exactly.
+8. Write `SUMMARY.json` as `ultra-review-summary-v2` and a concise `SUMMARY.md` with
    the two axis verdicts, blocking findings, limitations, positive observations, and
    artifact paths. Validate both files before acknowledging completion.
 

package/docs/AGENT-CONTEXT.md

@@ -38,14 +38,14 @@ native command or skill -> MCP workflow-state operation -> .ultra/state.db
 | CLI | `ultra-tools`, `ubp-orchestrator` | Selected initialization, backup-first recovery, automation, and diagnostics; not a change-state mirror |
 
 `.ultra/state.db` is the only durable Ultra authority for baselines, changes, tasks,
-sessions, events, incidents, projection jobs/cursors, telemetry, review evidence,
+workflow runs/steps, sessions, events, incidents, projection jobs/cursors, telemetry, review evidence,
 and circuit-breaker state. `tasks.json`, context Markdown, execution plans, and
 reports are projections or workflow artifacts.
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 36 tools across
-six families:
+`spec/mcp-tools.yaml` declares and the bundled server registers 41 tools across
+seven families:
 
 | Family | Live tools |
 |---|---|
@@ -53,6 +53,7 @@ six families:
 | `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events |
 | `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
 | `change.*` | create, update, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
+| `workflow.*` | start, get, list, step, complete |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
@@ -60,12 +61,15 @@ Review, repository impact discovery, skill loading, and user interaction remain
 host-native capabilities rather than fake MCP contracts. The generated Codex
 capability map documents those replacements.
 
+The complete write, transition, invalidation, and recovery contract lives in
+[`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md).
+
 Any new MCP contract starts in `spec/mcp-tools.yaml` with valid and invalid
 fixtures. Do not add an ad-hoc server handler first.
 
 ## 4. Context Spine contract
 
-Context Manifest v2 is a DB-backed role handoff, not a static codebase summary.
+Context Manifest v2 is an immutable DB-backed role handoff, not a static codebase summary.
 `change.context` compiles required references, digests, readiness, context budget,
 public seam, exact verification command, and one next action for `plan`,
 `implement`, `check`, or `review`. The default 12-file, about 12k-token, and 40%
@@ -111,7 +115,8 @@ the shared read-only `context_spine.py` breadcrumb helper:
 - `workflow_checkpoint.py` before compaction;
 - `workflow_resume.py` after compaction/resume;
 - `pre_stop_check.py` reports unfinished workflow position at stop without denial;
-- `subagent_tracker.py` for bounded worker lifecycle evidence.
+- `subagent_tracker.py` for minimal DB event evidence containing only lifecycle ids
+  and types, never transcript paths or messages.
 
 `workflow_context.py`, `active_task_context.py`, `workflow_resume.py`, and the
 OpenCode plugin invoke the same bundled JavaScript `change.breadcrumb` reader
@@ -159,9 +164,11 @@ Archive before prune; the confirmation token is intentionally required.
 ├── tasks/                   # projections and task contexts
 ├── specs/                   # research/product/architecture artifacts
 ├── sessions/                # bounded runtime artifacts
-├── reviews/                 # review evidence
-├── test-report.json
-└── delivery-report.json
+├── reviews/                 # immutable review evidence by session id
+└── reports/
+    ├── templates/           # blank report schemas; never evidence
+    ├── tests/<workflow-id>.json
+    └── delivery/<workflow-id>.json
 ```
 
 ## 9. User handbook integration

package/docs/ARCHITECTURE.md

@@ -53,7 +53,7 @@ the supported hosts share.
 | Layer        | Role                                         | Form                                                  |
 |--------------|----------------------------------------------|-------------------------------------------------------|
 | **skill**    | knowledge carrier; tells the runtime *what to do* | `skills/<name>/SKILL.md` discovered natively by all supported runtimes |
-| **MCP**      | authoritative workflow-state and Context Spine API | stdio MCP server exposing 36 live tools across baseline/task/session/change/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
+| **MCP**      | authoritative workflow-state and Context Spine API | stdio MCP server exposing 41 live tools across task/session/baseline/change/workflow/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
 | **CLI**      | explicit initialization, recovery, diagnostics, and orchestration | `ultra-tools` / `ubp-orchestrator`; only commands listed by `--help` are executable (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
 
 Why three: skills give us behavior portability across runtimes; MCP gives
@@ -70,11 +70,11 @@ RPC, and host-native loaders own resolution and invocation.
 
 All durable Ultra workflow state lives in one SQLite file with WAL enabled. Schema is
 fixed in [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) and
-covers seventeen tables:
+covers nineteen tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
-| `baselines`        | repository classification, greenfield/brownfield adoption, worktree snapshot, specs, evidence, verification, gap ledger, and approval | 12 |
+| `baselines`        | repository classification, greenfield/brownfield adoption, worktree snapshot, specs, evidence, verification, gap ledger, persisted known-red acceptance, and approval | 12→14 |
 | `tasks`            | task rows — id, status, deps, files_modified, …   | 2     |
 | `events`           | append-only event stream; `id` is subscription cursor (D31) | 2 |
 | `sessions`         | execution sessions, **including lease + heartbeat fields** (D32) | 4.5 |
@@ -91,6 +91,8 @@ covers seventeen tables:
 | `incidents`        | structured runtime failures and resolutions         | 8C    |
 | `projection_jobs` | durable projection outbox/retry state                | 8C    |
 | `event_consumers` | durable monotonic consumer cursors                   | 8C    |
+| `workflow_runs`   | init/research/plan/change/dev/test/review/deliver run authority, position, blockers, approval, and derived summary | 13 |
+| `workflow_steps`  | ordered step state, evidence, decisions, immutable output paths, and recorded SHA-256 digests | 13 |
 
 Two rules make this work:
 
@@ -103,12 +105,16 @@ Two rules make this work:
 2. **Single writer for mutable tables, multi-writer for `events`.**
    `.ultra/state.db` opens in WAL with `busy_timeout=5000`. The MCP
    server holds the single writer connection for `baselines`, `tasks`, `sessions`,
-   `changes`, `context_snapshots`, `spec_learning_candidates`, `telemetry`,
+   `changes`, `workflow_runs`, `workflow_steps`, `artifacts`, `context_snapshots`,
+   `spec_learning_candidates`, `incidents`, `projection_jobs`, `telemetry`,
    `specs_refs`, and `migration_history`; the CLI calls
    those tools over stdio rather than opening its own writer. The
    `events` table is append-only and explicitly multi-writer — CLI and
    orchestrator processes append directly to it under the same WAL +
    `busy_timeout` discipline, since independent INSERTs do not conflict.
+   External writers and public `task.append_event` may append observations only;
+   lifecycle event names are emitted by the mutation that owns the corresponding
+   DB transition and no event row can substitute for that transition.
    In `spec/mcp-tools.yaml` this split is captured by `writer_role: mcp`
    (must go through the MCP server) versus `writer_role: any` (any
    process may execute). Full policy lives in
@@ -143,14 +149,22 @@ produce a pre-migration backup. Compatibility state never grants baseline approv
 references, bounded repository/runtime evidence, actual verification results,
 known unknowns, repository branch and worktree snapshot, the categorized gap ledger,
 and metadata-only external provider references, and
-`baseline.converge` records explicit owner approval. A ready baseline is replaced
-only by an explicit re-adoption, preserving the superseded row for recovery.
+`baseline.converge` records explicit owner approval, including a durable
+`known_red_accepted` decision when applicable. Read paths continuously revalidate
+ready authority: scope, three specifications, source/runtime evidence, verification,
+known-red rationale and acceptance, research provenance and output digests, repository
+revision/worktree state, blocking gaps and unknowns, approver, and convergence time.
+A row cannot become trusted merely because its stored status says `ready`. A ready
+baseline is replaced only by an explicit re-adoption, preserving the superseded row
+for recovery.
 For a selected monorepo scope, the worktree digest and dirty-file list include only
 that scope; out-of-scope changes remain visible repository context but cannot be
 accepted implicitly by `accept_dirty_worktree`.
 
-New ordinary changes require a healthy `ready` baseline. A change that was already
-active may continue with baseline drift surfaced as a warning. A new incident can
+New ordinary changes require a healthy `ready` baseline. An active ordinary change may
+continue through only the expected HEAD/worktree/spec/source drift created after its
+durable `bind-baseline` step; loss of ready approval, missing evidence, blocking gaps,
+or any other structural defect stops task/context/stage progression. A new incident can
 start on an unhealthy baseline only with an explicit reason and approver stored in
 `baseline_bypass_json`. Ordinary convergence and archive reconcile HEAD, worktree,
 and tracked-spec drift atomically. Break-glass incident archive creates an open
@@ -167,7 +181,7 @@ active -> blocked -> active -> ready -> archived
    |                              |
    ├─ intent + delta + plan       └─ verification + baseline reconciliation
    ├─ linked tasks
-   ├─ context-manifest v2 (role + gate + readiness + execution seam)
+   ├─ immutable context snapshots (role + gate + readiness + execution seam)
    └─ spec-learning candidates (proposed -> approved/rejected -> applied)
 ```
 
@@ -178,17 +192,23 @@ impact, and no open incident. Memory and graph payloads never enter Ultra;
 
 ### Context Spine
 
-Context Manifest v2 is the handoff contract between planning, implementation,
-checking, review, convergence, and recovery. Each snapshot records:
+Context Manifest v2 is the immutable handoff contract between planning,
+implementation, checking, review, convergence, and recovery. Each snapshot records:
 
 - one role (`plan`, `implement`, `check`, or `review`) and lifecycle gate;
 - required context references with local digests and reasons;
 - readiness blockers for missing/stale required references or an incomplete
   execution contract;
 - advisory attention budgets (12 files / about 12k tokens / 40% by default);
-- an execution contract (`slice_kind`, public seam, exact verification command);
+- a DB-derived execution contract (`slice_kind`, public seam, exact verification command);
 - one deterministic next action.
 
+Prompt input may identify the intended role/gate, add bounded reference candidates,
+and lower advisory budgets. It cannot supply or override the task seam, verification
+command, task context references, evidence digest, gate verdict, workflow summary, or
+next action. Critical change/dev/test/review/deliver workflow steps record the matching
+snapshot as an output; test, review, and delivery reports carry its digest forward.
+
 `change.breadcrumb` derives the compact current position from state.db. Session,
 edit, resume, and OpenCode lifecycle hooks invoke one bundled read-only reader
 and inject only this breadcrumb, never the intent body,
@@ -315,6 +335,7 @@ shippable; downstream slip never blocks an earlier release.
 | Exact SQLite schema?                               | [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) |
 | What does a tasks.json look like after projection? | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
 | Phase-by-phase work breakdown + decision log       | [`docs/PLAN.zh-CN.md`](./PLAN.zh-CN.md)             |
+| When does each workflow write, invalidate, and converge state? | [`docs/WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md) |
 
 ## 10. Verifying the architecture
 

package/docs/PLAN.zh-CN.md

@@ -10,8 +10,9 @@
 > Kimi Code 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：v0.13.0；四宿主 native plugin、36 个 live MCP tool、
-schema 12.0（17 表）、portable Skill authoring contract、双轴 review、
+**当前状态**：v0.15.0；四宿主 native plugin、41 个 live MCP tool、
+schema 15.0（19 表）、typed research semantics、complete Change Contract、
+acceptance coverage、mode-bound 双轴 review、verified learning/reconciliation provenance、
 Context Spine v2 / breadcrumb / spec-learning、持续 change/context/convergence/doctor、incident debug lane、
 checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发布由
 `v*.*.*` tag 触发。以下 Phase 0-9 正文保留为 2026-04 的实施历史，不再作为

package/docs/ROADMAP.md

@@ -13,7 +13,7 @@ sharing one authoritative workflow store.
 
 **Distribution channels (v1.0)**: npm · Homebrew · pip.
 
-**Release line**: `0.11.x`; every release is gated by `npm run verify:release`.
+**Release line**: `0.14.x`; every release is gated by `npm run verify:release`.
 
 ---
 
@@ -45,24 +45,27 @@ sharing one authoritative workflow store.
 | 8C    | Continuous change packets + context compiler + convergence + doctor | ✅ done (D52) |
 | 10    | Context Spine v2 + breadcrumb + fresh-context budget + spec learning + two-axis review | ✅ done |
 | 11    | Greenfield/brownfield baseline adoption + advisory context budgets + convergence gate | ✅ done |
+| 12    | Repository evidence snapshots + gap ledger + migration re-adoption + incident governance | ✅ done |
+| 13    | Durable init-to-delivery workflows + task execution contracts + immutable stage evidence | ✅ done |
 | 9     | Release pipeline                               | npm tag publishing live; Homebrew / pip not implemented |
 
 ## What is in the repo today
 
 ```
 spec/                       ← Phase 1 single source of truth
-├── mcp-tools.yaml          (36 live tools across 6 families)
+├── mcp-tools.yaml          (41 live tools across 7 families)
 ├── cli-protocol.md         (CLI ↔ MCP mapping table)
 ├── schemas/                (state-db.sql + 4 JSON schemas)
 ├── fixtures/{valid,invalid}/  (+ v4.4-project for migration)
 └── scripts/test-all.cjs    (npm run test:spec — 7 validation stages)
 
 mcp-server/                 ← Phase 2 authoritative state layer
-├── server.cjs              (stdio MCP server, 36 baseline/task/session/change/system/plan tools)
+├── server.cjs              (stdio MCP server, 41 task/session/baseline/change/workflow/system/plan tools)
 ├── lib/
 │   ├── state-db.cjs        (SQLite + WAL + pragmas)
 │   ├── state-ops.cjs       (full write API, status state machine)
 │   ├── baseline-workflow.cjs (project adoption + approval + reconciliation)
+│   ├── workflow-state.cjs  (ordered stage runs, evidence, output digests, and gates)
 │   └── projector.cjs       (state.db → tasks.json + context md)
 └── tests/                  (npm run test:state)
 
@@ -70,7 +73,7 @@ ultra-tools/                ← CLI fallback, migration, and diagnostics
 ├── cli.cjs
 └── commands/
     ├── db.cjs              (init/checkpoint/vacuum/integrity/backup)
-    ├── migrate.cjs         (v4.4 projection → v4.5 authority; v4.5 projection → schema 12; dry/rollback)
+    ├── migrate.cjs         (v4.4 projection → v4.5 authority; v4.5 projection → current schema; dry/rollback)
     └── legacy-memory.cjs   (explicit inspect/archive/confirmed prune)
 
 bin/install.js              ← multi-runtime installer
@@ -81,6 +84,7 @@ hooks/                      ← 7 executable workflow hooks + shared Context Spi
 docs/
 ├── PLAN.zh-CN.md                historical phase plan + decision log
 ├── ARCHITECTURE.md              Phase 1 single-page entry point
+├── WORKFLOW-LIFECYCLE.md        baseline classification + DB transition contract
 ├── AGENT-CONTEXT.md             Phase 3 canonical runtime context contract
 ├── USER-HANDBOOK-CONTRACT.md    managed CLAUDE.md / AGENTS.md boundary
 ├── RUNTIME-COMPAT-MATRIX.md     Phase 4 runtime capability matrix

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -71,7 +71,7 @@ they do not deny edits or stop active incident work.
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | plugin `mcpServers` entry |
-| Live/declared contracts | 36 | 36 | 36 | 36 |
+| Live/declared contracts | 41 | 41 | 41 | 41 |
 | Greenfield/brownfield baseline adoption | FULL | FULL | FULL | FULL |
 | Context Spine v2 / breadcrumb | FULL | FULL, same bundled read-only DB reader as every hook | FULL | FULL |
 | Approval-gated spec learning | FULL | FULL | FULL | FULL |
@@ -79,7 +79,7 @@ they do not deny edits or stop active incident work.
 | Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
 | Ultra memory API | N/A | N/A | N/A | N/A |
 
-All 36 `baseline.*`, `task.*`, `session.*`, `change.*`, `system.*`, and `plan.*` operations
+All 41 `task.*`, `session.*`, `baseline.*`, `change.*`, `workflow.*`, `system.*`, and `plan.*` operations
 registered by `mcp-server/server.cjs` are live. Review, impact discovery, skill
 loading, and user interaction remain host-native surfaces.
 
@@ -126,9 +126,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `12.0` |
+| Current state schema | `15.0` |
 | Runtime values | `claude`, `opencode`, `codex`, `kimi` |
-| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, authoritative baseline adoption in 11.0, then runtime constraint compatibility in 12.0 |
+| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, authoritative baseline adoption in 11.0, repository evidence in 12.0, durable workflows in 13.0, continuous baseline revalidation in 14.0, then typed research semantics, complete Change Contracts, verified learning application, and reconciliation provenance in 15.0 |
 | Preservation gate | rows, IDs, indexes, foreign keys, telemetry, incidents, and migration history remain intact |
 | Failure behavior | rollback; no partially upgraded authority database |
 

package/docs/STATE-DB-ACCESS-POLICY.md

@@ -4,13 +4,13 @@
 > risks R21 / R25.
 
 `.ultra/state.db` is the only authoritative state store for baselines, changes,
-tasks, events, sessions, incidents, projections, telemetry, and spec references
+tasks, workflow runs/steps, events, sessions, incidents, projections, telemetry, and spec references
 (D18, D52, D54). Every process
 that touches it must follow the rules below; deviations are bugs.
 
 ## 1. Three-role write matrix
 
-| Role | tasks | baselines | change/artifact state | events | sessions | telemetry | specs_refs | migration_history |
+| Role | tasks | baselines | change/workflow/artifact state | events | sessions | telemetry | specs_refs | migration_history |
 |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 | **MCP server** (single writer for mutables) | RW | RW | RW | RW | RW | RW | RW | RW |
 | **CLI** (`ultra-tools …`) | R | RW (init only) | R | RW (append-only) | R | R | R | RW (migration only) |
@@ -31,7 +31,11 @@ write API for normal task, change, session, or baseline lifecycle updates.
 The append-only carve-out for `events` exists because `events.id INTEGER
 PRIMARY KEY AUTOINCREMENT` makes concurrent inserts collision-free under
 WAL + `busy_timeout`. This lets hooks and short-lived CLI invocations
-record audit events without paying the cost of a full MCP round trip.
+record audit observations without paying the cost of a full MCP round trip.
+It does not grant lifecycle authority: external writers and public
+`task.append_event` use the published observation allowlist, while lifecycle event
+names are emitted only inside the mutation that owns the corresponding state change.
+Consumers must verify mutable rows rather than infer success from an event name.
 
 ## 2. Connection discipline
 
@@ -40,31 +44,27 @@ Every process **must**:
 1. Open the database with WAL + `busy_timeout=5000` + `foreign_keys=ON`.
    Use `mcp-server/lib/state-db.cjs` `openStateDb` so the pragmas are
    applied uniformly.
-2. Wrap every write in `BEGIN IMMEDIATE` (use the helper `withWrite(db,
-   fn)` once Phase 2.3 lands; until then call `db.transaction(fn)()` and
-   know that better-sqlite3 promotes to IMMEDIATE on the first write).
-3. Retry up to **3 times** on `SQLITE_BUSY`, with exponential backoff
-   starting at 25 ms. Each retry must re-issue the full transaction —
-   never partially commit.
+2. Wrap every mutable state operation with `state-ops.cjs` `tx(db, fn)`. The
+   helper calls better-sqlite3's immediate transaction variant, so the writer
+   lock is acquired before user code runs and the whole operation rolls back on
+   failure.
+3. Retry the complete transaction up to **10 attempts** on `SQLITE_BUSY`, using
+   decorrelated jitter from a 50 ms base with a 2 s cap. Never retry only a
+   suffix of a failed transaction or preserve partial state.
 4. Close the connection in a `finally` block. WAL files (`-wal`,
    `-shm`) are reclaimed on the last writer's close.
 
 Reads never need explicit transactions; better-sqlite3 reads observe a
 consistent snapshot under WAL.
 
-## 3. WAL fallback
+## 3. WAL requirement
 
-WAL is **unsafe on NFS / SMB / certain Docker bind mounts** (R21). When
-`.ultra/state.db` resides on such a filesystem the orchestrator must
-either:
-
-- refuse to start (preferred — surfaces the deployment problem early), or
-- downgrade to `PRAGMA journal_mode = DELETE` and warn loudly. Concurrent
-  writers fall back to short-burst contention; throughput drops but
-  correctness holds.
-
-Detection happens at boot: `statvfs` of `.ultra/state.db`'s mount;
-`f_type` ∈ `{NFS_SUPER_MAGIC, SMB_SUPER_MAGIC}` ⇒ refuse / downgrade.
+WAL is part of the authority contract, not an optional performance setting.
+`openStateDb` asks SQLite to enable WAL and checks the actual returned mode. If
+the storage layer returns anything else, startup fails with
+`STATE_DB_WAL_UNAVAILABLE`. Ultra does not silently downgrade to a different
+concurrency model. Move `.ultra/state.db` to storage that supports SQLite WAL or
+resolve the mount/runtime constraint before retrying.
 
 ## 4. Where each table is owned
 
@@ -73,9 +73,10 @@ Detection happens at boot: `statvfs` of `.ultra/state.db`'s mount;
 | `baselines`        | MCP server (`baseline.start` / `baseline.record` / `baseline.converge`); initialization and legacy-projection migration may create only the first draft or compatibility row |
 | `tasks`            | MCP server (`task.create` / `task.update` / `task.delete`) |
 | `changes`          | MCP server (`change.create` / `change.update` / `change.converge` / `change.archive`) |
+| `workflow_runs`, `workflow_steps` | MCP server (`workflow.start` / `workflow.step` / `workflow.complete`); skills provide evidence inputs but never write rows directly |
 | `artifacts`, `context_snapshots`, `spec_learning_candidates`, `trace_links` | MCP server through change lifecycle tools |
 | `incidents`, `projection_jobs`, `event_consumers`, `circuit_breaker` | MCP server; backup-first doctor recovery may perform only documented mechanical transitions |
-| `events`           | MCP server **and** any process via append-only INSERT  |
+| `events`           | MCP server for lifecycle events; approved processes and `task.append_event` for allowlisted append-only observations |
 | `sessions`         | MCP server (`session.spawn` / `session.close` / `session.heartbeat`); orchestrator may write status transitions |
 | `telemetry`        | MCP server (collected from tool-call wrappers); orchestrator may dump bulk samples |
 | `specs_refs`       | MCP server (rebuilt on `spec_changed` event); orchestrator may rebuild |
@@ -110,6 +111,7 @@ The contract on this page is enforced by:
   appending to `events` simultaneously; asserts no `SQLITE_BUSY` escapes
   the retry loop and the resulting `events.id` sequence has no gaps and
   no duplicates.
-- Phase 2.3 will add `concurrency-update.test.cjs` — 20 worker threads
-  driving `task.update` against disjoint task ids, verifying serialized
-  writes through the MCP server.
+- `mcp-server/tests/state-ops.test.cjs` — immediate transactions, rollback,
+  status transitions, task contracts, and event coupling.
+- `mcp-server/lib/workflow-state.test.cjs` — ordered workflow transitions,
+  evidence/output requirements, blocking/resume, and cross-stage gates.