ultra-builder-pro-cli 0.26.1 → 3.0.2

package/skills/ultra-dev/SKILL.md

@@ -5,29 +5,81 @@ 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.
-2. Read `CONTEXT.md` for vocabulary, and the `.ultra/decisions/` entries the task
+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. Read `../ultra-change/references/change-contract.md` and apply its **Active Change
+   authority resolution** before reading any active `intent.md` or resolving a current
+   `change_id`. Require its one valid authority; otherwise stop with its typed repair.
+   Then read `.ultra/tasks.json`. Without an exact task id in the owner invocation,
+   select only the uniquely current `in_progress` task and read its full
+   `context_file`, especially `## Resume Note`; if none exists, stop and ask
+   the owner to invoke Dev naming one exact task id — a `pending` row is a frontier
+   candidate, not active work, and Hooks will not have injected its acceptance or
+   Resume. An invocation that names one exact task id supplies invocation-local
+   selection authority for this Dev run only. If more than one row claims
+   `in_progress`, do not manufacture a unique current task; use the explicit recovery
+   below or stop with the Hook diagnostic. The ledger is the sole task-status authority;
+   legacy Status or Complexity never overrides it. A `completed` task with a current
+   invalidation observation may be selected only for the explicit reopen below; record
+   and read back that transition before repair.
+3. 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
-   state that acceptance in one sentence, you are not ready to start.
+4. Validate `.ultra/north-star.md` with the shipped Research structural sensor. Resolve
+   every listed `FP-*`, `NS-*`, and `HC-*` in the task and active Change against that
+   accepted authority. Compare the active Change's recorded **North Star revision** and
+   **North Star digest** with the accepted file's revision and current Git blob digest.
+   A missing ID, revision mismatch, or digest mismatch is a stale-plan observation: stop
+   before editing and recommend explicit owner invocation of `ultra-change` to reconcile
+   the active Change. Never inherit approval or silently rewrite the trace.
+5. Read the task's acceptance criteria. If you cannot state that acceptance in one
+   sentence, you are not ready to start.
+
+### Activating one named pending task
+
+When the owner invocation names a dependency-ready `pending` task, perform its
+canonical activation before any implementation work: write that row from
+`pending` to `in_progress` in `.ultra/tasks.json` and read the row back before
+the first implementation edit. This one canonical ledger write is what makes
+the named task live for the task-aware Hooks; without it Hooks correctly remain
+task-silent while you edit, because a trusted invocation is visible only to the
+invocation that carried it. The activation adds no selector, activation flag,
+or workflow state — the ledger row is the only authority — and it must respect
+the single-writer boundary: resolve any conflicting `in_progress` rows through
+the recovery below or an owner decision before writing.
+
+### Recover one exact task from an ambiguous ledger
+
+An explicit owner invocation with one exact task id supplies invocation-local selection
+authority for this Dev run even when multiple ledger rows claim `in_progress`. Before
+editing, read that exact canonical ledger row and context, especially its Resume Note,
+then inspect current Git/worktree evidence for the named task. Do not persist a new
+current-task selector, status, or workflow state to manufacture uniqueness. Hooks remain
+task-silent and progress-silent while the ledger is ambiguous.
+
+Only an explicit owner/Plan correction that establishes a conflicting task never started
+may return that row to `pending`. If multiple tasks contain real partial work, keep every
+task with real partial work `in_progress` and preserve each task's bytes. Recover them by
+separate exact task-id owner invocations or obtain owner-authorized Plan reconciliation;
+use a separate worktree when needed to keep their writes isolated. Completing the
+selected task still requires final review, canonical v2 evidence, context publication,
+ledger write, and readback.
 
 When this task starts from an observed error, failing check or unexpected behavior,
 read `references/debugging.md` and establish the earliest incorrect state before editing.
 
 ## 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 carry honest, current observations under the typed v2
