ultra-builder-pro-cli 0.5.0

package/spec/mcp-tools.yaml

@@ -0,0 +1,658 @@
+# Ultra Builder Pro — MCP tool contracts
+# Single source for tool name, schema, errors, and CLI mapping.
+# Validated by spec/schemas/mcp-tools.schema.json (run `npm run test:spec`).
+# Trace: PLAN §7.3, decisions D12 / D29 / D31-D34.
+
+version: '1.0'
+
+info:
+  title: Ultra Builder Pro MCP tool contracts
+  phase: '1.1'
+  trace_to: 'PLAN docs/PLAN.zh-CN.md §7.3'
+  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 (R19).
+    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: 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' }
+
+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.
+    phase: '2'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [title, type, priority]
+      additionalProperties: false
+      properties:
+        id:             { type: string, pattern: '^[a-zA-Z0-9_\-]+$', description: 'optional caller-supplied id; otherwise server mints a uuid' }
+        title:          { type: string, minLength: 3 }
+        type:           { type: string, enum: [architecture, feature, bugfix] }
+        priority:       { type: string, enum: [P0, P1, P2, P3] }
+        complexity:     { type: integer, minimum: 1, maximum: 10 }
+        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' }
+        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)' }
+    output_schema:
+      type: object
+      required: [id, status, created_at]
+      additionalProperties: false
+      properties:
+        id:         { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        status:     { type: string, enum: [pending] }
+        created_at: { type: string, format: date-time }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'input failed schema validation' }
+      - { code: DUPLICATE_TASK_ID, description: 'task id already exists' }
+      - { code: STATE_DB_LOCKED, description: 'database is locked', retriable: true }
+    cli_subcommand: task create
+    emits_events: [task_created]
+    trace_to: '§7.3, §7.1'
+
+  - name: task.update
+    family: task
+    description: Patch a task's mutable fields. status transitions enforced server-side.
+    phase: '2'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, patch]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        patch:
+          type: object
+          additionalProperties: false
+          properties:
+            status:        { type: string, enum: [pending, in_progress, completed, blocked, expanded] }
+            priority:      { type: string, enum: [P0, P1, P2, P3] }
+            complexity:    { type: integer, minimum: 1, maximum: 10 }
+            deps:          { type: array, items: { type: string } }
+            files_modified: { type: array, items: { type: string } }
+            session_id:    { type: string }
+            stale:         { type: boolean }
+            tag:           { type: string }
+            completion_commit: { type: string, pattern: '^[0-9a-f]{7,40}$' }
+    output_schema:
+      type: object
+      required: [ok, task]
+      additionalProperties: false
+      properties:
+        ok:   { type: boolean }
+        task: { type: object }
+    errors:
+      - { 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' }
+    cli_subcommand: task update
+    emits_events: [task_started, task_completed, task_blocked, task_stale_marked]
+    trace_to: '§7.3, §7.2'
+
+  - name: task.list
+    family: task
+    description: List tasks filtered by status / tag / time window.
+    phase: '2'
+    readonly: true
+    writer_role: any
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        status: { type: string, enum: [pending, in_progress, completed, blocked, expanded, any] }
+        tag:    { type: string }
+        since:  { type: string, format: date-time }
+        limit:  { type: integer, minimum: 1, maximum: 1000 }
+    output_schema:
+      type: object
+      required: [tasks, count]
+      additionalProperties: false
+      properties:
+        tasks: { type: array, items: { type: object } }
+        count: { type: integer, minimum: 0 }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'filter failed schema validation' }
+    cli_subcommand: task list
+    emits_events: []
+    trace_to: '§7.3'
+
+  - name: task.get
+    family: task
+    description: Fetch one task with its full row.
+    phase: '2'
+    readonly: true
+    writer_role: any
+    input_schema:
+      type: object
+      required: [id]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+    output_schema:
+      type: object
+      required: [task]
+      additionalProperties: false
+      properties:
+        task: { type: object }
+    errors:
+      - { code: TASK_NOT_FOUND, description: 'no task with given id' }
+    cli_subcommand: task get
+    emits_events: []
+    trace_to: '§7.3'
+
+  - name: task.switch_tag
+    family: task
+    description: Change a task's tag (branch-scoped context partition, Phase 7.2). Emits task_tag_changed.
+    phase: '7.2'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, tag]
+      additionalProperties: false
+      properties:
+        id:  { type: string }
+        tag: { type: ['string', 'null'] }
+    output_schema:
+      type: object
+      required: [task_id, tag]
+      additionalProperties: false
+      properties:
+        task_id: { type: string }
+        tag:     { type: ['string', 'null'] }
+        from:    { type: ['string', 'null'] }
+    errors:
+      - { code: TASK_NOT_FOUND, description: 'no task with given id' }
+      - { code: VALIDATION_ERROR, description: 'task_id missing' }
+    cli_subcommand: task switch-tag
+    emits_events: [task_tag_changed]
+    trace_to: '§6, D26'
+
+  - name: task.delete
+    family: task
+    description: Hard-delete a task. Refuses if any in_progress session is bound.
+    phase: '2'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id]
+      additionalProperties: false
+      properties:
+        id:    { type: string }
+        force: { type: boolean, default: false }
+    output_schema:
+      type: object
+      required: [ok]
+      additionalProperties: false
+      properties:
+        ok: { type: boolean }
+    errors:
+      - { code: TASK_NOT_FOUND, description: 'no task with given id' }
+      - { code: SESSION_ACTIVE, description: 'task has an active session; pass force=true to override' }
+    cli_subcommand: task delete
+    emits_events: []
+    trace_to: '§7.3'
+
+  - 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.
+    phase: '3'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [target_dir, project_name]
+      additionalProperties: false
+      properties:
+        target_dir:
+          type: string
+          description: absolute or repo-relative path of the project root where `.ultra/` will be created
+        project_name:
+          type: string
+          minLength: 1
+        project_type:
+          type: string
+          enum: [web, api, cli, fullstack, other]
+          description: optional; skill will pass detected value when available
+        stack:
+          type: string
+          description: optional tech stack descriptor (comma-separated for fullstack)
+        overwrite:
+          type: boolean
+          default: false
+          description: when true, back up an existing `.ultra/` to `.ultra.backup.<ts>` then re-create
+        source_template:
+          type: string
+          description: override path to the template root (defaults to bundled templates/.ultra/)
+    output_schema:
+      type: object
+      required: [created_path, status, copied_files]
+      additionalProperties: false
+      properties:
+        created_path:
+          type: string
+          description: absolute path to the created `.ultra/` directory
+        status:
+          type: string
+          enum: [created, overwritten]
+        copied_files:
+          type: array
+          items: { type: string }
+          description: paths relative to created_path
+        backup_path:
+          type: string
+          description: set only when status=overwritten
+    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: IO_ERROR,          description: 'filesystem write failed', retriable: true }
+    cli_subcommand: task init-project
+    emits_events: [project_initialized]
+    trace_to: 'PLAN §6 Phase 3.1'
+
+  - name: task.expand
+    family: task
+    description: Expand a parent task into N child sub-tasks (Phase 8A).
+    phase: '8a'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id]
+      additionalProperties: false
+      properties:
+        id:        { type: string }
+        sub_count: { type: integer, minimum: 1, maximum: 16 }
+        strategy:  { type: string, enum: [llm], default: llm }
+    output_schema:
+      type: object
+      required: [parent_id, children]
+      additionalProperties: false
+      properties:
+        parent_id: { type: string }
+        children:  { type: array, items: { type: object } }
+    errors:
+      - { code: TASK_NOT_FOUND, description: 'parent id missing' }
+      - { code: ALREADY_EXPANDED, description: 'task is already expanded' }
+    cli_subcommand: task expand
+    emits_events: [task_expanded]
+    trace_to: '§7.3, D34'
+
+  - name: task.parse_prd
+    family: task
+    description: Parse a PRD document into a task graph (Phase 8A). When dry_run=true the tasks are returned without writing to state.db (supports ultra-plan human gate workflow).
+    phase: '8a'
+    writer_role: mcp
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        prd_path: { type: string }
+        prd_text: { type: string }
+        tag:      { type: string }
+        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
+      required: [tasks, topo]
+      additionalProperties: false
+      properties:
+        tasks: { type: array, items: { type: object } }
+        topo:  { type: array, items: { type: array, items: { type: string } } }
+    errors:
+      - { code: NO_INPUT, description: 'one of prd_path or prd_text required' }
+      - { code: PARSE_FAILED, description: 'PRD could not be parsed into tasks' }
+    cli_subcommand: task parse-prd
+    emits_events: [task_created]
+    trace_to: '§7.3, D34'
+
+  - name: task.dependency_topo
+    family: task
+    description: Compute topological waves for a set of tasks; consumed by execution-plan.
+    phase: '8a'
+    readonly: true
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        task_ids: { type: array, items: { type: string } }
+    output_schema:
+      type: object
+      required: [waves]
+      additionalProperties: false
+      properties:
+        waves: { type: array, items: { type: array, items: { type: string } } }
+        cycles: { type: array, items: { type: array, items: { type: string } } }
+    errors:
+      - { code: CYCLE_DETECTED, description: 'dependency graph has cycles' }
+    cli_subcommand: task topo
+    emits_events: []
+    trace_to: '§7.3, D34'
+
+  - name: task.append_event
+    family: task
+    description: Append a row to events table. Returns assigned id (subscribe cursor).
+    phase: '2'
+    writer_role: any
+    input_schema:
+      type: object
+      required: [type]
+      additionalProperties: false
+      properties:
+        task_id:    { type: string }
+        session_id: { type: string }
+        runtime:    { type: string, enum: [claude, opencode, codex, gemini] }
+        type:
+          type: string
+          enum:
+            - task_created
+            - task_started
+            - task_completed
+            - task_failed
+            - task_blocked
+            - task_expanded
+            - task_stale_marked
+            - session_spawned
+            - session_closed
+            - session_crashed
+            - session_orphaned
+            - session_heartbeat_lost
+            - spec_changed
+            - context_updated
+            - plan_approved
+            - commit_pushed
+            - review_verdict
+            - merge_conflict
+            - auto_merged
+            - cost_alert
+            - token_alert
+            - circuit_open
+        payload: { type: object }
+    output_schema:
+      type: object
+      required: [event_id, ts]
+      additionalProperties: false
+      properties:
+        event_id: { type: integer, minimum: 1 }
+        ts:       { type: string, format: date-time }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'event payload failed validation' }
+      - { code: STATE_DB_LOCKED, description: 'database is locked', retriable: true }
+    cli_subcommand: task append-event
+    emits_events: []
+    trace_to: '§7.2, D31'
+
+  - name: task.subscribe_events
+    family: task
+    description: Pull events with id > since_id. Cursor is monotonic (D31, R26).
+    phase: '2'
+    readonly: true
+    input_schema:
+      type: object
+      required: [since_id]
+      additionalProperties: false
+      properties:
+        since_id: { type: integer, minimum: 0 }
+        types:    { type: array, items: { type: string } }
+        task_id:  { type: string }
+        limit:    { type: integer, minimum: 1, maximum: 500, default: 100 }
+    output_schema:
+      type: object
+      required: [events, next_since_id]
+      additionalProperties: false
+      properties:
+        events: { type: array, items: { type: object } }
+        next_since_id: { type: integer, minimum: 0 }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'cursor or filter invalid' }
+    cli_subcommand: task subscribe
+    emits_events: []
+    trace_to: '§7.2, D31'
+
+  # ────────────────────────── session family ──────────────────────────────
+  - name: session.spawn
+    family: session
+    description: Register execution-session intent, lease, and proposed worktree/artifact paths. The orchestrator creates the process and worktree after this admission step.
+    phase: '4.5'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [task_id, runtime]
+      additionalProperties: false
+      properties:
+        task_id:  { type: string }
+        runtime:  { type: string, enum: [claude, opencode, codex, gemini] }
+        takeover: { type: boolean, default: false, description: 'override active lease (D33 takeover strategy)' }
+        worktree_base: { type: string }
+    output_schema:
+      type: object
+      required: [sid, worktree_path, artifact_dir, lease_expires_at]
+      additionalProperties: false
+      properties:
+        sid:               { type: string }
+        worktree_path:     { type: string }
+        artifact_dir:      { type: string }
+        lease_expires_at:  { type: string, format: date-time }
+    errors:
+      - { code: TASK_NOT_FOUND, description: 'task id missing' }
+      - { code: ADMISSION_DENIED, description: 'active lease exists; choose takeover/resume/abandon' }
+    cli_subcommand: session spawn
+    emits_events: [session_spawned]
+    trace_to: '§7.3, D20, D33'
+
+  - name: session.close
+    family: session
+    description: Close a session and release its lease.
+    phase: '4.5'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [sid, status]
+      additionalProperties: false
+      properties:
+        sid:    { type: string }
+        status: { type: string, enum: [completed, crashed, orphan] }
+    output_schema:
+      type: object
+      required: [ok]
+      additionalProperties: false
+      properties:
+        ok: { type: boolean }
+    errors:
+      - { code: SESSION_NOT_FOUND, description: 'sid unknown' }
+    cli_subcommand: session close
+    emits_events: [session_closed, session_crashed, session_orphaned]
+    trace_to: '§7.3, D32'
+
+  - name: session.get
+    family: session
+    description: Fetch a session row.
+    phase: '4.5'
+    readonly: true
+    input_schema:
+      type: object
+      required: [sid]
+      additionalProperties: false
+      properties:
+        sid: { type: string }
+    output_schema:
+      type: object
+      required: [session]
+      additionalProperties: false
+      properties:
+        session: { type: object }
+    errors:
+      - { code: SESSION_NOT_FOUND, description: 'sid unknown' }
+    cli_subcommand: session get
+    emits_events: []
+    trace_to: '§7.3'
+
+  - name: session.list
+    family: session
+    description: List sessions filtered by status (default 'running') and optional task_id. Read-only snapshot for /ultra-status + orchestrator dashboards.
+    phase: '4.5'
+    readonly: true
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        status:   { type: string, enum: [running, completed, crashed, orphan] }
+        task_id:  { type: string }
+        limit:    { type: integer, minimum: 1, maximum: 500, default: 100 }
+    output_schema:
+      type: object
+      required: [sessions, count]
+      additionalProperties: false
+      properties:
+        sessions: { type: array, items: { type: object } }
+        count:    { type: integer, minimum: 0 }
+    errors:
+      - { code: STATE_DB_ERROR, description: 'database unavailable', retriable: true }
+    cli_subcommand: session list
+    emits_events: []
+    trace_to: '§7.3, Phase 4.5.4'
+
+  - name: session.admission_check
+    family: session
+    description: Check whether spawning a new session for task_id is allowed (D33). Returns recommended action.
+    phase: '4.5'
+    readonly: true
+    input_schema:
+      type: object
+      required: [task_id]
+      additionalProperties: false
+      properties:
+        task_id: { type: string }
+        runtime: { type: string, enum: [claude, opencode, codex, gemini] }
+    output_schema:
+      type: object
+      required: [can_spawn, recommended_action]
+      additionalProperties: false
+      properties:
+        can_spawn:          { type: boolean }
+        conflict:
+          type: object
+          properties:
+            sid:          { type: string }
+            status:       { type: string }
+            heartbeat_age_ms: { type: integer, minimum: 0 }
+        recommended_action:
+          type: string
+          enum: [spawn, takeover, resume, abandon, blocked_by_breaker]
+    errors:
+      - { code: TASK_NOT_FOUND, description: 'task id missing' }
+    cli_subcommand: session admission
+    emits_events: []
+    trace_to: '§7.3, D33'
+
+  - name: session.heartbeat
+    family: session
+    description: Refresh lease for a running session. Lease expires after grace period without heartbeat.
+    phase: '4.5'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [sid]
+      additionalProperties: false
+      properties:
+        sid: { type: string }
+    output_schema:
+      type: object
+      required: [ok, lease_expires_at]
+      additionalProperties: false
+      properties:
+        ok:               { type: boolean }
+        lease_expires_at: { type: string, format: date-time }
+    errors:
+      - { code: SESSION_NOT_FOUND, description: 'sid unknown' }
+      - { code: LEASE_EXPIRED, description: 'lease already expired; need takeover/resume' }
+    cli_subcommand: session heartbeat
+    emits_events: [session_heartbeat_lost]
+    trace_to: '§7.3, D32'
+
+  - name: session.subscribe_events
+    family: session
+    description: Pull session-related events with cursor.
+    phase: '4.5'
+    readonly: true
+    input_schema:
+      type: object
+      required: [since_id]
+      additionalProperties: false
+      properties:
+        since_id: { type: integer, minimum: 0 }
+        sid:      { type: string }
+        limit:    { type: integer, minimum: 1, maximum: 500, default: 100 }
+    output_schema:
+      type: object
+      required: [events, next_since_id]
+      additionalProperties: false
+      properties:
+        events:        { type: array, items: { type: object } }
+        next_since_id: { type: integer, minimum: 0 }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'cursor invalid' }
+    cli_subcommand: session subscribe
+    emits_events: []
+    trace_to: '§7.3, D31'
+
+  # ────────────────────────── plan family (D34) ───────────────────────────
+  - name: plan.export
+    family: plan
+    description: Render the current execution-plan artifact to disk (waves + ownership + conflict surface).
+    phase: '8a'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [out_path]
+      additionalProperties: false
+      properties:
+        format:   { type: string, enum: [json, md], default: json }
+        out_path: { type: string }
+        tag:      { type: string }
+    output_schema:
+      type: object
+      required: [plan_path, wave_count]
+      additionalProperties: false
+      properties:
+        plan_path:  { type: string }
+        wave_count: { type: integer, minimum: 0 }
+    errors:
+      - { code: NO_TASKS, description: 'no tasks to plan' }
+      - { code: WRITE_FAILED, description: 'cannot write plan file' }
+    cli_subcommand: plan export
+    emits_events: [plan_approved]
+    trace_to: '§7.3, D34'
+
+  - name: plan.get
+    family: plan
+    description: Read a section of the current project's persisted .ultra/execution-plan.json artifact.
+    phase: '8a'
+    readonly: true
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        section: { type: string, enum: [tasks, topo, conflicts, all], default: all }
+    output_schema:
+      type: object
+      required: [plan]
+      additionalProperties: false
+      properties:
+        plan: { type: object }
+    errors:
+      - { code: NO_PLAN, description: 'no plan has been computed yet' }
+    cli_subcommand: plan get
+    emits_events: []
+    trace_to: '§7.3, D34'

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

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultra-builder-pro.dev/spec/command-manifest.schema.json",
+  "title": "Command manifest (frontmatter)",
+  "description": "YAML frontmatter contract for commands/ultra-*.md thin-shell files. Phase 3 薄壳化: 命令文件 ≤ 80 行正文，真实 workflow 放 skills/<name>/SKILL.md。additionalProperties=false (PLAN R19).",
+  "type": "object",
+  "required": ["description"],
+  "additionalProperties": false,
+  "properties": {
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "description": "一句话触发描述; 给 runtime 的 skill router / 用户命令列表使用"
+    },
+    "argument-hint": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+      ],
+      "description": "Claude Code convention: hint shown after slash-command name. Both `argument-hint: [foo]` (YAML array form) and `argument-hint: \"[foo]\"` (string form) are accepted."
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Claude Code convention: comma-separated tool allowlist"
+    },
+    "model": {
+      "type": "string",
+      "enum": ["haiku", "sonnet", "opus"],
+      "description": "Claude Code convention: model routing hint"
+    },
+    "workflow-ref": {
+      "type": "string",
+      "pattern": "^@skills/[a-z][a-z0-9\\-]*/SKILL\\.md$",
+      "description": "Phase 3 薄壳关键字段: 指向 skills/<name>/SKILL.md; 存在即表示该命令已迁为薄壳"
+    },
+    "mcp_tools_required": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z]+\\.[a-z_]+$" },
+      "uniqueItems": true,
+      "description": "Phase 3+: 命令运行时会调用的 MCP tool 名单; 无 MCP 时走 cli_fallback"
+    },
+    "cli_fallback": {
+      "type": "string",
+      "description": "Phase 3+: MCP 不可达时回退的 ultra-tools 子命令 (e.g. 'init' -> 'ultra-tools init')"
+    }
+  }
+}