ultra-builder-pro-cli 0.26.1 → 0.26.2

package/skills/ultra-status/SKILL.md

@@ -1,65 +1,95 @@
 ---
 name: ultra-status
-description: Infer the current Ultra workflow position, stale evidence, task risk, and installation health from repository files and host manifests. Use when the owner asks what is complete, blocked, stale, unhealthy, or useful to do next.
+description: Infer the current Ultra route, baseline gaps, stale evidence, task risk, and installation health from repository files and host manifests. Use when the owner asks what is complete, blocked, stale, unhealthy, or useful to do next.
 ---
 
 # Route from artifacts without changing them
 
-This router is read-only. It reports verified files, model inference and unavailable
-evidence separately, then recommends one explicit capability without invoking it.
+This router is read-only. It separates verified files, model inference, and unavailable
+evidence, then recommends one explicit public capability without invoking it. It never
+persists a workflow-position field.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json` if present; read the active task's `context_file` and
-   closing `## Resume Note`.
-2. Read `CONTEXT.md` and relevant `.ultra/decisions/` entries when they exist.
-3. Inspect Git `HEAD`, worktree status, active/archive Change directories and installed
-   host manifests without repairing them.
+1. List directories containing `.ultra/changes/active/*/intent.md`. If exactly one
+   exists, its directory name is the current `change_id`. Read `.ultra/tasks.json`,
+   then tasks whose `change_id` matches it and the frontier task's `context_file` and
+   `## Resume Note`. Historical and abandoned tasks never define the frontier.
+2. Read `.ultra/project-brief.md`, `.ultra/north-star.md`, `CONTEXT.md`, relevant
+   `.ultra/decisions/`, specifications, active, archived, or abandoned Changes, and
+   evidence. An abandoned Change supplies historical boundary and recovery context;
+   it never defines the current route.
+3. Inspect Git `HEAD`, worktree status, and installed host manifests without repair.
 
 ## Definition of done
 
-- The artifact route below is evaluated in order and the matching evidence is named.
-- Stale test evidence, dirty worktree state and task graph risks are visible.
-- Installation health reports exact missing or drifted files without mutation.
-- The recommendation says why it follows; it does not launch the capability.
+- Evaluate the artifact route in order and name the evidence supporting the match.
+- Keep stale test evidence, dirty worktree state, baseline gaps, and task graph risks
+  visible without converting them into semantic failure.
+- Report exact installation drift and a reachable repair without mutating it.
+- Recommend one route and why; never launch it.
 
 ## Infer the route
 
-| Observable files | Recommendation |
+| Observable files and current need | Recommendation |
 |---|---|
 | No `.ultra/` | `ultra-init` |
-| Product specification missing or contains `[NEEDS CLARIFICATION]` | `ultra-research` |
+| Project Brief has no usable one-line and no legacy `## One-line` exists | `ultra-init` |
+| Project Brief or legacy seed exists but no accepted North Star supports the current boundary | `ultra-research` |
 | A new request exists and no active Change exists | `ultra-change` |
-| An active Change exists and `.ultra/tasks.json` is missing or `tasks` is empty | `ultra-plan` |
-| A frontier task is pending or in progress | `ultra-dev`, naming the task |
-| All tasks completed and no current report | `ultra-test` |
-| `test-report.passed` is false | `ultra-dev`, with blocking findings |
-| Report passed and `git_commit` equals `HEAD` | `ultra-deliver` |
+| More than one active Change exists | Diagnose the conflicting directories and ask the owner which one remains active; do not route or move either automatically |
+| The active intent is `draft` or has a blocking unresolved decision | `ultra-change` to finish and accept the contract |
+| The active `Research Disposition` names required exit evidence that is not satisfied | `ultra-research` for the named question and selected lenses |
+| Research evidence exists but the accepted intent has not reconciled it | `ultra-change` to update the bounded contract |
+| An active Change exists and `.ultra/tasks.json` has no tasks whose `change_id` matches it | `ultra-plan` |
+| A matching task is pending or in progress with same-Change dependencies satisfied | `ultra-dev`, naming that task |
+| All matching tasks are completed and no current report matches this Change | `ultra-test` |
+| A current false report has implementation, test, or wiring findings selected for repair | `ultra-dev` after owner disposition |
+| A current false report has missing external or product evidence selected for collection | `ultra-research` after owner disposition |
+| A current false report has an acceptance, scope, or existing-promise change selected for reconciliation | `ultra-change` after owner disposition; use `ultra-think` internally for one consequential trade-off |
+| Every current finding is explicitly accepted, deferred, or otherwise dispositioned | `ultra-deliver`, subject to its one orphan-export gate |
+| Report passed and all report identities match current files | `ultra-deliver` |
 | No active Change and no new request | Report the idle state; do not manufacture work |
 
