ultra-builder-pro-cli 0.20.0 → 0.21.1

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -14,29 +14,29 @@ not installed.
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | Package form | `.claude-plugin` native plugin | native config bundle + JS plugin | personal `.codex-plugin` | managed `kimi.plugin.json` plugin |
-| Public entry | `/ultra-*`, `/learn` | `/ultra-*`, `/learn` | `$ultra-builder-pro:<skill>` | `/ultra-builder-pro:<command>` |
-| Public Ultra workflows | 12, model invocation disabled | 12 commands backed by private workflow assets | 12, implicit invocation disabled | 12, model invocation disabled |
+| Public entry | `/ultra-builder-pro:ultra-*` | `/ultra-*` | `$ultra-builder-pro:ultra-*` | `/ultra-builder-pro:ultra-*` |
+| Public Ultra capabilities | 11, model invocation disabled | 11 commands backed by private workflow assets | 11, implicit invocation disabled | 11, model invocation disabled |
 | Internal agent-rule skills | 4, non-user-facing | 4, non-user-facing | 4 with implicit invocation disabled | 4, consumed by review workers |
 | Collaboration companions | `codex-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` | `cc-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` |
 | Automatic workflow bootstrap | N/A | N/A | N/A | N/A |
 | External browser/deploy/framework skills | N/A | N/A | N/A | N/A |
 
-Codex converts workflows into namespaced skills and records eleven legacy
+Codex converts workflows into namespaced skills and records ten compatibility
 command mappings in `command-map.json`; `ultra-review` remains directly
-invocable as a skill. Kimi registers all twelve commands through its native
+invocable as a skill. Kimi registers all eleven commands through its native
 plugin command directory and exposes the allowlisted skills independently.
 
 ## 2. Agents and collaboration
 
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
-| Bundled review/debug workers | FULL, native Markdown agents | FULL, native agent frontmatter | FULL, nine managed TOML agents | FUNCTIONAL, nine prompt templates consumed by `Agent` / `AgentSwarm` |
+| Bundled review/debug workers | FULL, native Markdown agents | FULL, native agent frontmatter | FULL, 10 managed TOML agents | FUNCTIONAL, 10 prompt templates consumed by `Agent` / `AgentSwarm` |
 | Plugin custom-agent registration | FULL | FULL | FULL | N/A; the 0.26 manifest has no custom-agent field |
 | Native bounded delegation | native agent surface | native agent surface | native Codex subagents | native `Agent` / `AgentSwarm` |
 | Cross-host advisor | explicit and read-only | explicit and read-only | explicit and read-only | explicit and read-only |
 | Primary-agent ownership | FULL | FULL | FULL | FULL |
 
-No bundled worker owns private persistent memory. It receives current-checkout
+No bundled worker owns private conversational memory. It receives current-checkout
 evidence and bounded context from the primary host, then returns a result for
 primary verification. On Kimi, the review workflow reads the bundled worker
 template before creating the corresponding `AgentSwarm` item; the templates are
@@ -54,7 +54,7 @@ not presented as nonexistent custom agents.
 | Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | FULL, native `SubagentStart` / `SubagentStop` |
 
 Health/context, compact, stop, and subagent hooks remain silent unless
-`.ultra/state.db` proves an active, blocked, or ready workflow. Projection
+`.ultra/.runtime/state.db` proves an active, blocked, or ready workflow. Projection
 protection applies to every initialized project because generated projections
 must never become a second authority. No host receives prompt capture, transcript capture,
 observation journaling, session-summary memory, generic command blocking, or
