ultra-builder-pro-cli 0.26.1 → 0.26.2

package/.ultra-template/north-star.md

@@ -1,46 +1,35 @@
 # Project North Star
 
-> **Authority**: the owner's literal intent for this project, kept short enough to re-inject every
-> session. Every task must trace back here.
+> **Authority**: the accepted steering contract established by `ultra-research` from
+> owner decisions and cited evidence. Every Change and task must serve this contract.
 >
-> **Scope**: only what cannot be derived from `specs/product.md`. Success metrics,
-> excluded features, actors and scenarios stay in that file — do not copy them here.
+> **Scope**: this file owns the project direction, the one North Star outcome or metric
+> when one is justified, hard constraints, and explicit exclusions. Product requirements,
+> supporting measurements, actors, and scenarios stay in `specs/product.md`.
 
----
+## Project Direction
 
-## One-line
+[NEEDS CLARIFICATION]
 
-<!-- ONE sentence, in the owner's own words, describing what they want.
-     Captured by ultra-init, or from the owner's first request.
-     Do not paraphrase into product-speak: specs/product.md holds the processed version.
-     The value of this line is that it is the unprocessed baseline you check the
-     processed version against. -->
+## North Star Outcome
 
-_(not yet defined — run `ultra-init`, or the first owner request will populate this)_
+- `NS-01` outcome: [NEEDS CLARIFICATION]
+- Metric or observation contract: [NEEDS CLARIFICATION]
+- Why it represents delivered value: [NEEDS CLARIFICATION]
 
----
+A single metric is optional. When one would distort the product, record that decision and
+use an observable outcome plus guardrails instead of inventing numeric precision.
 
 ## Hard Constraints
 
-<!-- What must never happen, even when convenient. These are prohibitions, not technical
-     constraints — architecture.md holds those. Examples:
-     - Never store plaintext passwords
-     - Cannot break backwards compatibility with API v1
-     - Bundle stays under 500 KB
-     - External API cost stays under $X/month -->
+- `HC-1`: [NEEDS CLARIFICATION]
 
-_(not yet defined)_
+## Explicit Exclusions
 
----
+- [NEEDS CLARIFICATION]
 
-## Notes for agents
+## Research Trace
 
-1. Re-anchor on the One-line — that is the literal owner request. When the spec and this line
-   disagree, the spec drifted.
-2. Check Hard Constraints before any "improvement". An improvement that violates a constraint is
-   a regression.
-3. If your current work does not trace back here, **stop and ask**. You may be building the
-   wrong thing.
-
-The One-line is injected by `session_context` at SessionStart. `mid_workflow_recall`
-re-injects the active task acceptance before relevant tool use. See PHILOSOPHY C1.
+- Project brief: `project-brief.md`
+- Accepted research run: [NEEDS CLARIFICATION]
+- Decision references: [NEEDS CLARIFICATION]

package/.ultra-template/project-brief.md

@@ -0,0 +1,28 @@
+# Project Brief
+
+> **Authority**: raw owner intake captured by `ultra-init`. It preserves what the owner
+> initially asked for and the broad outline needed to begin research. It is not an
+> evidence-backed product baseline.
+>
+> **Lifecycle**: `ultra-research` reads this seed and promotes accepted conclusions into
+> the North Star, specifications, domain language, or decisions. It does not rewrite the
+> brief to make later conclusions look inevitable.
+
+## One-line
+
+[NEEDS CLARIFICATION]
+
+## Initial Outline
+
+- What it is: [NEEDS CLARIFICATION]
+- Broadly for whom or what: [NEEDS CLARIFICATION]
+- Intended result: [NEEDS CLARIFICATION]
+- Broad boundary: [NEEDS CLARIFICATION]
+
+## Explicit Inputs
+
+- [NEEDS CLARIFICATION]
+
+## Open Questions for Research
+
+- [NEEDS CLARIFICATION]

package/.ultra-template/specs/product.md

@@ -60,6 +60,10 @@ Scope status must reflect an explicit decision. Do not infer a reduced product p
 
 ## 22 Outcomes and Measurements
 
+The accepted project direction and any single North Star outcome or metric live in
+`.ultra/north-star.md`. Record supporting outcomes, measures, and guardrails here; do
+not force one metric when an observable outcome plus guardrails is the honest contract.
+
 | Outcome or guardrail | Definition | Evidence source | Decision use | Owner |
 |---|---|---|---|---|
 | | | | | |

package/.ultra-template/specs/research-distillate.md

@@ -28,6 +28,14 @@ specifications' prose.
 |---|---|---|
 | | | |
 
