ultra-builder-pro-cli 0.25.1 → 0.26.0

package/package.json

@@ -1,21 +1,14 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.25.1",
-  "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build, with a project-local MCP persistence and safety kernel.",
+  "version": "0.26.0",
+  "description": "File-first Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
-    "ubp": "bin/install.js",
-    "ubp-orchestrator": "bin/orchestrator.js",
-    "ultra-tools": "ultra-tools/cli.cjs"
+    "ubp": "bin/install.js"
   },
   "files": [
     "bin",
     "adapters",
-    "ultra-tools",
-    "mcp-server",
-    "orchestrator",
-    "commands",
-    "agents",
     "skills/ultra-init",
     "skills/ultra-research",
     "skills/ultra-plan",
@@ -26,47 +19,30 @@
     "skills/ultra-status",
     "skills/ultra-think",
     "skills/ultra-change",
-    "skills/ultra-doctor",
-    "skills/code-review-expert",
-    "skills/security-rules",
-    "skills/integration-rules",
-    "skills/testing-rules",
-    "skills/cc-collab",
-    "skills/codex-collab",
-    "skills/ultra-verify",
+    "skills/ultra-delegate",
+    "skills/ultra-grilling",
+    "skills/ultra-domain-modeling",
+    "skills/ultra-tdd",
+    "hooks/_common.py",
     "hooks/*.py",
     "hooks/adapters/*.py",
     "hooks/README.md",
-    "spec/mcp-tools.yaml",
-    "spec/cli-protocol.md",
-    "spec/schemas",
     "LICENSE",
     "CHANGELOG.md",
-    "settings.json",
     ".ultra-template",
-    "docs/ROADMAP.md",
+    "docs/PHILOSOPHY.md",
     "docs/ARCHITECTURE.md",
     "docs/ARTIFACT-AUTHORITY.md",
     "docs/WORKFLOW-LIFECYCLE.md",
-    "docs/LEGACY-CLI-CROSSWALK.md",
-    "docs/AGENT-CONTEXT.md",
     "docs/SKILL-AUTHORING.md",
-    "docs/COMMIT-HASH-BACKFILL.md",
     "docs/DECISIONS.md",
-    "docs/STATE-DB-ACCESS-POLICY.md",
     "docs/PLUGIN-ISOLATION-CONTRACT.md",
     "docs/RUNTIME-COMPAT-MATRIX.md",
-    "!**/__pycache__/**",
     "!**/*.pyc",
     "!**/*.pyo",
     "!**/*.test.cjs",
     "!**/tests/**",
-    "!mcp-server/test-support/**",
-    "!mcp-server/lib/workflow-state.cjs",
-    "!mcp-server/lib/decision-dialogue.cjs",
-    "!mcp-server/lib/context-spine.cjs",
-    "!mcp-server/lib/project-breadcrumb.cjs",
-    "!mcp-server/lib/spec-learning.cjs"
+    "!**/__pycache__/**"
   ],
   "keywords": [
     "claude-code",
@@ -78,7 +54,7 @@
     "cli",
     "multi-runtime",
     "ultra-builder-pro",
-    "mcp",
+    "file-first",
     "meta-prompting",
     "context-engineering"
   ],
@@ -97,28 +73,17 @@
   },
   "scripts": {
     "test": "npm run test:all",
-    "test:state": "node --test 'mcp-server/**/*.test.cjs'",
-    "test:orch": "node --test 'orchestrator/**/*.test.cjs'",
-    "test:spec": "node spec/scripts/test-all.cjs",
-    "test:rest": "node --test adapters/_shared/tests/*.test.cjs adapters/tests/*.test.cjs ultra-tools/*.test.cjs tests/conformance/**/*.test.cjs tests/*.test.cjs",
-    "test:all": "npm run test:state && npm run test:orch && npm run test:spec && npm run test:rest",
+    "test:node": "node --test adapters/_shared/tests/*.test.cjs tests/*.test.cjs",
+    "test:all": "npm run test:node && npm run test:hooks",
     "test:hooks": "pytest hooks/tests -q",
-    "verify:release": "npm run test:all && npm run test:hooks && npm audit --omit=dev --audit-level=high",
+    "verify:release": "npm run test:all && npm audit --omit=dev --audit-level=high",
     "prepublishOnly": "npm run verify:release",
     "install:claude": "node bin/install.js --claude --local",
-    "install:kimi": "node bin/install.js --kimi --local",
-    "install:grok": "node bin/install.js --grok --local",
-    "install:all": "node bin/install.js --all --local"
+    "install:kimi": "node bin/install.js --kimi --global",
+    "install:grok": "node bin/install.js --grok --global",
+    "install:all": "node bin/install.js --all --global"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0-beta.5",
-    "@vercel/ncc": "0.38.4",
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "better-sqlite3": "^11.5.0",
     "js-yaml": "^4.1.0"
-  },
-  "devDependencies": {
-    "@modelcontextprotocol/client": "2.0.0-beta.5"
   }
 }

