ultra-builder-pro-cli 0.26.0 → 0.26.2

package/docs/ARTIFACT-AUTHORITY.md

@@ -10,29 +10,39 @@ them, how staleness is detected, and how recovery works in Ultra Builder Pro v0.
 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.
 
 ## Canonical artifacts
 
 | 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/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` | 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 |
+| `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` | append-only task ledger: globally unique identity, stable `change_id`, same-Change graph, status, trace, and context path | `ultra-plan` / `ultra-dev` | every user workflow and context Hook | dependency crosses Change, or ledger/context status disagrees |
 | 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/test-report.json` | whole-system audit, 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 | `change_id`, `task_ids`, `intent_digest`, `git_commit`, or worktree digest 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>/...` | cited investigation reports | `ultra-research` | specs, change, plan, delivery | newer sources or later superseding run |
+| `.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 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,
@@ -51,10 +61,24 @@ Pure file state uses three mechanisms:
 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.
 
+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 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.
 
+## 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.
+
 ## Decisions and reductions
 
 Write a durable decision only when it is difficult to reverse, surprising without
@@ -80,7 +104,10 @@ and provenance support the claim. The evidence is retained or cited; it is not c
 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, and Git commit. Missing or stale evidence remains
+carry the exact command, exit code, stable Change id, exact current task ids, intent
+SHA-256, Git commit, and product-worktree digest. Delivery metadata and moving the same
+Change between active and archive do not alter the product digest; 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
@@ -89,6 +116,7 @@ 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/worktrees/` | delegated checkout locations | inspect Git worktrees and remove safely |
@@ -104,9 +132,10 @@ those paths cannot delete accepted product intent, task contracts, or decisions.
 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;
+2. resolve zero or one active `change_id`, then read `.ultra/tasks.json`;
+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. repair any ledger/context mismatch explicitly before relying on status;
 7. continue through the next observable acceptance boundary.

package/docs/DECISIONS.md

@@ -21,6 +21,16 @@ 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.
 
+## 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
@@ -37,8 +47,14 @@ Directory position and explicit fields record mechanically checkable facts. The
 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`.
+Task status is written to both the ledger and context, then read back. Tasks retain a
+stable `change_id` in an append-only ledger; current readers select only rows matching
+the one active Change. Archive or abandonment is a `git mv`. Test-report freshness
+compares Change id, current task ids, intent digest, `git_commit`, and product-worktree
+digest with the current checkout. 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.
 
 ## Three independent integration defences
 
@@ -52,15 +68,18 @@ No single sensor is promoted into a semantic completion gate.
 
 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.
