ultra-builder-pro-cli 0.26.0 → 0.26.2

package/skills/ultra-init/SKILL.md

@@ -1,111 +1,94 @@
 ---
 name: ultra-init
-description: Establish a project's Ultra authority as files — the owner's one-line goal, hard constraints, the three specification skeletons, an empty task ledger, and Git. Use when a repository has no `.ultra` directory yet, or has a partial one left by an interrupted setup, whether the codebase is new or already carries years of history.
+description: Create or recover Ultra's repository-local skeleton and raw Project Brief without performing product research. Use when `.ultra` is absent or partial in a new or existing codebase and later workflows need stable file paths, preserved authority, and Git.
 ---
 
-# Build the skeleton the rest of the workflow writes into
+# Create the skeleton and capture only the initial project outline
 
-Initialization creates the repository-local authority and nothing else.
-It does not perform research, accept a product baseline, choose a Change, or
-start another capability — recommend the next one and stop; do not invoke it.
-
-The dividing line against research is **authorization versus claim**. What the
-owner authorizes comes out of their head and evidence cannot overturn it. What
-research collects is a claim about the outside world, which evidence can confirm
-or refute. A technology choice is a claim, so it is not initialization's business
-— and a new project has no configuration files to read anyway.
+Initialization establishes places for later authority and records raw owner intake. It
+does not validate the problem, establish a North Star, build a product or architecture
+baseline, settle domain language, choose a Change, or start another public workflow.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json` if it exists, along with the `context_file` of any
-   task it names — a partial `.ultra/` means an earlier attempt stopped midway.
-2. Read `CONTEXT.md` at the repository root for vocabulary already settled, and
-   `.ultra/decisions/` for any entries preserved by a partial setup.
-3. Establish the route's facts from the filesystem, not by asking.
+1. If `.ultra/changes/active/` exists, resolve at most one active `change_id`. Read
+   `.ultra/tasks.json` if it exists, plus the `context_file` and closing `## Resume Note`
+   of unfinished tasks matching that id. Historical unfinished rows do not turn a
+   partial skeleton into current work. A partial `.ultra/` is recovery work.
+2. Read `.ultra/project-brief.md`, `.ultra/north-star.md`, `CONTEXT.md`, and relevant
+   `.ultra/decisions/` when they exist. Preserve accepted authority byte-for-byte.
+3. Establish the repository root, Git state, and whether meaningful code or maintained
+   documentation exists from the filesystem. Do not ask the owner for those facts.
 
 ## Definition of done
 
-- `.ultra/north-star.md` carries the owner's one-line goal in their own words.
-- Every file listed under **What gets written** exists; you read each one back
-  after writing and stopped at the first one missing.
-- `.git` exists. Any initial commit is a separately authorized delivery effect.
-- Nothing is invented: what is unknown says `[NEEDS CLARIFICATION]`.
-
-## Which route
+- `.ultra/project-brief.md` contains raw owner intake: one line, a broad outline,
+  explicit inputs already supplied, and open questions handed to Research.
+- For a new skeleton, an empty North Star and the three specification skeletons exist.
+  Recovery preserves any populated authority; Init does not fill semantic sections or
+  create `CONTEXT.md`.
+- Every packaged path was read back after copying, while every pre-existing file stayed
+  byte-identical.
+- `.git` exists. Commit, push, remote creation, and publication remain separate effects.
 
-Check the filesystem in this order and take the first match:
+## Classify only for preservation
 
-| Check | Route | What changes |
-|---|---|---|
-| `docs/` holds two or more non-README `.md` files, or `docs/adr/` or `doc/` exists | Documented brownfield | Write everything; cite maintained documents as evidence and preserve their repository paths in `trace_to` when they remain authoritative |
-| A language configuration file exists and the row above did not match | Brownfield | Write everything; record what a code scan shows in `architecture.md` and `discovery.md`, marked as observed and unverified |
-| Neither | Greenfield | Write everything |
+Use `references/brownfield-adoption.md` when source, runtime configuration, tests, or
+maintained product documentation already exist. Classification changes what must be
+preserved and what Research should inspect; it never authorizes Init to write observed
+product behavior into a specification.
 
