ultra-builder-pro-cli 0.20.0 → 0.22.0

package/.ultra-template/docs/research/README.md

@@ -3,12 +3,33 @@
 Store durable research evidence here only when it is too detailed for the baseline
 specification. Baseline decisions and accepted behavior remain in `.ultra/specs/`.
 
-## Required step reports
+## Initialization modes
 
-Every selected `ultra-research` step writes one immutable report at
-`.ultra/docs/research/<workflow-id>/<step-id>.md`. Full and adoption research therefore
-produce seventeen reports. The shared specifications are updated during research but
-do not replace these per-step evidence records.
+`ultra-init` creates the scaffold and records classification; it never runs research
+or approves a baseline. A later explicit `ultra-research` invocation handles:
+
+- greenfield baseline evidence with adaptive product and architecture coverage;
+- brownfield adoption of observed product, runtime, quality, operations, known
+  failures, and documentation drift;
+- migrated or damaged authority only after backup-first `ultra-doctor` recovery,
+  followed by evidence-backed brownfield adoption.
+
+Blank templates are never baseline evidence. Existing authority is preserved rather
+than replaced by this scaffold.
+
+## Included-area reports
+
+Every included research area that executes, verifies, or reuses evidence writes one
+immutable report at `.ultra/docs/research/<workflow-id>/<step-id>.md`. The accepted
+coverage determines the report set; `full` and `adoption` describe baseline purpose,
+not a requirement to execute all seventeen catalog areas. Omitted areas create no
+report. The shared specifications are updated during research but do not replace these
+per-area evidence records.
+
+This directory is only for baseline establishment and adoption. Active Change research
+writes below
+`.ultra/changes/active/<change-id>/research/<workflow-id>/<step-id>.md`; it updates the
+Change overlay and never edits accepted baseline specifications.
 
 ## Report contract
 

package/.ultra-template/specs/discovery.md

@@ -67,7 +67,7 @@ decision. Include source date, segment, geography, and assumptions when applicab
 
 ## Baseline Gaps
 
-Reference authoritative gap ids from `.ultra/state.db`.
+Reference authoritative gap ids from `.ultra/.runtime/state.db`.
 
 | Gap id | Category | Status | Evidence | Owner |
 |---|---|---|---|---|

package/.ultra-template/tasks/tasks.json

@@ -1,6 +1,13 @@
 {
-  "schema_version": "4.5",
-  "generated_at": "1970-01-01T00:00:00.000Z",
-  "source": ".ultra/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": []
 }

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

@@ -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]

package/CHANGELOG.md

@@ -7,6 +7,112 @@ 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
+
+- Increased the packed four-host integration-test timeout to preserve the same
+  release gate on slower clean Linux runners instead of cancelling a healthy
+  tarball installation and MCP round-trip near the previous limit.
+
+## [0.21.0] — 2026-07-29
+
+### Added
+
+- Added a trackable semantic artifact registry with digest, provenance,
+  ownership, freshness, and orphan detection while keeping mutable SQLite,
+  leases, telemetry, backups, and worktrees under the ignored
+  `.ultra/.runtime/` boundary.
+- Added typed Change deltas, documentation reconciliation records, immutable
+  task and role context snapshots, transactional plan publication, and
+  self-contained delivery archives with crash-safe recovery journals.
+- Added workflow revision and supersession contracts so accepted intent can
+  evolve without rewriting history or leaving active documents detached from
+  their owning workflow.
+- Added schema 20 migration and backup-first recovery for legacy
+  `.ultra/state.db` projects, including safe runtime relocation and inode-pinned
+  archive finalization on supported POSIX platforms.
+
+### Changed
+
+- Published one exact eleven-capability graph across all four host interaction
+  contracts. Every adapter now presents the same
+  `inspect -> suggest -> host-native ask -> normalize -> persist -> apply -> read back`
+  flow, owns no semantic authority, and waits for explicit invocation before another
+  public capability starts.
+- Updated current workflow, authority, runtime, and project templates for the separate
+  greenfield, brownfield-adoption, and migrated-authority paths.
+- Made every Change converge through a current plan, DB-backed task contract,
+  bounded context, risk-selected verification, review, documentation
+  reconciliation, and local delivery archive. Research remains adaptive and
+  may be omitted when current evidence is sufficient.
+- Defined `.ultra/` as project-local cross-session workflow memory: registered
+  specifications and evidence carry semantic bodies, while MCP and SQLite own
+  lifecycle state, references, digests, legal transitions, and recovery.
+- Extended packed-package conformance to cover prompt hygiene, native interaction
+  parity, exact public capabilities, user-handbook byte preservation, and project
+  inertness before `ultra-init`.
+
+### Fixed
+
+- Fixed archive, plan, session-close, worktree, and migration mutations so
+  partial failures recover the prior files and state instead of reporting false
+  success or leaving split authority.
+- Fixed context and delivery gates accepting stale, cross-project, symlinked,
+  malformed, unowned, or digest-mismatched artifacts.
+- Fixed draft baselines exempting arbitrary files under `.ultra/specs/`; only
+  the four reserved baseline scaffold files are provisional before baseline
+  readiness, and every additional spec is diagnosed as an orphan immediately.
+- Fixed host hooks and adapters resolving legacy state paths or becoming a
+  second semantic authority. Hooks now observe active workflow state, protect
+  projections, and surface recovery without forcing a semantic route.
+
+### Removed
+
+- Removed the non-Ultra `learn` command and Skill, automatic session-to-Skill mining,
+  and both global output-style personas from source, host adapters, and npm
+  distribution. Ultra no longer creates user Skills or controls communication style.
+
 ## [0.20.0] — 2026-07-28
 
 ### Added

