ultra-builder-pro-cli 0.5.0

package/docs/ROADMAP.md

@@ -0,0 +1,102 @@
+# ultra-builder-pro-cli — Roadmap
+
+> **Authoritative roadmap**: [`PLAN.zh-CN.md`](./PLAN.zh-CN.md) (v0.3.1).
+> This file is a one-page summary; details, decisions, and time estimates
+> live in PLAN. If they disagree, PLAN wins.
+
+**Goal**: distribute the Ultra Builder Pro engineering loop as native Claude
+Code, OpenCode, and Codex plugins, retain a Gemini compatibility extension, and
+run the loop with isolated sessions sharing one authoritative workflow store.
+
+**First-class runtimes**: Claude Code · OpenCode · Codex.
+
+**Distribution channels (v1.0)**: npm · Homebrew · pip.
+
+**Confidence**: 86% (PLAN §10).
+
+**Timeline**: 14–18 weeks AI-assisted (PLAN §11).
+
+---
+
+## Milestones
+
+| Release | Week | Contents                                                                  |
+|---------|-----:|---------------------------------------------------------------------------|
+| **v0.1**| 8    | Rule layer + execution-lite (session isolation + admission + event subscribe + active-session visibility) — solves the core "independent conversations don't pollute each other" pain |
+| **v0.2**| 11   | Auto-recovery + monitoring + real-time code-review-graph + full conformance |
+| **v0.3**| 16   | PRD → execution-plan artifact → parallel dispatch / merge — coding factory |
+| **v1.0**| 17–18| Three-channel publish (npm + Homebrew + pip)                              |
+
+## Phase status
+
+| Phase | Title                                          | Status        |
+|-------|------------------------------------------------|---------------|
+| 0     | Skeleton                                       | ✅ done (`da69a7a`) |
+| 1     | Three-layer interface contracts (`spec/`)      | ✅ done (D38) |
+| 2     | Authoritative state — SQLite + WAL             | ✅ done (D39, `e286e41`) |
+| 3     | Command thin-shells (skill + MCP + CLI)        | ✅ done (D40, `b3d1797`) |
+| 4     | Cross-runtime distribution + 4.6a smoke flow   | ✅ done (D41, `5aa1fd0`) |
+| 4.5   | Execution-lite (session + admission + events)  | ✅ done (D42, `0d3e5ed`) — **v0.1 ready** |
+| 5     | Recovery + staleness + auto-routing            | ✅ done (D43) → v0.2 |
+| 6     | Monitoring + code-review-graph live watcher    | ✅ done (D44) → v0.2 |
+| 4.6b  | Full conformance suite                         | ✅ done (D45) — 20 conformance + 21 resolveTarget tests |
+| 7     | tagged tasks + skill mining; retired Ultra memory handed to cloud-mem/claude-mem | ✅ superseded by D50 boundary cleanup |
+| 8A    | Plan automation (parse / topo / expand + artifact + human gate) | ✅ done (D47, `a932cb8`) → v0.3 |
+| 8B    | Execution automation (dispatch / parallel worktree / merge) | ✅ done (D48, `8224159`) — **v0.3 ready** |
+| 9     | Release pipeline (npm / Homebrew / pip)        | pending → v1.0 |
+
+## What is in the repo today
+
+```
+spec/                       ← Phase 1 single source of truth
+├── mcp-tools.yaml          (30 declared tools across 7 families; 21 live)
+├── cli-protocol.md         (CLI ↔ MCP mapping table)
+├── schemas/                (state-db.sql + 4 JSON schemas)
+├── fixtures/{valid,invalid}/  (+ v4.4-project for migration)
+└── scripts/test-all.cjs    (npm run test:spec — 5 validators)
+
+mcp-server/                 ← Phase 2 authoritative state layer
+├── server.cjs              (stdio MCP server, 21 task/session/plan tools)
+├── lib/
+│   ├── state-db.cjs        (SQLite + WAL + pragmas)
+│   ├── state-ops.cjs       (full write API, status state machine)
+│   └── projector.cjs       (state.db → tasks.json + context md)
+└── tests/                  (npm run test:state — 44 tests)
+
+ultra-tools/                ← CLI fallback, migration, and diagnostics
+├── cli.cjs
+└── commands/
+    ├── db.cjs              (init/checkpoint/vacuum/integrity/backup)
+    ├── migrate.cjs         (v4.4 → v4.5 + dry/rollback)
+    └── legacy-memory.cjs   (explicit inspect/archive/confirmed prune)
+
+bin/install.js              ← multi-runtime installer
+bin/handbook.js             ← explicit managed user-handbook sync
+adapters/                   ← native Claude/OpenCode/Codex plugin builders + Gemini compatibility
+skills/                     ← allowlisted Ultra workflows, internal rules, and collab companions
+hooks/                      ← 7 workflow-only Python hooks; OpenCode uses native JavaScript hooks
+docs/
+├── PLAN.zh-CN.md                authoritative plan (1670+ lines)
+├── ARCHITECTURE.md              Phase 1 single-page entry point
+├── AGENT-CONTEXT.md             Phase 3 canonical runtime context contract
+├── USER-HANDBOOK-CONTRACT.md    managed CLAUDE.md / AGENTS.md boundary
+├── RUNTIME-COMPAT-MATRIX.md     Phase 4 runtime capability matrix
+├── STATE-DB-ACCESS-POLICY.md    Phase 2 multi-process write contract
+├── COMMIT-HASH-BACKFILL.md      Phase 2.8 two-commit completion flow
+└── ROADMAP.md                   this file
+```
+
+## How to verify
+
+```
+npm install
+npm run test:all
+python3 -m pytest hooks/tests -q
+npm audit
+```
+
+## Out of scope for v1.0 (deferred)
+
+PLAN §13 lists Copilot / Cursor / Windsurf / 7 more runtimes, web
+dashboard / TUI, LLM provider abstraction, team-collab server, plugin
+marketplace.

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -0,0 +1,98 @@
+# Runtime Compatibility Matrix
+
+Current presentation contract for Ultra Builder Pro. Claude Code, OpenCode, and
+Codex are first-class native plugins; Gemini CLI remains a compatibility
+extension. The canonical asset boundary lives in
+`adapters/_shared/runtime-assets.cjs`.
+
+Legend: **FULL** = native host surface, **DEGRADED** = compatible but missing an
+equivalent lifecycle/control surface, **N/A** = intentionally not installed.
+
+## 1. Plugin and workflow surface
+
+| Capability | Claude Code | OpenCode | Codex | Gemini CLI |
+|---|---|---|---|---|
+| Package form | `.claude-plugin` native plugin | native config bundle + JS plugin | personal `.codex-plugin` | compatibility extension |
+| Public entry | `/ultra-*`, `/learn` | `/ultra-*`, `/learn` | `$ultra-builder-pro:<skill>` | generated command TOML |
+| Public Ultra workflows | 10 | 10 | 10 | 10 |
+| Internal agent-rule skills | 4, non-user-facing | 4, non-user-facing | 4 with implicit invocation disabled | 4 prompt dependencies |
+| Collaboration companions | `codex-collab`, `gemini-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `gemini-collab`, `ultra-verify` | `cc-collab`, `gemini-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` |
+| External browser/deploy/framework skills | N/A | N/A | N/A | N/A |
+
+Codex does not emulate deprecated custom slash prompts. Its adapter converts
+the workflows into namespaced skills and records nine legacy command mappings
+in `command-map.json`; `ultra-review` is directly invocable as a skill.
+
+## 2. Agents and collaboration
+
+| Capability | Claude Code | OpenCode | Codex | Gemini CLI |
+|---|---|---|---|---|
+| Bundled review/debug agents | FULL, native Markdown agents | FULL, lowercased native agent frontmatter | FULL, nine managed TOML custom agents | N/A |
+| Native bounded delegation | `Task`/agent surface | native agent surface | native Codex subagents | evolving host surface, not packaged |
+| Cross-host advisor | explicit collab skill; read-only | explicit collab skill; read-only | explicit collab skill; read-only | explicit collab skill; read-only |
+| Primary-agent ownership | FULL | FULL | FULL | FULL |
+
+No bundled agent declares private persistent memory. It receives current
+checkout evidence and bounded context from the primary host, then returns a
+result for primary verification.
+
+## 3. Workflow hooks
+
+| Lifecycle | Claude Code | OpenCode | Codex | Gemini CLI |
+|---|---|---|---|---|
+| Session context/health | FULL, native `SessionStart` | FULL, system transform + event refresh | FULL, native `SessionStart` | N/A |
+| Active edit boundary | FULL, `PreToolUse Edit|Write` | DEGRADED, tool lifecycle can refresh but not inject a native pre-edit message | FULL, `PreToolUse Edit|Write` | N/A |
+| Compaction recovery | FULL, `PreCompact` + compact resume matcher | FULL, native compacting context | FULL, `PreCompact` + `PostCompact` | N/A |
+| Incomplete-stop gate | FULL, native blocking `Stop` hook | DEGRADED, no equivalent blocking stop hook | FULL, native blocking `Stop` hook | N/A |
+| Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | N/A |
+
+All reachable hooks are workflow-only and no-op without an active non-terminal
+`.ultra/workflow-state.json`. No runtime receives Ultra prompt capture,
+transcript capture, observation journal, session-summary memory, generic command
+blocking, or generic post-edit policy.
+
+## 4. MCP and state
+
+| Capability | Claude Code | OpenCode | Codex | Gemini CLI |
+|---|---|---|---|---|
+| stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | extension manifest |
+| Live contracts | 21 | 21 | 21 | 21 |
+| Declared upstream contracts | 30 | 30 | 30 | 30 |
+| Nine non-live contracts | host-native review/discovery/ask surfaces | host-native review/discovery/ask surfaces | explicit `codex-capability-map.json` | compatibility guidance |
+| Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` | project workflow state when invoked from the project |
+| Ultra memory API | N/A | N/A | N/A | N/A |
+
+The seven declared tool families are `task`, `session`, `plan`, `review`,
+`impact`, `skill`, and `ask`. Only the 21 `task.*`, `session.*`, and `plan.*`
+operations registered by `mcp-server/server.cjs` are advertised as live.
+
+## 5. User handbook presentation
+
+| Capability | Claude Code | OpenCode | Codex | Gemini CLI |
+|---|---|---|---|---|
+| Durable user file | `~/.claude/CLAUDE.md` | `~/.config/opencode/AGENTS.md` | `~/.codex/AGENTS.md` | extension `GEMINI.md` context |
+| Automatic overwrite by plugin install | no | no | no | extension-owned context only |
+| Explicit managed-block sync | `ubp-handbook --runtime claude` | `ubp-handbook --runtime opencode` | `ubp-handbook --runtime codex` | N/A |
+| Backup before change | FULL | FULL | FULL | N/A |
+
+## 6. Install, update, and uninstall
+
+| Capability | Claude Code | OpenCode | Codex | Gemini CLI |
+|---|---|---|---|---|
+| Adapter install | FULL | FULL | FULL | FULL compatibility |
+| Native registration/update | host loads plugin directory on next session | host loads local JS plugin on restart | cachebuster + `codex plugin add`; start a new task | host loads extension |
+| Removes stale managed assets | FULL | FULL | FULL | FULL while preserving extension runtime state |
+| Preserves unrelated user config | FULL | FULL | FULL | FULL inside user config; extension directory is managed |
+| Uninstall ownership guard | managed plugin root | sentinels + owned MCP entry | managed root/manifest/agent headers | extension `_ubp.source` |
+
+## 7. Verification sources
+
+- `adapters/tests/*.test.cjs` verifies each installer and native manifest.
+- `tests/conformance/<runtime>/*.test.cjs` verifies command/skill, hook, MCP,
+  idempotency, and smoke presentation.
+- `adapters/_shared/tests/runtime-assets.test.cjs` prevents retired or external
+  skills and generic/memory hooks from re-entering any package.
+- `adapters/_shared/tests/handbook.test.cjs` verifies host rendering, safe
+  legacy-section migration, backup, and idempotency.
+
+Any capability claim elsewhere must match current adapter code and these tests.

