ultra-builder-pro-cli 0.21.1 → 0.23.0

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

@@ -3,12 +3,14 @@
 > Multi-process access contract. Current authority is defined by
 > [`DECISIONS.md`](./DECISIONS.md) and the live database schema.
 
-`.ultra/.runtime/state.db` is the only lifecycle, index, transition, freshness, and
-coordination authority for baselines, changes, decision threads/items, tasks,
+`.ultra/.runtime/state.db` is the checkout-local 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.
+bodies; the DB owns their references and current digests. The tracked
+`.ultra/tasks/tasks.json` is an MCP-published handoff checkpoint, not a parallel live
+writer. Every process that touches the DB must follow the rules below; deviations are
+bugs.
 
 ## 1. Three-role write matrix
 
@@ -24,7 +26,7 @@ that touches it must follow the rules below; deviations are bugs.
   but never `UPDATE` / `DELETE`.
 
 The CLI may indirectly mutate ordinary workflow tables by spawning the MCP server over
-stdio and calling `task.update`, `session.spawn`, etc. — but the actual
+stdio and calling the public `ultra.*` kernel — but the actual
 SQLite write is performed by the MCP server's writer connection. The documented
 exceptions are initial schema/baseline creation, migration, and explicitly
 authorized backup-first doctor recovery. The CLI never provides a parallel raw
@@ -34,8 +36,8 @@ The append-only carve-out for `events` exists because `events.id INTEGER
 PRIMARY KEY AUTOINCREMENT` makes concurrent inserts collision-free under
 WAL + `busy_timeout`. This lets hooks and short-lived CLI invocations
 record audit observations without paying the cost of a full MCP round trip.
-It does not grant lifecycle authority: external writers and public
-`task.append_event` use the published observation allowlist, while lifecycle event
+It does not grant lifecycle authority: external writers use the published observation
+allowlist, while lifecycle event
 names are emitted only inside the mutation that owns the corresponding state change.
 Consumers must verify mutable rows rather than infer success from an event name.
 
@@ -72,25 +74,48 @@ resolve the mount/runtime constraint before retrying.
 
 | Table              | Writer of record                                      |
 |--------------------|--------------------------------------------------------|
