ultra-builder-pro-cli 0.20.0 → 0.22.0

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,13 +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/state.db` is the only durable Ultra lifecycle authority. Generated JSON
-and Markdown are projections or evidence artifacts. Prompt text, chat history,
-external memory, and code-graph payloads are not Ultra authority.
+`.ultra/` is project-local cross-session workflow memory. `.ultra/.runtime/state.db` is
+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
 
@@ -34,7 +39,10 @@ MCP validates generic invariants: selected identifiers must exist, dispositions
 must be legal, reused or excluded evidence must be referenced, synthesis must be
 active, and at least one non-synthesis area must be applicable. MCP does not
 choose the coverage set or prove how the owner answered. Once normalized intent
-is written, `.ultra/state.db` treats it as current cross-session authority.
+is written, `.ultra/.runtime/state.db` treats it as current cross-session authority. If
+that intent changes another Ultra authority, the host applies the change,
+reads it back, and records typed applied references when completing the
+decision thread.
 
 ## Lifecycle boundaries
 

package/docs/LEGACY-CLI-CROSSWALK.md

@@ -37,8 +37,9 @@ contract and adds stronger authority, recovery, or portability.
 
 The following are deliberate extensions built on the original spine:
 
-1. `.ultra/state.db` as the only lifecycle authority; Markdown and JSON are artifacts
-   or projections.
+1. `.ultra/.runtime/state.db` as the only lifecycle and index authority; registered
+   digest-bound Markdown and JSON carry semantic or evidence bodies, while generated
+   views remain projections.
 2. Typed MCP transitions for baseline, change, decision, workflow, task, session,
    incident, projection, and evidence state.
 3. Greenfield, brownfield, monorepo-scope, migrated, restore, and rebaseline paths.
@@ -52,12 +53,16 @@ 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
 
 These items are not compatibility losses:
 
-- embedded prompt, transcript, observation, summary, or cross-session memory;
+- embedded prompt, transcript, observation journal, session summary, or general
+  conversational cross-session memory;
 - an internal code graph or memory store;
 - retired model runtimes and their prompts;
 - retired command-proxy integrations;
@@ -83,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
@@ -99,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
@@ -121,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
@@ -146,7 +153,7 @@ status
 | Dependency waves advanced after transport exit | The plan pauses at the first non-terminal wave and resumes only after its DB tasks converge. |
 | A crafted or merely exported plan could bypass current plan authority | Change-owned dispatch requires a healthy completed plan workflow and the exact current DB graph; malformed, cyclic, stale, duplicate-task, or cross-change plans fail before session creation. |
 | Direct session or daemon spawn bypassed the current plan | Every change-owned admission and spawn revalidates current task-contract digests, task set, dependencies, and staleness before takeover or worktree creation. |
-| A worker launched inside a worktree could create a second `.ultra/state.db` | Every session checkout links its ignored `.ultra` entry to central authority and receives non-overridable DB/root bindings; legacy repositories get a local `info/exclude` rule without tracked drift, while unsafe ignore or link state rolls back before worker launch. |
+| A worker launched inside a worktree could create a second `.ultra/.runtime/state.db` | Every session checkout links its ignored `.ultra` entry to central authority and receives non-overridable DB/root bindings; legacy repositories get a local `info/exclude` rule without tracked drift, while unsafe ignore or link state rolls back before worker launch. |
 | Plan authority could drift between wave admission and actual spawn | The spawn-time gate converts this race into an authority pause without task-failure or circuit-breaker evidence. |
 | Explicit auto-merge could integrate before workflow gates | A change-owned auto-merge requires the exact completion commit, ready dev evidence, a current task review, and clean committed Git work; otherwise the worktree is preserved. |
 | Session close or auto-merge could delete uncommitted work | Close preserves by default; explicit cleanup verifies clean and integrated Git ancestry. |
@@ -154,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

@@ -12,7 +12,8 @@ An adapter may write only:
 - the plugin's own provenance and managed-file markers.
 
 The first command allowed to create project authority is `ultra-init`. Once invoked,
-Ultra owns only the repository-local `.ultra/` authority and its generated projections.
+Ultra owns only the repository-local `.ultra/` workflow-memory envelope and its
+MCP-published checkpoint plus generated local projections.
 
 ## Surfaces Ultra does not own
 
@@ -21,7 +22,7 @@ Install, update, doctor, and uninstall must not create, rewrite, trim, merge, or
 - user-level `CLAUDE.md`, `AGENTS.md`, or equivalent instruction files;
 - repository-level instruction files;
 - project source, Git history, remotes, or `.ultra/` data;
-- memory or code-graph provider data.
+- general memory or code-graph provider data.
 
 Existing Ultra marker blocks in a user handbook are legacy user content after this
 contract takes effect. They are not silently removed because the plugin cannot prove
@@ -44,10 +45,11 @@ Internal review-rule skills remain available only to their bounded workers.
 
 ## Idle behavior
 
-Outside a repository containing `.ultra/state.db`, all Ultra hooks are silent. Inside
+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

@@ -40,7 +40,7 @@ sharing one authoritative workflow store.
 | 5     | Recovery + staleness + auto-routing            | ✅ done (D43) → v0.2 |
 | 6     | Monitoring + telemetry                          | ✅ done (D44) → v0.2 |
 | 4.6b  | Full conformance suite                         | ✅ done (D45) — 20 conformance + 21 resolveTarget tests |
-| 7     | tagged tasks + skill mining; retired Ultra memory delegated to external providers | ✅ superseded by the package-boundary cleanup |
+| 7     | tagged tasks; non-core generation and retention surfaces removed from the plugin | ✅ superseded by the package-boundary cleanup |
 | 8A    | Plan automation (parse / topo / expand + artifact + human gate) | ✅ done (D47, `a932cb8`) → v0.3 |
 | 8B    | Execution automation (dispatch / parallel worktree / merge) | ✅ done (D48, `8224159`) — **v0.3 ready** |
 | 8C    | Continuous change packets + context compiler + convergence + doctor | ✅ done (D52) |
@@ -50,20 +50,21 @@ sharing one authoritative workflow store.
 | 13    | Durable init-to-delivery workflows + task execution contracts + immutable stage evidence | ✅ done |
 | 16    | Resumable one-question owner-agent decisions + artifact checkpoints + workflow gates | ✅ done |
 | 19    | Non-ceremonial decision completion + four-host semantic-selection contract | ✅ done |
+| 20    | Typed artifact registry + normalized dependency graph + orphan diagnostics | ✅ done |
 | 9     | Release pipeline                               | npm tag publishing live; Homebrew / pip not implemented |
 
 ## What is in the repo today
 
 ```
 spec/                       ← Phase 1 single source of truth
