ultra-builder-pro-cli 0.10.0 → 0.12.1

package/skills/ultra-change/SKILL.md

@@ -1,122 +1,76 @@
 ---
 name: ultra-change
-description: "Open or resume a continuous change, capture its delta and decisions, compile bounded role context, and route one executable slice."
-user-invocable: true
-runtime: all
-mcp_tools_required:
-  - change.create
-  - change.update
-  - change.get
-  - change.list
-  - change.context
-  - change.breadcrumb
-  - change.learning_propose
-  - change.learning_resolve
-  - task.create
-  - task.list
+description: Open or resume a bounded continuous change and connect its intent, delta, decisions, context, and executable tasks. Use when maintaining or extending an Ultra project after its baseline exists.
 ---
 
-# ultra-change — Delta Entry and Alignment Gate
+# Open or resume a continuous change
 
-Use this after the first baseline delivery for fixes, small features, redesigns,
-incidents, and maintenance. It keeps specifications live through a delta → implement
-→ learn → converge loop.
+Keep post-delivery work aligned through a delta, implementation, learning, and
+convergence loop.
 
 ## Authority boundary
 
-All change and task lifecycle writes use the live MCP tools. Do not write raw SQLite
-or mutate generated task/context projections. Provider payloads stay in their owning
-memory or graph system; Ultra stores metadata references only.
-
-## 1. Establish the change
-
-Call `change.list` and `change.breadcrumb` first.
-
-- Resume the single matching active/blocked change.
-- If several may match, require an explicit id.
-- Otherwise auto-discover repository facts, then ask only the highest-value unresolved
-  question. Do not ask the user for branch, stack, paths, or behavior already visible.
-
-Capture:
-
-- observable problem or requested outcome;
-- acceptance and explicit non-goals;
-- affected public seam or integration boundary;
-- documentation impact: `required` paths, `none` with rationale, or blocking `unknown`;
-- kind: `quick`, `standard`, `major`, or `incident`;
-- decision inventory: accepted decisions, rejected alternatives, and unresolved choices.
-
-Create with `change.create` using a stable kebab-case id. Update an existing packet
-with `change.update`; never create a parallel packet for the same outcome.
-
-## 2. Write only the delta
-
-The bounded packet is:
-
-```text
-.ultra/changes/active/<change-id>/
-  intent.md
-  delta/                 # standard and major
-  plan.md                # standard and major
-  diagnosis.md           # incident
-  context-manifest.json  # MCP projection
-  spec-learning.json     # MCP projection
-  verification.md        # convergence projection
-```
-
-`intent.md` records outcome, acceptance, non-goals, docs impact, and decisions.
-Delta files describe only differences from the baseline. An incident diagnosis must
-record symptom, earliest bad state, root-cause hypothesis, discriminating evidence,
-and recovery boundary.
-
-## 3. Create an executable slice
-
-Prefer the smallest vertical `tracer_bullet` that crosses a live public seam. Split
-only when ownership or verification is genuinely independent. Each task must declare:
-
-- one observable outcome and linked `change_id`;
-- bounded files/contracts and dependencies;
-- `public_seam` that proves reachability;
-- exact `verification_command`;
-- expected red signal for a bug/incident;
-- documentation impact.
-
-Persist tasks with `task.create`. Generated `tasks.json` is never an input authority.
-
-## 4. Compile Context Manifest v2
-
-Call `change.context` for the next task with:
-
-```json
-{
-  "id": "<change-id>",
-  "task_id": "<task-id>",
-  "role": "plan",
-  "gate": "planning",
-  "context_refs": [{"ref":"<path>","kind":"spec","reason":"defines acceptance","required":true}],
-  "budget": {"max_tokens":12000,"max_files":12},
-  "execution_contract": {
-    "slice_kind":"tracer_bullet",
-    "public_seam":"<reachable boundary>",
-    "verification_command":"<exact command>",
-    "context_budget_percent":40
-  }
-}
-```
-
-Include only files needed for the current role and gate. Missing required references,
-digest drift, file-count overflow, or a fresh-context budget over 40% blocks readiness.
-Use `expand_contract` only for an explicitly approved wider slice.
-
-## 5. Handle discoveries without silent spec drift
-
-When implementation reveals a stable requirement, invariant, or public behavior not
-in the baseline, call `change.learning_propose` with evidence and target document.
-It is a candidate, not an automatic edit. A human/primary-agent decision must approve
-or reject it; approved learning is marked applied only after the baseline was updated.
-
-## Exit contract
-
-Call `change.breadcrumb` and report the compiled task, readiness, blockers, and its
-single next action. Do not claim alignment while documentation impact is unknown,
-context is stale, or a material decision remains unresolved.
+Use Ultra MCP tools for change and task lifecycle writes. Do not write raw SQLite or
+mutate generated task and context projections. External memory or code-graph systems
+own their payloads; Ultra stores only provider references supplied by the user or host.
+
+## Workflow
+
+1. Call `baseline.get`. State integrity failure routes to `ultra-doctor`. When no
+   change is active, a missing, incomplete, or stale baseline routes to `ultra-init`.
+   An urgent or already active bounded change may proceed with that condition recorded
+   as a warning. `change.converge` requires an approved `ready` baseline; repository
+   revision and tracked-spec drift created by the change are reconciled at archive.
+2. Call `change.list` and `change.breadcrumb`.
+   - Resume the single change that matches the requested outcome.
+   - Require an explicit id when several changes could match.
+   - Create a new change only when no existing packet represents the same outcome.
+3. Capture the observable outcome, acceptance, non-goals, affected public seam,
+   documentation impact, and unresolved decisions.
+4. Classify the change as `quick`, `standard`, `major`, or `incident`. Ask only for a
+   material product, risk, or recovery decision that repository evidence cannot answer.
+5. Call `change.create` with a stable kebab-case id, or `change.update` when resuming.
+6. Write the minimum artifact set required by the classification:
+
+   ```text
+   .ultra/changes/active/<change-id>/
+     intent.md
+     delta/                 # standard and major
+     plan.md                # standard and major
+     diagnosis.md           # incident
+     context-manifest.json  # generated projection
+     spec-learning.json     # generated projection
+     verification.md        # generated projection
+   ```
+
+   Delta files describe differences from the baseline, not a second copy of it.
+   Incident diagnosis records the symptom, earliest bad state, falsifiable
+   hypotheses, evidence, root cause, and recovery boundary.
+7. Create the smallest executable vertical slice with `task.create`. Each task needs
+   one outcome, bounded ownership, dependencies, a live public seam, an exact
+   verification command, and documentation impact.
+8. Compile `change.context` for the next role and gate. Include only required
+   references and the task execution contract. Missing required references, digest or
+   HEAD drift, an absent public seam or verification command, and unknown
+   documentation impact are blockers. File count, token estimate, and context-share
+   thresholds are advisory warnings: narrow reads or split the slice when useful, but
+   never raise a threshold merely to make the warning disappear or refuse necessary
+   incident context.
+9. Call `change.breadcrumb` and return its single next action.
+
+## Specification learning
+
+When implementation uncovers a stable requirement, invariant, or public behavior
+missing from the baseline, call `change.learning_propose` with evidence and a target
+document. The proposal does not edit the baseline. It must be approved or rejected,
+and an approved item is marked applied only after the target document is updated and
+verified.
+
+## Completion gate
+
+Do not claim alignment while a material decision is unresolved, documentation impact
+is unknown, context is stale, or the next task is not executable. `change.converge`
+also requires a `ready` baseline, so incomplete adoption must be resolved before
+convergence. Normal HEAD or tracked-spec drift caused by the active change is not a
+convergence blocker. Declare every baseline update at archive; archive fails and rolls
+back when revision or digest health remains stale after reconciliation.

