ultra-builder-pro-cli 0.26.1 → 3.0.2

package/skills/ultra-research/SKILL.md

@@ -1,88 +1,139 @@
 ---
 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 is the first semantic writer of North Star v2 and owns the first accepted
+baseline plus 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. If model-selected, verify the live execution grant in `../ultra-change/references/execution-grant.md` — a current session-local activation or a stably verified durable work-package grant; without either, stop.
+2. 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.
+3. 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.
+4. Read existing `.ultra/north-star.md`, specifications, `CONTEXT.md`, relevant
+   `.ultra/decisions/`, active Change intent, evidence, Git state, and maintained docs.
+   Run `node <ultra-research-skill-dir>/scripts/validate_north_star.cjs
+   .ultra/north-star.md`; this entry captures one bounded regular non-symlink snapshot
+   and returns a typed repair diagnostic instead of following, blocking on, or validating
+   a changing path. Treat `unresearched` as an empty destination and `legacy_unadopted`
+   as preserved intake for explicit adoption, not accepted v2 truth.
 
 ## 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 and North Star relation.
+- The accepted North Star, shared vocabulary, product baseline, and architecture
+  baseline are sufficient for the current planning boundary; unknowns stay explicit.
+- The North Star follows `references/north-star-v2.md`; all `FP-*`, `NS-*`, and `HC-*`
+  definitions and references pass the structural validator without making that result
+  a semantic verdict.
+- `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`.
+At each checkpoint, use `../ultra-think/SKILL.md` for an adversarial challenge of the
+working candidate before asking the owner to accept direction, scope, or 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.
+   Record `north_star_effect: supports | refines | contradicts | independent` and
+   `north_star_claim: <the evidenced causal relation>` in the area report.
+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 problem reality and falsifiable first-principle
+propositions. `22-success-metrics` determines whether a
+single North Star metric is justified or whether an observable outcome plus guardrails
+is more honest. Follow `references/north-star-v2.md`: validate a mutable candidate while
+the last accepted revision remains current, show the owner the semantic delta and
+unresolved contradictions, and preserve one stable `.ultra/decisions/<id>.md` acceptance
+record with the owner's exact words, conversation scope, the model's responsibility for
+final wording, and no invented timestamp or inheritance by a future revision. Only after
+the owner accepts the candidate, atomically replace `.ultra/north-star.md`, then update the three
+specifications, domain language, qualifying decisions, and distillate for the first
+baseline. A scoped Research run updates only its mapped specification sections and then
+refreshes the distillate's three source hashes.
+
+When an accepted revision supersedes another, preserve prior evidence and report every
+active Change whose recorded revision or digest differs as a stale observation requiring
+Change reconciliation. Supersession never deletes evidence, rewrites a Change silently,
+or grants execution.
+
+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.
+- `references/north-star-v2.md` — exact semantic structure, adoption, validation, and
+  supersession contract.
+- `../ultra-change/references/execution-grant.md` — read only for grant-activated continuation.
+- `../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/04-product-strategy.md

@@ -4,8 +4,8 @@ Use for workflow step `04-product-strategy`.
 
 ## Objective
 
-Turn accepted evidence into a product direction, target boundary, value proposition,
-and explicit tradeoffs.
+Turn accepted evidence into problem reality, falsifiable first-principle propositions,
+a product direction, target boundary, value proposition, and explicit tradeoffs.
 
 ## Evidence and decisions
 
@@ -13,6 +13,8 @@ and explicit tradeoffs.
 - Ask the owner when a scope, customer, business, or risk decision is load-bearing.
 - Do not infer an MVP, reduced scope, release phase, or commercial posture.
 - Record exclusions only when the owner or an accepted constraint establishes them.
+- For each proposed `FP-*`, record evidence, causal consequence, and the falsifier or
+  revisit trigger. The ID becomes canonical only in an owner-accepted synthesis.
 
 ## Record
 
@@ -22,6 +24,7 @@ Update `discovery.md` with:
 - value delivered through observable behavior;
 - chosen tradeoffs and their rationale;
 - constraints, exclusions, and unresolved decisions;
+- the candidate `FP-* -> capability -> behavior -> outcome` causal chain;
 - any defensibility claim with its supporting evidence.
 
 Complete the step with decision and evidence references plus the updated output path.
@@ -30,3 +33,9 @@ Complete the step with decision and evidence references plus the updated output
 
 In the area report, record `tradeoff` and `rationale`, then link the decision file or
 specification anchor to the problems, opportunities, or constraints that support it.
+
+## Adversarial challenge
+
+Before the owner checkpoint, challenge whether the proposed direction follows from the
+underlying problem and first principles, steel-man the best conflicting direction, and
+name evidence that would overturn the working North Star candidate.

package/skills/ultra-research/references/21-features-scope.md

@@ -13,6 +13,8 @@ excluded, deferred, or unresolved.
 - Never infer an MVP, reduced version, phase label, or omission from implementation
   convenience.
 - Trace included capabilities to requirements and observable outcomes.
+- Trace each included capability to candidate `FP-*` and `NS-*` IDs, and name every
+  candidate `HC-*` it could breach, without copying North Star prose.
 - Record dependencies, migrations, compatibility, and operational obligations inside
   the capability that owns them.
 - Keep speculative future ideas outside the active scope unless selected.
@@ -28,3 +30,9 @@ Complete the step with decision evidence and the updated output path.
 
 In the area report, record `requirement_ids`, `scope_status`, and `rationale`, then link
 the capability heading in `product.md`.
+
+## Adversarial challenge
+
+Before the owner checkpoint, challenge whether every included capability causally serves
+the working North Star, whether an exclusion breaks that outcome or a hard constraint,
+and whether the proposed scope can optimize a proxy while missing delivered value.

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

@@ -12,13 +12,18 @@ 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 or more stable `NS-*` outcomes when justified by delivered value and a
+  credible observation contract. Each records observation method, baseline, target or
+  expected change, horizon, and anti-metric.
+- 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-*` entries for `north-star.md`; they become 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