package/docs/STATE-DB-ACCESS-POLICY.md

@@ -0,0 +1,109 @@
+# `.ultra/state.db` access policy
+
+> Phase 2.2 contract. Trace: PLAN §6 Phase 2.2, decisions D18 / D32 / D37,
+> risks R21 / R25.
+
+`.ultra/state.db` is the only authoritative state store for tasks,
+events, sessions, telemetry, and spec references (D18). Every process
+that touches it must follow the rules below; deviations are bugs.
+
+## 1. Three-role write matrix
+
+| Role                       | tasks | events | sessions | telemetry | specs_refs | migration_history |
+|----------------------------|:-----:|:------:|:--------:|:---------:|:----------:|:-----------------:|
+| **MCP server** (single writer for mutables) | RW | RW | RW | RW | RW | RW |
+| **CLI** (`ultra-tools …`)   | R     | RW (append-only) | R | R | R | R |
+| **Orchestrator daemon** (Phase 5+) | R | RW | RW | RW | RW | R |
+
+- **R** = read-only;
+- **RW** = read + write;
+- A `(append-only)` qualifier means the role may execute `INSERT INTO`
+  but never `UPDATE` / `DELETE`.
+
+The CLI may indirectly mutate any table by spawning the MCP server over
+stdio and calling `task.update`, `session.spawn`, etc. — but the actual
+SQLite write is performed by the MCP server's writer connection. The CLI
+never opens a writer connection on `tasks`, `sessions`, `telemetry`,
+`specs_refs`, or `migration_history`.
+
+The append-only carve-out for `events` exists because `events.id INTEGER
+PRIMARY KEY AUTOINCREMENT` makes concurrent inserts collision-free under
+WAL + `busy_timeout`. This lets hooks and short-lived CLI invocations
+record audit events without paying the cost of a full MCP round trip.
+
+## 2. Connection discipline
+
+Every process **must**:
+
+1. Open the database with WAL + `busy_timeout=5000` + `foreign_keys=ON`.
+   Use `mcp-server/lib/state-db.cjs` `openStateDb` so the pragmas are
+   applied uniformly.
+2. Wrap every write in `BEGIN IMMEDIATE` (use the helper `withWrite(db,
+   fn)` once Phase 2.3 lands; until then call `db.transaction(fn)()` and
+   know that better-sqlite3 promotes to IMMEDIATE on the first write).
+3. Retry up to **3 times** on `SQLITE_BUSY`, with exponential backoff
+   starting at 25 ms. Each retry must re-issue the full transaction —
+   never partially commit.
+4. Close the connection in a `finally` block. WAL files (`-wal`,
+   `-shm`) are reclaimed on the last writer's close.
+
+Reads never need explicit transactions; better-sqlite3 reads observe a
+consistent snapshot under WAL.
+
+## 3. WAL fallback
+
+WAL is **unsafe on NFS / SMB / certain Docker bind mounts** (R21). When
+`.ultra/state.db` resides on such a filesystem the orchestrator must
+either:
+
+- refuse to start (preferred — surfaces the deployment problem early), or
+- downgrade to `PRAGMA journal_mode = DELETE` and warn loudly. Concurrent
+  writers fall back to short-burst contention; throughput drops but
+  correctness holds.
+
+Detection happens at boot: `statvfs` of `.ultra/state.db`'s mount;
+`f_type` ∈ `{NFS_SUPER_MAGIC, SMB_SUPER_MAGIC}` ⇒ refuse / downgrade.
+
+## 4. Where each table is owned
+
+| Table              | Writer of record                                      |
+|--------------------|--------------------------------------------------------|
+| `tasks`            | MCP server (`task.create` / `task.update` / `task.delete`) |
+| `events`           | MCP server **and** any process via append-only INSERT  |
+| `sessions`         | MCP server (`session.spawn` / `session.close` / `session.heartbeat`); orchestrator may write status transitions |
+| `telemetry`        | MCP server (collected from tool-call wrappers); orchestrator may dump bulk samples |
+| `specs_refs`       | MCP server (rebuilt on `spec_changed` event); orchestrator may rebuild |
+| `migration_history`| `ultra-tools migrate` CLI only                         |
+| `schema_version`   | `ultra-tools db init` and `ultra-tools migrate` only   |
+
+## 5. Forbidden patterns
+
+- **No file copies for state.** Don't `cp .ultra/state.db
+  somewhere/state.db` and edit; use `ultra-tools db backup`.
+- **No long-held writer connections** outside the MCP server. Pop a
+  short transaction, finish, close.
+- **No `PRAGMA journal_mode` toggling at runtime** by any process other
+  than the orchestrator's boot-time WAL detector.
+- **No raw SQL in command md files.** Commands call MCP tools or
+  `ultra-tools …` subcommands; the SQL lives in `mcp-server/lib`.
+- **No `vacuum` / `wal_checkpoint(TRUNCATE)` from inside a transaction.**
+  Maintenance subcommands open their own connection.
+
+## 6. Maintenance windows
+
+`ultra-tools db checkpoint` and `ultra-tools db vacuum` are safe to run
+while the MCP server is up (they take their own connection and obey the
+busy timeout). `db backup` uses better-sqlite3's online `.backup` API
+and produces a consistent snapshot without blocking writers.
+
+## 7. Verification
+
+The contract on this page is enforced by:
+
+- `mcp-server/tests/concurrency.test.cjs` — three writer threads
+  appending to `events` simultaneously; asserts no `SQLITE_BUSY` escapes
+  the retry loop and the resulting `events.id` sequence has no gaps and
+  no duplicates.
+- Phase 2.3 will add `concurrency-update.test.cjs` — 20 worker threads
+  driving `task.update` against disjoint task ids, verifying serialized
+  writes through the MCP server.

package/docs/USER-HANDBOOK-CONTRACT.md

@@ -0,0 +1,61 @@
+# Ultra Builder Pro — User Handbook Contract
+
+Ultra Builder Pro does not own a user's complete `CLAUDE.md` or `AGENTS.md`.
+Those files contain durable engineering doctrine for the host. The plugin owns
+only one small managed section describing its runtime boundary.
+
+## Source and render targets
+
+`adapters/_shared/handbook.cjs` is the canonical source. It renders the common
+authority, memory, hook, agent, and package boundaries with host-native command
+syntax:
+
+| Runtime | Default target | Main invocation form |
+|---|---|---|
+| Claude Code | `~/.claude/CLAUDE.md` | `/ultra-plan` |
+| Codex | `~/.codex/AGENTS.md` | `$ultra-builder-pro:ultra-plan` |
+| OpenCode | `~/.config/opencode/AGENTS.md` | `/ultra-plan` |
+
+The renderer never copies Claude Code-only APIs into Codex or OpenCode. Each
+host receives only its native invocation and collaboration names.
+
+## Managed-block contract
+
+The owned content is bounded by:
+
+```markdown
+<!-- ultra-builder-pro:handbook:start -->
+...
+<!-- ultra-builder-pro:handbook:end -->
+```
+
+Rules outside those markers remain byte-for-byte user-owned. A malformed or
+duplicated marker pair is an error, not an invitation to guess. For Codex only,
+the first apply can migrate the old unmarked
+`## Ultra Builder Pro Runtime Contract` section up to the next level-two heading.
+
+## Safe workflow
+
+Preview the full merged result before applying:
+
+```bash
+ubp-handbook preview --runtime claude
+ubp-handbook preview --runtime codex
+ubp-handbook preview --runtime opencode
+```
+
+Apply when the preview is correct:
+
+```bash
+ubp-handbook apply --runtime claude
+ubp-handbook apply --runtime codex
+ubp-handbook apply --runtime opencode
+```
+
+An existing target is copied to
+`<file>.ubp-backup-<timestamp>` before the atomic replacement. Re-running apply
+with the same rendered content is a no-op and creates no additional backup.
+
+The plugin installer intentionally does not apply this section implicitly. A
+plugin update and a durable user-handbook change have different rollback and
+review requirements, so handbook mutation stays explicit.

