ultra-builder-pro-cli 0.21.1 → 0.23.0

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
 
@@ -54,14 +59,12 @@ inspect -> suggest -> host-native ask -> normalize -> persist -> apply -> read b
 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.
+host-native question surface. Once the model batches the normalized result through
+`ultra.record`, 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
+through `ultra.record` or a digest-bound artifact and reads the result back. 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,
@@ -72,7 +75,7 @@ the exact file digest. Row existence alone never proves that intent was applied.
 
 Working material becomes durable only when all applicable conditions hold:
 
-1. the active workflow permits the write;
+1. the current Change and owner authority permit 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;
@@ -117,9 +120,9 @@ 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
+The Context compiler used by `ultra.checkpoint` 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.
 
@@ -136,8 +139,8 @@ A current plan is a Change-owned pair:
 - `<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 Plan checkpoint selects both paths from the owning Change and accepts no arbitrary
+output path. It 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
@@ -147,7 +150,7 @@ never current write or dispatch authority.
 
 ## Registry contract
 
-`artifact.record` is the public writer for a semantic or evidence file that is not
+`ultra.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`;
@@ -169,8 +172,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,
@@ -185,7 +188,7 @@ pretending that an old row satisfies the current registry contract.
 
 ## Dependency and orphan diagnosis
 
-`system.doctor` compares the registry, dependency graph, filesystem, and owner
+`ultra.doctor` compares the registry, dependency graph, filesystem, and owner
 tables. It reports:
 
 - unregistered semantic or evidence files;
@@ -196,11 +199,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 +213,59 @@ 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.
+
+`ultra.sync { action: 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
+`ultra.sync { action: 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          (7 public kernel tools + 60 hidden compatibility operations)
 ├── 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 with a 7-tool public façade)
 ├── 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

@@ -46,17 +46,18 @@ 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 |
+| Session context/health | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, native JS plugin injects only an active-workflow breadcrumb; health via `ultra.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 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,8 @@ 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 |
+| Public discovered MCP tools | 7 | 7 | 7 | 7 |
+| Hidden 0.22 compatibility operations | 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,12 +77,13 @@ 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.*`,
-`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.
+All hosts discover the seven `ultra.*` persistence and safety tools. The sixty
+fine-grained 0.22 operations remain callable but undiscoverable for one compatibility
+release; new Skills do not call them. Review, impact discovery, skill loading, model
+reasoning, and user interaction remain host-native surfaces.
 
 When a native structured question surface is unavailable, the shared interaction
 contract permits one concise direct question only if ordinary conversation is still