@@ -67,16 +67,18 @@ 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 | 51 | 51 | 51 | 51 |
+| Live/declared contracts | 57 | 57 | 57 | 57 |
 | Structured user alignment | `AskUserQuestion` in interactive sessions | `question` when permission is not denied | `request_user_input` when the current mode exposes it | `AskUserQuestion` outside auto mode |
 | Greenfield/brownfield baseline adoption | FULL | FULL | FULL | FULL |
 | Context Manifest v3 / breadcrumb | FULL | FULL, same bundled read-only DB reader as every hook | FULL | FULL |
 | Approval-gated spec learning | FULL | FULL | FULL | FULL |
 | Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` | native Kimi tools and workers |
-| 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 |
+| Workflow-memory envelope | project `.ultra/` | project `.ultra/` | project `.ultra/` | project `.ultra/` |
+| Lifecycle/index authority | project `.ultra/.runtime/state.db` | project `.ultra/.runtime/state.db` | project `.ultra/.runtime/state.db` | project `.ultra/.runtime/state.db` |
+| General memory-provider API | N/A | N/A | N/A | N/A |
 
-All 51 `task.*`, `session.*`, `baseline.*`, `change.*`, `decision.*`, `workflow.*`, `system.*`, and `plan.*` operations
+All 57 `task.*`, `session.*`, `baseline.*`, `change.*`, `decision.*`,
+`workflow.*`, `artifact.*`, `system.*`, and `plan.*` operations
 registered by `mcp-server/server.cjs` are live. Review, impact discovery, skill
 loading, and user interaction remain host-native surfaces.
 
@@ -91,6 +93,15 @@ generated launcher recovers the project from the inherited `PWD`, sets
 cannot be established. On POSIX it intentionally uses `env node` because Kimi
 0.26/0.27's embedded Node ABI differs from the ABI used to install `better-sqlite3`.
 
+Archive finalization and archive-journal recovery use an adjacent, explicitly
+packaged Python 3 worker. The worker accepts only bounded, basename-only
+operations and performs mutations relative to inherited, identity-checked
+directory descriptors. This boundary requires a POSIX Python runtime with
+`dir_fd`, no-follow `stat`, and `O_NOFOLLOW` support. If that prerequisite is
+missing, archive operations fail closed with `ARCHIVE_RUNTIME_UNAVAILABLE`;
+Ultra never falls back to ancestor-sensitive pathname mutation. Other MCP
+operations remain available.
+
 ## 5. User instruction isolation
 
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
@@ -135,9 +146,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `19.0` |
+| Current state schema | `20.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, repository evidence in 12.0, durable workflows in 13.0, continuous baseline revalidation in 14.0, typed research semantics and verified reconciliation in 15.0, resumable owner-agent decision threads and workflow alignment gates in 16.0, explicit unborn-Git authority in 17.0, adaptive transitions and legacy workflow normalization in 18.0, then non-ceremonial decision completion in 19.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, typed research semantics and verified reconciliation in 15.0, resumable owner-agent decision threads and workflow alignment gates in 16.0, explicit unborn-Git authority in 17.0, adaptive transitions and legacy workflow normalization in 18.0, non-ceremonial decision completion in 19.0, then typed artifact ownership and normalized dependency edges in 20.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

@@ -1,12 +1,13 @@
-# `.ultra/state.db` access policy
+# `.ultra/.runtime/state.db` access policy
 
 > Multi-process access contract. Current authority is defined by
 > [`DECISIONS.md`](./DECISIONS.md) and the live database schema.
 
-`.ultra/state.db` is the only authoritative state store for baselines, changes,
-decision threads/items, tasks, workflow runs/steps, events, sessions, incidents,
-projections, telemetry, and spec references
-(D18, D52, D54). Every process
+`.ultra/.runtime/state.db` is the only lifecycle, index, transition, freshness, and
+coordination authority for baselines, changes, decision threads/items, tasks,
+workflow runs/steps, events, sessions, incidents, projections, telemetry, and spec
+references (D18, D52, D54). Registered digest-bound files carry semantic and evidence
+bodies; the DB owns their references and current digests. Every process
 that touches it must follow the rules below; deviations are bugs.
 
 ## 1. Three-role write matrix
@@ -64,7 +65,7 @@ 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
+concurrency model. Move `.ultra/.runtime/state.db` to storage that supports SQLite WAL or
 resolve the mount/runtime constraint before retrying.
 
 ## 4. Where each table is owned
@@ -74,9 +75,10 @@ resolve the mount/runtime constraint before retrying.
 | `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`) |
-| `decision_threads`, `decision_items` | MCP server (`decision.thread_start` / `decision.open` / `decision.resolve` / `decision.delegate` / `decision.defer` / `decision.supersede` / `decision.complete` / `decision.checkpoint`); only pending questions needed for recovery, normalized choices, lifecycle completion, and optional artifact checkpoints are stored, never prompts or transcripts |
+| `decision_threads`, `decision_items` | MCP server (`decision.thread_start` / `decision.open` / `decision.resolve` / `decision.delegate` / `decision.defer` / `decision.supersede` / `decision.complete` / `decision.checkpoint`); pending recovery state, normalized accepted intent, durable effects, typed applied references, lifecycle completion, and optional artifact checkpoints are stored, never UI receipts, prompts, or transcripts |
 | `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 |
+| `artifacts`, `artifact_edges` | MCP server (`artifact.record`); workflow-owned registration may use the same internal registry transaction |
+| `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 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 |
@@ -87,7 +89,7 @@ resolve the mount/runtime constraint before retrying.
 
 ## 5. Forbidden patterns
 
