ultra-builder-pro-cli 0.11.0 → 0.13.0

package/spec/mcp-tools.yaml

@@ -3,11 +3,11 @@
 # Validated by spec/schemas/mcp-tools.schema.json (run `npm run test:spec`).
 # Trace: PLAN §7.3, decisions D12 / D29 / D31-D34.
 
-version: '1.1'
+version: '1.2'
 
 info:
   title: Ultra Builder Pro MCP tool contracts
-  phase: '1.1'
+  phase: '1.2'
   trace_to: 'PLAN docs/PLAN.zh-CN.md §7.3'
   notes: |
     This published contract contains only tools registered by the MCP server.
@@ -23,6 +23,7 @@ families:
   - { name: task,    description: 'authoritative task lifecycle on state.db', phase: '2' }
   - { name: session, description: 'execution-unit lifecycle with single-active-lease admission (D33)', phase: '4.5' }
   - { name: plan,    description: 'execution-plan artifact export and query (D34)', phase: '8a' }
+  - { name: baseline, description: 'project adoption, baseline evidence, convergence, and drift authority', phase: '11' }
   - { name: change,  description: 'continuous post-delivery change lifecycle and convergence', phase: '9' }
   - { name: system,  description: 'read-only diagnostics and explicit backup-first repair', phase: '9' }
 
@@ -31,7 +32,7 @@ tools:
   # ─────────────────────────── task family ────────────────────────────────
   - name: task.create
     family: task
-    description: Create a new task in state.db. Emits task_created event. If `id` is omitted the server mints a uuid.
+    description: Create a new task in state.db. Emits task_created event. If `id` is omitted the server mints a uuid. Child tasks inherit the parent's change ownership; conflicting ownership is rejected.
     phase: '2'
     writer_role: mcp
     input_schema:
@@ -47,10 +48,10 @@ tools:
         estimated_days: { type: number, exclusiveMinimum: 0, description: 'estimated implementation effort in days' }
         deps:           { type: array, items: { type: string } }
         files_modified: { type: array, items: { type: string }, description: 'Phase 8A conflict detection' }
-        parent_id:      { type: string, description: 'Phase 8A.3 parent reference for task.expand children' }
+        parent_id:      { type: string, description: 'Phase 8A.3 parent reference; the child inherits this task change ownership' }
         tag:            { type: string, description: 'git branch tag (Phase 7.2)' }
         trace_to:       { type: string, description: 'spec anchor (e.g. spec/mcp-tools.yaml#task.create)' }
-        change_id:      { type: string, pattern: '^[a-zA-Z0-9_\-]+$', description: 'continuous change unit owning this task' }
+        change_id:      { type: string, pattern: '^[a-zA-Z0-9_\-]+$', description: 'active or blocked continuous change unit owning this task; inherited from parent_id when omitted' }
     output_schema:
       type: object
       required: [id, status, created_at]
@@ -62,6 +63,11 @@ tools:
     errors:
       - { code: VALIDATION_ERROR, description: 'input failed schema validation' }
       - { code: DUPLICATE_TASK_ID, description: 'task id already exists' }