-A report whose `git_commit` differs from `HEAD`, or whose recorded `worktree.diff_digest`
-differs from the result of resolving the installed `ultra-test` Skill and running
-`node <ultra-test-skill-dir>/scripts/worktree_digest.cjs --project <repository-root>`, is stale. A dirty
-worktree is a warning, not evidence of failure.
+An explicit `[NEEDS CLARIFICATION]` is evidence of an unresolved field, not proof that
+the entire project requires Research. Judge whether it can change the current boundary.
+Do not add `research_complete`, a score, or another state bit to replace that judgment.
+
+A test-report is stale when its `change_id` is not the active Change, its `task_ids` are not
+the exact ordered ids of tasks whose `change_id` matches that Change, `git_commit`
+differs from `HEAD`, or its `worktree.diff_digest` or `intent_digest` differs from
+running
+`node <ultra-test-skill-dir>/scripts/worktree_digest.cjs --project <repository-root> --change-id <change_id>`.
+A dirty worktree is a warning, not evidence of failure.
+
+`passed: false` does not itself select a repair. Preserve each finding, ask for owner
+disposition where scope or risk changes, then route by the accepted response above.
+Likewise, task completion is necessary for `passed: true` but never sufficient to
+manufacture it.
+
+The repository has one primary writer for canonical `.ultra` files. Native review
+workers and delegated CLIs may inspect or write isolated source roots, but their results
+return to that writer. Concurrent canonical writes require separate worktrees and
+explicit integration; this router does not invent locks or silently merge ledgers.
 
 ## Surface risk and installation health
 
-List unmet task dependencies, any `in_progress` task older than 3 days, complexity
-concentration and broken `trace_to` or `context_file` paths. These are sensors.
+List unmet task dependencies, more than one matching `in_progress` task under the
+single-writer contract, any `in_progress` task older than 3 days, complexity
+concentration, and broken `trace_to` or `context_file` paths. These are sensors.
 
-For installation health, compare the selected host's plugin path, skill inventory,
-version, provenance and hook manifest against the installed files. Report broken links
-and missing registrations. Recommend `ubp install` or `ubp update` as the reachable
-repair; this read-only skill never performs it.
+Compare the selected host's plugin path, skill inventory, version, provenance, and hook
+manifest with installed files. Recommend `ubp install` or `ubp update` as the repair;
+this read-only Skill never performs it.
 
 ## When the owner decides
 
-The owner chooses the next workflow, risk disposition and any reinstall. Contradictory
-file facts are reported as contradictions rather than silently selecting one.
+The owner chooses the next public workflow, risk disposition, and any reinstall.
+Contradictory facts remain visible instead of being resolved by routing heuristics.
 
 ## References
 
-- `../ultra-think/SKILL.md` — read only when contradictory evidence creates a real
+- `../ultra-think/SKILL.md` — read only when contradictory evidence creates one real
   decision rather than a mechanical repair.
 - `../ultra-think/references/autonomy-boundary.md` — read before recommending a route
   that would reduce an accepted commitment.

package/skills/ultra-tdd/SKILL.md

@@ -10,8 +10,11 @@ the loop that supplies it, and it serves Goal 3, Production-Ready.
 
 ## Before you start
 
-1. Read the current task context for the seams already confirmed during
-   planning. Tests live on those, and choosing a new one is a planning decision.
+1. When called from a planned Change, resolve the unique active `change_id` and read the
+   matching current task context for the seams already confirmed during planning. For a
+   micro edit outside the Ultra lifecycle, no active task context is required; use the
+   accepted request, maintained specification, and an existing repository seam, and
+   create no Ultra task or delivery claim.
 2. Run the repository's existing test command once, unchanged, to see what
    passing currently looks like. Read `references/test-execution.md` before recording
    that run or any red/green evidence.

package/skills/ultra-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ultra-test
-description: Audit whole-system integrity after the task ledger is complete by finding anti-patterns, coverage gaps, broken wiring, E2E failures, performance risk, and security risk. Use when preparing delivery or when locally green tasks may not form a working product.
+description: Audit whole-system integrity after tasks for the active Change are complete by finding anti-patterns, coverage gaps, broken wiring, E2E failures, performance risk, and security risk. Use when preparing delivery or when locally green tasks may not form a working product.
 ---
 
 # NOT for running unit tests (that's `ultra-dev`). This audits whole-system integrity before delivery.
