ultra-builder-pro-cli 0.25.1 → 0.26.1

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

@@ -1,20 +1,39 @@
-# Baseline reconciliation manifest
-
-Write a JSON file inside `.ultra/changes/active/<change-id>/` with
-`$schema: "ultra-baseline-reconciliation-v1"`.
-
-Bind `change_id`, `baseline_id`, and `baseline_updates` exactly to the archive request.
-Include:
-
-- `semantic_changes`: stable id, `add` or `update`, project-relative `source_ref` using
-  `path#anchor`, the prior baseline digest or `null`, and the current file digest;
-- `resolved_gap_ids`: existing baseline gaps closed by this delivery;
-- `resolved_unknowns`: exact existing unknown summaries closed by this delivery;
-- `verification`: named checks with exact commands, `pass`, and bounded evidence;
-- `semantic_no_change_reason`: an evidence-backed reason when `baseline_updates` is
-  empty.
-
-Every updated file needs a semantic change record and current anchor. The before digest
-must match baseline authority and the after digest must match the file. Keep the
-manifest with the change so archive recovery can replay the same transaction after an
-interrupted filesystem move.
+# Delivery reconciliation contract
+
+Write exactly one `.ultra/changes/active/<change-id>/delivery.md`. It is editable while
+the Change is active and moves with the directory when archived.
+
+```markdown
+# Delivery: <change-id>
+
+## Outcome Reconciliation
+<accepted outcome versus observed result, with path#anchor evidence>
+
+## Specification and Documentation Updates
+<changed files and why, or an evidence-backed no-change statement>
+
+## Verification
+| Command | Exit | Evidence | Freshness |
+|---|---:|---|---|
+
+## Review
+<SUMMARY.json path, packet digest, verdict, and unresolved findings>
+
+## Technical Debt
+<bounded debt, consequence, owner, and upgrade path; or None>
+
+## Residual Risks and Omissions
+<owner disposition for every material item>
+
+## Recovery
+<rollback or recovery procedure and verification>
+
+## External Effects
+<commit, push, tag, publish, deploy: authorized and observed status separately>
+```
+
+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.

package/skills/ultra-dev/SKILL.md

@@ -1,66 +1,119 @@
 ---
 name: ultra-dev
-description: Implement one authoritative Ultra task through a fresh-context, test-driven, review-backed live path. Use when a planned task is executable, interrupted, or ready for focused recovery.
+description: Carry one planned task from a written implementation plan through red-green development to recorded evidence and a task-level review. Use when a task in the ledger is ready to execute, was interrupted partway, or has to be picked up in a fresh session or on another host.
 ---
 