+      - { code: TASK_NOT_FOUND, description: 'parent task does not exist' }
+      - { code: CHANGE_NOT_FOUND, description: 'assigned change does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'assigned change no longer accepts tasks' }
+      - { code: TASK_CHANGE_OWNERSHIP_MISMATCH, description: 'child ownership conflicts with its parent change' }
+      - { code: BASELINE_NOT_READY, description: 'ordinary task creation requires a ready baseline or an already-authorized active change' }
       - { code: LEGACY_STATE_MIGRATION_REQUIRED, description: 'non-empty v4.4 projection must be migrated before state-backed tools can run' }
       - { code: STATE_DB_LOCKED, description: 'database is locked', retriable: true }
     cli_subcommand: task create
@@ -105,6 +111,9 @@ tools:
       - { code: TASK_NOT_FOUND, description: 'no task with given id' }
       - { code: ILLEGAL_STATUS_TRANSITION, description: 'transition rejected by state machine' }
       - { code: VALIDATION_ERROR, description: 'patch failed schema validation' }
+      - { code: CHANGE_NOT_FOUND, description: 'assigned change does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'assigned change no longer accepts task updates' }
+      - { code: TASK_CHANGE_OWNERSHIP_MISMATCH, description: 'task ownership conflicts with its parent or children' }
       - { code: LEGACY_STATE_MIGRATION_REQUIRED, description: 'non-empty v4.4 projection must be migrated before state-backed tools can run' }
     cli_subcommand: task update
     emits_events: [task_started, task_completed, task_blocked, task_stale_marked]
@@ -217,9 +226,9 @@ tools:
   - name: task.init_project
     family: task
     description: |
-      Bootstrap a fresh `.ultra/` skeleton in target_dir from the bundled
-      templates/.ultra/ source. Copies spec templates, tasks.json, context
-      template, and report stubs. Phase 3.1 entry point for /ultra-init.
+      Bootstrap `.ultra/` and start an authoritative greenfield or brownfield
+      baseline. Auto mode detects meaningful existing project content before
+      copying specification templates and creating state.db.
     phase: '3'
     writer_role: mcp
     input_schema:
@@ -240,6 +249,22 @@ tools:
         stack:
           type: string
           description: optional tech stack descriptor (comma-separated for fullstack)
+        mode:
+          type: string
+          enum: [auto, greenfield, brownfield]
+          default: auto
+          description: auto detects whether meaningful project content already exists
+        resume:
+          type: boolean
+          default: false
+          description: preserve an existing `.ultra/`, upgrade its schema, and install only missing current scaffold files
+        scope:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items: { type: string, minLength: 1 }
+          default: ['.']
+          description: project-relative repository roots governed by the initial baseline
         overwrite:
           type: boolean
           default: false
@@ -249,7 +274,7 @@ tools:
           description: override path to the template root (defaults to bundled templates/.ultra/)
     output_schema:
       type: object
-      required: [created_path, state_db_path, status, copied_files]
+      required: [created_path, state_db_path, status, mode, baseline, copied_files, repository_profile]
       additionalProperties: false
       properties:
         created_path:
@@ -260,21 +285,38 @@ tools:
           description: absolute path to the initialized authoritative SQLite database
         status:
           type: string
-          enum: [created, overwritten]
+          enum: [created, overwritten, resumed]
+        mode:
+          type: string
+          enum: [greenfield, brownfield]
+        baseline:
+          type: object
+          required: [id, mode, status, scope]
+          additionalProperties: true
         copied_files:
           type: array
           items: { type: string }
           description: paths relative to created_path
+        repository_profile:
+          type: object
+          description: bounded classification evidence used to route greenfield or brownfield adoption
         backup_path:
           type: string
           description: set only when status=overwritten
+        migration_backup_path:
+          type: string
+          description: pre-migration database backup created while resuming an older schema
     errors:
       - { code: ULTRA_DIR_EXISTS,  description: '.ultra/ already exists and overwrite=false' }
       - { code: TEMPLATE_MISSING,  description: 'source_template path does not exist' }
       - { code: TARGET_NOT_DIR,    description: 'target_dir is not a directory' }
+      - { code: BASELINE_SCOPE_MISSING, description: 'a selected baseline scope does not exist' }
+      - { code: LEGACY_STATE_MIGRATION_REQUIRED, description: 'projection-only tasks must be imported before resume' }
+      - { code: STATE_AUTHORITY_CONFLICT, description: 'projection tasks and authoritative state cannot be reconciled automatically' }
+      - { code: STATE_PROJECTION_INVALID, description: 'the existing task projection is malformed' }
       - { code: IO_ERROR,          description: 'filesystem write failed', retriable: true }
     cli_subcommand: task init-project
-    emits_events: [project_initialized]
+    emits_events: [project_initialized, project_resumed]
     trace_to: 'PLAN §6 Phase 3.1'
 
   - name: task.expand
@@ -300,6 +342,9 @@ tools:
     errors:
       - { code: TASK_NOT_FOUND, description: 'parent id missing' }
       - { code: ALREADY_EXPANDED, description: 'task is already expanded' }
+      - { code: CHANGE_NOT_FOUND, description: 'the parent task change does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'the parent task change no longer accepts children' }
+      - { code: BASELINE_NOT_READY, description: 'child creation requires a ready baseline or the parent task to belong to an already-authorized active change' }
     cli_subcommand: task expand
     emits_events: [task_expanded]
     trace_to: '§7.3, D34'
@@ -316,6 +361,7 @@ tools:
         prd_path: { type: string }
         prd_text: { type: string }
         tag:      { type: string }
+        change_id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$', description: 'continuous change unit that will own every persisted parsed task' }
         dry_run:  { type: boolean, default: false, description: 'when true, do not persist to state.db — used by ultra-plan gate to preview before approve' }
     output_schema:
       type: object
@@ -327,6 +373,9 @@ tools:
     errors:
       - { code: NO_INPUT, description: 'one of prd_path or prd_text required' }
       - { code: PARSE_FAILED, description: 'PRD could not be parsed into tasks' }
+      - { code: CHANGE_NOT_FOUND, description: 'assigned change does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'assigned change no longer accepts tasks' }
+      - { code: BASELINE_NOT_READY, description: 'persisting parsed tasks requires a ready baseline or an already-authorized active change' }
     cli_subcommand: task parse-prd
     emits_events: [task_created]
     trace_to: '§7.3, D34'
@@ -629,6 +678,250 @@ tools:
     emits_events: []
     trace_to: '§7.3, D31'
 
+  # ───────────────────────── baseline family ─────────────────────────────
+  - name: baseline.start
+    family: baseline
+    description: Start a greenfield baseline or brownfield adoption without overwriting a ready baseline implicitly.
+    phase: '11'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [project_name, mode]
+      additionalProperties: false
+      allOf:
+        - if:
+            required: [replace_ready]
+            properties: { replace_ready: { const: true } }
+          then: { required: [replacement_authorization] }
+        - if: { required: [replacement_authorization] }
+          then:
+            required: [replace_ready]
+            properties: { replace_ready: { const: true } }
+      properties:
+        id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$', default: project-baseline }
+        project_name: { type: string, minLength: 1 }
+        project_type: { type: string, enum: [web, api, cli, fullstack, other] }
+        stack: { type: string }
+        mode: { type: string, enum: [greenfield, brownfield] }
+        scope: { type: array, minItems: 1, items: { type: string, minLength: 1 }, default: ['.'] }
+        repository_revision: { type: string, minLength: 1 }
+        replace_ready: { type: boolean, default: false }
+        replacement_authorization:
+          type: object
+          required: [approved_by, reason]
+          additionalProperties: false
+          properties:
+            approved_by: { type: string, minLength: 1 }
+            reason: { type: string, minLength: 3 }
+        replace_migrated: { type: boolean, default: false, description: explicitly supersede a compatibility-only migrated baseline and start evidence-backed adoption }
+        classification: { type: object, description: bounded repository classification evidence; content is limited to 32 KiB }
+        provider_refs:
+          type: object
+          additionalProperties: false
+          properties:
+            memory:
+              type: object
+              required: [provider]
+              additionalProperties: false
+              properties:
+                provider: { type: string }
+                project: { type: string }
+                reference: { type: string }
+                revision: { type: string }
+                indexed_head: { type: string }
+                status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+            code_graph:
+              type: object
+              required: [provider]
+              additionalProperties: false
+              properties:
+                provider: { type: string }
+                project: { type: string }
+                reference: { type: string }
+                revision: { type: string }
+                indexed_head: { type: string }
+                status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+    output_schema:
+      type: object
+      required: [baseline]
+      additionalProperties: false
+      properties:
+        baseline: { type: object }
+    errors:
+      - { code: BASELINE_EXISTS, description: 'a ready baseline requires explicit replacement' }
+      - { code: BASELINE_IN_PROGRESS, description: 'another adoption is already active' }
+      - { code: BASELINE_REPLACEMENT_AUTHORIZATION_REQUIRED, description: 'ready-baseline replacement lacks durable owner approval and rationale' }
+      - { code: BASELINE_REPLACEMENT_INVALID, description: 'replacement flags do not match the current baseline lifecycle or authorization payload' }
+      - { code: BASELINE_SCOPE_MISSING, description: 'a selected baseline scope does not exist' }
+      - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
+    cli_subcommand: baseline start
+    emits_events: [baseline_started]
+
+  - name: baseline.record
+    family: baseline
+    description: Replace the current adoption snapshot with bounded specification digests, evidence references, verification, unknowns, and provider metadata.
+    phase: '11'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id]
+      additionalProperties: false
+      properties:
+        id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        repository_revision: { type: string, minLength: 1 }
+        scope: { type: array, minItems: 1, items: { type: string, minLength: 1 } }
+        spec_refs:
+          type: array
+          items:
+            type: object
+            required: [kind, path]
+            additionalProperties: false
+            properties:
+              kind: { type: string, enum: [discovery, product, architecture, quality, delivery, other] }
+              path: { type: string, minLength: 1 }
+        evidence:
+          type: array
+          items:
+            type: object
+            required: [kind, ref, summary]
+            additionalProperties: false
+            properties:
+              kind: { type: string, enum: [source, docs, runtime, test, deploy, external] }
+              ref: { type: string, minLength: 1 }
+              summary: { type: string, minLength: 1 }
+        verification:
+          type: array
+          items:
+            type: object
+            required: [name, command, status, evidence]
+            additionalProperties: false
+            properties:
+              name: { type: string, minLength: 1 }
+              command: { type: string, minLength: 1 }
+              status: { type: string, enum: [pass, known_red, not_run] }
+              evidence: { type: string, minLength: 1 }
+              rationale: { type: string, minLength: 1 }
+        unknowns:
+          type: array
+          items:
+            type: object
+            required: [summary, blocking]
+            additionalProperties: false
+            properties:
+              summary: { type: string, minLength: 1 }
+              blocking: { type: boolean }
+              owner: { type: string, minLength: 1 }
+        gaps:
+          type: array
+          items:
+            type: object
+            required: [id, category, summary]
+            additionalProperties: false
+            properties:
+              id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+              category: { type: string, enum: [baseline_blocker, documentation_drift, known_defect, technical_debt, unknown, future_change] }
+              status: { type: string, enum: [open, accepted, resolved, deferred], default: open }
+              blocking: { type: boolean, default: false }
+              summary: { type: string, minLength: 1 }
+              evidence_refs: { type: array, uniqueItems: true, items: { type: string, minLength: 1 }, default: [] }
+              owner: { type: ['string', 'null'], minLength: 1 }
+              resolution: { type: string, minLength: 1 }
+        classification: { type: object, description: bounded repository classification evidence; content is limited to 32 KiB }
+        provider_refs:
+          type: object
+          additionalProperties: false
+          properties:
+            memory:
+              type: object
+              required: [provider]
+              additionalProperties: false
+              properties:
+                provider: { type: string }
+                project: { type: string }
+                reference: { type: string }
+                revision: { type: string }
+                indexed_head: { type: string }
+                status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+            code_graph:
+              type: object
+              required: [provider]
+              additionalProperties: false
+              properties:
+                provider: { type: string }
+                project: { type: string }
+                reference: { type: string }
+                revision: { type: string }
+                indexed_head: { type: string }
+                status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+    output_schema:
+      type: object
+      required: [baseline]
+      additionalProperties: false
+      properties:
+        baseline: { type: object }
+    errors:
+      - { code: BASELINE_NOT_FOUND, description: 'baseline id does not exist' }
+      - { code: BASELINE_NOT_MUTABLE, description: 'ready and superseded baselines are immutable' }
+      - { code: BASELINE_SPEC_MISSING, description: 'a declared specification file does not exist' }
+      - { code: BASELINE_SCOPE_MISSING, description: 'a selected baseline scope does not exist' }
+      - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
+    cli_subcommand: baseline record
+    emits_events: [baseline_recorded]
+
+  - name: baseline.get
+    family: baseline
+    description: Read the current or named authoritative baseline with live digest and repository-revision health.
+    phase: '11'
+    readonly: true
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+    output_schema:
+      type: object
+      required: [baseline, health]
+      additionalProperties: false
+      properties:
+        baseline: { type: object }
+        health: { type: object }
+    errors:
+      - { code: BASELINE_NOT_FOUND, description: 'no matching baseline exists' }
+    cli_subcommand: baseline get
+    emits_events: []
+
+  - name: baseline.converge
+    family: baseline
+    description: Approve a baseline only when its revision, specification digests, evidence, verification, and blocking unknowns satisfy deterministic gates.
+    phase: '11'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, expected_revision, approved_by, approval_note]
+      additionalProperties: false
+      properties:
+        id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        expected_revision: { type: string, minLength: 1 }
+        approved_by: { type: string, minLength: 1 }
+        approval_note: { type: string, minLength: 3 }
+        accept_known_red: { type: boolean, default: false }
+        accept_dirty_worktree: { type: boolean, default: false, description: explicitly freeze the exact recorded dirty-worktree digest into the baseline }
+    output_schema:
+      type: object
+      required: [ready, status, blockers, baseline]
+      additionalProperties: false
+      properties:
+        ready: { type: boolean }
+        status: { type: string, enum: [blocked, ready] }
+        blockers: { type: array, items: { type: string } }
+        baseline: { type: object }
+    errors:
+      - { code: BASELINE_NOT_FOUND, description: 'baseline id does not exist' }
+      - { code: BASELINE_NOT_CONVERGEABLE, description: 'baseline lifecycle does not allow convergence' }
+      - { code: BASELINE_NOT_READY, description: 'baseline evidence, gaps, revision, branch, worktree, or verification still blocks convergence' }
+    cli_subcommand: baseline converge
+    emits_events: [baseline_blocked, baseline_converged]
+
   # ────────────────────────── change family ──────────────────────────────
   - name: change.create
     family: change
@@ -645,6 +938,14 @@ tools:
         kind: { type: string, enum: [quick, standard, major, incident] }
         intent: { type: string, minLength: 3 }
         base_commit: { type: string, pattern: '^[0-9a-f]{7,40}$' }
+        baseline_bypass:
+          type: object
+          required: [reason, approved_by]
+          additionalProperties: false
+          properties:
+            reason: { type: string, minLength: 3 }
+            approved_by: { type: string, minLength: 1 }
+          description: incident-only break-glass approval when the project baseline is unhealthy
         docs_impact:
           type: object
           additionalProperties: false
@@ -690,6 +991,8 @@ tools:
       - { code: DUPLICATE_CHANGE_ID, description: 'change id already exists' }
       - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
       - { code: VALIDATION_ERROR, description: 'change input failed validation' }
+      - { code: BASELINE_NOT_READY, description: 'ordinary work is blocked until the project baseline is healthy' }
+      - { code: BASELINE_BYPASS_REQUIRED, description: 'an incident on an unhealthy baseline requires explicit break-glass approval' }
     cli_subcommand: change create
     emits_events: [change_created, context_updated]
 
@@ -1048,6 +1351,8 @@ tools:
     errors:
       - { code: CHANGE_NOT_READY, description: 'change has not passed convergence' }
       - { code: BASELINE_RECONCILIATION_REQUIRED, description: 'baseline update or explicit no-change reason required' }
+      - { code: BASELINE_FILE_MISSING, description: 'a declared baseline update does not exist' }
+      - { code: BASELINE_RECONCILIATION_INCOMPLETE, description: 'repository revision or tracked specification digests remain stale after reconciliation' }
       - { code: ARCHIVE_EXISTS, description: 'archive target already exists' }
     cli_subcommand: change archive
     emits_events: [change_archived]

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

@@ -60,7 +60,7 @@
         },
         "family": {
           "type": "string",
-          "enum": ["task", "memory", "review", "impact", "skill", "session", "ask", "plan", "change", "system"]
+          "enum": ["task", "memory", "review", "impact", "skill", "session", "ask", "plan", "baseline", "change", "system"]
         },
         "description": { "type": "string", "minLength": 10 },
         "phase": {

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
--- task / session / event / telemetry data. tasks.json and context md status
+-- baseline / change / task / session / event / telemetry data. tasks.json and context md status
 -- header are projections (PLAN §7.1, D18, D32).
 --
--- Trace: docs/PLAN.zh-CN.md §7.1; decisions D18/D30/D31/D32/D37.
+-- Trace: docs/PLAN.zh-CN.md §7.1; decisions D18/D30/D31/D32/D37/D52/D54.
 --
 -- PRAGMAs are applied by mcp-server/lib/state-db.ts on connection open;
 -- they cannot be persisted in CREATE statements but are documented here.
@@ -12,6 +12,43 @@
 --   PRAGMA busy_timeout=5000;       -- block up to 5s on lock (R25)
 --   PRAGMA foreign_keys=ON;         -- enforce FK constraints
 
+-- ──────────────────────────── project baseline ─────────────────────────────
+-- The baseline is the approved, repository-scoped snapshot that every change
+-- is measured against. It stores digests and evidence references, never source,
+-- prompt, transcript, memory, or code-graph payloads.
+CREATE TABLE IF NOT EXISTS baselines (
+  id                  TEXT PRIMARY KEY,
+  project_name        TEXT NOT NULL,
+  project_type        TEXT,
+  stack               TEXT,
+  mode                TEXT NOT NULL CHECK (mode IN ('greenfield', 'brownfield', 'migrated')),
+  status              TEXT NOT NULL DEFAULT 'draft'
+                        CHECK (status IN ('draft', 'adopting', 'blocked', 'ready', 'superseded')),
+  repository_root     TEXT NOT NULL DEFAULT '.',
+  scope_json          TEXT NOT NULL DEFAULT '["."]',
+  repository_revision TEXT,
+  repository_branch   TEXT,
+  worktree_state      TEXT NOT NULL DEFAULT 'unavailable'
+                        CHECK (worktree_state IN ('clean', 'dirty', 'unavailable')),
+  worktree_digest     TEXT,
+  worktree_files_json TEXT NOT NULL DEFAULT '[]',
+  worktree_accepted   INTEGER NOT NULL DEFAULT 0 CHECK (worktree_accepted IN (0, 1)),
+  spec_refs_json      TEXT NOT NULL DEFAULT '[]',
+  evidence_json       TEXT NOT NULL DEFAULT '[]',
+  verification_json   TEXT NOT NULL DEFAULT '[]',
+  unknowns_json       TEXT NOT NULL DEFAULT '[]',
+  gaps_json           TEXT NOT NULL DEFAULT '[]',
+  classification_json TEXT NOT NULL DEFAULT '{}',
+  provider_refs_json  TEXT NOT NULL DEFAULT '{}',
+  approved_by         TEXT,
+  approval_note       TEXT,
+  started_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  converged_at        TEXT
+);
+
+CREATE INDEX IF NOT EXISTS baselines_status ON baselines(status, updated_at);
+
 -- ──────────────────────────── changes ─────────────────────────────────────
 -- A project baseline is continuous; each feature, fix, incident, or redesign
 -- is an independently converged change unit. Only changes become terminal.
@@ -24,6 +61,7 @@ CREATE TABLE IF NOT EXISTS changes (
   intent            TEXT NOT NULL,
   docs_impact_json  TEXT NOT NULL DEFAULT '{"status":"unknown","files":[],"rationale":null}',
   provider_refs_json TEXT NOT NULL DEFAULT '{}',
+  baseline_bypass_json TEXT,
   base_commit       TEXT,
   artifact_root     TEXT NOT NULL,
   created_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
@@ -305,3 +343,7 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('9.1', 'Kimi runtime support in durable events and sessions');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('10.0', 'Role-scoped context snapshots, deterministic breadcrumbs, and approval-gated specification learning');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('11.0', 'Greenfield and brownfield baseline adoption, convergence, and drift authority');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('12.0', 'Evidence-backed repository snapshots, gap ledger, safe re-adoption, and incident break-glass governance');

package/ultra-tools/cli.cjs

@@ -20,7 +20,7 @@ const path = require('node:path');
 
 const VERSION = (() => {
   try {
-    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    const pkg = require('../package.json');
     return pkg.version;
   } catch (_err) {
     return '0.1.0';
@@ -35,10 +35,10 @@ USAGE:
 SUBCOMMANDS:
   task      init-project
   session   close | get | list | admission | heartbeat | subscribe | reap
-  system    doctor [--repair]
+  system    doctor [--repair] | restore | rebaseline
   status    [--cost] [--since <duration>] [--json]
   db        init | checkpoint | vacuum | integrity | backup (Phase 2)
-  migrate   --from=4.4 --to=4.5 [--dry|--rollback]          (Phase 2)
+  migrate   --from=<4.4|4.5> --to=<4.5|12.0> [--dry|--rollback]
   legacy-memory inspect | archive | prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
   --help / -h      show this message
@@ -68,7 +68,11 @@ const statusCommand = require('./commands/status.cjs');
 const legacyMemoryCommand = require('./commands/legacy-memory.cjs');
 const systemCommand = require('./commands/system.cjs');
 
-// Phase 6.2 — CLI telemetry: best-effort, never blocks the subcommand.
+// Session commands run only against healthy authority and may emit best-effort
+// telemetry. Initialization, diagnosis, migration, and recovery commands must
+// never open state.db before their own evidence-preserving checks.
+const TELEMETRY_SUBCOMMANDS = new Set(['session']);
+
 function emitCliTelemetry(sub, rest) {
   try {
     const dbPath = path.resolve('.ultra', 'state.db');
@@ -112,7 +116,7 @@ function main(argv) {
   const [sub, ...rest] = args;
   const handler = SUBCOMMANDS[sub];
   if (!handler) fail(`unknown subcommand: ${sub}\n\n${USAGE}`);
-  emitCliTelemetry(sub, rest);
+  if (TELEMETRY_SUBCOMMANDS.has(sub)) emitCliTelemetry(sub, rest);
   handler(rest);
 }