ultra-builder-pro-cli 0.17.1 → 0.19.1

package/mcp-server/lib/workflow-state.cjs

@@ -110,15 +110,9 @@ const RESEARCH_DISPOSITIONS = new Set([
   'execute', 'verify_existing', 'reuse', 'not_applicable', 'deferred',
 ]);
 
-const RESEARCH_MODES = Object.freeze({
-  full: WORKFLOW_DEFINITIONS.research.map((item) => item.id),
-  adoption: WORKFLOW_DEFINITIONS.research.map((item) => item.id),
-  product: WORKFLOW_DEFINITIONS.research
-    .filter((item) => Number.parseInt(item.id, 10) < 30 || item.id === '99-synthesis')
-    .map((item) => item.id),
-  feature: ['10-user-personas', '11-user-scenarios', '20-user-stories', '21-features-scope', '22-success-metrics', '99-synthesis'],
-  architecture: ['30-architecture-context', '31-solution-strategy', '32-building-blocks', '40-deployment', '41-quality-risks', '99-synthesis'],
-});
+const RESEARCH_MODE_NAMES = new Set([
+  'full', 'adoption', 'product', 'feature', 'architecture', 'custom',
+]);
 
 const RESEARCH_SEMANTIC_CONTRACTS = Object.freeze({
   '00-problem-validation': ['problem', ['actor', 'current_workaround', 'consequence', 'evidence_status']],
@@ -459,9 +453,20 @@ function decorateRun(db, row, rootDir) {
   return value;
 }
 
+function definitionForRun(run) {
+  const definition = WORKFLOW_DEFINITIONS[run.kind] || [];
+  if (run.kind !== 'research') return definition;
+  const metadata = parseJson(run.metadata_json, 'workflow_runs.metadata_json', {});
+  if (!Array.isArray(metadata.coverage) || metadata.coverage.length === 0) {
+    return definition;
+  }
+  const covered = new Set(metadata.coverage.map((item) => item?.step_id).filter(Boolean));
+  return definition.filter((item) => covered.has(item.id));
+}
+
 function inspectRunHealth(run, steps, rootDir) {
   const blockers = [...inspectOutputHealth(steps, rootDir).blockers];
-  const definition = WORKFLOW_DEFINITIONS[run.kind] || [];
+  const definition = definitionForRun(run);
   const expectedIds = new Set(definition.map((item) => item.id));
   const actualIds = new Set(steps.map((item) => item.step_id));
   if (run.definition_version !== DEFINITION_VERSION) {
@@ -576,6 +581,9 @@ function listWorkflows(db, filter = {}, { rootDir = process.cwd() } = {}) {
 function normalizeResearchCoverage(mode, coverage, selectedSteps, metadata = {}) {
   const knownSteps = WORKFLOW_DEFINITIONS.research.map((item) => item.id);
   const known = new Set(knownSteps);
+  if (!RESEARCH_MODE_NAMES.has(mode)) {
+    throw new WorkflowStateError('VALIDATION_ERROR', `unsupported research mode: ${mode}`);
+  }
   if (coverage !== undefined) {
     if (!Array.isArray(coverage) || coverage.length === 0) {
       throw new WorkflowStateError(
@@ -635,55 +643,66 @@ function normalizeResearchCoverage(mode, coverage, selectedSteps, metadata = {})
         ...(consequence ? { consequence } : {}),
       };
     });
-    if (['full', 'adoption'].includes(mode)) {
-      const missing = knownSteps.filter((stepId) => !seen.has(stepId));
-      if (missing.length > 0) {
-        throw new WorkflowStateError(
-          'WORKFLOW_RESEARCH_COVERAGE_REQUIRED',
-          `${mode} research must disposition every semantic area: ${missing.join(', ')}`,
-        );
-      }
-      const synthesis = normalized.find((item) => item.step_id === '99-synthesis');
-      if (!synthesis || !['execute', 'verify_existing', 'reuse'].includes(synthesis.disposition)) {
-        throw new WorkflowStateError(
-          'WORKFLOW_RESEARCH_SYNTHESIS_REQUIRED',
-          `${mode} research requires an executable or reusable 99-synthesis disposition`,
-        );
-      }
+    const selectionReason = String(metadata.selection_reason || '').trim();
+    if (selectionReason.length < 3) {
+      throw new WorkflowStateError(
+        'WORKFLOW_SELECTION_REASON_REQUIRED',
+        `${mode} research requires the model's evidence-based coverage rationale`,
+      );
+    }
+    const synthesis = normalized.find((item) => item.step_id === '99-synthesis');
+    if (!synthesis || !['execute', 'verify_existing', 'reuse'].includes(synthesis.disposition)) {
+      throw new WorkflowStateError(
+        'WORKFLOW_RESEARCH_SYNTHESIS_REQUIRED',
+        `${mode} research requires an executable or reusable 99-synthesis disposition`,
+      );
+    }
+    const selectedSemanticArea = normalized.some((item) => (
+      item.step_id !== '99-synthesis'
+      && (
+        ['execute', 'verify_existing', 'reuse'].includes(item.disposition)
+        || (item.disposition === 'deferred' && !item.accepted_by)
+      )
+    ));
+    if (!selectedSemanticArea) {
+      throw new WorkflowStateError(
+        'WORKFLOW_RESEARCH_COVERAGE_REQUIRED',
+        `${mode} research requires at least one applicable semantic area besides synthesis`,
+      );
     }
     return normalized.sort(
       (left, right) => knownSteps.indexOf(left.step_id) - knownSteps.indexOf(right.step_id),
     );
   }
 
-  if (['full', 'adoption'].includes(mode)) {
-    throw new WorkflowStateError(
-      'WORKFLOW_RESEARCH_COVERAGE_REQUIRED',
-      `${mode} research requires model-selected coverage dispositions`,
-    );
-  }
   if (mode === 'custom') {
     if (!Array.isArray(selectedSteps) || selectedSteps.length === 0) {
-      throw new WorkflowStateError('VALIDATION_ERROR', 'custom research requires selected_steps');
+      throw new WorkflowStateError(
+        'WORKFLOW_RESEARCH_COVERAGE_REQUIRED',
+        'custom research requires model-selected coverage or selected_steps',
+      );
     }
-    const known = new Set(WORKFLOW_DEFINITIONS.research.map((item) => item.id));
     const invalid = selectedSteps.find((item) => !known.has(item));
     if (invalid) throw new WorkflowStateError('VALIDATION_ERROR', `unknown research step: ${invalid}`);
-    return [...new Set([...selectedSteps, '99-synthesis'])].map((stepId) => ({
+    const selectionReason = String(metadata.selection_reason || '').trim();
+    if (selectionReason.length < 3) {
+      throw new WorkflowStateError(
+        'WORKFLOW_SELECTION_REASON_REQUIRED',
+        'custom research requires the model\'s evidence-based coverage rationale',
+      );
+    }
+    const explicitCoverage = [...new Set([...selectedSteps, '99-synthesis'])].map((stepId) => ({
       step_id: stepId,
       disposition: 'execute',
-      rationale: String(metadata.selection_reason || 'Explicit bounded research selection.').trim(),
+      rationale: selectionReason,
       evidence_refs: [],
     }));
+    return normalizeResearchCoverage(mode, explicitCoverage, undefined, metadata);
   }
-  const selected = RESEARCH_MODES[mode];
-  if (!selected) throw new WorkflowStateError('VALIDATION_ERROR', `unsupported research mode: ${mode}`);
-  return selected.map((stepId) => ({
-    step_id: stepId,
-    disposition: 'execute',
-    rationale: String(metadata.selection_reason || `${mode} research profile selected by the host model.`).trim(),
-    evidence_refs: [],
-  }));
+  throw new WorkflowStateError(
+    'WORKFLOW_RESEARCH_COVERAGE_REQUIRED',
+    `${mode} research requires model-selected coverage dispositions`,
+  );
 }
 
 function assertReference(db, table, id, field) {
@@ -722,15 +741,7 @@ function assertWorkflowAuthority(db, input, mode) {
         'WORKFLOW_AUTHORITY_REQUIRED', 'research workflow requires baseline_id or change_id',
       );
     }
-    if (['product', 'feature', 'architecture', 'custom'].includes(mode)) {
-      requireField('change_id');
-      if (!String(input.metadata?.selection_reason || '').trim()) {
-        throw new WorkflowStateError(
-          'WORKFLOW_SELECTION_REASON_REQUIRED',
-          `${mode} research requires an explicit owner-selected scope reason`,
-        );
-      }
-    }
+    if (['product', 'feature', 'architecture', 'custom'].includes(mode)) requireField('change_id');
     if (input.baseline_id && !input.change_id) {
       const baseline = db.prepare('SELECT mode FROM baselines WHERE id = ?').get(input.baseline_id);
       const expectedMode = baseline?.mode === 'brownfield' ? 'adoption' : 'full';
@@ -887,7 +898,7 @@ function insertWorkflowInTx(db, input = {}, { rootDir = process.cwd() } = {}) {
     throw new WorkflowStateError('VALIDATION_ERROR', `unsupported workflow kind: ${input.kind}`);
   }
   input = bindChangeWorkflowAuthority(db, input);
-  const definition = WORKFLOW_DEFINITIONS[input.kind];
+  const catalogDefinition = WORKFLOW_DEFINITIONS[input.kind];
   const mode = input.kind === 'research' ? (input.mode || 'full') : null;
   assertWorkflowAuthority(db, input, mode);
   const id = input.id || `wf-${input.kind}-${crypto.randomUUID().slice(0, 12)}`;
@@ -957,6 +968,9 @@ function insertWorkflowInTx(db, input = {}, { rootDir = process.cwd() } = {}) {
     ? normalizeResearchCoverage(mode, input.coverage, input.selected_steps, input.metadata)
     : null;
   const coverageByStep = new Map((researchCoverage || []).map((item) => [item.step_id, item]));
+  const definition = input.kind === 'research'
+    ? catalogDefinition.filter((item) => coverageByStep.has(item.id))
+    : catalogDefinition;
   const selected = new Set(input.kind === 'research'
     ? researchCoverage
       .filter((item) => ['execute', 'verify_existing', 'reuse'].includes(item.disposition)
@@ -2380,7 +2394,6 @@ function recoverUntrackedChangeWorkflows(db, { rootDir = process.cwd() } = {}) {
 module.exports = {
   DEFINITION_VERSION,
   WORKFLOW_DEFINITIONS,
-  RESEARCH_MODES,
   RUN_KINDS,
   RUN_STATUSES,
   WorkflowStateError,

package/mcp-server/server.cjs

@@ -818,16 +818,28 @@ function appendHookLifecycleEvent({ rootDir, action, hookInput = {} } = {}) {
   const db = openStateDb(dbPath);
   try {
     ensureSchemaVersion(db);
-    const change = db.prepare(
-      `SELECT id FROM changes WHERE status IN ('active', 'blocked', 'ready')
+    const workflow = db.prepare(
+      `SELECT change_id, task_id FROM workflow_runs
+       WHERE status IN ('active', 'blocked', 'ready') AND change_id IS NOT NULL
        ORDER BY updated_at DESC, rowid DESC LIMIT 1`,
     ).get();
+    if (!workflow) return { recorded: false, reason: 'NO_ACTIVE_WORKFLOW' };
+    const change = db.prepare(
+      `SELECT id FROM changes
+       WHERE id = ? AND status IN ('active', 'blocked', 'ready')`,
+    ).get(workflow.change_id);
     if (!change) return { recorded: false, reason: 'NO_ACTIVE_CHANGE' };
-    const task = db.prepare(
-      `SELECT id FROM tasks WHERE change_id = ? AND status IN ('in_progress', 'pending', 'blocked')
-       ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END,
-                updated_at DESC, rowid DESC LIMIT 1`,
-    ).get(change.id);
+    const task = workflow.task_id
+      ? db.prepare(
+        `SELECT id FROM tasks
+         WHERE id = ? AND change_id = ?
+           AND status IN ('in_progress', 'pending', 'blocked')`,
+      ).get(workflow.task_id, change.id)
+      : db.prepare(
+        `SELECT id FROM tasks WHERE change_id = ? AND status IN ('in_progress', 'pending', 'blocked')
+         ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END,
+                  updated_at DESC, rowid DESC LIMIT 1`,
+      ).get(change.id);
     const payload = {
       agent_id: hookMetadata(hookInput.agent_id),
       agent_type: hookMetadata(hookInput.agent_type),

package/orchestrator/dispatch-rules.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-// Phase 8B.1 — Declarative dispatch rules (GSD-2 pattern).
+// Declarative dispatch rules for deterministic priority matching.
 //
 // evaluate(ctx, rules) walks a priority-sorted rule array and returns the
 // first matching { rule_id, action, runtime }. Actions:

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.17.1",
-  "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, Codex CLI, and Kimi Code.",
+  "version": "0.19.1",
+  "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, and Kimi Code, with project-local MCP authority and lifecycle recovery.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
     "ubp": "bin/install.js",
-    "ubp-handbook": "bin/handbook.js",
     "ubp-orchestrator": "bin/orchestrator.js",
     "ultra-tools": "ultra-tools/cli.cjs"
   },
@@ -54,9 +53,9 @@
     "docs/AGENT-CONTEXT.md",
     "docs/SKILL-AUTHORING.md",
     "docs/COMMIT-HASH-BACKFILL.md",
-    "docs/PLAN.zh-CN.md",
+    "docs/DECISIONS.md",
     "docs/STATE-DB-ACCESS-POLICY.md",
-    "docs/USER-HANDBOOK-CONTRACT.md",
+    "docs/PLUGIN-ISOLATION-CONTRACT.md",
     "docs/RUNTIME-COMPAT-MATRIX.md",
     "!**/__pycache__/**",
     "!**/*.pyc",

package/skills/ultra-change/SKILL.md

@@ -60,9 +60,10 @@ meaning is coupled. Downstream task, context, test, or review evidence affected
 change must become stale and be regenerated; never keep old evidence green by prompt
 assertion.
 
-If research is required, invoke `ultra-research` with the recorded disposition. If the
-contract is sufficiently evidenced, the host may recommend `ultra-plan`. `change.context`
-is compiled only for an actual plan, implementation, test, or review consumer.
+If research is required, recommend `ultra-research` with the recorded disposition. If
+the contract is sufficiently evidenced, recommend `ultra-plan`. Return and wait for an
+explicit user invocation; do not start either workflow. `change.context` is compiled
+only for an actual plan, implementation, test, or review consumer.
 
 Stable implementation discoveries use the approval-gated specification-learning
 transitions. External memory and graph providers retain their own content; Ultra stores

package/skills/ultra-init/SKILL.md

@@ -75,7 +75,8 @@ Read the returned `allowed_transitions` and `required_transition`:
 - a required transition represents a hard recovery invariant and must be followed;
 - otherwise the host model recommends among the allowed capabilities using the user's
   goal and current evidence;
-- start `ultra-research` only when the user invoked it or the host selects it after init.
+- never invoke another public Ultra workflow automatically; recommend the best allowed
+  capability and wait for an explicit user invocation.
 
 Report classification, scope, schema and backup result, Git state, init workflow id,
 baseline state, and allowed transitions. Do not claim that a baseline is ready until a

package/skills/ultra-research/SKILL.md

@@ -7,8 +7,8 @@ description: Build or refresh an evidence-backed product and architecture baseli
 
 The host model owns investigation, synthesis, and coverage judgment. Ultra MCP owns the
 run, evidence references, semantic records, artifact digests, freshness, and
-convergence. The seventeen areas are a coverage catalog, not a mandatory questionnaire
-or a fixed sequence of user conversations.
+convergence. The reference areas are an optional coverage catalog, not a mandatory
+questionnaire or a fixed sequence of user conversations.
 
 Read `../ultra-think/references/decision-dialogue.md` before asking a material question.
 
@@ -21,16 +21,19 @@ Read `../ultra-think/references/decision-dialogue.md` before asking a material q
    - `adoption` for a brownfield baseline;
    - a bounded mode only for a recorded active-change research disposition.
 4. Before `workflow.start`, inspect current code, docs, tests, runtime, and prior
-   artifacts. Provide one disposition for every catalog area in `full` or `adoption`:
+   artifacts. Select the smallest sufficient set of applicable catalog areas. Include
+   only areas that need work or whose exclusion must remain auditable:
    - `execute`: produce fresh evidence;
    - `verify_existing`: verify a current artifact against its source;
    - `reuse`: reuse evidence that is still current;
    - `not_applicable`: exclude with an evidence reference and rationale;
    - `deferred`: record the consequence and owner acceptance when deferral changes the
      accepted scope or leaves material risk.
+5. Pass the evidence-based coverage rationale as `metadata.selection_reason`. Omitted
+   catalog areas create no DB step and need no ceremonial disposition.
 
 `99-synthesis` must execute, verify, or reuse. A missing disposition is a coverage
-error; a non-executed area with evidence is not an incomplete workflow.
+error only for an included area; a recorded exclusion with evidence is not incomplete.
 
 ## Coverage catalog
 

package/spec/cli-protocol.md

@@ -1,11 +1,11 @@
 # `ultra-tools` CLI protocol
 
-`ultra-tools` is the maintenance CLI around the live MCP runtime (PLAN §4,
-D12). The mapping registry below reserves stable command names for MCP tools;
+`ultra-tools` is the maintenance CLI around the live MCP runtime. The mapping
+registry below reserves stable command names for MCP tools;
 it does not mean every mapping is executable. Task lifecycle workflows must use
 the live MCP server and fail closed when it is unavailable.
 
-Trace: PLAN §6 Phase 1.4, decisions D12 / D29 / D33 / D37.
+Authority boundary: [`docs/DECISIONS.md`](../docs/DECISIONS.md).
 
 ## 1. Invocation
 
@@ -159,7 +159,7 @@ The full access policy lives in
 The CLI follows the `version` field of `spec/mcp-tools.yaml`. Adding a new
 flag is a minor bump; renaming or removing a flag, or changing exit-code
 semantics, is a major bump. Major bumps require an entry in
-`docs/PLAN.zh-CN.md §14 Decision log`.
+[`docs/DECISIONS.md`](../docs/DECISIONS.md) and the changelog.
 
 ## 7. `ubp-orchestrator`
 

package/spec/mcp-tools.yaml

@@ -1,14 +1,14 @@
 # Ultra Builder Pro — MCP tool contracts
 # Single source for tool name, schema, errors, and CLI mapping.
 # Validated by spec/schemas/mcp-tools.schema.json (run `npm run test:spec`).
-# Trace: PLAN §7.3, decisions D12 / D29 / D31-D34.
+# Current authority boundary: docs/DECISIONS.md.
 
 version: '1.3'
 
 info:
   title: Ultra Builder Pro MCP tool contracts
   phase: '1.2'
-  trace_to: 'PLAN docs/PLAN.zh-CN.md §7.3'
+  trace_to: 'docs/DECISIONS.md and mcp-server/server.cjs'
   notes: |
     This published contract contains only tools registered by the MCP server.
     Host-native review, impact, skill discovery, and human-interaction capabilities
@@ -397,7 +397,7 @@ tools:
       - { code: IO_ERROR,          description: 'filesystem write failed', retriable: true }
     cli_subcommand: task init-project
     emits_events: [project_initialized, project_resumed]
-    trace_to: 'PLAN §6 Phase 3.1'
+    trace_to: 'mcp-server/lib/init-project.cjs'
 
   - name: task.expand
     family: task
@@ -1833,7 +1833,7 @@ tools:
   # ────────────────────────── workflow family ────────────────────────────
   - name: workflow.start
     family: workflow
-    description: Start one durable Ultra workflow run. For full or adoption research, the host model must disposition every semantic coverage area without being forced to execute every area.
+    description: Start one durable Ultra workflow run. For research, the host model supplies only evidence-relevant semantic coverage; MCP records and validates the selection without choosing it.
     phase: '13'
     writer_role: mcp
     input_schema:
@@ -1883,11 +1883,11 @@ tools:
       - { code: WORKFLOW_AUTHORITY_REQUIRED, description: 'the workflow is missing its required baseline, change, or task authority' }
       - { code: WORKFLOW_CHANGE_DECISION_BLOCKING, description: 'the change contains unresolved material owner decisions' }
       - { code: WORKFLOW_CHANGE_RESEARCH_INCOMPLETE, description: 'the change-bound research disposition is not current and complete' }
-      - { code: WORKFLOW_RESEARCH_COVERAGE_REQUIRED, description: 'full and adoption research require a disposition for every semantic area' }
+      - { code: WORKFLOW_RESEARCH_COVERAGE_REQUIRED, description: 'research requires model-selected coverage with at least one applicable semantic area beyond synthesis' }
       - { code: WORKFLOW_RESEARCH_COVERAGE_EVIDENCE_REQUIRED, description: 'reuse, verification, and not-applicable dispositions require evidence references' }
       - { code: WORKFLOW_RESEARCH_SYNTHESIS_REQUIRED, description: 'research synthesis must execute, verify, or reuse durable evidence' }
       - { code: WORKFLOW_RESEARCH_MODE_MISMATCH, description: 'the selected research mode does not match its authority or baseline mode' }
-      - { code: WORKFLOW_SELECTION_REASON_REQUIRED, description: 'bounded research requires an explicit owner-selected scope reason' }
+      - { code: WORKFLOW_SELECTION_REASON_REQUIRED, description: 'research requires the model evidence rationale for its selected coverage' }
       - { code: TASK_EXECUTION_CONTRACT_INCOMPLETE, description: 'dev cannot start until the linked task contract is executable' }
       - { code: TASK_CHANGE_OWNERSHIP_MISMATCH, description: 'linked task and change authority disagree' }
       - { code: TASK_DEPENDENCIES_INCOMPLETE, description: 'dev cannot start while a task dependency remains incomplete' }

package/spec/schemas/context-file.v4.5.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ultra-builder-pro.dev/spec/context-file.v4.5.schema.json",
   "title": "context-file projection (v4.5)",
-  "description": "Schema for the parsed representation of .ultra/tasks/contexts/task-*.md. The header is regenerated by the projector from state.db (D32). Body sections are author-owned; status MUST NOT appear in body. Trace: PLAN §7.1, D17, D21.",
+  "description": "Schema for the parsed representation of .ultra/tasks/contexts/task-*.md. The header is regenerated by the projector from state.db. Body sections are author-owned; status MUST NOT appear in body. Authority boundary: docs/DECISIONS.md.",
   "type": "object",
   "required": ["header", "body"],
   "additionalProperties": false,

package/spec/schemas/mcp-tools.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ultra-builder-pro.dev/spec/mcp-tools.schema.json",
   "title": "MCP tools manifest",
-  "description": "Meta-schema describing the shape of spec/mcp-tools.yaml. The manifest itself is the single source for MCP tool contracts (PLAN R19).",
+  "description": "Meta-schema describing the shape of spec/mcp-tools.yaml. The manifest is the single source for published MCP tool contracts.",
   "type": "object",
   "required": ["version", "info", "tools"],
   "additionalProperties": false,
@@ -56,7 +56,7 @@
         "name": {
           "type": "string",
           "pattern": "^[a-z][a-z_]*\\.[a-z][a-z_]*$",
-          "description": "family.verb naming convention (PLAN §7.3)"
+          "description": "family.verb naming convention"
         },
         "family": {
           "type": "string",
@@ -103,7 +103,7 @@
         },
         "trace_to": {
           "type": "string",
-          "description": "PLAN section/decision id (e.g. §7.3, D33)"
+          "description": "current source or decision reference"
         }
       }
     },

package/spec/schemas/state-db.sql

@@ -1,9 +1,9 @@
 -- Ultra Builder Pro — authoritative state schema
--- Phase 2 builds .ultra/state.db from this file. Source of truth for all
+-- This file builds .ultra/state.db, the source of truth for all
 -- baseline / change / task / session / event / telemetry data. tasks.json and context md status
--- header are projections (PLAN §7.1, D18, D32).
+-- headers are projections.
 --
--- Trace: docs/PLAN.zh-CN.md §7.1; decisions D18/D30/D31/D32/D37/D52/D54.
+-- Authority boundary: docs/DECISIONS.md.
 --
 -- PRAGMAs are applied by mcp-server/lib/state-db.ts on connection open;
 -- they cannot be persisted in CREATE statements but are documented here.

package/spec/schemas/tasks.v4.5.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ultra-builder-pro.dev/spec/tasks.v4.5.schema.json",
   "title": "tasks.json projection (v4.5)",
-  "description": "Read-only projection of the tasks table. Generated by the projector (Phase 2.6) — manual edits are overwritten. Status and dependencies are derived from state.db; do not write them through this file. Trace: PLAN §7.1, D21, D32.",
+  "description": "Read-only projection of the tasks table. Generated by the projector; manual edits are overwritten. Status and dependencies are derived from state.db. Authority boundary: docs/DECISIONS.md.",
   "type": "object",
   "required": ["schema_version", "generated_at", "tasks"],
   "additionalProperties": false,

package/adapters/_shared/handbook.cjs

@@ -1,156 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-
-const { writeAtomic } = require('./file-ops.cjs');
-
-const BEGIN_MARKER = '<!-- ultra-builder-pro:handbook:start -->';
-const END_MARKER = '<!-- ultra-builder-pro:handbook:end -->';
-const LEGACY_HEADING = '## Ultra Builder Pro Runtime Contract';
-
-const HOSTS = Object.freeze({
-  claude: Object.freeze({
-    name: 'Claude Code',
-    handbook: ['.claude', 'CLAUDE.md'],
-    invocation: '`/ultra-init`, `/ultra-research`, `/ultra-plan`, `/ultra-change`, `/ultra-dev`, `/ultra-test`, `/ultra-review`, and `/ultra-deliver`; diagnostics use `/ultra-status`, `/ultra-think`, and `/ultra-doctor`',
-    collaboration: '`/codex-collab` is an explicitly requested read-only advisor',
-    coordination: 'Claude Code task UI is host coordination; it does not replace Ultra task state',
-  }),
-  codex: Object.freeze({
-    name: 'Codex',
-    handbook: ['.codex', 'AGENTS.md'],
-    invocation: '`$ultra-builder-pro:ultra-init`, `$ultra-builder-pro:ultra-research`, `$ultra-builder-pro:ultra-plan`, `$ultra-builder-pro:ultra-change`, `$ultra-builder-pro:ultra-dev`, `$ultra-builder-pro:ultra-test`, `$ultra-builder-pro:ultra-review`, and `$ultra-builder-pro:ultra-deliver`; diagnostics use `$ultra-builder-pro:ultra-status`, `$ultra-builder-pro:ultra-think`, and `$ultra-builder-pro:ultra-doctor`',
-    collaboration: '`$ultra-builder-pro:cc-collab` is an explicitly requested read-only advisor',
-    coordination: 'The Codex plan is turn-facing coordination; it does not replace Ultra task state',
-  }),
-  opencode: Object.freeze({
-    name: 'OpenCode',
-    handbook: ['.config', 'opencode', 'AGENTS.md'],
-    invocation: '`/ultra-init`, `/ultra-research`, `/ultra-plan`, `/ultra-change`, `/ultra-dev`, `/ultra-test`, `/ultra-review`, and `/ultra-deliver`; diagnostics use `/ultra-status`, `/ultra-think`, and `/ultra-doctor`',
-    collaboration: '`/cc-collab` and `/codex-collab` are explicitly requested read-only advisors',
-    coordination: 'OpenCode session coordination does not replace Ultra task state',
-  }),
-  kimi: Object.freeze({
-    name: 'Kimi Code',
-    handbook: ['.kimi-code', 'AGENTS.md'],
-    invocation: '`/ultra-builder-pro:ultra-init`, `/ultra-builder-pro:ultra-research`, `/ultra-builder-pro:ultra-plan`, `/ultra-builder-pro:ultra-change`, `/ultra-builder-pro:ultra-dev`, `/ultra-builder-pro:ultra-test`, `/ultra-builder-pro:ultra-review`, and `/ultra-builder-pro:ultra-deliver`; diagnostics use `/ultra-builder-pro:ultra-status`, `/ultra-builder-pro:ultra-think`, and `/ultra-builder-pro:ultra-doctor`',
-    collaboration: '`/skill:cc-collab` and `/skill:codex-collab` are explicitly requested read-only advisors',
-    coordination: 'Kimi `TodoList` and `Agent` / `AgentSwarm` are host coordination; they do not replace Ultra task state',
-  }),
-});
-
-function host(runtime) {
-  const value = HOSTS[runtime];
-  if (!value) throw new Error(`unsupported handbook runtime: ${runtime}`);
-  return value;
-}
-
-function renderHandbook(runtime) {
-  const value = host(runtime);
-  return [
-    BEGIN_MARKER,
-    '## Ultra Builder Pro Runtime Contract',
-    '',
-    `Ultra Builder Pro is installed as a native ${value.name} plugin. Keep general engineering`,
-    'policy in this handbook and detailed Ultra procedures in the plugin skills.',
-    '',
-    `- Workflow entry points: ${value.invocation}.`,
-    `- Collaboration boundary: ${value.collaboration}. The current host remains primary and owns final verification.`,
-    `- Coordination boundary: ${value.coordination}.`,
-    '- Authority: `.ultra/state.db` is the only durable Ultra authority for baselines, changes, decision threads, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
-    '- Baseline boundary: `task.init_project` classifies greenfield or brownfield work and records repository scope. Projection-only prior state uses the exact supported backup-first import returned by the authority check; migrated compatibility rows require explicit brownfield re-adoption. `baseline.record` owns evidence, verification, repository snapshot, and the gap ledger; `baseline.converge` requires explicit owner approval. New ordinary changes require a healthy ready baseline. Existing active work may continue with warnings, but baseline readiness blocks change convergence; normal drift reconciliation is health-checked atomically at archive. Only an explicitly approved incident break-glass may start without baseline readiness, and its archive creates a blocking reconciliation gap.',
-    '- Decision boundary: project-bound owner choices use one resumable DB-backed decision thread. The host resolves observable facts autonomously, presents only the earliest unresolved decision with evidence and a recommendation, waits for the owner, and records the normalized decision rather than prompts or transcripts. A linked workflow cannot advance until blocking decisions are resolved and its owner-approved checkpoint is current.',
-    '- Context Spine boundary: `change.context` compiles role/gate readiness, required references, a fresh-context budget, public seam, verification command, Change/task authority digests, allowed transitions, and any unique hard-recovery transition. File, token, and context-share budgets are advisory attention signals, not refusal gates. The host owns semantic recommendations. Hooks inject only the DB-derived `change.breadcrumb`; missing required evidence or stale execution context must be recompiled.',
-    '- Specification learning boundary: stable implementation discoveries use approval-gated propose/approve-or-reject/apply transitions. Unresolved learning blocks convergence; review requires independent specification-fidelity and engineering-standards evidence.',
-    '- Memory and graph boundary: Ultra Builder Pro does not capture prompts, transcripts, observations, summaries, cross-session memory, or code-graph content. Separately installed providers own that data; Ultra may store only their metadata references in a change context manifest.',
-    '- Hook boundary: Ultra hooks observe workflow/change lifecycle only. Health/context may run when `.ultra/state.db` exists; advisory warnings never reject work, and an incomplete workflow never traps session stop. Direct projection protection remains authoritative; compact and subagent recovery stays active-workflow scoped. Generic command blocking and post-edit policy stay in user or repository governance.',
-    '- Installation boundary: `ubp --doctor` is the read-only authority for installed asset provenance, content hashes, and host entry-point wiring. Project `system.doctor` diagnoses state and performs only authorized backup-first schema, projection, session, and archive-journal recovery; it never approves a baseline.',
-    '- Agent boundary: the bundled review and debugging agents are bounded workers. They use the current checkout and parent-supplied context, do not own private persistent state, and never replace the primary agent.',
-    '- Package boundary: only the twelve Ultra workflows, four internal review-rule skills, host-specific collaboration companions, and the minimal host bootstrap belong to this plugin. General browser, deployment, discovery, and framework skills must be installed from their owners.',
-    END_MARKER,
-  ].join('\n');
-}
-
-function markerCount(text, marker) {
-  return text.split(marker).length - 1;
-}
-
-function replaceManagedBlock(existing, block) {
-  const beginCount = markerCount(existing, BEGIN_MARKER);
-  const endCount = markerCount(existing, END_MARKER);
-  if (beginCount !== endCount || beginCount > 1) {
-    throw new Error('handbook contains malformed or duplicate Ultra managed markers');
-  }
-  if (beginCount === 0) return null;
-
-  const start = existing.indexOf(BEGIN_MARKER);
-  const end = existing.indexOf(END_MARKER, start) + END_MARKER.length;
-  return existing.slice(0, start) + block + existing.slice(end);
-}
-
-function replaceLegacyCodexSection(existing, block) {
-  const heading = new RegExp(`^${LEGACY_HEADING.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[^\\n]*$`, 'm');
-  const match = heading.exec(existing);
-  if (!match) return null;
-
-  const start = match.index;
-  const remainder = existing.slice(start + match[0].length);
-  const nextHeading = /^##\s+/m.exec(remainder);
-  const end = nextHeading ? start + match[0].length + nextHeading.index : existing.length;
-  const before = existing.slice(0, start).trimEnd();
-  const after = existing.slice(end).trimStart();
-  return `${before}${before ? '\n\n' : ''}${block}${after ? `\n\n${after}` : '\n'}`;
-}
-
-function mergeHandbook(existing, runtime) {
-  host(runtime);
-  const current = typeof existing === 'string' ? existing : '';
-  const block = renderHandbook(runtime);
-  const managed = replaceManagedBlock(current, block);
-  if (managed !== null) return managed;
-
-  if (runtime === 'codex') {
-    const migrated = replaceLegacyCodexSection(current, block);
-    if (migrated !== null) return migrated;
-  }
-
-  const before = current.trimEnd();
-  return `${before}${before ? '\n\n' : ''}${block}\n`;
-}
-
-function resolveHandbookFile(runtime, { homeDir = os.homedir() } = {}) {
-  return path.join(homeDir, ...host(runtime).handbook);
-}
-
-function timestamp() {
-  return new Date().toISOString().replace(/[-:.]/g, '').replace(/\.\d{3}Z$/, 'Z');
-}
-
-function applyHandbook({ runtime, file, homeDir, now = timestamp() }) {
-  const target = path.resolve(file || resolveHandbookFile(runtime, { homeDir }));
-  const exists = fs.existsSync(target);
-  const existing = exists ? fs.readFileSync(target, 'utf8') : '';
-  const merged = mergeHandbook(existing, runtime);
-  if (merged === existing) return { runtime, file: target, changed: false, backup: null };
-
-  let backup = null;
-  if (exists) {
-    backup = `${target}.ubp-backup-${now}`;
-    if (fs.existsSync(backup)) throw new Error(`handbook backup already exists: ${backup}`);
-    writeAtomic(backup, existing);
-  }
-  writeAtomic(target, merged);
-  return { runtime, file: target, changed: true, backup };
-}
-
-module.exports = {
-  BEGIN_MARKER,
-  END_MARKER,
-  HOSTS,
-  applyHandbook,
-  mergeHandbook,
-  renderHandbook,
-  resolveHandbookFile,
-};