@@ -11,23 +11,29 @@ the owner decides what to fix or accept.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json` and every completed task's `context_file`, especially its
-   Acceptance, Completion and closing `## Resume Note`.
+1. Resolve exactly one `.ultra/changes/active/<change_id>/intent.md`. Read
+   `.ultra/tasks.json` and only tasks whose `change_id` matches the active Change. Every
+   matching task must be complete; read each task's `context_file` Acceptance, Completion and
+   closing `## Resume Note`. Historical tasks are not part of this audit snapshot.
 2. Read `CONTEXT.md` for vocabulary and the relevant `.ultra/decisions/` entries.
 3. Read the active Change intent, the task evidence directories and the current Git
    `HEAD`; old output is evidence only for the commit it names.
 4. Resolve this loaded Skill's directory and run
-   `node <ultra-test-skill-dir>/scripts/worktree_digest.cjs --project <repository-root>`
-   before and after the audit. Its digest excludes
-   only `.ultra/test-report.json`, avoiding a self-referential report.
+   `node <ultra-test-skill-dir>/scripts/worktree_digest.cjs --project <repository-root> --change-id <change_id>`
+   before and after the audit. It returns the stable Change id, exact intent SHA-256,
+   HEAD, and product-worktree digest. The product digest excludes the report and all
+   active/archive/abandoned Change-directory metadata; intent freshness is checked
+   separately, so writing delivery metadata or moving the same Change cannot invalidate
+   its tested product snapshot.
 
 ## Definition of done
 
 - All six audit areas have an evidence-backed result or an explicit material omission.
 - Wiring lists each changed export and its non-test consumers; zero matches are visible
   as orphan findings.
-- `.ultra/test-report.json` records `git_commit`, commands, findings, omissions and the
-  owner's disposition without rewriting a finding into a pass.
+- `.ultra/test-report.json` records `change_id`, the exact current-Change `task_ids`,
+  `intent_digest`, `git_commit`, commands, findings, omissions and the owner's
+  disposition without rewriting a finding into a pass.
 
 ## Audit six areas
 
@@ -61,14 +67,22 @@ the smallest real boundary or implementation that would make it observable.
 
 ## Write the report
 
-Store the exact `git_commit`, timestamp, run count, commands and exit codes, the six
-area results, findings with paths, verified seams, material omissions, residual risk,
-and `passed` as the model's evidence-derived summary in the one canonical
+Store the exact `change_id`, ordered current-Change `task_ids`, `intent_digest`,
+`git_commit`, timestamp, run count, commands and exit codes, the six area results,
+findings with paths, verified seams, material omissions, residual risk, and `passed` as
+the model's evidence-derived summary in the one canonical
 `.ultra/test-report.json`. Each command records `command`, `exit_code`, and an
 `evidence_ref`; each area records `status`, `evidence_refs`, and `omissions`. Copy the
-script's `head`, `dirty`, and `diff_digest` into `git_commit` and `worktree`. A stale commit or digest is labelled stale;
+script's `head`, `dirty`, `diff_digest`, and `intent_digest` into the report. A stale
+commit, product digest, intent digest, Change id, or task-id snapshot is labelled stale;
 it is never reused as current proof.
 
+`passed` is a one-way claim: `true` requires every current-Change task complete and no
+required area left `not_run`. Completed tasks do not force `passed: true`; findings,
+omitted evidence, or a failed command may keep it false, while an explicitly
+dispositioned gap remains visible even if the model's evidence summary passes. Preserve
+the finding and the owner's disposition as separate fields.
+
 Present the findings by consequence and recommend the highest-leverage response. The
 owner may fix all, fix selected findings, accept recorded risk, or reduce scope through
 the normal REDUCTION decision. Recommend the next capability; do not invoke it.

package/skills/ultra-test/scripts/worktree_digest.cjs

@@ -15,22 +15,55 @@ function git(cwd, args, encoding = 'utf8') {
   });
 }
 
-function projectFromArgs(argv) {
-  if (argv.length === 0) return process.cwd();
-  if (argv.length === 2 && argv[0] === '--project' && argv[1]) return path.resolve(argv[1]);
-  throw new Error('usage: worktree_digest.cjs [--project <repository-root>]');
+function optionsFromArgs(argv) {
+  const options = { project: process.cwd(), changeId: null };
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (!value) throw new Error('usage: worktree_digest.cjs [--project <repository-root>] [--change-id <id>]');
+    if (flag === '--project') options.project = path.resolve(value);
+    else if (flag === '--change-id') options.changeId = value;
+    else throw new Error('usage: worktree_digest.cjs [--project <repository-root>] [--change-id <id>]');
+  }
+  if (options.changeId && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(options.changeId)) {
+    throw new Error(`invalid Change id: ${options.changeId}`);
+  }
+  return options;
+}
+
+function intentSnapshot(root, changeId) {
+  if (!changeId) return { change_id: null, intent_digest: null };
+  const matches = ['active', 'archive', 'abandoned']
+    .map((state) => path.join(root, '.ultra', 'changes', state, changeId, 'intent.md'))
+    .filter((file) => fs.existsSync(file));
+  if (matches.length !== 1) {
+    throw new Error(`expected exactly one intent.md for Change ${changeId}; found ${matches.length}`);
+  }
+  const intent = fs.readFileSync(matches[0]);
+  return {
+    change_id: changeId,
+    intent_digest: crypto.createHash('sha256').update(intent).digest('hex'),
+  };
+}
+
+function excluded(file) {
+  return file === '.ultra/test-report.json'
+    || /^\.ultra\/changes\/(?:active|archive|abandoned)(?:\/|$)/.test(file);
 }
 
