ultra-builder-pro-cli 0.25.0 → 0.26.0

package/spec/mcp-tools.yaml

@@ -1,312 +0,0 @@
-# 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`).
-# Current authority boundary: docs/DECISIONS.md.
-
-version: '2.0'
-
-info:
-  title: Ultra Builder Pro MCP tool contracts
-  phase: '24'
-  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
-    are documented by each adapter's capability map rather than advertised as MCP.
-    Generators consume this YAML to derive types, validators, and CLI parsers.
-    cli_subcommand values reserve stable names. Skills adapt semantic workflows;
-    MCP persists facts, creates immutable checkpoints, and protects only transactional
-    safety boundaries.
-    Adding a tool requires: (a) update this file, (b) add valid+invalid
-    fixture to spec/fixtures/{valid,invalid}/, (c) `npm run test:spec` green.
-
-families:
-  - { name: ultra, description: 'model-facing persistence and safety kernel', phase: '24' }
-
-tools:
-
-  # ───────────────────── public model-facing kernel ─────────────────────
-  - name: ultra.context
-    family: ultra
-    description: Read one bounded canonical Context Envelope. This tool is side-effect free and reports diagnostics without choosing the next semantic action.
-    phase: '24'
-    readonly: true
-    writer_role: mcp
-    input_schema:
-      type: object
-      additionalProperties: false
-      properties:
-        stage: { type: string, enum: [project, research, plan, dev, test, review, deliver] }
-        scope:
-          type: object
-          additionalProperties: false
-          properties:
-            change_id: { type: string, minLength: 1 }
-            task_id: { type: string, minLength: 1 }
-        detail: { type: string, enum: [summary, full] }
-    output_schema: { type: object }
-    errors:
-      - { code: VALIDATION_ERROR, description: 'input failed structural validation' }
-      - { code: STATE_CORRUPT, description: 'local authority cannot be read safely' }
-    cli_subcommand: 'ultra context'
-
-  - name: ultra.record
-    family: ultra
-    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:
-      type: object
-      required: [entries]
-      additionalProperties: false
-      properties:
-        entries:
-          type: array
-          minItems: 1
-          items:
-            type: object
-            required: [kind, action, data, idempotency_key]
-            additionalProperties: false
-            properties:
-              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:
-                  - initialize
-                  - start
-                  - observe
-                  - accept
-                  - open
-                  - revise
-                  - cancel
-                  - supersede
-                  - define
-                  - remove
-                  - complete
-                  - block
-                  - reopen
-                  - attest_commit
-                  - bind
-                  - append
-                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:
-      - { code: VALIDATION_ERROR, description: 'input failed structural validation' }
-      - { code: STATE_CORRUPT, description: 'local authority cannot be updated safely' }
-      - { code: PATH_AUTHORITY_VIOLATION, description: 'a requested write escapes managed authority' }
-    cli_subcommand: 'ultra record'
-    emits_events: [ultra_facade_call]
-
-  - name: ultra.checkpoint
-    family: ultra
-    description: Commit one caller-declared stage checkpoint after validating scope, structure, idempotency, current file bytes, digests, and transactional publication. Semantic completeness remains a Skill/model judgment and is returned only as advisory diagnostics.
-    phase: '24'
-    writer_role: mcp
-    input_schema:
-      type: object
-      required: [stage, scope, payload, idempotency_key]
-      additionalProperties: false
-      properties:
-        stage: { type: string, enum: [research, plan, dev, test, review, deliver] }
-        scope:
-          type: object
-          additionalProperties: false
-          properties:
-            change_id: { type: string, minLength: 1 }
-            task_id: { type: string, minLength: 1 }
-        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:
-      - { code: VALIDATION_ERROR, description: 'input failed structural validation' }
-      - { code: STATE_CORRUPT, description: 'local authority cannot be checkpointed safely' }
-      - { code: PATH_AUTHORITY_VIOLATION, description: 'checkpoint evidence escapes managed authority' }
-      - { code: CHECKPOINT_EVIDENCE_AUTHORITY_MISSING, description: 'declared checkpoint evidence is not current managed authority' }
-      - { code: CHECKPOINT_EVIDENCE_DIGEST_MISMATCH, description: 'declared checkpoint evidence bytes changed' }
-      - { code: CHECKPOINT_SCOPE_NOT_FOUND, description: 'the explicit Task or Change scope does not exist' }
-      - { code: CHECKPOINT_SCOPE_MISMATCH, description: 'the explicit Task does not belong to the supplied Change scope' }
-    cli_subcommand: 'ultra checkpoint'
-    emits_events: [ultra_checkpoint_accepted, ultra_checkpoint_rejected]
-
-  - name: ultra.sync
-    family: ultra
-    description: Inspect, import, or publish the Git team checkpoint while preserving local sessions and rejecting real concurrent team-state conflicts.
-    phase: '24'
-    writer_role: mcp
-    input_schema:
-      type: object
-      required: [action]
-      additionalProperties: false
-      properties:
-        action: { type: string, enum: [inspect, import, publish, migrate] }
-        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' }
-      - { code: TASK_LEDGER_HISTORY_CONFLICT, description: 'team checkpoint histories conflict' }
-      - { code: TASK_LEDGER_TASK_CONFLICT, description: 'the same durable task changed concurrently' }
-    cli_subcommand: 'ultra sync'
-
-  - name: ultra.session
-    family: ultra
-    description: Acquire, inspect, heartbeat, or release the small execution lease that requires transactional concurrency control.
-    phase: '24'
-    writer_role: mcp
-    input_schema:
-      type: object
-      required: [action]
-      additionalProperties: false
-      properties:
-        action: { type: string, enum: [admission, acquire, get, list, heartbeat, release] }
-        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' }
-      - { code: SESSION_STATUS_CONFLICT, description: 'a concurrent session transition won' }
-      - { code: LEASE_EXPIRED, description: 'the execution lease already expired' }
-    cli_subcommand: 'ultra session'
-
-  - name: ultra.archive
-    family: ultra
-    description: Archive one caller-declared local Change handoff through a recoverable filesystem and database transaction. The kernel validates authority, paths, digests, reconciliation structure, and recovery safety without requiring a fixed semantic stage sequence.
-    phase: '24'
-    writer_role: mcp
-    input_schema:
-      type: object
-      required: [change_id, payload, idempotency_key]
-      additionalProperties: false
-      properties:
-        change_id: { type: string, minLength: 1 }
-        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:
-      - { code: VALIDATION_ERROR, description: 'input failed structural validation' }
-      - { code: STATE_CORRUPT, description: 'archive authority cannot be trusted' }
-      - { code: ARCHIVE_RUNTIME_UNAVAILABLE, description: 'safe archive primitives are unavailable' }
-    cli_subcommand: 'ultra archive'
-
-  - name: ultra.doctor
-    family: ultra
-    description: Inspect mechanical health and optionally apply only backup-first deterministic repairs. Semantic choices remain with the model and owner.
-    phase: '24'
-    writer_role: mcp
-    input_schema:
-      type: object
-      additionalProperties: false
-      properties:
-        repair: { type: boolean }
-    output_schema: { type: object }
-    errors:
-      - { code: STATE_CORRUPT, description: 'the state database cannot be inspected safely' }
-      - { code: BACKUP_FAILED, description: 'a required recovery backup could not be created' }
-    cli_subcommand: 'ultra doctor'