package/skills/ultra-change/SKILL.md

@@ -1,54 +1,101 @@
 ---
 name: ultra-change
-description: Capture or revise one bounded feature, fix, redesign, or incident contract against a ready Ultra baseline. Use when post-baseline work needs accepted intent before research, planning, or implementation.
+description: Open one bounded unit of work by first reconciling what the specifications promise against what the code actually does, then writing the intent that closes the gap. Use when nothing is in flight and something new is being asked for — a feature, a fix, a redesign, or an incident response.
 ---
 
-# Capture accepted Change intent
-
-A Change is the durable unit connecting research, plan, implementation, verification,
-review, documentation, and delivery. Its draft stays editable until a semantic
-checkpoint accepts the downstream authority.
-
-## Inspect and align
-
-1. Call `ultra.context { stage: project, detail: full }`.
-2. Inspect or import the team checkpoint with `ultra.sync`. Stop only on a real
-   baseline, Change, task, ancestry, or active-session conflict.
-3. Reuse an existing matching Change. Do not duplicate authority.
-4. Convert the request into observable outcome, executable acceptance, non-goals,
-   public seams, recovery, verification, documentation impact, risk, and research
-   disposition.
-5. Recommend `quick`, `standard`, `major`, or `incident` from evidence, or record a
-   clearer bounded repository-specific kind when those profiles lose meaning. These
-   are model-owned labels, not SQLite enums. Ask only when
-   a choice changes accepted product intent, compatibility, security, material cost,
-   external effects, or recovery.
-
-Read `../ultra-think/references/interaction-boundary.md` before asking. MCP may report
-contradictory risk fields, but the model and owner choose the semantic correction.
-
-## Record the contract
-
-Use one `ultra.record` batch with `change_contract / open` or
-`change_contract / revise`, relevant `decision / accept`, and `artifact / bind` for
-an already-known typed delta. Every entry carries a stable idempotency key. Read the
-result through `ultra.context`.
-
-Keep every Change-owned semantic artifact below
-`.ultra/changes/active/<change-id>/`. Standard and major Changes require a typed delta
-before planning. A true no-semantic-change case records an explicit reason instead of
-manufacturing a mutation.
-
-Changing accepted intent creates a new accepted checkpoint revision and makes only
-genuinely dependent evidence stale. Readiness is derived, not a stored absorbing
-state. Semantic diagnostics remain advisory; structural, digest, path, or concurrency
-conflicts require repair and retry of the same draft.
-Use `change_contract / cancel` only when the owner intentionally abandons the Change.
-An archived or cancelled Change remains immutable history. When new evidence requires
-continued work, use `change_contract / supersede` to create one linked active successor;
-never patch SQLite, reopen the historical row, or duplicate the relationship manually.
-
-Publish the durable Change contract with `ultra.sync { action: publish }` when it is a
-useful team handoff. Recommend bounded `ultra-research` for a real evidence gap or
-`ultra-plan` when the contract is sufficiently evidenced. Do not invoke the next
-capability automatically.
+# Reconcile first, then write down what this Change commits to
+
+A Change is the durable unit connecting research, plan, implementation,
+verification, review and delivery. Reconciliation comes first because writing new
+intent on top of specifications that already disagree with the code buries the
+disagreement instead of resolving it.
+
+## Before you start
+
+1. Read `.ultra/tasks.json`, and the `context_file` of any task not yet finished.
+2. Read `CONTEXT.md` for vocabulary and `.ultra/decisions/` for entries in scope.
+3. Read `.ultra/north-star.md` — a Change that does not serve it is worth
+   questioning out loud before it is written down.
+
+## Whether this skill applies at all
+
+| Situation | Where it goes |
+|---|---|
+| No pending or in-progress task, and something new is asked for | Here |
+| A task is in progress and the specification turns out not to match reality | Not here — the dual-write path inside `ultra-dev` |
+| The change makes no sentence in the specifications false | Neither — just make the change |
+
+That third row is the checkable answer to "how small is too small to deserve a
+Change file": if nothing the specifications say becomes untrue, there is nothing
+to reconcile and nothing to record.
+
+## Definition of done
+
+- `.ultra/changes/active/<id>/intent.md` states the observable outcome, the
+  executable acceptance, the non-goals, and the public seams touched.
+- Each of the three reconciliation buckets is either empty or dispositioned, with
+  the owner's answer recorded for every bucket that was not empty.
+- The draft stays editable until then; the owner's acceptance is what turns it
+  into authority.
+
+## Reconcile against a bounded scope
+
+A whole-repository diff is unusable, so derive the scope with four steps anyone
+can rerun:
+
+1. Decide which specification sections this request touches.
+2. For each section, collect the past tasks whose `trace_to` points at it, and
+   from those the set of code files they changed.
+3. `git log -- .ultra/specs/<file>` gives the commit where that specification
+   last changed.
+4. `git diff <that commit>..HEAD -- <those code files>` is the reconciliation
+   scope.
+
+Sort what you find into three buckets, each with your recommended disposition:
+
+| Bucket | Meaning |
+|---|---|
+| Specification says it, code does not implement it | Promised and missing |
+| Code implements it, no specification says so | Built and unpromised |
+| Both speak and they conflict | Contradictory |
+
+Take the buckets to the owner. This is confirmed rather than assumed, because a
+disposition can quietly be a REDUCTION.
+
+## Write the intent
+
+Read `references/change-contract.md` and use its exact `intent.md` headings. The active
+Change directory contains only this accepted contract until planning or delivery adds
+its defined artifacts; do not invent a parallel semantic record.
+
+Follow `../ultra-grilling/SKILL.md` to settle the boundary — one question at a
+time, each with your recommendation. New domain terms go through
+`../ultra-domain-modeling/SKILL.md`.
+
+When the work is too large *and* the path itself is unclear, follow
+`../ultra-think/SKILL.md` for a decision ticket instead of forcing a task
+breakdown. What comes out is a question whose answer is a decision, not an
+implementation slice.
+
+When reconciliation proves the request is a directly executable one-slice correction,
+follow `../ultra-tdd/SKILL.md` at the confirmed public seam instead of manufacturing a
+task graph merely to satisfy ceremony.
+
+Output is `.ultra/changes/active/<id>/intent.md`, the specification patches
+reconciliation justified, possibly a `.ultra/decisions/<id>.md`, and any
+vocabulary update. Recommend `ultra-research` for a real evidence gap or
+`ultra-plan` once the contract is evidenced enough; do not invoke either.
+
+## When the owner decides
+
+Every non-empty bucket, the Change boundary, and anything reconciliation turns up
+that shrinks a prior commitment. A change that makes no specification sentence
+false needs no permission at all.
+
+## References
+
+- `../ultra-grilling/SKILL.md` — the loop for settling the boundary.
+- `references/change-contract.md` — exact `intent.md` structure and profile fields.
+- `../ultra-think/references/autonomy-boundary.md` — read before dispositioning a
+  bucket in a way that removes something already promised.
+- `../ultra-tdd/SKILL.md` — read for an evidenced one-slice correction.

