ultra-builder-pro-cli 0.19.1 → 0.21.1

package/docs/AGENT-CONTEXT.md

@@ -7,9 +7,9 @@ and Kimi Code plugins.
 
 Ultra Builder Pro owns only:
 
-- twelve public workflows: `learn`, `ultra-init`, `ultra-research`, `ultra-plan`,
-  `ultra-dev`, `ultra-test`, `ultra-review`, `ultra-deliver`, `ultra-status`, and
-  `ultra-think`, plus the daily `ultra-change` and diagnostic `ultra-doctor`;
+- eleven public capabilities: `ultra-init`, `ultra-research`, `ultra-plan`,
+  `ultra-dev`, `ultra-test`, `ultra-review`, `ultra-deliver`, `ultra-status`,
+  `ultra-think`, `ultra-change`, and `ultra-doctor`;
 - four internal agent-only rule skills: `code-review-expert`, `security-rules`,
   `integration-rules`, and `testing-rules`;
 - the host-specific collaboration companions, `ultra-verify`, and host-native
@@ -25,7 +25,7 @@ not put it in a plugin until that allowlist classifies it.
 ## 2. Three-layer architecture
 
 ```text
-native command or skill -> MCP workflow-state operation -> .ultra/state.db
+native command or skill -> MCP workflow-state operation -> .ultra/.runtime/state.db
                                       ^
                                       |
               selected CLI init / doctor / diagnostics / orchestration
@@ -34,34 +34,41 @@ native command or skill -> MCP workflow-state operation -> .ultra/state.db
 | Layer | Artifact | Contract |
 |---|---|---|
 | Skill/command | `skills/*/SKILL.md`, `commands/*.md` | Model-facing workflow and host-native entry point |
-| MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/state.db` |
+| MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/.runtime/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, 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.
+`.ultra/` is project-local cross-session workflow memory for normalized intent,
+progress, tasks, bounded context, specifications, evidence, provenance, and recovery.
+`.ultra/.runtime/state.db` is the only lifecycle, index, transition, freshness, and
+coordination authority for baselines, changes, decisions, tasks, workflow runs/steps,
+sessions, events, incidents, projection jobs/cursors, telemetry, review evidence, and
+circuit-breaker state. Registered digest-bound specifications and reports carry
+semantic or evidence bodies. `tasks.json`, generated task-context files, runtime
+checkpoints, and collaboration scratch are not independent authority. See
+[`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 50 tools across
-eight families:
+`spec/mcp-tools.yaml` declares and the bundled server registers 57 tools across
+nine families:
 
 | Family | Live tools |
 |---|---|
 | `baseline.*` | start, record, get, converge |
 | `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 |
+| `change.*` | create, update, delta, documentation_reconcile, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
+| `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, complete, checkpoint |
+| `workflow.*` | start, get, list, step, revise, supersede, complete |
+| `artifact.*` | record, get |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
 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.
+decision authority, pending-question recovery state, lifecycle completion, and optional
+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).
@@ -79,34 +86,56 @@ review, and deliver route back to the same thread instead of deciding for the ow
 
 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 a material accepted cluster to current artifact digests
-when interruption recovery needs that boundary. Status and breadcrumb return only the
-current question plus allowed and mechanically required transitions, so recovery does
-not require replaying conversation history.
+`decision.supersede` preserves history when evidence or intent changes.
+After normalization, the host applies accepted intent through the owning MCP operation
+or digest-bound artifact, reads it back, and records typed `applied_refs` when another
+authority changed. Row-backed references require the exact field and canonical value;
+specification and artifact references require the exact file digest. Active proposals
+are never recalled as accepted intent. `decision.complete` then closes settled state without manufacturing
+an approval receipt. Prepare and confirm checkpointing remain optional and bind only a
+material accepted cluster to current artifact digests when interruption recovery needs
+that boundary. Status and breadcrumb return the current unresolved question, accepted
+intent relevant to the active authority, and allowed or mechanically required
+transitions, so recovery does not require replaying conversation history.
 
 ## 5. Context Spine contract
 
 Context Manifest v3 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, Change/task authority digests, and valid
-transitions for `plan`, `implement`, `check`, or `review`. The default 12-file,
-about 12k-token, and 40%
+transitions for `plan`, `implement`, `check`, or `review`. Compilation never updates
+Change or provider authority; provider metadata changes through `change.update`.
+Snapshots are selected exactly by `change_id`, nullable `task_id`, `role`, and `gate`,
+so a review packet cannot satisfy implementation or planning evidence.
+
+Implementation packets inline only the selected task, direct dependency/integration
+neighborhood, and the restored task-context contract. Referenced file bodies remain
+lazy. The token estimate includes inline Change/task authority plus referenced-file
+estimates. Context refs preserve `expected_digest`, `anchor`, `scope`, and one of
+`digest`, `existence`, or `advisory` freshness. Current consumers revalidate these
+policies instead of trusting an old manifest.
+
+The default 12-file, about 12k-token, and 40%
 fresh-context values are attention guidance. Overflow produces warnings; it does
 not block work or require raising a threshold. Prefer direct reads, bounded
 excerpts, or a smaller slice when they preserve correctness, and retain all
 necessary context when they do not.
 
 `change.breadcrumb` is the only compact router. Hooks may inject its change/task,
-role, gate, readiness, blockers, `allowed_transitions`, and `required_transition`.
-They must not inject intent
-bodies, transcripts, external memory, or graph payloads. Missing references,
-digest drift, HEAD drift, or a missing execution seam blocks readiness. Context
+role, gate, readiness, blockers, bounded normalized accepted intent,
+`allowed_transitions`, and `required_transition`. They must not inject raw prompts,
+interaction transcripts, external-memory payloads, or graph payloads. Missing references,
+required digest drift, HEAD drift, or a missing execution seam blocks readiness. Context
 size and baseline drift are advisory for a change that is already active. New ordinary
 work requires a healthy baseline. Only an explicitly approved incident break-glass may
 start without it; incident archive records a blocking reconciliation gap. Revision and
 tracked-spec integrity are reconciled and rechecked atomically for ordinary archive.
 
+The plan workflow records a `plan/planning` manifest before design and exports only
+`<artifact_root>/plan.json` plus deterministic `plan.md`. Both bind the planning
+snapshot digest. The global `.ultra/execution-plan.json` is legacy read-only
+compatibility and must not receive new plan writes.
+
 Stable discoveries use `change.learning_propose`; they reach the baseline only
 through approve/reject/apply transitions in `change.learning_resolve`. Unresolved
 learning blocks convergence. Review contributes two independent axes,
@@ -116,10 +145,14 @@ learning blocks convergence. Review contributes two independent axes,
 
 | Host | Plugin form | Workflow entry | Hook form | Collaboration companions |
 |---|---|---|---|---|
-| Claude Code | `.claude-plugin/plugin.json`, native commands/skills/agents, `.mcp.json` | `/ultra-*`, `/learn` | native `hooks/hooks.json` | `codex-collab`, `ultra-verify` |
-| Codex | personal plugin with `.codex-plugin/plugin.json`, namespaced skills, TOML agents, `.mcp.json` | `$ultra-builder-pro:ultra-*`, `$ultra-builder-pro:learn` | native `hooks/hooks.json` through the Codex wire adapter | `cc-collab`, `ultra-verify` |
-| OpenCode | config bundle plus native JavaScript plugin | `/ultra-*`, `/learn` | `event`, system transform, compaction, and tool lifecycle handlers | `cc-collab`, `codex-collab`, `ultra-verify` |
-| Kimi Code 0.26+ | managed `kimi.plugin.json` plugin with commands, skills, hooks, and MCP | `/ultra-builder-pro:ultra-*`, `/ultra-builder-pro:learn` | native hooks through the Kimi wire adapter | `cc-collab`, `codex-collab`, `ultra-verify` |
+| Claude Code | `.claude-plugin/plugin.json`, native commands/skills/agents, `.mcp.json` | `/ultra-builder-pro:ultra-*` | native `hooks/hooks.json` | `codex-collab`, `ultra-verify` |
+| Codex | personal plugin with `.codex-plugin/plugin.json`, namespaced skills, TOML agents, `.mcp.json` | `$ultra-builder-pro:ultra-*` | native `hooks/hooks.json` through the Codex wire adapter | `cc-collab`, `ultra-verify` |
+| OpenCode | config bundle plus native JavaScript plugin | `/ultra-*` | `event`, system transform, compaction, and tool lifecycle handlers | `cc-collab`, `codex-collab`, `ultra-verify` |
+| Kimi Code 0.26+ | managed `kimi.plugin.json` plugin with commands, skills, hooks, and MCP | `/ultra-builder-pro:ultra-*` | native hooks through the Kimi wire adapter | `cc-collab`, `codex-collab`, `ultra-verify` |
+
+`spec/interaction-contract.json` carries the same exact public-capability graph for
+every host. Adapters translate the question and invocation surfaces; they never own
+semantic selection or durable state.
 
 The current host remains primary. Collaboration skills call another runtime
 only when explicitly requested, use it as a read-only advisor, and return the
@@ -153,12 +186,13 @@ reject an edit, stop, or tool call.
 Generic command blocking, post-edit governance, and unrelated user hooks are not
 copied into Ultra Builder Pro.
 
-## 8. Memory boundary
+## 8. Workflow-memory boundary
 
-Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
-transcript capture, observation journal, or session-summary hook. Persistent
-cross-session memory belongs to a separately installed provider such as
-cloud-mem/claude-mem. Code graph content is equally external. A change context
+Ultra Builder Pro has no general memory MCP family, general recall skill, prompt
+capture, transcript capture, observation journal, or session-summary hook. It does
+retain its own project-local cross-session workflow memory under `.ultra/`.
+General conversational or episodic memory belongs to a separately installed provider
+such as cloud-mem/claude-mem. Code-graph content is equally external. A change context
 may contain only provider metadata references, never provider payload content.
 
 Old Ultra data is never deleted during install. The explicit migration path is:
@@ -170,25 +204,25 @@ ultra-tools legacy-memory prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 ```
 
 Archive before prune; the confirmation token is intentionally required.
+This CLI is an operator-invoked migration cleanup surface only. Hooks, MCP, and
+sessions never call it, and it cannot collect, recall, or reflect memory.
 
 ## 9. Project state layout
 
 ```text
 .ultra/
-├── state.db                 # authoritative SQLite store
-├── runtime/
+├── .runtime/
+│   ├── state.db             # authoritative SQLite lifecycle/index store
 │   └── checkpoint.json      # advisory breadcrumb recovery projection
 ├── changes/
-│   ├── active/<id>/         # intent, delta, plan, context v3, learning, verification
+│   ├── active/<id>/         # all Change semantics and evidence
+│   │   ├── intent.md, findings.md, progress.md
+│   │   ├── research/, delta/, documentation/, plan.json, plan.md
+│   │   └── contexts/, test/, review/, delivery/
 │   └── archive/             # converged packets after baseline reconciliation
 ├── tasks/                   # projections and task contexts
 ├── specs/                   # research/product/architecture artifacts
-├── sessions/                # bounded runtime artifacts
-├── reviews/                 # immutable review evidence by session id
-└── reports/
-    ├── templates/           # blank report schemas; never evidence
-    ├── tests/<workflow-id>.json
-    └── delivery/<workflow-id>.json
+└── reports/templates/      # blank report schemas; never evidence
 ```
 
 ## 10. Plugin and user-instruction isolation

package/docs/ARCHITECTURE.md

@@ -10,10 +10,11 @@
 Ultra Builder Pro engineering loop (skills + commands + workflow hooks) as
 native Claude Code, OpenCode, Codex, and Kimi Code plugins, and
 **runs** that loop with isolated sessions sharing one authoritative state
-store (`.ultra/state.db`).
+store (`.ultra/.runtime/state.db`).
 
-It is not an agent and it is not a memory provider. It is the workflow substrate
-the supported hosts share.
+It is not an agent or a general conversational-memory provider. It is the workflow
+substrate the supported hosts share, including project-local cross-session workflow
+memory under `.ultra/`.
 
 ## 2. Three layers
 
@@ -38,20 +39,20 @@ the supported hosts share.
                └────────────┬───────┴──────────────────┘
                             ▼
                   ┌─────────────────────┐
-                  │   .ultra/state.db   │
-                  │  (SQLite + WAL)     │  ← single authoritative store
+                  │   .ultra/.runtime/state.db   │
+                  │  (SQLite + WAL)     │  ← lifecycle + index authority
                   └──────────┬──────────┘
                              │ projector (Phase 2.6)
                              ▼
               .ultra/tasks/tasks.json     (read-only view)
-              .ultra/tasks/contexts/*.md  (read-only header)
+              .ultra/tasks/contexts/*.md  (fully generated read-only view)
               .ultra/activity-log.json    (optional dump)
 ```
 
 | 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, decision, and Context Spine API | stdio MCP server exposing 50 live tools across task/session/baseline/change/decision/workflow/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
+| **MCP**      | authoritative workflow-state, decision, artifact, and Context Spine API | stdio MCP server exposing 57 live tools across task/session/baseline/change/decision/workflow/artifact/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
@@ -64,10 +65,19 @@ The skill layer is **read-only by design** (D29) and is discovered directly by
 each host. Ultra exposes no `skill.*` MCP family: skills are documentation, not
 RPC, and host-native loaders own resolution and invocation.
 
-## 3. Authoritative state — `.ultra/state.db`
+## 3. Workflow memory and authoritative state
 
-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
+Together, `.ultra/` retains project-local cross-session workflow memory:
+normalized intent, progress, tasks, bounded context, specifications, evidence,
+provenance, and recovery. `.ultra/.runtime/state.db` is the sole authority for lifecycle,
+indexing, transitions, freshness, and coordination. Registered digest-bound files
+carry semantic and evidence bodies. Generated projections and working scratch do
+not become authority merely because they live under `.ultra/`. The complete
+classification and promotion contract is
+[`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
+
+All durable Ultra lifecycle and index 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 twenty-one tables:
 
 | Table              | Holds                                             | Phase |
@@ -82,7 +92,8 @@ covers twenty-one tables:
 | `specs_refs`       | spec change tracking → staleness propagation       | 5     |
 | `circuit_breaker`  | bounded retry and halt state for failed tasks       | 5     |
 | `changes`          | continuous feature/fix/incident lifecycle, alignment-thread link, and incident baseline bypass | 12→16 |
-| `artifacts`        | intent/context/verification artifact registry       | 8C    |
+| `artifacts`        | typed semantic/evidence ownership, digest, status, and provenance | 8C→20 |
+| `artifact_edges`  | normalized source and consumer dependency graph      | 20    |
 | `context_snapshots`| role/gate context, readiness, budget, execution seam, hashes, git head, provider refs | 10 |
 | `spec_learning_candidates` | approval-gated implementation discoveries for baseline convergence | 10 |
 | `trace_links`      | task/spec/change traceability                        | 8C    |
@@ -91,21 +102,22 @@ covers twenty-one tables:
 | `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 |
-| `decision_threads` | baseline/change/workflow-bound owner-agent alignment, interaction mode, normalized summary, and checkpoint authority | 16 |
+| `decision_threads` | baseline/change/workflow-bound owner-agent alignment, interaction mode, normalized completion, and optional checkpoint authority | 16/19 |
 | `decision_items` | one-at-a-time owner choices, evidence, recommendations, durable effects, resolutions, delegation, deferral, and supersession history | 16 |
 
 Two rules make this work:
 
 1. **No double source (D32).** lease/heartbeat live only in `sessions`,
    not in a `lease.json` file. Activity log lives only in `events`, not
-   in JSON files. `tasks.json` and the status header in
-   `contexts/task-*.md` are **projections** generated by the projector;
+   in JSON files. `tasks.json` and the complete
+   `contexts/task-*.md` files are **projections** generated by the projector;
    manual edits are overwritten on the next state.db change.
 
 2. **Single writer for mutable tables, multi-writer for `events`.**
-   `.ultra/state.db` opens in WAL with `busy_timeout=5000`. The MCP
+   `.ultra/.runtime/state.db` opens in WAL with `busy_timeout=5000`. The MCP
    server holds the single writer connection for `baselines`, `tasks`, `sessions`,
-   `changes`, `decision_threads`, `decision_items`, `workflow_runs`, `workflow_steps`, `artifacts`, `context_snapshots`,
+   `changes`, `decision_threads`, `decision_items`, `workflow_runs`, `workflow_steps`,
+   `artifacts`, `artifact_edges`, `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
@@ -123,14 +135,18 @@ Two rules make this work:
 Subscribers always pull `events.id > since_id` rather than `max(ts)`,
 because two events may share the same millisecond timestamp (D31).
 
-### Memory ownership is outside Ultra Builder Pro
+### General memory and graph ownership remain outside Ultra Builder Pro
 
 Ultra Builder Pro does not retain prompts, transcripts, tool observations,
-session summaries, or cross-session memory. It ships no `memory.*` MCP family,
-no recall skill, and no memory-capture hook. A separately installed provider
-such as cloud-mem/claude-mem owns persistent memory and its own lifecycle. The
-only related migration surface is the explicit `ultra-tools legacy-memory`
-archive/prune command for data created by older releases.
+session summaries, general conversational memory, or code-graph payloads. It ships
+no `memory.*` MCP family, general recall skill, or memory-capture hook. A separately
+installed provider such as cloud-mem/claude-mem owns general persistent memory and
+its own lifecycle. Ultra stores only bounded provider metadata references needed by
+workflow context. The only related migration surface is the explicit
+`ultra-tools legacy-memory` inspect/archive/confirmed-prune command for general memory
+data created by older releases. It is never called by a hook, MCP operation, or
+session lifecycle; it does not collect, recall, reflect, or remove Ultra workflow
+authority.
 
 ### Project baseline adoption
 
@@ -141,9 +157,13 @@ same authoritative state shape without rewriting application code.
 
 Initialization completes after local authority, classification, Git/scaffold setup,
 and read-back verification. It does not start or complete research. An explicit
-`ultra-research` invocation then records the model-selected semantic coverage and
-executes, verifies, or reuses only the evidence needed to converge the baseline.
-Omitted catalog areas create no workflow row.
+`ultra-research` invocation lets the model inspect evidence and recommend a semantic
+route. The owner selects, modifies, delegates, or defers through the host-native
+question surface unless current intent already resolves the route. The normalized
+accepted coverage is then recorded, and research executes, verifies, or reuses only
+the evidence needed to converge the baseline. Omitted catalog areas create no
+workflow row. MCP validates the stored state and evidence, not the preceding user
+interaction.
 
 Auto initialization preserves an existing Git repository and HEAD. When Git is absent,
 it initializes `main`, adds the symlink-safe `.ultra` rule to `.gitignore`, and persists
@@ -193,12 +213,16 @@ alternatives, evidence refs, and durable effects; a partial unique index guarant
 current question per thread. The host ends that turn and waits.
 
 The next response becomes a normalized owner decision, explicit reversible delegation,
-or consequence-bearing deferral. Prompts and transcripts are never persisted. A coherent
-cluster moves through prepare/confirm checkpointing, which binds an owner-approved
-decision digest to the current specification, Change Contract, alignment, or plan artifact.
-Matching workflow steps and completion fail closed until the checkpoint is confirmed.
-Supersession preserves prior history and reopens alignment instead of silently editing an
-old decision. The shared procedure lives in
+or consequence-bearing deferral. Prompts and transcripts are never persisted. The host
+applies accepted intent through the owning MCP operation or digest-bound artifact,
+reads it back, and records typed `applied_refs` when another authority changed. Routine
+settled state then closes through `decision.complete`, which is lifecycle completion
+rather than another approval. The breadcrumb recalls normalized accepted intent after
+the thread closes. Only a coherent cluster that needs an artifact-bound recovery
+boundary moves through prepare/confirm checkpointing. Matching workflow steps fail
+closed while a blocking question, blocking deferral, prepared checkpoint, or stale
+checkpoint artifact remains. Supersession preserves prior history and reopens alignment
+instead of silently editing an old decision. The shared procedure lives in
 `skills/ultra-think/references/decision-dialogue.md`; status, breadcrumb, and doctor expose
 only the current recovery surface.
 
@@ -210,10 +234,11 @@ is represented by a `changes` row and an inspectable packet:
 ```text
 active -> blocked -> active -> ready -> archived
    |                              |
-   ├─ intent + delta + plan       └─ verification + baseline reconciliation
-   ├─ linked tasks
-   ├─ immutable context snapshots (role + gate + readiness + execution seam)
-   └─ spec-learning candidates (proposed -> approved/rejected -> applied)
+   ├─ intent + adaptive research + findings
+   ├─ typed delta + documentation reconciliation + deterministic progress
+   ├─ plan + linked tasks + immutable contexts
+   ├─ Change-scoped test/review/delivery evidence
+   └─ atomic baseline apply + self-contained archive
 ```
 
 `quick`, `standard`, `major`, and `incident` kinds require different evidence,
@@ -221,6 +246,18 @@ but all require completed linked tasks, current context, declared documentation
 impact, and no open incident. Memory and graph payloads never enter Ultra;
 `context_snapshots.provider_refs_json` stores metadata references only.
 
+Baseline files are immutable while a Change is active. `change.delta` registers
+overlay payloads against exact baseline revision and specification digests.
+`change.documentation_reconcile` records exact document before/after evidence and
+consumer trace. Standard and major convergence requires both current authorities.
+`change.archive` preflights the whole write set and uses a recoverable transaction;
+only after all writes and baseline reconciliation succeed does it rebind the complete
+Change root into the archive.
+
+Workflow revisions preserve prior accepted runs. A candidate becomes current only
+through `workflow.supersede`; the artifact graph then invalidates the prior run's true
+transitive consumers without staling unrelated tasks.
+
 ### Context Spine
 
 Context Manifest v3 is the immutable handoff contract between planning,
@@ -291,7 +328,7 @@ swallowed warning. `system.doctor` is read-only by default. Explicit repair perf
 backup-first schema upgrade, archive-journal recovery, session and projection
 recovery, and regenerated projections. It cannot approve a baseline or replace a
 corrupt SQLite file silently. `system restore` accepts only a verified SQLite backup
-inside `.ultra/backups`, quarantines the corrupt authority, and rolls back on failure.
+inside `.ultra/.runtime/backups`, quarantines the corrupt authority, and rolls back on failure.
 When no valid backup exists, confirmed `system rebaseline` preserves both corrupt
 authority and the legacy task projection before creating a new brownfield adoption.
 
@@ -304,7 +341,7 @@ A **session** is the standard unit of execution across all four runtimes
 - an isolated `git worktree` created by `session.spawn`,
 - an ignored `.ultra` link from that checkout to the one central authority,
 - a lease + heartbeat row in `sessions` (D32),
-- an `artifact_dir` under `.ultra/sessions/<sid>/` for logs and scratch;
+- an `artifact_dir` under `.ultra/.runtime/sessions/<sid>/` for logs and scratch;
 - either the active host operating in that exact worktree or an explicitly configured
   worker process.
 
@@ -366,7 +403,7 @@ rejects corrupt, non-object, schema-mismatched, or terminal candidates, and
 selects the newest valid state. A newer live state wins; a newer checkpoint can
 atomically restore a missing or older live state before context is re-injected.
 The checkpoint is therefore a recovery artifact and consumer, never a second
-durable authority alongside `.ultra/state.db`.
+durable authority alongside `.ultra/.runtime/state.db`.
 
 ## 7. Installation provenance — read-only cross-host diagnosis