-- **No file copies for state.** Don't `cp .ultra/state.db
+- **No file copies for state.** Don't `cp .ultra/.runtime/state.db
   somewhere/state.db` and edit; use `ultra-tools db backup`.
 - **No long-held writer connections** outside the MCP server. Pop a
   short transaction, finish, close.

package/docs/WORKFLOW-LIFECYCLE.md

@@ -11,11 +11,16 @@ host and project owner. It is the operational companion to
 |---|---|---|
 | Active host and owner | Product judgment, research content, implementation, review findings, and authorization for destructive or external effects | Durable workflow status or fabricated evidence digests |
 | Skill | One reusable procedure and its evidence requirements | Project state, static product doctrine, host-specific tool fiction |
-| MCP | IDs, valid transitions, hard recovery requirements, task contracts, evidence references, output hashes, and gate verdicts | Semantic route selection, research prose, code generation, memory, or model calls |
-| `.ultra/state.db` | Baseline, change, decision, task, workflow, session, event, incident, projection, and evidence authority | Prompts, transcripts, external memory, or code-graph payloads |
-| Generated JSON and Markdown | Read-only projections and durable artifacts | Independent lifecycle authority |
+| MCP | IDs, valid transitions, hard recovery requirements, task contracts, evidence references, output hashes, and gate verdicts | Semantic route selection, research prose, code generation, general memory-provider payloads, or model calls |
+| `.ultra/.runtime/state.db` | Lifecycle, index, transition, freshness, and coordination authority for baseline, change, decision, task, workflow, session, event, incident, projection, and evidence references | Prompts, transcripts, general external-memory payloads, semantic prose, or code-graph payloads |
+| Digest-bound artifacts | Registered specification, research, Change, context, test, review, delivery, and verification bodies | Independent lifecycle state or content whose digest no longer matches |
+| Generated projections and scratch | Human-readable views and temporary working material | Lifecycle, semantic, or evidence authority before supported promotion |
 | Hook | Compact DB-derived lifecycle observation, minimal event metadata, and projection protection | Generic engineering judgment, prompt/transcript capture, parallel lifecycle logs, or arbitrary edit blocking |
 
+Together, `.ultra/` is project-local cross-session workflow memory. The detailed
+artifact classes and promotion rules live in
+[`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
+
 Prompt input can supply facts, content paths, reasons, owner decisions, and
 evidence references. MCP reads the current repository and DB, validates those
 inputs, hashes outputs, and derives status. Prompt input cannot override a task's
@@ -71,7 +76,7 @@ signals. In a monorepo, the owner selects the repository scope; baseline
 worktree digests and accepted dirty files are restricted to that scope.
 
 Classification and readiness are separate. Initialization immediately creates
-or resumes `.ultra/state.db`, installs only the required scaffold, records the
+or resumes `.ultra/.runtime/state.db`, installs only the required scaffold, records the
 classification, and completes an `init` workflow after read-back verification. It
 does not create a research run. A later explicit `ultra-research` invocation selects
 `full` for greenfield or `adoption` for brownfield, records coverage dispositions, and
@@ -144,11 +149,12 @@ traceability, slice kind, public seam, exact verification command, acceptance
 checks, context references, resolved documentation impact, owner, and valid
 dependencies.
 
-A semantic Change update marks all derived tasks stale. Clearing that marker requires
-one complete execution-contract rebind through `task.update`; a marker-only clear is
-rejected. MCP validates the resulting contract and appends
-`task_contract_reconciled` with the current Change authority digest before a new plan
-may converge.
+A semantic Change update traverses registered provenance and consumer edges and marks
+only reachable task, workflow, and artifact consumers stale. Unrelated tasks remain
+current. Clearing a task marker requires one complete execution-contract rebind through
+`task.update`; a marker-only clear is rejected. MCP validates the resulting contract
+and appends `task_contract_reconciled` with the current Change authority digest before
+a new plan may converge.
 
 A session process and a task have different status machines. Process exit zero closes
 the execution transport but leaves the task `in_progress` until development,
@@ -221,14 +227,14 @@ stores the conversation transcript.
 | Stage | Authoritative writes | Completion verification | Available continuation |
 |---|---|---|---|
 | `init` | Baseline classification/scope, Git bootstrap state, completed init run, initialization event, projection job | DB/schema opens, scaffold/projection and read-back succeed; existing Git is preserved or missing local Git is initialized | Explicitly chosen `research`, `status`, or `doctor`; an already-ready project may also enter `change` |