package/spec/schemas/baseline-reconciliation.v1.schema.json

@@ -1,73 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://ultra-builder-pro.dev/schemas/baseline-reconciliation.v1.schema.json",
-  "title": "Ultra baseline reconciliation v1",
-  "type": "object",
-  "required": [
-    "$schema", "change_id", "baseline_id", "baseline_updates", "semantic_changes",
-    "resolved_gap_ids", "resolved_unknowns", "verification"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "$schema": { "const": "ultra-baseline-reconciliation-v1" },
-    "change_id": { "type": "string", "minLength": 1 },
-    "baseline_id": { "type": ["string", "null"] },
-    "baseline_updates": {
-      "type": "array",
-      "uniqueItems": true,
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "semantic_changes": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id", "action", "source_ref", "before_digest", "after_digest"],
-        "additionalProperties": false,
-        "properties": {
-          "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" },
-          "action": { "enum": ["add", "update"] },
-          "source_ref": { "type": "string", "pattern": "^[^#]+#[^#]+$" },
-          "before_digest": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$" },
-          "after_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
-        }
-      }
-    },
-    "resolved_gap_ids": {
-      "type": "array", "uniqueItems": true,
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "resolved_unknowns": {
-      "type": "array", "uniqueItems": true,
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "verification": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "required": ["name", "command", "status", "evidence"],
-        "additionalProperties": false,
-        "properties": {
-          "name": { "type": "string", "minLength": 1 },
-          "command": { "type": "string", "minLength": 1 },
-          "status": { "const": "pass" },
-          "evidence": { "type": "string", "minLength": 1 }
-        }
-      }
-    },
-    "semantic_no_change_reason": { "type": ["string", "null"], "minLength": 3 }
-  },
-  "allOf": [
-    {
-      "if": { "properties": { "baseline_updates": { "maxItems": 0 } } },
-      "then": {
-        "required": ["semantic_no_change_reason"],
-        "properties": {
-          "semantic_changes": { "maxItems": 0 },
-          "semantic_no_change_reason": { "type": "string", "minLength": 3 }
-        }
-      },
-      "else": { "properties": { "semantic_changes": { "minItems": 1 } } }
-    }
-  ]
-}

