ultra-builder-pro-cli 0.17.1 → 0.18.0

package/docs/USER-HANDBOOK-CONTRACT.md

@@ -1,45 +1,46 @@
 # 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.
+Ultra Builder Pro has two explicit handbook modes:
+
+- default mode owns only one small managed section describing the Ultra runtime;
+- full mode installs a complete host-native engineering handbook when the owner
+  explicitly chooses to replace legacy unmarked prompt content.
+
+Neither mode runs implicitly during plugin installation. Existing files are backed
+up before mutation, and full mode preserves other provider-owned marker blocks.
 
 ## Source and render targets
 
-`adapters/_shared/handbook.cjs` is the canonical source. It renders the common
-authority, baseline adoption, decision dialogue, Context Spine, specification-learning,
-memory, hook, agent, and package boundaries with host-native command syntax:
+`adapters/_shared/handbook.cjs` is the canonical source. It renders both the bounded
+runtime contract and the complete engineering handbook with host-native command,
+interaction, coordination, delegation, and durable-file semantics:
 
 | Runtime | Default target | Main invocation form |
 |---|---|---|
-| Claude Code | `~/.claude/CLAUDE.md` | `/ultra-plan` |
+| Claude Code | `~/.claude/CLAUDE.md` | `/ultra-builder-pro:ultra-plan` |
 | Codex | `~/.codex/AGENTS.md` | `$ultra-builder-pro:ultra-plan` |
 | OpenCode | `~/.config/opencode/AGENTS.md` | `/ultra-plan` |
 | Kimi Code | `~/.kimi-code/AGENTS.md` | `/ultra-builder-pro:ultra-plan` |
 
 The renderer never copies Claude Code-only APIs into Codex, OpenCode, or Kimi. Each
-host receives only its native invocation and collaboration names.
+host receives only its native invocation, collaboration, interaction, and worker
+language.
 
-The managed block deliberately stays short. It says that `.ultra/state.db` is
-authoritative; `change.context` compiles role/gate readiness, bounded references,
-fresh-context budget, public seam, and exact verification; size budgets are advisory,
-new ordinary work requires a healthy baseline, existing active work may continue with
-warnings, and only an approved incident break-glass may start without baseline
-readiness; ordinary archive restores baseline health while break-glass archive records
-a blocking reconciliation gap; hooks inject only the DB-derived
-`change.breadcrumb`; and unresolved specification learning or either failed review
-axis blocks convergence. Detailed procedures remain in the plugin skills so user
-handbooks do not accumulate duplicated prompt sediment.
+The default managed block deliberately stays short. It says that `.ultra/state.db`
+is authoritative; `change.context` compiles role/gate readiness, bounded references,
+fresh-context budget, public seam, and exact verification; size budgets are advisory;
+new ordinary work requires a healthy baseline; and only an approved incident
+break-glass may start without baseline readiness. It explicitly separates user intent,
+host-model judgment, MCP mechanics, host-adapter presentation, and hook lifecycle
+responsibilities. It also records the decision, specification-learning, memory, agent,
+and package boundaries.
 
-The decision boundary is intentionally short but normative: project-bound owner
-choices use one resumable DB-backed thread; the host resolves observable facts first,
-presents only one current decision with evidence and a recommendation, and stores the
-normalized result rather than conversation text. Matching workflows remain gated until
-blocking choices are resolved and the owner-approved artifact checkpoint is current.
+Detailed procedures remain in the plugin skills so neither handbook mode duplicates
+workflow implementation steps.
 
-## Managed-block contract
+## Managed-block contracts
 
-The owned content is bounded by:
+Default mode owns only:
 
 ```markdown
 <!-- ultra-builder-pro:handbook:start -->
@@ -49,33 +50,71 @@ The owned content is bounded by:
 
 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
+the first default apply can migrate an old unmarked
 `## Ultra Builder Pro Runtime Contract` section up to the next level-two heading.
 
+Full mode owns:
+
+```markdown
+<!-- ultra-builder-pro:full-handbook:start -->
+...
+<!-- ultra-builder-pro:full-handbook:end -->
+```
+
+On first full apply, unmarked legacy prompt content is replaced. Marker-delimited
+content owned by another provider is retained before the Ultra full-handbook region.
+Both `provider:start` / `provider:end` and `BEGIN provider` / `END provider`
+comment forms are supported. Repeated blocks remain repeated, and blocks nested
+inside an old Ultra full region are extracted before that region is replaced. Later
+full applies produce the same canonical output and keep each retained block
+byte-for-byte intact.
+
+Because full apply intentionally removes unmarked content, a current preview is
+enforced rather than merely documented. The confirmation token binds the runtime,
+target path, existing content, and rendered result; missing or stale tokens are
+rejected before any file changes.
+
 ## Safe workflow
 