+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
 
 `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.
+no authority. The instruction selects task execution, scoped Research evidence, or
+aggregate Change review/verification; only task execution requires a task row.
 
 ## Installation isolation
 

package/docs/PHILOSOPHY.md

@@ -43,9 +43,11 @@ one or more.
 
 ### C1 — Goal-Always-Present
 
-The agent never stops seeing the north-star. Every hook trigger that costs context budget injects:
-the project one-liner plus the current task's acceptance criteria. The cost of repetition is
-always less than the cost of drift.
+The agent never stops seeing the current steering contract. Before Research accepts a
+baseline, the session Hook injects the raw Project Brief fallback. After Research, it
+injects the accepted North Star: Project Direction, any settled North Star Outcome, and
+Hard Constraints. Current task acceptance is appended in both cases. The cost of
+repetition is always less than the cost of drift.
 
 > **Test**: pick a random in-progress task, ask the agent "what's the acceptance criteria?" — if
 > it cannot answer in one sentence, this commandment is broken.
@@ -61,16 +63,20 @@ agents to find loopholes (rename `mock` to `stub`, etc.). The cheaper path must
 
 ### C3 — Sensors not Blockers
 
-Hooks emit signal; agents and users decide. Block only the **truly irreversible**:
+Hooks emit signal; agents and users decide. Block only the **truly irreversible or
+privileged destructive** effects for which the hook has an exact repair:
 
-- `git push` to protected branches
 - Funds transfer / on-chain transactions
-- DB migrations / `DROP` / `TRUNCATE`
+- Protected-branch history rewrite or deletion
+- `DROP` / `TRUNCATE`
 - Hardcoded secret commit
 - Arbitrary code execution driven by user input
 
-Everything else is advisory on stderr — the work stands, the signal is delivered, the agent
-proceeds.
+Additive protected-branch publication and database migrations are advisory: the former
+remains recoverable through Git and the portable hook cannot receive every host's
+trusted approval receipt; the latter is not mechanically classifiable as reversible or
+irreversible. The work stands, the signal is delivered, and the agent proceeds inside
+the owner's authorized frame.
 
 > **Why this is absolute**: hard final gates and hard pre-commit gates each produced the same
 > over-correction loop in v7 — the agent weakened tests to escape the gate and drifted from the
@@ -102,6 +108,27 @@ boundary surfaces to the user.
   feature flags, in-memory replacing real persistence, scope reduction, external or irreversible
   effects
 
+**Which decisions reach the owner.** Inside/Crossing above sorts actions. Read from the owner's
+side, the same boundary sorts decisions into three:
+
+| Type | Definition | Handling |
+|---|---|---|
+| taste | no objectively correct answer; only the owner's preference settles it | always ask |
+| crossing | objectively decidable, but the consequence is irreversible | always ask |
+| everything else | has an objective answer, or is cheap to reverse | decide and proceed; asking is the error |
+
+How much lands in the third row is a function of how sharp the north star is. With constraints
+that can veto a concrete decision, most execution-time questions are answered by reading them.
+With vague ones, "does this cross a boundary?" cannot be decided at all, so every question
+degrades into taste and reaches the owner. **Interrupt frequency measures the north star, not
+the work.** Frequent interruptions mean going back to sharpen constraints, not asking faster.
+
+**Boundaries grow; they do not change.** Adding a hard constraint or a non-goal mid-flight is
+routine and needs no permission — the frame got sharper and no prior promise broke. Editing or
+deleting one is a REDUCTION under the test below. This is what makes iteration five cheaper than
+iteration one: the frame accumulates, and the share of decisions the model settles alone rises
+with it.
+
 **Operational test for spec changes.** When implementation and spec disagree, classify the change
 before touching the spec. Do not classify by intent — classify by asking one question that can be
 checked against the file:
@@ -119,6 +146,12 @@ not convert a REDUCTION into a CORRECTION; the rationale goes into the question
 This is the mechanism by which specs shrink silently, so it is the one place the model must not
 be allowed to self-certify.
 
+**Not to be confused with Planning Posture.** A Change's `## Planning Posture` uses
+EXPAND / SELECTIVE / HOLD / REDUCE to say how much work to plan right now. That is a scope
+decision about the future and is freely reversible. The classification above is about the past:
+whether a promise already made still holds. `REDUCE` the plan is routine; a `REDUCTION` of
+commitments stops the work and goes to the owner.
+
 > **Test**: any boundary-crossing action must trigger an owner question, an active task
 > `## Change Log` entry, or an accepted `.ultra/decisions/<id>.md`.
 
@@ -154,15 +187,15 @@ Skill instruction. Do not touch it casually.
 
 | Consumer | Reads | Source of truth | Failure mode if drifted |
 |---|---|---|---|
-| `session_context` | headings `## One-line`, `## Hard Constraints` | `.ultra-template/north-star.md` | SessionStart shows no goal; C1 dies |
-| `session_context` | active `in_progress` task → its context | `tasks.json[].context_file` | acceptance criteria never surfaced |
+| `session_context` | North Star headings `## Project Direction`, `## North Star Outcome`, `## Hard Constraints`; Project Brief `## One-line`, or legacy North Star `## One-line` | `.ultra-template/north-star.md`, `.ultra-template/project-brief.md`, and the Hook's legacy-read branch | SessionStart shows no accepted North Star or Project Brief fallback; C1 dies |
+| `session_context` | unique active `change_id` → one matching `in_progress` task, else first dependency-ready `pending` task → its context | active Change directory plus `tasks.json[].change_id`, dependencies, status, and `context_file` | abandoned or blocked acceptance is injected, or current acceptance never surfaces |
 | `mid_workflow_recall` | heading `## Acceptance Criteria` | `.ultra-template/contexts/TEMPLATE.md` | hook injects nothing; C1 dies silently |
 | `ultra-tdd` | path `references/templates/*` | `skills/ultra-tdd/references/templates/` | guidance points at a missing runnable alternative; C2 dies |