+  evidence contract; a real limitation remains a gap rather than becoming a pass.
+- `.ultra/tasks.json` remains the sole task-status authority 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.
+- A task-level review runs while the ledger task remains `in_progress`; its blocking
+  findings are resolved or owner-dispositioned as required and affected evidence is
+  refreshed before the model writes `completed` to the ledger.
 
 ## Write the implementation plan before the code
 
@@ -39,29 +91,54 @@ buries the design decisions in the details.
 ## Develop through red then green
 
 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.
+confirmed, one slice at a time. `ultra-review` owns evidence-backed refactoring when
+observed duplication, coupling, or a boundary defect justifies it; a slice count does
+not make that decision.
 
 ## Converge on the task-scoped acceptance set
 
-Development ends when the task's acceptance commands pass, not when the code looks
+Development ends when every task-scoped criterion has its required current evidence and
+responsible semantic disposition, not merely when commands pass or the code looks
 finished. Resolve the context's **Change Acceptance IDs** against the active `intent.md`
-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:
+for `<change_id>`. For each named row consume its exact `Verification type` and
+`Required evidence`. When one outcome needs more than one authority, split it into
+independent criteria with unique IDs and preserve each authority separately; every row
+has exactly one verification type. Task-local acceptance may add evidence requirements,
+but it does not replace or narrow the Change mapping.
+
+Handle the four verification types without converting one authority into another:
+
+- Execute only `command` observations. Record the exact command, working directory,
+  exit status, retained raw output reference, and its exact SHA-256.
+- For `inspection`, cite the exact source and revision or digest, then refresh the
+  observation after any touched source changes.
+- For `owner-judgment`, preserve the cited owner decision. The owner alone supplies its
+  semantic result; a model statement, validator, score, or command cannot proxy it.
+- For `external-observation`, preserve the provider or system receipt without proxying it
+  with a local command, model claim, or synthetic fixture, and bind its exact bytes by
+  SHA-256.
+
+- Missing `owner-judgment` stops at its named owner gate.
+- Missing `external-observation` stops at its named external or authorization gate.
+- If an inspection exists but its semantic implication is unresolved, stop at the
+  responsible model or owner gate; a structural citation is not an automatic acceptance
+  verdict.
+
+Run one baseline before repairing anything. Track a best-ever evidence set keyed by
+criterion, verification type, and source identity to make progress visible, plus the
+current evidence set used for convergence. Stale or regressed evidence remains history
+but cannot satisfy the current set. Do not infer semantic progress or failure from a
+round count. 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 |
+| Converged | Every mapped and task-local criterion has current required evidence of every named type, and the responsible model or owner has made any semantic disposition | Close out below |
+| Stalled | An in-scope repair yields no new or refreshed evidence and no further evidence-producing repair is justified inside the approved task | Stop; report the missing evidence, the attempted repair, and the responsible next gate |
+| Unreachable | Required evidence cannot be observed because an executable, fixture, provider, service, declared environment prerequisite, or required authorization is unavailable | Stop that criterion; report the unavailable prerequisite or gate and its reachable 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.
+A nonzero command exit is an observation, not automatically `Unreachable`; inspect its
+output and repair within scope when justified. None of these exits mechanically decides
+semantic sufficiency, owner acceptance, or external truth.
 
 ## Answer the six evidence dimensions
 