-| `research` | Accepted coverage dispositions, selected step evidence, normalized material decisions, optional artifact checkpoints, typed semantic records with source digests, immutable reports, output paths and SHA-256 digests | Every included coverage area is dispositioned; only executed/verified/reused areas require work evidence; synthesis binds current specifications and distillate; all material decisions and digests are current | Baseline record/convergence for initial research; bounded change research returns to its owning change |
+| `research` | Accepted coverage dispositions, selected step evidence, normalized material decisions, optional artifact checkpoints, typed semantic records with source digests, immutable reports, output paths and SHA-256 digests | Every included coverage area is dispositioned; only executed/verified/reused areas require work evidence; baseline synthesis binds current specifications and distillate, while Change synthesis stays in its overlay; all material decisions and digests are current | Baseline record/convergence for initial research; bounded Change research records its delta and returns to plan |
 | baseline convergence | Spec/source/runtime refs, verification results, known failures, unknowns, gaps, branch/HEAD/worktree, approval | Full/adoption research complete; required discovery/product/architecture refs current; revision/worktree exact; blocking gaps resolved or explicitly accepted where allowed | `change` for every initial or daily outcome |
-| `change` | Complete Change Contract, profile/risk rationale, research disposition, intent/delta artifacts, and a completed capture run; a decision thread only when material intent remains unresolved | Intent, acceptance, recovery, classification, and research disposition are complete and bound to the baseline | Model recommends; owner selects or delegates bounded `research`, `plan`, current `dev`, `think`, or `status` from allowed transitions |
-| `plan` | Accepted planning posture, selected planning evidence, complete change-owned task rows, acceptance coverage matrix, and change-bound `.ultra/execution-plan.json`; approval only for a material owner decision | Every Change acceptance id is owned by a task; trace targets, ownership, dependencies, topology, task contracts, and exported digest match current authority | Any dependency-ready task may enter `dev` |
+| `change` | Complete Change Contract, profile/risk rationale, research disposition, isolated Change root, typed delta, and a completed capture run; a decision thread only when material intent remains unresolved | Intent, acceptance, recovery, classification, research disposition, and exact baseline anchors are current | Model recommends; owner selects bounded `research` or direct `plan`; both routes converge on plan before development |
+| `plan` | Accepted planning posture, immutable `plan/planning` context, selected planning evidence, complete change-owned task rows, acceptance coverage matrix, and deterministic `<artifact_root>/plan.json` plus `plan.md`; approval only for a material owner decision | Every Change acceptance id is owned by a task; trace targets, ownership, dependencies, topology, task contracts, planning-context binding, and exported digests match current authority | Any dependency-ready task may enter `dev` |
 | `dev` | Task/session transitions, real worktree, step evidence, immutable implementation context, completion/review references | Task completed; no live session; task contract unchanged; starting context and review artifacts valid; completion commits are integrated and remain ancestors of current HEAD | Next task, then aggregate `test` |
-| `test` | Immutable checking context, an explicit risk-selected verification profile, and `.ultra/reports/tests/<workflow-id>.json` | Selected dimensions and acceptance pass; every excluded dimension has a rationale; report change/task set, HEAD, worktree, context, commands, blockers, and digests agree | `review` when passing, otherwise resume `dev`/`test` |
-| `review` | Immutable review context, `task`/`change`/`plan` mode, risk-selected worker provenance, two mandatory specialist axes, and coordinated summary | Current diff/HEAD and context match; the complete worker roster is selected or skipped with rationale; completed workers match specialist artifacts; both axes complete; findings and axis verdicts derive the final verdict | `deliver` only from a passing `change` review, otherwise resume implementation or checking |
-| `deliver` | Convergence context, verified learning resolutions, semantic reconciliation manifest, local change archive, and immutable delivery report | Tasks/test/change-review are current; baseline semantic updates are anchored; archive and baseline transaction agree; the report contains no release action | Report local completion or start the next `change`; publish/deploy/push are separate explicitly authorized operations |
+| `test` | Immutable checking context, an explicit risk-selected verification profile, and `<artifact_root>/test/<workflow-id>/report.json` | Selected dimensions and exact Change acceptance ids pass; every excluded dimension has a rationale; report change/task set, HEAD, worktree, context, commands, blockers, and digests agree | `review` when passing, otherwise resume `dev`/`test` |
+| `review` | Immutable review context plus risk-selected specialist and summary artifacts below `<artifact_root>/review/<workflow-id>/` | Current diff/HEAD and context match; the complete worker roster is selected or skipped with rationale; completed workers match specialist artifacts; both axes complete; findings and axis verdicts derive the final verdict | `deliver` only from a passing `change` review, otherwise resume implementation or checking |
+| `deliver` | Convergence context, typed delta, documentation reconciliation, recoverable overlay transaction, self-contained archive, and immutable delivery report | Tasks/test/change-review and acceptance are current; every before/after digest and baseline anchor is current; the archive transaction is complete; the report contains no release action | Report local completion or start the next `change`; publish/deploy/push are separate explicitly authorized operations |
 | `status` | None | Reads doctor, baseline, workflows, breadcrumb, tasks, sessions, Git, and DB-referenced reports | Shows allowed transitions, any hard required transition, and a host-owned recommendation |
 | `doctor` | None by default; explicit repair writes only mechanical recovery state | Re-runs integrity, schema, workflow-output, projection, session, incident, archive, and install checks | Mechanically required recovery when unique; otherwise a set of safe recovery capabilities |
 