-For either brownfield route, read `references/brownfield-adoption.md`. Existing docs
-are evidence or an explicitly retained authority; they never justify omitting the
-canonical specification skeleton that downstream workflows require.
+## Draw out the brief, then stop
 
-## Draw out the intent
+Follow `../ultra-grilling/SKILL.md` with only these required fields:
 
-Follow `../ultra-grilling/SKILL.md`. It is a loop, not a questionnaire, because
-the owner cannot state what they want up front. Start from what they already said
-when invoking you, restate it for confirmation, and ask only about what is
-genuinely missing. Five things come out of it:
-
-| What you draw out | Where it lands |
+| Raw intake | Project Brief section |
 |---|---|
-| What you want to build, in one sentence, their words | `north-star.md`, `## One-line` |
-| What counts as success | `specs/product.md`, behavioral requirements and acceptance |
-| What must never happen | `north-star.md`, `## Hard Constraints` |
-| Who uses it, and how they cope today | `discovery.md`, marked as the owner's statement |
-| **What you already know you are unsure about** | `discovery.md` — research's priority queue |
+| What the owner wants to build, in one sentence and their words | `## One-line` |
+| What it is, broadly for whom or what, intended result, broad boundary | `## Initial Outline` |
+| Constraints, materials, and decisions the owner already volunteered | `## Explicit Inputs` |
+| Questions already visible but requiring evidence or deeper decisions | `## Open Questions for Research` |
 
-When the first domain terms appear, follow `../ultra-domain-modeling/SKILL.md`
-and create `CONTEXT.md` at the repository root.
+Ask only enough to distinguish materially different outlines. If an answer would define
+a problem, actor evidence, desired outcome, success measure, product strategy, accepted
+constraint, domain term, requirement, or architecture, record it as an input or open
+question and stop drilling. Research owns that maturation and must not re-ask an answer
+unless evidence conflicts with it.
 
-## What gets written
+## Write and recover the skeleton
 
 Resolve this loaded Skill's directory, then run
-`node <ultra-init-skill-dir>/scripts/init_project.cjs --project <repository-root>`. The script copies
-only missing files from `assets/project-template`, preserves every existing authority
-file byte-for-byte, and reads the resulting skeleton back. Then fill its semantic
-placeholders from verified facts and owner decisions.
+`node <ultra-init-skill-dir>/scripts/init_project.cjs --project <repository-root>`.
+The script copies only missing files from `assets/project-template`, preserves every
+existing file, and reads the complete result back.
 
 ```text
-.ultra/north-star.md                                ## One-line, ## Hard Constraints
-.ultra/specs/{product,architecture,discovery}.md    ## Observed, ## Decisions, ## Unknowns
-.ultra/tasks.json                                   {"tasks": []}
-.ultra/test-report.json                             not-yet-run report with git_commit
-.ultra/contexts/  .ultra/decisions/  .ultra/evidence/
-CONTEXT.md                                          repository root, once a term is settled
+.ultra/project-brief.md                            raw intake and initial outline
+.ultra/north-star.md                               empty Research-owned steering contract
+.ultra/specs/{product,architecture,discovery}.md  empty specification skeletons
+.ultra/specs/research-distillate.md                empty Research synthesis skeleton
+.ultra/{tasks.json,test-report.json}               empty or not-yet-run ledgers
+.ultra/{contexts,decisions,evidence,research}/
+.ultra/changes/{active,archive,abandoned}/
 ```
 
