ultra-builder-pro-cli 5.0.0 → 6.0.0

package/docs/ARTIFACT-AUTHORITY.md

@@ -1,305 +0,0 @@
-# Ultra artifact 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. Since the
-accepted 3.0 design it is the per-fact expression of the Ultra Core Protocol: one
-canonical representation per semantic fact, explicit authorization, bounded effects,
-and reachable recovery, on files plus Git alone.
-
-## Rules
-
-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.
-6. A Change keeps one stable `change_id`; directory position records lifecycle, not identity.
-
-## Routing precedence
-
-When workflow-route signals conflict, consumers resolve them in this order:
-
-1. the current explicit owner instruction, accepted decisions, and external-effect
-   authorization;
-2. the current accepted North Star and the active Change intent;
-3. the current owner-issued Execution Grant — `session-local` while its conversation
-   activation is live, or a `durable work-package` grant a fresh Agent has stably
-   verified — its exact Change, modes, effects, topology, budget, and stop conditions;
-4. the task ledger, task acceptance, planned paths, and dependencies;
-5. the current validated Review SUMMARY verdict;
-6. current evidence and Test observations;
-7. the Resume Note;
-8. Hooks, progress records, compact snapshots, historical reviews, and other
-   derived observations.
-
-A lower layer never overrides a higher one. A conflict produces a typed diagnostic,
-preserves the original bytes, and routes to the nearest repair or owner checkpoint;
-nothing silently selects the "safer" semantic result. The Resume Note is
-navigational context — the current checkpoint, the next action a higher authority
-has already allowed, unresolved prerequisites, and the cheapest safe resume command
-or path — and never route authority: it cannot rewrite acceptance, a Review verdict,
-scope, or budget, and it cannot promote P2/P3 findings into blockers or reopen a
-review that returned a current verdict. Historical reviews, progress records, and
-Hook observations are provenance only.
-
-The Route Card is a projection of this precedence, not another layer in it. Its Route,
-Mode, Position, Exit condition, Delta, and Next fields are recalculated from the same
-authorities and current observations whenever a public Skill enters, pauses, exits, or
-transitions.
-
-A formal terminal outcome — an accepted result, an owner decision, an external
-blocker, a review-budget stop, or an abandonment — outranks every Resume, Hook, or
-Status suggestion that appears to continue the same work. Review stays inside the
-budget accepted for the work package, under one precedence rule: an exact current
-owner grant overrides the versioned product default — the released default is one
-initial Review plus two P0/P1 delta Reviews. Budget exhaustion with a remaining
-blocker returns the choice to the owner instead of another round; no Agent,
-reviewer, Hook, or control plane extends a budget itself, and the same root
-surviving three failed fixes stops point-patching and reports an architecture
-problem.
-
-## Effect classes
-
-Every action belongs to exactly one class, and the class fixes who may perform it:
-
-| Effect class | Examples | Default rule |
-|---|---|---|
-| `observation` | read-only source inspection, search, test listing | an Agent may act freely inside its task scope |
-| `local-reversible` | editing files inside the authorized worktree, running local tests, creating deletable temporary files | allowed inside an accepted work package with a recovery point |
-| `canonical-authority` | modifying the North Star, an active intent, task status, or an evidence verdict | one designated writer per fact; material semantic deltas return to the owner |
-| `external-or-irreversible` | commit, push, tag, publish, deploy, real installation, provider spend, credential or production mutation | one separate owner authorization per effect; capability or readiness never implies permission |
-
-A durable work-package grant may cover exact `local-reversible` execution and the
-canonical status writes it names explicitly. It never inherits
-`external-or-irreversible` effects by default; those require the owner to list each
-one in the grant and the consuming Agent to verify the listing is current.
-
-## Owner checkpoint semantics
-
-Every owner-facing checkpoint — the WIP at a stop, a task's closing Resume Note, a
-delivery report, or a review's owner handoff — answers eight fixed semantics, in
-whatever length keeps the owner able to judge:
-
-1. **Why** — the real problem being solved.
-2. **Outcome** — what difference the owner will see.
-3. **Accepted boundary** — what is accepted, and what explicitly is not.
-4. **Delta** — what materially changed since the last checkpoint.
-5. **Reality** — how far the live path actually works; what is still fake, unknown,
-   or unverified.
-6. **Decision needed** — what the owner must decide now; a Route Card says `none` when
-   nothing is genuinely blocking, while a free-form handoff may omit the section.
-7. **Next bounded action** — the smallest authorized next step.
-8. **Not done** — what remains owed when stopping or pausing.
-
-The canonical
-[`UBP Route Card`](../skills/ultra-status/references/route-contract.md#route-card) adds
-four navigation fields — Route, Mode, Position, and Exit condition — around these eight
-semantics. It is emitted output only: it has no canonical project path, never becomes a
-route ledger, and cannot grant continuation. Counts and transport events may explain
-Position or Reality but cannot produce a semantic completion verdict.
-
-A checkpoint is a cognitive interface, not a mechanical stage marker: no line count,
-token budget, or coverage percentage gates it, and alignment failure ("I don't know
-what you are doing", or the same concept re-explained repeatedly) stops execution and
-review until the owner re-accepts an outcome.
-
-## Canonical artifacts
-
-| Artifact | Canonical content | Primary writer | Required readers | Staleness or conflict signal |
-|---|---|---|---|---|
-| `.ultra/project-brief.md` | Raw owner intake, broad outline, explicit inputs, and open Research questions | `ultra-init`, owner correction | research, status; session Hook before an accepted baseline exists | owner correction or a recovered legacy one-line; never rewritten as researched truth |
-| `.ultra/north-star.md` | Accepted project direction, outcome or metric decision, hard constraints, and exclusions | `ultra-research` after owner acceptance; owner correction | every workflow; session Hook | accepted correction, superseding decision, or evidence conflict |
-| `.ultra/specs/product.md` | Product behavior and acceptance | research establishes; change/delivery reconcile touched sections | change, plan, dev, test, review, delivery | source/evidence conflict or unresolved marker |
-| `.ultra/specs/architecture.md` | Boundaries, authority, consumers, failure and recovery | research establishes; change/delivery reconcile touched sections | change, plan, dev, test, review, delivery | live-path evidence conflicts with text |
-| `.ultra/specs/discovery.md` | observations, unknowns, drift, and evidence queue | research; change for its scoped delta | 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`, first called by research and later by any qualifying workflow | every workflow and test naming | source/product use reveals ambiguity |
-| `.ultra/changes/{active,archive,abandoned}/<id>/intent.md` | one bounded requested outcome, reconciliation, Research Disposition, stable identity, and exact Abandonment closure when abandoned | `ultra-change`; Planning Posture by `ultra-plan` | active: research through delivery; all states: status and future Change history | more than one active Change, duplicate id across positions, missing Abandonment closure, or acceptance/scope change |
-| `.ultra/tasks.json` | `ultra-task-ledger-v2`: append-only task identity, stable `change_id`, same-Change graph, sole task status, trace, and context path | `ultra-plan` / `ultra-dev` | every user workflow and context Hook | dependency crosses Change, row shape is invalid, or a named context cannot be resolved |
-| task `context_file` | typed acceptance, seams, implementation, evidence pointers, Completion, Task Review, Resume Note; no v2 task status | plan/dev | dev, test, review, status, delivery, resume | acceptance identity, evidence pointer, or implementation differs from current source; a legacy Status or Complexity field is a migration diagnostic |
-| `.ultra/decisions/<id>.md` | durable consequential owner decision | `ultra-think` after acceptance | every workflow in scope | superseded by a newer decision file |
-| active Change `## Execution Grant` | the current work package's execution authorization: mode (`session-local` default or `durable work-package`), scope, Agent topology, allowed local effects, budgets/expiry, invalidation, and revoke; the exact durable grant bytes live in the cited owner decision, never in a second prose mirror | owner issues; `ultra-change` records the exact reference and fields; no workflow may widen it | executor, handoff, Status | a new Change, a recorded owner revocation, or a fired invalidation condition; stored grant text alone never activates |
-| `.ultra/evidence/<task-id>/...` | one final `ultra-task-evidence-v2` record: typed acceptance evidence, six dimensions, independent completion-snapshot freshness observation, separate task-review provenance, raw-output refs, and limitations | `ultra-dev` after validated task review | test, delivery; review consumes actual pre-review evidence instead | context acceptance, completion observation, cited artifacts, or review binding differs, or a legacy record has not been migrated |
-| `.ultra/test-report.json` | whole-system audit, ordered task-evidence identities, strict aggregate-review provenance, findings, and owner disposition for one Change/task/intent/product snapshot | `ultra-test`; `ultra-deliver` may add owner disposition without changing findings or `passed` | status and delivery | root identity, ordered task-evidence projection, or packet/admission/subject/summary review binding differs |
-| `.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>/<step-id>.md` | cited investigation report for one selected lens | `ultra-research` | specs, change, plan, delivery | newer sources or later superseding run |
-
-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.
-
-The append-only task ledger preserves sequential Change history. Current readers select
-only rows whose `change_id` matches the one unique active Change. Moving its directory
-to archive or abandoned never rewrites task identity, and an unfinished historical row
-never becomes current merely because of its status. Before an abandoned move,
-`ultra-change` appends `## Abandonment` with the owner decision, reason, reusable
-evidence, and recovery or successor. Future Change reconciliation and Status consume
-that record as history, not as accepted current intent.
-
-Every current completed task has exactly one final
-`.ultra/evidence/<task-id>/evidence.json` with schema `ultra-task-evidence-v2`. The
-canonical field and type contract lives in
-`skills/ultra-plan/references/task-evidence-v2.md`; this document does not duplicate it.
-The record binds the task and Change, context acceptance bytes, typed acceptance
-evidence and dispositions, all six evidence dimensions,
-task-review provenance, artifacts, limitations, and timestamp. `command`, `inspection`,
-`owner-judgment`, and `external-observation` retain separate evidence authorities. The
-owner alone supplies an owner-judgment result. The CLI establishes only JSON shape,
-token syntax, and authority designation; it does not prove current identity, provenance,
-freshness, or semantic acceptance. Test takes stable bytes independently, recomputes the
-Acceptance-section SHA-256, aligns exact criterion IDs and verification types with the
-current context, and aligns task-review session and summary digest with the retained strict summary. The `subject` is an independently captured completion-snapshot freshness observation made after the final strict task Review validates and immediately before
-evidence publication. Its `task_review` separately binds the retained strict summary.
-Worker Packet v1 and its summary's null `worktree_digest` do not prove or
-cryptographically bind the completion subject. Test separately binds its report to the
-current whole Change, then rechecks the current Acceptance, criterion IDs and verification
-types, owner record, review summary, and cited affected artifacts instead of demanding
-digest equality with the earlier task observation.
-For `owner-judgment`, the durable owner record must exist and its cited statement and
-disposition must remain readable. Any mismatch is an evidence gap returned to Dev or,
-for missing owner judgment, to the owner. Optional raw logs live beside the record and
-do not create another summary. Historical v1 records stay readable evidence but produce
-a migration diagnostic and cannot satisfy a current Change's Test or Deliver input.
-
-Task-review provenance has two discriminated branches with one authority rule: a
-strict-v4 record binds its retained strict session artifacts, while an
-`external-manual` record binds a real external-reviewer receipt under
-`.ultra/evidence/<task-id>/` by exact stable bytes and SHA-256 through the task
-evidence sensor's verify mode. The external receipt is a reconstructable observation
-of reviewer identity, reviewed subject, verdict, and exact findings — never semantic
-authority, never owner acceptance, and never a substitute strict
-SUMMARY/ADMISSION/session. Consumers recheck whichever branch a record declares and
-never rewrite one into the other.
-
-## Mutable workflow state
-
-Pure file state uses three mechanisms:
-
-- directory position, such as `changes/active/` versus `changes/archive/`;
-- an explicit field, such as task status in `.ultra/tasks.json`;
-- an on-the-spot model judgment that is not persisted as state.
-
-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.
-The Route Card is derived each time and is disposable in exactly this sense.
-
-At most one Change is active in one worktree. Zero active Changes is valid before a new
-request and after delivery; completed current tasks may remain active while awaiting
-Test or Deliver. More than one active directory is a conflict for owner/model repair,
-not a reason for code to select the first entry.
-
-Task status has one writer and one authority: `.ultra/tasks.json`. New contexts carry no
-Status field. A legacy context Status or Complexity header is preserved as a migration
-diagnostic, but the ledger wins. During implementation the row remains `in_progress`.
-Task-review admission uses that row, task context, an immutable review packet, and
-actual pre-review evidence; it does not require the final record it is helping create.
-After the final summary validates, Dev writes the one canonical evidence record with
-every blocking finding, resolution or authoritative disposition, and affected evidence
-refresh. Only after that record and the context review facts are current may the primary
-model write `completed` to the ledger and read the row back. A validator may check this
-ordering and its references; it cannot decide that a finding is semantically resolved.
-
-Later invalidation uses one explicit recovery edge. The ledger-authoritative row changes
-from `completed` to `in_progress`; Dev must never silently demote it. Before the write,
-Dev records the affected criterion IDs and reason in the task context Change Log and Resume Note.
-It preserves the old frozen review as history, then writes and reads back the ledger
-transition. New evidence and review close the task again through the same path.
-
-## Single-writer boundary
-
-One primary host model writes canonical `.ultra` files in a worktree. Native review
-workers are read-only sensors, and delegated CLIs write only declared non-`.ultra`
-roots in isolated registered worktrees; their findings return to the primary writer.
-Parallel implementation uses separate worktrees and explicit Git integration. Ultra
-does not add a lock service or semantic state machine to make concurrent canonical
-writes appear safe.
-
-The primary writer of a work package changes only through an owner-granted primary
-transfer (`skills/ultra-change/references/primary-transfer.md`): a derived OFFER
-binding canonical refs/hashes, HEAD, and worktree digest; a receiver ACK that is
-ready only on full stable-read match; sole-writer execution; and a frozen terminal
-RESULT. A delegated worker never becomes the canonical writer, and a delegation
-receipt never serves as an ACK or RESULT. While an ACK-ready transfer is open, at
-most that one receiver may write canonical files.
-
-## Decisions and reductions
-
-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.
-
-An accepted decision file is append-only history. A changed answer creates a new file
-with `supersedes`; it does not rewrite the prior decision.
-
-Classification of a specification change is outcome-based:
-
-- `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.
-
-Only the owner may accept a reduction.
-
-## Evidence promotion
-
-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.
-
-A test result is current only for the code and environment it exercised. A report must
-carry the exact command, exit code, stable Change id, exact current task ids, intent
-SHA-256, Git commit, product-worktree digest, ordered v2 task-evidence identities, and
-strict aggregate-review packet, admission, subject, and summary bindings. Delivery
-metadata and moving the same Change between active and archive do not alter the product
-digest. The product-worktree digest has one fixed boundary: it excludes
-`.ultra/evidence/**`, whose command and external-observation entries bind exact raw bytes
-as `raw_evidence_sha256` before stable record bytes are bound as `evidence_digest`
-through the ordered task-evidence projection. Test, Status, and Deliver independently
-recompute both bindings from bounded stable repository-contained regular non-symlink
-files; exact review receipts retain their own digest and consumer checks. No writer may
-add a caller-selected exclusion. Changing intent bytes does alter `intent_digest`.
-Missing or stale evidence remains
-`not_run`, `unknown`, or `stale`; it is never inferred as passing.
-
-## Derived artifacts
-
-These paths are intentionally non-authoritative:
-
-| Path | Purpose | Recovery |
-|---|---|---|
-| `.ultra/research/<run-id>/brief.md` | optional Wayfinding question map for a multi-lens Research run | rebuild from Project Brief, accepted authority, evidence needs, and owner checkpoints |
-| `.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/handoffs/` | primary-transfer OFFER/ACK/RESULT receipts, plus the optional CLOSEOUT receipt of the one prescribed post-review closeout | create a fresh handoff id from canonical authority; never reconstruct an old ACK or RESULT; close out a newest completed v2 RESULT by publishing its CLOSEOUT receipt, never by refreshing the RESULT or opening a handoff for the closeout |
-| `.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>/` | `WORKER-PACKET.json`, `ADMISSION.json`, selected specialist artifacts, and `SUMMARY.json` | retain a current strict session through successful aggregate Test and Deliver consumption; after premature loss, run a fresh Review and Test and never reconstruct the old receipt |
-
-The canonical template's nested `.ultra/.gitignore` ignores `.runtime/`, `progress/`,
-and `reviews/` without rewriting the owner's repository-level ignore rules. A current
-strict review session contains `WORKER-PACKET.json`, `ADMISSION.json`, every selected
-specialist artifact, and `SUMMARY.json`; it may be garbage-collected only after aggregate Test and
-Deliver have both consumed it successfully. Premature loss requires a fresh Review and
-Test, never reconstruction of the old receipt. Subject to that retention window,
-deleting derived 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. resolve zero or one active `change_id`, then read `.ultra/tasks.json`; if authority
-   resolution returns a typed conflict or unavailable observation, stop semantic writes
-   but keep Status recovery diagnosis reachable without selecting an ambiguous intent;
-3. select only matching tasks and read the frontier task's full context and closing Resume Note;
-4. read the Project Brief, accepted North Star, `CONTEXT.md`, relevant decisions, active
-   Change, specifications, and evidence;
-5. inspect the working tree and compare it with Completion and evidence claims;
-6. rely only on ledger task status; preserve any legacy context Status or Complexity as
-   a migration diagnostic, and use the explicit recorded reopen before repairing an
-   invalid completed task's current v2 evidence or task-review bindings;
-7. derive a fresh Route Card and continue only through the next observable acceptance
-   boundary covered by the current owner instruction or valid Execution Grant.
-
-Hooks and the `ubp` executable may be unavailable. Recovery must still work through
-these files and Git alone.

package/docs/DECISIONS.md

@@ -1,229 +0,0 @@
-# Ultra Builder Pro 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/`.
-
-## Ultra Core Protocol (3.0, accepted 2026-08-17; r3 revision same day)
-
-The owner accepted `docs/ULTRA-BUILDER-PRO-3.0.zh-CN.md` and projected it as North
-Star revision `north-star-v2-r2`
-(`.ultra/decisions/2026-08-17-ultra-3-0-north-star-r2.md`), then converged the
-constitution with the owner-directed r3 design
-(`docs/ULTRA-BUILDER-PRO-3.0-NORTH-STAR-R3.zh-CN.md`) as revision
-`north-star-v2-r3`
-(`.ultra/decisions/2026-08-17-ultra-3-0-north-star-r3.md`). Ultra Builder Pro is
-the file-first, provider-neutral Ultra Core Protocol: cognitive alignment through
-checkpoints, per-fact canonical authority, explicit dual-mode authorization, typed
-evidence with recovery, exclusive verified Agent handover, and review convergence
-bounded by an owner-visible budget. The constitution itself stays count-free —
-agent counts and topology detail, Host and Skill counts, provider names, and
-exact review-round numbers live in the versioned product contract and exact
-work-package grants. Authorization has two
-modes — `session-local` by default, `durable work-package` when the owner issues an
-exact grant (see `.ultra/decisions/2026-08-17-ultra-builder-pro-3.0-mode-b.md`); no
-file, status, Hook, or Resume note ever implies activation. Optional Graph/Loop
-coordination layers own observations only and none is integrated.
-
-## Ultra 5.0 workflow projection (accepted 2026-08-25)
-
-The owner accepted the 5.0 scope and interaction boundary in
-`.ultra/decisions/2026-08-25-ultra-5-0-scope.md`; the versioned contract is
-`docs/ULTRA-BUILDER-PRO-5.0.zh-CN.md`. One shared Route Contract projects the existing
-owner-checkpoint semantics into every public Skill without adding route state. Research
-has explicit baseline and grant-continuable Change-scoped modes; Change makes
-intake/evidence/reconcile/accepted visible and permits only same-Change non-material
-reconciliation under a valid grant; Plan returns product evidence gaps through Change.
-Host invocation bits remain coarse discovery metadata and every Skill rechecks mode,
-grant, effects, and material checkpoints. Team Pack, remote shared assets, a semantic
-state machine, daemon, and resident ACP service remain outside 5.0.
-
-## Primary transfer between Agents (r3, accepted 2026-08-17)
-
-A work package's canonical writer moves to another Agent only through an
-owner-granted primary transfer: the sender writes current reality into the task
-context and Resume Note, derives an OFFER binding canonical refs/hashes, HEAD,
-and the worktree digest, and stops writing after the receiver's ready ACK; the
-receiver stable-reads, verifies every digest, becomes the sole canonical writer,
-and freezes a terminal RESULT. Receipts under `.ultra/.runtime/handoffs/` are
-derived and rebuildable, never authority; mismatches block instead of
-auto-repairing; delegated workers stay mutually exclusive with this path and
-never write canonical `.ultra`
-(`.ultra/decisions/2026-08-17-ultra-3-0-r3-primary-handoff.md`,
-`skills/ultra-change/references/primary-transfer.md`).
-
-## ZCode headless transport stays experimental (r3, accepted 2026-08-17)
-
-The ZCode app-bundled CLI is a verified-local surface — it exists, launches, and
-passed local drills — but the provider publishes no headless CLI, SDK, or
-protocol stability contract. Its transport maturity is recorded `experimental`
-in the shared host profile and compatibility matrix; promotion to `supported`
-requires both official documentation and a full recovery drill. Interactive
-Desktop use and the documented plugin surface are unaffected, and no adapter may
-pass an app-internal binary off as an official stable interface.
-
-## 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-invocable public workflows, five model-invoked
-disciplines, and one router. Public modes are `explicit-entry` or
-`grant-continuable`. Scoped Research, same-Change reconciliation, Plan, Dev, Test, and
-Deliver reconciliation may be selected under an activated Change-scoped execution
-grant — session-local activation in the current conversation, or a stably verified
-durable work-package grant. All other public modes stay explicit-entry; Status stays
-owner-invoked and read-only. 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.
-
-## Bounded same-session continuation
-
-The stored grant text is descriptive authority, not an executable grant. Session-local
-activation is a current owner utterance approving the exact grant and current task
-ledger; a durable work-package grant is executable only after a fresh Agent stably
-verifies its recorded subject, scope, topology, effects, budgets, expiry, revocation,
-and invalidation. A fresh session without a durable grant, host change, lost
-activation context, semantic stop, or budget ceiling pauses
-the loop. Plan, task, and aggregate reviews remain mandatory. Delivery continuation is
-reconcile-only; finalization, archive, authenticated providers, install, commit, push,
-publish, and deploy remain separately authorized.
-
-The native host model-tool loop performs the work. Existing files and Git carry
-recovery; no route position, daemon, or extra semantic store is introduced.
-
-## Review topology is owner-selected
-
-The owner chooses reviewer and provider count for each stage. The default is one reviewer:
-the current Agent. An initial task review selects `review-spec` plus the
-lenses justified by risk and touched seams; a delta review reruns only affected
-lenses; an aggregate Change review may default to the full roster only when cross-task
-wiring justifies it — never as a mandatory count or a quality proxy. Specification
-fidelity owns both accepted-behavior mapping and the challenge to a Change's claimed
-North Star contribution, with actual execution mode and coverage recorded. When
-another model family is available, a blind premise challenger is an additional probe
-rather than a voting lens.
-
-The seeded 2026-08-14 evaluation found no consequential defect class uniquely caught
-by a permanent premise lens: the strengthened specification lens, the six-concern Kimi
-probe, and the ZCode specification probe each found all five hidden classes. Grok's
-malformed terminal output was rejected and was not counted as semantic evidence. See
-`docs/evals/adversarial-review-2026-08-14.md`.
-
-## ZCode activation uses documented plugin directories
-
-ZCode receives a managed local marketplace for importability and a documented
-`plugins.dirs` entry for immediate native discovery. Ultra owns only the entry it adds,
-so reinstall is idempotent and uninstall preserves unrelated user configuration. It
-does not write ZCode's private plugin cache or copy desktop provider credentials into
-headless CLI configuration.
-
-## Intake, baseline, and delta
-
-Init preserves raw owner intake in the Project Brief; Research establishes the accepted North Star, domain language, and specification baseline; Change reconciles only the sections touched by one requested delta.
-
-The optional Research Wayfinding brief is derived navigation, not a fifteenth Skill or
-semantic authority. The first six Research references remain dependency-aware semantic
-lenses. Grilling controls how caller-named questions are asked, Think stress-tests one
-consequential decision, and Domain Modeling promotes settled vocabulary. This prevents
-Init from consuming Research while keeping reusable methods in one canonical place.
-
-## 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.
-
-The `UBP Route Card` is the owner-visible projection of those facts: it adds Route,
-Mode, Position, and Exit condition around the eight accepted checkpoint semantics. It
-is derived at public boundaries, has no canonical path, and provides neither completion
-nor continuation authority.
-
-Task status lives only in the `ultra-task-ledger-v2` row and is read back there. New task
-contexts do not duplicate it; legacy context Status and Complexity fields remain
-migration diagnostics and the ledger wins. Tasks retain a stable `change_id` in the
-append-only ledger; current readers select only rows matching the one active Change.
-Archive or abandonment is a `git mv`. Test-report freshness is governed normatively by the complete v2 rule in [Artifact Authority](ARTIFACT-AUTHORITY.md#evidence-promotion).
-That authority binds the current Change snapshot, ordered v2 task-evidence identities,
-and strict aggregate-review packet, admission, subject, and summary bindings. This
-decision intentionally does not maintain a second field mirror. Deliver reconciles
-first and finalizes only while that complete snapshot remains current. A separate
-request cannot create a second active Change; it waits, exits the current Change, or is
-explicitly reconciled into the same id.
-
-## Typed task evidence and completion ordering
-
-Current work uses `ultra-task-evidence-v2`. Command, inspection, owner-judgment, and
-external-observation evidence retain distinct authorities; the owner alone can supply
-an owner-judgment result. Structural validators report exact fields, identities,
-digests, provenance, and freshness, never semantic acceptance. A task remains
-`in_progress` through its task review. Blocking findings and their dispositions are
-recorded and affected evidence is refreshed before the primary model writes
-`completed` to the ledger. Historical v1 evidence remains readable but cannot satisfy a
-current Change's Test or Deliver input without migration.
-
-## Counts are observations, not semantic gates
-
-Task, file, line, context, question, finding, repair-round, and complexity counts do not
-decide plan quality, review convergence, staleness, or completion. The model interprets
-concrete coupling, evidence, risk, and recovery facts. Explicit physical ceilings such
-as time, bytes, cost, provider spend, or bounded process resources still stop resource
-consumption and return a typed recovery path; exhaustion never dispositions a finding.
-
-## 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/`. Additive protected-branch publication is advisory because the
-portable hook cannot receive every host's trusted owner-approval receipt. History
-rewrites, branch deletion, and the narrower named destructive effects can be denied;
-their repair is authorization scoped to the exact command digest.
-
-## Delegation is a process boundary
-
-The installed `ultra-delegate/scripts/delegate.cjs` starts a supported CLI with an
-immutable instruction, explicit permission JSON, and named worktree. Its exact
-digest-bound sources are embedded in
-the worker prompt because some native sandboxes correctly deny reads outside the
-worktree. Files remain the cross-host state; the embedded copy is transport, not another
-authority. The parent reads a stable terminal result instead of worker chatter. The
-package `ubp delegate` surface is a one-release compatibility import of that same
-launcher, not a second implementation or a runtime installation requirement.
-Delegation adds no semantic store and no authority. The instruction selects task
-execution, scoped Research evidence, or aggregate Change review/verification; only task
-execution requires a task row.
-
-## 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.