ultra-builder-pro-cli 0.20.0 → 0.22.0

package/docs/ARCHITECTURE.md

@@ -9,11 +9,13 @@
 `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/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 and it is not a memory provider. It is the workflow substrate
-the supported hosts share.
+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
+memory under `.ultra/`.
 
 ## 2. Three layers
 
@@ -38,20 +40,22 @@ the supported hosts share.
                └────────────┬───────┴──────────────────┘
                             ▼
                   ┌─────────────────────┐
-                  │   .ultra/state.db   │
-                  │  (SQLite + WAL)     │  ← single authoritative store
+                  │   .ultra/.runtime/state.db   │
+                  │  (SQLite + WAL)     │  ← lifecycle + index authority
                   └──────────┬──────────┘
-                             │ projector (Phase 2.6)
-                             ▼
-              .ultra/tasks/tasks.json     (read-only view)
-              .ultra/tasks/contexts/*.md  (read-only header)
-              .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, and Context Spine API | stdio MCP server exposing 51 live tools across task/session/baseline/change/decision/workflow/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
@@ -64,10 +68,22 @@ The skill layer is **read-only by design** (D29) and is discovered directly by
 each host. Ultra exposes no `skill.*` MCP family: skills are documentation, not
 RPC, and host-native loaders own resolution and invocation.
 
-## 3. Authoritative state — `.ultra/state.db`
-
-All durable Ultra workflow state lives in one SQLite file with WAL enabled. Schema is
-fixed in [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) and
+## 3. Workflow memory and authoritative state
+
+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 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.
+Schema is fixed in [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) and
 covers twenty-one tables:
 
 | Table              | Holds                                             | Phase |
@@ -82,7 +98,8 @@ covers twenty-one tables:
 | `specs_refs`       | spec change tracking → staleness propagation       | 5     |
 | `circuit_breaker`  | bounded retry and halt state for failed tasks       | 5     |
 | `changes`          | continuous feature/fix/incident lifecycle, alignment-thread link, and incident baseline bypass | 12→16 |
-| `artifacts`        | intent/context/verification artifact registry       | 8C    |
+| `artifacts`        | typed semantic/evidence ownership, digest, status, and provenance | 8C→20 |
+| `artifact_edges`  | normalized source and consumer dependency graph      | 20    |
 | `context_snapshots`| role/gate context, readiness, budget, execution seam, hashes, git head, provider refs | 10 |
 | `spec_learning_candidates` | approval-gated implementation discoveries for baseline convergence | 10 |
 | `trace_links`      | task/spec/change traceability                        | 8C    |
@@ -98,14 +115,17 @@ 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 status header in
-   `contexts/task-*.md` 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/state.db` opens in WAL with `busy_timeout=5000`. The MCP
+   `.ultra/.runtime/state.db` opens in WAL with `busy_timeout=5000`. The MCP
    server holds the single writer connection for `baselines`, `tasks`, `sessions`,
-   `changes`, `decision_threads`, `decision_items`, `workflow_runs`, `workflow_steps`, `artifacts`, `context_snapshots`,
+   `changes`, `decision_threads`, `decision_items`, `workflow_runs`, `workflow_steps`,
+   `artifacts`, `artifact_edges`, `context_snapshots`,
    `spec_learning_candidates`, `incidents`, `projection_jobs`, `telemetry`,
    `specs_refs`, and `migration_history`; the CLI calls
    those tools over stdio rather than opening its own writer. The
@@ -123,14 +143,18 @@ Two rules make this work:
 Subscribers always pull `events.id > since_id` rather than `max(ts)`,
 because two events may share the same millisecond timestamp (D31).
 
-### Memory ownership is outside Ultra Builder Pro
+### General memory and graph ownership remain outside Ultra Builder Pro
 
 Ultra Builder Pro does not retain prompts, transcripts, tool observations,