package/hooks/README.md

@@ -0,0 +1,24 @@
+# Ultra Builder Pro workflow hooks
+
+These hooks protect only a currently active Ultra workflow. Every hook is a no-op unless the
+project contains `.ultra/workflow-state.json` with a non-terminal status.
+
+| Lifecycle | Hook | Purpose |
+|---|---|---|
+| Session start | `health_check.py` | Advisory check of `.ultra/state.db` core tables |
+| Session start | `workflow_context.py` | Inject current command, task, step, and authority |
+| Before edit | `active_task_context.py` | Restate the active task boundary |
+| Before compact | `workflow_checkpoint.py` | Atomically save a minimal workflow checkpoint |
+| After compact/resume | `workflow_resume.py` | Re-inject the current workflow boundary |
+| Stop | `pre_stop_check.py` | Block once when the Ultra workflow is incomplete |
+| Subagent lifecycle | `subagent_tracker.py` | Append lifecycle evidence under `.ultra/runtime/` |
+
+The plugin deliberately does not capture prompts, tool observations, transcripts, summaries, or
+cross-session memory. Generic command blocking and post-edit policy are user/repository governance,
+not Ultra plugin hooks. Persistent memory belongs to the separately installed memory provider.
+
+Runtime wiring:
+
+- Claude Code: native `hooks/hooks.json` with `${CLAUDE_PLUGIN_ROOT}` paths.
+- Codex: native `hooks/hooks.json` through `hooks/adapters/codex.py` for wire normalization.
+- OpenCode: native JavaScript plugin events; the Python hook suite is not copied.