-The copied `.ultra/.gitignore` excludes `.runtime/`, `progress/`, and `reviews/`
-without editing the owner's root ignore file. Those paths are exact — hooks and later
-skills read them by name. Every section left unfilled carries
-`[NEEDS CLARIFICATION]`, and which of those you resolve now has a checkable rule:
-**what can be read out of repository files, you fill; what needs investigation,
-research fills.**
+For a legacy `north-star.md` containing `## One-line`, keep that file byte-identical.
+When the new Project Brief is still unresolved, copy the legacy one-line verbatim into
+it and list legacy hard constraints under Explicit Inputs without assigning new IDs.
+Research later proposes the accepted North Star; it never rewrites history silently.
 
-Git is not a preference. Reconciliation reads `git log` and `git diff`, staleness
-detection compares against `HEAD`, archiving is a `git mv`, and rollback is Git.
-If `.git` is absent, run `git init`. Report the uncommitted initialized files and ask
-for commit authority only if the owner wants that separate effect now.
+Git supplies revision identity, history, comparison, archive moves, and rollback. Run
+`git init` only when `.git` is absent, then report the uncommitted scaffold.
 
 ## When the owner decides
 
-Only the five things above, and only through the grilling loop. Replacing
-authority that already exists and looks healthy is the owner's call, never a
-convenience on the way to a clean start — preserve it and report what you found.
-
-Where the host cannot ask at all, leave the one-line goal empty and say plainly
-that it is empty, that goal injection will therefore be empty, and that the next
-skill asks again. Do not infer it from the directory name.
+The owner confirms the one-line outline and any replacement of healthy authority. Where
+the host cannot ask, leave unresolved fields explicit and recommend resuming Init on a
+host that can; do not infer intent from the directory name. Recommend Research after a
+usable brief exists, but do not invoke it.
 
 ## References
 
-- `../ultra-grilling/SKILL.md` — the loop; read it before the first question.
-- `../ultra-domain-modeling/SKILL.md` — read when the first term needs writing.
-- `references/brownfield-adoption.md` — read for either existing-code route.
-- `../ultra-think/references/autonomy-boundary.md` — read before touching
-  authority that already exists.
+- `../ultra-grilling/SKILL.md` — read before the first missing brief field.
+- `references/brownfield-adoption.md` — read when maintained behavior already exists.
+- `../ultra-think/references/autonomy-boundary.md` — read before replacing authority.

package/skills/ultra-init/references/brownfield-adoption.md

@@ -1,49 +1,32 @@
-# Brownfield adoption
+# Brownfield initialization
 
-Use this procedure only when `ultra-init` detects an existing codebase without a
-healthy `.ultra/` authority surface. Initialization records the observable baseline;
-it does not redesign the application or accept claims the repository cannot support.
+Use this procedure only when `ultra-init` finds maintained behavior but no healthy,
+complete Ultra skeleton. Init preserves the checkout and prepares an evidence route; it
+does not establish the brownfield baseline.
 
 ## Bind the repository boundary
 
-Record the repository root, selected workspace roots, branch, `HEAD`, dirty files,
-generated and vendored exclusions, manifests, verification commands, and public
-seams. Keep out-of-scope dirty files visible as context without treating them as part
-of the selected baseline.
+Identify the repository root, selected workspace roots, branch, `HEAD`, dirty files,
+generated or vendored exclusions, manifests, maintained documents, verification
+commands, and visible public entry points. Resolve these from files and Git instead of
+asking the owner.
 
-## Inspect the maintained system
+## Preserve before interpreting
 
-Trace product behavior through real entry points, runtime consumers, persistence,
-integrations, permissions, failure paths, tests, deployment, observability, and
-recovery. Classify every material statement as `Observed`, `Verified`, `Decided`, or
-`Unknown`. Record maintained-document conflicts as drift.
+- Never replace existing `.ultra` files, `CONTEXT.md`, decisions, or maintained project
+  documents merely to obtain the current template shape.
+- Treat source, tests, runtime configuration, and documentation as evidence candidates,
+  not conclusions Init may promote.
+- Keep out-of-scope dirty files visible in the report without adding them to the
+  Project Brief or specification skeletons.
+- Record an exact legacy one-line as raw intake only when the Project Brief is empty.
 