-session summaries, or cross-session memory. It ships no `memory.*` MCP family,
-no recall skill, and no memory-capture hook. A separately installed provider
-such as cloud-mem/claude-mem owns persistent memory and its own lifecycle. The
-only related migration surface is the explicit `ultra-tools legacy-memory`
-archive/prune command for data created by older releases.
+session summaries, general conversational memory, or code-graph payloads. It ships
+no `memory.*` MCP family, general recall skill, or memory-capture hook. A separately
+installed provider such as cloud-mem/claude-mem owns general persistent memory and
+its own lifecycle. Ultra stores only bounded provider metadata references needed by
+workflow context. The only related migration surface is the explicit
+`ultra-tools legacy-memory` inspect/archive/confirmed-prune command for general memory
+data created by older releases. It is never called by a hook, MCP operation, or
+session lifecycle; it does not collect, recall, reflect, or remove Ultra workflow
+authority.
 
 ### Project baseline adoption
 
@@ -197,9 +221,12 @@ alternatives, evidence refs, and durable effects; a partial unique index guarant
 current question per thread. The host ends that turn and waits.
 
 The next response becomes a normalized owner decision, explicit reversible delegation,
-or consequence-bearing deferral. Prompts and transcripts are never persisted. Routine
-settled state closes through `decision.complete`, which is lifecycle completion rather
-than another approval. Only a coherent cluster that needs an artifact-bound recovery
+or consequence-bearing deferral. Prompts and transcripts are never persisted. The host
+applies accepted intent through the owning MCP operation or digest-bound artifact,
+reads it back, and records typed `applied_refs` when another authority changed. Routine
+settled state then closes through `decision.complete`, which is lifecycle completion
+rather than another approval. The breadcrumb recalls normalized accepted intent after
+the thread closes. Only a coherent cluster that needs an artifact-bound recovery
 boundary moves through prepare/confirm checkpointing. Matching workflow steps fail
 closed while a blocking question, blocking deferral, prepared checkpoint, or stale
 checkpoint artifact remains. Supersession preserves prior history and reopens alignment
@@ -215,10 +242,11 @@ is represented by a `changes` row and an inspectable packet:
 ```text
 active -> blocked -> active -> ready -> archived
    |                              |
-   ├─ intent + delta + plan       └─ verification + baseline reconciliation
-   ├─ linked tasks
-   ├─ immutable context snapshots (role + gate + readiness + execution seam)
-   └─ spec-learning candidates (proposed -> approved/rejected -> applied)
+   ├─ intent + adaptive research + findings
+   ├─ typed delta + documentation reconciliation + deterministic progress
+   ├─ plan + linked tasks + immutable contexts
+   ├─ Change-scoped test/review/delivery evidence
+   └─ atomic baseline apply + self-contained archive
 ```
 
 `quick`, `standard`, `major`, and `incident` kinds require different evidence,
@@ -226,6 +254,18 @@ but all require completed linked tasks, current context, declared documentation
 impact, and no open incident. Memory and graph payloads never enter Ultra;
 `context_snapshots.provider_refs_json` stores metadata references only.
 
+Baseline files are immutable while a Change is active. `change.delta` registers
+overlay payloads against exact baseline revision and specification digests.
+`change.documentation_reconcile` records exact document before/after evidence and
+consumer trace. Standard and major convergence requires both current authorities.
+`change.archive` preflights the whole write set and uses a recoverable transaction;
+only after all writes and baseline reconciliation succeed does it rebind the complete
+Change root into the archive.
+
+Workflow revisions preserve prior accepted runs. A candidate becomes current only
+through `workflow.supersede`; the artifact graph then invalidates the prior run's true
+transitive consumers without staling unrelated tasks.
+
 ### Context Spine
 
 Context Manifest v3 is the immutable handoff contract between planning,
@@ -292,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/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
@@ -309,7 +375,7 @@ A **session** is the standard unit of execution across all four runtimes
 - an isolated `git worktree` created by `session.spawn`,
 - an ignored `.ultra` link from that checkout to the one central authority,
 - a lease + heartbeat row in `sessions` (D32),
-- an `artifact_dir` under `.ultra/sessions/<sid>/` for logs and scratch;
+- an `artifact_dir` under `.ultra/.runtime/sessions/<sid>/` for logs and scratch;
 - either the active host operating in that exact worktree or an explicitly configured
   worker process.
 
@@ -371,7 +437,7 @@ rejects corrupt, non-object, schema-mismatched, or terminal candidates, and
 selects the newest valid state. A newer live state wins; a newer checkpoint can
 atomically restore a missing or older live state before context is re-injected.
 The checkpoint is therefore a recovery artifact and consumer, never a second