+## Source Revisions
+
+| Canonical source | Git blob hash from `git hash-object` | Status |
+|---|---|---|
+| `.ultra/specs/product.md` | | current or stale |
+| `.ultra/specs/architecture.md` | | current or stale |
+| `.ultra/specs/discovery.md` | | current or stale |
+
 ## End-to-End Trace
 
 | Problem or constraint | Actor and scenario | Requirement and acceptance | Architecture path | Verification |

package/.ultra-template/test-report.json

@@ -3,6 +3,7 @@
   "change_id": null,
   "task_ids": [],
   "git_commit": null,
+  "intent_digest": null,
   "worktree": {
     "dirty": null,
     "diff_digest": null

package/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.2] — 2026-08-04
+
+### Added
+
+- Added `.ultra/project-brief.md` as the raw owner-intake artifact and optional
+  Research `wayfinding.md` navigation for unclear multi-lens paths, without adding a
+  fifteenth Skill or another semantic authority.
+- Expanded Research alternatives beyond direct competitors and made a single North
+  Star metric optional when an observable outcome plus guardrails is more honest.
+
+### Changed
+
+- Narrowed `ultra-init` to the Project Brief and empty skeleton, made
+  `ultra-research` own the first accepted North Star, domain language, and
+  specification baseline, and limited `ultra-change` to touched baseline sections.
+- Made the first six Research lenses dependency-aware and kept Grilling, Think, and
+  Domain Modeling as caller-bounded reusable methods rather than Research stages or
+  owner routes.
+- Routed `ultra-status` from semantic file contents instead of a Research completion
+  bit or any single unresolved marker.
+- Gave every Change one stable id across active, archive, and abandoned positions;
+  made the task ledger append-only and every current reader active-id scoped.
+- Added explicit `none`, `bounded`, and `required` Research Disposition contracts,
+  one-task planning for quick Changes, and two-pass delivery against a fresh semantic
+  plus product snapshot.
+- Gave the exact Change Contract explicit Profile rationale and Risk flags fields so
+  its required blast-radius decision has one stable representation.
+- Kept ordinary technical seam selection model-owned and made delegation reachable for
+  task execution, scoped Research evidence, and aggregate Change review without
+  manufacturing task rows.
+
+### Fixed
+
+- Made session context prefer the accepted North Star, fall back to the Project Brief
+  before Research, retain legacy one-line compatibility, and always append active task
+  acceptance when present.
+- Bound Research distillates to the actual `git hash-object` value of all three
+  baseline specifications so staleness is mechanically observable.
+- Prevented archived or abandoned unfinished tasks, invalid Change ids, blocked
+  dependencies, and ambiguous multiple `in_progress` rows from being injected as the
+  current Hook acceptance.
+- Made canonical `change_id` override a conflicting legacy `change_ref`, so migration
+  compatibility cannot revive a historical task.
+- Bound Test reports to exact Change id, ordered task ids, intent digest, HEAD, and a
+  product-worktree digest that excludes the report and Change-directory metadata while
+  binding current intent separately, so product reconciliation requires retest while
+  delivery metadata and archive finalization do not self-invalidate.
+- Prevented a separate request from opening a second active Change, and gave abandoned
+  intents an exact owner decision, reason, reusable-evidence, and recovery closure read
+  by future Change and Status workflows.
+- Kept non-publishing package inspection diagnostic while the explicit Deliver gate
+  blocks release-package creation only for an undispositioned changed export with no
+  non-test consumer.
+- Made that gate's authorization path use the finding disposition in the current Test
+  report and carry the accepted decision into `delivery.md`.
+- Aligned `.npmignore` with the explicit package allowlist and locked all eight
+  maintained product documents into the tarball smoke contract.
+
+### Verified
+
+- Passed 119 Node tests, 21 Hook tests, 14 Skill Creator validations, five isolated
+  host install/Doctor/uninstall lifecycles, a 115-entry package dry-run inspection, and
+  an audit with zero vulnerabilities.
+
 ## [0.26.1] — 2026-08-03
 
 ### Added

package/README.md

@@ -29,14 +29,14 @@ The package installs exactly fourteen Skills in three roles.
 
 | Skill | Outcome |
 |---|---|
-| `ultra-init` | Establish the project skeleton and one-line north star |
-| `ultra-research` | Verify external claims and refresh specifications |
-| `ultra-change` | Reconcile a requested change against current product truth |
+| `ultra-init` | Establish the project skeleton and raw Project Brief |
+| `ultra-research` | Establish an accepted North Star and evidence-backed baseline |
+| `ultra-change` | Reconcile one requested delta against the accepted baseline |
 | `ultra-plan` | Write tracer-bullet tasks, contexts, dependencies, and seams |
 | `ultra-dev` | Implement one task through red/green development and six evidence dimensions |
 | `ultra-test` | Audit whole-system wiring, E2E behavior, performance, and security |
 | `ultra-deliver` | Reconcile, review, document, and archive a completed Change |
