ultra-builder-pro-cli 0.26.0 → 0.26.2

package/skills/ultra-delegate/SKILL.md

@@ -10,7 +10,16 @@ semantic synthesis and remains the only writer of `.ultra/tasks.json`.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json`, the delegated task's `context_file` and `## Resume Note`.
+1. Resolve exactly one active `change_id`, then select one scope and name it in
+   `instruction.md`:
+   - **task execution or continuation** — select one matching task and read its full
+     `context_file` and `## Resume Note`;
+   - **scoped Research evidence** — read the active intent's Research Disposition,
+     named question, sources, and required exit evidence;
+   - **aggregate Change review or verification** — read the exact matching task ids,
+     relevant contexts, current report or review summary, and Change diff.
+   Research and aggregate read-only scopes do not require a task. An archived or
+   abandoned task cannot be delegated as current work.
 2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, acceptance and current evidence.
 3. Define one bounded instruction, permission set, clean Git worktree and result.
 4. Read `references/delegation-contract.md` before writing either JSON artifact.
@@ -21,19 +30,28 @@ semantic synthesis and remains the only writer of `.ultra/tasks.json`.
   spec digests remain unchanged.
 - The worker terminates as `finished`, `blocked` or `failed` in a schema-valid
   `result.json`; declared paths equal the actual Git diff and stay in writable roots.
+- No `writable_roots` entry is `.ultra/` or sits under it, and the actual diff touches
+  nothing there.
 - Timeout and cancellation reach a terminal failed result and release `run.lock`.
-- The primary host verifies the result against the delegated workflow's acceptance.
+- The primary host verifies the result against the selected scope's task acceptance,
+  Research exit evidence, or aggregate review/verification question.
 
 ## Prepare and run
 
 Write under `.ultra/.runtime/delegations/<id>/`:
 
-- `instruction.md`: bounded goal, sources, acceptance and forbidden effects;
+- `instruction.md`: scope type, stable `change_id`, optional task id, bounded goal,
+  sources, acceptance or exit evidence, and forbidden effects;
 - `permission.json`: the exact file-local boundary in the contract reference;
 - `result.json`: launcher-published terminal artifact only.
 
 `writable_roots` is an array of existing worktree-relative directories. An empty array
 selects native read-only mode; one or more roots selects bounded write mode.
+**Neither `.ultra/` nor any path under it may appear in it.** The worktree carries a
+checkout of `.ultra` because Git tracks it, but the project's memory has exactly one
+writer. Two workers appending to `tasks.json`, `progress/` or `evidence/` in separate
+worktrees collide in the very files every later session reads to resume. Worker findings
+and state changes travel back in `result.json` and are applied by the primary host.
 `external_effects` must be empty in this portable launcher: commit, push, publish,
 deployment and other effects stay with the primary host. There is no `readable_roots`
 claim because the five host sandboxes do not share one mechanically enforceable read

package/skills/ultra-delegate/references/delegation-contract.md

@@ -12,8 +12,16 @@
 
 Fields are exact. Roots are normalized worktree-relative directories that already
 exist. An empty array selects native read-only mode; `.` deliberately grants the whole
-isolated checkout. Absolute paths, symlink escapes, unknown fields, `readable_roots`,
-and non-empty external effects are rejected.
+isolated checkout except `.ultra/`. Absolute paths, symlink escapes, unknown fields,
+`readable_roots`, `.ultra` or any path beneath it, and non-empty external effects are
+rejected.
+
+`.ultra/` is never writable by a worker under any root, `.` included. The project's
+memory has exactly one writer — the primary host — because two worktrees appending to
+`tasks.json`, `progress/` or `evidence/` collide in precisely the files a later session
+reads to resume. Enforced twice: the launcher rejects a `.ultra` root before the
+delegation starts, and the worker fails an actual diff that touches it with
+`unauthorized_write`.
 
 ## Model final response
 

package/skills/ultra-deliver/SKILL.md

@@ -1,51 +1,93 @@
 ---
 name: ultra-deliver
