ultra-builder-pro-cli 0.20.0 → 0.22.0

package/orchestrator/worktree-manager.cjs

@@ -3,7 +3,7 @@
 // Phase 8B.3 — N-concurrent git worktree registry.
 //
 // Wraps session-runner's single-session gitWorktreeAdd/Remove with:
-//   • allocate({repoRoot, sid, baseRef})  — create .ultra/worktrees/<sid>
+//   • allocate({repoRoot, sid, baseRef})  — create .ultra/.runtime/worktrees/<sid>
 //   • release({repoRoot, worktree_path})  — remove one
 //   • listActive(repoRoot)                — scan git + filter our domain
 //   • releaseAll(repoRoot)                — batch cleanup (crash recovery)
@@ -16,27 +16,91 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
+const Database = require('better-sqlite3');
 
-const { _internal } = require('./session-runner.cjs');
+const runtimePaths = require('../mcp-server/lib/runtime-paths.cjs');
+const gitBootstrap = require('../mcp-server/lib/git-bootstrap.cjs');
+const { SessionRunnerError, _internal } = require('./session-runner.cjs');
 
-const WORKTREE_DOMAIN = path.join('.ultra', 'worktrees');
+const WORKTREE_DOMAIN = path.join(runtimePaths.RUNTIME_RELATIVE_DIR, 'worktrees');
 
 function worktreePath(repoRoot, sid) {
-  return path.join(repoRoot, WORKTREE_DOMAIN, sid);
+  _internal.assertSessionId(sid);
+  return _internal.assertManagedWorktreePath(
+    repoRoot,
+    path.join(repoRoot, WORKTREE_DOMAIN, sid),
+    { sid },
+  );
 }
 
 function allocate({ repoRoot, sid, baseRef = 'HEAD' }) {
   if (!repoRoot) throw new Error('allocate: repoRoot required');
   if (!sid) throw new Error('allocate: sid required');
+  const authority = runtimePaths.ensureRuntimeState(repoRoot, {
+    admitStorageBoundary: () => gitBootstrap.ensureExistingProjectStorageBoundary(repoRoot),
+  });
   const wt = worktreePath(repoRoot, sid);
   _internal.gitWorktreeAdd(repoRoot, wt, baseRef); // throws WORKTREE_FAILED
-  return { worktree_path: wt };
+  try {
+    _internal.linkAuthorityIntoWorktree(repoRoot, wt, { authority });
+    return { worktree_path: wt, authority_db_path: authority.stateDbPath };
+  } catch (error) {
+    try { fs.rmSync(path.join(wt, '.ultra', '.runtime'), { force: true }); }
+    catch { /* best effort */ }
+    try { _internal.gitWorktreeRemove(repoRoot, wt); }
+    catch { /* original authority error is more actionable */ }
+    throw error;
+  }
 }
 