-├── mcp-tools.yaml          (51 live tools across 8 families)
+├── mcp-tools.yaml          (60 live tools across 9 families)
 ├── cli-protocol.md         (CLI ↔ MCP mapping table)
 ├── schemas/                (state-db.sql + 4 JSON schemas)
 ├── fixtures/{valid,invalid}/  (+ v4.4-project for migration)
 └── scripts/test-all.cjs    (npm run test:spec — 7 validation stages)
 
 mcp-server/                 ← Phase 2 authoritative state layer
-├── server.cjs              (stdio MCP server, 51 task/session/baseline/change/decision/workflow/system/plan tools)
+├── server.cjs              (stdio MCP server, 60 task/session/baseline/change/decision/workflow/artifact/system/plan tools)
 ├── lib/
 │   ├── state-db.cjs        (SQLite + WAL + pragmas)
 │   ├── state-ops.cjs       (full write API, status state machine)
@@ -81,9 +82,22 @@ ultra-tools/                ← CLI fallback, migration, and diagnostics
     └── legacy-memory.cjs   (explicit inspect/archive/confirmed prune)
 
 bin/install.js              ← multi-runtime installer
-adapters/                   ← native Claude/OpenCode/Codex plugin builders
+adapters/                   ← native host plugin builders
+├── claude.js
+├── opencode.js
+├── codex.js
+└── kimi.js
 skills/                     ← allowlisted Ultra workflows, internal rules, and collab companions