-function main(cwd) {
-  const root = fs.realpathSync(git(cwd, ['rev-parse', '--show-toplevel']).trim());
+function main(options) {
+  const root = fs.realpathSync(git(options.project, ['rev-parse', '--show-toplevel']).trim());
   const head = git(root, ['rev-parse', 'HEAD']).trim();
   const diff = git(root, [
     'diff', '--binary', '--no-ext-diff', 'HEAD', '--', '.',
     ':(exclude).ultra/test-report.json',
+    ':(exclude).ultra/changes/active/**',
+    ':(exclude).ultra/changes/archive/**',
+    ':(exclude).ultra/changes/abandoned/**',
   ], 'buffer');
   const untracked = git(root, ['ls-files', '--others', '--exclude-standard', '-z'], 'buffer')
     .toString('utf8').split('\0').filter(Boolean)
-    .filter((file) => file !== '.ultra/test-report.json')
+    .filter((file) => !excluded(file))
     .sort();
   const hash = crypto.createHash('sha256');
   hash.update('ultra-worktree-digest-v1\0').update(head).update('\0').update(diff);
@@ -39,6 +72,7 @@ function main(cwd) {
   }
   return {
     $schema: 'ultra-worktree-digest-v1',
+    ...intentSnapshot(root, options.changeId),
     head,
     dirty: diff.length > 0 || untracked.length > 0,
     diff_digest: hash.digest('hex'),
@@ -47,7 +81,7 @@ function main(cwd) {
 }
 
 try {
-  process.stdout.write(`${JSON.stringify(main(projectFromArgs(process.argv.slice(2))), null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify(main(optionsFromArgs(process.argv.slice(2))), null, 2)}\n`);
 } catch (error) {
   process.stderr.write(`${error.message}\n`);
   process.exitCode = 1;

package/skills/ultra-think/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: ultra-think
-description: Stress-test one consequential product, architecture, recovery, or scope decision and preserve the accepted result when it must outlive the session. Use when another skill needs adversarial reasoning, or when fog of war is too large and unclear to decompose safely.
+description: Stress-test one consequential product, architecture, recovery, or scope decision and preserve the accepted result when it must outlive the session. Use when another skill has one evidence-backed trade-off whose answer could materially change accepted work.
 ---
 
 # Turn one consequential uncertainty into an evidence-backed decision
 
-Thinking sharpens a decision; it does not perform the implementation that follows.
+Thinking sharpens one consequential decision; it does not map a research frontier or
+perform the implementation that follows.
 Persist only decisions that are hard to reverse, look surprising without context, and
 arose from a real trade-off. All three criteria must hold.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json` and the current task's `context_file` and `## Resume Note`.
+1. Resolve at most one active `change_id`, read `.ultra/tasks.json`, and if the decision
+   is task-scoped read the matching current task's `context_file` and `## Resume Note`.
 2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, the active Change and its evidence.
 3. State the one decision and the assumptions capable of changing its answer.
 
@@ -34,13 +36,6 @@ arose from a real trade-off. All three criteria must hold.
 Give the owner one recommendation with the decisive evidence and what changes under
 each viable answer. Reuse an answer already explicit in the request.
 
-## Use decision tickets for fog of war
-
-When the work does not fit one session *and* the path itself remains unclear, map one
-question instead of manufacturing implementation tasks. Write a decision ticket with
-`status: open`; resolve one at a time until no unresolved ticket prevents planning.
-Each answer should make the remaining fog of war smaller.
-
 ## Write durable decisions
 
 Use `.ultra/decisions/<id>.md`: question, status, options and real trade-offs, accepted

package/skills/ultra-think/references/interaction-boundary.md

@@ -16,7 +16,8 @@ every write.
 
 ## Interaction sequence
 
-1. Read `.ultra/north-star.md`, `.ultra/tasks.json`, the active task context, relevant
+1. Read `.ultra/north-star.md`, resolve at most one active `change_id`, then read only
+   matching `.ultra/tasks.json` rows and the current task context, plus relevant
    specifications, Changes, decisions, and evidence.
 2. Inspect source, runtime, tests, and primary documentation for observable facts.
 3. Reuse an explicit choice already present in the current request or an accepted