-| `post_edit_guard` | writes `.ultra/progress/<task-id>.json` | `tasks.json[].id`, created on demand | mechanical observations disappear; C4 weakens |
+| `post_edit_guard` | writes `.ultra/progress/<task-id>.json` for the active Change's current task | active Change directory plus `tasks.json[].change_id` and `id`, created on demand | historical work receives current observations; C4 weakens |
 | `ultra-dev` and `post_edit_guard` | 6 keys: `tests_written`, `tests_passed`, `persistence_real`, `feature_flags_audit`, `vertical_slice`, `spec_trace` | the six-dimension table in `skills/ultra-dev/SKILL.md` | sensor and workflow report different evidence |
 | planning and status | marker `[NEEDS CLARIFICATION]` | `.ultra-template/specs/*.md` | unresolved product truth is hidden |
 | `ultra-plan` / `ultra-dev` / hooks | `trace_to` form `.ultra/specs/file.md#anchor` | `tasks.json[].trace_to` + GFM heading slugify | traces appear resolved when their heading is absent |
-| `ultra-deliver` / `ultra-status` | field `git_commit` | `.ultra/test-report.json` | stale test results pass as current |
+| `ultra-deliver` / `ultra-status` | fields `change_id`, `task_ids`, `intent_digest`, `git_commit`, and `worktree.diff_digest` | `.ultra/test-report.json` plus `worktree_digest.cjs` | stale Change, intent, task set, or product results pass as current |
 | `compact_context` | `.ultra/.runtime/compact-snapshot.md` | derived from canonical files and Git | compact recovery loses acceleration, not authority |
 | every hook | existence of `.ultra/` | the project directory | Ultra taxes projects that never opted in (see `docs/PLUGIN-ISOLATION-CONTRACT.md`) |
 | `ultra-init` | the project data skeleton | `.ultra-template/` and the exact file list in its Skill | later Skills read missing authority paths; C1 dies |

package/docs/PLUGIN-ISOLATION-CONTRACT.md

@@ -70,9 +70,12 @@ Every hook resolves the current project and checks for `.ultra/` before reading,
 writing, injecting context, or denying an effect. Without `.ultra/`, it emits no stdout,
 exits zero, and leaves the project untouched.
 
-The only hook denial is a named dangerous shell effect in an active Ultra project. The
-denial identifies the protected effect and supplies an exact-command SHA-256
-authorization path. All other hook failures are fail-open diagnostics.
+The only hook denial is a named destructive shell effect in an active Ultra project.
+The denial identifies the protected effect and supplies an exact-command SHA-256
+authorization path. Additive protected-branch publication is an advisory observation
+because a portable hook cannot consume every host's trusted owner-approval receipt;
+history rewrites and branch deletion remain guarded. All other hook failures are
+fail-open diagnostics.
 
 ## Project data boundary
 

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -60,7 +60,7 @@ host feature OpenCode does not expose.
 | mid-workflow recall | yes | handles `apply_patch` | native bridge | normalized | executed |
 | compact context | pre/start | pre/post | native compact event | pre/post | pre-compact |
 | post-edit observation | Write/Edit | Write/Edit/`apply_patch` | write/edit/patch | Write/Edit | Write/Edit/patch |
-| dangerous command guard | Bash | Bash | bash | Bash | Bash deny mapping |
+| dangerous command guard | Bash advisory/deny | Bash advisory/deny | bash advisory/deny | Bash advisory/deny | Bash allow/deny mapping |
 
 All hooks share the same `.ultra/` idle guard. Wire adapters normalize payload and
 output fields only; they do not change semantic policy. Codex installation health and