-hooks/                      ← 7 executable workflow hooks + shared Context Spine helper; OpenCode uses native JavaScript hooks
+hooks/                      ← allowlisted workflow hooks; OpenCode uses native JavaScript hooks
+├── active_task_context.py
+├── context_spine.py
+├── health_check.py
+├── pre_stop_check.py
+├── runtime_paths.py
+├── subagent_tracker.py
+├── workflow_checkpoint.py
+├── workflow_context.py
+└── workflow_resume.py
 docs/
 ├── DECISIONS.md                 current authority and package boundaries
 ├── ARCHITECTURE.md              Phase 1 single-page entry point
@@ -92,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

@@ -14,29 +14,29 @@ not installed.
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | Package form | `.claude-plugin` native plugin | native config bundle + JS plugin | personal `.codex-plugin` | managed `kimi.plugin.json` plugin |
-| Public entry | `/ultra-*`, `/learn` | `/ultra-*`, `/learn` | `$ultra-builder-pro:<skill>` | `/ultra-builder-pro:<command>` |
-| Public Ultra workflows | 12, model invocation disabled | 12 commands backed by private workflow assets | 12, implicit invocation disabled | 12, model invocation disabled |
+| Public entry | `/ultra-builder-pro:ultra-*` | `/ultra-*` | `$ultra-builder-pro:ultra-*` | `/ultra-builder-pro:ultra-*` |
+| Public Ultra capabilities | 11, model invocation disabled | 11 commands backed by private workflow assets | 11, implicit invocation disabled | 11, model invocation disabled |
 | Internal agent-rule skills | 4, non-user-facing | 4, non-user-facing | 4 with implicit invocation disabled | 4, consumed by review workers |
 | Collaboration companions | `codex-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` | `cc-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` |
 | Automatic workflow bootstrap | N/A | N/A | N/A | N/A |
 | External browser/deploy/framework skills | N/A | N/A | N/A | N/A |
 
-Codex converts workflows into namespaced skills and records eleven legacy
+Codex converts workflows into namespaced skills and records ten compatibility
 command mappings in `command-map.json`; `ultra-review` remains directly
-invocable as a skill. Kimi registers all twelve commands through its native
+invocable as a skill. Kimi registers all eleven commands through its native
 plugin command directory and exposes the allowlisted skills independently.
 
 ## 2. Agents and collaboration
 
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
-| Bundled review/debug workers | FULL, native Markdown agents | FULL, native agent frontmatter | FULL, nine managed TOML agents | FUNCTIONAL, nine prompt templates consumed by `Agent` / `AgentSwarm` |
+| Bundled review/debug workers | FULL, native Markdown agents | FULL, native agent frontmatter | FULL, 10 managed TOML agents | FUNCTIONAL, 10 prompt templates consumed by `Agent` / `AgentSwarm` |
 | Plugin custom-agent registration | FULL | FULL | FULL | N/A; the 0.26 manifest has no custom-agent field |
 | Native bounded delegation | native agent surface | native agent surface | native Codex subagents | native `Agent` / `AgentSwarm` |
 | Cross-host advisor | explicit and read-only | explicit and read-only | explicit and read-only | explicit and read-only |
 | Primary-agent ownership | FULL | FULL | FULL | FULL |
 
-No bundled worker owns private persistent memory. It receives current-checkout
+No bundled worker owns private conversational memory. It receives current-checkout
 evidence and bounded context from the primary host, then returns a result for
 primary verification. On Kimi, the review workflow reads the bundled worker
 template before creating the corresponding `AgentSwarm` item; the templates are