-## Write the baseline once
+## Prepare the Research handoff
 
-- Update `.ultra/specs/product.md` with delivered behavior and acceptance.
-- Update `.ultra/specs/architecture.md` with boundaries, authority, consumers,
-  permissions, failures, and recovery.
-- Update `.ultra/specs/discovery.md` with scope evidence, known defects, drift, and
-  unresolved questions.
-- Initialize `.ultra/tasks.json` and `.ultra/test-report.json` from the packaged
-  templates without manufacturing passing results.
+List the concrete paths and live seams that can answer each open baseline question.
+`ultra-research` establishes the observed and accepted baseline from those sources. Init
+does not run verification, classify delivered behavior, reconcile documentation drift,
+or write product, discovery, or architecture conclusions.
 
-Use the specifications as the canonical representation. Do not create a second
-baseline ledger, database projection, or generated semantic mirror.
-
-## Characterize verification
-
-Run the repository's existing verification commands. Record each result as `pass`,
-`known_red`, or `not_run`; a missing command is not a pass. A critical public seam
-without a stable signal is an explicit gap, not an excuse to invent completion.
-
-## Converge
-
-Read every written file back, show the owner the selected scope, observed behavior,
-drift, known-red verification, unknowns, and material decisions, and leave unresolved
-items marked `[NEEDS CLARIFICATION]`. Adoption is ready when the file set is complete,
-the recorded revision matches the inspected checkout, and every material gap remains
-visible with its evidence and owner decision where one exists.
-
-Recommend `ultra-change` for subsequent work and stop; public skills do not invoke one
-another.
+Report the preserved files, repository boundary, candidate evidence, and unresolved
+questions. Recommend Research and stop; public workflows never invoke one another.

package/skills/ultra-plan/SKILL.md

@@ -5,24 +5,32 @@ description: Turn an evidenced Change intent into a dependency-valid task ledger
 
 # Turn one Change into executable tracer bullets
 
-Planning owns decomposition and technical design. Files carry the result across
-sessions and hosts; no runtime state decides whether the plan is meaningful.
+Planning owns decomposition and technical design; files carry it across sessions and hosts.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json`; if a task is unfinished, read its `context_file` and
-   closing `## Resume Note` before replacing or extending anything.
-2. Read `CONTEXT.md` for vocabulary and the relevant `.ultra/decisions/` entries.
-3. Read the active Change intent, its `trace_to` specification anchors, and the
+1. Resolve exactly one `.ultra/changes/active/<change_id>/intent.md`. If none or more
+   than one exists, stop with that file conflict. The intent must be `accepted`, every
+   blocking decision resolved, and its `## Research Disposition` exit evidence
+   satisfied before decomposition.
+2. Read `.ultra/tasks.json`; select matching tasks and read each unfinished context and
+   Resume Note. Preserve all historical tasks in the append-only ledger.
+3. Read `CONTEXT.md` for vocabulary and the relevant `.ultra/decisions/` entries.
+4. Read the active Change intent, its `trace_to` specification anchors, and the
    source, tests, consumers and recovery paths those anchors describe.
 
 ## Definition of done
 
-- `.ultra/tasks.json` and one `.ultra/contexts/task-<id>.md` per task agree on
-  identifiers, status, dependencies and trace anchors.
-- The owner confirmed the scope posture and the seam list.
+- `.ultra/tasks.json` and one `.ultra/contexts/task-<id>.md` per current-Change task
+  agree on identifiers, stable `change_id`, status, dependencies and trace anchors.
+- The owner confirmed any material posture. Seams resolve to code; technical selection
+  stays model-owned unless it changes public contract, accepted risk, or material trade-off.
 - Every feature task is a tracer bullet touching at least two layers, unless the
   Change itself demonstrably touches only one layer.
