ultra-builder-pro-cli 0.21.1 → 0.23.0

package/skills/ultra-think/SKILL.md

@@ -3,55 +3,36 @@ name: ultra-think
 description: Resolve a consequential product, architecture, or recovery question through evidence-first reasoning and adaptive user alignment. Use when a material decision cannot be derived safely from accepted intent and current evidence.
 ---
 
-# Align without suppressing model judgment
+# Align without suppressing judgment
 
-Thinking is an optional reasoning capability, not a mandatory stage. Answer
-self-contained questions directly. Use durable decision state only when a
-project-bound choice must survive interruption or gate later work.
+Thinking is optional. Answer self-contained questions directly. Persist only a
+project-bound decision that must survive interruption or control later work.
 
-## Reason first
+## Reason and interact
 
-1. Define the actual decision or disputed claim and the constraints that can change
-   its answer.
-2. Inspect current authority, source, runtime, tests, and primary documentation before
-   asking the user for facts.
-3. Separate verified fact, evidence-backed inference, accepted intent, delegated
+1. Call `ultra.context` for the relevant project or Change scope.
+2. Define the real decision and the constraints that can change its answer.
+3. Inspect source, runtime, tests, accepted artifacts, and primary documentation
+   before asking the owner for facts.
+4. Separate verified fact, evidence-backed inference, accepted intent, delegated
    implementation judgment, and unresolved owner choice.
-4. Form credible alternatives only when alternatives materially help the decision.
-   Evaluate them against the real constraints; do not impose a fixed option count,
-   scoring system, or confidence percentage.
-5. Stress-test the leading answer with its strongest counterexample, likely failure
-   path, recovery, and load-bearing assumption.
-
-## Interact adaptively
-
-Read `references/decision-dialogue.md`. If the user already gave a clear decision,
-normalize and use it without asking for confirmation. If the decision is reversible
-and delegated by the accepted contract, decide it and explain the reasoning.
-
-When owner authority is required, use the host's native question UI when available.
-Ask the earliest dependent decision with a recommendation, decisive evidence, and the
-effect of the answer. Keep cognitive load small; group only independent, simple facts.
-Do not expose the hidden decision queue.
-
-For durable project decisions, use `decision.thread_start`, `decision.open`, and the
-appropriate resolve, delegate, defer, or supersede transition. Store normalized
-decisions and artifact references, never transcripts or internal reasoning.
-Apply any resulting change through its owning baseline, change, workflow, task, or
-semantic artifact operation, read it back, and pass typed `applied_refs` to
-`decision.complete`. If the decision record itself is the complete durable authority,
-the list may be empty. Completion is not another owner approval.
-
-Prepare and confirm a checkpoint only when the decision changes a durable contract or
-artifact and a checkpoint is needed for recovery. Do not add a ceremonial approval
-gate to an already explicit user instruction or a reversible implementation detail.
-
-## Return control
-
-Return the conclusion, decisive evidence, material uncertainty, and affected
-contracts. Re-read the invoking workflow or breadcrumb and recommend one of its
-`allowed_transitions`; follow `required_transition` only when a hard invariant leaves
-no alternative. Thinking does not implement code, mutate unrelated state, or invent a
-canonical next action.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+5. Stress-test the leading answer with its strongest failure path and recovery.
+
+Read `references/decision-dialogue.md`. Reuse a clear decision already present in the
+request. Decide reversible delegated implementation details yourself. When owner
+authority is necessary, ask one dependent decision through the host-native question
+surface with a recommendation, decisive evidence, and the effect of the answer.
+
+## Persist only the normalized result
+
+Use one `ultra.record` batch for `decision.thread_start`, `decision.open`, the
+appropriate resolve/delegate/defer/supersede operation, the owning artifact mutation,
+and `decision.complete` when they are all known. Store normalized decisions and
+artifact references, never transcripts or internal reasoning.
+
+A semantic rejection remains a mutable diagnostic. Correct the record or intentionally
+abandon the draft; do not invent a new decision merely to satisfy a state machine.
+
+Return the conclusion, decisive evidence, uncertainty, affected authority, and the
+model's recommended next explicit capability. Thinking never performs unrelated
+implementation or an external effect. Do not invoke the next capability automatically.

package/skills/ultra-think/references/decision-dialogue.md

@@ -147,7 +147,9 @@ exists; that exception does not create interaction proof.
 
 ## Return to the capability graph
 