@@ -47,16 +47,17 @@ not presented as nonexistent custom agents.
 | Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | Session context/health | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, native JS plugin injects only an active-workflow breadcrumb; health via `system.doctor` | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, active-workflow breadcrumb via native hooks |
-| Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
+| Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects managed checkpoint/projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
 | Pre-compact checkpoint | FULL | FULL | FULL | FULL, native `PreCompact` |
 | Post-compact context injection | FULL | FULL, native compacting context | FULL, native `PostCompact` restore | DEGRADED; checkpoint restoration runs, but Kimi 0.26/0.27 does not reinject fire-and-forget hook text |
 | Stop lifecycle advisory | FULL, native non-blocking `Stop` | N/A, no equivalent stop event needed | FULL, native non-blocking `Stop` | FULL, native non-blocking `Stop` |
 | Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | FULL, native `SubagentStart` / `SubagentStop` |
 
 Health/context, compact, stop, and subagent hooks remain silent unless
-`.ultra/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,16 +68,19 @@ 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 | 51 | 51 | 51 | 51 |
+| Live/declared contracts | 60 | 60 | 60 | 60 |
 | Structured user alignment | `AskUserQuestion` in interactive sessions | `question` when permission is not denied | `request_user_input` when the current mode exposes it | `AskUserQuestion` outside auto mode |
 | Greenfield/brownfield baseline adoption | FULL | FULL | FULL | FULL |
 | Context Manifest v3 / breadcrumb | FULL | FULL, same bundled read-only DB reader as every hook | FULL | FULL |
 | Approval-gated spec learning | FULL | FULL | FULL | FULL |
 | Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` | native Kimi tools and workers |
-| Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
-| Ultra memory API | N/A | N/A | N/A | N/A |
+| 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 51 `task.*`, `session.*`, `baseline.*`, `change.*`, `decision.*`, `workflow.*`, `system.*`, and `plan.*` operations
+All 60 `task.*`, `session.*`, `baseline.*`, `change.*`, `decision.*`,
+`workflow.*`, `artifact.*`, `system.*`, and `plan.*` operations
 registered by `mcp-server/server.cjs` are live. Review, impact discovery, skill
 loading, and user interaction remain host-native surfaces.
 
@@ -91,6 +95,15 @@ generated launcher recovers the project from the inherited `PWD`, sets
 cannot be established. On POSIX it intentionally uses `env node` because Kimi
 0.26/0.27's embedded Node ABI differs from the ABI used to install `better-sqlite3`.
 
+Archive finalization and archive-journal recovery use an adjacent, explicitly
+packaged Python 3 worker. The worker accepts only bounded, basename-only
+operations and performs mutations relative to inherited, identity-checked
+directory descriptors. This boundary requires a POSIX Python runtime with
+`dir_fd`, no-follow `stat`, and `O_NOFOLLOW` support. If that prerequisite is
+missing, archive operations fail closed with `ARCHIVE_RUNTIME_UNAVAILABLE`;
+Ultra never falls back to ancestor-sensitive pathname mutation. Other MCP
+operations remain available.
+
 ## 5. User instruction isolation
 
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
@@ -135,9 +148,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `19.0` |
+| Current state schema | `20.0` |
 | Runtime values | `claude`, `opencode`, `codex`, `kimi` |
-| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, authoritative baseline adoption in 11.0, repository evidence in 12.0, durable workflows in 13.0, continuous baseline revalidation in 14.0, typed research semantics and verified reconciliation in 15.0, resumable owner-agent decision threads and workflow alignment gates in 16.0, explicit unborn-Git authority in 17.0, adaptive transitions and legacy workflow normalization in 18.0, then non-ceremonial decision completion in 19.0 |
+| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, authoritative baseline adoption in 11.0, repository evidence in 12.0, durable workflows in 13.0, continuous baseline revalidation in 14.0, typed research semantics and verified reconciliation in 15.0, resumable owner-agent decision threads and workflow alignment gates in 16.0, explicit unborn-Git authority in 17.0, adaptive transitions and legacy workflow normalization in 18.0, non-ceremonial decision completion in 19.0, then typed artifact ownership and normalized dependency edges in 20.0 |
 | Preservation gate | rows, IDs, indexes, foreign keys, telemetry, incidents, and migration history remain intact |
 | Failure behavior | rollback; no partially upgraded authority database |
 

package/docs/STATE-DB-ACCESS-POLICY.md

@@ -1,13 +1,16 @@
-# `.ultra/state.db` access policy
+# `.ultra/.runtime/state.db` access policy
 
 > Multi-process access contract. Current authority is defined by
 > [`DECISIONS.md`](./DECISIONS.md) and the live database schema.
 
-`.ultra/state.db` is the only authoritative state store for baselines, changes,
-decision threads/items, tasks, workflow runs/steps, events, sessions, incidents,
-projections, telemetry, and spec references
-(D18, D52, D54). Every process
-that touches it must follow the rules below; deviations are bugs.
+`.ultra/.runtime/state.db` is the checkout-local lifecycle, index, transition,
+freshness, and coordination authority for baselines, changes, decision threads/items, tasks,
+workflow runs/steps, events, sessions, incidents, projections, telemetry, and spec
+references (D18, D52, D54). Registered digest-bound files carry semantic and evidence
+bodies; the DB owns their references and current digests. The tracked
+`.ultra/tasks/tasks.json` is an MCP-published handoff checkpoint, not a parallel live
+writer. Every process that touches the DB must follow the rules below; deviations are
+bugs.
 
 ## 1. Three-role write matrix
 
@@ -64,7 +67,7 @@ WAL is part of the authority contract, not an optional performance setting.
 `openStateDb` asks SQLite to enable WAL and checks the actual returned mode. If
 the storage layer returns anything else, startup fails with
 `STATE_DB_WAL_UNAVAILABLE`. Ultra does not silently downgrade to a different
-concurrency model. Move `.ultra/state.db` to storage that supports SQLite WAL or
+concurrency model. Move `.ultra/.runtime/state.db` to storage that supports SQLite WAL or
 resolve the mount/runtime constraint before retrying.
 
 ## 4. Where each table is owned
@@ -74,9 +77,10 @@ resolve the mount/runtime constraint before retrying.
 | `baselines`        | MCP server (`baseline.start` / `baseline.record` / `baseline.converge`); initialization and legacy-projection migration may create only the first draft or compatibility row |
 | `tasks`            | MCP server (`task.create` / `task.update` / `task.delete`) |
 | `changes`          | MCP server (`change.create` / `change.update` / `change.converge` / `change.archive`) |
-| `decision_threads`, `decision_items` | MCP server (`decision.thread_start` / `decision.open` / `decision.resolve` / `decision.delegate` / `decision.defer` / `decision.supersede` / `decision.complete` / `decision.checkpoint`); only pending questions needed for recovery, normalized choices, lifecycle completion, and optional artifact checkpoints are stored, never prompts or transcripts |
+| `decision_threads`, `decision_items` | MCP server (`decision.thread_start` / `decision.open` / `decision.resolve` / `decision.delegate` / `decision.defer` / `decision.supersede` / `decision.complete` / `decision.checkpoint`); pending recovery state, normalized accepted intent, durable effects, typed applied references, lifecycle completion, and optional artifact checkpoints are stored, never UI receipts, prompts, or transcripts |
 | `workflow_runs`, `workflow_steps` | MCP server (`workflow.start` / `workflow.step` / `workflow.complete`); skills provide evidence inputs but never write rows directly |
