ultra-builder-pro-cli 0.14.0 → 0.16.0

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.14.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.16.0-blue)](./CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#verification)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)
@@ -25,9 +25,14 @@ authoritative `.ultra/state.db`.
   Install and uninstall are symmetric on every supported host; `ubp --doctor`
   verifies the installed asset hashes and host entry points without mutation.
 - **Shares state across runtimes.** `.ultra/state.db` (SQLite + WAL) is the
-  authoritative source for baselines, changes, tasks, sessions, events, incidents,
-  projection jobs, and telemetry. `tasks.json` and context markdown are
+  authoritative source for baselines, changes, decision threads, workflows, tasks,
+  sessions, events, incidents, projection jobs, and telemetry. `tasks.json` and context markdown are
   generated projections, not handwritten.
+- **Aligns the owner and agent without questionnaire overload.** The host resolves
+  observable facts first, then presents exactly one load-bearing decision with
+  evidence, a recommendation, credible alternatives, and the durable effect. The
+  normalized answer and owner-approved artifact checkpoint live in the DB; prompts
+  and transcripts do not. Matching workflows stop until that authority is current.
 - **Keeps memory ownership explicit.** Ultra Builder Pro does not collect
   prompts, transcripts, observations, summaries, or cross-session memory.
   Install cloud-mem/claude-mem separately if persistent memory is wanted.
@@ -35,10 +40,13 @@ authoritative `.ultra/state.db`.
   host derives task objects; `task.parse_prd` validates them → `lib/topo.cjs` waves →
   `.ultra/execution-plan.json` → parallel worktree sessions → auto-merge back.
 - **Keeps daily work convergent.** `/ultra-change` creates a bounded delta and
-  Context Manifest v2; the Context Spine assigns a role/gate, verifies required
+  complete Change Contract, classifies risk, records whether bounded research is
+  required, and creates immutable Context Manifest v2 snapshots; the Context Spine assigns a role/gate, verifies required
   references, reports fresh-context budget pressure as advisory warnings, exposes one DB-derived breadcrumb, and
-  routes a single next action. `/ultra-deliver` requires applied specification
-  learning plus docs/test/two-axis review evidence before archive. `/ultra-doctor` reports incidents,
+  routes a single next action. Research stores typed, source-digested semantic records;
+  planning proves Change acceptance coverage; `/ultra-deliver` requires applied specification
+  learning plus docs/test/mode-bound two-axis review evidence and a schema-validated
+  baseline reconciliation manifest before archive. `/ultra-doctor` reports incidents,
   projection lag, orphan sessions, and backup-first mechanical recovery.
   Incident changes additionally require a five-section `diagnosis.md` covering
   reproduction, hypotheses, root cause, regression test, and recovery.
@@ -86,13 +94,22 @@ install or update.
 See [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md)
 for per-runtime capabilities.
 
-Start with `ultra-init` in both new and existing projects. An empty project opens
-a `draft` greenfield baseline. An existing codebase opens an `adopting`
-brownfield baseline; inspect current behavior, call `baseline.record`, then
-approve it through `baseline.converge` before normal planning or delivery. Existing
-active work may continue while adoption drift is visible. A new incident requires an
-explicit break-glass approver and leaves a blocking reconciliation gap at archive;
-new ordinary work always requires a healthy ready baseline.
+Start with `ultra-init` in both new and existing projects. Auto classification is
+based on delivered-system evidence: application source, tests, deployment, or
+persisted-state/schema signals make a repository brownfield; a Git repository,
+manifest, README, or starter documentation alone remains greenfield. An empty project
+opens a `draft` greenfield baseline and an existing system opens an `adopting`
+brownfield baseline. Both execute all seventeen research steps before
+`baseline.record` and explicit `baseline.converge`; initialization never treats blank
+templates as a trusted baseline and never selects an MVP. Existing active work may
+continue only when its durable change workflow was bound to a healthy ready baseline;
+the expected HEAD, worktree, spec, and source-evidence drift created by that change is
+advisory until delivery reconciliation. Loss of approved-ready status or structural
+baseline evidence blocks ordinary work. An incident requires an explicit break-glass
+approver and leaves a blocking reconciliation gap at archive; new ordinary work always
+requires a healthy ready baseline. See
+[`docs/WORKFLOW-LIFECYCLE.md`](./docs/WORKFLOW-LIFECYCLE.md) for exact write,
+transition, invalidation, and recovery semantics.
 
 ## Three-layer architecture
 
@@ -105,10 +122,11 @@ new ordinary work always requires a healthy ready baseline.
 The layers share one `.ultra/state.db`, but the CLI is not a mirror of every MCP
 tool: continuous change mutations are MCP-only and fail closed. See
 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full contract and
-[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 36 live contracts.
-Review, impact discovery, skill resolution, and user interaction stay on each
-Host's native surfaces; the generated Codex capability map documents those
-replacements without advertising non-existent MCP tools.
+[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 50 live contracts.
+Review, impact discovery, skill resolution, and decision presentation stay on each
+host's native surfaces; MCP stores normalized decision authority but never generates
+questions. The generated Codex capability map documents those replacements without
+advertising non-existent MCP tools.
 
 The package boundary is deliberate: twelve public Ultra workflow skills, four
 internal review-rule skills, host-specific collaboration companions, and the
@@ -138,10 +156,12 @@ ultra-tools task init-project --project-name myapp --mode auto
 
 # Projection-only projects from prior releases use one backup-first import:
 ultra-tools migrate --from=4.4 --to=4.5 --source-dir .
-ultra-tools migrate --from=4.5 --to=12.0 --source-dir .
+ultra-tools migrate --from=4.5 --to=16.0 --source-dir .
 
-# 2. Record and converge the greenfield/brownfield baseline, then turn accepted
-#    behavior into a task graph (normally driven by ultra-init/research/plan)
+# 2. Complete all 17 research steps. When owner judgment is required, the host asks
+#    one evidence-backed decision at a time and checkpoints the accepted artifacts.
+#    Record current evidence, obtain explicit baseline approval, then open and align
+#    an initial change before persisting its task contracts.
 
 # 3. Run the plan — parallel sessions, auto-merge back to main on success
 ubp-orchestrator run
@@ -154,10 +174,11 @@ ultra-tools system doctor
 ```
 
 Or let the skills drive it. In Codex, invoke
-`$ultra-builder-pro:ultra-init` → `$ultra-builder-pro:ultra-plan` → `$ultra-builder-pro:ultra-dev` →
-`$ultra-builder-pro:ultra-test` → `$ultra-builder-pro:ultra-review` →
-`$ultra-builder-pro:ultra-deliver`; after the baseline is delivered, daily work
-starts with `$ultra-builder-pro:ultra-change`, while
+`$ultra-builder-pro:ultra-init` → `$ultra-builder-pro:ultra-research` →
+`$ultra-builder-pro:ultra-change` → `$ultra-builder-pro:ultra-plan` →
+`$ultra-builder-pro:ultra-dev` → `$ultra-builder-pro:ultra-test` →
+`$ultra-builder-pro:ultra-review` → `$ultra-builder-pro:ultra-deliver`; after the
+baseline is delivered, daily work starts with `$ultra-builder-pro:ultra-change`, while
 `$ultra-builder-pro:ultra-status` reads the compact authoritative breadcrumb.
 Kimi uses the corresponding
 `/ultra-builder-pro:ultra-*` namespace. Other runtimes retain their native
@@ -239,6 +260,7 @@ Individual suites: `test:state`, `test:orch`, `test:spec`, `test:rest`.
 | [`docs/PLAN.zh-CN.md`](./docs/PLAN.zh-CN.md) | Historical 12-phase plan and decision log with a current-boundary overlay |
 | [`docs/ROADMAP.md`](./docs/ROADMAP.md) | One-page English roadmap + phase status |
 | [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Single-page system architecture |
+| [`docs/WORKFLOW-LIFECYCLE.md`](./docs/WORKFLOW-LIFECYCLE.md) | Baseline classification, DB writes, status machines, gates, invalidation, and recovery |
 | [`docs/AGENT-CONTEXT.md`](./docs/AGENT-CONTEXT.md) | Canonical runtime context contract |
 | [`docs/USER-HANDBOOK-CONTRACT.md`](./docs/USER-HANDBOOK-CONTRACT.md) | Shared user-handbook policy and host renderings |
 | [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md) | Per-runtime capability matrix |

package/adapters/_shared/codex-assets.cjs

@@ -89,8 +89,8 @@ function replaceSlashCommand(text, command, replacement) {
 function adaptCodexPrimaryText(input, skillName) {
   let text = String(input);
   if (skillName === '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,
       'native Codex custom agents installed for the selected review workers',
     );
   }
@@ -396,6 +396,10 @@ main().catch((error) => {
     path.join(repoRoot, 'mcp-server', 'breadcrumb.cjs'),
     path.join(runtimeRoot, 'breadcrumb.cjs'),
   );
+  fs.copyFileSync(
+    path.join(repoRoot, 'mcp-server', 'hook-event.cjs'),
+    path.join(runtimeRoot, 'hook-event.cjs'),
+  );
 
   const sourceToolsFile = path.join(repoRoot, 'spec', 'mcp-tools.yaml');
   const upstreamManifest = yaml.load(fs.readFileSync(sourceToolsFile, 'utf8'));

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/_shared/handbook.cjs

@@ -59,8 +59,9 @@ function renderHandbook(runtime) {
     `- Workflow entry points: ${value.invocation}.`,
     `- Collaboration boundary: ${value.collaboration}. The current host remains primary and owns final verification.`,
     `- Coordination boundary: ${value.coordination}.`,
-    '- Authority: `.ultra/state.db` is the only durable Ultra authority for baselines, changes, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
+    '- Authority: `.ultra/state.db` is the only durable Ultra authority for baselines, changes, decision threads, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
     '- Baseline boundary: `task.init_project` classifies greenfield or brownfield work and records repository scope. Projection-only prior state uses the exact supported backup-first import returned by the authority check; migrated compatibility rows require explicit brownfield re-adoption. `baseline.record` owns evidence, verification, repository snapshot, and the gap ledger; `baseline.converge` requires explicit owner approval. New ordinary changes require a healthy ready baseline. Existing active work may continue with warnings, but baseline readiness blocks change convergence; normal drift reconciliation is health-checked atomically at archive. Only an explicitly approved incident break-glass may start without baseline readiness, and its archive creates a blocking reconciliation gap.',
+    '- Decision boundary: project-bound owner choices use one resumable DB-backed decision thread. The host resolves observable facts autonomously, presents only the earliest unresolved decision with evidence and a recommendation, waits for the owner, and records the normalized decision rather than prompts or transcripts. A linked workflow cannot advance until blocking decisions are resolved and its owner-approved checkpoint is current.',
     '- Context Spine boundary: `change.context` compiles role/gate readiness, required references, a fresh-context budget, public seam, verification command, and one next action. File, token, and context-share budgets are advisory attention signals, not refusal gates. Hooks inject only the DB-derived `change.breadcrumb`; missing required evidence or stale execution context must be recompiled.',
     '- Specification learning boundary: stable implementation discoveries use approval-gated propose/approve-or-reject/apply transitions. Unresolved learning blocks convergence; review requires independent specification-fidelity and engineering-standards evidence.',
     '- Memory and graph boundary: Ultra Builder Pro does not capture prompts, transcripts, observations, summaries, cross-session memory, or code-graph content. Separately installed providers own that data; Ultra may store only their metadata references in a change context manifest.',

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/commands/ultra-change.md

@@ -1,5 +1,5 @@
 ---
-description: Open or resume a bounded continuous change with linked authoritative tasks and context
+description: Align, open, and route one bounded continuous change through research, plan, and delivery
 argument-hint: "[change-id-or-title] [quick|standard|major|incident]"
 workflow-ref: "@skills/ultra-change/SKILL.md"
 ---

package/commands/ultra-plan.md

@@ -1,5 +1,5 @@
 ---
-description: Convert validated requirements into dependency-valid Ultra tasks with bounded context and exact verification
+description: Interactively review and persist dependency-valid tasks with bounded context and exact verification
 argument-hint: "[scope]"
 workflow-ref: "@skills/ultra-plan/SKILL.md"
 ---

package/commands/ultra-research.md

@@ -1,5 +1,5 @@
 ---
-description: Research unresolved product or architecture decisions and update the authoritative baseline specifications
+description: Build complete research evidence while presenting only one load-bearing owner decision at a time
 argument-hint: "[scope-or-question]"
 workflow-ref: "@skills/ultra-research/SKILL.md"
 ---

package/commands/ultra-think.md

@@ -1,10 +1,10 @@
 ---
-description: Analyze a consequential question with evidence, uncertainty, and proportionate stress testing
+description: Resolve a consequential question through evidence or one-decision-at-a-time alignment
 argument-hint: "[question]"
 workflow-ref: "@skills/ultra-think/SKILL.md"
 ---
 
-# Analyze a consequential question
+# Align on a consequential question
 
 Read and follow `@skills/ultra-think/SKILL.md`, treating `$ARGUMENTS` as the question to resolve.
 Treat the referenced skill as the only workflow definition.

package/docs/AGENT-CONTEXT.md

@@ -37,15 +37,15 @@ native command or skill -> MCP workflow-state operation -> .ultra/state.db
 | MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.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,
+`.ultra/state.db` is the only durable Ultra authority for baselines, changes, decisions, tasks,
+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 50 tools across
+eight families:
 
 | Family | Live tools |
 |---|---|
@@ -53,19 +53,40 @@ 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 |
+| `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, checkpoint |
+| `workflow.*` | start, get, list, step, complete |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
-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.
+Review, repository impact discovery, skill loading, and decision presentation remain
+host-native capabilities rather than fake MCP contracts. MCP stores only normalized
+decision authority and checkpoints; it never generates questions or retains prompts
+and transcripts. The generated Codex capability map documents host 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
+## 4. Human-agent alignment contract
+
+`skills/ultra-think/references/decision-dialogue.md` is the single reusable prompt
+contract for load-bearing owner choices. Research, change, and plan read it at their
+decision boundaries. They inspect evidence first, expose only the earliest unresolved
+choice, include a recommendation and durable effects, and stop the turn. Dev, test,
+review, and deliver route back to the same thread instead of deciding for the owner.
+
+One partial unique index permits only one open item per thread. `decision.resolve`,
+`decision.delegate`, and `decision.defer` preserve the source of authority;
+`decision.supersede` preserves history when evidence or intent changes. Prepare and
+confirm checkpointing bind the accepted cluster to current artifact digests before a
+matching workflow may advance. Status and breadcrumb return only the current question
+and one route, so recovery does not require replaying conversation history.
+
+## 5. 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%
@@ -88,7 +109,7 @@ through approve/reject/apply transitions in `change.learning_resolve`. Unresolve
 learning blocks convergence. Review contributes two independent axes,
 `spec_fidelity` and `engineering_standards`; neither can replace the other.
 
-## 5. Native host presentation
+## 6. Native host presentation
 
 | Host | Plugin form | Workflow entry | Hook form | Collaboration companions |
 |---|---|---|---|---|
@@ -101,7 +122,7 @@ The current host remains primary. Collaboration skills call another runtime
 only when explicitly requested, use it as a read-only advisor, and return the
 evidence to the primary host for final verification.
 
-## 6. Hook boundary
+## 7. Hook boundary
 
 The canonical Python hook bundle contains seven executable workflow hooks plus
 the shared read-only `context_spine.py` breadcrumb helper:
@@ -111,7 +132,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
@@ -128,7 +150,7 @@ reject an edit, stop, or tool call.
 Generic command blocking, post-edit governance, and unrelated user hooks are not
 copied into Ultra Builder Pro.
 
-## 7. Memory boundary
+## 8. Memory boundary
 
 Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
 transcript capture, observation journal, or session-summary hook. Persistent
@@ -146,7 +168,7 @@ ultra-tools legacy-memory prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
 Archive before prune; the confirmation token is intentionally required.
 
-## 8. Project state layout
+## 9. Project state layout
 
 ```text
 .ultra/
@@ -159,12 +181,14 @@ 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
+## 10. User handbook integration
 
 General engineering doctrine remains user-owned in `CLAUDE.md` or `AGENTS.md`.
 Ultra Builder Pro contributes one managed section only. Preview or apply it with:
@@ -179,7 +203,7 @@ timestamped backup, replaces only the marked block, and can migrate the old
 Codex `## Ultra Builder Pro Runtime Contract` section without touching the next
 user section. Plugin adapters themselves do not silently overwrite handbooks.
 
-## 10. Verification
+## 11. Verification
 
 Run `npm run test:all`, `python3 -m pytest hooks/tests -q`, and `npm audit`.
 Adapter tests assert the allowlisted assets, native manifests, hook boundary,