+- Every context names the north-star hard constraints its work could violate, and
+  each `HC-<n>` it names resolves to a real entry in `.ultra/north-star.md`.
+- Every Change acceptance id maps to at least one task context, and every context id
+  resolves back to the active Change.
 - Coverage, dependency, trace, scope and context-budget checks have concrete results.
 
 ## Fix the planning posture
@@ -34,8 +42,8 @@ separate `plan.md` authority.
 Use `../ultra-grilling/SKILL.md` through the host-native question surface when the
 choice remains material, one question with a recommendation at a time.
 
-If the work cannot fit in one session *and* the path itself is still unclear, use
-`../ultra-think/SKILL.md` to resolve decision tickets before decomposing tasks.
+When the whole path is still unclear, recommend `ultra-research`; the Change is not yet
+evidenced enough to decompose. For one consequential trade-off, use `../ultra-think/SKILL.md`.
 
 ## Choose the plan shape
 
@@ -54,39 +62,55 @@ Build the graph with these structural defences:
 - A feature task that touches only one of several affected layers is merged or split
   into a tracer bullet; moving a whole layer into one task is horizontal slicing.
 
-Confirm the seam list before tests are written. Reuse an existing public seam and use
-the highest seam that observes the behavior; one seam is ideal when it covers the path.
+Record seams before tests. The model chooses the technical seam: prefer an existing,
+highest observable public seam, ideally one. Ask the owner only when it changes the
+public contract or another material product, risk, or recovery trade-off.
 
 ## Write the files
 
 Each task records `id`, `title`, `type`, `priority`, `complexity`, `status`,
-`dependencies`, `context_file`, `trace_to` and `change_ref`. Complexity is only a
+`dependencies`, `context_file`, `trace_to` and `change_id`. Task ids are globally
+unique, and every dependency must name a task with the same `change_id`; an archived
+Change must never become an implicit prerequisite of current work. Complexity is only a
 splitting and context signal: 1–2 is local, 3–5 is bounded, 6–7 crosses a boundary,
 and complexity > 7 must split.
 
-Each context records Acceptance, confirmed seams, layers touched, target files,
-Implementation, verification commands, Definition of Drift, Change Log, Completion
-and Resume Note. Read every file back; task count and context count must match.
+Append new tasks or repair matching current-Change tasks in place; never replace the
+ledger with only the latest graph. A `quick` Change produces exactly one minimal task
+and context rather than bypassing the task/evidence lifecycle.
+
+Each context records Change Acceptance IDs, task-local Acceptance, confirmed seams,
+layers touched, target files, Implementation, verification commands, the hard
+constraints the work could violate, Definition of Drift, Change Log, Completion and
+Resume Note. Read every file back; task count and context count must match.
+
+Name a hard constraint whenever the task could plausibly breach it, not only when you
+expect it to. The entry costs one line and is what makes a later breach a checkable
+question instead of a judgement call; `none` is a legitimate answer for a task that
+touches nothing constrained.
 
 ## Verify the plan
 
-1. Map every in-scope user story or acceptance anchor to at least one task.
+1. Map every Change acceptance ID to at least one task context and reject dangling
+   context IDs. Map every in-scope user story or specification anchor to at least one task.
 2. Walk dependencies and repair every cycle with the exact cycle chain visible.
 3. Resolve every `trace_to` path and heading against a real file.
-4. Surface complexity, more than eight target files, or more than twenty tasks as
+4. Resolve every `HC-<n>` against `.ultra/north-star.md`. A dangling constraint id is
+   the same defect as a dangling `trace_to`: it reads as checked and never was.
+5. Surface complexity, more than eight target files, or more than twenty tasks as
    scope warnings; they are observations, not semantic verdicts.