-| `artifacts`, `context_snapshots`, `spec_learning_candidates`, `trace_links` | MCP server through change lifecycle tools |
+| `artifacts`, `artifact_edges` | MCP server (`artifact.record`); workflow-owned registration may use the same internal registry transaction |
+| `context_snapshots`, `spec_learning_candidates`, `trace_links` | MCP server through change lifecycle tools |
 | `incidents`, `projection_jobs`, `event_consumers`, `circuit_breaker` | MCP server; backup-first doctor recovery may perform only documented mechanical transitions |
 | `events`           | MCP server for lifecycle events; approved processes and `task.append_event` for allowlisted append-only observations |
 | `sessions`         | MCP server (`session.spawn` / `session.close` / `session.heartbeat`); orchestrator may write status transitions |
@@ -85,10 +89,33 @@ resolve the mount/runtime constraint before retrying.
 | `migration_history`| schema initializer and `ultra-tools migrate` or doctor repair |
 | `schema_version`   | schema initializer, `ultra-tools db init`, migration, and doctor repair |
 
-## 5. Forbidden patterns
+## 5. Git team checkpoint
 
-- **No file copies for state.** Don't `cp .ultra/state.db
+Only `task.ledger_publish` may derive `.ultra/tasks/tasks.json` from SQLite, and only
+`task.ledger_import` may merge it into SQLite. Server startup performs one import after
+opening project authority; later pulls in a long-running process require an explicit
+import. The same checkpoint is idempotent and must not append an event again.
+
+The checkpoint carries portable baseline, Change, and durable task records with
+per-record revisions and digests. It excludes local `in_progress` ownership, sessions,
+leases, worktrees, telemetry, and completion commit hashes. Import validates document
+ancestry plus record-level common bases. It fast-forwards clean records and fails
+before commit on same-record concurrency, parent/owner gaps, non-descendant history, or
+an active-task collision. A Git-ready baseline is downgraded to checkout-local
+revalidation rather than trusted as execution authority.
+
+Legacy v4.4/v4.5 task projections are backed up and replaced only when every available
+durable field matches current SQLite. Doctor reports checkpoint condition but never
+performs semantic import, publication, or conflict selection.
+
+## 6. Forbidden patterns
+
+- **No file copies for state.** Don't `cp .ultra/.runtime/state.db
   somewhere/state.db` and edit; use `ultra-tools db backup`.
+- **No direct checkpoint edits.** Don't merge or repair
+  `.ultra/tasks/tasks.json` by hand; use the typed import/publish conflict path.
+- **No committed live projections.** `.ultra/.runtime/projections/**` remains ignored
+  checkout-local output.
 - **No long-held writer connections** outside the MCP server. Pop a
   short transaction, finish, close.
 - **No `PRAGMA journal_mode` toggling at runtime** by any process other
@@ -98,14 +125,14 @@ resolve the mount/runtime constraint before retrying.
 - **No `vacuum` / `wal_checkpoint(TRUNCATE)` from inside a transaction.**
   Maintenance subcommands open their own connection.
 
-## 6. Maintenance windows
+## 7. Maintenance windows
 
 `ultra-tools db checkpoint` and `ultra-tools db vacuum` are safe to run
 while the MCP server is up (they take their own connection and obey the
 busy timeout). `db backup` uses better-sqlite3's online `.backup` API
 and produces a consistent snapshot without blocking writers.
 
-## 7. Verification
+## 8. Verification
 
 The contract on this page is enforced by:
 
@@ -117,3 +144,6 @@ The contract on this page is enforced by:
   status transitions, task contracts, and event coupling.
 - `mcp-server/lib/workflow-state.test.cjs` — ordered workflow transitions,
   evidence/output requirements, blocking/resume, and cross-stage gates.
+- `mcp-server/lib/task-ledger.test.cjs` — portable-field filtering, digest ancestry,
+  idempotent import, baseline/Change/task fast-forward and conflict behavior, legacy
+  backup, and active-session protection.