@@ -99,3 +99,45 @@ inherits the same isolated `HOME` and `CODEX_HOME`. Grok native registration is
 only in explicit isolated test mode. Lifecycle tests also require the isolated config
 and fake HOME to contain zero children after uninstall, while separate ownership tests
 prove that pre-existing empty Codex and Kimi registries survive.
+
+## Authenticated cross-host continuation evidence
+
+On 2026-08-03, one deliberately narrow task was run in an isolated Git repository to
+test the product's central recovery claim with real authenticated models. This was a
+continuation drill, not a full project workflow or a delegation receipt test.
+
+Both hosts used globally installed artifacts from the same clean source candidate:
+
+- source commit: `c473a248bde2afce77591f2ba382246d420b5c72`;
+- worktree digest: `e83bdcbe2905cf02cb06cb0219127f6ce0400484331a6e9fc95622bbe24b44bd`;
+- Doctor: Claude healthy with 83 assets and zero issues; Codex healthy with 99 assets
+  and zero issues, with optional hooks still `user_review_required`.
+
+The seed repository had one passing smoke test, one pending task, one mapped Change
+acceptance ID, and seed HEAD `cf27d62aeeae353e0650413de6d9a118b89a0406`.
+
+| Phase | Execution boundary | Observed result |
+|---|---|---|
+| Claude | One print-mode call, `acceptEdits`, no persistent session, empty MCP config, explicit file and local-test tools, USD 1.00 cap | Exit 0 at USD 0.741367 with zero web requests. It changed only the task ledger/context, added `test/slug.test.cjs`, and allowed the hook to write disposable progress. `src/slug.cjs` and completion evidence remained untouched. The task test exited 1 with actual `hello,-world!` versus expected `hello-world`; both task surfaces read `in_progress`, and the Resume Note named the exact next action. |
+| Codex | One ephemeral `workspace-write` call with sandbox network disabled and no conversation from Claude | Exit 0. It found and read the installed `ultra-dev` Skill, recovered the single task from Git and `.ultra/`, reproduced the same red, changed only the intended implementation, then passed the task test 1/1 and `npm test` 2/2. It wrote the three-command canonical evidence record and logs, completed both task status surfaces, and filled Completion and the final Resume Note. |
+| Independent check | Local commands after both model calls | `node --test test/slug.test.cjs` passed 1/1, `npm test` passed 2/2, `git diff --check` passed, and a structural check confirmed one completed task, six evidence dimensions, three existing command-log references, and matching ledger/context state. |
+
+The Codex process emitted non-blocking diagnostics for an older local model-cache
+schema and an unauthenticated user-config MCP startup. No MCP result was consumed and
+no external effect occurred; all task actions used local file and shell tools. This
+means the drill proves file-backed Claude-to-Codex continuation even while Codex hooks
+remain untrusted, but it does not claim that arbitrary user configuration starts
+without unrelated host diagnostics.
+
+The result establishes one real end-to-end example of cross-host resume without a
+shared conversation, database, MCP authority, daemon, or generated prompt projection.
+It does not establish output quality for every model, host, repository, or task shape.
+Task-level `ultra-review` and commits were intentionally excluded from the drill so the
+two host calls tested only the handoff boundary.
+
+Two older `.ultra` evidence snapshots originally named the completed WIP by its former
+path. The current-path artifact contract requires every reference to resolve in the
+checkout, so those two references now point here while their 2026-08-01 status and
+limitations remain explicitly historical. The original WIP is still recoverable from
+their pinned source commit `3f99189bc68697262cd90444685ac2d4857139c4` with
+`git show`; the live `docs/wip/` directory contains no unfinished document.

package/docs/SKILL-AUTHORING.md

