ultra-builder-pro-cli 0.22.0 → 0.23.0

package/mcp-server/lib/workflow-state.cjs

@@ -657,8 +657,9 @@ function inspectRunHealth(run, steps, rootDir) {
     const firstOpen = steps.find(
       (item) => item.required && !['completed', 'skipped'].includes(item.status),
     );
-    if (!firstOpen) blockers.push('WORKFLOW_ACTIVE_WITHOUT_OPEN_STEP');
-    else if (run.current_step !== firstOpen.step_id) {
+    if (!firstOpen) {
+      if (runMetadata.draft_dirty !== true) blockers.push('WORKFLOW_ACTIVE_WITHOUT_OPEN_STEP');
+    } else if (run.current_step !== firstOpen.step_id) {
       blockers.push(`WORKFLOW_CURRENT_STEP_INVALID:${run.current_step || 'missing'}`);
     }
   }
@@ -1196,6 +1197,166 @@ function startWorkflow(db, input = {}, { rootDir = process.cwd() } = {}) {
   return readWorkflow(db, id, { rootDir });
 }
 
+function abandonWorkflow(db, input = {}, { rootDir = process.cwd() } = {}) {
+  const id = nonEmpty(input.id, 'id');
+  const reason = nonEmpty(input.reason, 'reason');
+  return ops.tx(db, () => {
+    const run = readWorkflow(db, id, { rootDir });
+    if (!run) throw new WorkflowStateError('WORKFLOW_NOT_FOUND', `workflow ${id} not found`);
+    if (run.status === 'cancelled') return run;
+    if (run.status === 'completed') {
+      throw new WorkflowStateError(
+        'WORKFLOW_NOT_MUTABLE',
+        `accepted workflow ${id} is immutable; create a new draft revision instead`,
+      );
+    }
+    const metadata = {
+      ...run.metadata,
+      abandoned: {
+        reason,
+        abandoned_at: nowIso(),
+      },
+    };
+    delete metadata.authority_invalidation;
+    const ts = nowIso();
+    db.prepare(
+      `UPDATE workflow_runs
+       SET status = 'cancelled', current_step = NULL, blockers_json = '[]',
+           metadata_json = ?, completed_at = ?, updated_at = ?
+       WHERE id = ?`,
+    ).run(JSON.stringify(metadata), ts, ts, id);
+    ops.appendEventInTx(db, {
+      type: 'workflow_abandoned',
+      task_id: run.task_id,
+      change_id: run.change_id,
+      payload: { workflow_id: id, kind: run.kind, reason },
+    });
+    return readWorkflow(db, id, { rootDir });
+  });
+}
+
+function prepareWorkflowCheckpoint(db, input = {}, { rootDir = process.cwd() } = {}) {
+  const id = nonEmpty(input.id, 'id');
+  const suppliedSteps = new Map(
+    (Array.isArray(input.steps) ? input.steps : []).map((item) => [
+      nonEmpty(item.step_id, 'steps.step_id'),
+      item,
+    ]),
+  );
+  const defaultEvidence = Array.isArray(input.evidence) && input.evidence.length > 0
+    ? normalizeEvidence(input.evidence)
+    : [{
+      kind: 'checkpoint',
+      ref: `workflow:${id}`,
+      summary: 'The model recorded this semantic stage in one checkpoint.',
+    }];
+  return ops.tx(db, () => {
+    const run = readWorkflow(db, id, { rootDir });
+    if (!run) throw new WorkflowStateError('WORKFLOW_NOT_FOUND', `workflow ${id} not found`);
+    if (run.status === 'completed') return { workflow: run, blockers: [], ready: true };
+    if (run.status === 'cancelled') {
+      throw new WorkflowStateError('WORKFLOW_NOT_MUTABLE', `workflow ${id} is cancelled`);
+    }
+    const blockers = [];
+    const ts = nowIso();
+    for (const workflowStep of run.steps) {
+      if (!workflowStep.required) continue;
+      const supplied = suppliedSteps.get(workflowStep.step_id) || {};
+      const definition = WORKFLOW_DEFINITIONS[run.kind]
+        .find((item) => item.id === workflowStep.step_id);
+      const outputs = supplied.outputs === undefined
+        ? workflowStep.outputs
+        : normalizeOutputs(supplied.outputs, rootDir);
+      const evidence = supplied.evidence === undefined
+        ? (workflowStep.evidence.length > 0 ? workflowStep.evidence : defaultEvidence)
+        : normalizeEvidence(supplied.evidence);
+      const semanticRecords = supplied.semantic_records === undefined
+        ? workflowStep.semantic_records
+        : (run.kind === 'research'
+          ? normalizeSemanticRecords(supplied.semantic_records, workflowStep.step_id, rootDir)
+          : normalizeObjects(supplied.semantic_records, 'semantic_records'));
+      if (definition.output_required && outputs.length === 0) {
+        blockers.push(`WORKFLOW_OUTPUT_REQUIRED:${workflowStep.step_id}`);
+        continue;
+      }
+      if (definition.evidence_required && evidence.length === 0) {
+        blockers.push(`WORKFLOW_EVIDENCE_REQUIRED:${workflowStep.step_id}`);
+        continue;
+      }
+      if (run.kind === 'research' && semanticRecords.length === 0) {
+        blockers.push(`WORKFLOW_SEMANTIC_RECORDS_REQUIRED:${workflowStep.step_id}`);
+        continue;
+      }
+      db.prepare(
+        `UPDATE workflow_steps
+         SET status = 'completed', evidence_json = ?, outputs_json = ?,
+             decisions_json = ?, semantic_records_json = ?, blockers_json = '[]',
+             started_at = COALESCE(started_at, ?), completed_at = ?, updated_at = ?
+         WHERE run_id = ? AND step_id = ?`,
+      ).run(
+        JSON.stringify(evidence),
+        JSON.stringify(outputs),
+        JSON.stringify(supplied.decisions === undefined
+          ? workflowStep.decisions
+          : normalizeObjects(supplied.decisions, 'decisions')),
+        JSON.stringify(semanticRecords),
+        ts,
+        ts,
+        ts,
+        id,
+        workflowStep.step_id,
+      );
+    }
+    const metadata = { ...run.metadata };
+    delete metadata.authority_invalidation;
+    metadata.draft_dirty = blockers.length > 0;
+    db.prepare(
+      `UPDATE workflow_runs
+       SET status = ?, current_step = NULL, blockers_json = ?, metadata_json = ?, updated_at = ?
+       WHERE id = ?`,
+    ).run(
+      blockers.length > 0 ? 'active' : 'ready',
+      JSON.stringify(blockers),
+      JSON.stringify(metadata),
+      ts,
+      id,
+    );
+    ops.appendEventInTx(db, {
+      type: blockers.length > 0 ? 'workflow_checkpoint_rejected' : 'workflow_checkpoint_prepared',
+      task_id: run.task_id,
+      change_id: run.change_id,
+      payload: { workflow_id: id, kind: run.kind, blockers },
+    });
+    return {
+      workflow: readWorkflow(db, id, { rootDir }),
+      blockers,
+      ready: blockers.length === 0,
+    };
+  });
+}
+
+function reopenWorkflowDraft(db, input = {}, { rootDir = process.cwd() } = {}) {
+  const id = nonEmpty(input.id, 'id');
+  const blocker = typeof input.blocker === 'string' && input.blocker.trim()
+    ? input.blocker.trim()
+    : 'CHECKPOINT_REJECTED';
+  return ops.tx(db, () => {
+    const run = readWorkflow(db, id, { rootDir });
+    if (!run) throw new WorkflowStateError('WORKFLOW_NOT_FOUND', `workflow ${id} not found`);
+    if (run.status === 'completed' || run.status === 'cancelled') return run;
+    const metadata = { ...run.metadata, draft_dirty: true };
+    delete metadata.authority_invalidation;
+    const blockers = [...new Set([...(run.blockers || []), blocker])];
+    db.prepare(
+      `UPDATE workflow_runs
+       SET status = 'active', blockers_json = ?, metadata_json = ?,
+           updated_at = ?
+       WHERE id = ?`,
+    ).run(JSON.stringify(blockers), JSON.stringify(metadata), nowIso(), id);
+    return readWorkflow(db, id, { rootDir });
+  });
+}
+
 function reviseWorkflow(db, input = {}, { rootDir = process.cwd() } = {}) {
   const id = nonEmpty(input.id, 'id');
   const replacementId = nonEmpty(input.replacement_id, 'replacement_id');
@@ -2948,6 +3109,9 @@ module.exports = {
   WorkflowStateError,
   insertWorkflowInTx,
   startWorkflow,
+  abandonWorkflow,
+  prepareWorkflowCheckpoint,
+  reopenWorkflowDraft,
   readWorkflow,
   listWorkflows,
   recordWorkflowStep,

package/mcp-server/server.cjs

@@ -39,6 +39,7 @@ const workflows = require('./lib/workflow-state.cjs');
 const decisions = require('./lib/decision-dialogue.cjs');
 const doctor = require('./lib/doctor.cjs');
 const artifactRegistry = require('./lib/artifact-registry.cjs');
+const ultraFacade = require('./lib/ultra-facade.cjs');
 const {
   readProjectBreadcrumb,
   renderProjectBreadcrumb,
@@ -137,19 +138,29 @@ const ARTIFACT_TOOLS = Object.freeze([
   'artifact.get',
 ]);
 
-const REGISTERED_TOOLS = Object.freeze([
+const LEGACY_TOOLS = Object.freeze([
   ...TASK_TOOLS, ...SESSION_TOOLS, ...PLAN_TOOLS, ...BASELINE_TOOLS, ...CHANGE_TOOLS,
   ...DECISION_TOOLS,
   ...WORKFLOW_TOOLS,
   ...ARTIFACT_TOOLS,
   ...SYSTEM_TOOLS,
 ]);
+const PUBLIC_TOOLS = ultraFacade.PUBLIC_TOOLS;
+const REGISTERED_TOOLS = Object.freeze([...PUBLIC_TOOLS, ...LEGACY_TOOLS]);
 
 const STATELESS_TOOLS = new Set(['task.init_project']);
 
+function isStatelessPublicCall(name, input = {}) {
+  return name === 'ultra.record'
+    && Array.isArray(input.entries)
+    && input.entries.length === 1
+    && input.entries[0]?.operation === 'task.init_project';
+}
+
 // init_project owns its target project's schema, baseline seed, and first
 // projection internally. Do not enqueue a second projection on the caller DB.
 const MUTATING_TOOLS = new Set([
+  'ultra.record', 'ultra.checkpoint', 'ultra.sync', 'ultra.session', 'ultra.archive',
   'task.create', 'task.update', 'task.delete', 'task.append_event', 'task.switch_tag',
   'task.parse_prd', 'task.expand',
   'task.ledger_import',
@@ -167,6 +178,7 @@ const MUTATING_TOOLS = new Set([
 ]);
 
 const TEAM_LEDGER_SYNC_TOOLS = new Set([
+  'ultra.record', 'ultra.checkpoint', 'ultra.archive',
   'task.create', 'task.update', 'task.delete', 'task.parse_prd', 'task.expand',
   'plan.export',
   'baseline.start', 'baseline.record', 'baseline.converge',
@@ -651,10 +663,6 @@ async function dispatchTool(name, input, db, ctx = {}) {
         // caller must see a typed failure and later mutations must stop.
         throw error;
       }
-      taskLedger.publishTaskLedger(db, {
-        rootDir,
-        reason: 'plan_accepted',
-      });
       return {
         plan_path: publication.plan_path,
         plan_md_path: publication.plan_md_path,
@@ -969,6 +977,19 @@ function startServer({
   };
   const getDb = (toolName = null) => {
     if (!db) {
+      if (toolName === 'ultra.context') {
+        if (!fs.existsSync(authorityDbPath)) {
+          const error = new Error(
+            'Ultra authority is not initialized; invoke ultra-init before reading project context',
+          );
+          error.code = 'STATE_DB_MISSING';
+          throw error;
+        }
+        db = openStateDb(authorityDbPath);
+        ensureSchemaVersion(db);
+        assertStateAuthority(db, rootDir, { importTeamLedger: false });
+        return db;
+      }
       const projectPaths = runtimePaths.pathsFor(rootDir);
       if ([projectPaths.legacyStateDbPath, projectPaths.stateDbPath].includes(authorityDbPath)) {
         // The packaged launcher has no explicit DB override. Its default path
@@ -1005,7 +1026,7 @@ function startServer({
       }
       planRecovery = planStore.recoverPlanPublications(db, { rootDir });
     }
-    if (toolName !== 'system.doctor'
+      if (!['system.doctor', 'ultra.doctor'].includes(toolName)
       && (planRecovery?.pending > 0 || planRecovery?.issues?.length > 0)) {
       planRecovery = planStore.recoverPlanPublications(db, { rootDir });
       if (planRecovery.pending > 0 || planRecovery.issues.length > 0) {
@@ -1021,6 +1042,7 @@ function startServer({
   };
 
   const tools = loadRegisteredTools();
+  const publicTools = tools.filter((tool) => PUBLIC_TOOLS.includes(tool.name));
   const ajv = buildAjv();
   const inputValidators = new Map();
   const outputValidators = new Map();
@@ -1035,7 +1057,7 @@ function startServer({
   );
 
   server.setRequestHandler('tools/list', async () => ({
-    tools: tools.map((t) => ({
+    tools: publicTools.map((t) => ({
       name: t.name,
       description: t.description,
       inputSchema: t.input_schema,
@@ -1081,23 +1103,51 @@ function startServer({
     let result;
     let toolDb = null;
     try {
-      toolDb = STATELESS_TOOLS.has(name) ? null : getDb(name);
+      toolDb = (STATELESS_TOOLS.has(name) || isStatelessPublicCall(name, args))
+        ? null
+        : getDb(name);
       if (toolDb) assertStateAuthority(toolDb, rootDir);
       if (toolDb && TEAM_LEDGER_SYNC_TOOLS.has(name)) {
         taskLedger.syncTaskLedger(toolDb, { rootDir });
       }
-      result = await dispatchTool(
-        name,
-        args,
-        toolDb,
-        {
-          rootDir,
-          sessionId,
-          projector: project,
-          markPlanRecoveryRequired,
-        },
-      );
-      if (name === 'system.doctor' && args.repair === true) {
+      const callContext = {
+        rootDir,
+        sessionId,
+        projector: project,
+        markPlanRecoveryRequired,
+      };
+      const callLegacy = async (legacyName, legacyArgs = {}) => {
+        if (!LEGACY_TOOLS.includes(legacyName)) {
+          const error = new Error(`legacy operation ${legacyName} is not supported`);
+          error.code = 'ULTRA_RECORD_OPERATION_UNSUPPORTED';
+          throw error;
+        }
+        const validateLegacyInput = inputValidators.get(legacyName);
+        if (!validateLegacyInput(legacyArgs)) {
+          const error = new Error(ajv.errorsText(validateLegacyInput.errors));
+          error.code = 'VALIDATION_ERROR';
+          error.details = validateLegacyInput.errors;
+          throw error;
+        }
+        const legacyResult = await dispatchTool(
+          legacyName,
+          legacyArgs,
+          toolDb,
+          callContext,
+        );
+        const validateLegacyOutput = outputValidators.get(legacyName);
+        if (!validateLegacyOutput(legacyResult)) {
+          const error = new Error(ajv.errorsText(validateLegacyOutput.errors));
+          error.code = 'OUTPUT_SCHEMA_DRIFT';
+          error.details = validateLegacyOutput.errors;
+          throw error;
+        }
+        return legacyResult;
+      };
+      result = PUBLIC_TOOLS.includes(name)
+        ? await ultraFacade.dispatch(name, args, toolDb, { ...callContext, callLegacy })
+        : await dispatchTool(name, args, toolDb, callContext);
+      if (['system.doctor', 'ultra.doctor'].includes(name) && args.repair === true) {
         planRecovery = result.repair?.plan_publications || null;
       }
     } catch (err) {
@@ -1122,7 +1172,7 @@ function startServer({
         projection_job_id: job.id,
       };
       if (own && own.incident_id) runtimeMeta.incident_id = own.incident_id;
-    } else if (toolDb && name === 'system.doctor' && args.repair === true) {
+    } else if (toolDb && ['system.doctor', 'ultra.doctor'].includes(name) && args.repair === true) {
       runtimeMeta = {
         state_commit: 'committed',
         projection_status: result.checks.projections.status === 'pass' ? 'completed' : 'failed',
@@ -1260,6 +1310,8 @@ module.exports = {
   ARTIFACT_TOOLS,
   SYSTEM_TOOLS,
   REGISTERED_TOOLS,
+  LEGACY_TOOLS,
+  PUBLIC_TOOLS,
   STATELESS_TOOLS,
   MUTATING_TOOLS,
   appendHookLifecycleEvent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, and Kimi Code, with project-local MCP authority and lifecycle recovery.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",

package/skills/ultra-change/SKILL.md

@@ -3,105 +3,45 @@ name: ultra-change
 description: Capture or revise one bounded feature, fix, redesign, or incident contract against a ready Ultra baseline. Use when post-baseline work needs accepted intent before research, planning, or implementation.
 ---
 
-# Capture accepted change intent
+# Capture accepted Change intent
 
-Change is the durable unit that connects later research, plan, implementation,
-verification, review, and baseline reconciliation. Capturing a change does not start
-those workflows or compile execution context.
-
-Read `../ultra-think/references/decision-dialogue.md` before asking a material question.
+A Change is the durable unit connecting research, plan, implementation, verification,
+review, documentation, and delivery. Its draft stays editable until a semantic
+checkpoint accepts the downstream authority.
 
 ## Inspect and align
 
-1. Read `system.doctor`, `task.ledger_get`, `baseline.get`, active changes, breadcrumb
-   `accepted_intent`, decisions, and `change.breadcrumb`. Import a newer descendant
-   checkpoint before capturing intent. Stop on a typed baseline, Change, task,
-   ancestry, or active-session conflict.
-2. Resume an existing change that matches the request. Do not duplicate authority.
-3. Ordinary work requires a healthy ready baseline. An incident may use only an
-   explicit `baseline_bypass` reason and approver; urgency is not approval.
-4. Inspect the checkout and accepted baseline before asking the user. Resolve code and
-   runtime facts yourself.
-5. Convert the request into a Change Contract:
-   - observable outcome and executable acceptance;
-   - non-goals and public seams;
-   - recovery strategy and verification;
-   - unresolved material decisions;
-   - documentation impact;
-   - change kind and evidence-backed risk flags;
-   - research disposition.
-
-Recommend `quick`, `standard`, `major`, or `incident` from actual scope and risk,
-together with the research disposition. A quick change may have no material risk,
-research obligation, or more than one task. MCP may reject a profile that contradicts
-hard risk invariants; it does not choose a replacement.
-
-After `change.create` or `change.update`, read back the complete Change Contract. When
-that write applies a durable decision, complete the decision thread with the change
-reference in `applied_refs`.
-
-Ask only when a choice changes accepted product intent, scope, public behavior,
-compatibility, security, material cost, external effects, or recovery. Use the host's
-native question UI when available. Normalize clear choices already in the user's
-request. When profile or research posture remains unresolved, present the recommended
-route and credible alternatives through that same UI, then stop. The user selects,
-modifies, delegates, or defers the semantic route. The model owns reversible
-implementation detail inside the accepted contract.
-
-## Persist the contract
-
-When a durable alignment checkpoint is necessary, bind it to a compact artifact and
-pass its id as `alignment_thread_id`. Do not require a checkpoint for a complete,
-unambiguous request that already provides current authority.
-
-Call `change.create`. It records and completes exactly:
-
-1. `bind-baseline`
-2. `classify-change`
-3. `record-intent`
-
-The returned change workflow must be `completed`; research, plan, context, dev, test,
-review, and deliver remain independent capabilities. Keep every Change-owned semantic
-artifact, finding, plan, context, test result, review result, documentation update,
-and progress projection below `.ultra/changes/active/<id>/`. Incidents maintain the
-structured diagnosis artifact there as well.
-
-`change.create` and `change.update` publish the portable Change Contract to
-`.ultra/tasks/tasks.json`, even before the Change owns tasks. The tracked Change
-artifacts carry semantic bodies; the checkpoint carries normalized baseline, Change,
-and task records with digest ancestry. Never edit either generated checkpoint or
-checkout-local projection directly.
-
-Before planning a standard or major change, write the accepted specification updates
-to the Change overlay and call `change.delta` with exact baseline id, repository
-revision, specification digests, decisions, non-goals, acceptance, documentation
-impact, unknowns, and mutation before/after digests. If accepted behavior truly does
-not change baseline semantics, record an empty typed delta with a specific
-`no_semantic_change_reason`; do not manufacture a mutation. Read back the registered
-delta and deterministic `progress.md`. This records proposed authority only and must
-not edit baseline specifications.
-
-Use `change.update` when accepted intent or evidence changes. Update the Change
-Contract, classification, research disposition, and docs impact together when their
-meaning is coupled. Downstream task, context, test, or review evidence affected by that
-change must become stale and be regenerated; never keep old evidence green by prompt
-assertion.
-
-If research is required, recommend `ultra-research` with the recorded disposition. If
-the contract is sufficiently evidenced, finish the typed delta and recommend
-`ultra-plan`. Direct Build skips Research only; it never skips Plan, DB-backed task
-contracts, or fresh task context. Return and wait for an explicit user invocation; do
-not start another workflow. `change.context` is compiled only for an actual plan,
-implementation, test, or review consumer.
-
-Stable implementation discoveries use the approval-gated specification-learning
-transitions. External memory and graph providers retain their own content; Ultra stores
-metadata references only.
-
-Return the normalized contract, change id and kind, research disposition, blockers,
-and `allowed_transitions`. Recommend a semantic next action from those transitions.
-If current intent does not already select it, present the recommendation and credible
-alternatives through the interaction protocol, then wait. MCP does not encode a
-semantic next action.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+1. Call `ultra.context { stage: project, detail: full }`.
+2. Inspect or import the team checkpoint with `ultra.sync`. Stop only on a real
+   baseline, Change, task, ancestry, or active-session conflict.
+3. Reuse an existing matching Change. Do not duplicate authority.
+4. Convert the request into observable outcome, executable acceptance, non-goals,
+   public seams, recovery, verification, documentation impact, risk, and research
+   disposition.
+5. Recommend `quick`, `standard`, `major`, or `incident` from evidence. Ask only when
+   a choice changes accepted product intent, compatibility, security, material cost,
+   external effects, or recovery.
+
+Read `../ultra-think/references/decision-dialogue.md` before asking. MCP may report
+contradictory risk fields, but the model and owner choose the semantic correction.
+
+## Record the contract
+
+Use one `ultra.record` batch for `change.create` or `change.update`, relevant
+`decision.*`, and `change.delta` when the delta is already known. Every entry carries
+a stable idempotency key. Read the result through `ultra.context`.
+
+Keep every Change-owned semantic artifact below
+`.ultra/changes/active/<change-id>/`. Standard and major Changes require a typed delta
+before planning. A true no-semantic-change case records an explicit reason instead of
+manufacturing a mutation.
+
+Changing accepted intent reopens the draft and makes only genuinely dependent evidence
+stale. `ready` is not an absorbing state. A semantic rejection returns diagnostics;
+repair and retry the same draft. Use `workflow.abandon` only to preserve and cancel an
+attempt intentionally.
+
+Publish the durable Change contract with `ultra.sync { action: publish }` when it is a
+useful team handoff. Recommend bounded `ultra-research` for a real evidence gap or
+`ultra-plan` when the contract is sufficiently evidenced. Do not invoke the next
+capability automatically.

package/skills/ultra-deliver/SKILL.md

@@ -1,71 +1,48 @@
 ---
 name: ultra-deliver
-description: Converge a verified Ultra change, reconcile baseline specifications, and archive it with recoverable local evidence. Use when implementation, testing, and review are current.
+description: Converge a verified Ultra Change, reconcile baseline specifications, and archive it with recoverable local evidence. Use when implementation, testing, and review are current.
 ---
 
 # Converge and archive local authority
 
-Delivery closes Ultra's local change authority. It does not grant or perform commit,
-push, tag, registry publication, deployment, or another external effect.
-
-## Bind current evidence
-
-1. Read doctor, `task.ledger_get`, baseline, change, breadcrumb `accepted_intent`,
-   decisions, tasks, test, review, learning, and current checkout. Import a newer
-   descendant checkpoint before convergence; stop on any typed merge conflict.
-2. Resume or start a deliver workflow bound to the change and baseline.
-3. Require complete task evidence, a current test report, both review axes, current
-   context, and resolved material decisions. Record `bind-evidence`.
-
-Evidence from another revision, task set, or change is invalid.
-
-## Reconcile specifications
-
-Resolve every specification-learning candidate. Apply approved learning to its target
-inside the Change overlay; preserve rejection reasons. Read the current registered
-`change.delta` and verify every baseline anchor, payload digest, acceptance reference,
-and unknown.
-
-Write documentation updates below
-`.ultra/changes/active/<change-id>/documentation/`. Call
-`change.documentation_reconcile` for every Change: bind the current delta id and
-digest, exact before/after document digests, delta and acceptance references,
-verification, and each verified consumer. When no documentation changes, record an
-empty reconciliation with a specific `no_change_reason`. An unexplained orphan
-document is blocking. Record `reconcile-specifications`.
-
-Compile final convergence context and run the risk-selected candidate checks, install
-or doctor smoke when this change modifies distributed assets, public-seam verification,
-and recovery sanity. Record the immutable context under `verify-candidate`.
-
-Call `change.converge`; MCP derives readiness from durable dev, test, review,
-typed delta, documentation reconciliation, diagnosis, and current checkout evidence.
-Successful convergence publishes the current portable team checkpoint.
-Record
-`converge-authority` only when ready.
-
-Call `change.archive` with the summary. MCP preflights all target before states and
-overlay digests, applies the complete packet atomically, refreshes baseline authority,
-rebinds every registered artifact into the self-contained archive, and rolls back or
-resumes from its transaction journal after interruption. A partial success is not
-delivery. Archive publication refreshes the checkpoint with the archived Change and
-new baseline summary. Verify the refreshed baseline and archived packet, then record
-`archive-change`.
-
-Write `<archived-change-root>/delivery/<workflow-id>/report.json` with
-`ultra-delivery-report-v1`: archived change, baseline, HEAD, worktree and context
-digests, local checks, rollback notes, and timestamp. The report must not contain a
-release decision. Record it under `verify-delivery` and complete the workflow.
-
-## External effects
-
-If the user separately requests commit, push, tag, publish, or deploy, handle that as a
-host-owned effect after Ultra delivery. Confirm only missing material authority, run
-the repository's release checks, and report remote evidence separately. Never infer an
-external effect from `ultra-deliver`, and never encode it as completed Ultra delivery
-state.
-
-Return archive and baseline state, evidence digests, recovery notes, residual risks,
-and allowed transitions.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+Delivery closes local Ultra authority. It never grants commit, push, tag, registry
+publication, deployment, or another external effect.
+
+## Prepare the packet
+
+1. Call `ultra.context { stage: deliver, scope: { change_id }, detail: full }`.
+2. Import a newer team checkpoint with `ultra.sync`; stop on a real conflict.
+3. Require current task outcomes, test report, both review axes, accepted decisions,
+   typed delta, documentation reconciliation, and current checkout evidence.
+4. Resolve every specification-learning candidate. Keep updates inside the Change
+   overlay until archive.
+5. Write and register documentation reconciliation and an
+   `ultra-delivery-report-v1` report. The report binds Change, baseline, HEAD,
+   worktree/context digests, local checks, rollback guidance, and timestamp; it contains
+   no release decision.
+
+Use one `ultra.record` batch for the reconciliation, report artifact, learning
+resolutions, and other durable facts.
+
+## Archive once
+
+Call `ultra.archive` once with the Change id, stable idempotency key, archive summary,
+reconciliation fields, delivery evidence steps, and report output. The operation
+internally:
+
+- compiles or reuses convergence context;
+- checks the deliver draft;
+- derives convergence from current dev, test, review, delta, docs, and checkout;
+- applies the overlay and archive through the recoverable filesystem/DB transaction;
+- rebinds registered artifacts into a self-contained archive;
+- completes the durable delivery checkpoint;
+- publishes the updated team checkpoint.
+
+A semantic rejection returns mutable blockers. Repair the same packet and retry. A
+hard corruption, path, concurrency, or recovery error remains fail-closed and routes to
+`ultra-doctor`.
+
+Verify the archived packet, baseline, checkpoint, and rollback state. Handle any
+separately authorized Git or release effect only after local delivery and report it as
+external evidence, not Ultra delivery authority. Do not invoke another capability
+automatically.