-Preview the full merged result before applying:
+Preview and apply only the runtime contract:
 
 ```bash
 ubp-handbook preview --runtime claude
 ubp-handbook preview --runtime codex
 ubp-handbook preview --runtime opencode
 ubp-handbook preview --runtime kimi
-```
 
-Apply when the preview is correct:
-
-```bash
 ubp-handbook apply --runtime claude
 ubp-handbook apply --runtime codex
 ubp-handbook apply --runtime opencode
 ubp-handbook apply --runtime kimi
 ```
 
-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.
+Converge a legacy complete handbook through explicit full mode:
+
+```bash
+ubp-handbook preview --runtime codex --full > /tmp/ubp-codex-handbook.md
+# Inspect /tmp/ubp-codex-handbook.md and copy the token printed to the terminal.
+ubp-handbook apply --runtime codex --full \
+  --confirm "PASTE_64_CHARACTER_TOKEN_HERE"
+```
+
+Repeat with `claude`, `opencode`, or `kimi` as the runtime. An existing target is
+copied to `<file>.ubp-backup-<timestamp>` before atomic replacement. A handbook
+symlink remains a symlink and the resolved target's POSIX mode is retained.
+Re-running either apply mode with the same rendered content is a no-op and creates
+no additional backup.
+
+The plugin installer intentionally applies neither mode. A plugin update and a
+durable user-handbook change have different rollback and review requirements.
+
+## Ownership boundaries
+
+The complete handbook defines general engineering and collaboration behavior, but it
+does not install or invoke external memory, graph, browser, deployment, discovery, or
+framework skills. Those providers retain their own installation, prompts, credentials,
+and lifecycle. Ultra records only the minimum provider references required for workflow
+provenance.
 
-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.
+Host adaptation is semantic, not textual substitution. A foreign tool name or prompt
+mechanism must never be made “compatible” by changing only its path or product name.

package/docs/WORKFLOW-LIFECYCLE.md

@@ -35,12 +35,13 @@ authority, and no new stage may start on an archived or cancelled change. Doctor
 recovers a legacy change without this link into an explicitly blocked workflow;
 it does not fabricate the missing provenance.
 
-Ultra does not select an MVP. Product scope and material delivery posture are owner
-decisions. The seventeen research areas are a coverage catalog, not a forced
-questionnaire. Initial greenfield and brownfield research must disposition every area
-as `execute`, `verify_existing`, `reuse`, `not_applicable`, or accepted `deferred`;
-only selected necessary work executes. Bounded change research records the same
-selection rationale over its smaller scope.
+Ultra does not select product scope or material delivery posture; those remain user
+decisions. Research references form an optional catalog, not a forced questionnaire.
+The host model selects only evidence-relevant areas and records one coverage rationale.
+MCP validates identifiers, dispositions, evidence requirements, synthesis, and at
+least one applicable semantic area. Omitted areas create no workflow step. An explicit
+`not_applicable` or accepted `deferred` row is retained only when its exclusion is
+material.
 
 ## 2. How `ultra-init` classifies a repository
 
@@ -325,7 +326,7 @@ current gate evidence do block.
 
 ```text
 ultra-init -> Git/scaffold/authority verification -> init completed
--> explicit ultra-research -> disposition 17 coverage areas -> selected evidence work
+-> explicit ultra-research -> model-selected coverage -> selected evidence work
 -> local checkpoint when Git is unborn -> baseline approval
 -> ultra-change -> optional bounded research/plan -> dev -> risk-selected test/review
 -> local deliver/archive
@@ -335,7 +336,7 @@ ultra-init -> Git/scaffold/authority verification -> init completed
 
 ```text
 ultra-init -> preserve Git/classify brownfield -> init completed
--> explicit adoption research -> disposition 17 coverage areas
+-> explicit adoption research -> model-selected coverage
 -> selected characterization/known-red evidence -> gap ledger -> owner approval
 -> first ultra-change -> optional bounded research/plan -> dev -> test/review -> deliver
 ```
@@ -389,8 +390,9 @@ parallel workflow or substitutes a Prompt summary for DB state.
 
 ## 9. Recovery and diagnosis
 
-Use `system.doctor` for project authority and `ubp --doctor` for installed host
-assets. Both are read-only unless an explicit project repair command is chosen.
+Use `system.doctor` for project authority and
+`ubp --all --global --doctor` for installed host assets. Both are read-only
+unless an explicit project repair command is chosen.
 
 During an explicit repair, a legacy active change that predates durable workflows gets
 one blocked change run at `bind-baseline` with

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/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,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "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.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
@@ -54,7 +54,7 @@
     "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/RUNTIME-COMPAT-MATRIX.md",

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,