@@ -76,14 +153,15 @@ Each has a rule you can check against the work rather than assert:
 | `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 |
 
-Record one canonical `.ultra/evidence/<task-id>/evidence.json` with
-`$schema: "ultra-task-evidence-v1"`, `task_id`, `git_head`, `commands`, the six-key
-`dimensions` object, `artifacts`, `limitations`, and `timestamp`. Raw logs and cited
-files stay beside it; no second summary restates the same evidence. Each command has
-`command`, `exit_code`, and `evidence_ref`. Each dimension has `status` (`satisfied`,
-`gap`, or `not_applicable`), `evidence_refs`, and a non-empty `rationale`. Evidence is a
-sensor, not a gate: a gap is reported and handed over, never used to block the work — a
-gate that can be escaped by damaging the work gets escaped by damaging the work.
+Before task review, retain the actual criterion evidence, raw logs, owner records,
+external receipts, and cited artifacts without inventing another completion record.
+Do not write `evidence.json` before the task's validated final `SUMMARY.json` exists.
+The review packet admits those actual pre-review observations together with the ledger,
+context acceptance, and packet-defined task scope. A structural validator may check
+exact fields, types, digests, paths, and freshness observations. It never supplies an
+acceptance disposition, turns a model claim into command evidence, or decides semantic pass.
+Evidence is a sensor: a gap or legacy v1 record is reported with a migration
+diagnostic, never rewritten as v2 truth.
 
 ## When implementation and the specification disagree
 
@@ -95,10 +173,60 @@ classification in the context file's Change Log.
 
 ## Close out
 
-Write the status to both places and read both back. Add the Completion entry and
-rewrite the Resume Note to say where the next session picks up. Then run the
-task-level review through `../ultra-review/SKILL.md`, resolve blocking findings, and refresh
-the evidence they touched.
+Keep the ledger row `in_progress` while running task review through
+`../ultra-review/SKILL.md`. Build its immutable packet from the ledger, task context,
+packet-defined task scope, and actual pre-review evidence; the final v2 record is not an
+admission prerequisite. Route only the exact current P0/P1 findings (or a P2 the owner
+explicitly promoted) as one in-scope repair set, followed by one affected-lens delta
+review per repair set inside the active review budget — an exact current owner grant
+overrides the versioned product default of one initial review plus at most two
+P0/P1 delta reviews per package. When another `REQUEST_CHANGES` would exceed the
+active budget, return to the owner checkpoint with the exact blocking set instead of
+an automatic repair; the same root surviving three failed fixes stops point-patching
+and reports an architecture problem. Budget exhaustion stops execution at `owner checkpoint` /
+`budget_exhausted` and keeps the ledger row `in_progress`.
+It never yields `APPROVE`, `REQUEST_CHANGES`, `INCOMPLETE`, pass, fail, accept, or
+abandon. If a repair changes implementation or evidence in review scope, use a new
+immutable packet and validated review summary before closeout rather than rebinding the
+old review. Worker Packet v1 and its summary do not bind a task worktree digest.
+
+After the final validated `SUMMARY.json`, write one canonical `ultra-task-evidence-v2` record only after completing the raw-receipt binding below.
+When the task's owner-designated review mode is external manual, the final review
+product is instead the external reviewer's real receipt, bound through the
+`review_mode: "external-manual"` branch of
+`../ultra-plan/references/task-evidence-v2.md`: publish that receipt under
+`.ultra/evidence/<task-id>/`, record its exact stable-byte SHA-256, and verify it
+with the sensor's `--verify-external-receipt` mode instead of inventing a strict
+session. Never fabricate one branch's artifacts to satisfy the other's shape.
+The `subject` is an independently captured completion-snapshot freshness observation.
+Before writing `evidence.json`, resolve every
+command and external-observation `raw_evidence_ref` below the real repository root and
+take bounded stable repository-contained bytes from an ordinary regular non-symlink file
+opened nonblocking and no-follow. Reject a missing, escaped, symlinked, special,
+oversized, or replaced file; otherwise compute `raw_evidence_sha256` from that one byte
+snapshot. Publish that canonical record at `.ultra/evidence/<task-id>/evidence.json`,
+read back the stable record and each raw ref,
+and require the same ref bytes and digest before continuing.
+Follow `../ultra-plan/references/task-evidence-v2.md`: `task_review` separately binds the retained strict summary; record one typed acceptance entry per criterion, all
+six dimensions, the exact Execution Packet and review identities, blocking-finding
+dispositions, evidence refresh refs, artifacts, limitations, and retention without
+claiming that the review summary proves `subject.worktree_digest`. Read the record back, then update context
+`## Task Review`, Completion, and `## Resume Note`; the context has no second status.
+Only after those facts are durable may the primary model write `completed` to the
+ledger and read the row back. When the task's work package sits under an
+ACK-ready primary transfer whose newest terminal receipt is a completed v2
+RESULT, this sequence is that contract's prescribed closeout: publish the
+handoff's `CLOSEOUT.json` beside the frozen RESULT — citing the review receipt,
+the closeout-start/end observations, and any recorded owner-authorized
+continuation — instead of refreshing the RESULT or opening a new handoff; the
+closeout starts no review and no repair round
+(`../ultra-change/references/primary-transfer.md`).
+
+If later work invalidates a completed task's criterion evidence, Dev performs an
+explicit reopen. A reopen changes the ledger row from `completed` to `in_progress`;
+Dev must never silently demote the row. Before that write, record the affected criterion IDs and reason in both the context Change Log and Resume Note, preserve the prior review as
+historical evidence, then write and read back the ledger transition. Refresh the named
+evidence, run task review for the new snapshot, and repeat this closeout sequence.
 
 Report the changed paths, the seam, the exact checks run, the review result, the
 evidence gaps and the residual risk. Recommend the next capability from what the
