ultra-builder-pro-cli 0.19.1 → 0.21.1

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

@@ -9,28 +9,38 @@ release-version authority.
 
 | Layer | Owns | Must not own |
 |---|---|---|
-| User intent | Goals, acceptance, non-goals, 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, investigation, research coverage, solution design, task decomposition, context, test and review strategy, documentation impact, and next-action recommendations | Fabricated evidence, bypassed authorization, or durable lifecycle state |
+| 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 |
 | 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
 
 The research references form an optional semantic catalog. The host model
-selects only the areas justified by the current goal and evidence, records an
-evidence-based selection reason, and always includes synthesis. Omitted catalog
-areas create no workflow rows. An explicit `not_applicable` or accepted
-`deferred` entry is recorded only when preserving that exclusion is useful.
+inspects current evidence and recommends the smallest sufficient route. The
+owner selects, modifies, delegates, or defers that route through the current
+host's native question surface unless current intent already resolves it. The
+host then normalizes and records the accepted coverage with an evidence-based
+rationale and synthesis. Omitted catalog areas create no workflow rows. An
+explicit `not_applicable` or accepted `deferred` entry is recorded only when
+preserving that exclusion is useful.
 
 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.
+choose the coverage set or prove how the owner answered. Once normalized intent
+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

@@ -24,21 +24,22 @@ contract and adds stronger authority, recovery, or portability.
 | Original capability | Current implementation | Compatibility result |
 |---|---|---|
 | Init gathers project facts, creates Ultra files, and establishes Git | `task.init_project` performs deterministic classification, scaffold, schema, Git bootstrap, read-back verification, and then stops | Preserved and strengthened. Init has its own completion boundary and never starts research implicitly. |
-| Complete product and architecture research | `ultra-research` retains the semantic reference catalog while the model selects only applicable areas and records execute/verify/reuse/not-applicable/deferred dispositions as needed | Preserved without questionnaire overload. Necessary reports, typed semantic records, source digests, and material decision checkpoints add durable evidence. |
+| Complete product and architecture research | `ultra-research` retains the semantic reference catalog while the model recommends evidence-relevant coverage and the owner selects, modifies, delegates, or defers the route | Preserved without questionnaire overload. Accepted dispositions, necessary reports, typed semantic records, source digests, and optional material decision checkpoints add durable evidence. |
 | Planning converts accepted research into executable work with dependencies | `ultra-plan` persists complete change-owned task contracts and an exact dependency graph | Preserved and strengthened with topology, acceptance coverage, public seams, verification commands, and plan digests. |
 | Development uses isolated Git work, TDD, verification, review, commit, and integration | `ultra-dev`, `session.*`, and the session runner create real worktrees and retain task/review/commit evidence | Preserved and strengthened. Process exit cannot complete a task; uncommitted or unintegrated worktrees cannot be deleted. |
 | Test checks wiring, acceptance, regression, build, performance, security, and failures | `ultra-test` emits a change-bound immutable report covering each applicable dimension | Preserved and strengthened with HEAD, context, task-set, and report-digest validation. |
 | Review challenges specification fidelity and engineering quality | `ultra-review` is a first-class stage with independent specification and engineering axes | Strengthened. A coordinated summary cannot replace either complete axis. |
 | Delivery verifies clean readiness, documentation, build, and evidence | `ultra-deliver` requires current tasks, test, review, learning resolution, reconciliation, a local archive, and an immutable report | Preserved and strengthened. Publish, deploy, push, and other external effects remain separate explicitly authorized operations. |
 | Status restores the current workflow position | `ultra-status` reads DB authority, Git, sessions, artifacts, decisions, allowed transitions, and any hard recovery requirement | Strengthened. The host recommends the semantic route; projections and Prompt prose cannot override state. |
-| Thinking synchronizes owner and Agent intent | `ultra-think` plus `decision.*` persists one-question dialogue and artifact checkpoints | Strengthened. Observable facts are resolved first; only load-bearing owner choices block. |
+| Thinking synchronizes owner and Agent intent | `ultra-think` plus `decision.*` persists one-question dialogue, non-ceremonial completion, and optional artifact checkpoints | Strengthened. Observable facts are resolved first; only load-bearing owner choices block. |
 
 ## CLI-original capabilities
 
 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;
