ultra-builder-pro-cli 0.20.0 → 0.22.0

package/docs/WORKFLOW-LIFECYCLE.md

@@ -11,10 +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 |
-| 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 |
+| 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` | 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 | 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
@@ -71,8 +77,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/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.
@@ -144,11 +152,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,
@@ -220,24 +229,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` |
-| `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 |
-| 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` |
-| `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 |
-| `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 |
-
-Every mutating MCP operation appends an event and enqueues projection work when
-the corresponding read-only view can change. Projection failure is recorded as
+| `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, 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, 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 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
@@ -256,26 +282,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 +320,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 +381,17 @@ 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
-  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.
 
 ## 8. Entry flows
 
@@ -347,7 +402,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 +412,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 +432,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 +447,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,24 +1,26 @@
 # 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;
-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 without intent or provider payloads |
-| Before edit | `active_task_context.py` | Protect `tasks.json` and restate the same DB-derived task 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 `.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 |
 | 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

@@ -1,30 +1,77 @@
 #!/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
 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")
+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 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()
-        if resolved == (root / TASKS_PROJECTION).resolve():
+        yield candidate.resolve() if candidate.is_absolute() else (start / candidate).resolve()
+
+
+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_managed_task_file(data: dict, root: Path) -> bool:
+    for resolved in tool_paths(data, root):
+        if any(resolved == (root / relative).resolve() for relative in PROTECTED_TASK_FILES):
             return True
     return False
 
 
+def managed_file_denial(reason: str) -> dict:
+    return {"hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": reason,
+    }}
+
+
+def conflicted_managed_root(data: dict, start: Path) -> Path | None:
+    for candidate in (start, *start.parents):
+        if not (candidate / ".ultra").exists():
+            continue
+        if targets_managed_task_file(data, candidate):
+            return candidate
+    return None
+
+
+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 = protected_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 +79,60 @@ 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 managed_roots(data, start):
+        try:
+            target_authority = find_root(target_root)
+        except ContextSpineError as exc:
+            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 retrying the owning "
+                "MCP operation."
+            )))
+            return
+        if target_authority is None:
+            continue
+        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:
+        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 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 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({"hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": (
-                "Refusing a direct write to the .ultra/tasks/tasks.json projection. "
-                ".ultra/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:
         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:

package/hooks/health_check.py

@@ -6,7 +6,8 @@ import sqlite3
 import sys
 from pathlib import Path
 
-from context_spine import ContextSpineError, find_root, read_breadcrumb
+from context_spine import ContextSpineError, find_root_for_hook, read_breadcrumb
+from runtime_paths import state_db_path
 
 
 REQUIRED_TABLES = {
@@ -44,7 +45,7 @@ def has_active_workflow(db_path: Path) -> bool:
 
 
 def inspect(root: Path) -> dict:
-    db_path = root / ".ultra" / "state.db"
+    db_path = state_db_path(root)
     report = {"status": "healthy", "project": str(root), "checks": {}}
     issues = []
     if not db_path.is_file():
@@ -183,11 +184,11 @@ def inspect(root: Path) -> dict:
 def main() -> None:
     data = hook_input()
     start = Path(data.get("cwd") or Path.cwd()).resolve()
-    root = find_root(start)
+    root = find_root_for_hook(start, "health_check")
     if root is None:
         print(json.dumps({}))
         return
-    if not has_active_workflow(root / ".ultra" / "state.db"):
+    if not has_active_workflow(state_db_path(root)):
         print(json.dumps({}))
         return
     report = inspect(root)

package/hooks/pre_stop_check.py

@@ -5,7 +5,7 @@ import json
 import sys
 from pathlib import Path
 
-from context_spine import ContextSpineError, find_root, read_breadcrumb
+from context_spine import ContextSpineError, find_root_for_hook, read_breadcrumb
 
 
 def allow_stop() -> None:
@@ -24,7 +24,10 @@ def main() -> None:
     if hook_data.get("stop_hook_active", False):
         allow_stop()
         return
-    root = find_root(Path(hook_data.get("cwd") or Path.cwd()).resolve())
+    root = find_root_for_hook(
+        Path(hook_data.get("cwd") or Path.cwd()).resolve(),
+        "pre_stop_check",
+    )
     if root is None:
         allow_stop()
         return