@@ -256,26 +262,31 @@ thread only for a new material decision cluster. Before asking, it must:
 6. normalize the owner response with `decision.resolve`, explicit reversible
    delegation with `decision.delegate`, or a consequence-bearing deferral with
    `decision.defer`;
-7. call `decision.complete` when normalized state is settled, or prepare a compact
+7. apply accepted intent through the owning MCP operation or digest-bound artifact;
+8. read the resulting authority back and record typed `applied_refs` when another
+   authority changed;
+9. call `decision.complete` when normalized state is settled, or prepare a compact
    checkpoint only when a material decision cluster changes a durable contract and
    interruption recovery needs an artifact-bound boundary.
 
-The shared semantic flow is `inspect -> suggest -> ask if unresolved -> normalize ->
-persist`. Claude Code and Kimi Code use `AskUserQuestion`, Codex uses
+The shared semantic flow is `inspect -> suggest -> host-native ask -> normalize ->
+persist -> apply -> read back`. The ask is skipped only when current explicit intent
+already resolves the material choice. Claude Code and Kimi Code use `AskUserQuestion`, Codex uses
 `request_user_input` when its current mode exposes it, and OpenCode uses `question`
 when permitted. Every host falls back to one concise direct question when normal
 conversation is still allowed. If the current host mode forbids interaction entirely,
 the choice remains unanswered and route-dependent writes stop. A dismissed question
 also remains unanswered. The DB trusts a normalized persisted result as current
 authority across sessions; it does not store or verify a UI receipt, raw prompt, or
-transcript.
+transcript. Breadcrumb and decision reads recall completed normalized intent, so a new
+host session can continue without replaying the dialogue.
 
 `ultra-think` owns this interaction protocol. `ultra-research`, `ultra-change`, and
 `ultra-plan` invoke it at their decision boundaries. `ultra-dev`, `ultra-test`,
 `ultra-review`, and `ultra-deliver` stop and route back to the same thread when new
 owner authority is required; they never answer on the owner's behalf. `ultra-status`
-shows only the current decision and transition set, while `ultra-doctor` diagnoses
-stale checkpoint artifacts and recovery state.
+shows current unresolved decisions, relevant accepted intent, and the transition set,
+while `ultra-doctor` diagnoses stale checkpoint artifacts and recovery state.
 
 When only a bound artifact changes, the same resolved thread is prepared and approved
 again against the current digest; this is checkpoint renewal, not a fabricated decision
@@ -289,37 +300,54 @@ opens one replacement.
 - the bound baseline/change/task identity;
 - a role and lifecycle gate;
 - DB-backed task outcome, public seam, verification command, and required refs;
+- the selected task's bounded dependency/integration neighborhood rather than every
+  unrelated task;
+- the task-context contract: purpose, why, constraints, non-goals, target seams/files,
+  pattern refs, acceptance, documentation impact, recovery, and drift definition;
 - local file hashes, current HEAD, branch, and worktree digest;
 - optional metadata-only external memory or graph references;
-- advisory file/token/context-share budgets;
+- advisory file/token/context-share budgets, including inline Change/task authority;
 - the current Change and task authority digests;
 - readiness blockers, `allowed_transitions`, and a `required_transition` only for a
   unique hard-recovery path.
 
+Compilation is pure with respect to accepted Change authority. Provider references are
+updated only through `change.update`; they cannot be smuggled into `change.context`.
+Context references retain `expected_digest`, `anchor`, `scope`, and
+`freshness_policy`. `digest` requires byte-current content, `existence` allows an
+implementation target to change while remaining present, and `advisory` reports drift
+without blocking.
+
 Critical stage workflows bind a matching snapshot as a durable output:
 
 | Workflow | Required role | Required gate |
 |---|---|---|
+| `plan` | `plan` | `planning` |
 | `dev` | `implement` | `implementation` |
 | `test` | `check` | `verification` |
 | `review` | `review` | `review` |
 | `deliver` | `check` | `convergence` |
 