@@ -17,12 +17,30 @@ creating a second condensed authority.
 - Documentation conflicts, known failures, and load-bearing unknowns are in the gap
   ledger with owners or explicit decisions.
 - Verification commands and observed results are current.
+- Every accepted `FP-*` has evidence, causal consequence, and a falsifier or revisit
+  trigger; every `NS-*` has an observation contract and anti-metric; every `HC-*` names
+  the protected value or threat, authority, and revisit condition.
 
 ## Record
 
+Follow `north-star-v2.md`. Validate the complete mutable candidate with
+`scripts/validate_north_star.cjs` while the previous accepted revision remains current.
+Only after the owner accepts this checkpoint and exact semantic delta, record the owner
+acceptance source and atomically replace `.ultra/north-star.md` with accepted problem
+reality, `FP-*` propositions, causal chains, `NS-*` outcomes, `HC-*` constraints,
+exclusions, uncertainties, revisit triggers, and Research trace.
+
+If this supersedes an accepted revision, preserve its Git and downstream evidence.
+Report dependent active Change traces as stale observations until Change reconciliation;
+do not silently rewrite intent or infer new execution authority.
+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
@@ -33,3 +51,9 @@ reporting convergence.
 Record one verified chain through `problem_id`, `scenario_id`, `requirement_ids`,
 `architecture_path_ids`, and `verification_refs`. Every referenced id must exist in an
 earlier selected area report or specification heading.
+
+## Adversarial challenge
+
+Before acceptance, challenge the strongest premise, Goodhart or proxy failure, and a
+scenario where every stated output passes while the claimed delivered value still fails.
+Record what would change the conclusion and every unresolved contradiction.

package/skills/ultra-research/references/north-star-v2.md

