ultra-builder-pro-cli 0.5.0

package/.ultra-template/specs/product.md

@@ -0,0 +1,223 @@
+# Product Specification
+
+> **Source of Truth**: This document defines WHAT the system does and WHO it's for.
+> Generated by `/ultra-research` Steps 10-22
+> Technical HOW belongs in `architecture.md`.
+
+---
+
+## §1 Problem Statement
+
+### Core Problem
+[NEEDS CLARIFICATION] — One paragraph describing the problem, grounded in discovery.md §0
+
+### Who It Affects
+[NEEDS CLARIFICATION] — Brief overview connecting problem to specific user types
+
+### Current Impact
+- **Time cost**: [NEEDS CLARIFICATION] — Hours/week wasted on workarounds
+- **Money cost**: [NEEDS CLARIFICATION] — $ lost to inefficiency
+- **Opportunity cost**: [NEEDS CLARIFICATION] — What they can't do because of this problem
+
+---
+
+## §2 User Personas
+
+### Persona 1: [NEEDS CLARIFICATION] (Primary)
+
+**Role**: Job title / context
+**Context**: Where they work, team dynamics, industry
+
+**Goals**:
+1. [NEEDS CLARIFICATION] — Primary goal (what gets them promoted)
+2. Secondary goal (daily care)
+3. Tertiary goal (nice to have)
+
+**Pain Points**:
+1. [NEEDS CLARIFICATION] — Connects to Opportunity O# from discovery.md §1
+2. Connects to Opportunity O#
+3. Source: URL or user quote
+
+**Current Workflow**:
+> Step-by-step description of how they solve this today
+> Tools used: List of current tools/processes
+> Time spent: X hours/week
+
+**Success Metric**: How they measure their own success
+**Adoption Trigger**: What would make them try our solution
+**Objections**: Why they might resist
+
+### Persona 2: [NEEDS CLARIFICATION] (Secondary)
+
+**Role**: [NEEDS CLARIFICATION]
+**Context**: [NEEDS CLARIFICATION]
+
+**Goals**:
+1. [NEEDS CLARIFICATION]
+
+**Pain Points**:
+1. [NEEDS CLARIFICATION]
+
+**Current Workflow**:
+> [NEEDS CLARIFICATION]
+
+**Success Metric**: [NEEDS CLARIFICATION]
+**Adoption Trigger**: [NEEDS CLARIFICATION]
+**Objections**: [NEEDS CLARIFICATION]
+
+### Persona Prioritization
+
+| Persona | Urgency | Willingness to Pay | Reachability | Priority |
+|---------|---------|-------------------|-------------|----------|
+| P1 | [NEEDS CLARIFICATION] | | | **Primary** |
+| P2 | | | | **Secondary** |
+
+---
+
+## §3 User Scenarios
+
+### Scenario Overview
+
+| # | Scenario | Persona | Frequency | Pain | Value | Score |
+|---|----------|---------|-----------|------|-------|-------|
+| S1 | [NEEDS CLARIFICATION] | P1 | /5 | /5 | /5 | |
+| S2 | | | | | | |
+| S3 | | | | | | |
+
+> Priority Score = Frequency × Pain × Value
+
+### Scenario 1: [NEEDS CLARIFICATION] — Primary
+
+**Persona**: [NEEDS CLARIFICATION]
+**Frequency**: Daily / Weekly / Monthly
+
+**Trigger**: What event causes this scenario
+**Context**: Where, when, device, time pressure
+
+**Current Flow** (painful):
+1. [NEEDS CLARIFICATION] — What they do today
+2. Where friction occurs
+3. Workaround they use
+4. Outcome and time wasted
+
+**Desired Flow** (with our product):
+1. [NEEDS CLARIFICATION] — Trigger detected
+2. Streamlined action
+3. Fast resolution
+4. Outcome achieved in less time
+
+**Success Outcome**: [NEEDS CLARIFICATION] — Specific and measurable
+**Failure Outcome**: [NEEDS CLARIFICATION] — Consequences
+**Emotional Arc**: Frustration → Discovery → Relief
+
+### Scenario 2: [NEEDS CLARIFICATION]
+
+[Same structure as Scenario 1]
+
+### Scenario 3: [NEEDS CLARIFICATION]
+
+[Same structure as Scenario 1]
+
+---
+
+## §4 User Stories & Features
+
+### Story Map Overview
+
+| ID | Story | Persona | Scenario | Priority | Complexity |
+|----|-------|---------|----------|----------|-----------|
+| US-01 | [NEEDS CLARIFICATION] | P1 | S1 | Must | S/M/L |
+| US-02 | | | | | |
+| US-03 | | | | | |
+
+### Must-Have Stories
+
+#### US-01: [NEEDS CLARIFICATION]
+**As a** [Persona], **I want** [action], **so that** [benefit].
+
+**Acceptance Criteria**:
+- [ ] Given [context], when [action], then [result]
+- [ ] Given [context], when [edge case], then [result]
+
+**Traces to**: Scenario S#, Opportunity O#
+**Complexity**: S/M/L
+
+### Should-Have Stories
+
+#### US-04: [NEEDS CLARIFICATION]
+[Same structure]
+
+### Could-Have Stories
+
+#### US-07: [NEEDS CLARIFICATION]
+[Same structure]
+
+---
+
+## §5 Feature Scope
+
+### Features In (MVP)
+
+#### Feature 1: [NEEDS CLARIFICATION]
+- **Description**: What this feature does
+- **Stories**: US-01, US-02
+- **User value**: What user can do with this
+- **Priority**: Must-Have
+- **Complexity**: S/M/L
+
+### Features In (v2 — Planned)
+
+#### Feature 4: [NEEDS CLARIFICATION]
+- **Description**: What this feature does
+- **Stories**: US-07, US-08
+- **Rationale for deferral**: Why not MVP
+- **Trigger to build**: When to reconsider
+
+### Features Out (Explicitly Excluded)
+
+| Feature | Rationale | Reconsider When | Alternative |
+|---------|-----------|----------------|-------------|
+| [NEEDS CLARIFICATION] | Why excluded (ref strategy §4) | Condition | What users do instead |
+
+### Scope Summary
+- **MVP features**: [NEEDS CLARIFICATION] features, stories
+- **v2 features**: features, stories
+- **Excluded features**: features
+
+---
+
+## §6 Success Metrics
+
+### North Star Metric
+- **Metric**: [NEEDS CLARIFICATION]
+- **Definition**: Exactly what is measured
+- **Current baseline**: Current state or industry benchmark
+- **Target**: Specific number
+- **Timeline**: When to achieve
+- **Measurement method**: How to collect this data
+
+### Business Metrics
+
+| Metric | Baseline | Target (M3) | Target (M6) | Target (M12) | How Measured |
+|--------|----------|-------------|-------------|--------------|-------------|
+| [NEEDS CLARIFICATION] | | | | | |
+
+### User Metrics
+
+| Metric | Baseline | Target | How Measured |
+|--------|----------|--------|-------------|
+| Task completion rate | [NEEDS CLARIFICATION] | | |
+| Time on task | | | |
+| User satisfaction (NPS) | | | |
+| Feature adoption | | | |
+
+### Anti-Metrics (What NOT to Optimize)
+
+| Anti-Metric | Why Not | What It Could Sacrifice |
+|------------|---------|------------------------|
+| [NEEDS CLARIFICATION] | | |
+
+---
+
+**Document Status**: Draft
+**Last Updated**: [Date]