package/hooks/active_task_context.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Remind an active Ultra workflow of its task boundary before edits."""
+
+import json
+import sys
+from pathlib import Path
+
+TERMINAL = {"committed", "completed", "done", "cancelled"}
+
+
+def main() -> None:
+    try:
+        data = json.loads(sys.stdin.read() or "{}")
+        data = data if isinstance(data, dict) else {}
+    except json.JSONDecodeError as exc:
+        print(f"[active_task_context] invalid hook input: {exc}", file=sys.stderr)
+        data = {}
+    start = Path(data.get("cwd") or Path.cwd()).resolve()
+    for root in (start, *start.parents):
+        state_file = root / ".ultra" / "workflow-state.json"
+        if not state_file.is_file():
+            continue
+        try:
+            state = json.loads(state_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"[active_task_context] cannot read {state_file}: {exc}", file=sys.stderr)
+            break
+        if not isinstance(state, dict) or state.get("status") in TERMINAL:
+            break
+        task = state.get("task_id", state.get("task", "unknown"))
+        step = state.get("step", "unknown")
+        print(json.dumps({"hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": (
+                f"Active Ultra task {task}, step {step}. Keep this edit inside the approved "
+                "task and preserve .ultra/state.db as workflow authority."
+            ),
+        }}))
+        return
+    print(json.dumps({}))
+
+
+if __name__ == "__main__":
+    main()