@@ -0,0 +1,168 @@
+# North Star v2 contract
+
+Use this contract when Research proposes the first steering authority or a replacement
+revision. Init creates only the packaged `unresearched` placeholder.
+
+## Agency boundary
+
+Research selects evidence, synthesizes causal propositions, and proposes language. The
+owner accepts the problem boundary, `FP-*`, `NS-*`, `HC-*`, exclusions, and material
+uncertainty. The validator observes headings, fields, IDs, and references; it never
+decides whether a proposition is true, an outcome is valuable, or a constraint is wise.
+
+Keep the last accepted file current while a replacement is drafted. Validation failure
+returns diagnostics and leaves the draft mutable. Only explicit owner acceptance permits
+an atomic replacement of `.ultra/north-star.md`.
+
+## Exact top-level headings
+
+1. `## Acceptance and Revision`
+2. `## Problem Reality`
+3. `## First-Principle Propositions`
+4. `## Value Causal Chain`
+5. `## North Star Outcomes`
+6. `## Hard Constraints`
+7. `## Explicit Exclusions`
+8. `## Uncertainties and Revisit Triggers`
+9. `## Research Trace`
+
+`Acceptance and Revision` records `Schema`, `Status`, `Revision`, `Owner acceptance
+source`, `Acceptance time`, and `Supersedes`. Do not invent a timestamp: use
+`not-recorded` when the authoritative owner source has none. `Status` is exactly
+`unresearched` for the empty Init placeholder, `draft` for a mutable candidate, or
+`accepted` after owner acceptance. A draft may define semantic IDs but must use
+`Owner acceptance source: none`; every First-Principle Proposition in an accepted
+revision has `Status: accepted`.
+
+The `unresearched` form is one exact packaged byte sequence, not a looser shape. Its
+title, authority and adoption preamble, all six acceptance fields, all eight later
+sentinel bodies, interstitial whitespace, and trailing newline must match
+`.ultra-template/north-star.md`. Any mutation is invalid and Init stops before publication
+with an `ultra-init-error-v1` payload: `code: north_star_template_invalid`, plus the full
+canonical validator `diagnostics`, including `invalid_unresearched_placeholder` for an
+exact-byte mismatch. This checksum-backed grammar prevents Init from becoming a hidden
+semantic writer; it does not judge any researched proposition.
+
+## Stable semantic entries
+
+Define accepted entries with level-three headings. IDs are stable within project
+history, unique, and never silently recycled.
+
+```markdown
+### FP-1 — Short name
+- Proposition:
+- Evidence:
+- Causal consequence:
+- Falsifier or revisit trigger:
+- Status: `accepted`
+
+### NS-1 — Short name
+- Outcome:
+- Observation method:
+- Baseline:
+- Target or expected change:
+- Horizon:
+- Anti-metric:
+
+### HC-1 — Short name
+- Protected value or threat:
+- Constraint:
+- Authority or evidence:
+- Revisit condition:
+```
+
+Do not impose a maximum count. Prefer the smallest set that explains the accepted
+boundary, but let Research and the owner decide semantic sufficiency.
+
+The Value Causal Chain references definitions instead of repeating them:
+
+```text
+FP-* -> capability -> observable behavior -> NS-*
+```
+
+In a draft or accepted revision every pipe-delimited causal-chain row has exactly five
+cells. Header and separator rows use that same width; each data row carries a `VC-*`, a
+resolving `FP-*`, nonempty capability and behavior, and a resolving `NS-*`. A malformed
+row remains invalid even when another row is valid. Every one of the nine required
+sections is nonempty for accepted publication; these are exact structural observations,
+not a mechanical claim that the content is semantically sufficient.
+
+Supporting product behavior, actors, requirements, measurements, and architecture stay
+in specifications. Shared vocabulary stays in `CONTEXT.md`. Change-local outcome,
+non-goals, acceptance, risk, and recovery stay in the active intent.
+
+## Validation and adoption
+
+Callers that already own a bounded stable no-symlink snapshot pass those exact bytes
+through stdin while identifying the canonical absolute path:
+
+```bash
+node <ultra-research-skill-dir>/scripts/validate_north_star.cjs --stdin --path <canonical-absolute-path>
+```
+
+Research and manual callers may instead use the direct path entry:
+
+```bash
+node <ultra-research-skill-dir>/scripts/validate_north_star.cjs <candidate-path>
+```
+
+Path mode applies the same 8 MiB ceiling itself. It requires a regular non-symlink file,
+opens with `O_NONBLOCK` and `O_NOFOLLOW`, binds the pre-read `lstat` to the open
+descriptor, and rechecks descriptor/path identity, size, and the retained-byte digest
+after the bounded read. An oversized file, symlink, special file, read failure, or
+observable ordinary replacement returns `input_too_large`, `input_symlink`,
+`input_not_regular`, `read_error`, or `input_changed`; preserve the current path and
+retry after cooperative workspace writes settle. No typed input failure is a semantic
+judgment or a promise to defeat a malicious operating-system-level writer.
+
+Every verdict over a completed byte snapshot carries `input.path`, `input.byte_length`,
+and `input.sha256` for those bytes. A capture failure keeps the same keys but uses null
+for any byte length or digest it could not safely observe. Markdown headings, grammar
+fields, causal rows, and decision-record fields count only rendered lines outside
+backtick or tilde fences; acceptance binding still hashes the exact raw bytes.
+SessionStart applies the same 8 MiB stable no-symlink snapshot limit and validates those
+same bytes, rather than reopening a different path snapshot.
+
+The command emits `ultra-north-star-validation-v1`. The actual v0.26 shape containing
+`Project Direction`, `North Star Outcome`, and `Hard Constraints`, and the older
+`## One-line` form, are reported as `legacy_unadopted` with an advisory. A candidate
+combining v2 markers with a legacy semantic heading is reported with
+`kind: "north-star-v2"`, its parsed v2 `status`, `classification: "mixed"`, and
+`valid: false`; appending a legacy heading cannot bypass v2 validation. Other malformed
+shapes are `unknown` and invalid. Research must migrate legacy input through an
+owner-accepted replacement rather than mutating it in place.
+
+Init consumes a preserved North Star from the same stable descriptor/path identity and
+SHA-256 snapshot used for classification, and rechecks that snapshot before staging,
+before publication, and before success. Under the cooperative-workspace contract, any
+observable authority-path or byte drift preserves the current bytes and returns the
+typed retryable `preserved_north_star_changed` diagnostic. Other preserved or newly
+published Init paths use the same recovery rule and the typed retryable
+`initialization_snapshot_changed` diagnostic. This is detectable-drift protection, not
+a promise that Node filesystem calls can defend against a malicious operating-system-
+level replacement.
+
+For an accepted replacement:
+
+1. preserve the current accepted file while drafting and validating the candidate;
+2. challenge premise, falsifiers, causal chain, proxy failure, exclusions, and hard
+   constraints independently;
+3. show the owner the semantic delta and unresolved contradictions;
+4. preserve a stable decision record with the owner's exact words, conversation scope,
+   the model's responsibility for final wording, and a rule that future revisions do not
+   inherit acceptance; record no timestamp the owner source did not provide;
+5. atomically replace the canonical file;
+6. record that dependent active Change traces are stale observations until Change
+   reconciliation maps old `FP/NS/HC` references to the new revision.
+
+The cited decision fragment resolves exactly one rendered Markdown heading outside fenced
+code. That section carries each of these list fields exactly once with a nonempty value:
+`Conversation scope`, `Exact raw owner acceptance`, `Agency boundary`, `Time boundary`,
+and `Revision boundary`. The validator observes only their anchored presence, uniqueness,
+and nonempty bytes. It does not decide whether the quoted acceptance is genuine,
+sufficiently informed, or semantically adequate; those judgments remain with the owner
+and model.
+
+Never delete old task, review, Test, or delivery evidence because of supersession. Git
+preserves the old North Star revision; canonical consumers retain their historical
+revision and digest while current execution waits for explicit reconciliation.

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

@@ -0,0 +1,50 @@
+# 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.
+
+## North Star Working Candidate
+
+In the same brief, keep the current candidate outcome, `FP-*` propositions, causal chain,
+evidence, counter-evidence, and the accepted `.ultra/north-star.md` revision and digest it
+began from. Update
+this section as lenses refine or contradict it. It is derived navigation and not semantic
+authority; only accepted synthesis can replace the canonical North Star.
+
+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.