-| `ultra-delegate` | Run a bounded instruction through another supported CLI |
+| `ultra-delegate` | Run bounded task work, Research evidence, or aggregate review through another supported CLI |
 
 ### Model-invoked disciplines
 
@@ -60,6 +60,14 @@ review, and a consequential unresolved decision uses think. A host with native b
 subagents may parallelize review lenses; another host runs the same lens assets
 sequentially.
 
+Inside `ultra-research`, the first six references are six semantic lenses, not six
+extra Skills: problem validation, opportunity discovery, market assessment,
+alternatives, product strategy, and assumptions validation. `wayfinding.md` chooses
+the smallest dependency-correct path through those and the later evidence lenses.
+Grilling still owns how to ask one missing question, Think owns one consequential
+trade-off, and Domain Modeling owns vocabulary; Research owns the overall question
+map, evidence convergence, owner checkpoints, and baseline promotion.
+
 ### What happened to the original Agents
 
 v0.26 does not install a custom `agents/` projection. The old review workers became the
@@ -72,12 +80,15 @@ host exposes the same custom-agent API.
 
 ## Project authority
 
-A new project uses this shape:
+A project after its first accepted Research baseline uses this shape. Immediately after
+Init, `CONTEXT.md` does not exist yet and the North Star/specification files are empty
+skeletons.
 
 ```text
 CONTEXT.md
 .ultra/
 ├── .gitignore                  # ignores only derived Ultra paths
+├── project-brief.md
 ├── north-star.md
 ├── tasks.json
 ├── test-report.json
@@ -88,15 +99,18 @@ CONTEXT.md
 │   └── research-distillate.md
 ├── changes/
 │   ├── active/<change-id>/{intent.md,delivery.md}
-│   └── archive/<change-id>/intent.md
+│   ├── archive/<change-id>/{intent.md,delivery.md}
+│   └── abandoned/<change-id>/intent.md  # includes exact Abandonment closure
 ├── contexts/<task-id>.md
 ├── decisions/<decision-id>.md
 ├── evidence/<task-id>/...
-└── research/<run-id>/...
+└── research/<run-id>/{brief.md,<step-id>.md}
 ```
 