@@ -41,14 +41,15 @@ Every Skill has one outcome-led title and these semantic sections:
 ## References
 ```
 
-User workflows begin by reading `.ultra/tasks.json`, the unfinished task's
-`context_file` and Resume Note, `CONTEXT.md`, and relevant decisions. They name the
-files they write and read them back. Completion criteria must be observable without a
-semantic validator.
+User workflows first resolve at most one active `change_id`, then read only matching
+rows from `.ultra/tasks.json`, the frontier task's `context_file` and Resume Note,
+`CONTEXT.md`, and relevant decisions. Historical or abandoned rows never become current
+from status alone. They name the files they write and read them back. Completion
+criteria must be observable without a semantic validator.
 
 Use positive leading words consistently: tracer bullet, seam, deep module, red,
-frontier, and fog of war. Explain a branch by its checkable result, not the model's
-reason for choosing it.
+frontier, and research boundary. Explain a branch by its checkable result, not the
+model's reason for choosing it.
 
 ## Progressive disclosure
 
@@ -56,6 +57,9 @@ Keep resident `SKILL.md` short enough to load on every invocation. Move focused
 into `references/` and deterministic validation or waiting into `scripts/`.
 
 - Load one research step or review lens at a time.
+- Keep Research's semantic lenses and optional Wayfinding map inside
+  `ultra-research/references/`; they are stages of that public workflow, not reusable
+  model-invoked Skills.
 - Keep one canonical copy of grilling, TDD, review, domain language, and autonomy rules.
 - Cross-reference another model-invoked Skill by relative path.
 - Do not hide the primary workflow in a script.

package/docs/WORKFLOW-LIFECYCLE.md

@@ -6,9 +6,9 @@ criteria; repository files record facts; the host model chooses the route.
 ## Capability flow
 
 ```text
-ultra-init
-    ├─ unresolved external claims ─► ultra-research
-    └─ bounded requested outcome ──► ultra-change
+ultra-init ──raw Project Brief──► ultra-research ──accepted baseline──► ultra-change
+                                      ▲                                  │
+                                      └──── scoped consequential evidence gap ────┘
 
 ultra-change ─► ultra-plan ─► ultra-dev (per task) ─► ultra-test ─► ultra-deliver
                      ▲                 │                    │
@@ -19,51 +19,78 @@ ultra-delegate  orthogonal bounded execution on another CLI
 ```
 
 Arrows are recommendations, not automatic invocation. The owner explicitly selects
-each public workflow.
+each public workflow. Delivery archives one stable `change_id`; the next request opens
+a new active id while prior task rows remain in the append-only ledger.
 
 ## Common entry contract
 
 Every user-invoked Skill reads, in order:
 
-1. `.ultra/tasks.json`;
-2. the unfinished task's `context_file` and closing `## Resume Note`;
-3. `CONTEXT.md` and relevant `.ultra/decisions/`;
-4. the active Change, specifications, evidence, and Git state relevant to its scope.
+1. zero or one `.ultra/changes/active/<change_id>/intent.md`; more than one is a conflict;
+2. `.ultra/tasks.json`, selecting only tasks whose `change_id` matches that active id;
+3. the matching frontier task's `context_file` and closing `## Resume Note`;
+4. `.ultra/project-brief.md`, the accepted `.ultra/north-star.md`, `CONTEXT.md`, and
+   relevant `.ultra/decisions/`, where those artifacts already exist;
+5. the active Change, specifications, evidence, maintained documentation, and Git state
+   relevant to its scope.
 
 Missing files produce a precise recovery or initialization recommendation. They do not
 cause the Skill to invent a state transition.
 
 ## Initialization
 
-`ultra-init` distinguishes owner authorization from claims requiring evidence. It
-creates the file skeleton, preserves unknowns as `[NEEDS CLARIFICATION]`, initializes
-Git when absent, and records only repository-observable brownfield facts. It does not
-perform research or launch another workflow.
+Init writes the raw Project Brief and stable empty skeleton. `ultra-init` preserves the
+owner's one-line request, broad outline, explicit inputs, and open questions without
+turning them into validated product truth. It initializes Git when absent and may
+preserve repository-observable brownfield facts as Research inputs. It does not define
+success, establish the North Star, create `CONTEXT.md`, populate specifications, or
+launch another workflow.
 
 ## Research
 
