ultra-builder-pro-cli 0.24.1 → 0.25.0

package/spec/mcp-tools.yaml

@@ -52,7 +52,7 @@ tools:
 
   - name: ultra.record
     family: ultra
-    description: Record one or more typed draft facts or actions with per-entry idempotency. Semantic rejections are returned as mutable diagnostics rather than transport errors.
+    description: Record one or more typed draft facts or actions with per-entry idempotency. Entry data is checked against its kind/action contract so one invalid batch item can return a mutable diagnostic without hiding the other results.
     phase: '24'
     writer_role: mcp
     input_schema:
@@ -71,6 +71,7 @@ tools:
               kind:
                 type: string
                 enum: [baseline, change_contract, decision, task_contract, task_outcome, artifact, event]
+                description: Selects the entry data contract. Task contracts own durable intent; Task outcomes own status and post-commit attestation.
               action:
                 type: string
                 enum:
@@ -81,14 +82,80 @@ tools:
                   - open
                   - revise
                   - cancel
+                  - supersede
                   - define
                   - remove
                   - complete
                   - block
                   - reopen
+                  - attest_commit
                   - bind
                   - append
-              data: { type: object }
+                description: Valid actions are checked with kind at runtime; task_outcome uses start, block, reopen, complete, or attest_commit.
+              data:
+                type: object
+                description: |
+                  Every kind/action selects one exact data contract. Unknown fields,
+                  wrong scalar/container types, invalid closed mechanical enums,
+                  malformed digests, and mismatched authority references return an entry-level mutable
+                  VALIDATION_ERROR before SQLite or filesystem mutation.
+
+                  baseline uses mode greenfield|brownfield; spec kinds
+                  discovery|product|architecture|quality|delivery|other; evidence kinds
+                  source|docs|runtime|test|deploy|external; verification status
+                  pass|known_red|not_run; gap status open|accepted|resolved|deferred and
+                  category baseline_blocker|documentation_drift|known_defect|
+                  technical_debt|unknown|future_change. blocking and acceptance flags
+                  are booleans, never truthy strings.
+
+                  change_contract/open accepts a bounded caller-defined kind; quick,
+                  standard, major, and incident are recommended Skill-level profiles,
+                  docs_impact.status unknown|required|none, risk flags
+                  public_contract|schema_migration|data_migration|authorization|
+                  security|multi_module|external_integration|release_semantics are
+                  recommended Skill-level labels rather than a closed MCP vocabulary, and
+                  research status none|bounded|required with mode
+                  product|feature|architecture|custom are likewise recommended profiles;
+                  bounded repository-defined status, mode, and risk labels remain valid.
+                  revise uses {id, patch};
+                  cancel uses {id}. supersede uses an archived or cancelled source id,
+                  a successor_id, and optional title/kind/intent overrides. Draft
+                  semantic corrections remain reversible; immutable history creates a
+                  linked active successor instead of reopening in place.
+
+                  decision/accept has exact scope {baseline_id} or {change_id};
+                  applied_refs items are exactly {ref, field, digest?}. effects and
+                  provenance are JSON objects; non_goals is a string array.
+
+                  Task contracts are structurally exact. task_contract/define requires
+                  id, title, and bounded non-empty type and priority strings.
+                  architecture|feature|bugfix and P0|P1|P2|P3 are recommended
+                  Skill-level vocabulary, not SQLite business verdicts.
+                  id matches [A-Za-z0-9_-]+ and title has at least 3 characters.
+                  Optional complexity is integer 1..10, estimated_days is >0,
+                  slice_kind is an optional bounded caller-defined string; tracer_bullet,
+                  expand_contract, and integration_checkpoint are recommended profiles.
+                  deps/files_modified are non-empty-string arrays, and
+                  acceptance/context_refs are object arrays. task_contract/revise uses
+                  {id, patch} and permits contract fields, including corrected
+                  title/type, only. status, session_id, stale, tag, context_file, and
+                  completion_commit are runtime-owned and forbidden in Task Contracts.
+                  task_outcome start|block|reopen uses {id}. complete uses exactly
+                  {id, packet_digest} with a 64-hex packet digest; patch and
+                  completion_commit are forbidden.
+                  After durable completion is synced and committed, attest_commit uses
+                  exactly {id, completion_commit}; the commit is a full 40- or 64-hex
+                  Git object id recorded as checkout-local proof.
+
+                  artifact/bind uses owner_type project|baseline|change|task|workflow,
+                  status current|stale|terminal|archived, 64-lowercase-hex content
+                  digests, and exact reference items {type, id, relation}; type is
+                  artifact|project|baseline|change|task|workflow|external. Current
+                  public authority rejects workflow-owned legacy references.
+
+                  event/append is exactly {type, task_id?, change_id?, session_id?,
+                  runtime?, payload?}. Identifiers/runtime are strings or null and
+                  payload is a JSON object.
               idempotency_key: { type: string, minLength: 3 }
     output_schema: { type: object }
     errors:
@@ -115,7 +182,15 @@ tools:
           properties:
             change_id: { type: string, minLength: 1 }
             task_id: { type: string, minLength: 1 }
-        payload: { type: object }
+        payload:
+          type: object
+          description: |
+            Stage-specific semantic fields remain model-owned. Kernel-owned evidence
+            is an object array whose kind/ref/summary/digest/artifact_id values are
+            strings when present. diagnostics is an exact object array with required
+            string code and optional string severity/message plus JSON details.
+            Evidence authority, current bytes, scope, checkpoint identity, and the
+            accepted receipt are validated atomically.
         idempotency_key: { type: string, minLength: 3 }
     output_schema: { type: object }
     errors:
@@ -140,8 +215,13 @@ tools:
       additionalProperties: false
       properties:
         action: { type: string, enum: [inspect, import, publish, migrate] }
-        reason: { type: string }
-        idempotency_key: { type: string }
+        reason:
+          type: string
+          description: Allowed only for publish.
+        idempotency_key:
+          type: string
+          minLength: 3
+          description: Required only for publish; binds the exact request and ledger generation.
     output_schema: { type: object }
     errors:
       - { code: VALIDATION_ERROR, description: 'input failed structural validation' }
@@ -160,9 +240,24 @@ tools:
       additionalProperties: false
       properties:
         action: { type: string, enum: [admission, acquire, get, list, heartbeat, release] }
-        scope: { type: object }
-        payload: { type: object }
-        idempotency_key: { type: string }
+        scope:
+          type: object
+          description: |
+            admission/acquire/list use task_id (list may omit it); get/heartbeat/release
+            use sid. Unknown scope fields are rejected.
+        payload:
+          type: object
+          description: |
+            admission/get/list/heartbeat accept no payload fields. acquire accepts only
+            role, runtime, output_path, output_schema, evidence_refs, diff_range,
+            changed_files, takeover, and worktree_base. release accepts status
+            completed|crashed and optional boolean remove_worktree. Acquire, heartbeat,
+            and release compensate Session, lease, Worker Packet, and worktree effects
+            if their durable receipt fails.
+        idempotency_key:
+          type: string
+          minLength: 3
+          description: Required for acquire, heartbeat, and release.
     output_schema: { type: object }
     errors:
       - { code: VALIDATION_ERROR, description: 'input failed structural validation' }
@@ -181,7 +276,17 @@ tools:
       additionalProperties: false
       properties:
         change_id: { type: string, minLength: 1 }
-        payload: { type: object }
+        payload:
+          type: object
+          additionalProperties: false
+          properties:
+            summary: { type: string }
+            baseline_updates:
+              type: array
+              items: { type: string }
+            no_baseline_change_reason: { type: string }
+            reconciliation_path: { type: string }
+          description: The payload cannot replace the caller-declared change_id.
         idempotency_key: { type: string, minLength: 3 }
     output_schema: { type: object }
     errors:

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

@@ -20,8 +20,8 @@
           "x-derived": true,
           "description": "DERIVED from state.db tasks.status; written by projector, not by humans"
         },
-        "priority":       { "type": "string", "enum": ["P0", "P1", "P2", "P3"] },
-        "type":           { "type": "string", "enum": ["architecture", "feature", "bugfix"] },
+        "priority":       { "type": "string", "minLength": 1, "maxLength": 80 },
+        "type":           { "type": "string", "minLength": 1, "maxLength": 80 },
         "session_id":     { "type": "string", "x-derived": true },
         "schema_version": { "const": "4.5" },
         "generated_at":   { "type": "string", "format": "date-time" }

package/spec/schemas/state-db.sql

