ultra-builder-pro-cli 0.19.1 → 0.21.1

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
@@ -25,9 +30,10 @@ 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
-thread is active, waiting for checkpoint confirmation, or carrying a blocking
-deferral.
+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.
 
 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
@@ -37,11 +43,13 @@ it does not fabricate the missing provenance.
 
 Ultra does not select product scope or material delivery posture; those remain user
 decisions. Research references form an optional catalog, not a forced questionnaire.
-The host model selects only evidence-relevant areas and records one coverage rationale.
-MCP validates identifiers, dispositions, evidence requirements, synthesis, and at
-least one applicable semantic area. Omitted areas create no workflow step. An explicit
-`not_applicable` or accepted `deferred` row is retained only when its exclusion is
-material.
+The host model inspects evidence and recommends only relevant areas. The owner selects,
+modifies, delegates, or defers that route through the native question surface unless
+current intent already resolves it. The host records the normalized accepted coverage
+and rationale. MCP validates identifiers, dispositions, evidence requirements,
+synthesis, and at least one applicable semantic area; it does not prove the preceding
+interaction. Omitted areas create no workflow step. An explicit `not_applicable` or
+accepted `deferred` row is retained only when its exclusion is material.
 
 ## 2. How `ultra-init` classifies a repository
 
@@ -68,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
@@ -141,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,
@@ -195,33 +204,37 @@ making it `completed`.
 ### Decision thread and item
 
 ```text
-thread: active -> checkpoint_ready -> confirmed
-           ^              |
-           |--------------+  revision/supersession
+thread: active -> completed
+           |
+           +----> checkpoint_ready -> confirmed
+           ^              |              |
+           |--------------+--------------+  revision/supersession
 
 item: open -> answered | delegated | deferred | superseded
 ```
 
 A thread is bound to baseline, change, or workflow authority. A partial unique index
 allows only one `open` item per thread. Resolved items remain immutable history;
-changed evidence or intent uses `decision.supersede` and reopens the checkpoint.
-`decision.checkpoint` first freezes a normalized decision digest, then binds explicit
-owner approval to current artifact digests or a justified standalone no-artifact
-case. It never stores the conversation transcript.
+changed evidence or intent uses `decision.supersede` and reopens alignment.
+`decision.complete` closes settled normalized state without adding an approval claim.
+When an artifact-bound recovery boundary is actually needed, `decision.checkpoint`
+instead freezes a normalized decision digest and binds explicit owner approval to
+current artifact digests or a justified standalone no-artifact case. Neither path
+stores the conversation transcript.
 
 ## 4. Write and verification lifecycle
 
 | 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` | Coverage dispositions, selected step evidence, material decision checkpoints, typed semantic records with source digests, immutable reports, output paths and SHA-256 digests | Every 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 | Host selects among bounded `research`, `plan`, current `dev`, `think`, or `status` using allowed transitions |
-| `plan` | 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 |
 
@@ -249,15 +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. prepare a compact checkpoint only when a material decision cluster changes a
-   durable contract and interruption recovery needs an artifact-bound boundary.
+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 -> 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. 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
@@ -271,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
@@ -315,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
 
@@ -326,9 +375,10 @@ current gate evidence do block.
 
 ```text
 ultra-init -> Git/scaffold/authority verification -> init completed
--> explicit ultra-research -> model-selected coverage -> selected evidence work
+-> 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
 ```
 
@@ -336,9 +386,9 @@ ultra-init -> Git/scaffold/authority verification -> init completed
 
 ```text
 ultra-init -> preserve Git/classify brownfield -> init completed
--> explicit adoption research -> model-selected coverage
+-> 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
@@ -358,8 +408,9 @@ Migration preserves prior files and rows but never carries old approval forward.
 
 ```text
 ultra-status -> ultra-change intent capture
--> host chooses 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;
@@ -372,15 +423,15 @@ 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 | host selects 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 |
 | `ultra-review` | independent specification and engineering axes plus risk-selected workers | `ultra-deliver` on approval; otherwise implementation or checking |
 | `ultra-deliver` | convergence, reconciliation, local archive, and delivery evidence | `ultra-status` or the next `ultra-change`; external release is separate |
-| `ultra-status` | read-only authority and transition set | host recommendation among allowed transitions |
+| `ultra-status` | read-only authority and transition set | model recommendation; owner selection or delegation among allowed transitions |
 | `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

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:

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