-After alignment, re-read the invoking workflow and breadcrumb. A
-`required_transition` is authoritative only for a hard invariant. Otherwise the host
-model recommends among `allowed_transitions` based on the user's goal and current
-evidence. Do not persist that semantic recommendation as MCP authority.
+After alignment, re-read `ultra.context` for the invoking scope. The host model
+recommends the next explicit capability from the user's goal, accepted intent,
+evidence, recovery cost, and current warnings or blockers. MCP diagnostics describe
+mechanical facts; they do not encode a semantic route or persist the recommendation
+as authority. Only corruption, unsafe paths, true concurrency conflicts, permissions,
+or irreversible external effects are hard blockers.

package/spec/cli-protocol.md

@@ -81,6 +81,13 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 
 | MCP tool                  | CLI subcommand              | Phase | Writer  |
 |---------------------------|-----------------------------|------:|---------|
+| `ultra.context`           | `ultra context`             | 23    | mcp     |
+| `ultra.record`            | `ultra record`              | 23    | mcp     |
+| `ultra.checkpoint`        | `ultra checkpoint`          | 23    | mcp     |
+| `ultra.sync`              | `ultra sync`                | 23    | mcp     |
+| `ultra.session`           | `ultra session`             | 23    | mcp     |
+| `ultra.archive`           | `ultra archive`             | 23    | mcp     |
+| `ultra.doctor`            | `ultra doctor`              | 23    | mcp     |
 | `task.create`             | `task create`               | 2     | mcp     |
 | `task.update`             | `task update`               | 2     | mcp     |
 | `task.list`               | `task list`                 | 2     | any     |
@@ -91,6 +98,9 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 | `task.expand`             | `task expand`               | 8a    | mcp     |
 | `task.parse_prd`          | `task parse-prd`            | 8a    | mcp     |
 | `task.dependency_topo`    | `task topo`                 | 8a    | mcp     |
+| `task.ledger_get`         | `task ledger-get`           | 21    | any     |
+| `task.ledger_publish`     | `task ledger-publish`       | 21    | mcp     |
+| `task.ledger_import`      | `task ledger-import`        | 21    | mcp     |
 | `task.append_event`       | `task append-event`         | 2     | any (allowlisted observations only) |
 | `task.subscribe_events`   | `task subscribe`            | 2     | any     |
 | `session.spawn`           | `session spawn`             | 4.5   | mcp     |
@@ -139,6 +149,11 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 | `plan.export`             | `plan export`               | 8a    | mcp     |
 | `plan.get`                | `plan get`                  | 8a    | any     |
 
+The seven `ultra.*` rows are the public model-facing MCP surface. The remaining
+rows are one-release compatibility operations and CLI naming reservations; they
+are callable by an already-running 0.22 session but are not returned by
+`tools/list`.
+
 Current executable maintenance surfaces are `task init-project`,
 `session close|get|list|admission|heartbeat|subscribe|reap`, `status`, `db`,
 `migrate`, `system doctor|restore|rebaseline`, and `legacy-memory`. In particular, `task create|update|list|get`

package/spec/mcp-tools.yaml

@@ -20,6 +20,7 @@ info:
     fixture to spec/fixtures/{valid,invalid}/, (c) `npm run test:spec` green.
 
 families:
+  - { name: ultra,   description: 'narrow model-facing persistence and safety kernel', phase: '23' }
   - { 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' }
@@ -32,6 +33,164 @@ families:
 
 tools:
 
+  # ───────────────────── public model-facing kernel ─────────────────────
+  - name: ultra.context
+    family: ultra
+    description: Read the complete current Ultra spine and optionally compile one stage-scoped Context Manifest. This tool reports warnings and blockers without choosing the next semantic action.
+    phase: '23'
+    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. Semantic rejections are returned as mutable diagnostics rather than transport errors.
+    phase: '23'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [entries]
+      additionalProperties: false
+      properties:
+        entries:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required: [operation, data, idempotency_key]
+            additionalProperties: false
+            properties:
+              operation: { type: string, minLength: 3 }
+              data: { type: 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: Attempt one semantic stage checkpoint. Failed semantic checks return blockers and leave the draft mutable; accepted checkpoints commit durable authority once.
+    phase: '23'
+    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 }
+        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' }
+    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: '23'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [action]
+      additionalProperties: false
+      properties:
+        action: { type: string, enum: [inspect, import, publish] }
+        reason: { type: string }
+        idempotency_key: { type: string }
+    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: '23'
+    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 }
+        payload: { type: object }
+        idempotency_key: { type: string }
+    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: Converge and archive one accepted Change through the recoverable filesystem and database transaction boundary.
+    phase: '23'
+    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 }
+        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: '23'
+    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'
+
   # ─────────────────────────── task family ────────────────────────────────
   - name: task.create
     family: task