@@ -73,8 +75,9 @@ metadata references.
 ## Reference capability paths and gates
 
 These paths show common capability order and hard prerequisites. They are not a
-single mandatory pipeline: the host selects among MCP-reported allowed transitions,
-while MCP requires one route only for a unique mechanical recovery invariant.
+single mandatory pipeline: the model recommends among MCP-reported allowed
+transitions, while the owner selects or delegates the semantic route. MCP requires one
+route only for a unique mechanical recovery invariant.
 
 ### New repository
 
@@ -83,7 +86,7 @@ task.init_project
   -> greenfield classification
   -> Git bootstrap when absent
   -> init read-back and completion
-  -> explicit full research with model-selected coverage
+  -> explicit full research with a model-recommended, owner-selected route
   -> selected execute/verify/reuse work and synthesis
   -> owner-authorized local checkpoint commit when Git is unborn
   -> baseline.record
@@ -99,7 +102,7 @@ task.init_project
   -> brownfield classification and selected scope
   -> preserve current Git HEAD and dirty-state evidence
   -> init read-back and completion
-  -> explicit adoption research with model-selected coverage
+  -> explicit adoption research with a model-recommended, owner-selected route
   -> characterization verification + known-red/gap ledger
   -> baseline.record + owner approval
   -> baseline.converge
@@ -122,7 +125,8 @@ doctor/migrate with backup
 status
   -> change intent capture
   -> material alignment only when unresolved
-  -> host-selected bounded research, plan, current dev work, think, or status
+  -> 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
@@ -144,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) |
@@ -49,25 +49,27 @@ sharing one authoritative workflow store.
 | 12    | Repository evidence snapshots + gap ledger + migration re-adoption + incident governance | ✅ done |
 | 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          (50 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, 50 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)
 │   ├── baseline-workflow.cjs (project adoption + approval + reconciliation)
-│   ├── decision-dialogue.cjs (one-question authority + checkpoint gates)
+│   ├── decision-dialogue.cjs (one-question authority + completion/checkpoint gates)
 │   ├── workflow-state.cjs  (ordered stage runs, evidence, output digests, and gates)
 │   └── projector.cjs       (state.db → tasks.json + context md)
 └── tests/                  (npm run test:state)
@@ -80,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

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
@@ -54,7 +54,7 @@ not presented as nonexistent custom agents.
 | 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
+`.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,
 observation journaling, session-summary memory, generic command blocking, or
@@ -67,24 +67,41 @@ 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 | 50 | 50 | 50 | 50 |
+| Live/declared contracts | 57 | 57 | 57 | 57 |
+| 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` |
+| General memory-provider API | N/A | N/A | N/A | N/A |
 
-All 50 `task.*`, `session.*`, `baseline.*`, `change.*`, `decision.*`, `workflow.*`, `system.*`, and `plan.*` operations
+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.
 
+When a native structured question surface is unavailable, the shared interaction
+contract permits one concise direct question only if ordinary conversation is still
+available. A host mode that forbids interaction leaves the choice unanswered; Ultra
+does not infer consent or silently delegate the semantic route.
+
 Kimi starts plugin MCP processes with the managed plugin root as `cwd`. The
 generated launcher recovers the project from the inherited `PWD`, sets
 `UBP_ROOT_DIR` and `UBP_DB_PATH`, and refuses to start if that project boundary
 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+ |
@@ -129,9 +146,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `18.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, then adaptive transitions and legacy workflow normalization in 18.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,12 +1,13 @@
-# `.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
+`.ultra/.runtime/state.db` is the only 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. Every process
 that touches it must follow the rules below; deviations are bugs.
 
 ## 1. Three-role write matrix
@@ -64,7 +65,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 +75,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.checkpoint`); only normalized choices and 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 |
@@ -87,7 +89,7 @@ resolve the mount/runtime constraint before retrying.
 
 ## 5. Forbidden patterns
 
-- **No file copies for state.** Don't `cp .ultra/state.db
+- **No file copies for state.** Don't `cp .ultra/.runtime/state.db
   somewhere/state.db` and edit; use `ultra-tools db backup`.
 - **No long-held writer connections** outside the MCP server. Pop a
   short transaction, finish, close.