-Canonical semantic facts live in those files. Git provides history, comparison,
-rollback, and archive moves. The following are derived and can be deleted or rebuilt:
+The optional `brief.md` is derived navigation; the selected step reports are cited
+evidence, and promoted semantic facts live in the other canonical files. Git provides
+history, comparison, rollback, and archive moves. The following additional paths are
+derived and can be deleted or rebuilt:
 
 ```text
 .ultra/.runtime/
@@ -111,13 +125,13 @@ staleness, and recovery rules.
 
 | Route | Canonical write | Who consumes it next |
 |---|---|---|
-| `ultra-init` | north star and four specification skeletons; empty task and test ledgers | every later workflow and context Hook |
-| `ultra-research` | selected cited reports plus reconciled specifications and distillate | change, plan, and delivery |
-| `ultra-change` | one active `intent.md` with exact acceptance, seams, reconciliation, and recovery | plan, dev, test, review, status, delivery |
-| `ultra-plan` | `tasks.json`, one context per task, and Planning Posture in the active intent | dev and every resume path |
+| `ultra-init` | raw `project-brief.md`, empty North Star and specification skeletons, and empty task/test ledgers | research, status, and the pre-baseline session Hook fallback |
+| `ultra-research` | accepted North Star, first domain baseline, selected cited reports, reconciled specifications, and distillate | change, plan, and delivery |
+| `ultra-change` | one active `intent.md` with stable `change_id`, Research Disposition, and only the accepted baseline sections touched by that delta; or an exact Abandonment closure before an owner-authorized move | active: research through delivery; abandoned: future Change history and status |
+| `ultra-plan` | append-only `tasks.json` rows for the active `change_id`, one context per task, and Planning Posture in the active intent | dev and every resume path |
 | `ultra-dev` | source/tests, task evidence, synchronized task/context status, Completion and Resume Note | review, test, status, delivery |
-| `ultra-test` | the one current `test-report.json` bound to HEAD and worktree digest | status and delivery |
-| `ultra-deliver` | one `delivery.md`, reconciled specs/docs, then the archived Change directory | owner and future Change history |
+| `ultra-test` | the one current `test-report.json` bound to Change id, current task ids, intent digest, HEAD, and product-worktree digest | status and delivery |
+| `ultra-deliver` | first reconciled specs/docs, then after a fresh Test snapshot one `delivery.md` and the archived Change directory | owner and future Change history |
 | `ultra-status` | none | recommends the smallest explicit route from current files |
 | `ultra-delegate` | derived runtime receipt plus an isolated worktree diff | primary host inspection and optional integration |
 
@@ -178,23 +192,37 @@ installation; all five support managed global installation and isolated
 
 ## Typical workflow
 
-1. Select `ultra-init` once. It writes the skeleton, records the owner's one-line goal,
-   initializes Git when needed, and recommends the next route.
-2. Select `ultra-research` when a product or architecture claim needs evidence.
-3. Select `ultra-change` for the requested outcome and reconcile it against current
-   specifications before planning.
-4. Select `ultra-plan` to confirm public seams and produce resumable tracer-bullet tasks.
+1. Select `ultra-init` once. It writes the skeleton, preserves the owner's raw one-line
+   request and broad outline in the Project Brief, initializes Git when needed, and
+   stops before product research.
+2. Select `ultra-research` to turn that brief into the first accepted North Star,
+   shared vocabulary, and evidence-backed product and architecture baseline. For an
+   unclear multi-lens question it first writes a derived Wayfinding brief; for one
+   bounded evidence gap it skips that extra file.
+3. Select `ultra-change` for a requested delta. It reconciles only the baseline sections
+   the delta touches before planning; it does not rebuild the project baseline. Its
+   Research Disposition either cites sufficient evidence or names the bounded question
+   and exit evidence that must return through Research. A micro edit that makes no
+   specification sentence false stays outside Ultra; an accepted quick Change still
+   receives one Plan task. While that Change remains active, reconcile its same stable
+   id; never open a second active Change for a separate request.
+4. Select `ultra-plan` to record public seams and produce resumable tracer-bullet tasks.
+   The model owns ordinary technical seams; the owner decides only a seam that changes
+   the public contract or another material trade-off.
 5. Select `ultra-dev` for one task at a time. Each task leaves a Completion entry,
    evidence, and a closing Resume Note.
-6. Select `ultra-test` once the ledger is complete. Local green tests do not substitute
-   for wiring and E2E proof.
-7. Select `ultra-deliver` to run aggregate review, reconcile documentation, and archive
-   the Change. Commit, push, tag, publication, and deployment remain separately
-   authorized effects.
+6. Select `ultra-test` once tasks for the active Change are complete. Historical ledger
+   rows do not enter this audit. Local green tests do not substitute for wiring and E2E proof.
+7. Select `ultra-deliver` to run aggregate review and reconcile documentation. If that
+   changes product or semantic files, rerun Test; re-enter Deliver on the fresh snapshot
+   to write delivery metadata and archive the stable Change id. Commit, push, tag,
+   publication, and deployment remain separately authorized effects.
 
 At any point, `ultra-status` can reconstruct the current position. A fresh session or
 different host resumes by reading `.ultra/tasks.json`, the selected `context_file`, its
-`## Resume Note`, `CONTEXT.md`, relevant decisions, the active Change, and Git.
+`## Resume Note`, `CONTEXT.md`, relevant decisions, the active Change, and Git. It first
+filters the append-only ledger to tasks whose `change_id` matches the unique active
+Change; archived and abandoned unfinished rows are history, not the frontier.
 
 ## Three independent integration defences
 
@@ -215,7 +243,7 @@ Five optional hooks accelerate file reading and protect a narrow effect boundary
 
 | Hook | Behavior |
 |---|---|
-| `session_context.py` | Inject north star and current acceptance at session start |
+| `session_context.py` | Inject the accepted North Star, or the Project Brief fallback before Research, plus current acceptance |
 | `mid_workflow_recall.py` | Restate acceptance before relevant source operations |
 | `compact_context.py` | Save and restore a disposable Git/file snapshot |
 | `post_edit_guard.py` | Record mechanical evidence observations after edits |
@@ -244,6 +272,10 @@ Use `skills/ultra-delegate/scripts/delegate_wait.py` to wait for `result.json` w
 loading intermediate worker output into the parent context. Delegation grants no new
 authority; writable roots remain inside the worktree, and its permission file must
 declare zero external effects without widening the host sandbox.
+The immutable instruction names task execution/continuation, scoped Research evidence,
+or aggregate Change review/verification. The latter two may be read-only and do not
+require a task row, keeping pre-Plan Research and post-task cross-family review
+reachable without inventing ledger work.
 
 ## Host support
 

