ultra-builder-pro-cli 0.8.1 → 0.10.0

package/skills/ultra-change/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ultra-change
-description: "Start or resume a continuous post-delivery change, compile bounded context, declare documentation impact, and route the change through implementation and convergence."
+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
@@ -8,142 +9,114 @@ mcp_tools_required:
   - change.get
   - change.list
   - change.context
+  - change.breadcrumb
+  - change.learning_propose
+  - change.learning_resolve
   - task.create
   - task.list
 ---
 
-# ultra-change — Continuous Change Entry
+# ultra-change — Delta Entry and Alignment Gate
 
-Use this workflow for daily fixes, small features, redesigns, and incidents after
-the initial `init → research → plan → dev → test → deliver` baseline exists.
-Each piece of work becomes one durable change unit instead of an informal edit
-that drifts away from specifications and verification evidence.
+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.
 
-## Authority and provider boundary
+## Authority boundary
 
-- `.ultra/state.db` is authoritative for the change, its tasks, events, incidents,
-  context snapshots, and projection status.
-- `.ultra/changes/active/<change-id>/` contains inspectable artifacts, not a
-  second state authority.
-- Memory and code graph are external providers. Pass only metadata references:
-  `provider`, `project`, `reference`, `revision`, `indexed_head`, and `status`.
-- Never paste recalled memories, graph nodes, embeddings, summaries, or provider
-  payloads into `provider_refs`. If provider data is unavailable, record
-  `status: unavailable` and continue with current-checkout evidence.
-- If any required change/task MCP operation is unavailable, stop. Do not edit
-  `state.db`, `tasks.json`, or context projections directly.
+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.
 
-## Arguments
+## 1. Establish the change
 
-- `$1`: existing change id, or a short title for a new change.
-- Optional flags/concepts: `quick`, `standard`, `major`, `incident` and an
-  explicit documentation impact.
+Call `change.list` and `change.breadcrumb` first.
 
-## 1. Resume before creating
+- 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.
 
-Call `change.list` for `active` and `blocked` changes. If `$1` matches an
-existing id, call `change.get` and resume it. If the request clearly belongs to
-an active change, show the match and continue there rather than creating a
-duplicate.
+Capture:
 
-Do not resume `ready`, `archived`, or `cancelled` work as a new mutation. Create
-a follow-up change that links to the prior archive in its intent.
+- 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.
 
-## 2. Classify the change
+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.
 
-Choose the smallest honest kind:
+## 2. Write only the delta
 
-| Kind | Use when | Required convergence evidence |
-|---|---|---|
-| `quick` | localized fix or tiny behavior change | diff, tests, spec |
-| `standard` | normal feature or cross-file change | diff, tests, spec, docs, review |
-| `major` | architecture, public contract, migration, or broad redesign | diff, tests, spec, docs, review |
-| `incident` | canonical debug lane for a production/runtime failure | diagnosis, diff, tests |
+The bounded packet is:
 
-When uncertain between two kinds, choose the higher-risk kind. Classification
-changes the proof required; it must not be used to bypass evidence.
-
-## 3. Declare intent and documentation impact
-
-Before implementation, write a concise intent with:
-
-- observed problem or requested outcome;
-- acceptance behavior and non-goals;
-- affected contract/surface;
-- recovery or rollback concern when material.
-
-Documentation impact is mandatory:
+```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
+```
 
-- `required`: list every baseline document expected to change;
-- `none`: provide a concrete rationale;
-- `unknown`: allowed only while investigating and blocks convergence.
+`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
+  }
+}
+```
 
-Create the change with `change.create`. Use a stable kebab-case id. External
-provider references are optional and metadata-only.
+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.
 
-## 4. Build the delta packet
+## 5. Handle discoveries without silent spec drift
 
-The change directory is the bounded execution packet:
+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.
 
-```text
-.ultra/changes/active/<change-id>/
-  intent.md
-  context-manifest.json
-  delta/                  # required for standard and major
-  plan.md                 # required for standard and major
-  diagnosis.md            # created and structurally required for incident
-  verification.md         # generated by convergence
-```
+## Exit contract
 