-`ultra-research` maps unresolved claims to the smallest useful subset of seventeen
-focused references. Reports are written immediately. Three material checkpoints can
-change later scope; the owner resolves those checkpoints. The final distillate records
-Git blob hashes of the specifications it summarizes.
+Research turns the brief into an accepted North Star and evidence-backed baseline.
+`ultra-research` uses Wayfinding only when a multi-lens path is unclear, then maps the
+question to the smallest useful subset of seventeen focused references. The first six
+are semantic lenses with real dependencies: `00` precedes `01`; conditional `02` and
+`03` may fan out after the boundary is known; `04` consumes their relevant conclusions
+and is the first owner checkpoint; `05` extracts assumptions from `00` through `04`.
+Grilling controls how missing owner inputs are asked, Think tests one consequential
+decision, and Domain Modeling writes settled vocabulary; none owns the Research route.
+The final synthesis promotes accepted conclusions into the North Star, `CONTEXT.md`,
+three specifications, and a source-hash-bound distillate.
 
 ## Change reconciliation
 
-`ultra-change` first compares requested behavior with product truth and current code.
-It classifies changes by the resulting commitments:
+Change updates only the touched baseline rather than rebuilding it. `ultra-change`
+first compares requested behavior with accepted product truth and current code. It
+classifies changes by the resulting commitments:
 
 - expansion and correction may proceed inside accepted intent;
 - a reduction waits for explicit owner authority.
 
 The output is one active Change intent with observable outcome, acceptance, seams,
-non-goals, and trace anchors.
+non-goals, trace anchors, and an explicit Research Disposition. `none` cites sufficient
+existing evidence; `bounded` or `required` names the exact question, lenses, and exit
+evidence. Unsatisfied exit evidence routes to Research, then back through Change
+reconciliation before planning when the accepted contract needs an update.
+
+A micro edit that makes no specification sentence false stays outside the Ultra
+lifecycle and uses ordinary repository TDD/verification. Once an active Change exists,
+even a `quick` profile receives one minimal Plan task so evidence and delivery remain
+bound to its id. A separate request cannot open a second active Change: finish or
+deliver the current one, abandon it with owner authority, or explicitly reconcile the
+new request into the same stable id.
 
 ## Planning
 
-`ultra-plan` confirms the scope posture and public seams, then writes a task graph and
-one context file per task. Feature tasks are tracer bullets. A contract task precedes
-cross-process or cross-top-level-boundary implementations; integration checkpoints
-appear after several slices. Cycles and broken trace paths are repaired before handoff.
+`ultra-plan` confirms a material scope posture and records public seams, then appends a
+current-Change task graph and one context file per task without deleting historical
+rows. The model chooses ordinary technical seams; the owner is asked only when a seam
+changes a public contract, accepted risk, or another material trade-off. Every task
+stores the stable `change_id`; dependencies stay inside that Change and ids remain
+globally unique. Feature tasks are tracer bullets. A contract task precedes cross-process
+or cross-top-level-boundary implementations; integration checkpoints appear after
+several slices. Cycles and broken trace paths are repaired before handoff.
 
 ## Task development
 
@@ -78,15 +105,26 @@ duplication or coupling visible.
 
 ## Whole-system audit
 
-`ultra-test` runs once after the ledger is complete. It checks anti-patterns, coverage,
+`ultra-test` runs once after tasks for the active Change are complete. It checks anti-patterns, coverage,
 wiring, E2E behavior, performance, and security. It names the exact Git commit and
-never turns an orphan, failed command, stub, or omission into permission to alter scope.
+binds the report to `change_id`, exact current task ids, intent SHA-256, and the
+product-worktree digest. `passed: true` implies complete current tasks and no required
+area left `not_run`; task completion does not force a pass, and dispositioned gaps stay
+visible. It never turns an orphan,
+failed command, stub, or omission into permission to alter scope.
 
 ## Delivery
 
-`ultra-deliver` reconciles actual outcome, specifications, documentation, current test
-report, aggregate review, build, version impact, omissions, and rollback. It archives
-the Change with `git mv` after local reconciliation.
+`ultra-deliver` uses two observable passes. The first reconciles actual outcome,
+specifications, documentation, aggregate review, omissions, and rollback; if semantic
+or product files change, it stops and recommends a fresh Test. The second begins only
+when report Change/task/intent/HEAD/product identities match, applies the changed-export
+gate, runs build and non-publishing package inspection, records version impact, writes
+delivery metadata, and archives the same stable id with `git mv`. Delivery metadata and
+the directory move do not invalidate their own product snapshot. Producing a release
+package remains blocked while a changed export has neither a non-test consumer nor an
+owner disposition. That disposition is recorded against the finding in the current
+test report without changing the finding or `passed`, then carried into `delivery.md`.
 
 Commit, push, tag, publication, release, and deployment are independent external
 effects. Readiness grants none automatically.