package/.ultra-template/tasks/contexts/TEMPLATE.md

@@ -0,0 +1,57 @@
+# Task {id}: {title}
+
+> **Status**: pending | **Priority**: {priority} | **Complexity**: {complexity}
+
+## Context
+
+**What**: [Clear description of what to build/change]
+
+**Why**: [Business value linking to Persona + Scenario from specs]
+
+**Constraints**:
+- [Technical or business constraint 1]
+- [Technical or business constraint 2]
+
+## Implementation
+
+**Target Files**:
+- `path/to/file.ts` (create)
+- `path/to/existing.ts` (modify: description)
+
+**Pattern**: [Reference to existing code patterns to follow]
+
+**Tech Notes**: [Framework/library specific guidance]
+
+## Acceptance
+
+**Tests**:
+- [ ] `test command here`
+- [ ] Pass: [scenario 1 description]
+- [ ] Pass: [scenario 2 description]
+
+**Verification**:
+```bash
+# Manual verification command
+curl -X POST localhost:3000/api/example
+```
+
+## Trace
+
+**Source**: `.ultra/specs/product.md#section-id`
+
+## Change Log
+
+| Date | Change | Specs Updated | Reason |
+|------|--------|---------------|--------|
+| {created_date} | Initial creation | - | Generated by /ultra-plan |
+
+## Completion
+
+> _Fill when task completed_
+
+- **Completed**: {date}
+- **Commit**: {hash}
+- **Summary**: {brief description of what was delivered}
+
+---
+*Generated by /ultra-plan*