-The snapshot path and digest are then carried into test, review, and delivery
-reports. This prevents a later Prompt from claiming evidence gathered under a
-different context. File and token budgets warn; they do not block legitimate
-work. Missing authority, required refs, task contracts, outputs, required owner
-decisions, or
-current gate evidence do block.
+Every lookup is exact on `change_id + task_id + role + gate`. The snapshot path and
+digest are carried into plan, test, review, and delivery artifacts. `plan.export`
+writes only the owning Change's `plan.json` and deterministic `plan.md`, and binds the
+exact planning snapshot and digest to both the artifact registry and `verify-plan`.
+The legacy global `.ultra/execution-plan.json` is read-only migration compatibility,
+not current authority. These rules prevent a later Prompt or a different role packet
+from claiming evidence gathered under another context. Referenced file content remains
+lazy; only metadata and bounded task authority are inline. File and token budgets warn;
+they do not block legitimate work. Missing authority, required refs, stale
+digest-bound refs, task contracts, outputs, required owner decisions, or current gate
+evidence do block.
 
 ## 7. Invalidation rules
 
 - Changing a task contract invalidates contexts and gates that depended on the
   former contract.
 - Changing accepted Change intent, contract, classification, research disposition,
-  provider evidence, or documentation impact marks all derived tasks stale and
-  invalidates compiled contexts. Planning or task reconciliation must explicitly
-  clear staleness before execution.
+  provider evidence, or documentation impact invalidates only transitive registered
+  consumers. Planning or task reconciliation must explicitly refresh affected
+  authority before execution.
 - Changing required source/spec content invalidates the recorded output or
   context digest.
 - Changing a research semantic source invalidates that workflow even when its immutable
@@ -333,10 +361,13 @@ current gate evidence do block.
   overwrite historical evidence.
 - `.ultra` workflow artifacts are excluded from application-worktree drift, but
   their own recorded SHA-256 digests are still authoritative.
-- Generated `tasks.json` and task-context headers are projections. Manual edits
+- Generated `tasks.json` and complete task-context files are projections. Manual edits
   are overwritten and never repair DB authority.
 - A changed checkpoint artifact digest or superseded decision invalidates the linked
   decision checkpoint and blocks matching workflow advancement until reconfirmed.
+- `workflow.revise` creates a candidate without deleting the completed prior run.
+  `workflow.supersede` promotes only a completed matching candidate, preserves both
+  histories, and invalidates only the prior run's transitive registered consumers.
 
 ## 8. Entry flows
 
@@ -347,7 +378,7 @@ ultra-init -> Git/scaffold/authority verification -> init completed
 -> explicit ultra-research -> suggested route -> owner-selected accepted coverage
 -> selected evidence work
 -> local checkpoint when Git is unborn -> baseline approval
--> ultra-change -> optional bounded research/plan -> dev -> risk-selected test/review
+-> ultra-change -> optional bounded research -> typed delta -> plan -> dev -> risk-selected test/review
 -> local deliver/archive
 ```
 
@@ -357,7 +388,7 @@ ultra-init -> Git/scaffold/authority verification -> init completed
 ultra-init -> preserve Git/classify brownfield -> init completed
 -> explicit adoption research -> suggested route -> owner-selected accepted coverage
 -> selected characterization/known-red evidence -> gap ledger -> owner approval
--> first ultra-change -> optional bounded research/plan -> dev -> test/review -> deliver
+-> first ultra-change -> optional bounded research -> typed delta -> plan -> dev -> test/review -> deliver
 ```
 
 Adoption records the system that exists. It does not force the owner to recreate
@@ -377,9 +408,9 @@ Migration preserves prior files and rows but never carries old approval forward.
 
 ```text
 ultra-status -> ultra-change intent capture
--> model recommends; owner selects or delegates bounded research, plan, current task,
-   think, or status
--> dev -> risk-selected test -> review -> deliver -> reconciled baseline
+-> model recommends; owner selects bounded research or direct plan
+-> typed delta -> plan -> dev -> risk-selected test -> review
+-> documentation reconciliation -> atomic deliver -> reconciled baseline
 ```
 
 Quick changes shorten the artifact burden only where the machine contract allows;
@@ -392,9 +423,9 @@ evidence rather than bypassing them.
 | Entry | Owns | Normal handoff |
 |---|---|---|
 | `ultra-init` | classification, scope, Git/scaffold bootstrap, and init verification | stops completed; exposes research/status/doctor and any already-valid change capability |
-| `ultra-research` | coverage disposition, selected evidence acquisition, synthesis, and material research decisions | baseline convergence or return to the owning change |
+| `ultra-research` | coverage disposition, selected evidence acquisition, synthesis, and material research decisions | baseline convergence or Change delta then plan |
 | `ultra-think` | one material owner decision or read-only diagnosis | returns to the invoking capability after any needed checkpoint |