-function release({ repoRoot, worktree_path }) {
+function sessionRemovalBlocker(repoRoot, sid, worktreePath) {
+  const dbPath = runtimePaths.pathsFor(repoRoot).stateDbPath;
+  if (!fs.existsSync(dbPath)) return null;
+  const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+  try {
+    const rows = db.prepare(
+      'SELECT sid, status, worktree_path FROM sessions WHERE sid = ?',
+    ).all(sid);
+    for (const row of rows) {
+      let recorded;
+      let requested;
+      try { recorded = fs.realpathSync(row.worktree_path); }
+      catch { recorded = path.resolve(row.worktree_path); }
+      try { requested = fs.realpathSync(worktreePath); }
+      catch { requested = path.resolve(worktreePath); }
+      if (recorded !== requested) {
+        return `session ${sid} is bound to a different worktree`;
+      }
+      if (!['completed', 'crashed'].includes(row.status)) {
+        return `session ${sid} is nonterminal (${row.status})`;
+      }
+    }
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
+function release({ repoRoot, worktree_path, sid = null }) {
   if (!repoRoot) throw new Error('release: repoRoot required');
   if (!worktree_path) throw new Error('release: worktree_path required');
-  _internal.gitWorktreeRemove(repoRoot, worktree_path);
+  const expectedSid = sid === null ? path.basename(worktree_path) : sid;
+  _internal.assertSessionId(expectedSid);
+  const managedPath = _internal.assertManagedWorktreePath(
+    repoRoot, worktree_path, { sid: expectedSid },
+  );
+  const sessionBlocker = sessionRemovalBlocker(
+    repoRoot, expectedSid, managedPath,
+  );
+  const integrationBlocker = _internal.worktreeRemovalBlocker(repoRoot, managedPath);
+  const blocker = sessionBlocker || integrationBlocker;
+  if (blocker) {
+    throw new SessionRunnerError(
+      'WORKTREE_NOT_INTEGRATED',
+      `refusing to remove ${managedPath}: ${blocker}`,
+    );
+  }
+  _internal.gitWorktreeRemove(repoRoot, managedPath);
 }
 
 function parsePorcelain(text) {
@@ -62,63 +126,150 @@ function parsePorcelain(text) {
   return entries;
 }
 
-function listActive(repoRoot) {
+function gitDiscoveryError(message, cause) {
+  return new SessionRunnerError(
+    'WORKTREE_DISCOVERY_FAILED',
+    `cannot inspect Git worktrees safely: ${message}`,
+    { cause },
+  );
+}
+
+function hasGitMetadata(repoRoot) {
+  let current = path.resolve(repoRoot);
+  while (true) {
+    if (fs.lstatSync(path.join(current, '.git'), { throwIfNoEntry: false })) return true;
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+
+function runGitText(repoRoot, args, execGit) {
+  const value = execGit('git', args, {
+    cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+  });
+  if (typeof value !== 'string' && !Buffer.isBuffer(value)) {
+    throw gitDiscoveryError(`Git returned no output for ${args.join(' ')}`);
+  }
+  return String(value);
+}
+
+function listActive(repoRoot, { execGit = execFileSync } = {}) {
+  const metadataPresent = hasGitMetadata(repoRoot);
+  let inside;
+  try {
+    inside = runGitText(repoRoot, ['rev-parse', '--is-inside-work-tree'], execGit).trim();
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error);
+    if (!metadataPresent && /not a git repository/i.test(detail)) return [];
+    if (error instanceof SessionRunnerError) throw error;
+    throw gitDiscoveryError(detail.trim(), error);
+  }
+  if (inside !== 'true') {
+    if (!metadataPresent && inside === 'false') return [];
+    throw gitDiscoveryError(`unexpected repository probe result: ${inside || '(empty)'}`);
+  }
+
   let out;
   try {
-    out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
-      cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
-    });
+    out = runGitText(repoRoot, ['worktree', 'list', '--porcelain'], execGit);
   } catch (err) {
-    // Non-git or git failure — surface nothing but log via stderr so callers
-    // can trace. Return empty list so releaseAll is idempotent.
-    process.stderr.write(`worktree-manager: listActive git call failed: ${err.message}\n`);
-    return [];
+    if (err instanceof SessionRunnerError) throw err;
+    throw gitDiscoveryError(String(err?.stderr || err?.message || err).trim(), err);
   }
-  const rawDomainRoot = path.resolve(repoRoot, WORKTREE_DOMAIN);
+  const rawDomainRoot = _internal.assertManagedWorktreeRoot(repoRoot);
   // On macOS tmpdir is a symlink (/var → /private/var); git returns realpath.
   // Canonicalize both sides so prefix matching is robust.
   const domainRoot = (fs.existsSync(rawDomainRoot)
     ? fs.realpathSync(rawDomainRoot)
     : rawDomainRoot) + path.sep;
-  return parsePorcelain(out)
-    .filter((e) => {
-      if (!e.worktree) return false;
-      const canon = fs.existsSync(e.worktree) ? fs.realpathSync(e.worktree) : path.resolve(e.worktree);
-      return (canon + path.sep).startsWith(domainRoot);
-    })
-    .map((e) => ({
-      sid: path.basename(e.worktree),
-      worktree_path: e.worktree,
-      head: e.head || null,
-      branch: e.branch || null,
-      detached: !!e.detached,
-    }));
+  const active = [];
+  for (const entry of parsePorcelain(out)) {
+    if (!entry.worktree) continue;
+    const physical = fs.existsSync(entry.worktree)
+      ? fs.realpathSync(entry.worktree)
+      : path.resolve(entry.worktree);
+    if (!(physical + path.sep).startsWith(domainRoot)) continue;
+    const sid = path.basename(entry.worktree);
+    const canonical = _internal.assertManagedWorktreePath(
+      repoRoot, entry.worktree, { sid },
+    );
+    active.push({
+      sid,
+      worktree_path: canonical,
+      head: entry.head || null,
+      branch: entry.branch || null,
+      detached: !!entry.detached,
+    });
+  }
+  return active;
 }
 
-function releaseAll(repoRoot) {
-  const active = listActive(repoRoot);
+function releaseAll(repoRoot, options = {}) {
+  const active = listActive(repoRoot, options);
+  const releaseWorktree = options.releaseWorktree || release;
   let cleaned = 0;
+  const protectedSids = new Set();
+  const preserved = [];
+  const quarantined = [];
   for (const entry of active) {
     try {
-      release({ repoRoot, worktree_path: entry.worktree_path });
+      releaseWorktree({
+        repoRoot,
+        worktree_path: entry.worktree_path,
+        sid: entry.sid,
+      });
       cleaned += 1;
     } catch (err) {
+      protectedSids.add(entry.sid);
+      preserved.push({
+        sid: entry.sid,
+        worktree_path: entry.worktree_path,
+        reason: err.message,
+      });
       // Best-effort: one bad worktree shouldn't stop the sweep.
       process.stderr.write(`worktree-manager: release(${entry.sid}) failed: ${err.message}\n`);
     }
   }
-  // Sweep filesystem orphans that git no longer tracks.
+  // Filesystem entries Git no longer owns are recovery evidence, not trash.
+  // Move real managed children atomically into quarantine and report the path.
   const domainRoot = path.join(repoRoot, WORKTREE_DOMAIN);
   if (fs.existsSync(domainRoot)) {
     for (const name of fs.readdirSync(domainRoot)) {
       const full = path.join(domainRoot, name);
-      try { fs.rmSync(full, { recursive: true, force: true }); }
+      try {
+        if (protectedSids.has(name)) continue;
+        _internal.assertSessionId(name);
+        const managedPath = _internal.assertManagedWorktreePath(
+          repoRoot, full, { sid: name },
+        );
+        const recoveryRoot = path.join(
+          runtimePaths.pathsFor(repoRoot).runtimeDir,
+          'recovery',
+          'worktrees',
+        );
+        fs.mkdirSync(recoveryRoot, { recursive: true });
+        const token = new Date().toISOString().replace(/[:.]/g, '-');
+        let recoveryPath = path.join(recoveryRoot, `${token}-${name}`);
+        let attempt = 0;
+        while (fs.lstatSync(recoveryPath, { throwIfNoEntry: false })) {
+          attempt += 1;
+          recoveryPath = path.join(recoveryRoot, `${token}-${name}-${attempt}`);
+        }
+        fs.renameSync(managedPath, recoveryPath);
+        quarantined.push({
+          sid: name,
+          source_path: managedPath,
+          recovery_path: recoveryPath,
+        });
+      }
       catch (err) {
+        preserved.push({ sid: name, worktree_path: full, reason: err.message });
         process.stderr.write(`worktree-manager: orphan sweep failed for ${full}: ${err.message}\n`);
       }
     }
   }
-  return { cleaned };
+  return { cleaned, preserved, quarantined };
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.20.0",
+  "version": "0.22.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",
@@ -16,7 +16,6 @@
     "orchestrator",
     "commands",
     "agents",
-    "skills/learn",
     "skills/ultra-init",
     "skills/ultra-research",
     "skills/ultra-plan",
@@ -38,7 +37,6 @@
     "hooks/*.py",
     "hooks/adapters/*.py",
     "hooks/README.md",
-    "output-styles",
     "spec/mcp-tools.yaml",
     "spec/cli-protocol.md",
     "spec/schemas",
@@ -48,6 +46,7 @@
     ".ultra-template",
     "docs/ROADMAP.md",
     "docs/ARCHITECTURE.md",
+    "docs/ARTIFACT-AUTHORITY.md",
     "docs/WORKFLOW-LIFECYCLE.md",
     "docs/LEGACY-CLI-CROSSWALK.md",
     "docs/AGENT-CONTEXT.md",

package/skills/cc-collab/SKILL.md

@@ -27,10 +27,13 @@ claude --safe-mode -p "<bounded prompt>" \
   --no-session-persistence
 ```
 
-Store large output under `.ultra/collab/<session-id>/claude-output.md`. A missing CLI,
+Store large output under `.ultra/.runtime/collab/<session-id>/claude-output.md`. A missing CLI,
 failed authentication, timeout, or empty response degrades to host-only analysis and
 never blocks the underlying task.
 
+Treat `.ultra/.runtime/collab/` as working scratch, not Ultra authority. Promote only verified
+conclusions into the invoking DB-bound workflow artifact or report.
+
 ## Synthesis
 
 Verify consequential claims against the current checkout, runtime, tests, or primary

package/skills/codex-collab/SKILL.md

@@ -17,10 +17,10 @@ evidence, edits, verification, and the final answer.
 
 ## Invocation
 
-Create a session directory under `.ultra/collab/`, then run in a read-only sandbox:
+Create a session directory under `.ultra/.runtime/collab/`, then run in a read-only sandbox:
 
 ```bash
-SESSION_PATH=".ultra/collab/$(date +%Y%m%d-%H%M%S)-codex"
+SESSION_PATH=".ultra/.runtime/collab/$(date +%Y%m%d-%H%M%S)-codex"
 mkdir -p "${SESSION_PATH}"
 codex exec -s read-only \
   --ephemeral \
@@ -35,6 +35,9 @@ Do not enable write-capable automation or permission bypass. The isolation flags
 the advisory run independent from the user's Codex runtime configuration and rules;
 the normal Codex authentication store remains available.
 
+Treat `.ultra/.runtime/collab/` as working scratch, not Ultra authority. Promote only verified
+conclusions into the invoking DB-bound workflow artifact or report.
+
 ## Synthesis
 
 Read output only after the process exits and the file is non-empty. Verify

package/skills/ultra-change/SKILL.md

@@ -13,8 +13,10 @@ Read `../ultra-think/references/decision-dialogue.md` before asking a material q
 
 ## Inspect and align
 
-1. Read `system.doctor`, `baseline.get`, active changes, decisions, and
-   `change.breadcrumb`.
+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.
@@ -34,6 +36,10 @@ 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
@@ -55,9 +61,25 @@ Call `change.create`. It records and completes exactly:
 3. `record-intent`
 
 The returned change workflow must be `completed`; research, plan, context, dev, test,
-review, and deliver remain independent capabilities. Standard and major changes may
-store delta artifacts under `.ultra/changes/active/<id>/delta/`. Incidents maintain
-the structured diagnosis artifact.
+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
@@ -66,9 +88,11 @@ change must become stale and be regenerated; never keep old evidence green by pr
 assertion.
 
 If research is required, recommend `ultra-research` with the recorded disposition. If
-the contract is sufficiently evidenced, recommend `ultra-plan`. Return and wait for an
-explicit user invocation; do not start either workflow. `change.context` is compiled
-only for an actual plan, implementation, test, or review consumer.
+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
@@ -79,3 +103,5 @@ and `allowed_transitions`. Recommend a semantic next action from those transitio
 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.

package/skills/ultra-deliver/SKILL.md

@@ -10,8 +10,9 @@ push, tag, registry publication, deployment, or another external effect.
 
 ## Bind current evidence
 
-1. Read doctor, baseline, change, breadcrumb, decisions, tasks, test, review, learning,
-   and current checkout.
+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`.
@@ -21,25 +22,37 @@ Evidence from another revision, task set, or change is invalid.
 ## Reconcile specifications
 
 Resolve every specification-learning candidate. Apply approved learning to its target
-with before/after digests and verification; preserve rejection reasons.
+inside the Change overlay; preserve rejection reasons. Read the current registered
+`change.delta` and verify every baseline anchor, payload digest, acceptance reference,
+and unknown.
 
-Read `references/baseline-reconciliation.md` and write the reconciliation manifest
-inside the active change directory. Record semantic additions or updates, resolved
-gaps and unknowns, and verification. If baseline semantics did not change, record an
-evidenced no-change reason. Record `reconcile-specifications`.
+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,
-specification, docs, diagnosis, and current checkout evidence. Record
+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 reconciliation manifest and summary. Verify the refreshed
-baseline and archived packet, then record `archive-change`.
+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 `.ultra/reports/delivery/<workflow-id>.json` with
+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.
@@ -54,3 +67,5 @@ 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.

package/skills/ultra-dev/SKILL.md

@@ -10,14 +10,25 @@ fresh context contract, session lease, evidence references, and recovery.
 
 ## Bind and resume
 
-1. Read doctor, breadcrumb, active decisions, task contract, dependencies, dev runs,
-   sessions, HEAD, and worktree.
+1. Read doctor, `task.ledger_get`, breadcrumb `accepted_intent`, active decisions, task
+   contract, dependencies, dev runs, sessions, HEAD, and worktree. Import a newer
+   descendant team checkpoint before taking a lease. Stop on a typed baseline, Change,
+   task, ancestry, or active-session conflict; do not merge authority by editing JSON.
 2. Resume the matching dev run or start one with `change_id` and `task_id`.
 3. Record `bind-task` with current authority and dependency evidence.
-4. Compile `change.context` for `implement` using DB-backed public seam, verification
-   command, and refs. Context budgets are advisory; missing required evidence is
-   blocking. Record the immutable manifest as `compile-context`.
-5. Reuse an existing valid session. Otherwise pass admission and call `session.spawn`.
+4. Compile `change.context` with `role: implement` and `gate: implementation`. The
+   public seam, verification command, and context refs come from the DB-backed task
+   contract; update that contract before compilation instead of overriding it in the
+   call. Persist any changed external-provider metadata with `change.update` first.
+   Context compilation itself is read-only with respect to Change and provider
+   authority.
+5. Confirm the manifest contains the selected task, its direct dependencies, direct
+   dependents needed for integration, and relevant integration checkpoints—not the
+   entire task graph. Referenced file bodies stay lazy. The token estimate includes
+   inline Change/task authority as well as file estimates; budget overflow is
+   advisory, while a missing or stale required reference is blocking. Record the
+   immutable manifest as `compile-context`.
+6. Reuse an existing valid session. Otherwise pass admission and call `session.spawn`.
    Work only in the returned worktree and preserve unrelated changes.
 
 Do not spawn recursively from a parent-owned worker session. Process exit is transport
@@ -38,8 +49,30 @@ evidence, never task completion.
 5. Run a task-scoped independent review on specification fidelity and relevant
    engineering risks. Record `review-slice`. Fix blocking findings and refresh affected
    evidence.
-6. Create the authorized local task commit. Do not push, publish, tag, or deploy unless
-   the user separately authorized that external effect.
+6. In direct mode, update the task to `completed` only after verification and review
+   are current. This publishes the durable team ledger checkpoint. Create one
+   authorized local task commit containing code, semantic artifacts, and that
+   checkpoint. Read the resulting `HEAD`, then record it as `completion_commit`;
+   that hash remains checkout-local and must not create another Git commit. Do not
+   push, publish, tag, or deploy unless the user separately authorized that external
+   effect.
+
+The tracked team checkpoint contains durable task status and contract evidence, not
+live ownership. `in_progress`, `session_id`, leases, worktrees, telemetry, and
+`completion_commit` remain checkout-local. The local generated task view lives under
+`.ultra/.runtime/projections/` and is never committed.
+
+Treat the compiled task-context contract as the handoff boundary: purpose, why,
+constraints, non-goals, target seams/files, pattern refs, acceptance, documentation
+impact, recovery, and definition of drift. If accepted intent, the task contract, or a
+digest-bound reference changes, update the owning authority and recompile rather than
+continuing from a stale packet.
+
+Keep implementation findings and documentation candidates inside the owning Change
+root. When code changes invalidate or extend maintained documentation, update the
+Change documentation overlay and its evidence rather than editing accepted baseline
+specifications. Hooks may remind the host to reconcile documentation; they must not
+block ordinary development or choose the semantic update.
 
 Task-level tests and review belong to this inner loop. They do not replace aggregate
 change testing or review when multiple slices, integrations, or broader risks require
@@ -48,8 +81,15 @@ those capabilities.
 ## Complete or recover
 
 In direct mode, integrate the task commit through the repository's accepted path,
-verify ancestry and the public seam, close the session, update the task to `completed`,
-record `record-completion`, and complete the dev workflow.
+verify ancestry and the public seam, close the session, record `record-completion`,
+and complete the dev workflow. If commit creation fails after the pre-commit
+completion checkpoint, move the still-session-owned task to `blocked`, preserve the
+worktree, and record the failure. A completion with a recorded commit remains
+terminal.
+
+Change convergence revalidates the exact latest
+`change_id + task_id + implement + implementation` snapshot for every executable
+task. A newer review, test, or plan packet cannot substitute for it.
 
 In a parent-supervised worker, record completion evidence and exit without closing the
 parent-owned lease. The primary host verifies the exact session commit, performs any
@@ -62,3 +102,5 @@ worktree and evidence, and resume the same run later.
 
 Return outcome, changed paths, public seam, exact checks, review axes, commit and
 session state, residual risk, and allowed transitions.
+
+Never invoke the recommended capability here; wait for an explicit user invocation.

package/skills/ultra-doctor/SKILL.md

@@ -13,10 +13,14 @@ work complete.
 
 Run `system.doctor` without repair and inspect:
 
-- SQLite integrity, schema 18 migration, required tables, and backups;
+- SQLite integrity, schema 20 migration, required tables, and backups;
+- artifact registration, ownership, digest freshness, dependency edges, consumers,
+  and orphan or duplicate authority;
 - baseline and research provenance, gaps, digests, and Git/worktree drift;
 - workflow status, obsolete-step migration, blockers, and output freshness;
 - decisions and checkpoint artifact freshness;
+- Git team-checkpoint schema, ancestry, per-baseline, per-Change, and per-task drift,
+  plus checkout-local baseline revalidation requirements;
 - projection jobs and event cursors;
 - sessions, preserved worktrees, incidents, circuit state, and archive journals;
 - external provider boundaries.
@@ -30,21 +34,30 @@ by doctor.
 With explicit repair authorization, `system.doctor` may:
 
 - apply backup-first supported schema migrations;
-- migrate active pre-18 rigid workflows into recoverable adaptive state;
+- migrate incompatible rigid workflows into recoverable adaptive state;
 - requeue or regenerate projections from healthy DB authority;
 - reconcile orphan sessions without deleting unrelated or dirty worktrees;
 - resume supported archive journals;
 - recover missing workflow provenance as a blocked run requiring real evidence.
 
 It may not create a Git checkpoint, replace a healthy baseline, accept known failures,
-resolve decisions, regenerate semantic content, or edit application code.
+resolve decisions, regenerate semantic content, import or publish the team checkpoint,
+or edit application code. A missing or drifted valid checkpoint is a warning; invalid
+content or conflicting ancestry is degraded authority. Resolve semantic checkpoint
+state explicitly with `task.ledger_import` or `task.ledger_publish` after reviewing
+the typed conflict.
 
 Corrupt SQLite requires preservation of DB, WAL, and SHM followed by an explicit
 restore-or-rebaseline choice. Missing hook adapters or stale cache paths require
 `ubp --doctor` and adapter reinstall; never patch plugin cache contents by hand.
+A legacy task projection is never rewritten by doctor. The supported publication path
+first proves its durable task fields match SQLite and preserves its original bytes in
+the local runtime backup directory.
 
 After repair, rerun doctor read-only and verify backup paths, schema, installed hashes,
 entry points, MCP startup, and hook smoke tests as applicable.
 
 Return health first, failed checks, mechanical repairs performed, preserved recovery
 paths, unresolved owners, and allowed transitions plus any unique required transition.
+
+Never invoke the recommended capability here; wait for an explicit user invocation.