package/.ultra-template/tasks/tasks.json

@@ -0,0 +1,33 @@
+{
+  "version": "4.4",
+  "created": "",
+  "updated": "",
+  "project": {
+    "name": "",
+    "type": "",
+    "stack": ""
+  },
+  "tasks": [],
+  "metadata": {
+    "totalTasks": 0,
+    "completedTasks": 0,
+    "inProgressTasks": 0,
+    "pendingTasks": 0,
+    "totalEstimatedDays": 0
+  },
+  "_schema": {
+    "_comment": "Lightweight task registry - full context in contexts/task-{id}.md",
+    "task_example": {
+      "id": "1",
+      "title": "Action verb + specific target",
+      "type": "feature|architecture|bugfix",
+      "priority": "P0|P1|P2|P3",
+      "complexity": "1-10",
+      "status": "pending|in_progress|completed|blocked",
+      "dependencies": ["task_id"],
+      "estimated_days": 2,
+      "context_file": "contexts/task-1.md",
+      "trace_to": ".ultra/specs/product.md#section-id"
+    }
+  }
+}

package/.ultra-template/test-report.json

@@ -0,0 +1,8 @@
+{
+  "passed": false,
+  "run_count": 0,
+  "timestamp": null,
+  "git_commit": null,
+  "gates": {},
+  "blocking_issues": ["Not yet run"]
+}

package/CHANGELOG.md