-5. Estimate context at roughly `complexity × 5%`; surface anything above 40%.
+6. Estimate context at roughly `complexity × 5%`; surface anything above 40%.
 
 Report the graph, frontier, seams, warnings and first task. Recommend the next explicit
 capability from the files; do not invoke it.
 
 ## When the owner decides
 
-The owner chooses the posture, confirms seams, resolves reductions and accepts material
-omissions. Mechanical cycles and broken paths are repaired before handoff because they
-make the written graph impossible to execute.
+The owner chooses material posture, reductions, omissions, and any seam changing public
+contract or material trade-off. The model owns technical decomposition and seams.
+Repair mechanical cycles and broken paths before handoff.
 
 ## References
 
 - `../ultra-grilling/SKILL.md` — read before a material posture or seam question.
-- `../ultra-think/SKILL.md` — read when fog of war requires decision tickets.
+- `../ultra-think/SKILL.md` — read when one evidenced decision blocks decomposition.

package/skills/ultra-research/SKILL.md

@@ -1,82 +1,111 @@
 ---
 name: ultra-research
-description: Turn owner claims and specification gaps into cited product and architecture evidence, then refresh the canonical specifications and research distillate. Use when initialization, brownfield adoption, or an active Change contains claims that must be verified before planning.
+description: Turn a raw Project Brief or scoped evidence gap into an accepted North Star, domain language, cited product and architecture specifications, and a hash-bound synthesis. Use after initialization, for brownfield baselining, or inside an active Change whose consequential claims are not yet evidenced.
 ---
 
-# Verify claims and fill the specification gaps they control
+# Mature a project outline into an evidence-backed baseline
 
-Research owns evidence and synthesis. The owner chooses material scope and accepts the
-three conclusions that change what later research does. Files are written immediately,
-so interruption loses no completed investigation.
+Research owns the first accepted baseline and later evidence-backed corrections. Web
+search is one evidence source, not the workflow: repository files, Git, tests, runtime,
+maintained documentation, owner decisions, and current primary sources all count.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json`; if it names unfinished work, read its `context_file` and
-   closing `## Resume Note` before choosing research scope.
-2. Read `CONTEXT.md` for vocabulary and relevant `.ultra/decisions/` entries.
-3. Read `.ultra/north-star.md`, the active Change intent if any, and specification
-   sections carrying `[NEEDS CLARIFICATION]`.
+1. Resolve at most one active `change_id`, then read `.ultra/tasks.json` plus the
+   `context_file` and `## Resume Note` of unfinished tasks whose `change_id` matches it,
+   if any. Archived or abandoned unfinished rows are history, not the current frontier.
+2. Read `.ultra/project-brief.md`. For a legacy project without it, treat the exact
+   `.ultra/north-star.md` `## One-line` as raw intake until a brief is preserved.
+3. Read existing `.ultra/north-star.md`, specifications, `CONTEXT.md`, relevant
+   `.ultra/decisions/`, active Change intent, evidence, Git state, and maintained docs.
 
 ## Definition of done
 