@@ -233,6 +392,106 @@ tools:
     emits_events: []
     trace_to: '§7.3'
 
+  - name: task.ledger_get
+    family: task
+    description: Read the Git-facing durable baseline, Change, and task checkpoint ledger and compare it with local SQLite authority.
+    phase: '21'
+    readonly: true
+    writer_role: any
+    input_schema:
+      type: object
+      additionalProperties: false
+    output_schema:
+      type: object
+      required: [ledger, health]
+      additionalProperties: false
+      properties:
+        ledger: { type: ['object', 'null'] }
+        health: { type: object }
+    errors:
+      - { code: TASK_LEDGER_INVALID, description: 'the Git ledger is malformed' }
+      - { code: TASK_LEDGER_DIGEST_MISMATCH, description: 'ledger content does not match its digest' }
+      - { code: TASK_LEDGER_UNSAFE, description: 'ledger path is a symlink or non-regular file' }
+    cli_subcommand: task ledger-get
+    emits_events: []
+    trace_to: 'docs/ARTIFACT-AUTHORITY.md#team-task-ledger'
+
+  - name: task.ledger_publish
+    family: task
+    description: Publish a low-frequency Git-facing baseline, Change, and task checkpoint from local SQLite authority.
+    phase: '21'
+    writer_role: mcp
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        reason:
+          type: string
+          minLength: 1
+          default: manual_checkpoint
+    output_schema:
+      type: object
+      required: [changed, path, generation, state_digest]
+      additionalProperties: false
+      properties:
+        changed: { type: boolean }
+        path: { type: string }
+        generation: { type: integer, minimum: 0 }
+        state_digest: { type: string, pattern: '^[0-9a-f]{64}$' }
+        migrated_legacy_projection: { type: boolean }
+        legacy_backup_path: { type: string }
+    errors:
+      - { code: TASK_LEDGER_INVALID, description: 'the prior Git ledger is malformed' }
+      - { code: TASK_LEDGER_DIGEST_MISMATCH, description: 'prior ledger content does not match its digest' }
+      - { code: TASK_LEDGER_UNSAFE, description: 'ledger path is a symlink or non-regular file' }
+      - { code: TASK_LEDGER_CHANGE_MISSING, description: 'a task has no portable owning Change' }
+      - { code: TASK_LEDGER_LEGACY_CONFLICT, description: 'the legacy task projection differs from SQLite authority and cannot be replaced automatically' }
+      - { code: TASK_LEDGER_REVALIDATION_REQUIRED, description: 'an imported ready baseline must converge in this checkout before publication' }
+    cli_subcommand: task ledger-publish
+    emits_events: [task_ledger_published]
+    trace_to: 'docs/ARTIFACT-AUTHORITY.md#team-task-ledger'
+
+  - name: task.ledger_import
+    family: task
+    description: Import a validated Git checkpoint into local SQLite authority with per-baseline, per-Change, and per-task conflict checks.
+    phase: '21'
+    writer_role: mcp
+    input_schema:
+      type: object
+      additionalProperties: false
+    output_schema:
+      type: object
+      required: [imported, preserved, deleted, imported_changes, preserved_changes, imported_baseline, preserved_baseline, generation, state_digest, requires_plan_revalidation, requires_baseline_revalidation, already_current]
+      additionalProperties: false
+      properties:
+        imported: { type: integer, minimum: 0 }
+        preserved: { type: integer, minimum: 0 }
+        deleted: { type: integer, minimum: 0 }
+        imported_changes: { type: integer, minimum: 0 }
+        preserved_changes: { type: integer, minimum: 0 }
+        imported_baseline: { type: boolean }
+        preserved_baseline: { type: boolean }
+        generation: { type: integer, minimum: 0 }
+        state_digest: { type: string, pattern: '^[0-9a-f]{64}$' }
+        requires_plan_revalidation: { type: boolean }
+        requires_baseline_revalidation: { type: boolean }
+        already_current: { type: boolean }
+    errors:
+      - { code: TASK_LEDGER_INVALID, description: 'the Git ledger is malformed' }
+      - { code: TASK_LEDGER_DIGEST_MISMATCH, description: 'ledger content does not match its digest' }
+      - { code: TASK_LEDGER_UNSAFE, description: 'ledger path is a symlink or non-regular file' }
+      - { code: TASK_LEDGER_CONFLICT, description: 'the same task changed locally and in Git' }
+      - { code: TASK_LEDGER_ACTIVE_TASK_CONFLICT, description: 'Git changed a task with an active local session' }
+      - { code: TASK_LEDGER_STALE, description: 'the Git ledger is older than the last local checkpoint' }
+      - { code: TASK_LEDGER_HISTORY_CONFLICT, description: 'the Git ledger does not descend from the last local checkpoint' }
+      - { code: TASK_LEDGER_CHANGE_MISSING, description: 'a task references an unavailable Change' }
+      - { code: TASK_LEDGER_PARENT_MISSING, description: 'a task references an unavailable parent task' }
+      - { code: TASK_LEDGER_CHANGE_CONFLICT, description: 'the same Change changed locally and in Git' }
+      - { code: TASK_LEDGER_BASELINE_CONFLICT, description: 'the same baseline changed locally and in Git' }
+    cli_subcommand: task ledger-import
+    emits_events: [task_ledger_imported]
+    trace_to: 'docs/ARTIFACT-AUTHORITY.md#team-task-ledger'
+
   - name: task.switch_tag
     family: task
     description: Change a task's tag (branch-scoped context partition, Phase 7.2). Emits task_tag_changed.
