ultra-builder-pro-cli 0.25.1 → 0.26.0

package/docs/ARTIFACT-AUTHORITY.md

@@ -1,293 +1,115 @@
 # Ultra artifact authority
 
-This document defines what `.ultra/` remembers across sessions, which surface owns
-each fact, and how working output becomes durable Ultra authority.
+This document defines which project artifacts carry semantic authority, who may change
+them, how staleness is detected, and how recovery works in Ultra Builder Pro v0.26.
 
-## Boundary
+## Rules
 
-`.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.
+1. One semantic fact has one canonical representation.
+2. Owner intent and accepted reductions require owner authority.
+3. The model may interpret, decompose, investigate, and edit inside the authorized frame.
+4. Generated observations are disposable and never silently promoted.
+5. Git supplies revision identity, history, archive moves, comparison, and rollback.
 
-Semantic and evidence artifacts under `.ultra/` are trackable so reviewed intent and
-verification can travel with the repository. `.ultra/.runtime/` is always ignored:
-the SQLite authority, leases, worktrees, local telemetry, and recovery snapshots remain
-checkout-local. `.ultra/tasks/tasks.json` is the narrow MCP-owned Git handoff for
-portable baseline, Change, Decision, accepted Stage Checkpoint, and durable Task
-records; it is not a copy of live runtime state.
+## Canonical artifacts
 
-## Artifact classes
+| Artifact | Canonical content | Primary writer | Required readers | Staleness or conflict signal |
+|---|---|---|---|---|
+| `.ultra/north-star.md` | Owner's one-line goal and hard constraints | `ultra-init`, owner | every workflow; session Hook | owner correction or explicit replacement |
+| `.ultra/specs/product.md` | Product behavior and acceptance | research/change/delivery reconciliation | change, plan, dev, test, review, delivery | source/evidence conflict or unresolved marker |
+| `.ultra/specs/architecture.md` | Boundaries, authority, consumers, failure and recovery | research/change/delivery reconciliation | change, plan, dev, test, review, delivery | live-path evidence conflicts with text |
+| `.ultra/specs/discovery.md` | observations, unknowns, drift, and evidence queue | init/research | research, change, status | evidence resolves or overturns an entry |
+| `.ultra/specs/research-distillate.md` | bounded synthesis of specification state | `ultra-research` | change, plan, delivery | stored source blob hash differs from Git blob hash |
+| `CONTEXT.md` | ubiquitous language and relationships | `ultra-domain-modeling` | every workflow and test naming | source/product use reveals ambiguity |
+| `.ultra/changes/active/<id>/intent.md` | one bounded requested outcome | `ultra-change`; Planning Posture by `ultra-plan` | plan, dev, test, review, status, delivery | acceptance or scope changes |
+| `.ultra/tasks.json` | task identity, graph, status, trace, and context path | `ultra-plan` / `ultra-dev` | every user workflow and context Hook | ledger and context status disagree |
+| task `context_file` | acceptance, seams, implementation, evidence pointers, Completion, Resume Note | plan/dev | dev, test, review, status, delivery, resume | differs from ledger or current implementation |
+| `.ultra/decisions/<id>.md` | durable consequential owner decision | `ultra-think` after acceptance | every workflow in scope | superseded by a newer decision file |
+| `.ultra/evidence/<task-id>/...` | command output and bounded task evidence | `ultra-dev` | review, test, delivery | evidence revision differs from affected code |
+| `.ultra/test-report.json` | whole-system audit at one Git commit and worktree digest | `ultra-test` | status and delivery | `git_commit` or worktree digest differs from current checkout |
+| `.ultra/changes/active/<id>/delivery.md` | outcome, docs, verification, review, debt, risk, recovery, effects | `ultra-deliver` | owner and archived Change history | active evidence or accepted scope changes |
+| `.ultra/research/<run-id>/...` | cited investigation reports | `ultra-research` | specs, change, plan, delivery | newer sources or later superseding run |
 
-| Class | Examples | Authority |
-|---|---|---|
-| Checkout-local persistence and safety | `.ultra/.runtime/state.db` | Operational authority for identifiers, normalized accepted intent, accepted Stage Checkpoints, references, digests, freshness, provenance, locks, leases, transactions, recovery, and coordination in one checkout; never semantic route selection |
-| Git team checkpoint | `.ultra/tasks/tasks.json` | MCP-published, digest-chained handoff of portable baseline, Change, Decision summary/reference, accepted Stage Checkpoint, Task contract, dependency, and durable outcome records; never live Session or lease authority |
-| Digest-bound semantic artifacts | specifications, research reports, Change intent/delta/plan, Context Envelopes, Decision Records | Authoritative semantic bodies only while registered by the owning record or Stage Checkpoint and matching its recorded digest |
-| Digest-bound evidence artifacts | test, review, delivery, and verification reports | Authoritative evidence bodies only while registered, immutable where required, and matching the recorded digest and scope |
-| Generated projections | `.ultra/.runtime/projections/tasks.json`, generated task contexts, activity exports | Checkout-local read-only views derived from DB authority; manual edits are overwritten and never become authority |
-| Advisory recovery | `.ultra/.runtime/checkpoint.json` | Compact recovery hint derived from DB authority; stale or missing content never overrides the DB |
-| Working scratch | `.ultra/.runtime/collab/`, temporary session output, incomplete drafts | Non-authoritative working material until verified and promoted through a supported workflow write |
-| External provider references | memory or code-graph provider name, scope, version, stable reference, freshness metadata | Metadata-only context stored by Ultra; the provider remains authority for its payload |
-
-The DB is not expected to contain every semantic paragraph. It owns checkout-local
-lifecycle and the binding between a fact and its current content. A digest-bound file
-owns the registered semantic or evidence body. The team checkpoint moves a reviewed
-portable subset through Git and is merged into the receiving DB through MCP. None of
-these surfaces independently owns all three roles.
-
-## Human, model, and mechanical responsibilities
-
-| Actor | Responsible for | Must not do |
-|---|---|---|
-| Owner | Goals, acceptance, non-goals, material choices, risk acceptance, and authorization for irreversible or external effects | Supply facts the checkout or runtime can establish directly |
-| Host model | Inspect evidence, recommend a route, ask only for unresolved owner choices, normalize the answer, call the owning write, update semantic artifacts, read back the result, and present the next recommendation | Fabricate evidence, infer owner authorization, or bypass mechanical safety |
-| Ultra MCP | Persist normalized inputs, validate structure/current bytes/digests, record facts and provenance, commit caller-declared Stage Checkpoints, project local views, publish/import the Git checkpoint, and expose recovery | Judge semantic completeness, choose product direction, prove a UI click, pre-authorize reasoning steps, force a semantic route, or replace model judgment |
-| Host adapter | Render the shared interaction contract through the host-native question and tool surfaces | Become a second workflow authority |
-| Hook | Observe lifecycle, inject compact DB-derived recovery context, and protect MCP-owned checkpoint and generated projection paths | Select a semantic route or block ordinary development |
-
-## Intent persistence
-
-The interaction sequence is:
-
-```text
-inspect -> suggest -> host-native ask -> normalize -> persist -> apply -> read back
-```
-
-The host-native ask is conditional. An explicit owner instruction can already resolve
-a choice, so the model must not ask
-again merely to manufacture proof. When interaction is needed, the adapter uses the
-host-native question surface. Once the model batches the normalized result through
-`ultra.record`, the DB treats that result as current cross-session intent authority. It
-does not store or verify a UI receipt, raw prompt, or transcript.
-
-If the accepted decision changes another Ultra authority, the model applies that change
-through `ultra.record` or a digest-bound artifact and reads the result back. A decision whose normalized record is
-itself the complete authority may have no applied reference. Breadcrumb and decision
-read paths recall accepted intent only after the dialogue thread is completed or
-confirmed. A row-backed applied reference names an exact field and canonical value,
-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 current Change and owner authority permit the write;
-2. consequential claims are verified against the checkout, runtime, test result, or
-   primary source;
-3. the model writes through the owning MCP operation or immutable artifact path;
-4. the DB records the owning baseline, Change, Stage Checkpoint, Task, Decision, 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, Stage Checkpoint 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.
-
-Public kernel inputs are exact at their owning kind/action boundary. SQLite constraints
-remain defense in depth, not the first definition of a business vocabulary: wrong
-types, unsupported enums, unknown fields, malformed references, and invalid digests
-are rejected as typed mutable diagnostics before any row or file write. The rejected
-attempt is retained as audit evidence but never becomes semantic authority.
-
-An accepted mutation and its durable idempotency receipt form one logical transaction.
-DB-only operations commit them together. Operations that also publish managed files,
-the Git team checkpoint, a Session worktree/Worker Packet, or an archive packet use a
-recoverable journal or verified compensation. Failure restores the exact prior file
-bytes, rows, ledger generation, lease, packet, and worktree where applicable; an
-unprovable rollback becomes an explicit recovery condition rather than false success.
-
-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.
+The repository files may use prose, tables, or JSON as appropriate. The format is not
+authority by itself; the canonical path and accepted writer contract are.
 
-## Change overlay authority
+Every completed task has exactly one `.ultra/evidence/<task-id>/evidence.json` with
+schema `ultra-task-evidence-v1`. It records `task_id`, forty-character `git_head`, exact
+commands (`command`, `exit_code`, `evidence_ref`), all six evidence dimensions,
+artifact paths, limitations, and timestamp. Each dimension uses `status` of
+`satisfied`, `gap`, or `not_applicable`, plus `evidence_refs` and a non-empty rationale.
+Optional raw logs live beside that record; they do not create another summary.
 
-An active Change is an isolated overlay below
-`.ultra/changes/active/<change-id>/`. Its intent, normalized decisions, adaptive research,
-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.
+## Mutable workflow state
 
-`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.
+Pure file state uses three mechanisms:
 