-| `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`); 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`, `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 |
+| `baselines`        | MCP server through `ultra.record`, `ultra.checkpoint`, and `ultra.archive`; initialization and legacy migration may create only the first draft or compatibility row |
+| `tasks`            | MCP server through `ultra.record`, `ultra.checkpoint`, and `ultra.sync` |
+| `changes`          | MCP server through `ultra.record`, `ultra.checkpoint`, and `ultra.archive` |
+| `decision_threads`, `decision_items` | MCP server through `ultra.record`; normalized accepted intent and applied references are stored, never UI receipts, prompts, or transcripts |
+| `workflow_runs`, `workflow_steps` | MCP server internally through `ultra.checkpoint`; Skills supply semantic evidence but never drive individual rows |
+| `artifacts`, `artifact_edges` | MCP server through `ultra.record` and checkpoint-owned registration |
+| `context_snapshots`, `spec_learning_candidates`, `trace_links` | MCP server through `ultra.record` and `ultra.checkpoint` |
 | `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 |
+| `events`           | MCP server for lifecycle events; approved processes and `ultra.record` for allowlisted append-only observations |
+| `sessions`         | MCP server through `ultra.session`; orchestrator may write status transitions |
 | `telemetry`        | MCP server (collected from tool-call wrappers); orchestrator may dump bulk samples |
 | `specs_refs`       | MCP server (rebuilt on `spec_changed` event); orchestrator may rebuild |
 | `migration_history`| schema initializer and `ultra-tools migrate` or doctor repair |
 | `schema_version`   | schema initializer, `ultra-tools db init`, migration, and doctor repair |
 
-## 5. Forbidden patterns
+## 5. Git team checkpoint
+
+Only `ultra.sync { action: publish }` may derive `.ultra/tasks/tasks.json` from SQLite,
+and only `ultra.sync { action: import }` may merge it into SQLite. Server startup performs one import after
+opening project authority; later pulls in a long-running process require an explicit
+import. The same checkpoint is idempotent and must not append an event again.
+
+The checkpoint carries portable baseline, Change, and durable task records with
+per-record revisions and digests. It excludes local `in_progress` ownership, sessions,
+leases, worktrees, telemetry, and completion commit hashes. Import validates document
+ancestry plus record-level common bases. It fast-forwards clean records and fails
+before commit on same-record concurrency, parent/owner gaps, non-descendant history, or
+an active-task collision. A Git-ready baseline is downgraded to checkout-local
+revalidation rather than trusted as execution authority.
+
+Legacy v4.4/v4.5 task projections are backed up and replaced only when every available
+durable field matches current SQLite. Doctor reports checkpoint condition but never
+performs semantic import, publication, or conflict selection.
+
+## 6. Forbidden patterns
 
 - **No file copies for state.** Don't `cp .ultra/.runtime/state.db
   somewhere/state.db` and edit; use `ultra-tools db backup`.
+- **No direct checkpoint edits.** Don't merge or repair
+  `.ultra/tasks/tasks.json` by hand; use the typed import/publish conflict path.
+- **No committed live projections.** `.ultra/.runtime/projections/**` remains ignored
+  checkout-local output.
 - **No long-held writer connections** outside the MCP server. Pop a
   short transaction, finish, close.
 - **No `PRAGMA journal_mode` toggling at runtime** by any process other
@@ -100,14 +125,14 @@ resolve the mount/runtime constraint before retrying.
 - **No `vacuum` / `wal_checkpoint(TRUNCATE)` from inside a transaction.**
   Maintenance subcommands open their own connection.
 
-## 6. Maintenance windows
+## 7. Maintenance windows
 
 `ultra-tools db checkpoint` and `ultra-tools db vacuum` are safe to run
 while the MCP server is up (they take their own connection and obey the
 busy timeout). `db backup` uses better-sqlite3's online `.backup` API
 and produces a consistent snapshot without blocking writers.
 
-## 7. Verification
+## 8. Verification
 
 The contract on this page is enforced by:
 
@@ -119,3 +144,6 @@ The contract on this page is enforced by:
   status transitions, task contracts, and event coupling.
 - `mcp-server/lib/workflow-state.test.cjs` — ordered workflow transitions,
   evidence/output requirements, blocking/resume, and cross-stage gates.
+- `mcp-server/lib/task-ledger.test.cjs` — portable-field filtering, digest ancestry,
+  idempotent import, baseline/Change/task fast-forward and conflict behavior, legacy
+  backup, and active-session protection.

package/docs/WORKFLOW-LIFECYCLE.md

@@ -11,29 +11,33 @@ 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, 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 |
+| MCP | Durable checkpoints, task contracts, evidence references, output hashes, team sync, leases, archives, and mechanical recovery | Semantic route selection, research prose, code generation, general memory-provider payloads, or model calls |
+| `.ultra/.runtime/state.db` | Checkout-local 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 |
+| `.ultra/tasks/tasks.json` | MCP-published Git checkpoint for portable baseline, Change, task-contract, dependency, and durable status records | Live sessions, leases, `in_progress` ownership, completion hashes, or a parallel write API |
 | 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 |
+| Generated projections and scratch | Checkout-local views below `.ultra/.runtime/` and temporary working material | Lifecycle, semantic, or evidence authority before supported promotion |
+| Hook | Compact DB-derived lifecycle observation, minimal event metadata, and protection of MCP-owned checkpoint/projection paths | 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
-public seam, verification command, context references, workflow summary, gate
-verdict, output digest, or transition validity. A host recommendation is never stored
-as MCP authority.
+Model input can supply facts, content paths, reasons, owner decisions, and evidence
+references. `ultra.record` stores mutable typed drafts and `ultra.checkpoint` attempts
+one durable semantic commit. A semantic rejection returns diagnostics and keeps the
+draft editable. Model input cannot override a task's public seam, evidence digest, or
+accepted checkpoint. A host recommendation is never stored as MCP authority.
 
-Load-bearing owner choices are normalized through `decision.*`; Prompt prose is not
-durable authority. The host acquires observable facts autonomously, exposes one
-current question, and stops. A workflow cannot advance while a matching decision has
-an unanswered blocking question, a blocking deferral, a prepared checkpoint awaiting
-confirmation, or a stale confirmed artifact. A normalized answer alone does not require
-a ceremonial checkpoint.
+Load-bearing owner choices are normalized through `ultra.record`; prompt prose is not
+durable authority. The host acquires observable facts autonomously, exposes one current
+question, and stops. Unanswered material choices remain warnings or checkpoint
+diagnostics until a capability truly needs their result. A normalized answer alone
+does not require a ceremonial checkpoint.
+
+Every host discovers seven public MCP tools: `ultra.context`, `ultra.record`,
+`ultra.checkpoint`, `ultra.sync`, `ultra.session`, `ultra.archive`, and
+`ultra.doctor`. The 0.22 fine-grained operations documented below remain hidden
+compatibility internals for one release. Skills must not drive them one call at a time.
 
 Every change-bound research, plan, dev, test, review, and deliver run inherits
 the baseline id from the owning change workflow. A Prompt cannot switch that
@@ -76,8 +80,10 @@ 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/.runtime/state.db`, installs only the required scaffold, records the
-classification, and completes an `init` workflow after read-back verification. It
+or resumes `.ultra/.runtime/state.db`, creates or imports the Git team checkpoint,
+installs only the required scaffold, records the classification, and completes an
+`init` workflow after read-back verification. A ready checkpoint baseline is held for
+checkout-local revalidation. Init
 does not create a research run. A later explicit `ultra-research` invocation selects
 `full` for greenfield or `adoption` for brownfield, records coverage dispositions, and
 works toward baseline readiness. Empty templates are not an approved baseline.
@@ -187,8 +193,10 @@ execution failure.
 ### Workflow run and step
 
 ```text
-run:  active <-> blocked -> ready -> completed
-                              \----> cancelled
+draft: active <-> blocked <-> ready
+          |          |         |
+          +----------+---------+----> cancelled
+                              \----> completed (accepted, immutable)
 
 step: pending -> in_progress -> completed
          |            |
@@ -196,10 +204,10 @@ step: pending -> in_progress -> completed
        blocked ------> in_progress/completed
 ```
 
-Required steps execute in definition order. A step that requires evidence or an
-output cannot complete without it. When the final required step completes, the
-run becomes `ready`; `workflow.complete` revalidates the entire stage before
-making it `completed`.
+Fine-grained steps are internal evidence bookkeeping. `ultra.checkpoint` records and
+validates them in one public call. A missing output returns mutable diagnostics. Draft
+artifact changes reopen `ready` to `active`; only an accepted `completed` revision is
+immutable.
 
 ### Decision thread and item
 
@@ -226,24 +234,41 @@ 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` |
+| `init` | Baseline classification/scope, Git bootstrap state, completed init run, initialization event, empty or imported team checkpoint, projection job | DB/schema opens, scaffold/local projection/checkpoint and read-back succeed; existing Git is preserved or missing local Git is initialized; imported ready baseline is not trusted before local revalidation | 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; 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, 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` |
+| baseline convergence | Spec/source/runtime refs, verification results, known failures, unknowns, gaps, branch/HEAD/worktree, approval, and a published team checkpoint | 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, isolated Change root, typed delta, completed capture run, and portable Change checkpoint; a decision thread only when material intent remains unresolved | Intent, acceptance, recovery, classification, research disposition, exact baseline anchors, and checkpoint digest 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, deterministic `<artifact_root>/plan.json` plus `plan.md`, and published task contracts; 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, exported digests, and checkpoint generation match current authority | Any dependency-ready task may enter `dev` |
+| `dev` | Task/session transitions, real worktree, step evidence, immutable implementation context, completion/review references, and published durable task transitions | Task completed; no live session; task contract unchanged; starting context and review artifacts valid; the single completion commit is integrated and remains an ancestor of current HEAD; its hash is backfilled locally without another commit | Next task, then aggregate `test` |
 | `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 |
+| `status` | None | Reads doctor, team-checkpoint condition, 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, local projection, team-checkpoint, session, incident, archive, and install checks without choosing import/publish conflict resolution | Mechanically required recovery when unique; otherwise a set of safe recovery capabilities |
 
-Every mutating MCP operation appends an event and enqueues projection work when
-the corresponding read-only view can change. Projection failure is recorded as
+Every mutating MCP operation appends an event and enqueues local projection work when
+the corresponding checkout-local read-only view can change. Projection failure is recorded as
 a retryable incident; it does not silently convert a failed write into success.
+Semantic handoff operations separately publish the Git team checkpoint.
 `task.append_event` accepts only non-authoritative observations. Lifecycle events are
 emitted by their owning DB mutation and never act as a substitute state transition.
 
+### Team handoff checkpoint
+
+The Git checkpoint is intentionally lower-frequency than SQLite. It publishes accepted
+baseline, Change, plan, task-contract, and durable task-status boundaries; it does not
+mirror heartbeats, leases, active processes, telemetry, or provisional completion
+hashes. On MCP startup or explicit post-pull import, the receiving checkout validates
+checkpoint ancestry and record digests. Clean baseline, Change, and task records
+fast-forward independently. Concurrent edits to the same record or a remote edit to a
+locally active task stop without partial import.
+
+A checkpoint can restore portable project intent after clone, but cannot establish
+checkout truth by itself. An imported ready baseline becomes a local adoption/draft
+with `team-ledger-revalidation-required`; current scope content, HEAD, verification,
+known failures, and approval must converge again. Because baseline content hashing
+excludes `.ultra/`, committing the checkpoint cannot make its own baseline stale.
+
 ## 5. Human-agent alignment lifecycle
 
 The host first reads `decision.list` and resumes matching authority. It starts a new
@@ -295,7 +320,8 @@ opens one replacement.
 
 ## 6. Context and prompt follow-through
 
-`change.context` compiles an immutable Context Manifest v3 snapshot. It combines:
+The Context compiler used internally by `ultra.checkpoint` creates an immutable
+Context Manifest v3 snapshot. It combines:
 
 - the bound baseline/change/task identity;
 - a role and lifecycle gate;
@@ -308,11 +334,10 @@ opens one replacement.
 - optional metadata-only external memory or graph references;
 - 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.
+- readiness warnings and hard mechanical blockers without a semantic route command.
 
 Compilation is pure with respect to accepted Change authority. Provider references are
-updated only through `change.update`; they cannot be smuggled into `change.context`.
+recorded through `ultra.record`; they cannot be smuggled into a checkpoint 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
@@ -329,9 +354,9 @@ Critical stage workflows bind a matching snapshot as a durable output:
 | `deliver` | `check` | `convergence` |
 
 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`.
+digest are carried into plan, test, review, and delivery artifacts. The Plan
+`ultra.checkpoint` writes the owning Change's `plan.json` and deterministic `plan.md`
+once, and binds the exact planning snapshot and digest to the artifact registry.
 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
@@ -361,13 +386,17 @@ 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 complete task-context files are projections. Manual edits
-  are overwritten and never repair DB authority.
+- Generated `.ultra/.runtime/projections/tasks.json` and complete runtime task-context
+  files are local projections. Manual edits are overwritten and never repair DB
+  authority.
+- `.ultra/tasks/tasks.json` is a tracked MCP checkpoint, not a local projection.
+  Its full and per-record digests reject manual edits; publish/import performs typed
+  fast-forward or conflict handling.
 - 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.
+- A rejected draft is repaired in place or explicitly abandoned. A new accepted
+  revision preserves prior accepted history and invalidates only true transitive
+  registered consumers.
 
 ## 8. Entry flows
 
@@ -435,13 +464,14 @@ evidence rather than bypassing them.
 | `ultra-doctor` | read-only diagnosis and authorized mechanical recovery | required recovery only when unique; otherwise safe alternatives |
 
 Every row permits `ultra-think` when material owner authority is missing and permits
-`ultra-doctor` when state or installed-runtime authority is unhealthy. MCP makes one
-of them required only when no safe alternative exists. Neither capability creates a
-parallel workflow or substitutes a Prompt summary for DB state.
+`ultra-doctor` when state or installed-runtime authority is unhealthy. The host model
+recommends either from current evidence; hard MCP blockers remain limited to the
+mechanical safety boundary. Neither capability creates a parallel workflow or
+substitutes a prompt summary for DB state.
 
 ## 9. Recovery and diagnosis
 
-Use `system.doctor` for project authority and
+Use `ultra.doctor` for project authority and
 `ubp --all --global --doctor` for installed host assets. Both are read-only
 unless an explicit project repair command is chosen.
 

package/hooks/README.md

@@ -1,16 +1,17 @@
 # Ultra Builder Pro workflow hooks
 
 These hooks observe only Ultra-owned state. Session health/context recognizes an initialized
-`.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.
+`.ultra/.runtime/state.db` and active continuous changes. Direct writes to the MCP-owned Git
+checkpoint and checkout-local projections remain blocked; context, compact, stop, and subagent
+lifecycle behavior is recovery-oriented and does not turn advisory workflow conditions into
+refusal gates.
 
 | Lifecycle | Hook | Purpose |
 |---|---|---|
 | 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 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 edit | `active_task_context.py` | Protect `.ultra/tasks/tasks.json` (Git team checkpoint) and `.ultra/.runtime/projections/tasks.json` (local view), then 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 |

package/hooks/active_task_context.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Protect Ultra projections and restate an active task boundary before edits."""
+"""Protect Ultra managed task files and restate the active workflow boundary."""
 
 import json
 import sys
@@ -12,7 +12,9 @@ from context_spine import (
     render_breadcrumb,
 )
 
-TASKS_PROJECTION = Path(".ultra/tasks/tasks.json")
+TEAM_TASK_LEDGER = Path(".ultra/tasks/tasks.json")
+LIVE_TASK_PROJECTION = Path(".ultra/.runtime/projections/tasks.json")
+PROTECTED_TASK_FILES = (TEAM_TASK_LEDGER, LIVE_TASK_PROJECTION)
 
 
 def tool_paths(data: dict, start: Path):
@@ -28,25 +30,24 @@ def tool_paths(data: dict, start: Path):
         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
+def protected_root_for_target(target: Path) -> Path | None:
+    """Return the project root for an exact MCP-managed task file."""
+    parts = target.parts
+    for relative in PROTECTED_TASK_FILES:
+        suffix = relative.parts
+        if len(parts) >= len(suffix) and parts[-len(suffix):] == suffix:
+            return Path(*parts[:-len(suffix)])
     return None
 
 
-def targets_tasks_projection(data: dict, root: Path) -> bool:
+def targets_managed_task_file(data: dict, root: Path) -> bool:
     for resolved in tool_paths(data, root):
-        if resolved == (root / TASKS_PROJECTION).resolve():
+        if any(resolved == (root / relative).resolve() for relative in PROTECTED_TASK_FILES):
             return True
     return False
 
 
-def projection_denial(reason: str) -> dict:
+def managed_file_denial(reason: str) -> dict:
     return {"hookSpecificOutput": {
         "hookEventName": "PreToolUse",
         "permissionDecision": "deny",
@@ -54,19 +55,19 @@ def projection_denial(reason: str) -> dict:
     }}
 
 
-def conflicted_projection_root(data: dict, start: Path) -> Path | None:
+def conflicted_managed_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):
+        if targets_managed_task_file(data, candidate):
             return candidate
     return None
 
 
-def projection_roots(data: dict, start: Path):
+def managed_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)
+        root = protected_root_for_target(target)
         if root is not None and (root / ".ultra").exists():
             yield root
 
@@ -82,23 +83,24 @@ def main() -> None:
     # 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):
+    for target_root in managed_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 "
+            print(json.dumps(managed_file_denial(
+                "Refusing a direct write to an MCP-managed Ultra task file while the "
                 f"runtime authority is conflicted: {exc}. Resolve the "
-                "state.db conflict with ultra-doctor before editing generated "
-                "project artifacts."
+                "state.db conflict with ultra-doctor before retrying the owning "
+                "MCP operation."
             )))
             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."
+        print(json.dumps(managed_file_denial(
+            "Refusing a direct write to an MCP-managed Ultra task file. "
+            ".ultra/tasks/tasks.json is the MCP-published team checkpoint and "
+            ".ultra/.runtime/projections/tasks.json is the checkout-local DB view. "
+            "Use the Ultra MCP task or task.ledger tools."
         )))
         return
 
@@ -110,26 +112,26 @@ def main() -> None:
             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 "
+        # known managed task file is different: an authority conflict means the
+        # hook cannot prove which DB owns the publish or projection operation.
+        if conflicted_managed_root(data, start) is not None:
+            print(json.dumps(managed_file_denial(
+                "Refusing a direct write to an MCP-managed Ultra task file while the "
                 f"runtime authority is conflicted: {exc}. Resolve the "
-                "state.db conflict with ultra-doctor before editing generated "
-                "project artifacts."
+                "state.db conflict with ultra-doctor before retrying the owning "
+                "MCP operation."
             )))
             return
         root = None
     if root is None:
         print(json.dumps({}))
         return
-    if targets_tasks_projection(data, root):
-        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."
+    if targets_managed_task_file(data, root):
+        print(json.dumps(managed_file_denial(
+                "Refusing a direct write to an MCP-managed Ultra task file. "
+                ".ultra/tasks/tasks.json is the MCP-published team checkpoint and "
+                ".ultra/.runtime/projections/tasks.json is the checkout-local DB view. "
+                "Use the Ultra MCP task or task.ledger tools."
         )))
         return
     try:

package/mcp-server/lib/artifact-registry.cjs

@@ -27,7 +27,7 @@ const STATIC_EXEMPT_PATHS = new Set([
   '.ultra/docs/research/README.md',
   '.ultra/reports/templates/delivery-report.json',
   '.ultra/reports/templates/test-report.json',
-  '.ultra/tasks/contexts/TEMPLATE.md',
+  '.ultra/templates/task-context.md',
   '.ultra/tasks/tasks.json',
   '.ultra/changes/active/.gitkeep',
   '.ultra/changes/archive/.gitkeep',
@@ -81,9 +81,10 @@ function isExemptArtifactPath(value) {
 
 function isGeneratedProjectionPath(value) {
   const relative = normalizeRelativePath(value);
-  return relative === '.ultra/tasks/contexts'
-    || relative.startsWith('.ultra/tasks/contexts/')
-    || relative === '.ultra/tasks/tasks.json';
+  return relative === '.ultra/.runtime/projections'
+    || relative.startsWith('.ultra/.runtime/projections/')
+    || relative === '.ultra/tasks/contexts'
+    || relative.startsWith('.ultra/tasks/contexts/');
 }
 
 function artifactPathError(message, details = undefined) {
@@ -504,10 +505,34 @@ function invalidateConsumersFromEndpointInTx(db, start, {
     }
     if (endpoint.type === 'workflow') {
       const row = db.prepare(
-        'SELECT metadata_json, change_id, task_id FROM workflow_runs WHERE id = ?',
+        'SELECT status, metadata_json, change_id, task_id FROM workflow_runs WHERE id = ?',
       ).get(endpoint.id);
       if (row) {
         const metadata = parseJson(row.metadata_json, {});
+        if (['active', 'blocked', 'ready'].includes(row.status)) {
+          delete metadata.authority_invalidation;
+          metadata.draft_dirty = true;
+          db.prepare(
+            `UPDATE workflow_runs
+             SET status = CASE WHEN status = 'ready' THEN 'active' ELSE status END,
+                 metadata_json = ?,
+                 updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+             WHERE id = ?`,
+          ).run(JSON.stringify(metadata), endpoint.id);
+          ops.appendEventInTx(db, {
+            type: 'workflow_draft_changed',
+            change_id: row.change_id,
+            task_id: row.task_id,
+            payload: {
+              workflow_id: endpoint.id,
+              source_type: start.type,
+              source_id: start.id,
+              reason,
+            },
+          });
+          queue.push(...outgoingEdges(db, endpoint));
+          continue;
+        }
         if (metadata.authority_invalidation?.invalidated !== true) {
           metadata.authority_invalidation = {
             invalidated: true,
@@ -950,7 +975,7 @@ function knownArtifactPaths(db) {
   }
   for (const row of db.prepare('SELECT id, context_file FROM tasks').all()) {
     known.add(normalizeRelativePath(
-      row.context_file || `.ultra/tasks/contexts/task-${row.id}.md`,
+      contextPaths.resolveContextPath('.', row.context_file, { taskId: row.id }).relative,
     ));
   }
   return known;
@@ -1078,7 +1103,7 @@ function inspectArtifactHealth(db, { rootDir = process.cwd() } = {}) {
   for (const relative of tree.files) {
     if (isExemptArtifactPath(relative) || known.has(relative)) continue;
     if (!readyBaseline && PROVISIONAL_BASELINE_SPEC_PATHS.has(relative)) continue;
-    if (relative.startsWith(`${contextPaths.CONTEXT_ROOT_RELATIVE}/`)) {
+    if (relative.startsWith(`${contextPaths.LEGACY_CONTEXT_ROOT_RELATIVE}/`)) {
       let contents;
       try {
         contents = readStableProjectFile(rootDir, relative).bytes;