package/skills/ultra-change/references/change-contract.md

@@ -3,7 +3,46 @@
 Create one contract before planning. Keep every field specific enough to verify and
 stable enough to survive a fresh session.
 
-## Contract
+## Exact `intent.md` structure
+
+```markdown
+# Change <id>: <title>
+
+> **Status**: draft | accepted
+> **Profile**: quick | standard | major | incident
+
+## Outcome
+<one externally observable result>
+
+## Acceptance
+| ID | Criterion | Verification | Trace |
+|---|---|---|---|
+
+## Non-goals
+- <explicit boundary>
+
+## Public Seams
+- <entry point or output>
+
+## Reconciliation
+### Promised and Missing
+### Built and Unpromised
+### Contradictory
+
+## Planning Posture
+<EXPAND | SELECTIVE | HOLD | REDUCE, rationale, and owner confirmation>
+
+## Recovery
+<reversal or recovery path and its verification>
+
+## Unresolved Decisions
+- <stable id, summary, blocking state, owner>
+```
+
+Use `[NEEDS CLARIFICATION]` for missing semantic content. Do not silently omit a
+heading, and do not add another file that restates the same contract.
+
+## Contract fields
 
 - `outcome`: one externally observable result.
 - `acceptance`: stable ids with a criterion and exact verification for each accepted