package/skills/ultra-deliver/SKILL.md

@@ -1,111 +1,83 @@
 ---
 name: ultra-deliver
-description: "Converge an implementation, approved specification learning, independent review axes, and release evidence into one recoverable baseline."
-user-invocable: true
-runtime: all
-mcp_tools_required:
-  - change.list
-  - change.get
-  - change.context
-  - change.breadcrumb
-  - change.learning_resolve
-  - change.converge
-  - change.archive
-cli_fallback: "direct user interaction"
+description: Converge verified implementation, specification learning, review evidence, and release artifacts into a recoverable baseline. Use when an initial baseline or active change has current passing evidence and is ready to archive or release.
 ---
 
-# ultra-deliver — Converge, Archive, Release
+# Converge and deliver
 
-Deliver the current baseline or one continuous-change packet. Change lifecycle writes
-use MCP only; `.ultra/test-report.json`, review sessions, and delivery reports are
-evidence artifacts.
+Deliver one baseline or continuous change. Change lifecycle writes use MCP; test,
+review, and delivery reports are evidence artifacts.
 
-## 1. Bind the delivery
+## Bind current evidence
 
-1. Call `change.list` for active, blocked, and ready changes.
-2. Bind exactly one relevant change; require an id when ambiguous. Initial baseline
-   delivery may use `change_id: null`.
-3. Call `change.breadcrumb`. A stale/blocked context or incomplete linked task blocks.
-4. Verify `.ultra/test-report.json` exists, passed, matches the change, and records the
-   current full HEAD plus at least one public seam.
-5. Verify the latest review session matches the same HEAD and has passing independent
-   `spec_fidelity` and `engineering_standards` axes.
+1. Call `baseline.get`, then `change.list`. Bind exactly one relevant change, or the
+   current draft/adopting baseline when this is the initial delivery.
+2. Call `change.breadcrumb`. Context-size warnings are advisory, but delivery blocks
+   on incomplete baseline adoption, stale execution context, incomplete linked tasks,
+   or unresolved readiness. HEAD and tracked-spec drift caused by the current change
+   remain visible warnings until archive reconciliation.
+3. Require a passing test report for the current full HEAD and at least one declared
+   public seam.
+4. Require current independent `spec_fidelity` and `engineering_standards` review
+   verdicts. Evidence from another checkout, commit, task set, or change is invalid.
 