package/spec/schemas/change-delta.v1.schema.json

@@ -1,153 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://ultra-builder-pro.dev/schemas/change-delta.v1.schema.json",
-  "title": "Ultra Change delta v1",
-  "type": "object",
-  "required": [
-    "$schema",
-    "change_id",
-    "baseline_anchor",
-    "decisions",
-    "non_goals",
-    "acceptance",
-    "documentation_impact",
-    "unknowns",
-    "mutations"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "$schema": { "const": "ultra-change-delta-v1" },
-    "change_id": { "type": "string", "minLength": 1 },
-    "baseline_anchor": {
-      "type": "object",
-      "required": ["baseline_id", "repository_revision", "specs"],
-      "additionalProperties": false,
-      "properties": {
-        "baseline_id": { "type": "string", "minLength": 1 },
-        "repository_revision": { "type": ["string", "null"] },
-        "specs": {
-          "type": "array",
-          "uniqueItems": true,
-          "items": {
-            "type": "object",
-            "required": ["path", "digest"],
-            "additionalProperties": false,
-            "properties": {
-              "path": { "type": "string", "minLength": 1 },
-              "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
-            }
-          }
-        }
-      }
-    },
-    "decisions": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id", "summary"],
-        "additionalProperties": false,
-        "properties": {
-          "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
-          "summary": { "type": "string", "minLength": 1 },
-          "rationale": { "type": "string", "minLength": 1 }
-        }
-      }
-    },
-    "non_goals": {
-      "type": "array",
-      "uniqueItems": true,
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "acceptance": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "required": ["id", "criterion", "verification"],
-        "additionalProperties": false,
-        "properties": {
-          "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
-          "criterion": { "type": "string", "minLength": 1 },
-          "verification": { "type": "string", "minLength": 1 }
-        }
-      }
-    },
-    "documentation_impact": {
-      "type": "object",
-      "required": ["status", "files", "rationale"],
-      "additionalProperties": false,
-      "properties": {
-        "status": { "enum": ["none", "required"] },
-        "files": {
-          "type": "array",
-          "uniqueItems": true,
-          "items": { "type": "string", "minLength": 1 }
-        },
-        "rationale": { "type": "string", "minLength": 3 }
-      }
-    },
-    "unknowns": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id", "summary", "blocking"],
-        "additionalProperties": false,
-        "properties": {
-          "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
-          "summary": { "type": "string", "minLength": 1 },
-          "blocking": { "type": "boolean" }
-        }
-      }
-    },
-    "no_semantic_change_reason": { "type": "string", "minLength": 3 },
-    "mutations": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": [
-          "id",
-          "action",
-          "target_path",
-          "overlay_path",
-          "before_digest",
-          "after_digest",
-          "acceptance_refs",
-          "documentation_refs"
-        ],
-        "additionalProperties": false,
-        "properties": {
-          "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
-          "action": { "enum": ["add", "update"] },
-          "target_path": { "type": "string", "minLength": 1 },
-          "overlay_path": { "type": "string", "minLength": 1 },
-          "before_digest": {
-            "type": ["string", "null"],
-            "pattern": "^[0-9a-f]{64}$"
-          },
-          "after_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
-          "acceptance_refs": {
-            "type": "array",
-            "minItems": 1,
-            "uniqueItems": true,
-            "items": { "type": "string", "minLength": 1 }
-          },
-          "documentation_refs": {
-            "type": "array",
-            "uniqueItems": true,
-            "items": { "type": "string", "minLength": 1 }
-          }
-        }
-      }
-    }
-  },
-  "allOf": [
-    {
-      "if": {
-        "properties": {
-          "mutations": { "maxItems": 0 }
-        }
-      },
-      "then": { "required": ["no_semantic_change_reason"] }
-    }
-  ]
-}

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

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://ultra-builder-pro.dev/spec/command-manifest.schema.json",
-  "title": "Ultra command launcher frontmatter",
-  "description": "Portable source contract for a thin command launcher. Runtime metadata and workflow procedure belong outside the command file.",
-  "type": "object",
-  "required": ["description", "workflow-ref"],
-  "additionalProperties": false,
-  "properties": {
-    "description": {
-      "type": "string",
-      "minLength": 10,
-      "maxLength": 240,
-      "description": "Concise user-visible action description."
-    },
-    "argument-hint": {
-      "oneOf": [
-        { "type": "string" },
-        { "type": "array", "items": { "type": "string" }, "minItems": 1 }
-      ],
-      "description": "Optional host launcher hint; it does not define argument semantics."
-    },
-    "workflow-ref": {
-      "type": "string",
-      "pattern": "^@skills/[a-z][a-z0-9\\-]*/SKILL\\.md$",
-      "description": "The single Skill that owns this workflow."
-    }
-  }
-}

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

