ultra-builder-pro-cli 0.20.0 → 0.21.1

package/docs/ARCHITECTURE.md

@@ -10,10 +10,11 @@
 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`).
+store (`.ultra/.runtime/state.db`).
 
-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 +39,20 @@ 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/tasks/contexts/*.md  (fully generated read-only view)
               .ultra/activity-log.json    (optional dump)
 ```
 
 | 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 57 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 +65,19 @@ 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`
+## 3. Workflow memory and authoritative state
 
-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
+Together, `.ultra/` retains project-local cross-session workflow memory:
+normalized intent, progress, tasks, bounded context, specifications, evidence,
+provenance, and recovery. `.ultra/.runtime/state.db` is the sole authority for lifecycle,
+indexing, transitions, freshness, and coordination. Registered digest-bound files
+carry semantic and evidence bodies. Generated projections and working scratch do
+not become authority merely because they live under `.ultra/`. The complete
+classification and promotion contract is
+[`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 +92,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 +109,15 @@ 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;
+   in JSON files. `tasks.json` and the complete
+   `contexts/task-*.md` files are **projections** generated by the projector;
    manual edits are overwritten on the next state.db change.
 
 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 +135,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 +213,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 +234,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 +246,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,
@@ -296,7 +328,7 @@ swallowed warning. `system.doctor` is read-only by default. Explicit repair perf
 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.
+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.
 
@@ -309,7 +341,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 +403,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
 

package/docs/ARTIFACT-AUTHORITY.md

@@ -0,0 +1,234 @@
+# 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 unless a team uses an explicit synchronization or artifact handoff.
+
+## 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 |
+| 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 |
+| 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.
+
+## 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 views, 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 |
+
+## 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, `tasks.json`, 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;
+- generated task contexts whose task no longer exists.
+
+`.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
+`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.
+
+## 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.
+
+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.

package/docs/DECISIONS.md

@@ -15,9 +15,12 @@ release-version authority.
 | 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 |
 
-`.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
+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).
 
 ## Research coverage
 
@@ -34,7 +37,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.
@@ -57,7 +58,8 @@ The following are deliberate extensions built on the original spine:
 
 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;
@@ -146,7 +148,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. |

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
+generated 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,7 +45,7 @@ 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.

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          (57 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, 57 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