-For `standard` and `major`, write delta documents under `delta/` describing
-what changes relative to the current baseline. Do not copy the whole baseline.
-Write `plan.md` with live entry points, files/contracts, tests, documentation,
-and rollback. For `quick`, add only artifacts needed to make the decision and
-evidence inspectable. For `incident`, complete the generated `diagnosis.md` with
-non-empty `Reproduction`, `Hypotheses`, `Root cause`, `Regression test`, and
-`Recovery` sections. Free-form convergence evidence never substitutes for this
-durable diagnosis artifact.
-
-Create at least one task through `task.create` with `change_id` set. Split only
-when ownership, dependencies, or independent verification justify it. All task
-status changes remain MCP-authoritative.
-
-## 5. Compile task context
-
-Call `change.context` before implementation and again whenever any of these
-changes: git HEAD, task set, relevant specs, allowed paths, or provider revision.
-Supply only the minimum task/spec/path references needed for the current slice.
-
-Inspect `context-manifest.json` before handing work to an agent. A stale git head
-or task set is a hard signal to recompile. Provider `status: stale` is visible
-context, not permission to silently refresh or mutate the external provider.
-
-## 6. Route execution
-
-- For `incident`, diagnosis is the first execution slice. Route it to the bundled
-  `debugger` agent when the Host exposes native subagents; otherwise the primary
-  Host follows the same four-phase method. Supply only the compiled change/task
-  context. The primary Host owns the fix, updates `diagnosis.md`, and reruns the
-  discriminating regression test.
-- Implement one linked task with `/ultra-dev <task-id>`.
-- Run `/ultra-test` for project-level evidence.
-- Run `/ultra-review` when the change kind requires review.
-- Update baseline docs declared in `docs_impact` during the change, not after
-  memory has gone cold.
-- Finish with `/ultra-deliver`; it runs deterministic change convergence and
-  archive reconciliation before release actions.
-
-If work exposes a new requirement, update the change intent/delta and recompile
-context before continuing. Never let code become the only record of the change.
-
-## 7. Report
-
-Return the change id, kind, artifact root, linked tasks, documentation impact,
-context freshness, provider-reference status, and exact next workflow. Separate
-provider unavailability from an Ultra runtime incident.
-
-## What this skill does not do
-
-- It does not implement, test, review, release, or repair runtime state.
-- It does not own or synchronize Memory/code-graph content.
-- It does not bypass user approval for destructive or external release actions.
+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.

package/skills/ultra-deliver/SKILL.md

@@ -1,239 +1,111 @@
 ---
 name: ultra-deliver
-description: "Converge and deliver a verified baseline or continuous change: reconcile specs, build/test, archive evidence, version, tag, and push."
+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"
 ---
 
-# ultra-deliver — Phase 3.5
+# ultra-deliver — Converge, Archive, Release
 
-Release the current working tree and close its continuous-change packet when
-one exists. `.ultra/test-report.json` is the test gate; `change.converge` is the
-deterministic closure gate; `.ultra/delivery-report.json` is the release report.
-Change lifecycle writes go through MCP only.
-
-## Prerequisites (all validations are blocking)
+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.
 
-### Validation 0 — Resolve continuous change
+## 1. Bind the delivery
 
-Call `change.list` for `active`, `blocked`, and `ready` work.
+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.
 
-- Exactly one relevant change → bind delivery to that id.
-- More than one → require an explicit id; never guess which change to archive.
-- None → allow initial-baseline delivery, but record `change_id: null`.
-- Active/blocked change → its linked tasks must all be completed and its
-  `test-report.json.change_id` must match.
-- Ready change → do not rerun convergence blindly; verify its existing
-  verification artifact still matches current HEAD before archive.
-
-### Validation 1 — `/ultra-test` passed
-
-Read `.ultra/test-report.json`:
-- File must exist → else: "Run `/ultra-test` first" → **EXIT**
-- `passed === true` → else: show `blocking_issues`, **EXIT**
-- `git_commit === current HEAD` → else: "Code changed since last test;
-  re-run `/ultra-test`" → **EXIT**
+Do not reuse evidence from another checkout, commit, task set, or change.
 