-description: Reconcile one completed Change, run aggregate review and refactoring, refresh release documentation, and archive the local workflow record. Use when the task ledger is complete and the owner wants a delivery handoff or separately authorized release effects.
+description: Reconcile one Change whose matching tasks are complete, run aggregate review and refactoring, refresh release documentation, and archive the local workflow record. Use when the owner wants a delivery handoff or separately authorized release effects for the active Change.
 ---
 
 # Turn current evidence into a recoverable delivery handoff
 
-Delivery closes the local Change. Commit, push, tag, publication and deployment remain
-separate effects; local readiness grants none of them automatically.
+Delivery closes the local Change; readiness grants no commit, push, tag, publish, or deploy authority.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json` and each completed task's `context_file`, Completion and
-   closing `## Resume Note`.
+1. Resolve exactly one active `change_id`. Read `.ultra/tasks.json`; every matching task
+   must be complete. Read each `context_file`'s Completion and closing Resume Note.
 2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, active Change intent and evidence.
-3. Read `.ultra/test-report.json` and current `HEAD`. If `git_commit` differs from HEAD,
-   label the report stale and obtain current evidence before a release recommendation.
+3. Read `.ultra/test-report.json`, then run the Test Skill's `worktree_digest.cjs` with
+   project root and `--change-id`. Require report `task_ids` for the current Change plus
+   matching `change_id`, `git_commit`, worktree digest, and intent digest; otherwise stop.
 
 ## Definition of done
 
-- Actual outcome, specifications, docs, tests and aggregate review have been reconciled.
+- Outcome, specs, tests, aggregate review, and every document match the actual diff.
+- Every changed export has a non-test consumer or a recorded owner disposition.
 - Every omitted stage is explicitly recorded with its evidence-based rationale.
 - Build and release checks have exact commands and real results.
 - The Change is archived with `git mv`, and rollback remains a normal Git operation.
 
 ## Review and refactor
 
-Follow `../ultra-review/SKILL.md` across the aggregate Change. This is where useful
-refactoring occurs: several completed slices now reveal real duplication, coupling and
-deep-module boundaries. Rerun every check affected by a refactor and refresh the report
-against the resulting HEAD.
+Follow `../ultra-review/SKILL.md` across the aggregate Change; refactor only observed
+duplication, coupling, or boundary defects. Rerun affected checks and refresh the report.
 
 ## Reconcile the handoff
 
 1. Compare accepted intent and task traces with delivered behavior.
 2. Apply justified specification corrections; route any REDUCTION to the owner.
-3. Update CHANGELOG and README when public behavior changed. Record bounded debt only
-   in the active Change `delivery.md` under `## Technical Debt`.
-4. Run the repository's build and packaging checks.
-5. Determine the version impact from the public contract and project convention.
-6. Follow `references/baseline-reconciliation.md` and write the one canonical active
-   Change `delivery.md` with exact checks, residual risks, omissions and rollback.
+3. List documentation, compare every file with the full Change diff, and repair stale
+   behavior, examples, flags, or fields. Record bounded debt only in active
+   `delivery.md` under `## Technical Debt`.
+4. Defer build, non-publishing package inspection, version selection, and the canonical
+   `delivery.md` until the fresh-snapshot finalization pass below. Reconciliation that
+   changed files must return through Test first.
+
+Entry reconciliation prevents inherited drift; this exit reconciliation prevents the
+Change from leaving new document drift.
+
+## Reconcile, then finalize on a fresh snapshot
+
+Delivery has two observable passes, not a hidden state machine:
+
+1. Reconcile and review. If this pass changes source, tests, task/context/evidence,
+   specifications, maintained documentation, or `intent.md`, stop after writing the
+   reconciled files. The existing report is stale; recommend `ultra-test` and make no
+   delivery or release claim.
+2. After an unchanged pass or fresh Test, recheck Change/task/HEAD/product/intent
+   identities. Apply the gate, run build and non-publishing package inspection, determine
+   version impact, and use `references/baseline-reconciliation.md` for canonical
+   `delivery.md`. Archive the Change. Excluded delivery metadata and the directory move
+   cannot self-invalidate the product digest; intent stays independently bound.
+
+Do not draft a success narrative around stale evidence. A current `passed: false`
+report may still reach finalization only after every finding has an explicit owner
+disposition and the one hard gate below is clear; `passed` is evidence summary, not a
+second mechanical release gate.
+
+## The one delivery gate
+
+This gate applies only after the owner explicitly invokes `ultra-deliver`; it does not
+attach itself to ordinary repository packaging outside this workflow.
+
+Everything else in this workflow reports and hands over. This is the exception, and it
+is deliberately narrow:
+
+**Do not produce a release package while an export this Change added or changed has no
+non-test consumer and no recorded owner disposition.**
+
+| | |
+|---|---|
+| Invariant | Every changed export is either reachable from a non-test caller or explicitly declared internal |
+| Fact source | The Wiring Verification finding and its owner disposition in `.ultra/test-report.json`, bound to the current Change id, task ids, intent, HEAD, and product-worktree digest — the audit already found these; this is not a fresh opinion |
+| Blocked effect | Release-package creation and the separately authorized release effects after it. A non-publishing package inspection is diagnostic; local commit and archival are untouched |
+| Repair | Wire the export to its caller, or record the owner's disposition on the finding in `.ultra/test-report.json`, then carry it into `delivery.md`. Either one clears the gate |
+
+"Written but never connected" can leave tests and review green while the feature is
+absent. Keep this gate at finalization, after the audit can distinguish unfinished work.
 
 ## Archive locally
 
