ultra-builder-pro-cli 0.13.0 → 0.15.0

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.13.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.15.0-blue)](./CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#verification)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)
@@ -17,8 +17,6 @@ authoritative `.ultra/state.db`.
 
 ---
 
-> *(30-second demo GIF placeholder — to be added before v1.0)*
-
 ## What it does
 
 - **Builds host-native plugins from one allowlist.** Claude Code, OpenCode,
@@ -33,13 +31,17 @@ authoritative `.ultra/state.db`.
 - **Keeps memory ownership explicit.** Ultra Builder Pro does not collect
   prompts, transcripts, observations, summaries, or cross-session memory.
   Install cloud-mem/claude-mem separately if persistent memory is wanted.
-- **Runs real PRDs end-to-end.** `task.parse_prd` → `lib/topo.cjs` waves →
+- **Runs real PRDs end-to-end without a second model credential.** The current
+  host derives task objects; `task.parse_prd` validates them → `lib/topo.cjs` waves →
   `.ultra/execution-plan.json` → parallel worktree sessions → auto-merge back.
 - **Keeps daily work convergent.** `/ultra-change` creates a bounded delta and
-  Context Manifest v2; the Context Spine assigns a role/gate, verifies required
+  complete Change Contract, classifies risk, records whether bounded research is
+  required, and creates immutable Context Manifest v2 snapshots; the Context Spine assigns a role/gate, verifies required
   references, reports fresh-context budget pressure as advisory warnings, exposes one DB-derived breadcrumb, and
-  routes a single next action. `/ultra-deliver` requires applied specification
-  learning plus docs/test/two-axis review evidence before archive. `/ultra-doctor` reports incidents,
+  routes a single next action. Research stores typed, source-digested semantic records;
+  planning proves Change acceptance coverage; `/ultra-deliver` requires applied specification
+  learning plus docs/test/mode-bound two-axis review evidence and a schema-validated
+  baseline reconciliation manifest before archive. `/ultra-doctor` reports incidents,
   projection lag, orphan sessions, and backup-first mechanical recovery.
   Incident changes additionally require a five-section `diagnosis.md` covering
   reproduction, hypotheses, root cause, regression test, and recovery.
@@ -87,13 +89,22 @@ install or update.
 See [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md)
 for per-runtime capabilities.
 
-Start with `ultra-init` in both new and existing projects. An empty project opens
-a `draft` greenfield baseline. An existing codebase opens an `adopting`
-brownfield baseline; inspect current behavior, call `baseline.record`, then
-approve it through `baseline.converge` before normal planning or delivery. Existing
-active work may continue while adoption drift is visible. A new incident requires an
-explicit break-glass approver and leaves a blocking reconciliation gap at archive;
-new ordinary work always requires a healthy ready baseline.
+Start with `ultra-init` in both new and existing projects. Auto classification is
+based on delivered-system evidence: application source, tests, deployment, or
+persisted-state/schema signals make a repository brownfield; a Git repository,
+manifest, README, or starter documentation alone remains greenfield. An empty project
+opens a `draft` greenfield baseline and an existing system opens an `adopting`
+brownfield baseline. Both execute all seventeen research steps before
+`baseline.record` and explicit `baseline.converge`; initialization never treats blank
+templates as a trusted baseline and never selects an MVP. Existing active work may
+continue only when its durable change workflow was bound to a healthy ready baseline;
+the expected HEAD, worktree, spec, and source-evidence drift created by that change is
+advisory until delivery reconciliation. Loss of approved-ready status or structural
+baseline evidence blocks ordinary work. An incident requires an explicit break-glass
+approver and leaves a blocking reconciliation gap at archive; new ordinary work always
+requires a healthy ready baseline. See
+[`docs/WORKFLOW-LIFECYCLE.md`](./docs/WORKFLOW-LIFECYCLE.md) for exact write,
+transition, invalidation, and recovery semantics.
 
 ## Three-layer architecture
 
@@ -106,7 +117,7 @@ new ordinary work always requires a healthy ready baseline.
 The layers share one `.ultra/state.db`, but the CLI is not a mirror of every MCP
 tool: continuous change mutations are MCP-only and fail closed. See
 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full contract and
-[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 36 live contracts.
+[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 41 live contracts.
 Review, impact discovery, skill resolution, and user interaction stay on each
 Host's native surfaces; the generated Codex capability map documents those
 replacements without advertising non-existent MCP tools.
@@ -139,10 +150,11 @@ ultra-tools task init-project --project-name myapp --mode auto
 
 # Projection-only projects from prior releases use one backup-first import:
 ultra-tools migrate --from=4.4 --to=4.5 --source-dir .
-ultra-tools migrate --from=4.5 --to=12.0 --source-dir .
+ultra-tools migrate --from=4.5 --to=15.0 --source-dir .
 
-# 2. Record and converge the greenfield/brownfield baseline, then turn accepted
-#    behavior into a task graph (normally driven by ultra-init/research/plan)
+# 2. Complete all 17 research steps, record current evidence, and obtain explicit
+#    baseline approval. Then open an initial change and persist its task contracts
+#    (normally driven by ultra-research/change/plan).
 
 # 3. Run the plan — parallel sessions, auto-merge back to main on success
 ubp-orchestrator run
@@ -155,10 +167,11 @@ ultra-tools system doctor
 ```
 
 Or let the skills drive it. In Codex, invoke
-`$ultra-builder-pro:ultra-init` → `$ultra-builder-pro:ultra-plan` → `$ultra-builder-pro:ultra-dev` →
-`$ultra-builder-pro:ultra-test` → `$ultra-builder-pro:ultra-review` →
-`$ultra-builder-pro:ultra-deliver`; after the baseline is delivered, daily work
-starts with `$ultra-builder-pro:ultra-change`, while
+`$ultra-builder-pro:ultra-init` → `$ultra-builder-pro:ultra-research` →
+`$ultra-builder-pro:ultra-change` → `$ultra-builder-pro:ultra-plan` →
+`$ultra-builder-pro:ultra-dev` → `$ultra-builder-pro:ultra-test` →
+`$ultra-builder-pro:ultra-review` → `$ultra-builder-pro:ultra-deliver`; after the
+baseline is delivered, daily work starts with `$ultra-builder-pro:ultra-change`, while
 `$ultra-builder-pro:ultra-status` reads the compact authoritative breadcrumb.
 Kimi uses the corresponding
 `/ultra-builder-pro:ultra-*` namespace. Other runtimes retain their native
@@ -228,10 +241,10 @@ Individual suites: `test:state`, `test:orch`, `test:spec`, `test:rest`.
   `ultra-tools legacy-memory inspect`, archive with
   `ultra-tools legacy-memory archive`, then prune only with the explicit
   confirmation token printed by the command. Nothing is deleted implicitly.
-- **MCP tool errors with `ANTHROPIC_API_KEY` missing**: `task.parse_prd` and
-  `task.expand` need a real LLM key at runtime. Set `ANTHROPIC_API_KEY` or
-  `OPENAI_API_KEY` before invoking those tools; all other MCP tools work
-  without any LLM credential.
+- **MCP model credentials**: Ultra MCP does not require `ANTHROPIC_API_KEY`,
+  `OPENAI_API_KEY`, or another provider key. The active host uses its existing
+  model session to derive PRD tasks or child tasks; `task.parse_prd` and
+  `task.expand` only validate ownership, graph shape, and atomic persistence.
 
 ## Documentation
 
@@ -240,6 +253,7 @@ Individual suites: `test:state`, `test:orch`, `test:spec`, `test:rest`.
 | [`docs/PLAN.zh-CN.md`](./docs/PLAN.zh-CN.md) | Historical 12-phase plan and decision log with a current-boundary overlay |
 | [`docs/ROADMAP.md`](./docs/ROADMAP.md) | One-page English roadmap + phase status |
 | [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Single-page system architecture |
+| [`docs/WORKFLOW-LIFECYCLE.md`](./docs/WORKFLOW-LIFECYCLE.md) | Baseline classification, DB writes, status machines, gates, invalidation, and recovery |
 | [`docs/AGENT-CONTEXT.md`](./docs/AGENT-CONTEXT.md) | Canonical runtime context contract |
 | [`docs/USER-HANDBOOK-CONTRACT.md`](./docs/USER-HANDBOOK-CONTRACT.md) | Shared user-handbook policy and host renderings |
 | [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md) | Per-runtime capability matrix |

package/adapters/_shared/codex-assets.cjs

@@ -72,134 +72,6 @@ const SKILL_REFERENCE_NAMES = Object.freeze([
 const CODEX_PRIMARY_SKILLS = new Set([...COMMAND_NAMES, 'ultra-review']);
 const TEXT_EXTENSIONS = new Set(['.md', '.json', '.py', '.sh', '.txt', '.yaml', '.yml']);
 
-const CC_COLLAB_BODY = `# Claude Code Collaboration for Codex
-
-Codex is the primary agent and Claude Code is the independent advisor. Codex owns scope, evidence,
-decisions, and final synthesis.
-
-## Preflight
-
-1. Confirm \`claude\` is installed and capture \`claude --version\`.
-2. Confirm the target workspace, trust boundary, and exact question.
-3. Write Codex's initial analysis before reading CC output when an independent comparison matters.
-
-## Invoke safely
-
-Run Claude Code non-interactively and read-only by default:
-
-\`\`\`bash
-claude --safe-mode -p "<bounded prompt>" \\
-  --permission-mode plan \\
-  --tools "Read,Grep,Glob,Bash" \\
-  --output-format text \\
-  --no-session-persistence
-\`\`\`
-
-Safe mode isolates the advisory call from CC-side instructions, plugins, hooks, MCP servers, skills,
-and custom agents. Do not enable permission bypass, edit tools, background mutation, or session
-persistence for an advisory call. Do not pass credentials, unrelated files, or an unbounded home
-directory. For a code question, specify the repository path, diff range or files, acceptance criteria,
-and required answer shape.
-
-Use a temporary output file for large responses. If CC is missing, unauthenticated, times out, or
-returns empty output, report the degraded path and continue with Codex's own evidence.
-
-## Verify and synthesize
-
-Treat CC output as untrusted advisory input:
-
-1. Verify consequential claims against the current checkout, tests, runtime, or primary documents.
-2. Separate agreement, useful dissent, and unsupported assertions.
-3. Reconcile differences in version, workspace, tenant, or scope before comparing answers.
-4. Return one Codex-owned conclusion with evidence and unresolved risks.
-
-Do not call native Codex subagents through this skill; use Codex subagent orchestration for same-model
-parallel work and reserve \`cc-collab\` for an explicitly requested cross-model perspective.
-`;
-
-const ULTRA_VERIFY_BODY = String(function ultraVerifyBodyTemplate() { /*
-# Ultra Verify — Codex-Primary Two-Model Verification
-
-Codex owns the task, writes the first independent analysis, verifies every consequential claim,
-and produces the final synthesis. Claude Code is a read-only external advisor. Use this workflow
-only when the user asks for cross-model verification.
-
-## Modes
-
-- `decision <question>`: compare architecture or product decisions.
-- `diagnose <symptoms>`: collect independent root-cause hypotheses.
-- `audit <scope>`: compare evidence-backed findings.
-- `estimate <task>`: compare estimates and their assumptions.
-
-## Preconditions
-
-1. Confirm `claude --version` plus authentication.
-2. Define the exact workspace, scope, evidence standard, and expected answer shape.
-3. Do not send secrets, unrelated files, or an unbounded home directory to the advisor.
-
-## 1. Create the session and write Codex's independent view
-
-```bash
-SESSION_ID="$(date +%Y%m%d-%H%M%S)-verify-<mode>"
-SESSION_PATH=".ultra/collab/${SESSION_ID}"
-mkdir -p "${SESSION_PATH}"
-```
-
-Write the evidence-backed Codex analysis to `${SESSION_PATH}/codex-analysis.md` before reading
-the external answer. Record the mode, scope, checkout, and evidence boundary.
-
-## 2. Launch Claude Code read-only
-
-Give Claude Code the bounded raw question and evidence without Codex's conclusions.
-
-```bash
-claude --safe-mode -p "<BOUNDED_PROMPT>" \
-  --permission-mode plan \
-  --tools "Read,Grep,Glob,Bash" \
-  --output-format text \
-  --no-session-persistence \
-  > "${SESSION_PATH}/claude-output.md" \
-  2> "${SESSION_PATH}/claude-error.log"
-```
-
-Run the command in a yielded shell session. Do not enable permission bypass, mutation tools,
-background writes, or session persistence.
-
-## 3. Collect completed output
-
-The bundled `scripts/verify_wait.py` checks output stability. Poll yielded sessions in bounded
-intervals and never hold one blocking tool call longer than 60 seconds. Read the output only when
-it is non-empty; retain the error log when the advisor fails.
-
-## 4. Verify and synthesize
-
-Compare `codex-analysis.md` and `claude-output.md`:
-
-1. Verify claims against the current checkout, runtime, tests, or primary documentation.
-2. Separate verified agreement, useful dissent, and unsupported assertions.
-3. Explain scope, version, or assumption differences before judging the result.
-4. Write `${SESSION_PATH}/synthesis.md` and `metadata.json`, then present one Codex-owned answer.
-
-Model agreement never overrides failing tests or authoritative runtime evidence.
-
-## Degraded operation
-
-- Advisor failure: return Codex-only analysis with an explicit single-source warning.
-- Never block the user's task solely because the external CLI is absent, unauthenticated, or slow.
-
-## Session files
-
-```text
-.ultra/collab/<SESSION_ID>/
-  codex-analysis.md
-  claude-output.md
-  claude-error.log
-  metadata.json
-  synthesis.md
-```
-
-Read the bundled references for mode-specific evidence and confidence guidance.
-*/ }).match(/\/\*([\s\S]*?)\*\//)[1].trim();
 function titleCase(name) {
   const special = { 'cc-collab': 'Claude Code Collaboration' };
   if (special[name]) return special[name];
@@ -217,8 +89,8 @@ function replaceSlashCommand(text, command, replacement) {
 function adaptCodexPrimaryText(input, skillName) {
   let text = String(input);
   if (skillName === 'ultra-review') {
-    text = text.replaceAll(
-      "the current host's native bounded-worker mechanism",
+    text = text.replace(
+      /the current host's native bounded-worker\s+mechanism/g,
       'native Codex custom agents installed for the selected review workers',
     );
   }
@@ -226,34 +98,7 @@ function adaptCodexPrimaryText(input, skillName) {
   return text;
 }
 
-function adaptUltraVerifyAsset(input, rel) {
-  let text = adaptHostText(String(input), '');
-  if (rel === path.join('scripts', 'verify_wait.py')) {
-    text = text.replaceAll('Codex', 'Claude Code');
-    text = text.replaceAll('codex', 'claude');
-    text = text.replaceAll('run_in_background', 'a yielded exec session');
-    return text;
-  }
-
-  text = text.replaceAll('Claude', '__UBP_CODEX_PRIMARY__');
-  text = text.replaceAll('Codex', 'Claude Code');
-  text = text.replaceAll('__UBP_CODEX_PRIMARY__', 'Codex');
-  text = text.replaceAll('claude-analysis.md', 'codex-analysis.md');
-  text = text.replaceAll('codex-output.md', 'claude-output.md');
-  text = text.replaceAll('codex-error.log', 'claude-error.log');
-  text = text.replaceAll('codex-review', 'claude-review');
-  text = text.replaceAll('"claude": "claude-opus-4-6"', '"codex": "<primary>"');
-  text = text.replaceAll('"codex": "<model>"', '"claude": "<advisor>"');
-  text = text.replaceAll('["claude"]', '["codex"]');
-  text = text.replaceAll('Claude Code-only', 'Codex-only');
-  text = text.replaceAll('run_in_background', 'native concurrent execution');
-  text = text.replaceAll('Bash tool', '`exec_command`');
-  text = text.replaceAll('Read tool', 'targeted file reads');
-  return text;
-}
-
-function adaptSkillAsset(input, targetName, rel) {
-  if (targetName === 'ultra-verify') return adaptUltraVerifyAsset(input, rel);
+function adaptSkillAsset(input, targetName, _rel) {
   return adaptHostText(input, targetName);
 }
 
@@ -298,10 +143,7 @@ function adaptedDescription(sourceDescription, targetName) {
 
 function buildSkillMarkdown(sourceText, sourceName, targetName) {
   const { fm, body } = parseFrontmatter(sourceText);
-  let adaptedBody;
-  if (targetName === 'cc-collab') adaptedBody = CC_COLLAB_BODY;
-  else if (targetName === 'ultra-verify') adaptedBody = ULTRA_VERIFY_BODY;
-  else adaptedBody = adaptHostText(body, targetName);
+  const adaptedBody = adaptHostText(body, targetName);
   return yaml.dump({
     name: targetName,
     description: adaptedDescription(fm && fm.description, targetName),
@@ -309,13 +151,22 @@ function buildSkillMarkdown(sourceText, sourceName, targetName) {
     .replace(/^/, '---\n') + `\n---\n\n${adaptedBody.trim()}\n`;
 }
 
+function shortDescription(description, name) {
+  const value = String(description || `${titleCase(name)} for Codex`).replace(/\s+/g, ' ').trim();
+  if (value.length <= 64) return value;
+  const candidate = value.slice(0, 65);
+  const boundary = candidate.lastIndexOf(' ');
+  const short = (boundary >= 25 ? candidate.slice(0, boundary) : value.slice(0, 64))
+    .replace(/[\s.,;:]+$/, '');
+  return short || `${titleCase(name)} for Codex`;
+}
+
 function buildOpenAiYaml(name, description) {
   const policy = skillPolicy(name);
-  const short = description.replace(/\s+/g, ' ').trim().slice(0, 63).replace(/[\s.,;:]+$/, '');
   const metadata = {
     interface: {
       display_name: titleCase(name),
-      short_description: short || `${titleCase(name)} for Codex`,
+      short_description: shortDescription(description, name),
       default_prompt: `Use $ultra-builder-pro:${name} for this task and follow its workflow.`,
     },
     policy: { allow_implicit_invocation: policy.allowImplicitInvocation },
@@ -329,7 +180,12 @@ function buildOpenAiYaml(name, description) {
       }],
     };
   }
-  return yaml.dump(metadata, { lineWidth: -1, noRefs: true });
+  return yaml.dump(metadata, {
+    lineWidth: -1,
+    noRefs: true,
+    forceQuotes: true,
+    quotingType: "'",
+  });
 }
 
 function isTextFile(rel) {
@@ -536,6 +392,14 @@ main().catch((error) => {
 });
 `;
   writeAtomic(path.join(runtimeRoot, 'launch.cjs'), launcher);
+  fs.copyFileSync(
+    path.join(repoRoot, 'mcp-server', 'breadcrumb.cjs'),
+    path.join(runtimeRoot, 'breadcrumb.cjs'),
+  );
+  fs.copyFileSync(
+    path.join(repoRoot, 'mcp-server', 'hook-event.cjs'),
+    path.join(runtimeRoot, 'hook-event.cjs'),
+  );
 
   const sourceToolsFile = path.join(repoRoot, 'spec', 'mcp-tools.yaml');
   const upstreamManifest = yaml.load(fs.readFileSync(sourceToolsFile, 'utf8'));

package/adapters/_shared/file-ops.cjs

@@ -8,7 +8,11 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 
-const DEFAULT_EXCLUDES = new Set(['.DS_Store', 'Thumbs.db']);
+const DEFAULT_EXCLUDES = new Set(['.DS_Store', 'Thumbs.db', '__pycache__']);
+
+function isExcluded(name, exclude) {
+  return exclude.has(name) || name.endsWith('.pyc') || name.endsWith('.pyo');
+}
 
 function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
@@ -27,7 +31,7 @@ function listRelative(root, { exclude = DEFAULT_EXCLUDES } = {}) {
   const out = [];
   (function walk(dir) {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      if (exclude.has(entry.name)) continue;
+      if (isExcluded(entry.name, exclude)) continue;
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (entry.isFile()) out.push(path.relative(root, full));

package/adapters/_shared/runtime-assets.cjs

@@ -40,6 +40,7 @@ const COLLAB_SKILLS_BY_RUNTIME = Object.freeze({
 
 const MCP_DEPENDENT_SKILLS = Object.freeze([
   'ultra-init',
+  'ultra-research',
   'ultra-change',
   'ultra-plan',
   'ultra-dev',

package/adapters/claude.js

@@ -63,8 +63,8 @@ function copySkills(repoRoot, target, names) {
           adaptedBody = adaptedBody.replaceAll("current host's user skill directory", '`~/.claude/skills`');
         }
         if (name === 'ultra-review') {
-          adaptedBody = adaptedBody.replaceAll(
-            "the current host's native bounded-worker mechanism",
+          adaptedBody = adaptedBody.replace(
+            /the current host's native bounded-worker\s+mechanism/g,
             'Claude Code Task workers using the installed review agent definitions',
           );
         }
@@ -194,6 +194,7 @@ function install(ctx = {}) {
       plugin_manifest: { root: 'plugin', path: '.claude-plugin/plugin.json' },
       mcp_registration: { root: 'plugin', path: '.mcp.json' },
       mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+      hook_event_helper: { root: 'plugin', path: 'runtime/hook-event.cjs' },
       hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
       checkpoint_hook: { root: 'plugin', path: 'hooks/workflow_checkpoint.py' },
       resume_hook: { root: 'plugin', path: 'hooks/workflow_resume.py' },

package/adapters/codex.js

@@ -375,6 +375,7 @@ function install(ctx = {}) {
       plugin_manifest: { root: 'plugin', path: '.codex-plugin/plugin.json' },
       mcp_registration: { root: 'plugin', path: '.mcp.json' },
       mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+      hook_event_helper: { root: 'plugin', path: 'runtime/hook-event.cjs' },
       hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
       hook_adapter: { root: 'plugin', path: HOOK_ADAPTER_RELATIVE },
       runtime_manifest: { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },

package/adapters/kimi.js

@@ -94,8 +94,8 @@ function kimiTextTransform(input, assetName = '') {
     text = text.replaceAll('current host', 'Kimi Code');
   }
   if (assetName === 'ultra-review') {
-    text = text.replaceAll(
-      "the current host's native bounded-worker mechanism",
+    text = text.replace(
+      /the current host's native bounded-worker\s+mechanism/g,
       'Kimi `AgentSwarm` for parallel reviewers or one foreground Kimi `Agent` for a single reviewer, using the worker prompt files under `$KIMI_PLUGIN_ROOT/agents/`',
     );
   }
@@ -349,6 +349,7 @@ function writePluginProvenance(repoRoot, target) {
     contracts: {
       plugin_manifest: { root: 'plugin', path: 'kimi.plugin.json' },
       mcp_launcher: { root: 'plugin', path: path.join('runtime', 'launch.cjs') },
+      hook_event_helper: { root: 'plugin', path: path.join('runtime', 'hook-event.cjs') },
       hook_adapter: { root: 'plugin', path: path.join('hooks', 'adapters', 'kimi.py') },
       session_bootstrap: {
         root: 'plugin', path: path.join('skills', BOOTSTRAP_SKILL, 'SKILL.md'),