ultra-builder-pro-cli 0.26.1 → 0.26.2

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,22 +5,26 @@ 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
@@ -38,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
 
@@ -58,16 +62,23 @@ 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.
 
+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
@@ -95,11 +106,11 @@ 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,88 +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.
-
-Areas sitting between two checkpoints are independent and may run in parallel through
-the host's native bounded subagents, each loading exactly one reference. That
-strengthens progressive disclosure rather than breaking it — the parent holds no step
-prompt at all. The checkpoints stay barriers: nothing after one starts until the owner
-has answered it, because its conclusion changes what the later areas are even asking.
-
-## 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.
 

package/skills/ultra-research/references/22-success-metrics.md

@@ -12,13 +12,17 @@ including signals that would reveal harmful optimization.
 - Derive measurements from accepted outcomes and available instrumentation.
 - State definition, source, observation window, owner, and decision use.
 - Separate current measurements, target decisions, and unavailable telemetry.
-- Do not invent baselines, targets, or a single north-star metric.
+- Propose one North Star outcome or metric when justified by delivered value and a
+  credible observation contract.
+- Do not force a single metric, or invent baselines and targets, when guardrails plus an
+  observable outcome represent the product more honestly.
 
 ## Record
 
-Update `product.md` with outcome measures, operational measures, guardrails, evidence
-availability, and unresolved instrumentation needs. A metric that cannot be observed
-must be recorded as a gap or explicit future change.
+Update `product.md` with supporting outcome measures, operational measures, guardrails,
+evidence availability, and unresolved instrumentation needs. Propose the canonical
+`NS-01` entry for `north-star.md`; it becomes authority only through accepted synthesis.
+A metric that cannot be observed is a gap or explicit future Change.
 
 Complete the step with evidence references and the updated output path.
 

package/skills/ultra-research/references/99-synthesis.md

@@ -20,9 +20,16 @@ creating a second condensed authority.
 
 ## Record
 
+Update `.ultra/north-star.md` with the accepted project direction, North Star outcome or
+explicit no-single-metric decision, hard constraints, exclusions, and Research trace.
+Keep raw owner wording in `project-brief.md`; do not process it in place.
+
 Write `research-distillate.md` as a navigation and traceability artifact containing
 baseline ids, source document anchors, accepted decisions, blockers, gaps, verification
-evidence, and the exact planning entry. Do not duplicate the specifications' prose.
+evidence, the exact planning entry, and the current Git blob hash from
+`git hash-object` for `product.md`, `architecture.md`, and `discovery.md`. Do not
+duplicate the specifications' prose. A later mismatch marks the distillate stale; it
+does not make the old synthesis authoritative.
 
 Write the final `99-synthesis.md` report, link all three specification paths, the
 distillate path, and the evidence used for synthesis. Read those files back before

package/skills/ultra-research/references/wayfinding.md

@@ -0,0 +1,42 @@
+# Research wayfinding
+
+Use this method when Research spans several lenses or the path itself is unclear. Skip
+it for one bounded evidence question whose destination is already known.
+
+## Objective
+
+Turn fog into a small question map without turning the map into workflow authority.
+Select the smallest sufficient coverage that can establish the current baseline or
+unlock the active Change.
+
+## Inspect first
+
+Read the Project Brief, accepted authority, unresolved specification sections, current
+repository evidence, active Change, and owner statements already present. Do not ask a
+question whose answer is reachable in those sources.
+
+## Write the run brief
+
+Write `.ultra/research/<run-id>/brief.md` with:
+
+- entry question and planning boundary;
+- known facts and their sources;
+- unknowns, each with the decision it can change;
+- selected lenses, semantic dependencies, and explicit omissions;
+- likely evidence sources and current freshness limits;
+- owner decisions and the checkpoint that owns each one;
+- a stop condition stated as an observable artifact or resolved decision.
+
+The brief is derived navigation, not semantic authority. Specifications, the North Star,
+`CONTEXT.md`, and accepted decisions remain canonical. Rebuild or discard the map when
+evidence changes; never add a completion flag merely to route another Skill.
+
+## Keep the frontier small
+
+Prefer one load-bearing question over a speculative tree. Add a branch only when a
+viable answer would change selected evidence, product direction, scope, or architecture.
+Questions that cannot change the current boundary belong in explicit deferred work, not
+the active map.
+
+Wayfinding chooses where to investigate. Each evidence lens defines what to establish;
+Grilling defines how to ask the owner; Think resolves one consequential decision.

package/skills/ultra-review/SKILL.md

@@ -10,7 +10,10 @@ happens here, after several slices make a useful structure visible, not inside T
 
 ## Before you start
 
-1. Read `.ultra/tasks.json`, the scoped task's `context_file` and `## Resume Note`.
+1. Resolve the review scope first. For task or active-Change review, resolve exactly one
+   active `change_id`, read `.ultra/tasks.json`, and select only matching tasks before
+   reading the scoped task's `context_file` and `## Resume Note`. Historical review must
+   name its archived Change explicitly and never infer scope from unfinished status.
 2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, acceptance, evidence and exact diff.
 3. Create `.ultra/reviews/<session>/` and one immutable packet naming HEAD, scope,
    output path, acceptance and public seams. Follow `references/worker-packet.md`,