-Do not reuse evidence from another checkout, commit, task set, or change.
+## Reconcile the baseline
 
-## 2. Reconcile specification learning
+Call `change.get` for authoritative learning candidates.
 
-Call `change.get` for authoritative `learning_candidates`; use the packet's
-`spec-learning.json` only as the inspectable projection.
+- Resolve every proposed item as approved or rejected.
+- Apply each approved item to its declared baseline target, verify the edit, then mark
+  it applied.
+- Preserve rejection reasons as decision evidence.
+- Confirm previously applied items remain represented in the target document.
 
-- `proposed`: require approve or reject through `change.learning_resolve`.
-- `approved`: update the declared baseline target, verify the edit, then mark `apply`.
-- `rejected`: preserve the reason as decision evidence.
-- `applied`: verify the target still contains the accepted behavior.
+Reconcile accepted delta content and documentation impact into baseline documents.
+Record updated paths or a specific no-change reason. Unknown documentation impact,
+unresolved placeholders, and behavior that exists only in the delta block convergence.
 
-Any proposed or approved candidate blocks convergence. This is the mandatory path that
-keeps baseline specs alive after daily changes; it is not cross-session memory.
+For an initial baseline without a change, call `baseline.record`, obtain explicit owner
+approval, and call `baseline.converge`. Do not simulate initial delivery through a null
+change record.
 
-Reconcile accepted `delta/` content and declared documentation impact into baseline
-documents. Record `baseline_updates`, or a specific no-change reason. No unresolved
-placeholder, unknown docs impact, or delivered-only-in-delta behavior may remain.
+## Verify the release candidate
 
-## 3. Verify the release candidate
+Use a clean, reviewed release commit. Show any remaining diff and obtain explicit
+authorization before staging or committing. Never stage unrelated user changes.
 
-Require a clean, reviewed release commit. If changes remain, show the diff and obtain
-explicit approval before committing. Never auto-stage unrelated user changes.
+Run the exact repository commands needed for focused regression, relevant full tests,
+static checks, production build, package/install/doctor smoke when distributed, the
+public seam, and rollback or recovery sanity. Any post-verification edit invalidates
+the affected evidence.
 
-Run exact project commands for:
+Compile final change context at the release commit with the convergence gate. It must
+be ready before calling `change.converge`.
 
-1. focused regression/acceptance feedback loop;
-2. full relevant tests;
-3. static checks and production build;
-4. package/install/doctor smoke where the product is distributed;
-5. public-seam acceptance and rollback/recovery sanity.
+## Converge and archive
 
-Record commands, exit results, and current HEAD. Any post-test edit invalidates the
-test and review gates.
+Submit structured evidence for the reviewed diff and seam, test signals, baseline and
+delta, documentation, both independent review axes, and incident diagnosis when
+applicable. Do not collapse review axes or replace exact signal fields with prose.
 
-## 4. Compile final role context
+Resolve named blockers, rerun invalidated gates, then call `change.archive` with the
+summary and baseline updates. Archive reconciliation refreshes the authoritative
+baseline revision and digests. The archive transaction rechecks baseline health and
+rolls back the state row, artifacts, and reconciliation events if any tracked digest
+or repository revision remains stale. Verify the result with `baseline.get` before
+release.
 
-Call `change.context` at the release commit with `role=review`, `gate=convergence`,
-current required refs/digests, the public seam, exact verification command, and the
-single next action `Archive the converged change`. Readiness must be `ready`.
+## Optional release
 
-## 5. Converge
+Only when release authorization is in scope:
 