-- Every selected area has a cited report under `.ultra/research/<run-id>/` and its
-  mapped specification section reflects the current conclusion.
-- `99-synthesis.md` states what entered a specification or decision, and what remains
-  unknown or deferred.
-- `.ultra/specs/research-distillate.md` records the Git blob hash of each specification
-  it summarizes; a hash mismatch makes the distillate stale, never authoritative.
-- Material omissions and `[UNVERIFIED: no web access]` findings stay visible.
-
-## Select the coverage once
-
-Scan unresolved specification headings, map them to the seventeen focused references,
-and recommend the smallest sufficient profile: Full, Product Only, Feature Only,
-Architecture Change, or Custom. Confirm the list once with the owner. Load one reference
-at a time; holding several step prompts together defeats progressive disclosure.
-
-The three checkpoints are `04-product-strategy`, `21-features-scope`, and
-`99-synthesis`: each conclusion changes what comes next. Present its evidence and
-recommendation, wait for the owner's decision, then continue. Other areas write their
-report and mapped section immediately without another ceremony.
-
-## Investigate and write
-
-For each selected area:
-
-1. Search current primary sources and inspect relevant source, tests, runtime and docs.
-2. Separate Observed, Evidence, Inference and Unknowns; cite every external claim.
-3. For solution strategy and building blocks, cite at least one real implementation in
-   a comparable maintained project, not only an opinion article.
-4. Write `.ultra/research/<run-id>/<area>.md`, then replace the mapped specification
-   section rather than appending a second version. Git keeps the history.
-5. Follow `../ultra-domain-modeling/SKILL.md` when evidence settles a domain term. Use
-   `../ultra-think/SKILL.md` when a consequential trade-off meets the decision criteria.
-
-If web search is unavailable, write `[UNVERIFIED: no web access]` and continue. Lack of
-a tool lowers confidence; it does not create a dead end.
-
-## Synthesize
-
-Load `references/99-synthesis.md` after the selected reports are on disk. Write which
-claims were confirmed, overturned, deferred, or converted into decisions. Update the
-specification balances, then write the distillate and its three source blob hashes.
-Read all changed files back and report the exact unresolved headings.
-
-Recommend the next explicit capability from the resulting files; do not invoke it.
+- Every selected lens has a cited `.ultra/research/<run-id>/<area>.md` report and its
+  canonical specification section contains the current conclusion.
+- The accepted North Star, shared vocabulary, product baseline, and architecture
+  baseline are sufficient for the current planning boundary; unknowns stay explicit.
+- `99-synthesis.md` names what was promoted, overturned, deferred, or left blocking.
+- `.ultra/specs/research-distillate.md` stores the Git blob hash of each specification
+  it summarizes. A mismatch makes the distillate stale, never authoritative.
+
+## Find the path before collecting evidence
+
+When coverage spans several lenses or the path itself is unclear, read
+`references/wayfinding.md` and write `.ultra/research/<run-id>/brief.md`. Skip that file
+for one already-bounded evidence question. Wayfinding selects the smallest useful
+coverage; it does not create workflow state or another semantic authority.
+
+Map the brief and unresolved specification sections to seventeen focused evidence
+lenses. Confirm the proposed coverage once with the owner. Load one reference
+at a time; the parent holds the question map, not every step prompt.
+
+The first six lenses have real semantic dependencies:
+
+- `00-problem-validation` runs before `01-opportunity-discovery` because an opportunity must trace to a problem.
+- `02-market-assessment` and `03-alternatives` are conditional lenses and may run in parallel once the boundary is known.
+- `04-product-strategy` is the first owner checkpoint and consumes the relevant conclusions from `00` through `03`.
+- `05-assumptions-validation` extracts load-bearing assumptions from `00` through `04` after the strategy decision.
+
+The later groups turn that premise into product behavior (`10` through `22`), then an
+architecture and operating baseline (`30` through `41`). The three owner checkpoints
+remain `04-product-strategy`, `21-features-scope`, and `99-synthesis`.
+
+Only areas with satisfied inputs may fan out through native bounded subagents. Never
+parallelize a lens whose question depends on an unresolved earlier conclusion.
+
+## Investigate, ask, and decide
+
+For each selected lens:
+
+1. Inspect reachable facts before asking. Search current primary sources when a claim
+   depends on current external reality.
+2. Separate Observed, Verified, Decided, Inference, and Unknown; cite external claims.
+3. Follow `../ultra-grilling/SKILL.md` when a required owner field is missing. The lens
+   supplies what to ask; Grilling supplies the one-question interaction loop.
+4. Follow `../ultra-think/SKILL.md` for one consequential trade-off, not for mapping the
+   whole research frontier.
+5. Follow `../ultra-domain-modeling/SKILL.md` when evidence settles a shared term. The
+   first such term creates `CONTEXT.md`; later calls sharpen it.
+6. Write the area report, then replace the mapped specification section instead of
+   appending a second version. Git retains history.
+
+For scoped Research inside an active Change, answer only its recorded `Research
+Disposition` question and produce the named exit evidence. Research writes reports and
+the mapped canonical baseline sections; it does not silently rewrite Change acceptance.
+Return the evidence paths so `ultra-change` can reconcile the accepted intent before
+planning when that contract must change.
+
+If web access is unavailable, record `[UNVERIFIED: no web access]` and continue with
+other evidence. Missing tooling lowers confidence; it does not manufacture a blocker.
+
+## Synthesize the accepted baseline
+
+`04-product-strategy` proposes the direction. `22-success-metrics` determines whether a
+single North Star metric is justified or whether an observable outcome plus guardrails
+is more honest. After the owner accepts `99-synthesis`, update `.ultra/north-star.md`,
+the three specifications, domain language, qualifying decisions, and the distillate for
+the first baseline. A scoped Research run updates only its mapped specification sections
+and then refreshes the distillate's three source hashes.
+
+Load `references/99-synthesis.md` only after selected reports exist. Read every promoted
+file back, verify trace anchors and source hashes, and report exact unresolved gaps.
+Recommend the next explicit public workflow from the resulting files; do not invoke it.
 
 ## When the owner decides
 