-`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.
+- directory position, such as `changes/active/` versus `changes/archive/`;
+- an explicit field, such as a task or context status;
+- an on-the-spot model judgment that is not persisted as state.
 
-The Deliver Skill owns the evidence-based semantic handoff and records any deliberate
-stage omission. `change.archive` does not infer completeness or require a fixed
-Plan/Dev/Test/Review/Deliver sequence. It preflights the caller-declared target set
-before writing, validates reconciliation structure, 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.
+A state field records a mechanically checkable fact. Route selection remains a model
+judgment. Do not add a workflow-position field merely to decide which Skill should run.
 
-## Context and plan authority
+Task completion uses a dual write: `.ultra/tasks.json` and the task context header must
+agree. The writer reads both back. A mismatch is a visible recovery diagnostic; neither
+side silently wins.
 
-The canonical Context Envelope generator reads accepted Change, Task, baseline,
-Decision, checkout, evidence, execution, and provider-reference authority and writes
-one immutable manifest plus its DB snapshot row when persistence is requested. It
-never updates provider references or semantic Change fields. Each snapshot is
-identified by its exact scope, stage, content digest, and selected execution seam;
-consumers must not substitute a snapshot from another scope.
+## Decisions and reductions
 
-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.
+Write a durable decision only when it is difficult to reverse, surprising without
+context, and the result of a real trade-off. All three conditions are required.
 
-A current plan is a Change-owned pair:
+An accepted decision file is append-only history. A changed answer creates a new file
+with `supersedes`; it does not rewrite the prior decision.
 
-- `<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.
+Classification of a specification change is outcome-based:
 