-# Implement one task
-
-The model owns code reasoning and edits. Ultra owns the durable task contract,
-canonical Context Envelope, execution lease, immutable Worker Packet, evidence
-references, and checkpoint.
-
-## Bind execution
-
-1. Call `ultra.context { stage: dev, scope: { change_id, task_id }, detail: full }`.
-2. Import a newer team checkpoint with `ultra.sync`; stop on a real same-record or
-   active-session conflict.
-3. Reuse a valid lease or call `ultra.session { action: acquire }`. Acquire atomically
-   performs admission, compiles or reuses the implementation Context Envelope, mints
-   the lease/worktree, and returns the immutable Worker Packet. A separate
-   `action: admission` is an optional read-only preview, not a prerequisite.
-4. Verify the returned packet digest, purpose, acceptance, dependencies, public seam,
-   exact output path/schema, verification command,
-   non-goals, recovery, and required context refs. Update the task contract before
-   implementation when accepted intent changed.
-
-## Implement adaptively
-
-Reproduce the failure, write a failing test, or establish a characterization signal
-before changing logic. Implement the smallest complete vertical slice. Ask the owner
-only when new evidence changes product intent, compatibility, security, material cost,
-external effects, or recovery.
-
-Use typed `ultra.record` entries for `task_outcome / start|block|complete|attest_commit`,
-`event / append`, `artifact / bind`, `decision / accept`, and corrected
-`task_contract / revise`. Every worker output must repeat the exact `packet_digest`;
-the parent registers it only after packet, output path, schema, and digest validation.
-Live ownership, `in_progress`, session ids, leases, worktrees, telemetry, and
-completion hashes remain local runtime state; durable task outcome and evidence may
-enter the team checkpoint.
-
-Run focused and adjacent risk-justified checks, then a task-scoped independent review.
-Fix blocking findings and refresh affected evidence.
-
-## Commit one semantic checkpoint
-
-Call `ultra.checkpoint` once with `stage: dev`, the exact Change/Task scope, evidence,
-and stable idempotency key. It binds the exact Context Envelope and Worker Packet and
-reports outcome diagnostics. The model decides whether the implemented slice satisfies
-the Task; semantic warnings remain visible. A rejection means the declared authority,
-path, digest, or concurrency boundary was unsafe and leaves the draft mutable.
-
-After acceptance:
-
-1. Record `task_outcome / complete { id, packet_digest }`; never include a patch or SHA.
-2. Publish the durable completed status with `ultra.sync`.
-3. Create at most one authorized local task commit containing code, semantic
-   artifacts, and the team checkpoint.
-4. Record `task_outcome / attest_commit { id, completion_commit }` with that integrated
-   commit's full SHA. This is local mechanical proof and must not create another commit.
-
-Release the lease through `ultra.session`. Preserve a dirty or unintegrated worktree
-on interruption. Commit, push, tag, publish, deploy, or destructive cleanup require
-separate owner authority.
-
-Return changed paths, public seam, exact checks, review result, checkpoint, commit,
-session state, and residual risk. Do not invoke the next capability automatically.
+# 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.
+
+## 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
+   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.
+
+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.
+- The context file carries a Completion entry and a rewritten Resume Note.
+- A task-level review has run and its blocking findings are resolved.
+
+## Write the implementation plan before the code
+
+Fill in the task context's Implementation section as prose a person can read:
+which modules change, how the interfaces move, which seam the tests will use.
+Confirm that, then write code. Deciding the design while typing implementation
+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.
+
+## 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`
+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 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 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 |
+
+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.
+
+## When implementation and the specification disagree
+
+This is the one backward edge in the whole workflow. Classify before touching the
+specification, and classify by outcome rather than reason: does every commitment
+the specification already made still hold afterwards? If even one no longer holds
+it is a REDUCTION — stop and ask the owner, however good the argument. Log the
+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.
+
+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
+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.
+
+## References
+
+- `../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-dev/references/debugging.md

@@ -0,0 +1,22 @@
+# Evidence-first debugging
+
+Use this procedure for an observed error, failed check, or unexpected behavior. Diagnose
+before editing and work backward from the symptom to the earliest state that violates
+the accepted contract.
+
+1. Capture the complete symptom and reproduce it with the smallest exact command or
+   action. A different checkout or nearby passing test is not reproduction.
+2. Inspect the relevant diff, configuration, dependency, caller, side effect, and
+   runtime boundary.
+3. Form one falsifiable root-cause hypothesis and choose the smallest observation that
+   distinguishes it from alternatives.
+4. Test the hypothesis without broad refactoring. Record evidence that accepts or
+   rejects it in the active task context `## Change Log`.
+5. Write the failing regression on the public seam, then apply the smallest root-cause
+   repair through `ultra-tdd`.
+6. Rerun the exact reproduction and affected verification. Record residual uncertainty
+   and the recovery path in task evidence.
+
+After three distinct repair attempts reveal different underlying failures, stop
+patching. Treat the shared boundary as the next diagnostic target and report the
+evidence; do not disguise architectural uncertainty with another local fix.