-The owner chooses coverage, resolves the three checkpoints, and accepts any material
-deferral. Evidence facts are yours to establish. A conclusion that removes an existing
-commitment follows the REDUCTION boundary and waits for explicit authority.
+The owner chooses coverage, resolves the three checkpoints, accepts a North Star and
+material deferrals, and authorizes any REDUCTION. The model establishes evidence facts,
+selects methods, and updates accepted files inside that frame.
 
 ## References
 
+- `references/wayfinding.md` — read only for multi-lens or unclear research paths.
 - `references/00-problem-validation.md` through `references/05-assumptions-validation.md`
-  — product premise and strategy; load only a selected area.
-- `references/10-user-personas.md` through `references/22-success-metrics.md` — users,
-  stories, scope and measurable outcomes; load only a selected area.
+  — product premise and strategy; load only a selected lens.
+- `references/10-user-personas.md` through `references/22-success-metrics.md` — actors,
+  behavior, scope, and measurements.
 - `references/30-architecture-context.md` through `references/41-quality-risks.md` —
-  system boundary, implementation evidence, deployment and risk.
+  system boundary, implementation evidence, operations, and risk.
 - `references/99-synthesis.md` — load last, after selected reports exist.
-- `../ultra-think/references/autonomy-boundary.md` — read before a specification shrinks.
+- `../ultra-think/references/autonomy-boundary.md` — read before reducing authority.

package/skills/ultra-research/references/{03-competitive-landscape.md → 03-alternatives.md}

@@ -1,25 +1,25 @@
-# Competitive landscape
+# Alternatives
 
-Use for workflow step `03-competitive-landscape`.
+Use for workflow step `03-alternatives`.
 
 ## Objective
 
 Identify the alternatives actors actually use and the consequences for strategy.
-Alternatives may include direct products, adjacent tools, manual workflows, or doing
-nothing.
+Alternatives include direct products, adjacent tools, manual workflows, or doing
+nothing; a competitor-only frame is too narrow.
 
 ## Evidence
 
 - Use current product documentation, pricing, repositories, filings, or observed user
   workflows.
 - Evaluate only criteria that change the decision at hand.
-- Do not create a ceremonial matrix, fixed competitor count, or unsupported claim of
+- Do not create a ceremonial matrix, fixed alternative count, or unsupported claim of
   superiority.
 - Distinguish a verified capability from marketing language and inference.
 
 ## Record
 
-Update `discovery.md` with the relevant alternatives, evidence, meaningful differences,
+Update `discovery.md` with relevant alternatives, evidence, meaningful differences,
 switching constraints, and durable strategy implications. Record an unknown when a
 credible alternative cannot be verified.