-durable authority alongside `.ultra/state.db`.
+durable authority alongside `.ultra/.runtime/state.db`.
 
 ## 7. Installation provenance — read-only cross-host diagnosis
 
@@ -424,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) |
 
@@ -437,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

@@ -0,0 +1,274 @@
+# Ultra artifact authority
+
+This document defines what `.ultra/` remembers across sessions, which surface owns
+each fact, and how working output becomes durable Ultra authority.
+
+## Boundary
+
+`.ultra/` is the project-local cross-session workflow-memory envelope for Ultra
+Builder Pro. It retains normalized intent, lifecycle progress, tasks, bounded execution
+context, specifications, evidence, provenance, recovery state, and external provider
+references. It is not a general conversational-memory system and does not retain raw
+prompts, transcripts, chain-of-thought, general episodic summaries, or code-graph
+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. `.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 |
+|---|---|---|
+| 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 | `.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 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
+
+| Actor | Responsible for | Must not do |
+|---|---|---|
+| 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 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 MCP-owned checkpoint and generated projection paths | Select a semantic route or block ordinary development |
+
+## Intent persistence
+
+The interaction sequence is:
+
+```text
+inspect -> suggest -> host-native ask -> normalize -> persist -> apply -> read back
+```
+
+The host-native ask is conditional. An explicit owner instruction can already resolve
+a choice, so the model must not ask
+again merely to manufacture proof. When interaction is needed, the adapter uses the
+host-native question surface. Once the model writes the normalized result through
+`decision.resolve`, `decision.delegate`, or `decision.defer`, the DB treats that result
+as current cross-session intent authority. It does not store or verify a UI receipt,
+raw prompt, or transcript.
+
+If the accepted decision changes another Ultra authority, the model applies that change
+through its owning MCP tool or digest-bound artifact, reads the result back, and passes
+typed `applied_refs` to `decision.complete`. A decision whose normalized record is
+itself the complete authority may have no applied reference. Breadcrumb and decision
+read paths recall accepted intent only after the dialogue thread is completed or
+confirmed. A row-backed applied reference names an exact field and canonical value,
+with an optional digest of that value. A specification or artifact reference names
+the exact file digest. Row existence alone never proves that intent was applied.
+
+## Promotion and evidence
+
+Working material becomes durable only when all applicable conditions hold:
+
+1. the active workflow permits the write;
+2. consequential claims are verified against the checkout, runtime, test result, or
+   primary source;
+3. the model writes through the owning MCP operation or immutable artifact path;
+4. the DB records the owning baseline, change, workflow, task, or artifact reference;
+5. content-bearing files match the recorded SHA-256 digest and scope;
+6. the model reads back the resulting state before reporting completion.
+
+The durable evidence trail may include normalized decisions, delegation source,
+durable effects, typed applied references, workflow-step evidence, artifact hashes,
+verification commands and results, provenance, events, and recovery state. It must not
+include chain-of-thought, UI-click proof, raw prompts, or conversation transcripts.
+
+Verified conclusions from `.ultra/.runtime/collab/` or other scratch locations must be promoted
+into the invoking DB-bound workflow artifact or report. Keeping a file in the scratch
+directory is not promotion.
+
+## Change overlay authority
+
+An active Change is an isolated overlay below
+`.ultra/changes/active/<change-id>/`. Its intent, adaptive research, `findings.md`,
+typed delta payloads, plan, contexts, documentation payloads, progress projection,
+test reports, review artifacts, and delivery evidence remain below that root. Change
+research never edits baseline specifications.
+
+`change.delta` registers exact baseline id, repository revision, specification
+digests, accepted decisions, non-goals, acceptance, documentation impact, unknowns,
+and every semantic mutation's before/after digest. A no-semantic-change result is an
+explicit typed delta, not an absent file. `progress.md` is a deterministic projection
+of the registered delta and documentation state; it is never an independent status
+authority.
+
+`change.documentation_reconcile` binds the current delta id and digest, every changed
+document's before/after digest, delta and acceptance references, verification, and a
+verified consumer or explicit no-consumer reason. Standard and major delivery require
+one current reconciliation even when its document set is empty.
+
+`change.archive` preflights the complete target set before writing, applies overlay
+bytes through a recoverable local transaction, refreshes baseline digests, moves the
+complete Change root to its archive location, and rebinds registry paths. A conflict,
+crash, or DB failure must roll back or resume the whole packet; no subset is reported
+as delivered.
+
+## Context and plan authority
+
+`change.context` is a pure compiler. It reads accepted Change, task, baseline, checkout,
+and provider-reference authority and writes one immutable manifest plus its DB snapshot
+row. It never updates provider references or semantic Change fields. Each snapshot is
+identified exactly by `change_id`, nullable `task_id`, `role`, and `gate`; consumers
+must not substitute a newer snapshot from a different tuple.
+
+Context refs preserve `expected_digest`, `anchor`, `scope`, and `freshness_policy`.
+Digest-bound refs are revalidated at the consuming gate, existence-bound implementation
+targets may change while remaining present, and advisory drift is retained as a
+warning. File bodies stay lazy. Implementation manifests inline only the selected task,
+its direct dependency/integration neighborhood, and its task-context contract.
+
+A current plan is a Change-owned pair:
+
+- `<artifact_root>/plan.json` is the machine-readable topology and exact planning
+  context binding;
+- `<artifact_root>/plan.md` is the deterministic human projection of the same plan and
+  task contracts.
+
+`plan.export` selects both paths from the owning Change and accepts no arbitrary output
+path. `verify-plan` binds the JSON digest and the preceding `plan/planning` snapshot;
+the artifact registry records both plan files with that context provenance. Publication
+preflights both path authorities and prior digests, rejects symlinked ancestors or
+targets, and journals the two file replacements so a registry or event failure restores
+both prior files while the SQLite transaction rolls back. The global
+`.ultra/execution-plan.json` remains readable only for explicit legacy migration and is
+never current write or dispatch authority.
+
+## Registry contract
+
+`artifact.record` is the public writer for a semantic or evidence file that is not
+already registered by its owning workflow operation. Every managed registry row has:
+
+- a typed `owner_type` and `owner_id`;
+- an artifact `kind`, project-relative `path`, lifecycle `status`, and SHA-256
+  `digest`;
+- `before_digest` and `after_digest` values for optimistic write validation and
+  change evidence;
+- structured `provenance` and optional metadata;
+- normalized source and consumer edges in `artifact_edges`.
+
+The write replaces all edges for the artifact in one immediate SQLite transaction.
+It never accumulates stale edges with `INSERT OR IGNORE`. If an existing digest
+changes, the same transaction emits `spec_changed`, marks only reachable artifact
+and task consumers stale through typed artifact/task/workflow/change intermediates,
+and records the exact invalidated endpoints. Self-edges and dependency cycles are
+rejected without changing prior authority. A caller can provide
+`expected_before_digest`; a mismatch fails without changing the row or its edges.
+
+`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, 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,
+plan, test, review, delivery, archive reconciliation, and specification learning
+cannot update a managed digest or provenance through a parallel SQL path.
+
+Rows migrated from pre-20 schemas remain readable and preserve their original IDs,
+paths, hashes, timestamps, and legacy change/task ownership. They are marked
+`managed = 0` until an owning workflow or `artifact.record` supplies complete
+provenance and dependency edges. This compatibility state preserves data without
+pretending that an old row satisfies the current registry contract.
+
+## Dependency and orphan diagnosis
+
+`system.doctor` compares the registry, dependency graph, filesystem, and owner
+tables. It reports:
+
+- unregistered semantic or evidence files;
+- registered files that are missing or whose digest/status is stale;
+- missing typed owners;
+- current managed artifacts without a consumer, unless explicitly terminal;
+- dangling source or consumer endpoints;
+- graph cycles that cannot become consumer evidence;
+- more than one active authority for the same canonical path;
+- legacy compatibility rows that remain unmanaged;
+- 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 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
+empty templates. Doctor and status expose registered, managed, and unmanaged counts,
+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/.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`.
+The next context projection references that authority. Editing the task-context body
+or an accepted baseline specification directly is neither persistence nor promotion.