package/README.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/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.
 
@@ -59,14 +61,40 @@ session resumes from that authority instead of reconstructing it from chat.
 ## The mental model
 
 ```mermaid
-flowchart LR
-    U["User<br/>intent and material decisions"] <--> H["Host agent<br/>reasoning and implementation"]
-    H <--> S["Ultra skills<br/>task-specific workflows"]
-    S <--> M["Ultra MCP<br/>state, evidence, freshness, recovery"]
-    M <--> D[(".ultra/state.db")]
-    H --> A["Code, specifications,<br/>tests and review artifacts"]
-    A --> M
-    K["Lifecycle hooks<br/>breadcrumb and projection protection"] --> M
+flowchart TB
+    U["User<br/>goals, acceptance, trade-offs, risk, and external authorization"]
+
+    subgraph HOST["Supported coding host"]
+        UI["Host-native interaction<br/>Claude Code / Codex / OpenCode / Kimi Code"]
+        MODEL["Host agent<br/>inspect, recommend, implement, test, and review"]
+        ADAPTER["Host adapter<br/>native questions, commands, tools, and lifecycle wiring"]
+    end
+
+    SKILLS["Eleven explicit Ultra Skills<br/>init / research / think / change / plan / dev<br/>test / review / deliver / status / doctor"]
+    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 managed-file protection"]
+    OPS["Operational tools<br/>ubp / ultra-tools / optional orchestrator"]
+    EXTERNAL["External memory and graph providers"]
+
+    U <-->|"intent, recommendation, and owner choice"| UI
+    UI <--> MODEL
+    ADAPTER --> UI
+    ADAPTER -.->|"discovers and presents"| SKILLS
+    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
+    OPS -->|"installation"| ADAPTER
+    OPS -->|"diagnosis, recovery, and approved dispatch"| MCP
+    EXTERNAL -.->|"bounded provider references only"| DB
 ```
 
 The responsibility split is deliberate:
@@ -75,14 +103,37 @@ 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
 in a conversation.
 
+### How owner intent becomes durable authority
+
+```mermaid
+flowchart TD
+    CURRENT["Current Ultra workflow"] --> INSPECT["Host model inspects code, documents, and current authority"]
+    INSPECT --> SUGGEST["Model recommends a route and explains its consequences"]
+    SUGGEST --> CLEAR{"Is current owner intent already explicit?"}
+    CLEAR -->|"Yes"| NORMALIZE["Normalize the accepted intent"]
+    CLEAR -->|"No: a material choice remains"| ASK["Ask one dependent question through the host-native question tool"]
+    ASK --> NORMALIZE
+    NORMALIZE --> DECISION["Persist the normalized result through decision.*"]
+    DECISION --> APPLY["Apply it through the owning MCP operation or digest-bound artifact"]
+    APPLY --> AUTHORITY["Bind state, artifact digest, provenance, and downstream effects"]
+    AUTHORITY --> READBACK["Read back the authoritative result"]
+    READBACK --> RESUME["Resume the exact workflow step and recommend the next explicit capability"]
+```
+
+The interaction before the write establishes owner intent. Once the host model
+normalizes and persists that intent, MCP treats the stored result as current
+authority; it does not try to prove that the owner clicked a particular UI
+control. Ultra stores the accepted result and its scope, evidence, provenance,
+and effects—not chain-of-thought, raw prompts, transcripts, or UI receipts.
+
 ## What you get
 
 - Native plugins for **Claude Code**, **OpenCode**, **Codex**, and **Kimi Code**.