-Move `.ultra/changes/active/<id>` to `.ultra/changes/archive/<id>` with `git mv` only
-after local reconciliation. Do not create a second standalone delivery report: archived
-`delivery.md`, test report, evidence and Git history are the handoff.
+After the fresh check, `git mv` active `<id>` to archive. The id stays stable in task
+rows; never store a movable intent path or create a second delivery summary. Archived
+delivery, test report, evidence, and Git history are the handoff.
 
 For separately authorized effects, perform and verify each independently. Ask for
 authority at the point of effect: commit, then push, then tag, package publication and

package/skills/ultra-deliver/references/baseline-reconciliation.md

@@ -34,6 +34,8 @@ the Change is active and moves with the directory when archived.
 
 Every semantic update cites a repository-relative `path#anchor`. A reduction requires
 the owner decision before the affected specification changes. Exact command evidence
-must match the checkout identified by `.ultra/test-report.json`; stale results stay
-visible and never become a pass. Do not create a second JSON or Markdown delivery
-summary.
+must match the stable Change id, exact current task ids, intent digest, HEAD, and
+product-worktree digest identified by `.ultra/test-report.json`; stale results stay
+visible and never become a pass. Reconcile before finalizing. If reconciliation changes
+semantic or product files, obtain a fresh Test snapshot before writing final delivery
+metadata or archiving. Do not create a second JSON or Markdown delivery summary.

package/skills/ultra-dev/SKILL.md

@@ -5,13 +5,13 @@ description: Carry one planned task from a written implementation plan through r
 
 # Take one task from plan to recorded evidence
 
-The model owns the code reasoning and the edits. The repository owns the task
-contract, the evidence, and everything needed to resume.
+The model owns code reasoning and edits; repository files own the resumable contract.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json` and pick the task; read its `context_file` end to
-   end, above all the closing `## Resume Note` — that line says where to pick up.
+1. Resolve exactly one active `change_id`; more than one is a repository conflict. Read
+   `.ultra/tasks.json`, choose one matching `in_progress` or dependency-ready task, then read
+   its full `context_file`, especially `## Resume Note`.
 2. Read `CONTEXT.md` for vocabulary, and the `.ultra/decisions/` entries the task
    context names.
 3. Read `.ultra/north-star.md` and the task's acceptance criteria. If you cannot
@@ -22,10 +22,9 @@ read `references/debugging.md` and establish the earliest incorrect state before
 
 ## Definition of done
 
-- All six evidence dimensions are answered for this task, each against the
-  checkable rule below rather than an impression.
-- `tasks.json` and the context file's header state the same status, each written
-  and then read back — a one-sided write breaks resume on another host.
+- All six evidence dimensions answer the checkable rules below.
+- `tasks.json` and context status agree after write/read-back.
+- The task still names the active `change_id`; historical unfinished work stays out.
 - The context file carries a Completion entry and a rewritten Resume Note.
 - A task-level review has run and its blocking findings are resolved.
 