-### Validation 2 — No uncommitted changes
-
-`git status --porcelain` must be empty. If dirty, ask through the current
-Host's native user-interaction surface:
-- A: "Auto-commit all changes" → `git add -A && git commit -m "chore: pre-delivery cleanup"`
-- B: "Review changes first" → `git diff --stat` → re-ask
-- C: "Block delivery" → **EXIT**
-
-Commit failure (conflicts, hook rejection) → surface error and **EXIT**.
-
-## Workflow
+## 2. Reconcile specification learning
 
-### Step 1 — Documentation Update (MANDATORY)
-
-**1.1 CHANGELOG.md** (required):
-1. `git log --oneline <last-tag>..HEAD`
-2. Categorize by Conventional Commit type: `feat:` → Added, `fix:` → Fixed,
-   `chore:` → Maintenance, `refactor:` → Changed, `docs:` → Documentation,
-   `test:` → Tests, `perf:` → Performance.
-3. Insert a new version section at the top of CHANGELOG.md.
-4. Verify: Read CHANGELOG.md; confirm new version section exists.
-
-**1.2 Technical debt report** (required):
-1. Grep source for `TODO:` / `FIXME:` / `HACK:` / `XXX:`.
-2. Generate / refresh `.ultra/docs/technical-debt.md`:
-   ```markdown
-   # Technical Debt (<date>, <commit>)
-   | File | Line | Kind | Note |
-   |------|------|------|------|
-   | src/foo.ts | 42 | TODO | "remove after v1.3" |
-   ```
-3. Verify: file reflects current grep output.
-
-**1.3 README.md** (conditional — public API changed):
-1. Diff exported API signatures since last release (`git diff <last-tag>..HEAD -- 'src/**'`)
-2. If signatures changed, update README usage examples
-3. Verify examples match the new API
-
-**1.4 Baseline specification reconciliation** (continuous change):
-
-1. Read `intent.md`, `delta/`, and `docs_impact` from the bound change.
-2. Merge accepted deltas into the declared baseline documents.
-3. Record every updated project-relative path as `baseline_updates`.
-4. If no baseline file changes, write a specific `no_baseline_change_reason`.
-5. Verify no `[NEEDS CLARIFICATION]` or unresolved delta remains for delivered behavior.
-
-**Checklist**:
-- [ ] CHANGELOG.md updated
-- [ ] technical-debt.md refreshed
-- [ ] README.md reflects current API (if applicable)
-- [ ] active delta reconciled into baseline, or explicit no-change rationale exists
-
-Any unchecked → fix, then continue.
-
-### Step 2 — Production Build
-
-Detect build command (priority order):
-1. `package.json → scripts.build` → `npm run build` (or `pnpm build`/`yarn build`
-   based on lockfile)
-2. `Makefile` → `make build` or `make release`
-3. `Cargo.toml` → `cargo build --release`
-4. `go.mod` → `go build ./...`
-5. Nothing detected → ask the user for the command
-
-Non-zero exit → block with stderr captured, then ask the user:
-- A: "Fix error and retry"
-- B: "Abort delivery"
-
-### Step 3 — Version + convergence + release
-
-**3.1 Determine version bump**:
-- `git log <last-tag>..HEAD --oneline` → analyze commit types
-- `feat:` → minor, `BREAKING CHANGE:` / `!:` → major, else patch
-- Display `<old> → <new>`; allow an explicit user override.
-
-**3.2 Update version in project files**:
-- `package.json`, `Cargo.toml`, `pyproject.toml`, etc.
-- Verify: read the file; confirm new version.
-
-**3.2a Re-run release evidence after docs/version edits**:
-
-- Run the exact relevant test, type-check, build, and package commands again.
-- Capture command, exit code, and result. Any non-zero exit blocks delivery.
-- Do not reuse a test report whose `change_id` or pre-change HEAD belongs to a
-  different change as final evidence.
-
-**3.3 Release commit**:
-```bash
-git add -A
-git commit -m "chore(release): v<X.Y.Z>"
-```
-Verify with `git log -1 --oneline`.
-
-**3.4 Recompile context and converge the change** (skip only for initial baseline):
-
-For `active` or `blocked`, call `change.context` after the release commit so its
-git head and task set are current. Then call `change.converge` with the exact
-evidence required by kind:
-
-- `quick`: diff, tests, spec;
-- `standard` / `major`: diff, tests, spec, docs, review;
-- `incident`: diagnosis, diff, tests. The diagnosis evidence must point to the
-  completed `diagnosis.md`; convergence separately validates all five required
-  debugging sections and cannot be satisfied by the evidence string alone.
-
-Evidence must name concrete commands, artifacts, or file paths. If blockers are
-returned, stop before tag/push and route to the owning workflow. Do not weaken
-the change kind or mark failed evidence `not_applicable` merely to pass.
-
-**3.5 Archive after baseline reconciliation**:
-
-Call `change.archive` with the summary and either `baseline_updates` or the
-explicit no-change reason. This moves the packet from `changes/active` to the
-dated archive and records closure in state.db. Archive failure blocks release.
-
-**3.6 Git tag**:
-```bash
-git tag v<X.Y.Z>
-```
-Verify with `git tag -l v<X.Y.Z>`.
-
-**3.7 Push to remote**:
-```bash
-git push origin main     # release commit
-git push origin v<X.Y.Z> # version tag
-```
-Verify with `git ls-remote --tags origin | grep v<X.Y.Z>`.
-
-**Release checklist**:
-- [ ] Version determined and displayed
-- [ ] Version file updated and verified
-- [ ] Release commit created and verified
-- [ ] Change context current, convergence ready, baseline reconciled, archive complete
-- [ ] Git tag created and verified
-- [ ] Commit and tag pushed and verified on remote
-
-Any failure → stop immediately; do NOT continue; surface last-step error.
-
-### Step 4 — Persist `.ultra/delivery-report.json`
-
-```jsonc
-{
-  "timestamp": "<ISO8601>",
-  "version": "<X.Y.Z>",
-  "git_tag": "v<X.Y.Z>",
-  "git_commit": "<HEAD SHA>",
-  "change_id": "<archived-change-id-or-null>",
-  "change_archive_path": "<path-or-null>",
-  "convergence_ready": true,
-  "baseline_updates": ["<project-relative-path>"],
-  "changelog_updated": true,
-  "technical_debt_refreshed": true,
-  "build_success": true,
-  "pushed": true
-}
-```
-
-### Step 5 — Report
-
-Print a tight release summary: change id/archive, baseline files reconciled,
-tag, commit, exact verification commands, outstanding technical-debt count,
-and next suggested action. After release, daily work starts with `/ultra-change`.
-
-## Deliverables Checklist (final)
-
-- [ ] `/ultra-test` passed (verified via test-report.json)
-- [ ] Uncommitted changes handled
-- [ ] CHANGELOG + technical-debt refreshed (README if API changed)
-- [ ] Production build exit 0
-- [ ] Continuous change converged and archived (when present)
-- [ ] Version bumped, tagged, pushed
-- [ ] delivery-report.json written
-
-## MCP → CLI fallback matrix
-
-| Purpose | MCP tool | CLI fallback |
-|---------|----------|--------------|
-| Resolve dirty-tree action | none | current Host's native user-interaction surface |
-| Override version bump | none | current Host's native user-interaction surface |
-| Resolve/bind change | `change.list` / `change.get` | none; fail closed |
-| Refresh context | `change.context` | none; fail closed |
-| Deterministic closure | `change.converge` / `change.archive` | none; fail closed |
-
-## What this skill DOES NOT do
-
-- Does NOT replace `/ultra-test`; it re-runs the exact release evidence after
-  documentation and version changes so the shipped commit is verified
-- Does NOT publish to npm / crates.io / PyPI (Phase 9 handles distribution)
-- Does NOT directly mutate state.db or external provider state
-
-## Integration
-
-| | |
-|---|---|
-| **Input** | bound change (if any), test/review artifacts, current repo |
-| **Output** | archived change, reconciled baseline, delivery report, git tag + remote push |
-| **Next** | deploy/announce; next daily change begins with `/ultra-change` |
+Call `change.get` for authoritative `learning_candidates`; use the packet's
+`spec-learning.json` only as the inspectable projection.
+
+- `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.
+
+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.
+
+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.
+
+## 3. Verify the release candidate
+
+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 exact project commands for:
+
+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.
+
+Record commands, exit results, and current HEAD. Any post-test edit invalidates the
+test and review gates.
+
+## 4. Compile final role context
+
+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`.
+
+## 5. Converge
+
+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;
+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.
+
+## Completion gate
+
+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.