package/docs/ARCHITECTURE.md

@@ -38,14 +38,22 @@ The exact allowlists live in `adapters/_shared/runtime-assets.cjs`. Public workf
 never invoke another public workflow. They may use model-invoked disciplines and then
 recommend the next owner route.
 
+Research's seventeen references are workflow-owned semantic lenses. Its optional
+`wayfinding.md` maps a multi-lens question without becoming a new Skill or authority.
+The reusable mechanics remain separate: Grilling owns the interaction loop, Think owns
+one consequential decision, and Domain Modeling owns vocabulary promotion.
+
 ### Authority plane
 
 Canonical semantic authority consists of:
 
-- `.ultra/north-star.md` for owner wording and hard constraints;
+- `.ultra/project-brief.md` for raw owner intake and the initial outline;
+- `.ultra/north-star.md` for the accepted direction, outcome or metric decision, hard
+  constraints, and exclusions established by Research;
 - `.ultra/specs/*.md` for product, architecture, discovery, and research distillate;
-- `.ultra/changes/{active,archive}/<id>/intent.md` for bounded outcomes;
-- `.ultra/tasks.json` plus each task's `context_file`;
+- `.ultra/changes/{active,archive,abandoned}/<id>/intent.md` for bounded outcomes with
+  one stable id across directory moves;
+- append-only `.ultra/tasks.json` rows carrying `change_id`, plus each task's `context_file`;
 - `.ultra/decisions/*.md`, `.ultra/evidence/`, `.ultra/test-report.json`, and research;
 - repository-root `CONTEXT.md` for ubiquitous language;
 - Git for revision identity, history, moves, diff, and rollback.
@@ -53,6 +61,12 @@ Canonical semantic authority consists of:
 Each semantic fact has one canonical representation. A summary can point to authority,
 but cannot become a second authority merely because it is convenient to read.
 
+One primary host model writes this authority in a worktree. Native subagents are
+read-only sensors; delegated CLIs write isolated non-`.ultra` roots and return receipts.
+Sequential Changes share the ledger by stable id, while current readers filter by the
+one unique active Change. This keeps concurrency explicit in Git instead of adding a
+semantic lock service or workflow engine.
+
 ### Adaptation plane
 
 `adapters/*.js` translates the shared package into native host surfaces:
@@ -100,10 +114,11 @@ end-to-end evidence by themselves.
 
 Every user Skill starts by reading:
 
-1. `.ultra/tasks.json`;
-2. the unfinished task's `context_file` and closing `## Resume Note`;
-3. `CONTEXT.md` and relevant decisions;
-4. the active Change, specifications, evidence, and current Git state.
+1. zero or one active `change_id`, diagnosing more than one;
+2. `.ultra/tasks.json` tasks whose `change_id` matches it;
+3. the matching frontier task's `context_file` and closing `## Resume Note`;
+4. `CONTEXT.md` and relevant decisions;
+5. the active Change, specifications, evidence, and current Git state.
 
 That same sequence works after compaction, a fresh process, disabled hooks, or a host
 change. Compact snapshots can accelerate recovery but never outrank the source files.
@@ -112,10 +127,12 @@ change. Compact snapshots can accelerate recovery but never outrank the source f
 
 Three independent Skills protect the vertical path:
 
-1. `ultra-plan` confirms seams and rejects horizontal feature tasks.
+1. `ultra-plan` records model-selected technical seams, asks the owner only for a
+   public-contract or material trade-off, and rejects horizontal feature tasks.
 2. `ultra-dev` records six separate evidence dimensions, including real persistence,
    default-on behavior, vertical execution, and spec trace.
-3. `ultra-test` searches exports for real consumers and exercises the primary flow.
+3. `ultra-test` searches exports for real consumers, exercises the primary flow, and
+   binds the result to Change id, task ids, intent, HEAD, and product-worktree digest.
 
 These are independent sensors. None rewrites a finding into product truth.
 
@@ -131,6 +148,12 @@ schema-constrained final response; the Node worker validates `finished`, `blocke
 writes its own receipt; stdout, stderr, native final output, and the launch receipt
 remain diagnostic files.
 
+The instruction binds the active `change_id` and one of three semantic scopes: task
+execution/continuation, scoped Research evidence, or aggregate Change
+review/verification. Only task execution requires a task row. The read-only Research
+and aggregate scopes preserve the same process boundary without inventing work merely
+to make delegation reachable.
+
 Delegation does not grant authority or copy semantic state into another store. The
 worker reads and writes the same repository files in the specified worktree.
 

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
 
@@ -62,7 +78,8 @@ their repair is authorization scoped to the exact command digest.
 `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