@@ -42,16 +41,38 @@ Follow `../ultra-tdd/SKILL.md`, writing tests only on the seams the plan already
 confirmed, one slice at a time. Do no refactoring here — `ultra-review` owns it,
 because what is worth restructuring only becomes visible after several slices.
 
+## Converge on the task-scoped acceptance set
+
+Development ends when the task's acceptance commands pass, not when the code looks
+finished. Resolve the context's **Change Acceptance IDs** against the active `intent.md`
+for `<change_id>`
+and use each named row's executable `Verification`. Commands under the context's
+Acceptance Criteria may add task-local checks; they do not replace the Change mapping.
+
+Run one baseline before repairing anything. Track the best-ever passing set of mapped
+IDs and task-local commands, the total repair rounds, and consecutive rounds that add
+nothing to that set. The loop has three explicit exits:
+
+| Exit | Condition | Action |
+|---|---|---|
+| Converged | Every mapped Change verification and task-local command exits zero | Close out below |
+| Stalled | Two consecutive repair rounds add no new item to the best-ever passing set, or three repair rounds finish without convergence | Stop; report the remaining criteria and what each repair tried |
+| Unreachable | A command did not start because its executable, fixture, service or declared environment prerequisite is unavailable | Stop that criterion; report the missing prerequisite and its repair path |
+
+A nonzero exit normally means a failing criterion, not an unreachable one; inspect its
+output. A regression never shrinks the best-ever set, and the total round limit stops
+oscillation where different criteria alternate between pass and fail.
+
 ## Answer the six evidence dimensions
 
 Each has a rule you can check against the work rather than assert:
 
 | Dimension | Answered when |
 |---|---|
-| `tests_written` | This diff changes a test file |
+| `tests_written` | This diff adds or changes at least one assertion — touching a test file is not enough |
 | `tests_passed` | The last test run exited zero and covered the files this diff touched |
 | `persistence_real` | On any path that stores data, the test uses real storage or a container |
-| `feature_flags_audit` | No flag this task added defaults to off |
+| `feature_flags_audit` | No flag on this change's execution path defaults to off, including flags this task did not add but now depends on |
 | `vertical_slice` | One test's execution path runs from the entry point through to persistence |
 | `spec_trace` | The anchor the task's `trace_to` names exists in the specification |
 
@@ -92,9 +113,7 @@ as it stands and says so in the Resume Note instead of tidying it away.
 
 ## References
 
-- `../ultra-tdd/SKILL.md` — read before the first test, for the seam and the mock
-  boundary.
-- `../ultra-think/references/autonomy-boundary.md` — read the moment the
-  specification and the implementation disagree.
+- `../ultra-tdd/SKILL.md` — read before the first test, for the seam and mock boundary.
+- `../ultra-think/references/autonomy-boundary.md` — read when spec and code disagree.
 - `../ultra-review/SKILL.md` — read when implementation evidence is ready for review.
 - `references/debugging.md` — read for a reproduced failure before selecting a repair.

package/skills/ultra-grilling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ultra-grilling
-description: Interrogate an owner request until every branch of its decision tree is resolved, one question per turn, each carrying a recommended answer. Use when another skill needs the owner's intent specific enough to build from — a new project's north star, a Change boundary, or an ask whose acceptance criteria are still implicit.
+description: Turn caller-named missing owner decisions into confirmed answers, one question per turn and each carrying a recommendation. Use when Init needs a raw brief field, Research needs an owner decision, or Change and Plan need an explicit boundary or acceptance criterion.
 ---
 
 # Turn a vague ask into a decision list the owner has explicitly confirmed
@@ -12,8 +12,8 @@ finished work proves otherwise. It serves Goal 1, Intent Fidelity.
 ## Before you start
 
 1. Reread what the owner said in the current request, verbatim.
-2. Read `.ultra/north-star.md` and `CONTEXT.md` where they exist. Established
-   wording and vocabulary are decisions that were already made.
+2. Read `.ultra/project-brief.md`, `.ultra/north-star.md`, and `CONTEXT.md` where they
+   exist. Raw intake is reusable input; accepted wording must not be re-asked.
 3. Look up every fact you can reach on your own: repository files, Git history,
    installed dependencies, tool output.
 