package/skills/ultra-domain-modeling/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: ultra-domain-modeling
+description: Settle the project's vocabulary into CONTEXT.md — one opinionated definition per term, the rejected wordings, the relationships between terms, and the ambiguities already resolved. Use when another skill changes the shared language, meaning a term gets coined, two words compete for one concept, or one word turns out to mean two things.
+---
+
+# Keep one file that fixes what each domain word means
+
+This is how implementation reaches the earlier documents — not by better
+retrieval, but by needing less of it. `CONTEXT.md` is a compressor, not an index.
+What implementation lacks is rarely the content of the product specification; it
+is the vocabulary, so that trace anchors, variable names, function names, and
+test names all line up. It serves Goal 4, Cognitive Coherence.
+
+## Before you start
+
+1. Read `CONTEXT.md` at the repository root if it exists. Every skill reads it
+   for vocabulary; this one is for the moments that *change* it.
+2. Read the owner's current wording verbatim — their words are the raw material.
+3. Check the code for the same concept: type names, table names, function names.
+
+## Definition of done
+
+- Every term settled in this exchange is in the file, written the moment it was
+  settled rather than batched at the end.
+- Each entry defines what the term *is* in one or two sentences, and lists the
+  wordings that lost.
+- The file still holds vocabulary only, carrying no implementation detail.
+
+## The file
+
+Create it at the repository root the first time a term is actually settled, not
+before. This is the whole format:
+
+```markdown
+# {project name}
+
+{One or two sentences: what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{One or two sentences. Define what it is, not what it does.}
+_Avoid_: Purchase, Transaction
+
+## Relationships
+
+- One **Issue tracker** holds many **Issue**
+
+## Flagged ambiguities
+
+- "backlog" meant both the tool and the set of work — settled as **Issue tracker**
+```
+
+## Sharpen the language as it is spoken
+
+When several words compete for one concept, pick the best one and send the rest
+to `_Avoid_`. Keep only terms this project gives specific meaning to; general
+programming concepts stay out.
+
+- Name the conflict the moment it appears: the vocabulary defines cancellation
+  as one thing, and this sentence uses it as another — which one is meant?
+- Sharpen a vague word on the spot: "account" is either Customer or User.
+- Pressure-test a boundary with a concrete scenario.
+- Cross-check against the code: it cancels a whole Order, yet the description
+  allows cancelling part of one — which is true?
+
+## When the owner decides
+
+A term's meaning is the owner's to settle; you supply the candidates, the
+conflict you found, and your recommendation. Where the answer is a genuine
+trade-off, hard to reverse, and would look strange to a reader without the
+background, it belongs in a decision record instead of a vocabulary entry. All
+three have to hold, or `decisions/` fills with a log. Create that directory on
+the first record that qualifies.
+
+## References
+
+- `../ultra-think/references/autonomy-boundary.md` — read when renaming a term an
+  accepted specification already uses; that renaming is a C5 boundary.

package/skills/ultra-grilling/SKILL.md

@@ -0,0 +1,118 @@
+---
+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.
+---
+
+# Turn a vague ask into a decision list the owner has explicitly confirmed
+
+No-one knows exactly what they want at the start. This prevents the misalignment
+that surfaces at the end, when both sides believed they had agreed and the
+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.
+3. Look up every fact you can reach on your own: repository files, Git history,
+   installed dependencies, tool output.
+
+Facts are yours to find, decisions are the owner's to make. A question they could
+have answered by reading the repository spends the one input only they can give.
+
+## Definition of done
+
+- 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 calling skill holds a decision list it can write to a file: one line per
+  decision, each with the options rejected and why.
+
+## Extract, reframe, then ask
+
+**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.
+
+## One question per turn
+
+Ask through the host's native question surface, one unresolved choice at a time,
+and wait for the answer. Several questions at once gets the easy one answered and
+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. 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.
+
+## When the owner decides
+
+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.
+
+## 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.
+
+- **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.
+
+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.