@@ -95,27 +133,44 @@ effects. Readiness grants none automatically.
 
 `ultra-status` infers the smallest next route from observable files:
 
-- no healthy skeleton → init;
-- unresolved evidence-bearing claim → research;
+- no healthy skeleton or usable raw brief → init;
+- raw brief without an accepted baseline, or a consequential evidence gap → research;
 - requested outcome without active Change → change;
-- active Change without executable ledger → plan;
-- pending or in-progress task → dev;
-- completed ledger without current report → test;
-- current report and unarchived Change → deliver.
+- draft or blocking active intent → change;
+- unsatisfied Research Disposition → research;
+- active Change without matching executable tasks → plan;
+- matching pending or in-progress task → dev;
+- completed current-Change tasks without a matching fresh report → test;
+- false report → route by finding and owner disposition, not by the boolean alone;
+- fresh, dispositioned report and unarchived Change → deliver.
 
 It also checks installation provenance, stale reports, old in-progress work, and
 unresolved markers. It does not mutate artifacts.
 
+## Delegation
+
+`ultra-delegate` is orthogonal to the lifecycle and requires explicit owner authority.
+Its immutable instruction selects task execution/continuation, scoped Research evidence,
+or aggregate Change review/verification. Task execution reads one matching task context;
+the latter two may be read-only and do not require a task, so both pre-Plan evidence and
+post-task review remain reachable. Every scope still binds the one active `change_id`, a
+clean isolated worktree, strict permission/result schemas, and primary-host inspection.
+The worker cannot write canonical `.ultra` files or perform external effects.
+
 ## Artifact closure
 
 Every durable output has a later reader:
 
-- init's north star and specification skeletons are read by all later workflows;
-- research reports are traced into specifications, Change reconciliation, planning,
+- init's Project Brief is consumed by Research, Status, and the pre-baseline session
+  Hook fallback; its empty skeleton supplies stable paths rather than product claims;
+- Research's accepted North Star and domain/specification baseline are read by every
+  later workflow, while selected reports trace into Change reconciliation, planning,
   and delivery;
-- Change intent is consumed through planning, development, audit, review, status, and
-  delivery;
-- task ledger and contexts are the common resume input, while task evidence feeds
+- active Change intent and its touched specification deltas are consumed through
+  planning, development, audit, review, status, and delivery; an abandoned intent has
+  an exact `## Abandonment` closure consumed by future Change reconciliation and Status;
+- the append-only task ledger and contexts are the common resume input after filtering
+  by active `change_id`, while task evidence feeds
   review, whole-system audit, and delivery;
 - the current test report is consumed by status and delivery;
 - delivery moves with the Change into archive and remains historical evidence.
@@ -126,9 +181,18 @@ an unowned drift log, Change plan, technical-debt report, or second delivery sum
 
 ## Interruption and cross-host continuation
 
+There is one primary writer for canonical `.ultra` files. Review workers are read-only;
+delegated source edits use isolated worktrees and return results for explicit
+integration. Parallel canonical writes are unsupported because silently merging intent,
+task, evidence, or report authority would lose meaning.
+
 Before stopping, the active task context records current facts, exact verification,
 open questions, Completion, and a closing Resume Note. The next session or host repeats
 the common entry contract and compares the working tree with those claims.
 
 This path remains valid when hooks and `ubp` are disabled. A compact snapshot may be
 used as a hint, then checked against canonical files and Git.
+
+An authenticated Claude-to-Codex continuation using this path passed on 2026-08-03;
+the exact scope, provenance, results, and limitations are recorded in the
+[runtime compatibility matrix](RUNTIME-COMPAT-MATRIX.md#authenticated-cross-host-continuation-evidence).