package/skills/ultra-delegate/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ultra-delegate
+description: Delegate one bounded workflow segment to another installed CLI in an isolated worktree and return only its stable result artifact. Use when the owner asks for another model or host to execute, review, verify, or continue a specific slice of current work.
+---
+
+# Run a bounded worker without giving it project authority
+
+Delegation is an execution mode, not another workflow stage. The primary host keeps
+semantic synthesis and remains the only writer of `.ultra/tasks.json`.
+
+## Before you start
+
+1. Read `.ultra/tasks.json`, the delegated task's `context_file` and `## Resume Note`.
+2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, acceptance and current evidence.
+3. Define one bounded instruction, permission set, clean Git worktree and result.
+4. Read `references/delegation-contract.md` before writing either JSON artifact.
+
+## Definition of done
+
+- The worktree is a clean registered Git worktree; instruction, permission and worker
+  spec digests remain unchanged.
+- The worker terminates as `finished`, `blocked` or `failed` in a schema-valid
+  `result.json`; declared paths equal the actual Git diff and stay in writable roots.
+- Timeout and cancellation reach a terminal failed result and release `run.lock`.
+- The primary host verifies the result against the delegated workflow's acceptance.
+
+## Prepare and run
+
+Write under `.ultra/.runtime/delegations/<id>/`:
+
+- `instruction.md`: bounded goal, sources, acceptance and forbidden effects;
+- `permission.json`: the exact file-local boundary in the contract reference;
+- `result.json`: launcher-published terminal artifact only.
+
+`writable_roots` is an array of existing worktree-relative directories. An empty array
+selects native read-only mode; one or more roots selects bounded write mode.
+`external_effects` must be empty in this portable launcher: commit, push, publish,
+deployment and other effects stay with the primary host. There is no `readable_roots`
+claim because the five host sandboxes do not share one mechanically enforceable read
+policy.
+
+Create `.ultra/.runtime/worktrees/<id>` as a real Git worktree and run:
+
+```text
+ubp delegate run --to <host> --instruction <file> --permission <file> --worktree <dir> --timeout <seconds>
+```
+
+The command returns a receipt. Immediately run `scripts/delegate_wait.py`; read no
+intermediate output. Use `ubp delegate status --delegation <dir>` for a read-only state
+and `ubp delegate cancel --delegation <dir>` to request termination. Never delete a lock
+to manufacture completion.
+
+The worker returns one schema-constrained JSON final response. The launcher extracts it
+from the host's native structured output, validates digests, process exit, exact schema,
+actual base-HEAD diff and writable roots, then atomically publishes `result.json`. The
+model never writes its own receipt. If owner input is needed, the worker terminates
+`blocked` with questions and evidence; start a new id and fresh packet after obtaining
+the answer.
+
+After `finished`, inspect the isolated diff, rerun acceptance checks, and integrate via
+the repository's normal Git workflow with ordinary authorization. Delegation never
+auto-merges or writes canonical task/evidence files.
+
+## Synthesize multiple results
+
+Three agreeing results are Consensus. Two of three are Majority and require examining
+the dissent. Three different results are No Consensus: narrow the question or add
+evidence. A failed external CLI does not block the underlying workflow; report the
+missing evidence rather than turning a vote or score into truth.
+
+## When the owner decides
+
+The owner authorizes delegation. External effects cannot be delegated by this launcher;
+the primary host obtains their separate authorization. The primary host owns result
+interpretation, risk acceptance, integration and task state.
+
+## References
+
+- `references/delegation-contract.md` — strict permission, receipt and result schemas.
+- `scripts/delegate_wait.py` — run immediately after the launch receipt.
+- `../ultra-think/SKILL.md` — read when No Consensus exposes a consequential decision.
+- `../ultra-think/references/autonomy-boundary.md` — read before granting write effects.

package/skills/ultra-delegate/references/delegation-contract.md