-The Plan checkpoint selects both paths from the owning Change and accepts no arbitrary
-output path. The model owns decomposition and semantic coverage. MCP 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.
+- `EXPANSION`: adds a commitment while all prior commitments remain true;
+- `CORRECTION`: changes an inaccurate description while every prior product commitment
+  still holds in the result;
+- `REDUCTION`: any prior commitment stops holding, regardless of the justification.
 
-## Registry contract
+Only the owner may accept a reduction.
 
-`ultra.record` is the public writer for a semantic or evidence file that is not
-already registered by its owning typed record or Stage Checkpoint. Every managed registry row has:
+## Evidence promotion
 
-- 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`.
+Tool output, source inspection, external sources, and runtime observations begin as
+evidence. The model may use them to update a canonical specification when their scope
+and provenance support the claim. The evidence is retained or cited; it is not copied
+into a second semantic ledger.
 
-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, checkpoint, and 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.
+A test result is current only for the code and environment it exercised. A report must
+carry the exact command, exit code, and Git commit. Missing or stale evidence remains
+`not_run`, `unknown`, or `stale`; it is never inferred as passing.
 
-`artifact.get` reads by unique ID or unambiguous path. It fails closed when a path
-has multiple active authorities and reports whether the row satisfies the managed
-registry contract. A canonical path can have only one non-archived authority across
-all owners and kinds. Runtime, scratch, the MCP-owned team checkpoint, and generated
-task contexts cannot be promoted through this API.
+## Derived artifacts
 
-Owning internal writers use the same transaction contract. Change intent, delta and
-documentation packets, Context Envelopes, adaptive research, incident diagnosis,
-plan, test, review, delivery, archive reconciliation, and specification learning
-cannot update a managed digest or provenance through a parallel SQL path.
+These paths are intentionally non-authoritative:
 
-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 current record 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
-
-`ultra.doctor` compares the registry, dependency graph, filesystem, and owner
-tables. It reports:
-
-- unregistered semantic or evidence files;
-- registered files that are missing or whose digest/status is stale;
-- missing typed owners;
-- current managed artifacts without a consumer, unless explicitly terminal;
-- dangling source or consumer endpoints;
-- graph cycles that cannot become consumer evidence;
-- more than one active authority for the same canonical path;
-- legacy compatibility rows that remain unmanaged;
-- legacy generated task contexts left outside the runtime projection root.
-
-`.ultra/.runtime/**`, `.ultra/scratch/**`, and fixed scaffold support files are outside
-orphan diagnosis. Current generated projections are local runtime files and are not
-semantic artifacts. A retired `.ultra/tasks/contexts/**` entry is diagnosed and any
-generated marker is reported as a ghost projection. Before a baseline is ready, only
-the reserved
-`discovery.md`, `product.md`, `architecture.md`, and `research-distillate.md` scaffold
-paths under `.ultra/specs/` are provisional; every additional specification is subject
-to orphan diagnosis immediately. Completion cannot be manufactured by registering
-empty templates. Doctor and status expose registered, managed, and unmanaged counts,
-and compatibility remains unhealthy until every retained row is deliberately promoted
-or retired.
-
-## Team checkpoint
-
-`.ultra/tasks/tasks.json` has kind `ultra-team-task-ledger` and a versioned schema. It
-contains:
-
-- one portable baseline record, when present;
-- every Change summary, including a Change that has not yet produced Tasks;
-- normalized Decision summaries, artifact references, digests, and supersession;
-- accepted Stage Checkpoint summaries and evidence references;
-- durable Task contracts, dependencies, acceptance mappings, and outcomes;
-- per-record revisions, parent digests, the checkpoint state digest, and bounded
-  checkpoint ancestry.
-
-It excludes `in_progress` ownership, session ids, leases, worktrees, telemetry,
-projection jobs, recovery scratch, and `completion_commit`. Those fields are meaningful
-only in the checkout that owns the active process or Git object.
-
-MCP publishes a new generation at semantic handoff points: baseline convergence,
-Change creation or update, plan acceptance, durable task-contract or status change,
-task expansion or deletion, and Change convergence or archive. A direct edit is
-rejected by host hooks and fails digest validation even without hooks.
-
-`ultra.sync { action: import }` validates schema, full and per-record digests, bounded ancestry,
-Change ownership, task parents, and local active sessions. A clean record fast-forwards.
-A record changed on both sides, a non-descendant checkpoint, or a remote update to a
-locally active task stops with a typed conflict. Re-importing the same checkpoint
-performs no DB write. A ready imported baseline becomes `draft` or `adopting` with a
-blocking checkout-local revalidation gap; Git cannot prove the receiving checkout's
-HEAD, scope bytes, verification, or accepted dirty state. Publication remains blocked
-until that local baseline converges, preventing one unvalidated checkout from
-downgrading team authority.
-
-Legacy v4.4/v4.5 projections are replaced only through
-`ultra.sync { action: publish }`. The
-publisher first compares every available durable field with SQLite, writes the exact
-legacy bytes to `.ultra/.runtime/backups/task-ledger/`, and refuses any mismatch.
-Doctor diagnoses this state but never performs the semantic replacement.
-
-## Task-context projection
-
-`.ultra/.runtime/projections/contexts/<task-id>.md` is fully generated from current DB
-authority. The projector replaces the whole file, including its execution contract and
-stale banner, and marks it with `generated_by: ultra-projector`. It never preserves
-arbitrary prose inserted into an earlier projection.
-
-Before retiring an existing `.ultra/tasks/contexts/<task-id>.md`, the projector
-promotes its exact authored body bytes once into a digest-bound
-`legacy_context_findings` artifact owned and consumed by the task. Legacy frontmatter,
-stale banners, and generated contract marker regions are removed first; any remaining
-authored body is retained exactly, even when an older projector had preserved it after
-a generated contract. Migration fails without deleting the authored body if promotion
-cannot be registered. Both legacy reads and runtime projection writes reject traversal,
-symlink ancestors, and path escape. When a task disappears, only a runtime projection
-carrying the generated marker may be pruned, and the removal emits
-`projection_pruned`.
-
-Model findings, decisions, or evidence discovered during development must be written
-below the owning Change root and registered through its typed record, checkpoint, 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.
+| Path | Purpose | Recovery |
+|---|---|---|
+| `.ultra/.runtime/compact-snapshot.md` | compaction acceleration | rebuild from files and Git |
+| `.ultra/.runtime/delegations/` | delegated process receipts and logs | inspect result or rerun with new id |
+| `.ultra/.runtime/worktrees/` | delegated checkout locations | inspect Git worktrees and remove safely |
+| `.ultra/progress/<task-id>.json` | mechanical evidence observations | rerun sensors or inspect current diff |
+| `.ultra/reviews/<session>/` | bounded lens packets and findings | rerun review at a named revision |
+
+The canonical template's nested `.ultra/.gitignore` ignores `.runtime/`, `progress/`,
+and `reviews/` without rewriting the owner's repository-level ignore rules. Deleting
+those paths cannot delete accepted product intent, task contracts, or decisions.
+
+## Recovery order
+
+After interruption or host change:
+
+1. identify the repository root and current `HEAD`;
+2. read `.ultra/tasks.json`;
+3. read the unfinished task's full context and closing Resume Note;
+4. read `CONTEXT.md`, relevant decisions, active Change, specifications, and evidence;
+5. inspect the working tree and compare it with Completion and evidence claims;
+6. repair any ledger/context mismatch explicitly before relying on status;
+7. continue through the next observable acceptance boundary.
+
+Hooks and the `ubp` executable may be unavailable. Recovery must still work through
+these files and Git alone.

package/docs/DECISIONS.md

@@ -1,87 +1,75 @@
-# Ultra Builder Pro decision contract
-
-This document records the current product and authority boundaries that apply to
-the distributed package. Executable behavior remains defined by source,
-`spec/mcp-tools.yaml`, and `spec/schemas/state-db.sql`; `package.json` is the
-release-version authority.
-
-## Authority split
-
-| Layer | Owns | Must not own |
-|---|---|---|
-| 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, 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 protection of MCP-owned checkpoint/projection paths | Ordinary development blocking or semantic route selection |
-
-`.ultra/` is project-local cross-session workflow memory. `.ultra/.runtime/state.db` is
-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
-
-The research references form an optional semantic catalog. The host model
-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 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
-
-- `ultra-init` classifies and initializes local project authority. It does not
-  perform product research or start another workflow.
-- `ultra-research` establishes or refreshes evidence and converges a baseline
-  only after the required user decisions and local Git authority exist.
-- `ultra-change` owns post-baseline product deltas. Research, planning,
-  development, testing, review, and delivery remain separately invocable
-  capabilities with DB-enforced prerequisites.
-- `ultra-deliver` converges local Ultra evidence. Commit, push, publish, deploy,
-  messaging, and other external effects remain separately authorized host
-  actions.
-
-## Package boundary
-
-The package contains the public Ultra workflows, internal review-rule Skills,
-host-specific collaboration companions, MCP runtime, adapters, lifecycle hooks,
-and minimal project bootstrap. General browser, deployment, framework,
-discovery, memory, and graph capabilities remain owned by their separately
-installed providers. Ultra stores only bounded provider metadata references.
-
-## Installation provenance
-
-Each host installation records package identity, repository, source commit when
-available, installed-asset hashes, and contract targets. A local source checkout
-also records whether it was dirty and a deterministic worktree digest. An npm
-installation has no package-local Git repository and records those source
-checkout fields as `null`; it never inherits an enclosing consumer repository.
-
-Installation and project diagnostics are read-only unless an explicit repair or
-install action is requested. No local workflow completion authorizes a remote,
-release, deployment, or destructive effect.
-
-## Current source map
-
-- Runtime architecture: [`ARCHITECTURE.md`](./ARCHITECTURE.md)
-- Workflow state and invalidation: [`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md)
-- Host compatibility: [`RUNTIME-COMPAT-MATRIX.md`](./RUNTIME-COMPAT-MATRIX.md)
-- Plugin and user-instruction boundary: [`PLUGIN-ISOLATION-CONTRACT.md`](./PLUGIN-ISOLATION-CONTRACT.md)
-- MCP interface: [`../spec/mcp-tools.yaml`](../spec/mcp-tools.yaml)
-- Database contract: [`../spec/schemas/state-db.sql`](../spec/schemas/state-db.sql)
+# Ultra Builder Pro v0.26 decisions
+
+This file records durable product-level decisions that explain the current source tree.
+Project decisions created by Ultra belong in each project's `.ultra/decisions/`.
+
+## File-first authority
+
+Owner-readable repository files and Git are the complete semantic authority. Ultra
+does not maintain a database, MCP kernel, workflow state machine, prompt projection, or
+daemon. The previous mechanical supervisor could make every public path unreachable
+while still reporting internally consistent state; deletion restores the host model's
+ownership of route and meaning.
+
+## Three Skill roles
+
+The product exposes eight owner-invoked workflows, five model-invoked disciplines, and
+one router. Public workflows require explicit owner selection. A public workflow may
+recommend but never launch another public workflow. A model discipline needs at least
+two canonical callers or it is inlined.
+
+This keeps reusable reasoning in one place without turning it into another user-facing
+route or custom-agent registry.
+
+## Rule-side assets travel with Skills
+
+`.ultra/` contains project data only. Reusable executable examples live under
+`skills/ultra-tdd/references/templates/`; the reduction boundary lives under
+`skills/ultra-think/references/`; the full philosophy lives in `docs/PHILOSOPHY.md`.
+
+Skill `references/` is already copied by every adapter and supports relative
+cross-Skill links. No placeholder root variable or separate asset distributor is
+needed.
+
+## State is fact; route is judgment
+
+Directory position and explicit fields record mechanically checkable facts. The host
+model reads those facts and chooses the next route. There is no persisted “current
+workflow stage” whose value can override the actual files.
+
+Task status is written to both the ledger and context, then read back. Change archive
+is a `git mv`. Test-report freshness compares `git_commit` with `HEAD`.
+
+## Three independent integration defences
+
+Planning, task development, and final testing detect different versions of the
+locally-green/whole-system-broken failure. Their outputs remain independent sensors:
+horizontal task shape, six evidence dimensions, and final wiring/E2E audit.
+
+No single sensor is promoted into a semantic completion gate.
+
+## Five hooks only
+
+The hook surface is session context, mid-workflow acceptance recall, compact snapshot,
+post-edit evidence observation, and dangerous-command protection. Every hook is silent
+without `.ultra/`. Only a narrow named destructive effect can be denied, and its repair
+is authorization scoped to the exact command digest.
+
+## Delegation is a process boundary
+
+`ubp delegate run` starts a supported CLI with an immutable instruction, explicit
+permission JSON, and named worktree. Files are the cross-host state. The parent reads a
+stable terminal result instead of worker chatter. Delegation adds no semantic store and
+no authority.
+
+## Installation isolation
+
+An explicit `--config-dir` owns host sidecars as well as the primary config. In
+particular, Codex plugin and personal-marketplace paths resolve inside the sandbox.
+Managed staging, provenance, doctor, and uninstall are native adapter responsibilities.
+
+## External effects
+
+Commit, push, tag, package publication, release, deployment, installation, migrations,
+and real-money effects are independent. A locally complete delivery authorizes none of
+them automatically.