ultra-builder-pro-cli 0.8.1 → 0.10.0

package/spec/mcp-tools.yaml

@@ -3,7 +3,7 @@
 # Validated by spec/schemas/mcp-tools.schema.json (run `npm run test:spec`).
 # Trace: PLAN §7.3, decisions D12 / D29 / D31-D34.
 
-version: '1.0'
+version: '1.1'
 
 info:
   title: Ultra Builder Pro MCP tool contracts
@@ -367,7 +367,7 @@ tools:
         task_id:    { type: string }
         change_id:  { type: string }
         session_id: { type: string }
-        runtime:    { type: string, enum: [claude, opencode, codex] }
+        runtime:    { type: string, enum: [claude, opencode, codex, kimi] }
         type:
           type: string
           enum:
@@ -398,6 +398,8 @@ tools:
             - change_blocked
             - change_converged
             - change_archived
+            - spec_learning_proposed
+            - spec_learning_resolved
         payload: { type: object }
     output_schema:
       type: object
@@ -452,7 +454,7 @@ tools:
       additionalProperties: false
       properties:
         task_id:  { type: string }
-        runtime:  { type: string, enum: [claude, opencode, codex] }
+        runtime:  { type: string, enum: [claude, opencode, codex, kimi] }
         takeover: { type: boolean, default: false, description: 'override active lease (D33 takeover strategy)' }
         worktree_base: { type: string }
     output_schema:
@@ -554,7 +556,7 @@ tools:
       additionalProperties: false
       properties:
         task_id: { type: string }
-        runtime: { type: string, enum: [claude, opencode, codex] }
+        runtime: { type: string, enum: [claude, opencode, codex, kimi] }
     output_schema:
       type: object
       required: [can_spawn, recommended_action]
@@ -759,7 +761,7 @@ tools:
 
   - name: change.get
     family: change
-    description: Read one continuous change unit from authoritative state.
+    description: Read one continuous change unit and its specification-learning candidates from authoritative state.
     phase: '9'
     readonly: true
     input_schema:
@@ -805,8 +807,8 @@ tools:
 
   - name: change.context
     family: change
-    description: Compile an inspectable task context manifest from Ultra state and external provider metadata references.
-    phase: '9'
+    description: Compile a role-scoped Context Spine manifest with readiness, budget, execution seam, and next-action evidence.
+    phase: '10'
     writer_role: mcp
     input_schema:
       type: object
@@ -815,7 +817,37 @@ tools:
       properties:
         id: { type: string }
         task_id: { type: string }
+        role: { type: string, enum: [plan, implement, check, review] }
+        gate: { type: string, enum: [alignment, planning, implementation, verification, review, convergence, recovery] }
+        next_action: { type: string, minLength: 3 }
         spec_refs: { type: array, items: { type: object } }
+        context_refs:
+          type: array
+          maxItems: 64
+          items:
+            type: object
+            required: [ref, reason]
+            additionalProperties: false
+            properties:
+              ref: { type: string, minLength: 1 }
+              kind: { type: string, enum: [spec, source, test, docs, external], default: source }
+              reason: { type: string, minLength: 3 }
+              required: { type: boolean, default: true }
+              digest: { type: string, pattern: '^[0-9a-f]{64}$' }
+        budget:
+          type: object
+          additionalProperties: false
+          properties:
+            max_tokens: { type: integer, minimum: 1, default: 12000 }
+            max_files: { type: integer, minimum: 1, default: 12 }
+        execution_contract:
+          type: object
+          additionalProperties: false
+          properties:
+            slice_kind: { type: string, enum: [tracer_bullet, expand_contract, integration_checkpoint], default: tracer_bullet }
+            public_seam: { type: string }
+            verification_command: { type: string }
+            context_budget_percent: { type: integer, minimum: 1, maximum: 100, default: 40 }
         allowed_paths: { type: array, items: { type: string } }
         provider_refs:
           type: object
@@ -852,12 +884,96 @@ tools:
         manifest_hash: { type: string, pattern: '^[0-9a-f]{64}$' }
         manifest: { type: object }
     errors:
+      - { code: VALIDATION_ERROR, description: 'context role, gate, references, budget, or execution contract is invalid' }
       - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
       - { code: CHANGE_TERMINAL, description: 'terminal change cannot compile a new context' }
+      - { code: TASK_NOT_FOUND, description: 'task id is not linked to the change' }
       - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
     cli_subcommand: change context
     emits_events: [context_updated]
 
+  - name: change.breadcrumb
+    family: change
+    description: Read the compact DB-derived Context Spine position, readiness, and single recommended next action.
+    phase: '10'
+    readonly: true
+    writer_role: any
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        id: { type: string }
+    output_schema:
+      type: object
+      required: [breadcrumb]
+      additionalProperties: false
+      properties:
+        breadcrumb: { type: object }
+    errors:
+      - { code: CHANGE_NOT_FOUND, description: 'explicit change id does not exist' }
+      - { code: STATE_DB_ERROR, description: 'runtime state could not be read' }
+    cli_subcommand: change breadcrumb
+    emits_events: []
+
+  - name: change.learning_propose
+    family: change
+    description: Propose one stable implementation discovery for approval-gated baseline specification convergence.
+    phase: '10'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [change_id, target_ref, summary]
+      additionalProperties: false
+      properties:
+        id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        change_id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        task_id: { type: string }
+        target_ref: { type: string, minLength: 1 }
+        summary: { type: string, minLength: 3 }
+        evidence: { type: array, items: { type: string, minLength: 1 } }
+    output_schema:
+      type: object
+      required: [candidate]
+      additionalProperties: false
+      properties:
+        candidate: { type: object }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'candidate id, target, summary, or evidence is invalid' }
+      - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'learning must resolve before convergence' }
+      - { code: TASK_NOT_FOUND, description: 'task is not linked to the change' }
+      - { code: DUPLICATE_LEARNING_ID, description: 'candidate id already exists' }
+    cli_subcommand: change learning-propose
+    emits_events: [spec_learning_proposed]
+
+  - name: change.learning_resolve
+    family: change
+    description: Approve, reject, or mark applied one specification-learning candidate through a guarded state transition.
+    phase: '10'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [change_id, candidate_id, decision]
+      additionalProperties: false
+      properties:
+        change_id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        candidate_id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        decision: { type: string, enum: [approve, reject, apply] }
+        resolution: { type: string }
+    output_schema:
+      type: object
+      required: [candidate]
+      additionalProperties: false
+      properties:
+        candidate: { type: object }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'decision or required resolution is invalid' }
+      - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
+      - { code: LEARNING_NOT_FOUND, description: 'candidate id does not exist for the change' }
+      - { code: ILLEGAL_LEARNING_TRANSITION, description: 'candidate state transition is not permitted' }
+    cli_subcommand: change learning-resolve
+    emits_events: [spec_learning_resolved]
+
   - name: change.converge
     family: change
     description: Deterministically verify task, spec, test, documentation, review, context, and incident diagnosis structure before closure.
@@ -880,6 +996,19 @@ tools:
               category: { type: string, enum: [diagnosis, diff, tests, spec, docs, review] }
               status: { type: string, enum: [pass, fail, not_applicable] }
               evidence: { type: string, minLength: 3 }
+              axis: { type: string, enum: [spec_fidelity, engineering_standards] }
+              seam: { type: string, minLength: 3 }
+              signal:
+                type: object
+                additionalProperties: false
+                required: [command, expected_red, observed_red, observed_green, deterministic]
+                properties:
+                  command: { type: string, minLength: 3 }
+                  expected_red: { type: string, minLength: 3 }
+                  observed_red: { type: boolean }
+                  observed_green: { type: boolean }
+                  deterministic: { type: boolean }
+                  duration_ms: { type: number, minimum: 0 }
     output_schema:
       type: object
       required: [ready, status, blockers]

package/spec/schemas/skill-manifest.schema.json

