ultra-builder-pro-cli 0.26.2 → 5.0.0

package/skills/ultra-research/SKILL.md

@@ -5,26 +5,53 @@ description: Turn a raw Project Brief or scoped evidence gap into an accepted No
 
 # Mature a project outline into an evidence-backed baseline
 
-Research owns the first accepted baseline and later evidence-backed corrections. Web
+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.
 
+## Route modes
+
+| Mode | Entry | Observable exit | Next |
+|---|---|---|---|
+| `baseline` | Explicit owner invocation with a usable Project Brief and no accepted baseline for the boundary | Selected reports, synthesis, specifications, vocabulary, and accepted North Star are read back; unknowns and omissions remain explicit | Recommend `ultra-change` in `intake` mode for the next bounded request |
+| `change-scoped` | Explicit invocation or a valid Execution Grant for one active Change's recorded Research Disposition | The named exit evidence exists and the selected canonical sections are refreshed without changing Change acceptance | Return to the same `ultra-change` in `reconcile` mode |
+
+Follow `../ultra-status/references/route-contract.md`. At entry, name the mode, entry
+question, selected coverage, observable stop condition, and return route. Refresh the
+Route Card at each material checkpoint, pause, and exit; lens counts are navigation, not
+proof that Research is semantically complete.
+
 ## Before you start
 
-1. Resolve at most one active `change_id`, then read `.ultra/tasks.json` plus the
+1. Resolve `baseline` or `change-scoped` from the artifacts and invocation. A
+   model-selected run is valid only for `change-scoped` mode under the live execution
+   grant in `../ultra-change/references/execution-grant.md` — a current session-local
+   activation or a stably verified durable work-package grant covering the same Change;
+   without it, stop and recommend explicit invocation. Baseline adoption is always an
+   explicit-entry mode.
+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.
-2. Read `.ultra/project-brief.md`. For a legacy project without it, treat the exact
+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.
-3. Read existing `.ultra/north-star.md`, specifications, `CONTEXT.md`, relevant
+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 lens has a cited `.ultra/research/<run-id>/<area>.md` report and its
-  canonical specification section contains the current conclusion.
+  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.
@@ -36,9 +63,15 @@ When coverage spans several lenses or the path itself is unclear, read
 for one already-bounded evidence question. Wayfinding selects the smallest useful
 coverage; it does not create workflow state or another semantic authority.
 
+The derived brief records the entry question, selected lenses, deliberate omissions,
+dependencies, source plan, material checkpoints, observable stop condition, and return
+route. Read it on a fresh session instead of restarting completed evidence collection.
+
 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.
+lenses. Show the proposed coverage once. Pause only when it expands an accepted boundary
+or creates another material checkpoint; a covering Change Research Disposition does not
+need a duplicate confirmation. Load one reference at a time; the parent holds the
+question map, not every step prompt.
 
 The first six lenses have real semantic dependencies:
 
@@ -50,6 +83,8 @@ The first six lenses have real semantic dependencies:
 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.
@@ -61,6 +96,8 @@ 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
@@ -74,23 +111,38 @@ 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.
+planning when that contract must change. The scoped run's return route is always the
+same stable Change, even when the evidence supports the original intent unchanged.
 
 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
+`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. 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.
+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.
+For `baseline`, recommend `ultra-change/intake`; for `change-scoped`, return the named
+evidence to `ultra-change/reconcile`. Invoke neither unless the latter continuation is
+covered by the same valid Execution Grant; when it is covered, show the transition Route
+Card first and let Change re-verify its own mode and grant.
 
 ## When the owner decides
 
@@ -108,4 +160,8 @@ selects methods, and updates accepted files inside that frame.
 - `references/30-architecture-context.md` through `references/41-quality-risks.md` —
   system boundary, implementation evidence, operations, and risk.
 - `references/99-synthesis.md` — load last, after selected reports exist.
+- `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-status/references/route-contract.md` — owner-visible route, checkpoint, and recovery output.
 - `../ultra-think/references/autonomy-boundary.md` — read before reducing authority.

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,8 +12,9 @@ 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.
-- Propose one North Star outcome or metric when justified by delivered value and a
-  credible observation contract.
+- 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.
 
@@ -21,7 +22,7 @@ including signals that would reveal harmful optimization.
 
 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.
+`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,11 +17,22 @@ 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
 
-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.
+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
@@ -40,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

@@ -27,6 +27,14 @@ Write `.ultra/research/<run-id>/brief.md` with:
 - 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.