@@ -121,6 +172,8 @@ Requirements:
 
 - Node.js 22 or newer;
 - Git for the normal project workflow;
+- Python 3 on a POSIX platform with `dir_fd` filesystem operations for
+  inode-pinned archive finalization and recovery;
 - one or more supported coding-agent hosts.
 
 Install globally into all detected host configuration directories:
@@ -189,7 +242,7 @@ Initialization:
 - identifies the repository root and scope;
 - classifies the repository as greenfield, brownfield, or migrated;
 - initializes Git when needed;
-- creates `.ultra/` and schema 19 project authority;
+- creates `.ultra/` and schema 20 project authority;
 - verifies that the scaffold and database can be read back;
 - completes without silently starting research, creating a commit, adding a
   remote, or pushing anything.
@@ -205,16 +258,18 @@ The common path after baseline approval is:
 ```text
 ultra-change
   -> optional ultra-think or bounded ultra-research
-  -> ultra-plan when planning is needed
+  -> ultra-plan
   -> ultra-dev
   -> risk-selected ultra-test
   -> ultra-review
   -> ultra-deliver
 ```
 
-That diagram is a common path, not a mandatory pipeline. A small current task
-can take a shorter valid route; a high-risk or unclear change can require more
-research, planning, checking, or user alignment.
+Each public workflow is explicitly invoked rather than auto-chained. Thinking and
+research coverage are adaptive, and verification depth is risk-selected, but every
+Change reaches a current plan, DB-backed task contract, and role-scoped context before
+development. “Direct Build” skips Research only; it does not bypass Plan, Task, or
+Context authority.
 
 ### 2. Adopt an existing project
 
@@ -235,7 +290,7 @@ During `ultra-research`, the host model inspects current evidence and recommends
 the smallest sufficient route. The owner selects, modifies, delegates, or
 defers it through the host-native question surface unless the current request
 already resolves the route. The normalized accepted coverage is then stored in
-`.ultra/state.db`. Every included area receives one explicit disposition:
+`.ultra/.runtime/state.db`. Every included area receives one explicit disposition:
 
 - `execute` — produce fresh evidence;
 - `verify_existing` — validate an existing artifact;
@@ -249,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
 
@@ -266,8 +324,8 @@ The host then recommends one valid capability:
 
 - `ultra-think` for a material unresolved decision or diagnosis;
 - bounded `ultra-research` for a real evidence gap;
-- `ultra-plan` for task decomposition and dependency planning;
-- `ultra-dev` when a current task contract is already executable;
+- `ultra-plan` for the required task decomposition and dependency planning boundary;
+- `ultra-dev` after the current plan has produced an executable task contract;
 - `ultra-status` when the user needs the current authority and available routes;
 - `ultra-doctor` when state or installation health is degraded.
 
@@ -302,32 +360,145 @@ The next piece of daily work starts with a new `ultra-change`.
 | `ultra-deliver` | Reconcile specifications, close local authority, and archive the change |
 | `ultra-status` | Read the current breadcrumb, blockers, evidence, and allowed transitions |
 | `ultra-doctor` | Diagnose installation or project-state faults and expose safe recovery |
