ultra-builder-pro-cli 0.25.1 → 0.26.0

package/skills/ultra-deliver/SKILL.md

@@ -1,46 +1,65 @@
 ---
 name: ultra-deliver
-description: Reconcile and archive an explicitly accepted Ultra Change with recoverable local evidence. Use when the caller is ready to make a local delivery handoff with current managed evidence and an explicit rationale for any omitted capability.
+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.
 ---
 
-# Converge and archive local authority
-
-Delivery closes local Ultra authority. It never grants commit, push, tag, registry
-publication, deployment, or another external effect.
-
-## Prepare the packet
-
-1. Call `ultra.context { stage: deliver, scope: { change_id }, detail: full }`.
-2. Import a newer team checkpoint with `ultra.sync`; stop on a real conflict.
-3. Inspect current task outcomes, tests, both review axes, accepted decisions, typed
-   delta, documentation reconciliation, and checkout evidence. Decide whether the
-   actual Change is sufficiently complete; explicitly record any omitted stage and its
-   evidence-based rationale instead of inventing a fixed recipe.
-4. Resolve every specification-learning candidate. Keep updates inside the Change
-   overlay until archive.
-5. Write and register documentation reconciliation and an
-   `ultra-delivery-report-v1` report. The report binds Change, baseline, HEAD,
-   worktree/context digests, local checks, rollback guidance, and timestamp; it contains
-   no release decision.
-
-Use one typed `ultra.record` batch for `artifact / bind`, any normalized
-`decision / accept`, and bounded `event / append` facts.
-
-## Archive once
-
-Call `ultra.archive` once with the Change id, stable idempotency key, archive summary,
-reconciliation fields, delivery evidence steps, explicit omissions, and report output.
-The model's report is the semantic handoff. MCP validates its current registered
-authority, paths, digests, reconciliation structure, and idempotency; applies the
-overlay and archive through the recoverable filesystem/DB transaction; rebinds
-registered artifacts into a self-contained archive; and publishes the updated team
-checkpoint. It does not require a hard-coded Plan/Dev/Test/Review/Deliver sequence.
-
-Semantic warnings remain in the archive history but do not reject an explicit local
-handoff. Corruption, unsafe paths, digest/CAS conflicts, permissions, or recovery
-failure remain fail-closed and route to `ultra-doctor`.
-
-Verify the archived packet, baseline, checkpoint, and rollback state. Handle any
-separately authorized Git or release effect only after local delivery and report it as
-external evidence, not Ultra delivery authority. Do not invoke another capability
-automatically.
+# 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.
+
+## Before you start
+
+1. Read `.ultra/tasks.json` and each completed task's `context_file`, 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.
+
+## Definition of done
+
+- Actual outcome, specifications, docs, tests and aggregate review have been reconciled.
+- 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.
+
+## 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.
+
+## 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.
+
+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
+deployment as applicable. A failure in one does not imply permission to attempt another.
+
+## When the owner decides
+
+The owner accepts residual risk, reductions, the version, and every external effect.
+Without release authority, stop after the recoverable local archive and report it.
+
+## References
+
+- `../ultra-review/SKILL.md` — read before aggregate review and refactoring.
+- `../ultra-think/SKILL.md` — read when version or release posture is a consequential
+  trade-off rather than an established repository rule.
+- `../ultra-think/references/autonomy-boundary.md` — read before scope or evidence shrinks.
+- `references/baseline-reconciliation.md` — exact `delivery.md` reconciliation contract.

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,100 @@
 ---
 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.
+
+## 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_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 |
+| `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 the mock
+  boundary.
+- `../ultra-think/references/autonomy-boundary.md` — read the moment the
+  specification and the implementation 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,79 @@
+---
+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 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.
+
+## Extract first, 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.
+
+## 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, and prefer the ones whose
+answer changes what gets built:
+
+- 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?
+
+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.
+
+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.
+
+## Hand back a list
+
+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.
+
+## References
+
+- `../ultra-think/references/autonomy-boundary.md` — read when an answer removes
+  something the specification already promised, or otherwise crosses C5.