@@ -389,6 +648,32 @@ tools:
         migration_backup_path:
           type: string
           description: pre-migration database backup created while resuming an older schema
+        runtime_migration_backup_path:
+          type: string
+          description: verified backup of a legacy runtime layout moved into `.ultra/.runtime/`
+        team_checkpoint:
+          type: object
+          additionalProperties: false
+          required: [generation, state_digest, imported_tasks, deleted_tasks, imported_changes, imported_baseline, requires_plan_revalidation, requires_baseline_revalidation, already_current]
+          properties:
+            generation: { type: integer, minimum: 0 }
+            state_digest: { type: string, pattern: '^[0-9a-f]{64}$' }
+            imported_tasks: { type: integer, minimum: 0 }
+            deleted_tasks: { type: integer, minimum: 0 }
+            imported_changes: { type: integer, minimum: 0 }
+            imported_baseline: { type: boolean }
+            requires_plan_revalidation: { type: boolean }
+            requires_baseline_revalidation: { type: boolean }
+            already_current: { type: boolean }
+            published:
+              type: boolean
+              description: true when resume replaced a matching legacy task projection with a new team checkpoint
+            migrated_legacy_projection:
+              type: boolean
+              description: true when the prior tracked file used the supported legacy projection format
+            legacy_backup_path:
+              type: string
+              description: exact-byte backup of the replaced legacy task projection
     errors:
       - { code: ULTRA_DIR_EXISTS,  description: '.ultra/ already exists and overwrite=false' }
       - { code: TEMPLATE_MISSING,  description: 'source_template path does not exist' }
@@ -397,6 +682,7 @@ tools:
       - { 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: TASK_LEDGER_LEGACY_CONFLICT, description: 'the legacy task projection differs from SQLite authority and cannot be upgraded automatically' }
       - { code: GIT_INIT_FAILED, description: 'the local Git repository or Ultra ignore rule could not be initialized' }
       - { code: GITIGNORE_UNSAFE, description: 'root .gitignore is a symlink or non-file and cannot be updated safely' }
       - { code: GITIGNORE_INEFFECTIVE, description: 'the effective Git rules still expose the `.ultra` authority' }

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

@@ -2,7 +2,7 @@
   "$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/tasks/contexts/task-*.md. The header is regenerated by the projector from state.db. Body sections are author-owned; status MUST NOT appear in body. Authority boundary: docs/DECISIONS.md.",
+  "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,

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

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

package/spec/schemas/state-db.sql

@@ -105,7 +105,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   docs_impact_json  TEXT NOT NULL DEFAULT '{"status":"unknown","files":[],"rationale":null}',
   ownership_json    TEXT NOT NULL DEFAULT '{}',
   context_file      TEXT,                -- projection target path
-  completion_commit TEXT,                -- backfilled hash (Phase 2.8)
+  completion_commit TEXT,                -- checkout-local integrated commit evidence
   change_id         TEXT REFERENCES changes(id) ON DELETE SET NULL,
   parent_id         TEXT REFERENCES tasks(id) ON DELETE SET NULL,  -- Phase 8A.1: task.expand subtask→parent
   created_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),