-| `ultra-change` | outcome capture, Change Contract, risk/research routing | model recommends; owner selects or delegates research, plan, current dev work, think, or status |
+| `ultra-change` | outcome capture, Change Contract, isolated overlay, typed delta, and risk/research routing | model recommends; owner selects research or direct plan; development is never a direct handoff |
 | `ultra-plan` | task contracts, dependencies, acceptance coverage, optional material approval | any dependency-ready task through `ultra-dev` |
 | `ultra-dev` | one task/session vertical slice and focused review | next `ultra-dev` task or aggregate `ultra-test` |
 | `ultra-test` | risk-selected change acceptance and verification profile | `ultra-review` on pass, `ultra-dev`/`ultra-test` on failure |

package/hooks/README.md

@@ -1,7 +1,7 @@
 # Ultra Builder Pro workflow hooks
 
 These hooks observe only Ultra-owned state. Session health/context recognizes an initialized
-`.ultra/state.db` and active continuous changes. Direct projection writes remain blocked;
+`.ultra/.runtime/state.db` and active continuous changes. Direct projection writes remain blocked;
 context, compact, stop, and subagent lifecycle behavior is recovery-oriented and does not turn
 advisory workflow conditions into refusal gates.
 
@@ -9,16 +9,17 @@ advisory workflow conditions into refusal gates.
 |---|---|---|
 | Session start | `health_check.py` | Read-only integrity, incident, projection, session, and change-artifact checks |
 | Shared helper | `context_spine.py` | Read the latest role/gate/readiness snapshot from state.db and derive one compact breadcrumb |
-| Session start | `workflow_context.py` | Inject the DB-derived breadcrumb without intent or provider payloads |
+| Session start | `workflow_context.py` | Inject the DB-derived breadcrumb with bounded normalized accepted intent, never raw interaction or provider payloads |
 | Before edit | `active_task_context.py` | Protect `tasks.json` and restate the same DB-derived task breadcrumb |
 | Before compact | `workflow_checkpoint.py` | Validate and atomically save a minimal workflow checkpoint |
 | After compact/resume | `workflow_resume.py` | Prefer the DB breadcrumb; restore the minimal file checkpoint only when no active change owns recovery |
 | Stop | `pre_stop_check.py` | Report an incomplete workflow boundary and allow stop |
 | Subagent lifecycle | `subagent_tracker.py` | Append minimal start/stop metadata to the authoritative DB event stream |
 
-The plugin deliberately does not capture prompts, tool observations, transcripts, summaries, or
-cross-session memory or code-graph content. Generic command blocking and post-edit policy are
-user/repository governance. Persistent Memory/graph content belongs to separately installed providers.
+The plugin deliberately does not capture prompts, tool observations, transcripts, summaries, general
+conversational memory, or code-graph payloads. It does retain project-local Ultra workflow memory in
+`.ultra/`. Generic command blocking and post-edit policy are user/repository governance. General
+memory and graph content belongs to separately installed providers.
 
 `subagent_tracker.py` passes only agent id/type and the host session id to the bundled
 `hook-event.cjs` helper. The helper binds the current change/task and appends

package/hooks/active_task_context.py

@@ -5,26 +5,72 @@ import json
 import sys
 from pathlib import Path
 
-from context_spine import ContextSpineError, find_root, read_breadcrumb, render_breadcrumb
+from context_spine import (
+    ContextSpineError,
+    find_root,
+    read_breadcrumb,
+    render_breadcrumb,
+)
 
 TASKS_PROJECTION = Path(".ultra/tasks/tasks.json")
 
 
-def targets_tasks_projection(data: dict, root: Path) -> bool:
+def tool_paths(data: dict, start: Path):
+    """Yield absolute tool targets without assuming they belong to ``start``."""
     tool_input = data.get("tool_input")
     if not isinstance(tool_input, dict):
-        return False
+        return
     for key in ("file_path", "filePath", "filepath", "path"):
         value = tool_input.get(key)
         if not isinstance(value, str) or not value.strip():
             continue
         candidate = Path(value)
-        resolved = candidate.resolve() if candidate.is_absolute() else (root / candidate).resolve()
+        yield candidate.resolve() if candidate.is_absolute() else (start / candidate).resolve()
+
+
+def projection_root_for_target(target: Path) -> Path | None:
+    """Return the project root only for the exact generated tasks projection."""
+    if (
+        target.name == "tasks.json"
+        and target.parent.name == "tasks"
+        and target.parent.parent.name == ".ultra"
+    ):
+        return target.parent.parent.parent
+    return None
+
+
+def targets_tasks_projection(data: dict, root: Path) -> bool:
+    for resolved in tool_paths(data, root):
         if resolved == (root / TASKS_PROJECTION).resolve():
             return True
     return False
 
 