-| `learn` | Turn one approved, verified reusable procedure into a portable user skill |
+
+These eleven capabilities are the complete public Ultra command graph. Each capability
+returns current `allowed_transitions`; the host may recommend one, but another public
+capability starts only after an explicit user command or skill invocation.
+
+### Command interaction graph
+
+Every solid handoff below means: the current capability returns
+`allowed_transitions`, the model recommends a route, and the owner explicitly
+invokes the next public capability. It does not mean that one public command
+silently launches another.
+
+```mermaid
+flowchart TD
+    START["Project entry"] --> INIT["ultra-init"]
+    INIT --> CLASSIFY{"Repository classification"}
+
+    CLASSIFY -->|"Greenfield"| GREEN["Create scaffold<br/>verify Git and project authority"]
+    CLASSIFY -->|"Brownfield"| BROWN["Preserve the delivered system<br/>bootstrap adoption authority"]
+    CLASSIFY -->|"Legacy or damaged authority"| REPAIR["ultra-doctor<br/>migrate, recover, or rebaseline"]
+    REPAIR --> BROWN
+
+    GREEN --> RESEARCH["Explicit ultra-research"]
+    BROWN --> RESEARCH
+    RESEARCH --> BASELINE{"Has the baseline converged?"}
+    BASELINE -->|"Material decision gap"| THINK_BASE["ultra-think"]
+    THINK_BASE --> RESEARCH
+    BASELINE -->|"Evidence gap"| RESEARCH
+    BASELINE -->|"Approved and current"| CHANGE["Explicit ultra-change"]
+
+    CHANGE --> ROUTE{"Model recommends a route<br/>owner selects or modifies it"}
+    ROUTE -->|"Material intent remains unresolved"| THINK_CHANGE["ultra-think"]
+    THINK_CHANGE --> ROUTE
+    ROUTE -->|"Real evidence gap"| CHANGE_RESEARCH["Bounded ultra-research<br/>owned by the active Change"]
+    CHANGE_RESEARCH --> PLAN["ultra-plan"]
+    ROUTE -->|"Evidence is sufficient: Direct Build"| PLAN
+
+    PLAN --> DEV["ultra-dev<br/>one dependency-ready vertical task"]
+    DEV --> TASKS{"More executable tasks?"}
+    TASKS -->|"Yes"| DEV
+    TASKS -->|"No"| TEST["ultra-test<br/>risk-selected formal verification"]
+    TEST -->|"Failed or incomplete"| DEV
+    TEST -->|"Passing"| REVIEW["ultra-review<br/>specification fidelity and engineering quality"]
+    REVIEW -->|"Changes required"| DEV
+    REVIEW -->|"Approved"| DELIVER["ultra-deliver"]
+    DELIVER --> ARCHIVE["Reconcile specifications<br/>apply the Change overlay and archive evidence"]
+    ARCHIVE --> NEXT{"Continue"}
+    NEXT -->|"Next outcome"| CHANGE
+    NEXT -->|"Inspect current authority"| STATUS["ultra-status"]
+
+    ANY["Any active stage"] -.->|"read-only routing"| STATUS
+    ANY -.->|"mechanical health fault"| DOCTOR["ultra-doctor"]
+```
+
+“Direct Build” skips additional Research only. It still requires
+`ultra-plan`, current DB-backed task contracts, dependency ownership, and an
+immutable role-scoped Context Manifest before `ultra-dev`. `ultra-status` is a
+read-only side route, while `ultra-doctor` diagnoses and repairs mechanical
+health without selecting product intent.
 
 ## What lives in `.ultra/`
 
 ```text
 .ultra/
-  state.db                 # sole durable Ultra authority
-  specs/                   # current product and architecture baseline
+  .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
+    worktrees/             # registered local Git worktrees
+    telemetry/             # local operational telemetry
+  specs/                   # digest-bound product and architecture baseline
   changes/
-    active/                # current Change artifacts
+    active/<id>/           # all current Change semantics and evidence
+      intent.md            # accepted Change Contract
+      findings.md          # durable Change findings
+      progress.md          # generated human-readable projection
+      research/            # Change-only findings and research reports
+      delta/               # typed baseline overlay and semantic payloads
+      documentation/       # documentation overlay and reconciliation evidence
+      plan.json            # machine-readable task topology
+      plan.md              # deterministic human plan projection
+      contexts/            # immutable role/task context snapshots
+      test/                # Change-scoped test reports
+      review/              # Change-scoped review workers and summary
+      delivery/            # Change-scoped delivery evidence
     archive/               # immutable delivered Change artifacts
-  docs/research/           # evidence reports for selected research areas
-  reports/                 # test, review, and delivery evidence
+  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
 ```
 
-The host agent writes semantic specifications and evidence artifacts. MCP
-validates their references and digests, records workflow state, and rejects
-stale or illegal transitions. Generated Markdown and JSON help humans and tools
-inspect the project, but `.ultra/state.db` remains authoritative.
-
-Ultra does not store chain-of-thought, raw prompts, transcripts, cross-session
-memory, or code-graph content. Memory and graph systems remain separate
-providers; Ultra may store only bounded metadata references to them.
+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 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
+graph systems remain separate providers; Ultra may store bounded metadata
+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.
 
 ## Optional orchestration
 
@@ -379,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/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+