ultra-builder-pro-cli 0.21.1 → 0.22.0

package/spec/mcp-tools.yaml

@@ -233,6 +233,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 +489,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 +523,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/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')),

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

@@ -0,0 +1,217 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultra-builder-pro.dev/spec/task-ledger.v1.schema.json",
+  "title": "Ultra team task ledger v1",
+  "description": "Git-facing checkpoint ledger for durable task contracts and statuses. Live sessions, leases, worktrees, and in-progress ownership remain in .ultra/.runtime/state.db.",
+  "type": "object",
+  "required": [
+    "kind",
+    "schema_version",
+    "generation",
+    "parent_digest",
+    "ancestors",
+    "state_digest",
+    "published_at",
+    "reason",
+    "baseline",
+    "changes",
+    "tasks"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "const": "ultra-team-task-ledger" },
+    "schema_version": { "const": "1.0" },
+    "generation": { "type": "integer", "minimum": 0 },
+    "parent_digest": {
+      "type": ["string", "null"],
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "ancestors": {
+      "type": "array",
+      "maxItems": 64,
+      "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+    },
+    "state_digest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "published_at": {
+      "type": ["string", "null"],
+      "format": "date-time"
+    },
+    "reason": { "type": "string", "minLength": 1 },
+    "baseline": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "#/$defs/baseline" }
+      ]
+    },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "title",
+          "kind",
+          "status",
+          "intent",
+          "artifact_root",
+          "revision",
+          "parent_digest",
+          "digest"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string", "minLength": 1 },
+          "kind": { "type": "string", "enum": ["quick", "standard", "major", "incident"] },
+          "status": { "type": "string", "enum": ["active", "blocked", "ready", "archived", "cancelled"] },
+          "intent": { "type": "string", "minLength": 1 },
+          "docs_impact": { "type": "object" },
+          "provider_refs": { "type": "object" },
+          "baseline_bypass": { "type": "object" },
+          "contract": { "type": "object" },
+          "classification": { "type": "object" },
+          "research_disposition": { "type": "object" },
+          "base_commit": { "type": "string" },
+          "artifact_root": { "type": "string", "minLength": 1 },
+          "closed_at": { "type": "string" },
+          "revision": { "type": "integer", "minimum": 1 },
+          "parent_digest": {
+            "type": ["string", "null"],
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+        }
+      }
+    },
+    "tasks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/task" }
+    }
+  },
+  "$defs": {
+    "baseline": {
+      "type": "object",
+      "required": [
+        "id",
+        "project_name",
+        "mode",
+        "status",
+        "scope",
+        "worktree_accepted",
+        "known_red_accepted",
+        "spec_refs",
+        "evidence",
+        "verification",
+        "unknowns",
+        "gaps",
+        "classification",
+        "provider_refs",
+        "revision",
+        "parent_digest",
+        "digest"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "project_name": { "type": "string", "minLength": 1 },
+        "project_type": { "type": "string" },
+        "stack": { "type": "string" },
+        "mode": {
+          "type": "string",
+          "enum": ["greenfield", "brownfield", "migrated"]
+        },
+        "status": {
+          "type": "string",
+          "enum": ["draft", "adopting", "blocked", "ready"]
+        },
+        "scope": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "repository_revision": { "type": "string" },
+        "repository_branch": { "type": "string" },
+        "worktree_state": { "type": "string" },
+        "worktree_digest": { "type": "string" },
+        "worktree_accepted": { "type": "boolean" },
+        "known_red_accepted": { "type": "boolean" },
+        "spec_refs": { "type": "array" },
+        "evidence": { "type": "array" },
+        "verification": { "type": "array" },
+        "unknowns": { "type": "array" },
+        "gaps": { "type": "array" },
+        "classification": { "type": "object" },
+        "provider_refs": { "type": "object" },
+        "research_run_id": { "type": "string" },
+        "approved_by": { "type": "string" },
+        "approval_note": { "type": "string" },
+        "converged_at": { "type": "string" },
+        "revision": { "type": "integer", "minimum": 1 },
+        "parent_digest": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "task": {
+      "type": "object",
+      "required": [
+        "id",
+        "title",
+        "type",
+        "priority",
+        "status",
+        "deps",
+        "files_modified",
+        "stale",
+        "acceptance",
+        "context_refs",
+        "docs_impact",
+        "ownership",
+        "revision",
+        "parent_digest",
+        "digest"
+      ],
+      "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"] },
+        "complexity": { "type": "integer", "minimum": 1, "maximum": 10 },
+        "estimated_days": { "type": "number", "exclusiveMinimum": 0 },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "completed", "blocked", "expanded"]
+        },
+        "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"]
+        },
+        "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" },
+        "change_id": { "type": "string" },
+        "parent_id": { "type": "string" },
+        "revision": { "type": "integer", "minimum": 1 },
+        "parent_digest": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    }
+  }
+}

package/ultra-tools/commands/migrate.cjs

@@ -246,8 +246,11 @@ function sanitizeLegacyContextTemplate(sourceDir) {
       /Read by mid_workflow_recall\.py and session_context\.py and injected into agent context\./g,
       'Used as task-local acceptance criteria by the active Ultra workflow.',
     );
-  if (next === current) return false;
-  fs.writeFileSync(file, next);
+  const target = path.join(sourceDir, '.ultra', 'templates', 'task-context.md');
+  if (fs.existsSync(target)) return false;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, next);
+  fs.rmSync(file);
   return true;
 }
 

package/.ultra-template/tasks/contexts/TEMPLATE.md

@@ -1,19 +0,0 @@
-<!-- The projector owns YAML frontmatter and the generated execution contract. -->
-
-# Task Notes
-
-Use this body only for task-specific implementation discoveries that are not already
-authoritative task fields. Stable specification learning must follow the change
-approval workflow.
-
-## Implementation Notes
-
-- [Evidence-backed note with a source reference]
-
-## Open Questions
-
-- [Question, consequence, owner, and next evidence]
-
-## Recovery Notes
-
-- [Current safe resume point and any external prerequisite]