@@ -1,54 +0,0 @@
-{
-  "$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/.runtime/projections/contexts/task-*.md. The file is regenerated by the projector from state.db and remains checkout-local. Authority boundary: docs/ARTIFACT-AUTHORITY.md.",
-  "type": "object",
-  "required": ["header", "body"],
-  "additionalProperties": false,
-  "properties": {
-    "header": {
-      "type": "object",
-      "required": ["task_id", "title", "status", "schema_version"],
-      "additionalProperties": false,
-      "properties": {
-        "task_id":        { "type": "string" },
-        "title":          { "type": "string" },
-        "status": {
-          "type": "string",
-          "enum": ["pending", "in_progress", "completed", "blocked", "expanded"],
-          "x-derived": true,
-          "description": "DERIVED from state.db tasks.status; written by projector, not by humans"
-        },
-        "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" }
-      }
-    },
-    "body": {
-      "type": "object",
-      "required": ["sections"],
-      "additionalProperties": false,
-      "properties": {
-        "sections": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": ["heading", "content"],
-            "additionalProperties": false,
-            "properties": {
-              "heading": {
-                "type": "string",
-                "not": { "pattern": "^[Ss]tatus" },
-                "description": "body sections cannot be 'Status' — that lives only in header (D17)"
-              },
-              "content": { "type": "string" }
-            }
-          }
-        }
-      }
-    }
-  }
-}