@@ -22,18 +22,37 @@ have answered by reading the repository spends the one input only they can give.
 
 ## Definition of done
 
-- Every branch reachable from the original ask is resolved, or deferred with the
-  reason recorded.
-- Each resolved branch carries the owner's confirmation in their own words,
-  rather than something that sounded like agreement.
-- The calling skill holds a decision list it can write to a file: one line per
-  decision, each with the options rejected and why.
+- Every field the caller named as required is either answered in the owner's own
+  words or explicitly deferred with the reason recorded. "Every branch of the
+  tree" is not something you can check against a file; the caller's field list is.
+- The reframe below was put to the owner and either confirmed or corrected. It is
+  never skipped because the original wording sounded clear.
+- Each answer carries the owner's confirmation, rather than something that
+  sounded like agreement.
+- The caller owns the final artifact and receives a decision list it can write: one
+  line per decision, each with the options rejected and why.
 
-## Extract first, then ask
+## Extract, reframe, then ask
 
-Restate what the owner already told you and ask them to confirm the restatement.
-Ask only about what is genuinely missing. Re-asking something they answered
-teaches them that answering does not stick.
+**Extract.** Restate what the owner already told you and ask them to confirm the
+restatement. Ask only about what is genuinely missing. Re-asking something they
+answered teaches them that answering does not stick.
+
+**Reframe.** The owner describes a *form* when they want a *role*. Say what you
+believe they actually want, name the gap against their wording, and end on a
+question:
+
+> You said a daily briefing app. What you described is a personal chief of staff
+> — the briefing is one of its outputs, not the thing itself. Have I got that
+> right?
+
+This is what separates the loop from a questionnaire. A form accepted at face
+value yields a specification that is internally consistent and builds the wrong
+product. Offer the reframe, never assert it, and treat a correction as the better
+outcome — "no, it really is just the briefing" is a constraint you did not have a
+minute ago. Read `references/reframing.md` for when it applies and how it fails.
+
+**Then ask** only what the confirmed reframe leaves open; the caller sets the semantic depth, so Init stops at the raw outline and leaves baseline questions to Research.
 
 ## One question per turn
 
@@ -44,14 +63,27 @@ the load-bearing one skipped.
 Every question carries your recommended answer and what would change it. A
 question without a recommendation hands your own work back to the owner.
 
-Order questions so that answering one unlocks the next, and prefer the ones whose
-answer changes what gets built:
+Order questions so that answering one unlocks the next. Ask the framing questions
+before the detail questions — a detail settled inside the wrong frame has to be
+asked again.
+
+**Framing questions** come first — at most five, from the table in
+`references/reframing.md`. They refuse the owner's framing on purpose, which is
+how they surface what the request left out. Stop early once the frame stops
+moving.
+
+**Detail questions** fill in the confirmed frame:
 
 - What happens when this goes wrong, and how would we find out?
 - Which of these options is cheaper to reverse?
 - What are we deliberately not doing?
 - What does done look like, concretely enough to check?
 
+An answer counts once it is specific enough to **rule something out**. "It should
+be fast" rules nothing out; "the list renders before they finish typing" does.
+When an answer rules nothing out, ask what would have to be true for the owner to
+*reject* a candidate solution.
+
 Skip what you can derive, what does not change the work, and what they already
 settled.
 
@@ -61,19 +93,26 @@ This whole skill is owner-facing, so the boundary is narrow: hold the loop open
 until each decision is confirmed explicitly, and start no implementation on an
 inferred consensus.
 
-Where the host cannot present a structured question, ask one plain question per
-turn instead. Where it cannot ask at all, stop at the last confirmed decision,
-record what remains open, and hand that back to the caller — neither guessing an
-answer nor blocking the owner's next move.
+## How the loop ends
+
+Every ending hands back the same result: decisions written one per line, each with
+the options rejected and the reason they lost. The caller alone chooses the canonical
+destination; Grilling never promotes an answer into project authority by itself.
 