@@ -0,0 +1,51 @@
+# Delegation artifact contract
+
+## Permission
+
+```json
+{
+  "$schema": "ultra-delegation-permission-v1",
+  "writable_roots": ["src", "test"],
+  "external_effects": []
+}
+```
+
+Fields are exact. Roots are normalized worktree-relative directories that already
+exist. An empty array selects native read-only mode; `.` deliberately grants the whole
+isolated checkout. Absolute paths, symlink escapes, unknown fields, `readable_roots`,
+and non-empty external effects are rejected.
+
+## Model final response
+
+```json
+{
+  "$schema": "ultra-delegation-result-v1",
+  "status": "finished",
+  "summary": "Implemented the bounded slice.",
+  "changed_files": ["src/example.ts"],
+  "checks": [
+    {"command": "npm test -- example", "status": "passed", "output_ref": "stdout.log"}
+  ],
+  "evidence": ["src/example.ts"],
+  "questions": [],
+  "residual_risks": []
+}
+```
+
+Fields are exact. Status is `finished`, `blocked`, or `failed`; `blocked` requires a
+question. Check status is `passed`, `failed`, or `not_run`. Changed files are unique,
+normalized repository-relative paths and must exactly equal the launcher's Git diff.
+
+The launcher extracts this object from native structured output and adds
+`delegation_id`, `host`, instruction, permission, and output-schema digests,
+`read_only`, `base_head`, `final_head`, timestamps, `exit_code`, and signal. Launcher
+failures also add `failure_type`. A nonzero process cannot publish `finished`.
+
+## Recovery
+
+- `status` distinguishes running, cancelling, stalled, and terminal artifacts.
+- `cancel` writes `cancel.request`; the worker terminates its host process, publishes a
+  failed result with `failure_type: cancelled`, and removes `run.lock`.
+- `--timeout` does the same with `failure_type: timeout`.
+- A stopped worker with no result is recoverable through `cancel`, which finalizes the
+  stale run. Retry under a new delegation id and fresh digests.

package/skills/ultra-delegate/scripts/delegate_wait.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Wait for one delegated result to become non-empty and stable."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import time
+from pathlib import Path
+
+
+RESULT_SCHEMA = "ultra-delegation-result-v1"
+STATUSES = {"finished", "blocked", "failed"}
+CHECK_STATUSES = {"passed", "failed", "not_run"}
+
+
+def nonempty(value) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def validate_result(payload: dict) -> None:
+    if not isinstance(payload, dict):
+        raise ValueError("result must be a JSON object")
+    if payload.get("$schema") != RESULT_SCHEMA:
+        raise ValueError(f"result $schema must be {RESULT_SCHEMA}")
+    if payload.get("status") not in STATUSES:
+        raise ValueError("result status must be finished, blocked, or failed")
+    if not nonempty(payload.get("summary")):
+        raise ValueError("result summary must be non-empty")
+    for field in ("changed_files", "checks", "evidence", "questions", "residual_risks"):
+        if not isinstance(payload.get(field), list):
+            raise ValueError(f"result {field} must be an array")
+    for field in ("changed_files", "evidence", "questions", "residual_risks"):
+        if not all(nonempty(item) for item in payload[field]):
+            raise ValueError(f"result {field} must contain non-empty strings")
+    for check in payload["checks"]:
+        if not isinstance(check, dict) or not nonempty(check.get("command")):
+            raise ValueError("result checks require a command")
+        if check.get("status") not in CHECK_STATUSES:
+            raise ValueError("result check status is invalid")
+    if payload["status"] == "blocked" and not payload["questions"]:
+        raise ValueError("blocked result requires a question")
+    for field in ("delegation_id", "host", "base_head", "final_head", "started_at", "finished_at"):
+        if not nonempty(payload.get(field)):
+            raise ValueError(f"result {field} must be non-empty")
+    for field in ("instruction_digest", "permission_digest", "output_schema_digest"):
+        if not isinstance(payload.get(field), str) or not re.fullmatch(r"[0-9a-f]{64}", payload[field]):
+            raise ValueError(f"result {field} must be a SHA-256 digest")
+    if not isinstance(payload.get("read_only"), bool):
+        raise ValueError("result read_only must be a boolean")
+    if payload.get("exit_code") is not None and not isinstance(payload["exit_code"], int):
+        raise ValueError("result exit_code must be an integer or null")
+
+
+def wait_for_result(path: Path, interval: float, timeout: float) -> dict:
+    deadline = time.monotonic() + timeout
+    previous_size = -1
+    stable_reads = 0
+    while time.monotonic() < deadline:
+        size = path.stat().st_size if path.exists() else 0
+        if size > 0 and size == previous_size:
+            stable_reads += 1
+            if stable_reads >= 1:
+                payload = json.loads(path.read_text(encoding="utf-8"))
+                validate_result(payload)
+                return payload
+        else:
+            stable_reads = 0
+        previous_size = size
+        time.sleep(interval)
+    raise TimeoutError(f"result did not stabilize within {timeout:g}s: {path}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("result", type=Path)
+    parser.add_argument("--interval", type=float, default=1.0)
+    parser.add_argument("--timeout", type=float, default=1800.0)
+    args = parser.parse_args()
+    print(json.dumps(wait_for_result(args.result, args.interval, args.timeout)))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())