ultra-builder-pro-cli 0.19.1 → 0.21.1

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.19.1",
+  "version": "0.21.1",
   "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,8 @@ 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`, `baseline.get`, active changes, breadcrumb `accepted_intent`,
+   decisions, and `change.breadcrumb`.
 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.
@@ -29,13 +29,22 @@ Read `../ultra-think/references/decision-dialogue.md` before asking a material q
    - change kind and evidence-backed risk flags;
    - research disposition.
 
-Select `quick`, `standard`, `major`, or `incident` from actual scope and risk. A quick
-change may have no material risk, research obligation, or more than one task.
+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. The model owns reversible implementation detail inside the accepted contract.
+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
 
@@ -50,9 +59,19 @@ 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.
+
+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
@@ -61,14 +80,20 @@ 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
 metadata references only.
 
 Return the normalized contract, change id and kind, research disposition, blockers,
-and `allowed_transitions`. The host selects a recommendation from those transitions;
-MCP does not encode a semantic next action.
+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.

package/skills/ultra-deliver/SKILL.md

@@ -10,8 +10,8 @@ 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, baseline, change, breadcrumb `accepted_intent`, decisions, tasks, test,
+   review, learning, and current checkout.
 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 +21,35 @@ 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.
+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. 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 +64,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,23 @@ 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, breadcrumb `accepted_intent`, active decisions, task contract,
+   dependencies, dev runs, sessions, HEAD, and worktree.
 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
@@ -41,6 +50,18 @@ evidence, never task completion.
 6. Create the authorized local task commit. Do not push, publish, tag, or deploy unless
    the user separately authorized that external effect.
 
+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
 those capabilities.
@@ -51,6 +72,10 @@ 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.
 
+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
 integration, refreshes review if the reviewed checkout changed, settles the lease, and
@@ -62,3 +87,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,7 +13,9 @@ 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;
@@ -30,7 +32,7 @@ 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;
@@ -48,3 +50,5 @@ 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.

package/skills/ultra-init/SKILL.md

@@ -13,7 +13,7 @@ the next semantic workflow.
 
 1. Identify the repository root, existing `.ultra` state, Git state, meaningful source,
    monorepo boundaries, and current owner request.
-2. If `.ultra/state.db` exists, run `system.doctor` read-only and resume with
+2. If `.ultra/.runtime/state.db` exists, run `system.doctor` read-only and resume with
    `task.init_project` only when its report permits it.
 3. Otherwise call `task.init_project` with `mode: "auto"`, the project name, and an
    explicit scope only when the repository contains multiple plausible roots.
@@ -48,7 +48,7 @@ unresolved. Normalize clear intent already present in the request without asking
 
 The operation must:
 
-- create or migrate `.ultra/state.db` with a backup before schema migration;
+- create or migrate `.ultra/.runtime/state.db` with a backup before schema migration;
 - install only missing scaffold assets on resume;
 - preserve existing artifacts and unrelated work;
 - preserve an existing Git repository and HEAD;
@@ -81,3 +81,5 @@ Read the returned `allowed_transitions` and `required_transition`:
 Report classification, scope, schema and backup result, Git state, init workflow id,
 baseline state, and allowed transitions. Do not claim that a baseline is ready until a
 separate research/adoption workflow has recorded and converged it.
+
+Never invoke the recommended capability here; wait for an explicit user invocation.