+def projection_denial(reason: str) -> dict:
+    return {"hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": reason,
+    }}
+
+
+def conflicted_projection_root(data: dict, start: Path) -> Path | None:
+    for candidate in (start, *start.parents):
+        if not (candidate / ".ultra").exists():
+            continue
+        if targets_tasks_projection(data, candidate):
+            return candidate
+    return None
+
+
+def projection_roots(data: dict, start: Path):
+    """Yield initialized project roots derived from every resolved tool target."""
+    for target in tool_paths(data, start):
+        root = projection_root_for_target(target)
+        if root is not None and (root / ".ultra").exists():
+            yield root
+
+
 def main() -> None:
     try:
         data = json.loads(sys.stdin.read() or "{}")
@@ -32,20 +78,59 @@ def main() -> None:
     except json.JSONDecodeError as exc:
         print(f"[active_task_context] invalid hook input: {exc}", file=sys.stderr)
         data = {}
-    root = find_root(Path(data.get("cwd") or Path.cwd()).resolve())
+    start = Path(data.get("cwd") or Path.cwd()).resolve()
+    # An absolute tool target carries its own project boundary. Resolve and
+    # protect that authority before consulting cwd, because hooks may run from
+    # a host-owned temporary directory or another repository.
+    for target_root in projection_roots(data, start):
+        try:
+            target_authority = find_root(target_root)
+        except ContextSpineError as exc:
+            print(json.dumps(projection_denial(
+                "Refusing a direct write to an Ultra projection while the "
+                f"runtime authority is conflicted: {exc}. Resolve the "
+                "state.db conflict with ultra-doctor before editing generated "
+                "project artifacts."
+            )))
+            return
+        if target_authority is None:
+            continue
+        print(json.dumps(projection_denial(
+            "Refusing a direct write to the .ultra/tasks/tasks.json projection. "
+            ".ultra/.runtime/state.db is authoritative; use the Ultra MCP task tools and "
+            "run ultra-doctor when state or projection health is degraded."
+        )))
+        return
+
+    try:
+        root = find_root(start)
+    except ContextSpineError as exc:
+        print(
+            f"[active_task_context] cannot resolve Ultra root: {exc}",
+            file=sys.stderr,
+        )
+        # Ordinary context injection remains fail-open. A direct write to a
+        # known generated projection is different: an authority conflict
+        # means the hook cannot prove which DB would regenerate that file, so
+        # allowing the write would destroy the projection boundary.
+        if conflicted_projection_root(data, start) is not None:
+            print(json.dumps(projection_denial(
+                "Refusing a direct write to an Ultra projection while the "
+                f"runtime authority is conflicted: {exc}. Resolve the "
+                "state.db conflict with ultra-doctor before editing generated "
+                "project artifacts."
+            )))
+            return
+        root = None
     if root is None:
         print(json.dumps({}))
         return
     if targets_tasks_projection(data, root):
-        print(json.dumps({"hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": (
+        print(json.dumps(projection_denial(
                 "Refusing a direct write to the .ultra/tasks/tasks.json projection. "
-                ".ultra/state.db is authoritative; use the Ultra MCP task tools and "
+                ".ultra/.runtime/state.db is authoritative; use the Ultra MCP task tools and "
                 "run ultra-doctor when state or projection health is degraded."
-            ),
-        }}))
+        )))
         return
     try:
         breadcrumb = read_breadcrumb(root)

package/hooks/context_spine.py

@@ -5,8 +5,11 @@ import json
 import os
 import shutil
 import subprocess
+import sys
 from pathlib import Path
 
+from runtime_paths import RuntimePathError, find_project_root
+
 
 class ContextSpineError(RuntimeError):
     """The canonical breadcrumb helper could not be executed or decoded."""
@@ -21,10 +24,19 @@ class Breadcrumb(dict):
 
 
 def find_root(start: Path):
-    for root in (start, *start.parents):
-        if (root / ".ultra" / "state.db").is_file():
-            return root
-    return None
+    try:
+        return find_project_root(start)
+    except RuntimePathError as exc:
+        raise ContextSpineError(str(exc)) from exc
+
+
+def find_root_for_hook(start: Path, hook_name: str):
+    """Fail open at a hook boundary while preserving path-conflict evidence."""
+    try:
+        return find_root(start)
+    except ContextSpineError as exc:
+        print(f"[{hook_name}] cannot resolve Ultra root: {exc}", file=sys.stderr)
+        return None
 
 
 def _helper_path() -> Path: