ultra-builder-pro-cli 0.21.1 → 0.22.0

package/docs/ARCHITECTURE.md

@@ -9,8 +9,9 @@
 `ultra-builder-pro-cli` is a multi-runtime plugin suite that **distributes** the
 Ultra Builder Pro engineering loop (skills + commands + workflow hooks) as
 native Claude Code, OpenCode, Codex, and Kimi Code plugins, and
-**runs** that loop with isolated sessions sharing one authoritative state
-store (`.ultra/.runtime/state.db`).
+**runs** that loop with isolated sessions sharing checkout-local operational
+authority (`.ultra/.runtime/state.db`) plus one MCP-published Git team checkpoint
+(`.ultra/tasks/tasks.json`).
 
 It is not an agent or a general conversational-memory provider. It is the workflow
 substrate the supported hosts share, including project-local cross-session workflow
@@ -42,17 +43,19 @@ memory under `.ultra/`.
                   │   .ultra/.runtime/state.db   │
                   │  (SQLite + WAL)     │  ← lifecycle + index authority
                   └──────────┬──────────┘
-                             │ projector (Phase 2.6)
-                             ▼
-              .ultra/tasks/tasks.json     (read-only view)
-              .ultra/tasks/contexts/*.md  (fully generated read-only view)
-              .ultra/activity-log.json    (optional dump)
+                             │
+                   ┌─────────┴──────────┐
+                   │                    │
+                   ▼                    ▼
+     .ultra/.runtime/projections/   .ultra/tasks/tasks.json
+       (local generated views)      (Git team checkpoint:
+                                    baseline + Changes + tasks)
 ```
 
 | Layer        | Role                                         | Form                                                  |
 |--------------|----------------------------------------------|-------------------------------------------------------|
 | **skill**    | knowledge carrier; tells the runtime *what to do* | `skills/<name>/SKILL.md` discovered natively by all supported runtimes |
-| **MCP**      | authoritative workflow-state, decision, artifact, and Context Spine API | stdio MCP server exposing 57 live tools across task/session/baseline/change/decision/workflow/artifact/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
+| **MCP**      | authoritative workflow-state, decision, artifact, and Context Spine API | stdio MCP server exposing 60 live tools across task/session/baseline/change/decision/workflow/artifact/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
 | **CLI**      | explicit initialization, recovery, diagnostics, and orchestration | `ultra-tools` / `ubp-orchestrator`; only commands listed by `--help` are executable (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
 
 Why three: skills give us behavior portability across runtimes; MCP gives
@@ -69,11 +72,14 @@ RPC, and host-native loaders own resolution and invocation.
 
 Together, `.ultra/` retains project-local cross-session workflow memory:
 normalized intent, progress, tasks, bounded context, specifications, evidence,
-provenance, and recovery. `.ultra/.runtime/state.db` is the sole authority for lifecycle,
-indexing, transitions, freshness, and coordination. Registered digest-bound files
-carry semantic and evidence bodies. Generated projections and working scratch do
-not become authority merely because they live under `.ultra/`. The complete
-classification and promotion contract is
+provenance, and recovery. `.ultra/.runtime/state.db` is operational authority for
+lifecycle, indexing, transitions, freshness, and coordination in one checkout.
+Registered digest-bound files carry semantic and evidence bodies.
+`.ultra/tasks/tasks.json` is a portable, digest-chained Git handoff for baseline,
+Change, and durable task records; it never owns sessions, leases, or live
+`in_progress` state. Generated projections and working scratch do not become
+authority merely because they live under `.ultra/`. The complete classification and
+promotion contract is
 [`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
 
 All durable Ultra lifecycle and index state lives in one SQLite file with WAL enabled.
@@ -109,9 +115,11 @@ Two rules make this work:
 
 1. **No double source (D32).** lease/heartbeat live only in `sessions`,
    not in a `lease.json` file. Activity log lives only in `events`, not
-   in JSON files. `tasks.json` and the complete
-   `contexts/task-*.md` files are **projections** generated by the projector;
-   manual edits are overwritten on the next state.db change.
+   in JSON files. `.ultra/.runtime/projections/tasks.json` and its complete
+   `contexts/task-*.md` files are local projections generated by the projector;
+   manual edits are overwritten on the next state.db change. The tracked
+   `.ultra/tasks/tasks.json` is a different surface: only MCP publishes or imports
+   this versioned team checkpoint, and digest validation rejects manual edits.
 
 2. **Single writer for mutable tables, multi-writer for `events`.**
    `.ultra/.runtime/state.db` opens in WAL with `busy_timeout=5000`. The MCP
@@ -324,14 +332,40 @@ evidence, and final convergence decision.
 
 Mutating MCP calls enqueue durable `projection_jobs`. Success is exposed in MCP
 response metadata; failure becomes a retryable structured incident instead of a
-swallowed warning. `system.doctor` is read-only by default. Explicit repair performs
-backup-first schema upgrade, archive-journal recovery, session and projection
-recovery, and regenerated projections. It cannot approve a baseline or replace a
-corrupt SQLite file silently. `system restore` accepts only a verified SQLite backup
-inside `.ultra/.runtime/backups`, quarantines the corrupt authority, and rolls back on failure.
+swallowed warning. These jobs regenerate only checkout-local views below
+`.ultra/.runtime/projections/`; they never rewrite the Git team checkpoint. Durable
+semantic operations publish the checkpoint directly at baseline, Change, plan, and
+task handoff boundaries. `system.doctor` is read-only by default. Explicit repair
+performs backup-first schema upgrade, archive-journal recovery, session and local
+projection recovery, and regenerated local views. It cannot import or publish semantic
+team state, approve a baseline, or replace a corrupt SQLite file silently. `system
+restore` accepts only a verified SQLite backup inside `.ultra/.runtime/backups`,
+quarantines the corrupt authority, and rolls back on failure.
 When no valid backup exists, confirmed `system rebaseline` preserves both corrupt
 authority and the legacy task projection before creating a new brownfield adoption.
 
+### Git team checkpoint and checkout merge
+
+`task.ledger_publish` serializes the current portable baseline, all Change summaries,
+and durable task contracts to `.ultra/tasks/tasks.json`. Per-record digests and
+revisions make independent fast-forward possible; the document state digest, parent
+digest, and bounded ancestor list reject stale or unrelated histories. Local process
+ownership fields are deliberately absent.
+
+The MCP server imports the checkpoint once when it opens project authority. A
+long-running host explicitly calls `task.ledger_import` after receiving a newer Git
+version. Import is transactional: it validates every record first, preserves local-only
+fields, fast-forwards clean records, and rejects same-record concurrency or an active
+task collision. Re-reading an already imported checkpoint performs no write. A ready
+baseline is never trusted from Git alone; import creates a local revalidation gap and
+clears checkout-specific approval until current scope bytes, HEAD, and verification
+converge.
+
+Baseline freshness hashes scoped application content independently of Git staging and
+excludes `.ultra/`, then checks commit ancestry. This removes the metadata treadmill:
+committing a checkpoint or another Ultra artifact advances HEAD without staling the
+baseline, while changing scoped application bytes still does.
+
 ## 5. Sessions — the execution unit
 
 A **session** is the standard unit of execution across all four runtimes
@@ -456,7 +490,8 @@ shippable; downstream slip never blocks an earlier release.
 | What does each MCP tool accept and return?         | [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml)     |
 | How do CLI subcommands map to MCP tools?           | [`spec/cli-protocol.md`](../spec/cli-protocol.md)   |
 | Exact SQLite schema?                               | [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) |
-| What does a tasks.json look like after projection? | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
+| What does the Git team checkpoint look like?       | [`spec/schemas/task-ledger.v1.schema.json`](../spec/schemas/task-ledger.v1.schema.json) |
+| What does the local task projection look like?     | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
 | Current authority and package decisions            | [`docs/DECISIONS.md`](./DECISIONS.md)               |
 | When does each workflow write, invalidate, and converge state? | [`docs/WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md) |
 
@@ -469,8 +504,8 @@ Every contract on this page is enforced by `npm run test:spec`:
 - `validate-state-db.cjs` — schema applies cleanly to a fresh in-memory
   SQLite, valid fixtures insert, invalid fixtures are rejected by
   CHECK / NOT NULL / FK constraints.
-- `validate-json-schemas.cjs` — projection schemas for `tasks.json` and
-  `contexts/task-*.md`.
+- `validate-json-schemas.cjs` — the team-checkpoint schema plus local projection
+  schemas for `tasks.json` and `contexts/task-*.md`.
 - `validate-skills.cjs` — every existing skill passes the manifest
   contract; failures are recorded in `spec/migration-notes.md`.
 - `check-cli-mapping.cjs` — every MCP tool has exactly one CLI

package/docs/ARTIFACT-AUTHORITY.md

@@ -15,23 +15,28 @@ payloads.
 Semantic and evidence artifacts under `.ultra/` are trackable so reviewed intent and
 verification can travel with the repository. `.ultra/.runtime/` is always ignored:
 the SQLite authority, leases, worktrees, local telemetry, and recovery snapshots remain
-checkout-local unless a team uses an explicit synchronization or artifact handoff.
+checkout-local. `.ultra/tasks/tasks.json` is the narrow MCP-owned Git handoff for
+portable baseline, Change, and durable task records; it is not a copy of live runtime
+state.
 
 ## Artifact classes
 
 | Class | Examples | Authority |
 |---|---|---|
-| Lifecycle and index | `.ultra/.runtime/state.db` | Sole authority for identifiers, normalized accepted intent, status, legal transitions, references, digests, freshness, provenance, locks, leases, transactions, recovery, and coordination |
+| Checkout-local lifecycle and index | `.ultra/.runtime/state.db` | Operational authority for identifiers, normalized accepted intent, status, legal transitions, references, digests, freshness, provenance, locks, leases, transactions, recovery, and coordination in one checkout |
+| Git team checkpoint | `.ultra/tasks/tasks.json` | MCP-published, digest-chained handoff of portable baseline, Change, task-contract, dependency, and durable status records; never live session or lease authority |
 | Digest-bound semantic artifacts | specifications, research reports, Change intent/delta/plan, context manifests | Authoritative semantic bodies only while registered by the owning DB row or workflow step and matching its recorded digest |
 | Digest-bound evidence artifacts | test, review, delivery, and verification reports | Authoritative evidence bodies only while registered, immutable where required, and matching the recorded digest and scope |
-| Generated projections | `tasks/tasks.json`, generated task-status headers, activity exports | Read-only views derived from DB authority; manual edits are overwritten and never become authority |
+| Generated projections | `.ultra/.runtime/projections/tasks.json`, generated task contexts, activity exports | Checkout-local read-only views derived from DB authority; manual edits are overwritten and never become authority |
 | Advisory recovery | `.ultra/.runtime/checkpoint.json` | Compact recovery hint derived from DB authority; stale or missing content never overrides the DB |
 | Working scratch | `.ultra/.runtime/collab/`, temporary session output, incomplete drafts | Non-authoritative working material until verified and promoted through a supported workflow write |
 | External provider references | memory or code-graph provider name, scope, version, stable reference, freshness metadata | Metadata-only context stored by Ultra; the provider remains authority for its payload |
 
-The DB is not expected to contain every semantic paragraph. It owns the lifecycle and
-the binding between a fact and its current content. A digest-bound file owns the
-registered semantic or evidence body. Neither surface is a parallel lifecycle source.
+The DB is not expected to contain every semantic paragraph. It owns checkout-local
+lifecycle and the binding between a fact and its current content. A digest-bound file
+owns the registered semantic or evidence body. The team checkpoint moves a reviewed
+portable subset through Git and is merged into the receiving DB through MCP. None of
+these surfaces independently owns all three roles.
 
 ## Human, model, and mechanical responsibilities
 
@@ -39,9 +44,9 @@ registered semantic or evidence body. Neither surface is a parallel lifecycle so
 |---|---|---|
 | Owner | Goals, acceptance, non-goals, material choices, risk acceptance, and authorization for irreversible or external effects | Supply facts the checkout or runtime can establish directly |
 | Host model | Inspect evidence, recommend a route, ask only for unresolved owner choices, normalize the answer, call the owning write, update semantic artifacts, read back the result, and present the next recommendation | Fabricate evidence, infer owner authorization, or bypass legal transitions |
-| Ultra MCP | Persist normalized inputs, validate structure and current digests, record lifecycle and provenance, enforce legal transitions, project views, and expose recovery | Choose product direction, prove a UI click, force a semantic route, or replace model judgment |
+| Ultra MCP | Persist normalized inputs, validate structure and current digests, record lifecycle and provenance, enforce legal transitions, project local views, publish/import the Git checkpoint, and expose recovery | Choose product direction, prove a UI click, force a semantic route, or replace model judgment |
 | Host adapter | Render the shared interaction contract through the host-native question and tool surfaces | Become a second workflow authority |
-| Hook | Observe lifecycle, inject compact DB-derived recovery context, and protect generated projections | Select a semantic route or block ordinary development |
+| Hook | Observe lifecycle, inject compact DB-derived recovery context, and protect MCP-owned checkpoint and generated projection paths | Select a semantic route or block ordinary development |
 
 ## Intent persistence
 
@@ -169,8 +174,8 @@ rejected without changing prior authority. A caller can provide
 `artifact.get` reads by unique ID or unambiguous path. It fails closed when a path
 has multiple active authorities and reports whether the row satisfies the managed
 registry contract. A canonical path can have only one non-archived authority across
-all owners and kinds. Runtime, scratch, `tasks.json`, and generated task contexts
-cannot be promoted through this API.
+all owners and kinds. Runtime, scratch, the MCP-owned team checkpoint, and generated
+task contexts cannot be promoted through this API.
 
 Owning internal writers use the same transaction contract. Change intent, delta and
 documentation packets, contexts, adaptive research, findings, incident diagnosis,
@@ -196,11 +201,13 @@ tables. It reports:
 - graph cycles that cannot become consumer evidence;
 - more than one active authority for the same canonical path;
 - legacy compatibility rows that remain unmanaged;
-- generated task contexts whose task no longer exists.
+- legacy generated task contexts left outside the runtime projection root.
 
 `.ultra/.runtime/**`, `.ultra/scratch/**`, and fixed scaffold support files are outside
-orphan diagnosis. Current generated projections are recognized from the DB task set,
-not from a blanket directory exemption. Before a baseline is ready, only the reserved
+orphan diagnosis. Current generated projections are local runtime files and are not
+semantic artifacts. A retired `.ultra/tasks/contexts/**` entry is diagnosed and any
+generated marker is reported as a ghost projection. Before a baseline is ready, only
+the reserved
 `discovery.md`, `product.md`, `architecture.md`, and `research-distillate.md` scaffold
 paths under `.ultra/specs/` are provisional; every additional specification is subject
 to orphan diagnosis immediately. Completion cannot be manufactured by registering
@@ -208,25 +215,58 @@ empty templates. Doctor and status expose registered, managed, and unmanaged cou
 and compatibility remains unhealthy until every retained row is deliberately promoted
 or retired.
 
+## Team checkpoint
+
+`.ultra/tasks/tasks.json` has kind `ultra-team-task-ledger` and a versioned schema. It
+contains:
+
+- one portable baseline record, when present;
+- every Change summary, including a Change that has not yet produced tasks;
+- durable task contracts, dependencies, acceptance mappings, and statuses;
+- per-record revisions, parent digests, the checkpoint state digest, and bounded
+  checkpoint ancestry.
+
+It excludes `in_progress` ownership, session ids, leases, worktrees, telemetry,
+projection jobs, recovery scratch, and `completion_commit`. Those fields are meaningful
+only in the checkout that owns the active process or Git object.
+
+MCP publishes a new generation at semantic handoff points: baseline convergence,
+Change creation or update, plan acceptance, durable task-contract or status change,
+task expansion or deletion, and Change convergence or archive. A direct edit is
+rejected by host hooks and fails digest validation even without hooks.
+
+`task.ledger_import` validates schema, full and per-record digests, bounded ancestry,
+Change ownership, task parents, and local active sessions. A clean record fast-forwards.
+A record changed on both sides, a non-descendant checkpoint, or a remote update to a
+locally active task stops with a typed conflict. Re-importing the same checkpoint
+performs no DB write. A ready imported baseline becomes `draft` or `adopting` with a
+blocking checkout-local revalidation gap; Git cannot prove the receiving checkout's
+HEAD, scope bytes, verification, or accepted dirty state. Publication remains blocked
+until that local baseline converges, preventing one unvalidated checkout from
+downgrading team authority.
+
+Legacy v4.4/v4.5 projections are replaced only through `task.ledger_publish`. The
+publisher first compares every available durable field with SQLite, writes the exact
+legacy bytes to `.ultra/.runtime/backups/task-ledger/`, and refuses any mismatch.
+Doctor diagnoses this state but never performs the semantic replacement.
+
 ## Task-context projection
 
-`.ultra/tasks/contexts/<task-id>.md` is fully generated from current DB authority.
-The projector replaces the whole file, including its execution contract and stale
-banner, and marks it with `generated_by: ultra-projector`. It never preserves arbitrary
-prose inserted into an earlier projection.
-
-Before replacing an existing authored context, the projector promotes the exact legacy
-body bytes once into a digest-bound `legacy_context_findings` artifact owned and
-consumed by the task. Legacy frontmatter, stale banners, and generated contract marker
-regions are removed first; any remaining authored body is retained exactly, even when
-an older projector had preserved it after a generated contract. Replacement is skipped
-without promotion only when no authored content remains. If promotion cannot be
-registered, projection fails without deleting the authored body. A context target must
-remain lexically and physically below
-`.ultra/tasks/contexts/`; traversal and symlink ancestors are rejected by projection and
-migration. When a task disappears, only an orphan carrying the generated marker may be
-pruned, and the removal emits `projection_pruned`; unknown authored files are retained
-for diagnosis.
+`.ultra/.runtime/projections/contexts/<task-id>.md` is fully generated from current DB
+authority. The projector replaces the whole file, including its execution contract and
+stale banner, and marks it with `generated_by: ultra-projector`. It never preserves
+arbitrary prose inserted into an earlier projection.
+
+Before retiring an existing `.ultra/tasks/contexts/<task-id>.md`, the projector
+promotes its exact authored body bytes once into a digest-bound
+`legacy_context_findings` artifact owned and consumed by the task. Legacy frontmatter,
+stale banners, and generated contract marker regions are removed first; any remaining
+authored body is retained exactly, even when an older projector had preserved it after
+a generated contract. Migration fails without deleting the authored body if promotion
+cannot be registered. Both legacy reads and runtime projection writes reject traversal,
+symlink ancestors, and path escape. When a task disappears, only a runtime projection
+carrying the generated marker may be pruned, and the removal emits
+`projection_pruned`.
 
 Model findings, decisions, or evidence discovered during development must be written
 below the owning Change root and registered through the workflow or `artifact.record`.

package/docs/COMMIT-HASH-BACKFILL.md

@@ -1,101 +1,44 @@
-# Commit-hash backfill — two-commit completion flow
+# Commit-hash backfill
 
-> Phase 2.8 contract. Replaces the v4.4 `git commit --amend` step with an
-> append-only flow that survives the SQLite authority model.
-> Hook wiring lives in Phase 3 (`skills/ultra-dev/SKILL.md` Step 6).
+`tasks.completion_commit` is checkout-local integration evidence. It lives in
+`.ultra/.runtime/state.db` and may appear in checkout-local projections, but it is
+deliberately absent from the Git-facing team ledger.
 
-## Why we changed
+This removes the old self-referential two-commit loop. Recording a commit hash no
+longer changes any tracked file.
 
-In v4.4 the per-task `context md` carried a `completion_commit` field
-in its frontmatter. The legacy flow was:
+## Direct task completion
 
-1. `git commit -m "feat: …"` to land the implementation
-2. read the freshly-created commit hash
-3. edit `contexts/task-N.md` to write the hash into the header
-4. `git commit --amend --no-edit` to fold the edit into the same commit
+After implementation, verification, and review are current:
 
-That last step makes the commit non-atomic (the second write produces
-a new SHA, invalidating the value we just stamped). It also fights the
-v4.5 authority rule (D32) — the projector is the only writer to
-`contexts/task-N.md`, so any handwritten edit gets stomped.
+1. Update the task to `completed`. The MCP publishes its durable status and contract to
+   `.ultra/tasks/tasks.json`.
+2. Create one local task commit containing the implementation, semantic Ultra
+   artifacts, and the team ledger checkpoint.
+3. Read the resulting `HEAD` and update only `completion_commit` through `task.update`.
+4. Verify the task worktree `HEAD`, integration ancestry, review evidence, and public
+   seam; then close the session and complete the dev workflow.
 
-## The new flow
+The third step changes only ignored runtime state. Repeating it with the same hash is
+byte-idempotent and leaves Git clean.
 
-```
-┌──────────────────────────────────┐
-│ 1. feat commit                   │  context md still has empty
-│    git add … && git commit       │  completion_commit (projector
-│    -m "feat: task-N — title"     │  emitted it from a NULL row)
-└──────────────────┬───────────────┘
-                   ▼
-┌──────────────────────────────────┐
-│ 2. read the new SHA              │  hash = `git rev-parse HEAD`
-└──────────────────┬───────────────┘
-                   ▼
-┌──────────────────────────────────┐
-│ 3. update state.db               │  ops.patchTask(db, id,
-│                                  │    { completion_commit: hash })
-└──────────────────┬───────────────┘
-                   ▼
-┌──────────────────────────────────┐
-│ 4. projector regenerates the     │  projector.projectContext(db, id)
-│    context md header with the    │  writes a new contexts/task-N.md
-│    completion_commit value       │  whose YAML now contains the hash
-└──────────────────┬───────────────┘
-                   ▼
-┌──────────────────────────────────┐
-│ 5. chore commit                  │  git add contexts/task-N.md
-│                                  │  git commit -m
-│                                  │    "chore: record task-N hash"
-└──────────────────────────────────┘
-```
+If the commit fails after step 1, transition the still-session-owned task from
+`completed` to `blocked`, preserve the worktree, and record the failure. This recovery
+transition is accepted only while `completion_commit` is absent. A task with a recorded
+completion commit remains terminal.
 
-The result in `git log --oneline`:
+## Parent-supervised workers
 
-```
-2222222 chore: record task-N completion hash
-1111111 feat: task-N — <title>
-```
+A worker records evidence and exits without finalizing the parent-owned task. The
+primary host verifies and integrates the worker commit, publishes the task completion
+checkpoint, records the integrated commit hash locally, and settles the lease.
 
-Both commits are immutable. The chore commit is small (only the
-projection file changed) and is trivial to revert if the wrong task is
-recorded.
+## Why the hash is local
 
-## Why two commits, not amend
-
-- **Atomic history.** Each SHA is final the moment it is written.
-- **Idempotent.** Re-running the chore commit on the same hash is a
-  no-op (projector emits the same bytes).
-- **Survives the projector contract.** The projection is the only
-  writer to `contexts/task-N.md`; this flow keeps that promise.
-- **Audit trail.** Reviewers can see the implementation diff (commit 1)
-  separately from the bookkeeping diff (commit 2).
-
-## Hook integration (Phase 3)
-
-The post-commit hook installed by `skills/ultra-dev/` will invoke this
-flow as soon as a feat commit lands on a task branch:
-
-```
-post-commit workflow → if commit message starts with "feat:" and the
-                   working tree contains contexts/task-N.md →
-                   MCP task.update {id: task-N,
-                       patch: {completion_commit: $(git rev-parse HEAD)}} &&
-                   git add contexts/task-N.md &&
-                   git commit -m "chore: record task-N completion hash"
-```
-
-Until that hook lands, contributors run the two commits manually. The
-contract above is what the hook will codify.
-
-## Verification
-
-`mcp-server/tests/commit-hash-flow.test.cjs` builds a throwaway git
-repo, walks the five steps in-process, and asserts:
-
-- `git log --oneline -2` shows `chore: record task-N completion hash`
-  on top of `feat: task-N — …`.
-- The post-projection `contexts/task-N.md` frontmatter contains the
-  exact SHA produced by the feat commit.
-- Re-running step 4 + step 5 against the same SHA is a no-op (the
-  chore commit is empty and skipped).
+- A Git file cannot contain the hash of the commit that contains that same file.
+- Runtime integration evidence is checkout-specific and does not belong in a shared
+  semantic merge surface.
+- The team ledger needs the durable task outcome and status, not a self-referential
+  commit identifier.
+- Baseline freshness uses scoped content plus Git ancestry, so a metadata-only Ultra
+  checkpoint commit does not invalidate an otherwise unchanged baseline.

package/docs/DECISIONS.md

@@ -11,16 +11,18 @@ release-version authority.
 |---|---|---|
 | User intent | Goals, acceptance, non-goals, semantic route selection, material product trade-offs, risk acceptance, and authorization for irreversible or external effects | Facts that the current checkout or runtime can establish directly |
 | Host model | Classification and route recommendations, investigation, solution design, task decomposition, context, test and review strategy, documentation impact, intent normalization, and next-action recommendations | Fabricated evidence, bypassed authorization, or durable lifecycle state |
-| Ultra MCP | IDs, state, digests, provenance, freshness, locks, leases, transactions, recovery, and legal state transitions | Product direction, a fixed research route, technology selection, or business decisions |
+| Ultra MCP | IDs, checkout-local state, digests, provenance, freshness, locks, leases, transactions, recovery, legal state transitions, and Git checkpoint publish/import | Product direction, a fixed research route, technology selection, or business decisions |
 | Host adapter | Native Skill discovery, user-question surfaces, tool invocation, installation, and runtime wiring | A second project-state authority |
-| Hook | Lifecycle observation, compact DB-derived context, recovery hints, and generated-projection protection | Ordinary development blocking or semantic route selection |
+| Hook | Lifecycle observation, compact DB-derived context, recovery hints, and protection of MCP-owned checkpoint/projection paths | Ordinary development blocking or semantic route selection |
 
 `.ultra/` is project-local cross-session workflow memory. `.ultra/.runtime/state.db` is
-the only lifecycle, index, transition, freshness, and coordination authority.
-Registered digest-bound files carry semantic or evidence bodies; generated
-projections and working scratch are not authority. Prompt text, chat history,
-general external-memory payloads, and code-graph payloads are not Ultra
-authority. See [`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
+checkout-local lifecycle, index, transition, freshness, and coordination authority.
+Registered digest-bound files carry semantic or evidence bodies.
+`.ultra/tasks/tasks.json` is the MCP-published Git handoff for portable baseline,
+Change, and durable task records, never live session state. Generated projections and
+working scratch are not authority. Prompt text, chat history, general external-memory
+payloads, and code-graph payloads are not Ultra authority. See
+[`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
 
 ## Research coverage
 

package/docs/LEGACY-CLI-CROSSWALK.md

@@ -53,6 +53,9 @@ The following are deliberate extensions built on the original spine:
 9. Native adapters for Claude Code, OpenCode, Codex, and Kimi Code.
 10. Explicit worktree admission, leases, heartbeats, crash evidence, circuit breaking,
     dependency waves, and optional verified cleanup.
+11. A digest-chained Git team checkpoint that keeps the original shareable task-ledger
+    benefit without committing SQLite, leases, sessions, or live `in_progress`
+    ownership.
 
 ## Intentionally retired original baggage
 
@@ -85,6 +88,7 @@ route only for a unique mechanical recovery invariant.
 task.init_project
   -> greenfield classification
   -> Git bootstrap when absent
+  -> empty or imported team checkpoint
   -> init read-back and completion
   -> explicit full research with a model-recommended, owner-selected route
   -> selected execute/verify/reuse work and synthesis
@@ -101,6 +105,7 @@ task.init_project
 task.init_project
   -> brownfield classification and selected scope
   -> preserve current Git HEAD and dirty-state evidence
+  -> import portable team state and require local baseline revalidation when cloned
   -> init read-back and completion
   -> explicit adoption research with a model-recommended, owner-selected route
   -> characterization verification + known-red/gap ledger
@@ -123,13 +128,13 @@ doctor/migrate with backup
 
 ```text
 status
-  -> change intent capture
+  -> checkpoint condition + change intent capture
   -> material alignment only when unresolved
   -> model-recommended, owner-selected or delegated bounded research, plan,
      current dev work, think, or status
   -> session.spawn creates the real task worktree
   -> red/green/verify/review
-  -> local task commit and verified integration
+  -> durable task checkpoint + one local task commit + local hash backfill
   -> safe session close
   -> aggregate test -> review -> deliver
   -> atomic baseline reconciliation
@@ -156,6 +161,9 @@ status
 | Failure returned a task to pending without recovery evidence | Exit and spawn failures become `blocked` and record session-linked circuit-breaker evidence. |
 | A late resume failure could leave refreshed DB metadata behind | Resume snapshots DB authority and generated projections, then restores both together with Git rollback. |
 | A legacy schema migrated before a later resume failure | Resume restores the pre-migration backup, not the partially completed upgraded intermediate state. |
+| Tracked `tasks.json` made every Ultra write dirty and every metadata commit stale the baseline | Live projections moved below ignored `.ultra/.runtime/projections/`; the tracked file became a low-frequency MCP checkpoint, and baseline freshness excludes `.ultra` while still checking scoped source bytes plus Git ancestry. |
+| A local SQLite DB could not hand baseline, Change, and task authority to another checkout | The Git checkpoint carries portable records with per-record digests and ancestry; import fast-forwards clean records, rejects concurrency, and revalidates every ready baseline locally. |
+| A completed task needed a second commit to record its own commit hash | Durable task outcome enters the same task commit; the resulting hash is backfilled only into local SQLite/projections, so no self-referential metadata commit is created. |
 
 ## Advancement rule
 

package/docs/PLUGIN-ISOLATION-CONTRACT.md

@@ -13,7 +13,7 @@ An adapter may write only:
 
 The first command allowed to create project authority is `ultra-init`. Once invoked,
 Ultra owns only the repository-local `.ultra/` workflow-memory envelope and its
-generated projections.
+MCP-published checkpoint plus generated local projections.
 
 ## Surfaces Ultra does not own
 
@@ -48,7 +48,8 @@ Internal review-rule skills remain available only to their bounded workers.
 Outside a repository containing `.ultra/.runtime/state.db`, all Ultra hooks are silent. Inside
 an initialized repository they remain silent unless a DB-authoritative workflow is
 active, blocked, or ready. The sole idle-time enforcement is protection against direct
-writes to generated Ultra projections; the DB remains authoritative.
+writes to the MCP-owned team checkpoint or generated Ultra projections; the DB remains
+checkout-local operational authority.
 
 Installation tests preserve byte-for-byte snapshots of all supported user handbook
 paths. Runtime tests cover explicit activation, idle silence, active recovery, and

package/docs/ROADMAP.md

@@ -57,14 +57,14 @@ sharing one authoritative workflow store.
 
 ```
 spec/                       ← Phase 1 single source of truth
-├── mcp-tools.yaml          (57 live tools across 9 families)
+├── mcp-tools.yaml          (60 live tools across 9 families)
 ├── cli-protocol.md         (CLI ↔ MCP mapping table)
 ├── schemas/                (state-db.sql + 4 JSON schemas)
 ├── fixtures/{valid,invalid}/  (+ v4.4-project for migration)
 └── scripts/test-all.cjs    (npm run test:spec — 7 validation stages)
 
 mcp-server/                 ← Phase 2 authoritative state layer
-├── server.cjs              (stdio MCP server, 57 task/session/baseline/change/decision/workflow/artifact/system/plan tools)
+├── server.cjs              (stdio MCP server, 60 task/session/baseline/change/decision/workflow/artifact/system/plan tools)
 ├── lib/
 │   ├── state-db.cjs        (SQLite + WAL + pragmas)
 │   ├── state-ops.cjs       (full write API, status state machine)
@@ -106,7 +106,7 @@ docs/
 ├── PLUGIN-ISOLATION-CONTRACT.md install, activation, idle, and ownership contract
 ├── RUNTIME-COMPAT-MATRIX.md     Phase 4 runtime capability matrix
 ├── STATE-DB-ACCESS-POLICY.md    Phase 2 multi-process write contract
-├── COMMIT-HASH-BACKFILL.md      Phase 2.8 two-commit completion flow
+├── COMMIT-HASH-BACKFILL.md      Checkout-local completion commit evidence
 └── ROADMAP.md                   this file
 ```
 

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -47,16 +47,17 @@ not presented as nonexistent custom agents.
 | Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | Session context/health | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, native JS plugin injects only an active-workflow breadcrumb; health via `system.doctor` | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, active-workflow breadcrumb via native hooks |
-| Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
+| Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects managed checkpoint/projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
 | Pre-compact checkpoint | FULL | FULL | FULL | FULL, native `PreCompact` |
 | Post-compact context injection | FULL | FULL, native compacting context | FULL, native `PostCompact` restore | DEGRADED; checkpoint restoration runs, but Kimi 0.26/0.27 does not reinject fire-and-forget hook text |
 | Stop lifecycle advisory | FULL, native non-blocking `Stop` | N/A, no equivalent stop event needed | FULL, native non-blocking `Stop` | FULL, native non-blocking `Stop` |
 | Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | FULL, native `SubagentStart` / `SubagentStop` |
 
 Health/context, compact, stop, and subagent hooks remain silent unless
-`.ultra/.runtime/state.db` proves an active, blocked, or ready workflow. Projection
-protection applies to every initialized project because generated projections
-must never become a second authority. No host receives prompt capture, transcript capture,
+`.ultra/.runtime/state.db` proves an active, blocked, or ready workflow. Managed-file
+protection applies to every initialized project because neither a hand-edited team
+checkpoint nor generated local projection may become a second authority. No host
+receives prompt capture, transcript capture,
 observation journaling, session-summary memory, generic command blocking, or
 generic post-edit policy.
 Baseline-adoption and context-budget warnings are injected as advisory context;
@@ -67,7 +68,7 @@ they do not deny edits or stop active incident work.
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | plugin `mcpServers` entry |
-| Live/declared contracts | 57 | 57 | 57 | 57 |
+| Live/declared contracts | 60 | 60 | 60 | 60 |
 | Structured user alignment | `AskUserQuestion` in interactive sessions | `question` when permission is not denied | `request_user_input` when the current mode exposes it | `AskUserQuestion` outside auto mode |
 | Greenfield/brownfield baseline adoption | FULL | FULL | FULL | FULL |
 | Context Manifest v3 / breadcrumb | FULL | FULL, same bundled read-only DB reader as every hook | FULL | FULL |
@@ -75,9 +76,10 @@ they do not deny edits or stop active incident work.
 | Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` | native Kimi tools and workers |
 | Workflow-memory envelope | project `.ultra/` | project `.ultra/` | project `.ultra/` | project `.ultra/` |
 | Lifecycle/index authority | project `.ultra/.runtime/state.db` | project `.ultra/.runtime/state.db` | project `.ultra/.runtime/state.db` | project `.ultra/.runtime/state.db` |
+| Git team checkpoint | `.ultra/tasks/tasks.json` | `.ultra/tasks/tasks.json` | `.ultra/tasks/tasks.json` | `.ultra/tasks/tasks.json` |
 | General memory-provider API | N/A | N/A | N/A | N/A |
 
-All 57 `task.*`, `session.*`, `baseline.*`, `change.*`, `decision.*`,
+All 60 `task.*`, `session.*`, `baseline.*`, `change.*`, `decision.*`,
 `workflow.*`, `artifact.*`, `system.*`, and `plan.*` operations
 registered by `mcp-server/server.cjs` are live. Review, impact discovery, skill
 loading, and user interaction remain host-native surfaces.