ultra-builder-pro-cli 0.21.1 → 0.22.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
 
@@ -87,10 +89,33 @@ resolve the mount/runtime constraint before retrying.
 | `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 `task.ledger_publish` may derive `.ultra/tasks/tasks.json` from SQLite, and only
+`task.ledger_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

@@ -12,10 +12,11 @@ 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 |
+| `.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
@@ -76,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/.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.
@@ -226,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` |
+| `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
@@ -361,8 +381,12 @@ 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.

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) {
@@ -950,7 +951,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 +1079,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;

package/mcp-server/lib/baseline-workflow.cjs

@@ -59,6 +59,49 @@ function gitBranch(rootDir) {
   return result.status === 0 ? (result.stdout.trim() || null) : null;
 }
 
+function gitCommitIsAncestor(rootDir, ancestor, descendant) {
+  if (!ancestor || !descendant) return false;
+  const result = spawnSync(
+    'git', ['merge-base', '--is-ancestor', ancestor, descendant],
+    { cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  return result.status === 0;
+}
+
+function hashScopedWorkingTree(rootDir, relativePaths) {
+  const root = path.resolve(rootDir);
+  const digest = crypto.createHash('sha256');
+  for (const relative of [...new Set(relativePaths)].sort()) {
+    const file = path.resolve(root, relative);
+    if (file !== root && !file.startsWith(`${root}${path.sep}`)) {
+      throw new BaselineWorkflowError(
+        'BASELINE_SCOPE_INVALID',
+        `Git returned a path outside the repository: ${relative}`,
+      );
+    }
+    digest.update(relative).update('\0');
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) {
+      digest.update('missing\0');
+    } else if (stat.isSymbolicLink()) {
+      digest.update('symlink\0').update(fs.readlinkSync(file)).update('\0');
+    } else if (stat.isFile()) {
+      digest.update(stat.mode & 0o111 ? 'file+x\0' : 'file\0');
+      digest.update(fs.readFileSync(file)).update('\0');
+    } else if (stat.isDirectory()) {
+      const submoduleHead = spawnSync('git', ['-C', file, 'rev-parse', 'HEAD'], {
+        cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      digest.update('directory\0');
+      if (submoduleHead.status === 0) digest.update(submoduleHead.stdout.trim());
+      digest.update('\0');
+    } else {
+      digest.update(`special:${stat.mode}\0`);
+    }
+  }
+  return digest.digest('hex');
+}
+
 function gitWorktreeSnapshot(rootDir, scope = ['.']) {
   const repositoryRoot = gitRepositoryRoot(rootDir);
   if (!repositoryRoot) {
@@ -76,40 +119,24 @@ function gitWorktreeSnapshot(rootDir, scope = ['.']) {
     'git', ['status', '--porcelain=v1', '-z', '--untracked-files=all', ...args],
     { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
   );
-  const diff = head
-    ? spawnSync(
-      'git', ['diff', '--binary', '--no-ext-diff', 'HEAD', ...args],
-      { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
-    )
-    : { status: 0, stdout: Buffer.alloc(0) };
-  const untracked = spawnSync(
-    'git', ['ls-files', '--others', '--exclude-standard', '-z', ...args],
+  const inventory = spawnSync(
+    'git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z',
+      '--', ...pathspecs, ':(exclude).ultra', ':(exclude).ultra/**'],
     { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
   );
-  if (status.status !== 0 || diff.status !== 0 || untracked.status !== 0) {
+  if (status.status !== 0 || inventory.status !== 0) {
     return {
       head, branch: gitBranch(rootDir), state: 'unavailable', digest: null, files: [],
     };
   }
   const statusText = status.stdout.toString('utf8');
   const files = statusText.split('\0').filter(Boolean);
-  const digest = crypto.createHash('sha256');
-  digest.update(head || 'unborn').update('\0').update(gitBranch(rootDir) || '').update('\0');
-  digest.update(status.stdout).update(diff.stdout);
-  for (const relative of untracked.stdout.toString('utf8').split('\0').filter(Boolean).sort()) {
-    digest.update(relative).update('\0');
-    const file = path.resolve(rootDir, relative);
-    if (file.startsWith(`${path.resolve(rootDir)}${path.sep}`)
-      && fs.existsSync(file) && fs.statSync(file).isFile()) {
-      digest.update(fs.readFileSync(file));
-    }
-    digest.update('\0');
-  }
+  const scopedFiles = inventory.stdout.toString('utf8').split('\0').filter(Boolean);
   return {
     head,
     branch: gitBranch(rootDir),
     state: head ? (files.length > 0 ? 'dirty' : 'clean') : 'unborn',
-    digest: digest.digest('hex'),
+    digest: hashScopedWorkingTree(rootDir, scopedFiles),
     files,
   };
 }
@@ -741,7 +768,12 @@ function convergenceBlockers(db, baseline, input, rootDir) {
   else if (baseline.repository_revision !== expected) blockers.add('BASELINE_REVISION_MISMATCH');
   const snapshot = gitWorktreeSnapshot(rootDir, baseline.scope);
   if (snapshot.state === 'unborn') blockers.add('BASELINE_GIT_HEAD_REQUIRED');
-  if (snapshot.head && expected && snapshot.head !== expected) blockers.add('BASELINE_HEAD_STALE');
+  if (snapshot.head && expected && snapshot.head !== expected
+      && (!gitCommitIsAncestor(rootDir, expected, snapshot.head)
+        || (baseline.worktree_digest && snapshot.digest
+          && baseline.worktree_digest !== snapshot.digest))) {
+    blockers.add('BASELINE_HEAD_STALE');
+  }
   if (baseline.repository_branch && snapshot.branch
     && baseline.repository_branch !== snapshot.branch) blockers.add('BASELINE_BRANCH_STALE');
   if (!Array.isArray(baseline.scope) || baseline.scope.length === 0) blockers.add('BASELINE_SCOPE_MISSING');
@@ -857,7 +889,11 @@ function inspectBaseline(db, { rootDir = process.cwd(), id } = {}) {
     blockers.push('BASELINE_GIT_HEAD_REQUIRED');
   }
   if (snapshot.head && baseline.repository_revision && snapshot.head !== baseline.repository_revision) {
-    blockers.push('BASELINE_HEAD_STALE');
+    if (!gitCommitIsAncestor(rootDir, baseline.repository_revision, snapshot.head)
+        || (baseline.worktree_digest && snapshot.digest
+          && baseline.worktree_digest !== snapshot.digest)) {
+      blockers.push('BASELINE_HEAD_STALE');
+    }
   } else if (!snapshot.head && baseline.repository_revision?.startsWith('workspace:')) {
     const revision = workspaceRevision({
       scope: baseline.scope, specs: baseline.spec_refs, evidence: baseline.evidence,

package/mcp-server/lib/context-paths.cjs

@@ -3,7 +3,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const CONTEXT_ROOT_RELATIVE = '.ultra/tasks/contexts';
+const CONTEXT_ROOT_RELATIVE = '.ultra/.runtime/projections/contexts';
+const LEGACY_CONTEXT_ROOT_RELATIVE = '.ultra/tasks/contexts';
 const GENERATED_BY = 'ultra-projector';
 
 class ContextPathError extends Error {
@@ -77,9 +78,12 @@ function resolveContextPath(rootDir, value, {
   if (raw.split('/').includes('..')) invalid(original, 'parent traversal is not allowed');
 
   if (allowLegacyAliases && raw.startsWith('contexts/')) {
-    raw = `.ultra/tasks/${raw}`;
+    raw = `${LEGACY_CONTEXT_ROOT_RELATIVE}/${raw.slice('contexts/'.length)}`;
   } else if (allowLegacyAliases && !raw.includes('/')) {
-    raw = `${CONTEXT_ROOT_RELATIVE}/${raw}`;
+    raw = `${LEGACY_CONTEXT_ROOT_RELATIVE}/${raw}`;
+  }
+  if (raw.startsWith(`${LEGACY_CONTEXT_ROOT_RELATIVE}/`)) {
+    raw = `${CONTEXT_ROOT_RELATIVE}/${raw.slice(LEGACY_CONTEXT_ROOT_RELATIVE.length + 1)}`;
   }
 
   const relative = path.posix.normalize(raw);
@@ -98,14 +102,41 @@ function resolveContextPath(rootDir, value, {
   return { root, contextRoot, relative, file };
 }
 
+function resolveLegacyContextPath(rootDir, value, { taskId } = {}) {
+  const root = path.resolve(rootDir || '.');
+  const original = value || `${LEGACY_CONTEXT_ROOT_RELATIVE}/task-${taskId}.md`;
+  if (typeof original !== 'string' || original.trim() === '' || original.includes('\0')) {
+    invalid(original, 'a non-empty legacy path is required');
+  }
+  if (path.isAbsolute(original)) invalid(original, 'legacy paths must be project-relative');
+  const raw = original.trim().replaceAll('\\', '/').replace(/^\.\//, '');
+  if (raw.split('/').includes('..')) invalid(original, 'parent traversal is not allowed');
+  const relative = path.posix.normalize(raw);
+  if (!relative.startsWith(`${LEGACY_CONTEXT_ROOT_RELATIVE}/`)
+      || relative === `${LEGACY_CONTEXT_ROOT_RELATIVE}/`
+      || relative.endsWith('/')) {
+    invalid(original, `legacy path must be a file below ${LEGACY_CONTEXT_ROOT_RELATIVE}`);
+  }
+  const file = path.resolve(root, ...relative.split('/'));
+  const contextRoot = path.resolve(root, ...LEGACY_CONTEXT_ROOT_RELATIVE.split('/'));
+  if (!file.startsWith(`${contextRoot}${path.sep}`)) {
+    invalid(original, `legacy path escapes ${LEGACY_CONTEXT_ROOT_RELATIVE}`);
+  }
+  assertNoSymlinkAncestors(root, relative, original);
+  assertRealContainment(root, file, original);
+  return { root, contextRoot, relative, file };
+}
+
 function isGeneratedContextContents(contents) {
   return new RegExp(`^generated_by:\\s*${GENERATED_BY}\\s*$`, 'm').test(String(contents));
 }
 
 module.exports = {
   CONTEXT_ROOT_RELATIVE,
+  LEGACY_CONTEXT_ROOT_RELATIVE,
   GENERATED_BY,
   ContextPathError,
   isGeneratedContextContents,
   resolveContextPath,
+  resolveLegacyContextPath,
 };