-Call `change.converge` with evidence rows for:
-
-- `diff`: reviewed release diff and public seam;
-- `tests`: exact signal object (`command`, expected/observed red, observed green,
-  deterministic, duration when known) and seam;
-- `spec`: baseline/delta and applied learning evidence;
-- `docs`: updated paths or explicit non-applicability;
-- `review`, `axis=spec_fidelity`;
-- `review`, `axis=engineering_standards`;
-- `diagnosis` for incidents.
-
-Do not collapse the two review axes or substitute prose for the signal fields. If
-convergence returns blockers, fix the named source and rerun the invalidated gates.
-
-## 6. Archive and release
-
-After `ready=true`, call `change.archive` with summary and `baseline_updates` (or the
-validated no-change reason). Then:
-
-1. determine the semantic version from user-visible compatibility;
+1. determine the semantic version from compatibility impact;
 2. update version and changelog;
-3. rerun release verification if version files changed;
-4. create a non-force commit/tag and push only with explicit release authorization;
-5. publish the package/release through the repository's authenticated workflow;
-6. verify the remote tag/release and registry version independently.
-
-Write `.ultra/delivery-report.json` with change id, archived status, commit, version,
-commands, package/release identifiers, baseline updates, rollback notes, and timestamp.
+3. rerun checks invalidated by version changes;
+4. create a non-force commit and tag;
+5. push and publish through the repository's authenticated workflow;
+6. independently verify the remote commit, tag, release, and registry version.
 
-## Completion gate
+Write the delivery report with the change id, archive status, commit, version, exact
+commands, release identifiers, baseline updates, rollback notes, and timestamp.
 
-Delivery is complete only when the change is archived, local and remote commit/tag
-agree, registry/release verification is current, and the worktree contains no
-unexplained scope. Report the outcome first, exact evidence next, and residual risks
-last. Never say “published” based only on a local version bump.
+Delivery is complete only when local and remote evidence agree and the worktree has no
+unexplained scope. A local version bump is not publication evidence.

package/skills/ultra-dev/SKILL.md

@@ -1,120 +1,61 @@
 ---
 name: ultra-dev
-description: "Execute one fresh-context vertical slice through a public seam with strict red-green evidence, bounded recovery, and specification learning."
-user-invocable: true
-runtime: all
-mcp_tools_required:
-  - task.update
-  - task.get
-  - task.list
-  - change.get
-  - change.context
-  - change.breadcrumb
-  - change.learning_propose
+description: Execute one authoritative Ultra task through a bounded fresh context, a red-green feedback loop, live-path verification, and review. Use when a dependency-ready planned slice is ready for implementation.
 ---
 
-# ultra-dev — One Slice, One Feedback Loop
+# Execute one vertical slice
 
-Drive one task from `pending` to `completed`. Task status lives in
-`.ultra/state.db`; generated task JSON and context frontmatter are read-only.
+Drive one task from `pending` to `completed` without widening its contract silently.
 
 ## Authority and recovery
 
-If `task.list`, `task.get`, or `task.update` fails, stop. Never write raw SQLite,
-`.ultra/tasks/tasks.json`, or projected status fields. On
-`LEGACY_STATE_MIGRATION_REQUIRED`, use the documented migration command before work.
+Task state changes use `task.update`. Never write raw SQLite, generated task JSON, or
+projected status fields. If task MCP access fails, stop and route state health to
+`ultra-doctor`.
 
-At entry, read `change.breadcrumb` when a change is active. A blocked or stale
-breadcrumb is an implementation blocker, not an advisory warning.
+Read `change.breadcrumb` when a change is active. Stale context, blocked readiness,
+unknown documentation impact, or a HEAD mismatch blocks implementation.
+Baseline-adoption and context-size warnings do not block an active slice. Address
+them when practical without dropping required evidence or arbitrarily changing a
+threshold. Approved baseline availability is enforced at convergence; revision and
+tracked-spec health are reconciled and verified at archive.
 
-`.ultra/workflow-state.json` is a compact recovery checkpoint only. Record command,
-task, branch, current step, status, and timestamp; do not copy prompts, codebase
-summaries, or provider memory into it.
-
-## 1. Select and compile the slice
+## Workflow
 
 1. Select the requested task, otherwise the first dependency-ready pending task.