-## Hand back a list
+- **Resolved** — every required field answered or explicitly deferred.
+- **Stalled** — two consecutive turns add no newly confirmed decision. Hand back
+  the open fields and what each one blocks.
+- **Unavailable** — the host cannot ask, or the owner stopped answering. Hand back
+  the last confirmed state, every unanswered field named.
 
-Once the tree is walked, write the decisions out one per line, each with the
-rejected options and the reason they lost. That list is the record. The caller
-chooses where it lands: `north-star.md`, `discovery.md`, a Change intent, or a
-decision file.
+A loop with no exit traps the owner as much as you: re-asking what they cannot
+currently answer costs more than deferring it. Deferral is a recorded outcome,
+not a failure. Where the host has no structured question surface, ask one plain
+question per turn instead.
 
 ## References
 
+- `references/reframing.md` — read before the first question: when to reframe,
+  how it fails, the five framing questions, and what counts as an answer.
 - `../ultra-think/references/autonomy-boundary.md` — read when an answer removes
   something the specification already promised, or otherwise crosses C5.

package/skills/ultra-grilling/references/reframing.md

@@ -0,0 +1,72 @@
+# Reframing: recovering the role from the form
+
+An owner fluent in their own domain still describes a **form** when what they
+want is a **role**. They are not being vague; they are naming the nearest thing
+they can picture. Taken at face value, that name produces a specification that is
+internally consistent and builds the wrong product.
+
+## When to reframe
+
+Most first asks qualify. Any one of these is enough:
+
+- the request names an artifact — an app, a dashboard, a bot, a script — rather
+  than an outcome;
+- the request names a solution whose problem has not been stated;
+- the request would be satisfied by something far smaller, or is impossible as
+  worded;
+- two readings of the request would lead to materially different builds;
+- the request describes what a competitor has, rather than what the owner needs.
+
+## How to put it
+
+State what you believe they want, name the gap against the words they used, and
+end on a question:
+
+> You said a daily briefing app. What you described is a personal chief of staff
+> — the briefing is one of its outputs, not the thing itself. Have I got that
+> right?
+
+Rules that keep this honest:
+
+- **One reframe at a time.** Two competing reinterpretations in one turn is a
+  quiz, and the owner will pick the one that sounds more flattering.
+- **Offer it, never assert it.** A reframe is a hypothesis about their intent,
+  and they are the only authority on it.
+- **A correction is the better outcome.** "No, it really is just the briefing" is
+  a constraint you did not have a minute ago. Record it as a decision.
+- **Never reframe toward what is easier to build.** If your reinterpretation
+  happens to shrink the work, say that out loud and let the owner weigh it.
+- **Stop after two rejected reframes.** A third is no longer listening. Take the
+  owner's framing as given and move to the framing questions below.
+
+## Framing questions
+
+These refuse the owner's framing on purpose, which is how they surface what the
+request left out. Ask at most five, and stop early once the frame stops moving.
+
+| Question | What it recovers |
+|---|---|
+| What do you do today, without this? | The real job, with the proposed form stripped off |
+| What would make you say this was a waste of effort? | Success via its negative — people picture failure far more concretely than they picture success |
+| What must never happen, even if it would work better? | The hard constraints they were never going to volunteer |
+| If it could only do one thing and you would still use it, which? | Core against periphery, before scope has a chance to spread |
+| Whose situation gets worse when this exists? | Stakeholders, and the constraints attached to them |
+
+Two of these are worth their place for a specific reason. Asking for success
+directly gets an aspiration; asking what would make it a waste gets a threshold.
+Asking who is made worse off surfaces the constraints an owner never thinks to
+state, because to them they are simply how the world is.
+
+## What counts as an answer
+
+An answer counts once it is specific enough to **rule something out**.
+
+| Not yet an answer | An answer |
+|---|---|
+| "It should be fast" | "The list renders before they finish typing" |
+| "It should be secure" | "A support agent must never see a full card number" |
+| "Keep costs reasonable" | "Under fifty dollars a month in API spend" |
+
+When an answer rules nothing out, do not re-ask the same question louder. Ask
+what would have to be true for the owner to **reject** a candidate solution — the
+rejection criterion is the constraint, stated from the other side.