@@ -0,0 +1,194 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0] — 2026-07-16
+
+### Added
+
+- Added first-class native Claude Code and OpenCode plugin builders alongside
+  the Codex personal plugin. All hosts build from one explicit runtime asset
+  allowlist; Gemini remains a compatibility extension using the same boundary.
+- Added `ubp-handbook` for previewed, backed-up managed-block integration with
+  user-level Claude `CLAUDE.md`, Codex `AGENTS.md`, and OpenCode `AGENTS.md`.
+- Added `ultra-tools legacy-memory inspect|archive|prune`; prune requires the
+  exact `DELETE_ULTRA_LEGACY_MEMORY` confirmation token and never runs during
+  install or update.
+- Added release verification for a freshly packed npm consumer, including
+  executable CLI links and live Claude Code, OpenCode, and Codex MCP round trips.
+
+### Changed
+
+- Reduced the package to ten Ultra-owned public workflows, four internal
+  agent-rule skills, and host-specific collaboration companions. The internal
+  `code-review-expert` skill is no longer implicitly user-invocable.
+- Replaced the imported hook suite with seven workflow-only hooks that are
+  no-ops outside an active `.ultra/workflow-state.json`. OpenCode uses native
+  JavaScript lifecycle hooks; Claude Code and Codex use native plugin manifests.
+- Upgraded `@anthropic-ai/sdk` to the patched `^0.111.0` line.
+- Reduced the published MCP contract to the 21 tools the server actually
+  exposes; review, impact, skill discovery, and user interaction use native
+  Host surfaces.
+
+### Fixed
+
+- Made MCP database initialization lazy, synchronized the handshake version
+  with the npm package, and fixed `session.subscribe_events` sid filtering.
+- Aligned session/plan input schemas with runtime behavior, including circuit
+  breaker output, session spawn intent semantics, and removal of ignored inputs.
+- Bundled Gemini's compatibility MCP runtime durably and restored project-local
+  `.ultra/state.db` ownership across all adapters.
+- Exported the documented `ultra-tools` executable and included every README
+  documentation target in the npm tarball.
+
+### Removed
+
+- Removed Ultra's memory MCP tools, store, wrapper, recall skill, memory-capture
+  and summary hooks, and private agent-memory declarations. Persistent memory is
+  now solely the responsibility of a separate cloud-mem/claude-mem plugin.
+- Removed bundled copies of `agent-browser`, `find-skills`, `use-railway`, the
+  three Vercel skill packs, and all Impeccable-derived assets from Ultra output.
+- Removed generic dangerous-command and post-edit governance hooks from the
+  Ultra plugin; unrelated user/repository hooks remain outside this package.
+
+## [0.4.0] — 2026-07-15
+
+### Changed
+
+- Replaced the deprecated Codex `prompts/` and `config.toml` marker projection
+  with a complete personal plugin: 25 adapted skills, nine legacy-command maps,
+  plugin MCP registration, and current native hook events.
+- Converted all nine Ultra agents to native `.codex/agents/*.toml` definitions.
+- Renamed the cross-model skill from `codex-collab` to `cc-collab`; Codex remains
+  the primary agent and Claude Code is an explicitly requested, read-only advisor.
+- Made hook memory, compaction, health, subagent, transcript, and summary behavior
+  runtime-aware. Codex no longer writes fallback state under `~/.claude` or
+  launches a nested model CLI for session summaries.
+- Bundled the Codex MCP and status CLI with `@vercel/ncc`, preserving the active
+  task cwd for project-local state. Generated Codex plugins now distinguish the
+  24 live MCP tools from nine upstream scheduled contracts and document each
+  Codex-native replacement.
+
+### Fixed
+
+- Preserved live Codex task hooks across plugin cache refreshes by restoring
+  retired adapter paths as forwarding shims to the current cached adapter.
+  Failed refreshes recover through the managed plugin source, and corrupt
+  runtime manifests now stop uninstall before managed assets are removed.
+
+## [0.3.0] — 2026-04-18
+
+### Added
+
+- **Phase 8B — executor line** (D48, `8224159`): parallel session orchestrator
+  that consumes `.ultra/execution-plan.json` waves, spawns sessions per
+  `dispatch-rules.cjs` (declarative priority-sorted rule table, GSD-2 pattern),
+  manages N concurrent git worktrees via `worktree-manager.cjs`, and auto-merges
+  session branches back to `main` with conflict detection via `auto-merge.cjs`.
+  Events: `wave_started` / `wave_completed` / `plan_completed` / `merged_back` /
+  `merge_conflict`. Opt-in `autoMerge` on `runPlan` and `closeSession`.
+- **Phase 8A — planner line** (D47, `a932cb8`): `task.parse_prd` with dual-provider
+  LLM client (official `@anthropic-ai/sdk` + `openai`); `lib/topo.cjs`
+  Kahn + Tarjan SCC for dependency waves; `task.expand` atomic subtask creation;
+  `lib/plan-store.cjs` for atomic `.ultra/execution-plan.json` write / section
+  projection; `skills/ultra-plan` PRD-Direct workflow with human-gate via
+  `dry_run` parameter. Schema bump 7.1 → 8A.1 for `tasks.parent_id`.
+- **Phase 7 — intelligence layer** (D46): `memory_entries` FTS5 store with
+  auto-recall on session spawn and auto-retain on close (event-type heuristic,
+  zero LLM cost); tagged task lists per git branch (`deriveBranchTag`);
+  skill mining to `skills/learned/*_unverified.md` on task completion /
+  breaker trip / session crash.
+
+### Changed
+
+- `STATUS_TRANSITIONS` contract now strictly requires `pending → in_progress
+  → completed` — parallel-orchestrator transitions tasks to `in_progress`
+  before the child's exit code may flip them to completed/pending.
+- `daemon.routeTask` is now a thin wrapper over `dispatch-rules.evaluate`
+  (6 default rules: breaker-blocked / deps-not-ready / no-runtimes /
+  wave-conflict / by-preference / fallback-first-available).
+- `closeSession` gains `autoMerge` / `mergeBaseBranch` opt-in params.
+
+### Fixed
+
+- D49 tech-debt sweep: stale Phase comments (`"scheduled for Phase 1"`,
+  `"not implemented in Phase 3.1"`) replaced with accurate `unknown verb`
+  messages; `docs/ROADMAP.md` status table synchronized; `.gitignore`
+  excludes `.rtk/` local filter cache.
+
+### Tests
+
+- **397 tests total** across state (182) + orch (103) + spec (6) + rest
+  (106). Zero regressions from v0.2.
+
+## [0.2.0] — 2026-04-17
+
+### Added
+
+- **Phase 6 — monitoring + live code graph** (D44): RTK soft-dependency hook
+  (`adapters/_shared/rtk-detect.cjs`) with `--skip-rtk` flag and install hint;
+  token / cost telemetry with per-runtime pricing table, `telemetry` table +
+  daily `.ultra/telemetry/YYYY-MM-DD.jsonl`; `ultra-tools status --cost`
+  panel with by-runtime / by-task / by-session aggregation; chokidar-based
+  code-graph watcher with debounce / awaitWriteFinish / batch thresholds,
+  opt-in via `--with-graph-watcher`.
+- **Phase 5 — execution resilience** (D43): `recovery.cjs` boot-time orphan
+  scan using live PID probe; `circuit_breaker` table with `recordTaskFailure`
+  counter and `resetCircuitBreaker` escape hatch; spec-change staleness
+  propagation via cursor-consumed `spec_changed` events; `orchestrator/daemon.cjs`
+  polling loop with `routeTask` by complexity hint; `bin/orchestrator.js`
+  `run`/`start`/`stop`/`status` subcommands, gated by
+  `settings.json#orchestrator.auto_dispatch`.
+- **Phase 4.6b — full conformance suite** (D45): 4 runtime × 5 capability
+  (command / skills / hooks / MCP + no `env._source` leak / install idempotency)
+  = 20 additional conformance tests; table-driven `resolve-target.test.cjs`
+  (21 tests) covering `configDir > env > home/cwd` precedence + Gemini
+  extensionRoot append; schema bump 5.2 → 7.1 alongside memory store.
+
+### Changed
+
+- `_source` leak fix (D45 P2 #9): four adapters now emit a sibling
+  `_ubp: {source}` envelope instead of polluting `env._source`; Codex uses
+  a marker-fence instead of nested TOML object.
+
+## [0.1.0] — 2026-04-17
+
+### Added
+
+- **Phase 4.5 — execution-lite** (D42, `0d3e5ed`): 7 `session.*` MCP tools
+  (spawn / close / get / list / admission_check / heartbeat / subscribe_events);
+  `orchestrator/session-runner.cjs` creates real git worktree + child process;
+  `sessions` table holds lease / heartbeat (no lease.json file — D32);
+  admission control with takeover / resume / abandon strategies (D33).
+- **Phase 4 — cross-runtime distribution** (D41, `5aa1fd0`): shared adapter
+  toolkit (`adapters/_shared/` — file-ops / frontmatter / settings-merge /
+  path-rewrite / md-to-toml); 4 runtime adapters (Claude sentinel-block
+  settings.json merge; OpenCode `opencode.json.mcp`; Codex `config.toml`
+  marker-block + prompts/; Gemini `extensions/ultra-builder-pro/` package);
+  `docs/RUNTIME-COMPAT-MATRIX.md` with 10-section capability matrix;
+  install / uninstall round-trip tests + idempotency.
+- **Phase 3 — thin-shell commands** (D40, `b3d1797`): 9 commands migrated
+  to skill + MCP + CLI three-layer (36-54 LOC per command); 7 new skills
+  under `skills/ultra-*/`; `task.init_project` MCP tool with
+  `.ultra-template/`; `docs/AGENT-CONTEXT.md` canonical runtime contract.
+- **Phase 2 — authoritative state** (D39, `e286e41`): `.ultra/state.db` SQLite
+  + WAL with 7 tables; `mcp-server/lib/{state-db, state-ops, projector}.cjs`
+  write API and state machine; `mcp-server/server.cjs` stdio MCP server with
+  7 `task.*` tools; `ultra-tools db` (init/checkpoint/vacuum/integrity/
+  backup) and `migrate` (v4.4→v4.5 with dry-run + rollback).
+- **Phase 1 — spec contracts** (D38): `spec/` locks the three-layer
+  contract — 30 MCP tools in `mcp-tools.yaml`, 7-table SQLite schema,
+  skill manifest, CLI protocol + mapping table; 5 spec validators.
+- **Phase 0 — skeleton**: multi-runtime installer scaffolding.
+
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/rocky2431/ultra-builder-pro-cli/releases/tag/v0.5.0
+[0.4.0]: https://github.com/rocky2431/ultra-builder-pro-cli/releases/tag/v0.4.0
+[0.3.0]: https://github.com/rocky2431/ultra-builder-pro-cli/releases/tag/v0.3.0
+[0.2.0]: https://github.com/rocky2431/ultra-builder-pro-cli/releases/tag/v0.2.0
+[0.1.0]: https://github.com/rocky2431/ultra-builder-pro-cli/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ultra Builder Pro contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.