-2. Call `task.get`; verify dependencies, ownership, acceptance, public seam, and exact
-   verification command.
-3. If linked to a change, call `change.get`, then compile `change.context` with:
-   `role=implement`, `gate=implementation`, the smallest required references, and the
-   task's execution contract.
-4. Stop on missing/stale references, budget overflow, unknown documentation impact,
-   or a HEAD mismatch. Do not compensate by loading the whole repository.
-5. Mark the task `in_progress` with `task.update` and checkpoint the step.
-
-The default slice is a `tracer_bullet`. An `expand_contract` must already be approved;
-implementation does not widen its own contract silently.
-
-## 2. Establish red
-
-Before production logic changes:
-
-1. Reproduce the smallest observable symptom at the declared public seam.
-2. Add or identify the regression/contract test.
-3. Run the exact command and record:
-   - command;
-   - expected failure;
-   - observed red result;
-   - deterministic/non-deterministic classification;
-   - duration when useful.
-
-For a new feature, red means an assertion expressing missing behavior. For a refactor,
-establish a green characterization baseline first. Documentation/config-only tasks may
-use a structural validator instead of a failing test, but must state why.
-
-If red cannot be observed, stop and correct the task contract; do not implement against
-an unproven hypothesis.
-
-## 3. Implement the minimum complete path
-
-- Trace entry point → domain rule → side effect → public seam.
-- Search for existing utilities and dependencies before adding helpers.
-- Keep IO at boundaries and domain behavior testable.
-- Include required validation, errors, observability, recovery, and documentation.
-- Preserve unrelated dirty worktree changes and stay within allowed paths.
-- Verify each meaningful increment through the same feedback loop.
-
-If implementation reveals a stable invariant or public behavior absent from the
-baseline, call `change.learning_propose` with its evidence and target document. Do not
-edit the baseline silently and do not store the discovery as Ultra memory.
-
-## 4. Establish green and inspect reachability
-
-Run, in order:
-
-1. the exact red command until the observed failure becomes green;
-2. adjacent focused tests;
-3. type check/lint/build proportionate to the change;
-4. the live public-seam acceptance path;
-5. final diff and worktree scope inspection.
-
-Record exact commands and zero-failure results. “Compiled” or “unit tests pass” is not
-enough when the new module is not connected to a consumer.
-
-## 5. Review gate
-
-Checkpoint `status=pre_review`, then invoke `/ultra-review all`. The review must produce
-independent `spec_fidelity` and `engineering_standards` verdicts. Fix all P0/P1 issues,
-rerun affected tests, and recheck until both axes pass. The primary host owns final
-verification; review workers never mutate durable Ultra state.
-
-## 6. Complete the task
-
-First call `task.update` with `status=completed` and completion commit/evidence
-supported by the task contract. Then, for a linked change, recompile
-`change.context` at the final HEAD with:
-
-- `role=implement`, `gate=verification`;
-- exact required references and current digests;
-- the public seam and verification command;
-- a single next action, normally `Run ultra-test for this change`.
-
-This ordering ensures the snapshot records the completed task state. Clear the active
-workflow checkpoint, call `change.breadcrumb`, and report exactly one next action.
+2. Call `task.get` and verify acceptance, dependencies, ownership, public seam, and
+   exact verification command.
+3. For a linked change, call `change.get`, then compile `change.context` for the
+   implementation role and gate with the smallest required references.
+4. Mark the task `in_progress` only after the context is ready.
+5. Establish the feedback-loop baseline before changing production logic:
+   - reproduce the smallest observable symptom at the declared seam;
+   - add or identify the contract or regression test;
+   - record the exact command, expected signal, and observed result.
+
+   A feature starts with an assertion for missing behavior. A refactor starts from a
+   green characterization baseline. Documentation or configuration work may use a
+   structural validator when no logic test applies.
+6. Implement the minimum complete path from entry point to public seam. Reuse existing
+   utilities, keep IO at boundaries, include required errors and recovery, and preserve
+   unrelated worktree changes.
+7. If the work reveals a stable requirement or public behavior absent from the
+   baseline, call `change.learning_propose`. Do not edit the baseline silently or store
+   the discovery as private Ultra memory.
+8. Verify in this order:
+   - the original feedback-loop command;
+   - adjacent focused tests;
+   - proportionate static checks and build;
+   - the live public-seam acceptance path;
+   - final diff and worktree scope.
+9. Run `ultra-review` against the current diff. Fix blocking findings, rerun invalidated
+   checks, and require independent specification-fidelity and engineering verdicts.
+10. Call `task.update` with `status=completed` and exact evidence. For a linked change,
+    recompile the verification context at the final HEAD, then call
+    `change.breadcrumb`.
 
 ## Completion evidence
 
-Report task/change id, changed paths, red signal, green commands, public-seam result,
-review session, spec-learning candidates, and remaining blockers. If any item is
-missing, leave the task in progress or blocked rather than claiming completion.
+Report the task and change ids, changed paths, baseline signal, passing commands,
+public-seam result, review session, specification-learning candidates, and one next
+action. Leave the task in progress or blocked when required evidence is missing.