feat: add Git team checkpoints for Ultra state

Cause: the tracked task projection mixed checkout-local SQLite state with team handoff state, creating baseline HEAD churn and unsafe cross-checkout synchronization.

Scope: add the digest-chained baseline/Change/task ledger and MCP publish/import tools, move generated views below .ultra/.runtime, migrate matching legacy projections with backups, stabilize baseline freshness and completion commits, and align all four host adapters, Skills, schemas, templates, and documentation. Release version is 0.22.0.

Verification: npm run verify:release; npm pack --dry-run --json; repeated daemon immediate-poll regression test.

Residual risk: concurrent edits to the same durable record intentionally fail closed and require explicit reconciliation; imported ready baselines require local revalidation.

Rollback: git revert this commit, reinstall the prior published version, and restore any legacy task projection from its managed exact-byte backup if migration had already run.

Author: rocky2431

.gitignore

@@ -95,6 +95,8 @@ templates/
 !/.ultra-template/reports/
 !/.ultra-template/reports/templates/
 !/.ultra-template/reports/templates/**
+!/.ultra-template/templates/
+!/.ultra-template/templates/**
 
 # npm / build artifacts
 node_modules/

.ultra-template/tasks/contexts/TEMPLATE.md

@@ -1,6 +1,13 @@
 {
-  "schema_version": "4.5",
-  "generated_at": "1970-01-01T00:00:00.000Z",
-  "source": ".ultra/.runtime/state.db",
+  "kind": "ultra-team-task-ledger",
+  "schema_version": "1.0",
+  "generation": 0,
+  "parent_digest": null,
+  "ancestors": [],
+  "state_digest": "5bf27fb3627b711c97abf72f0aad150ba693d35bcebdd57c2d80e325f495de6d",
+  "published_at": null,
+  "reason": "scaffold",
+  "baseline": null,
+  "changes": [],
   "tasks": []
 }

.ultra-template/tasks/tasks.json

@@ -0,0 +1,19 @@
+<!-- Runtime task views are generated under .ultra/.runtime/projections/contexts/. -->
+
+# Task Context Reference
+
+Use this file only as a structure reference. Runtime task context views are generated
+from SQLite authority and must not be edited by hand. Stable specification learning
+must follow the Change workflow.
+
+## Implementation Notes
+
+- [Evidence-backed note with a source reference]
+
+## Open Questions
+
+- [Question, consequence, owner, and next evidence]
+
+## Recovery Notes
+
+- [Current safe resume point and any external prerequisite]

.ultra-template/templates/task-context.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] — 2026-07-30
+
+### Added
+
+- Added a versioned, digest-chained Git team checkpoint at
+  `.ultra/tasks/tasks.json` for portable baseline, Change, task-contract,
+  dependency, and durable task-status handoff.
+- Added `task.ledger_get`, `task.ledger_publish`, and `task.ledger_import` with
+  per-record revisions, bounded ancestry, transactional fast-forward imports,
+  and typed baseline, Change, task, deletion, and active-session conflicts.
+- Added exact-byte backup and deterministic upgrade of matching legacy v4.4
+  and v4.5 task projections during project resume.
+
+### Changed
+
+- Moved generated task and context views under
+  `.ultra/.runtime/projections/`; SQLite remains checkout-local operational
+  authority while the Git checkpoint is the narrow team handoff.
+- Updated all public workflow Skills, project templates, hooks, adapters, and
+  documentation to inspect and synchronize the team checkpoint without
+  turning hooks or host adapters into semantic authorities.
+- Made imported ready baselines require checkout-local revalidation before
+  they may publish a descendant checkpoint.
+
+### Fixed
+
+- Fixed tracked task projections creating a self-referential
+  `BASELINE_HEAD_STALE` treadmill after every Ultra operation or metadata-only
+  commit. Baseline freshness now uses scoped source content plus Git ancestry
+  while continuing to detect specification and source drift.
+- Fixed task completion requiring a second bookkeeping commit. The completion
+  SHA is now backfilled only into local SQLite and generated views after the
+  single real completion commit.
+- Fixed resume, doctor, status, and four-host install paths disagreeing about
+  legacy task projections, team checkpoints, generated views, and protected
+  files.
+- Replaced the daemon's machine-speed-dependent 500ms release assertion with a
+  bounded observable-session wait while preserving the immediate-poll
+  behavior requirement.
+
 ## [0.21.1] — 2026-07-29
 
 ### Fixed

CHANGELOG.md

@@ -43,9 +43,11 @@ Ultra Builder Pro addresses those gaps with four ideas:
 2. **Low-load user alignment.** The agent investigates observable facts itself
    and asks the user only for material intent, scope, risk, or authorization
    decisions—normally one dependent decision at a time.
-3. **Durable project authority.** `.ultra/.runtime/state.db` records baselines, changes,
-   decisions, workflows, tasks, evidence digests, sessions, incidents, and
-   recovery state across hosts and sessions.
+3. **Durable project authority.** `.ultra/.runtime/state.db` records checkout-local
+   lifecycle, decisions, workflows, evidence digests, sessions, incidents, and
+   recovery state across host sessions. Tracked semantic artifacts plus the
+   MCP-published `.ultra/tasks/tasks.json` checkpoint carry reviewed project intent
+   across Git checkouts without committing SQLite, leases, or telemetry.
 4. **Convergent delivery.** Research, plans, implementation, tests, review, and
    specification updates must agree before a change is archived.
 
@@ -69,10 +71,12 @@ flowchart TB
     end
 
     SKILLS["Eleven explicit Ultra Skills<br/>init / research / think / change / plan / dev<br/>test / review / deliver / status / doctor"]
-    MCP["Ultra MCP<br/>57 typed tools across nine families"]
+    MCP["Ultra MCP<br/>60 typed tools across nine families"]
     DB[(".ultra/.runtime/state.db<br/>SQLite lifecycle and index authority")]
+    LEDGER[".ultra/tasks/tasks.json<br/>Git team checkpoint for portable baseline, Change, and task state"]
+    VIEWS[".ultra/.runtime/projections<br/>checkout-local generated views"]
     FILES["Digest-bound .ultra artifacts<br/>specification / research / change / plan / context<br/>test / review / delivery"]
-    HOOKS["Lifecycle hooks<br/>health, breadcrumbs, recovery hints, and projection protection"]
+    HOOKS["Lifecycle hooks<br/>health, breadcrumbs, recovery hints, and managed-file protection"]
     OPS["Operational tools<br/>ubp / ultra-tools / optional orchestrator"]
     EXTERNAL["External memory and graph providers"]
 
@@ -83,6 +87,8 @@ flowchart TB
     MODEL -->|"explicit invocation"| SKILLS
     SKILLS -->|"typed operations"| MCP
     MCP <--> DB
+    MCP -->|"publish / validate / import"| LEDGER
+    MCP -->|"regenerate"| VIEWS
     MODEL -->|"writes semantic and evidence bodies"| FILES
     MCP <-->|"registers owner, digest, provenance, and freshness"| FILES
     HOOKS -->|"observes and records lifecycle events"| MCP
@@ -97,9 +103,9 @@ The responsibility split is deliberate:
 |---|---|
 | **User** | Product intent, semantic route selection, material scope and trade-offs, risk acceptance, destructive actions, publishing and deployment authorization |
 | **Host model** | Fact-finding, synthesis, research-coverage and route recommendations, reversible implementation decisions |
-| **Ultra MCP** | Durable state, evidence references, digests, freshness, locks, valid transitions and hard recovery |
+| **Ultra MCP** | Checkout-local state, evidence references, digests, freshness, locks, valid transitions, hard recovery, and Git checkpoint publish/import |
 | **Host adapter** | Native Skill discovery, user questions, tool invocation, installation, and runtime wiring |
-| **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of generated projections |
+| **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of MCP-owned checkpoint and generated projection paths |
 
 The MCP does not replace the model's judgment. A hook does not decide product
 strategy. A prompt does not become durable authority merely because it appeared
@@ -298,8 +304,11 @@ that rationale is useful. MCP validates state, evidence, and transitions; it
 does not store or prove the preceding UI interaction.
 
 Older projection-only Ultra projects are preserved and routed through a
-backup-first migration or rebaseline. Use `ultra-doctor` when initialization
-reports migration or authority damage; do not overwrite old state manually.
+backup-first migration or rebaseline. The first supported checkpoint publication
+replaces a v4.4/v4.5 task projection only when its ids and durable fields match
+SQLite, after copying its exact bytes to `.ultra/.runtime/backups/task-ledger/`.
+Use `ultra-doctor` when initialization reports migration, mismatch, or authority
+damage; do not overwrite old state manually.
 
 ### 3. Make daily changes
 
@@ -418,6 +427,7 @@ health without selecting product intent.
   .runtime/                # local mutable state; ignored by Git
     state.db               # lifecycle, index, transition, and freshness authority
     checkpoint.json        # advisory recovery projection
+    projections/           # generated local task and task-context views
     backups/               # verified migration and recovery snapshots
     collab/                # local collaboration scratch
     sessions/              # local leases and session runtime
@@ -442,17 +452,20 @@ health without selecting product intent.
   docs/research/           # baseline-only research evidence
   reports/templates/       # blank report schemas; never delivery evidence
   tasks/
-    tasks.json             # generated projection, never the authority
-    contexts/              # bounded role/task context artifacts
+    tasks.json             # MCP-published Git team checkpoint; never hand-edited
+  templates/
+    task-context.md        # authored template, not a generated task context
 ```
 
 Together, `.ultra/` is Ultra's project-local cross-session workflow memory. The
 host model writes semantic specifications and evidence through the active
 workflow. MCP records lifecycle state, references, digests, provenance, and
 accepted intent, then rejects stale or illegal transitions. The DB is the
-lifecycle and index authority; registered digest-bound files carry the semantic
-or evidence bodies that the DB references. Generated projections and working
-scratch are not authority.
+lifecycle and index authority for one checkout; registered digest-bound files carry
+the semantic or evidence bodies that the DB references. The Git checkpoint is a
+portable, digest-chained handoff of baseline, Change, and durable task records. It is
+not a second live session authority. Generated projections and working scratch are
+not authority.
 
 Ultra does not store chain-of-thought, raw prompts, transcripts, general
 conversational or episodic memory, or code-graph payloads. External memory and
@@ -461,6 +474,29 @@ references to them as workflow context. Only `.ultra/.runtime/` is ignored by
 Git: semantic and evidence artifacts can travel with the repository, while
 SQLite, leases, telemetry, and recovery scratch remain checkout-local.
 
+### Team checkpoint protocol
+
+MCP publishes `.ultra/tasks/tasks.json` at durable boundaries: baseline convergence,
+Change creation or revision, accepted plan export, durable task-contract or status
+changes, task expansion or deletion, and Change convergence or archive. The file
+contains per-record revisions and digests plus checkpoint ancestry. It excludes
+`in_progress` ownership, session ids, leases, worktrees, telemetry, and
+`completion_commit`.
+
+After a pull or on a fresh checkout, MCP validates and imports the checkpoint. Clean
+records fast-forward independently. A baseline imported as `ready` is downgraded to
+checkout-local revalidation until its scope, files, verification, and HEAD are proven
+again. Concurrent edits to the same baseline, Change, or task, a non-descendant
+checkpoint, or remote modification of an active local task fail with a typed conflict;
+Ultra never silently picks a side. Re-importing the same checkpoint is read-only, and
+an imported ready baseline cannot publish another checkpoint until local revalidation
+converges.
+
+Baseline freshness does not use the checkpoint commit as a self-referential marker.
+It combines Git ancestry with a scoped content digest that excludes `.ultra/`.
+Consequently, a commit containing only Ultra metadata does not make the baseline stale,
+while a descendant commit that changes scoped application content does.
+
 See [Artifact authority](./docs/ARTIFACT-AUTHORITY.md) for the promotion and
 evidence rules.
 
@@ -514,8 +550,11 @@ host's existing model session.
   reinstall only the degraded host.
 - **Project state is unhealthy:** invoke `ultra-doctor` or run
   `ultra-tools system doctor`. Repairs and schema migrations are backup-first.
-- **A projection disagrees with MCP:** trust `.ultra/.runtime/state.db`; do not repair
-  `tasks.json` or generated context Markdown by hand.
+- **The team checkpoint disagrees with local state:** run `ultra-status`, inspect the
+  typed ledger condition, then use the recommended `task.ledger_import` or
+  `task.ledger_publish` path. Never edit `.ultra/tasks/tasks.json` by hand.
+- **A generated view disagrees with MCP:** trust `.ultra/.runtime/state.db`; never edit
+  `.ultra/.runtime/projections/` by hand.
 - **A workflow appears blocked:** use `ultra-status` to read the exact current
   workflow, blocker, owner decision, and mechanically valid transitions.
 - **Kimi reports a native-module ABI error:** ensure an external Node.js 22+

README.md

@@ -337,7 +337,8 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-const TASKS_PROJECTION = ".ultra/tasks/tasks.json";
+const TEAM_TASK_LEDGER = ".ultra/tasks/tasks.json";
+const LIVE_TASK_PROJECTION = ".ultra/.runtime/projections/tasks.json";
 const NODE_BINARY = ${JSON.stringify(process.execPath)};
 const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url));
 const BREADCRUMB_CLI = path.resolve(
@@ -382,20 +383,28 @@ function targetPaths(tool, args) {
   return [...new Set(paths)];
 }
 
-function projectionRootForTarget(baseRoot, candidate) {
+function managedTaskRootForTarget(baseRoot, candidate) {
   const target = path.isAbsolute(candidate)
     ? path.resolve(candidate)
     : path.resolve(baseRoot, candidate);
-  if (path.basename(target) !== "tasks.json"
-      || path.basename(path.dirname(target)) !== "tasks"
-      || path.basename(path.dirname(path.dirname(target))) !== ".ultra") {
-    return null;
+  if (target === path.resolve(baseRoot, TEAM_TASK_LEDGER)
+      || target === path.resolve(baseRoot, LIVE_TASK_PROJECTION)) return baseRoot;
+  if (path.basename(target) !== "tasks.json") return null;
+  const parent = path.dirname(target);
+  if (path.basename(parent) === "tasks"
+      && path.basename(path.dirname(parent)) === ".ultra") {
+    return path.dirname(path.dirname(parent));
+  }
+  if (path.basename(parent) === "projections"
+      && path.basename(path.dirname(parent)) === ".runtime"
+      && path.basename(path.dirname(path.dirname(parent))) === ".ultra") {
+    return path.dirname(path.dirname(path.dirname(parent)));
   }
-  return path.dirname(path.dirname(path.dirname(target)));
+  return null;
 }
 
-function protectsTasksProjection(baseRoot, candidate) {
-  const targetRoot = projectionRootForTarget(baseRoot, candidate);
+function protectsManagedTaskFile(baseRoot, candidate) {
+  const targetRoot = managedTaskRootForTarget(baseRoot, candidate);
   if (!targetRoot) return false;
   return Boolean(readUltraContext(targetRoot));
 }
@@ -421,11 +430,13 @@ export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
       const tool = String(input?.tool ?? "").toLowerCase();
       if (!["write", "edit", "apply_patch"].includes(tool)) return;
       if (targetPaths(tool, output?.args).some(
-        (candidate) => protectsTasksProjection(root, candidate),
+        (candidate) => protectsManagedTaskFile(root, candidate),
       )) {
         throw new Error(
-          "Ultra Builder Pro refused a direct write to .ultra/tasks/tasks.json. " +
-          ".ultra/.runtime/state.db is authoritative; use MCP task tools and run ultra-doctor when state or projection health is degraded."
+          "Ultra Builder Pro refused a direct write to an MCP-managed 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."
         );
       }
     },

adapters/opencode.js

@@ -107,7 +107,10 @@ test('Claude plugin collaboration workflows are safe native plugin assets', () =
     assert.match(review, /scripts\/review_wait\.py/);
     assert.doesNotMatch(plan, /LEGACY_STATE_MIGRATION_REQUIRED|v4\.4|v4\.5/);
     assert.match(plan, /Never read or\s+write .*tasks\.json/i);
-    assert.match(status, /Never fall\s+back to generated task JSON/i);
+    assert.match(
+      status,
+      /Never fall\s+back to the Git team checkpoint,\s+generated task\s+JSON/i,
+    );
     assert.doesNotMatch(plan, /ultra-tools task create/);
 
     for (const name of skillsForRuntime('claude')) {

adapters/tests/claude.test.cjs

@@ -129,10 +129,7 @@ test('Codex hook adapter denies apply_patch writes to tasks.json after Ultra ini
     assert.equal(result.status, 0, result.stderr);
     const output = JSON.parse(result.stdout);
     assert.equal(output.hookSpecificOutput.permissionDecision, 'deny');
-    assert.match(
-      output.hookSpecificOutput.permissionDecisionReason,
-      /\.ultra\/\.runtime\/state\.db/,
-    );
+    assert.match(output.hookSpecificOutput.permissionDecisionReason, /team checkpoint/);
   } finally {
     fs.rmSync(project, { recursive: true, force: true });
   }

adapters/tests/codex-hook.test.cjs

@@ -180,7 +180,10 @@ test('every generated skill is Codex-valid, UI-visible, and free of Claude host
     const status = fs.readFileSync(path.join(layout.pluginRoot, 'skills', 'ultra-status', 'SKILL.md'), 'utf8');
     assert.doesNotMatch(plan, /LEGACY_STATE_MIGRATION_REQUIRED|v4\.4|v4\.5/);
     assert.match(plan, /Never read or\s+write .*tasks\.json/i);
-    assert.match(status, /Never fall\s+back to generated task JSON/i);
+    assert.match(
+      status,
+      /Never fall\s+back to the Git team checkpoint,\s+generated task\s+JSON/i,
+    );
 
     const coreWorkflowText = [
       ...COMMANDS,
@@ -297,8 +300,8 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
     const upstreamSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'upstream-mcp-tools.yaml'), 'utf8'));
     const capabilityMap = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'codex-capability-map.json'), 'utf8'));
     const interaction = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'interaction-contract.json'), 'utf8'));
-    assert.equal(liveSpec.tools.length, 57);
-    assert.equal(upstreamSpec.tools.length, 57);
+    assert.equal(liveSpec.tools.length, 60);
+    assert.equal(upstreamSpec.tools.length, 60);
     assert.deepEqual(upstreamSpec.tools.map((tool) => tool.name).sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.deepEqual(capabilityMap.live_mcp_tools.sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.equal(Object.keys(capabilityMap.codex_native_replacements).length, 9);