@@ -106,14 +234,16 @@ files now say; do not invoke it.
 
 ## When the owner decides
 
-Any REDUCTION, and each external effect separately.
-At most one authorized local task commit happens here; push, tag, publish and
-deploy each need their own authorization. An interrupted task leaves its worktree
-as it stands and says so in the Resume Note instead of tidying it away.
+The owner decides any REDUCTION and each external effect separately. At most one
+authorized local task commit happens here; push, tag, publish and deploy need separate
+authority. An interruption leaves the worktree as-is and names it in the Resume Note.
 
 ## References
 
+- `../ultra-change/references/change-contract.md` — canonical Active Change authority resolution.
 - `../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.
+- `../ultra-change/references/execution-grant.md` — read only for grant-activated continuation.
+- `../ultra-plan/references/task-evidence-v2.md` — canonical evidence, disposition, and task-review shape.
 - `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.
 
@@ -29,8 +29,8 @@ have answered by reading the repository spends the one input only they can give.
   never skipped because the original wording sounded clear.
 - Each answer carries the owner's confirmation, 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.
+- 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, reframe, then ask
 
@@ -52,7 +52,7 @@ product. Offer the reframe, never assert it, and treat a correction as the bette
 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.
+**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
 
@@ -67,10 +67,11 @@ Order questions so that answering one unlocks the next. Ask the framing question
 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.
+**Framing questions** come first, selecting only prompts from
+`references/reframing.md` that can change the current frame. They refuse the owner's
+framing on purpose, which is how they surface what the request left out. Stop once the
+owner confirms the frame or further prompts cannot distinguish a materially different
+build; a question count never decides that.
 
 **Detail questions** fill in the confirmed frame:
 
@@ -95,13 +96,15 @@ inferred consensus.
 
 ## How the loop ends
 
-Every ending hands back the same artifact: the decisions written one per line,
-each with the options rejected and the reason they lost. The caller chooses where
-it lands — `north-star.md`, `discovery.md`, a Change intent, or a decision file.
+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.
 
 - **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.
+- **Stalled** — the evidence shows that another in-scope question cannot produce a new
+  decision without unavailable owner input or a newly framed choice. Hand back the open
+  fields, the attempted distinctions, and what each one blocks; do not infer this from
+  a turn count.
 - **Unavailable** — the host cannot ask, or the owner stopped answering. Hand back
   the last confirmed state, every unanswered field named.
 
@@ -113,6 +116,6 @@ 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.
+  how it fails, the framing prompts, 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

@@ -36,13 +36,17 @@ Rules that keep this honest:
   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.
+- **Stop when the owner rejects the proposed role and confirms their original frame.**
+  Do not keep producing cosmetic reinterpretations. If a materially different reading
+  later becomes evidenced, present that new distinction rather than counting prior
+  attempts.
 
 ## 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.
+request left out. Ask only the prompts that can distinguish a materially different
+build, and stop when the owner confirms the frame or the remaining prompts cannot
+change it.
 
 | Question | What it recovers |
 |---|---|