@@ -59,7 +59,7 @@ CREATE INDEX IF NOT EXISTS baselines_status ON baselines(status, updated_at);
 CREATE TABLE IF NOT EXISTS changes (
   id                TEXT PRIMARY KEY,
   title             TEXT NOT NULL,
-  kind              TEXT NOT NULL CHECK (kind IN ('quick', 'standard', 'major', 'incident')),
+  kind              TEXT NOT NULL CHECK (length(trim(kind)) BETWEEN 1 AND 80),
   status            TEXT NOT NULL DEFAULT 'active'
                       CHECK (status IN ('active', 'blocked', 'ready', 'archived', 'cancelled')),
   intent            TEXT NOT NULL,
@@ -71,6 +71,7 @@ CREATE TABLE IF NOT EXISTS changes (
   research_disposition_json TEXT NOT NULL DEFAULT '{}',
   alignment_thread_id TEXT REFERENCES decision_threads(id) ON DELETE SET NULL,
   base_commit       TEXT,
+  supersedes_id     TEXT REFERENCES changes(id) ON DELETE SET NULL,
   artifact_root     TEXT NOT NULL,
   created_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')),
@@ -81,13 +82,14 @@ CREATE INDEX IF NOT EXISTS changes_status ON changes(status, created_at);
 CREATE INDEX IF NOT EXISTS changes_kind   ON changes(kind, created_at);
 
 -- ──────────────────────────── tasks ───────────────────────────────────────
--- Authoritative task row. tasks.json is generated from this table by the
--- projector (Phase 2.6). Manual edits to tasks.json are overwritten.
+-- Checkout-local operational task authority. The Git-facing tasks.json is a
+-- durable team checkpoint published/imported through ultra.sync; live
+-- projections stay below .ultra/.runtime and are never edited manually.
 CREATE TABLE IF NOT EXISTS tasks (
   id                TEXT PRIMARY KEY,
   title             TEXT NOT NULL,
-  type              TEXT NOT NULL CHECK (type IN ('architecture', 'feature', 'bugfix')),
-  priority          TEXT NOT NULL CHECK (priority IN ('P0', 'P1', 'P2', 'P3')),
+  type              TEXT NOT NULL CHECK (length(trim(type)) BETWEEN 1 AND 80),
+  priority          TEXT NOT NULL CHECK (length(trim(priority)) BETWEEN 1 AND 80),
   complexity        INTEGER CHECK (complexity BETWEEN 1 AND 10),
   estimated_days    REAL CHECK (estimated_days IS NULL OR estimated_days > 0),
   status            TEXT NOT NULL DEFAULT 'pending'
@@ -99,7 +101,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   tag               TEXT,                -- git branch tag (Phase 7.2)
   trace_to          TEXT,                -- spec anchor reference
   outcome           TEXT,                -- observable result owned by this task
-  slice_kind        TEXT CHECK (slice_kind IS NULL OR slice_kind IN ('tracer_bullet', 'expand_contract', 'integration_checkpoint')),
+  slice_kind        TEXT CHECK (slice_kind IS NULL OR length(trim(slice_kind)) BETWEEN 1 AND 80),
   public_seam       TEXT,                -- externally observable seam exercised by the slice
   verification_command TEXT,             -- exact task-level verification command
   acceptance_json   TEXT NOT NULL DEFAULT '[]',
@@ -635,3 +637,5 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('21.0', 'Seven-tool persistence kernel, reversible stage checkpoints, canonical context envelopes, normalized decisions, and worker packets');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('22.0', 'Checkpoint-native baseline authority plus byte-bound Context Envelopes and Worker Packets');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('23.0', 'Open semantic vocabularies, mutable Change drafts, and linked immutable-archive successors');

package/spec/schemas/task-ledger.v2.schema.json

@@ -67,7 +67,7 @@
         "properties": {
           "id": { "type": "string" },
           "title": { "type": "string", "minLength": 1 },
-          "kind": { "type": "string", "enum": ["quick", "standard", "major", "incident"] },
+          "kind": { "type": "string", "minLength": 1, "maxLength": 80 },
           "status": { "type": "string", "enum": ["active", "archived", "cancelled"] },
           "intent": { "type": "string", "minLength": 1 },
           "docs_impact": { "type": "object" },
@@ -79,6 +79,7 @@
           "base_commit": { "type": "string" },
           "artifact_root": { "type": "string", "minLength": 1 },
           "closed_at": { "type": "string" },
+          "supersedes_id": { "type": "string", "minLength": 1 },
           "revision": { "type": "integer", "minimum": 1 },
           "parent_digest": {
             "type": ["string", "null"],
@@ -223,6 +224,7 @@
     },
     "task": {
       "type": "object",
+      "description": "Git-facing durable Task authority. Checkout-local session_id, tag, context_file, completion_commit, created_at, and updated_at are intentionally forbidden.",
       "required": [
         "id",
         "title",
@@ -244,22 +246,35 @@
       "properties": {
         "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
         "title": { "type": "string", "minLength": 3 },
-        "type": { "type": "string", "enum": ["architecture", "feature", "bugfix"] },
-        "priority": { "type": "string", "enum": ["P0", "P1", "P2", "P3"] },
+        "type": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "priority": { "type": "string", "minLength": 1, "maxLength": 80 },
         "complexity": { "type": "integer", "minimum": 1, "maximum": 10 },
         "estimated_days": { "type": "number", "exclusiveMinimum": 0 },
         "status": {
           "type": "string",
-          "enum": ["pending", "completed", "blocked", "expanded"]
+          "enum": ["pending", "completed", "blocked", "expanded"],
+          "description": "Durable Task outcome. Checkout-local in_progress is never published."
+        },
+        "deps": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Durable dependency Task ids."
+        },
+        "files_modified": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Durable path-level conflict surface."
+        },
+        "stale": {
+          "type": "boolean",
+          "description": "Runtime-derived freshness fact published for team handoff."
         },
-        "deps": { "type": "array", "items": { "type": "string" } },
-        "files_modified": { "type": "array", "items": { "type": "string" } },
-        "stale": { "type": "boolean" },
         "trace_to": { "type": "string" },
         "outcome": { "type": "string" },
         "slice_kind": {
           "type": "string",
-          "enum": ["tracer_bullet", "expand_contract", "integration_checkpoint"]
+          "minLength": 1,
+          "maxLength": 80
         },
         "public_seam": { "type": "string" },
         "verification_command": { "type": "string" },

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; manual edits are overwritten. Status and dependencies are derived from state.db. Authority boundary: docs/DECISIONS.md.",
+  "description": "Read-only checkout-local projection of the tasks table. Generated by the projector; manual edits are overwritten. It includes both durable Task authority and runtime-only fields that never enter the Git team ledger. Authority boundary: docs/DECISIONS.md.",
   "type": "object",
   "required": ["schema_version", "generated_at", "tasks"],
   "additionalProperties": false,
@@ -18,13 +18,14 @@
   "$defs": {
     "task": {
       "type": "object",
+      "description": "Live Task projection. task_contract may write contract fields only; status/session/freshness/context/timestamps and completion attestation are runtime-owned.",
       "required": ["id", "title", "type", "priority", "status", "created_at", "updated_at"],
       "additionalProperties": false,
       "properties": {
         "id":         { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
         "title":      { "type": "string", "minLength": 3 },
-        "type":       { "type": "string", "enum": ["architecture", "feature", "bugfix"] },
-        "priority":   { "type": "string", "enum": ["P0", "P1", "P2", "P3"] },
+        "type":       { "type": "string", "minLength": 1, "maxLength": 80 },
+        "priority":   { "type": "string", "minLength": 1, "maxLength": 80 },
         "complexity": { "type": "integer", "minimum": 1, "maximum": 10 },
         "estimated_days": { "type": "number", "exclusiveMinimum": 0 },
         "status": {
@@ -35,14 +36,14 @@
         },
         "deps": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": { "type": "string", "minLength": 1 },
           "x-derived": true,
           "description": "DERIVED from state.db tasks.deps JSON"
         },
         "files_modified": {
           "type": "array",
-          "items": { "type": "string" },
-          "description": "Phase 8B conflict surface; new in v4.5"
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Durable path-level conflict surface."
         },
         "session_id": {
           "type": "string",
@@ -54,20 +55,41 @@
           "x-derived": true,
           "description": "DERIVED from staleness propagation (Phase 5.3)"
         },
-        "tag":              { "type": "string" },
+        "tag": {
+          "type": "string",
+          "x-derived": true,
+          "description": "Checkout-local runtime tag; never task_contract input."
+        },
         "trace_to":         { "type": "string" },
         "outcome":          { "type": "string" },
-        "slice_kind":       { "type": "string", "enum": ["tracer_bullet", "expand_contract", "integration_checkpoint"] },
+        "slice_kind":       { "type": "string", "minLength": 1, "maxLength": 80 },
         "public_seam":      { "type": "string" },
         "verification_command": { "type": "string" },
         "acceptance":       { "type": "array", "items": { "type": "object" } },
         "context_refs":     { "type": "array", "items": { "type": "object" } },
         "docs_impact":      { "type": "object" },
         "ownership":        { "type": "object" },
-        "context_file":     { "type": "string" },
-        "completion_commit": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
-        "created_at":       { "type": "string", "format": "date-time" },
-        "updated_at":       { "type": "string", "format": "date-time" }
+        "context_file": {
+          "type": "string",
+          "x-derived": true,
+          "description": "Checkout-local generated Context path; never task_contract input."
+        },
+        "completion_commit": {
+          "type": "string",
+          "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$",
+          "x-derived": true,
+          "description": "Checkout-local integrated commit proof written only by task_outcome/attest_commit."
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "x-derived": true
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "x-derived": true
+        }
       }
     }
   }