@@ -19,10 +19,10 @@
     },
     "runtime": {
       "oneOf": [
-        { "type": "string", "enum": ["claude", "opencode", "codex", "all"] },
+        { "type": "string", "enum": ["claude", "opencode", "codex", "kimi", "all"] },
         {
           "type": "array",
-          "items": { "type": "string", "enum": ["claude", "opencode", "codex"] },
+          "items": { "type": "string", "enum": ["claude", "opencode", "codex", "kimi"] },
           "minItems": 1,
           "uniqueItems": true
         }

package/spec/schemas/state-db.sql

@@ -79,7 +79,7 @@ CREATE TABLE IF NOT EXISTS events (
   task_id       TEXT,
   change_id     TEXT,
   session_id    TEXT,
-  runtime       TEXT CHECK (runtime IS NULL OR runtime IN ('claude', 'opencode', 'codex')),
+  runtime       TEXT CHECK (runtime IS NULL OR runtime IN ('claude', 'opencode', 'codex', 'kimi')),
   payload_json  TEXT
 );
 
@@ -95,7 +95,7 @@ CREATE INDEX IF NOT EXISTS events_change  ON events(change_id, id);
 CREATE TABLE IF NOT EXISTS sessions (
   sid               TEXT PRIMARY KEY,
   task_id           TEXT NOT NULL REFERENCES tasks(id),
-  runtime           TEXT NOT NULL CHECK (runtime IN ('claude', 'opencode', 'codex')),
+  runtime           TEXT NOT NULL CHECK (runtime IN ('claude', 'opencode', 'codex', 'kimi')),
   pid               INTEGER,
   worktree_path     TEXT NOT NULL,
   artifact_dir      TEXT NOT NULL,
@@ -197,11 +197,40 @@ CREATE TABLE IF NOT EXISTS context_snapshots (
   provider_refs_json TEXT NOT NULL DEFAULT '{}',
   manifest_path      TEXT NOT NULL,
   manifest_hash      TEXT NOT NULL,
+  role               TEXT NOT NULL DEFAULT 'plan'
+                       CHECK (role IN ('plan', 'implement', 'check', 'review')),
+  gate               TEXT NOT NULL DEFAULT 'alignment'
+                       CHECK (gate IN ('alignment', 'planning', 'implementation', 'verification', 'review', 'convergence', 'recovery')),
+  next_action        TEXT NOT NULL DEFAULT 'Resolve the next Ultra workflow action.',
+  readiness          TEXT NOT NULL DEFAULT 'ready'
+                       CHECK (readiness IN ('ready', 'blocked')),
+  blockers_json      TEXT NOT NULL DEFAULT '[]',
+  context_json       TEXT NOT NULL DEFAULT '{}',
+  token_estimate     INTEGER NOT NULL DEFAULT 0 CHECK (token_estimate >= 0),
+  token_budget       INTEGER NOT NULL DEFAULT 12000 CHECK (token_budget > 0),
   created_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
 );
 
 CREATE INDEX IF NOT EXISTS context_snapshots_change ON context_snapshots(change_id, created_at);
 
+CREATE TABLE IF NOT EXISTS spec_learning_candidates (
+  id            TEXT PRIMARY KEY,
+  change_id     TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+  task_id       TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  target_ref    TEXT NOT NULL,
+  summary       TEXT NOT NULL,
+  evidence_json TEXT NOT NULL DEFAULT '[]',
+  status        TEXT NOT NULL DEFAULT 'proposed'
+                  CHECK (status IN ('proposed', 'approved', 'rejected', 'applied')),
+  resolution    TEXT,
+  proposed_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  resolved_at   TEXT,
+  applied_at    TEXT
+);
+
+CREATE INDEX IF NOT EXISTS spec_learning_change
+  ON spec_learning_candidates(change_id, status, proposed_at);
+
 CREATE TABLE IF NOT EXISTS trace_links (
   id          INTEGER PRIMARY KEY AUTOINCREMENT,
   change_id   TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
@@ -272,3 +301,7 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('8A.2', 'Phase 8A.2 — tasks.estimated_days preserved across MCP and v4.4 migration');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('9.0', 'Continuous change units, context snapshots, trace links, incidents, projection outbox, and durable consumers');
+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');