ultra-builder-pro-cli 0.12.1 → 0.13.0

package/mcp-server/tests/state-ops.test.cjs

@@ -20,6 +20,13 @@ function freshDb() {
   return { ...t, db: init.db };
 }
 
+function seedChange(db, id, status = 'active') {
+  db.prepare(
+    `INSERT INTO changes (id, title, kind, status, intent, artifact_root)
+     VALUES (?, ?, 'quick', ?, ?, ?)`,
+  ).run(id, `Change ${id}`, status, `Intent for ${id}.`, `.ultra/changes/active/${id}`);
+}
+
 test('createTask inserts a row, preserves estimated_days, defaults status=pending, emits task_created', () => {
   const { dir, db } = freshDb();
   try {
@@ -65,6 +72,107 @@ test('createTask rejects duplicates with DUPLICATE_TASK_ID', () => {
   }
 });
 
+test('createTask preserves parent change ownership and rejects terminal change targets', () => {
+  const { dir, db } = freshDb();
+  try {
+    seedChange(db, 'change-a');
+    seedChange(db, 'change-b');
+    seedChange(db, 'change-closed', 'archived');
+    ops.createTask(db, {
+      id: 'parent-owned', title: 'owned parent', type: 'feature', priority: 'P1',
+      change_id: 'change-a',
+    });
+    const inherited = ops.createTask(db, {
+      id: 'child-inherited', title: 'inherited child', type: 'feature', priority: 'P1',
+      parent_id: 'parent-owned',
+    });
+    assert.equal(inherited.change_id, 'change-a');
+    assert.throws(
+      () => ops.createTask(db, {
+        id: 'child-mismatch', title: 'mismatched child', type: 'feature', priority: 'P1',
+        parent_id: 'parent-owned', change_id: 'change-b',
+      }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    assert.throws(
+      () => ops.createTask(db, {
+        id: 'child-orphan', title: 'orphan child', type: 'feature', priority: 'P1',
+        parent_id: 'missing-parent',
+      }),
+      (error) => error.code === 'TASK_NOT_FOUND',
+    );
+    assert.throws(
+      () => ops.createTask(db, {
+        id: 'closed-change-task', title: 'closed change task', type: 'feature', priority: 'P1',
+        change_id: 'change-closed',
+      }),
+      (error) => error.code === 'CHANGE_NOT_MUTABLE',
+    );
+  } finally {
+    closeStateDb(db);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('patchTask keeps established ownership immutable and rejects terminal-change writes', () => {
+  const { dir, db } = freshDb();
+  try {
+    seedChange(db, 'change-a');
+    seedChange(db, 'change-b');
+    seedChange(db, 'change-ready', 'ready');
+    ops.createTask(db, {
+      id: 'patch-parent', title: 'patch parent', type: 'feature', priority: 'P1',
+      change_id: 'change-a',
+    });
+    ops.createTask(db, {
+      id: 'patch-child', title: 'patch child', type: 'feature', priority: 'P1',
+      parent_id: 'patch-parent',
+    });
+    assert.throws(
+      () => ops.patchTask(db, 'patch-child', { change_id: null }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    assert.throws(
+      () => ops.patchTask(db, 'patch-child', { change_id: 'change-b' }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    assert.throws(
+      () => ops.patchTask(db, 'patch-parent', { change_id: 'change-b' }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    const root = ops.createTask(db, {
+      id: 'patch-root', title: 'owned root', type: 'feature', priority: 'P1',
+      change_id: 'change-a',
+    });
+    assert.equal(root.change_id, 'change-a');
+    assert.throws(
+      () => ops.patchTask(db, 'patch-root', { change_id: null }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    assert.throws(
+      () => ops.patchTask(db, 'patch-root', { change_id: 'change-b' }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    const standalone = ops.createTask(db, {
+      id: 'patch-standalone', title: 'patch standalone', type: 'feature', priority: 'P1',
+    });
+    assert.equal(standalone.change_id, null);
+    assert.equal(ops.patchTask(db, 'patch-standalone', { change_id: 'change-b' }).change_id, 'change-b');
+    assert.throws(
+      () => ops.patchTask(db, 'patch-root', { change_id: 'change-ready' }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    db.prepare("UPDATE changes SET status = 'archived' WHERE id = 'change-a'").run();
+    assert.throws(
+      () => ops.patchTask(db, 'patch-root', { priority: 'P0' }),
+      (error) => error.code === 'CHANGE_NOT_MUTABLE',
+    );
+  } finally {
+    closeStateDb(db);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('updateTaskStatus enforces the legal transition graph', () => {
   const { dir, db } = freshDb();
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, Codex CLI, and Kimi Code.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",

package/skills/ultra-change/SKILL.md

@@ -16,11 +16,13 @@ own their payloads; Ultra stores only provider references supplied by the user o
 
 ## Workflow
 
-1. Call `baseline.get`. State integrity failure routes to `ultra-doctor`. When no
-   change is active, a missing, incomplete, or stale baseline routes to `ultra-init`.
-   An urgent or already active bounded change may proceed with that condition recorded
-   as a warning. `change.converge` requires an approved `ready` baseline; repository
-   revision and tracked-spec drift created by the change are reconciled at archive.
+1. Call `baseline.get`. State integrity failure routes to `ultra-doctor`.
+   - Create ordinary work only when the baseline is healthy and `ready`.
+   - Resume a change that was already active when baseline drift appears; record the
+     condition as a warning and restore baseline readiness before ordinary convergence.
+   - Create an `incident` on an unhealthy baseline only with an explicit
+     `baseline_bypass` containing the reason and approver.
+   - Route every other missing, migrated, incomplete, or stale baseline to `ultra-init`.
 2. Call `change.list` and `change.breadcrumb`.
    - Resume the single change that matches the requested outcome.
    - Require an explicit id when several changes could match.
@@ -30,6 +32,8 @@ own their payloads; Ultra stores only provider references supplied by the user o
 4. Classify the change as `quick`, `standard`, `major`, or `incident`. Ask only for a
    material product, risk, or recovery decision that repository evidence cannot answer.
 5. Call `change.create` with a stable kebab-case id, or `change.update` when resuming.
+   For incident break-glass, persist the approved reason in `baseline_bypass`; never
+   infer approval from urgency.
 6. Write the minimum artifact set required by the classification:
 
    ```text
@@ -69,8 +73,12 @@ verified.
 ## Completion gate
 
 Do not claim alignment while a material decision is unresolved, documentation impact
-is unknown, context is stale, or the next task is not executable. `change.converge`
-also requires a `ready` baseline, so incomplete adoption must be resolved before
-convergence. Normal HEAD or tracked-spec drift caused by the active change is not a
-convergence blocker. Declare every baseline update at archive; archive fails and rolls
-back when revision or digest health remains stale after reconciliation.
+is unknown, context is stale, or the next task is not executable. Ordinary change
+convergence requires a non-migrated `ready` baseline. Normal HEAD or tracked-spec drift
+caused by the active change is reconciled at archive.
+
+An approved break-glass incident may converge and archive while baseline adoption is
+incomplete. Its archive must add an open `baseline_blocker` reconciliation gap owned by
+the recorded approver. Report the incident as closed and the project baseline as not
+ready until that gap is resolved. Every archive declares baseline updates or an exact
+no-change reason; failed ordinary reconciliation rolls back state and artifacts.

package/skills/ultra-deliver/SKILL.md

@@ -12,10 +12,10 @@ review, and delivery reports are evidence artifacts.
 
 1. Call `baseline.get`, then `change.list`. Bind exactly one relevant change, or the
    current draft/adopting baseline when this is the initial delivery.
-2. Call `change.breadcrumb`. Context-size warnings are advisory, but delivery blocks
-   on incomplete baseline adoption, stale execution context, incomplete linked tasks,
-   or unresolved readiness. HEAD and tracked-spec drift caused by the current change
-   remain visible warnings until archive reconciliation.
+2. Call `change.breadcrumb`. Context-size warnings are advisory. Ordinary delivery
+   blocks on incomplete baseline adoption, stale execution context, incomplete linked
+   tasks, or unresolved readiness. An explicitly approved break-glass incident may
+   continue while baseline adoption is incomplete.
 3. Require a passing test report for the current full HEAD and at least one declared
    public seam.
 4. Require current independent `spec_fidelity` and `engineering_standards` review
@@ -59,11 +59,15 @@ delta, documentation, both independent review axes, and incident diagnosis when
 applicable. Do not collapse review axes or replace exact signal fields with prose.
 
 Resolve named blockers, rerun invalidated gates, then call `change.archive` with the
-summary and baseline updates. Archive reconciliation refreshes the authoritative
-baseline revision and digests. The archive transaction rechecks baseline health and
-rolls back the state row, artifacts, and reconciliation events if any tracked digest
-or repository revision remains stale. Verify the result with `baseline.get` before
-release.
+summary and baseline updates or an exact no-change reason. Ordinary archive
+reconciliation refreshes the authoritative baseline revision and digests, rechecks
+health, and rolls back state and artifacts when any tracked digest or revision remains
+stale.
+
+For a break-glass incident, verify that archive returned `baseline_bypass: true` and
+created the open reconciliation gap on the current baseline. Report incident delivery
+separately from project baseline readiness. Resolve that gap through `ultra-init`
+before starting ordinary work.
 
 ## Optional release
 

package/skills/ultra-dev/SKILL.md

@@ -17,8 +17,10 @@ Read `change.breadcrumb` when a change is active. Stale context, blocked readine
 unknown documentation impact, or a HEAD mismatch blocks implementation.
 Baseline-adoption and context-size warnings do not block an active slice. Address
 them when practical without dropping required evidence or arbitrarily changing a
-threshold. Approved baseline availability is enforced at convergence; revision and
-tracked-spec health are reconciled and verified at archive.
+threshold. Ordinary convergence requires approved baseline availability; revision
+and tracked-spec health are reconciled and verified at archive. An approved
+break-glass incident may finish recovery first and must leave a blocking baseline
+reconciliation gap.
 
 ## Workflow
 
@@ -40,8 +42,8 @@ tracked-spec health are reconciled and verified at archive.
    utilities, keep IO at boundaries, include required errors and recovery, and preserve
    unrelated worktree changes.
 7. If the work reveals a stable requirement or public behavior absent from the
-   baseline, call `change.learning_propose`. Do not edit the baseline silently or store
-   the discovery as private Ultra memory.
+   baseline, call `change.learning_propose`. Do not edit the baseline silently or keep
+   the discovery only in transient conversation context.
 8. Verify in this order:
    - the original feedback-loop command;
    - adjacent focused tests;

package/skills/ultra-doctor/SKILL.md

@@ -15,6 +15,7 @@ Call `system.doctor` with `{ "repair": false }` and inspect:
 - open structured incidents;
 - event and projection cursor lag;
 - failed or interrupted projection jobs;
+- interrupted archive journals;
 - orphan sessions;
 - missing active-change artifact roots;
 - missing, incomplete, or stale project baseline readiness and specification digests;
@@ -36,17 +37,31 @@ delete artifacts, or collect memory during diagnosis.
   not approve a baseline, accept known-red verification, or invent adoption evidence.
   Baseline readiness is an advisory workflow check, not state-database corruption and
   not a reason for doctor repair.
+- A compatibility `migrated` baseline requires explicit brownfield re-adoption and
+  cannot authorize ordinary changes.
+- A corrupt SQLite file requires preserving the file, locating a verified backup, and
+  an explicit restore-or-rebaseline decision.
 
 ## Explicit repair
 
 After authorization, call `system.doctor` with `{ "repair": true }` or use the
-installed `ultra-tools system doctor --repair` fallback. The runtime must create a
-timestamped state database backup before any mechanical repair.
-
-Repair is limited to documented recovery operations such as reconciling orphan
-sessions, consuming staleness events, requeueing interrupted or failed projections,
-and regenerating projections from authoritative state. If backup fails, stop. Always
-inspect the post-repair report; a completed repair action does not imply healthy state.
+installed `ultra-tools system doctor --repair` fallback. The CLI applies supported
+schema upgrades to the packaged current schema and reports a pre-migration backup path. Doctor then
+creates a second timestamped backup before runtime recovery.
+
+Repair is limited to documented schema upgrades, archive-journal completion,
+reconciling orphan sessions, consuming staleness events, requeueing interrupted or
+failed projections, and regenerating projections from authoritative state. If either
+backup fails, stop. Always inspect the post-repair report; a completed repair action
+does not imply healthy state.
+
+If SQLite integrity prevents doctor from opening authority, preserve the original
+database, WAL, and SHM. After the owner chooses a recovery path, either run
+`ultra-tools system restore --backup <managed-backup> --confirm
+REPLACE_CORRUPT_ULTRA_STATE` or run `ultra-tools system rebaseline --project-name
+<name> [--scope <path>] --confirm REBASELINE_CORRUPT_ULTRA_STATE`. Both commands
+must report the recovery backup directory. A failed command must restore the
+original authority, sidecars, and task projection before returning an error.
 
 ## Installed-plugin failures
 

package/skills/ultra-init/SKILL.md

@@ -1,66 +1,111 @@
 ---
 name: ultra-init
-description: Initialize Ultra Builder Pro or resume greenfield and brownfield baseline adoption. Use when a repository lacks Ultra state or its project baseline is missing, draft, adopting, or blocked.
+description: Initialize a new repository, adopt an existing codebase, or upgrade prior Ultra state into an evidence-backed project baseline. Use when `.ultra` is absent, baseline readiness is incomplete, or legacy project state must be migrated.
 ---
 
-# Initialize or adopt a project
-
-Create project-local Ultra state, then route the repository according to its actual
-baseline status. Do not treat an existing codebase as a new product.
-
-## Preflight
-
-Use the current working directory unless the user names another target. Inspect the
-root, project manifests, Git state, and `.ultra/` without mutation.
-
-If `.ultra/` exists, call `baseline.get` and `system.doctor`:
-
-- a healthy `ready` baseline routes to `ultra-change` or `ultra-status`;
-- `draft`, `adopting`, or baseline-blocked state resumes this workflow;
-- state integrity or migration failure routes to `ultra-doctor`;
-- recreation requires explicit authorization and must preserve the returned backup.
-
-Never overwrite `.ultra/` merely because the repository is old or its documents are
-incomplete.
+# Establish the project baseline
+
+Create or recover project-local Ultra authority, classify the repository, and finish
+the applicable baseline workflow. Keep application source unchanged during adoption.
+
+## Authority rules
+
+- Treat `.ultra/state.db` as the only durable Ultra authority.
+- Preserve every existing `.ultra/` tree and migration backup.
+- Require explicit authorization before replacing a healthy baseline or discarding a
+  corrupt database.
+- Store only metadata references for external memory and code-graph providers.
+- Create ordinary tasks only after the baseline is ready. Record characterization
+  needs and adoption gaps in the gap ledger until convergence.
+
+## Inspect and route
+
+1. Bind the repository root, Git branch and HEAD, worktree status, manifests, package
+   scripts, workspace markers, deployment files, and existing `.ultra/` assets.
+2. When `.ultra/` is absent, run **Bootstrap**.
+3. When `.ultra/tasks/tasks.json` contains tasks but `state.db` is absent or has no
+   tasks, run **Import projection-only state** before ordinary state-backed work.
+4. When `state.db` exists, run read-only project doctor first. Call `baseline.get`
+   only when doctor confirms that the current schema authority is readable. Route an
+   old schema to repair and a corrupt database to recovery without another DB read.
+5. After current authority is readable, call `task.init_project` with `resume: true` to install
+   only missing current scaffold files. Verify that existing artifacts were preserved.
+6. Route the result:
+   - healthy `ready` baseline: return `ultra-change` or `ultra-status`;
+   - `draft`, `adopting`, or baseline-blocked: resume the matching baseline;
+   - `migrated`: start evidence-backed brownfield re-adoption;
+   - old schema: run backup-first schema repair;
+   - corrupt database: preserve it and stop at the restore-or-rebaseline decision.
 
 ## Bootstrap
 
-When `.ultra/` is absent, derive project name, type, and stack from repository evidence,
-then call `task.init_project` with `mode: "auto"`. Use an explicit `greenfield` or
-`brownfield` mode only when the user has made that classification authoritative.
-
-Verify the returned mode, baseline id and status, state database path, initial
-projection, and copied specification files.
-
-## Route by mode
-
-### Greenfield
-
-The new baseline begins as `draft`. Route unresolved product or architecture intent to
-`ultra-research`. That workflow records evidence and converges the baseline before
-planning. Do not create implementation tasks during initialization.
-
-### Brownfield
-
-Read `references/brownfield-adoption.md` completely. Adopt current behavior from the
-checkout, tests, maintained documentation, and runtime evidence. Use `baseline.record`
-for the bounded snapshot and `baseline.converge` only after the owner approves the
-captured baseline and any accepted known-red verification.
-
-## Failure handling
-
-- `ULTRA_DIR_EXISTS`: inspect and resume; do not retry with overwrite automatically.
-- `BASELINE_EXISTS`: keep the ready baseline unless explicit re-adoption is required.
-- `BASELINE_IN_PROGRESS`: resume the named baseline rather than creating another.
-- `TEMPLATE_MISSING`: report a package-integrity failure and route to installer doctor.
-- `TARGET_NOT_DIR`, `VALIDATION_ERROR`, or `IO_ERROR`: correct only the evidenced input;
-  preserve any backup and partial diagnostic.
-
-## Output
-
-Report target path, detected mode, baseline id/status/revision, state health, known-red
-verification, blocking unknowns, and one next action. `.ultra/state.db` is authoritative;
-JSON and Markdown projections do not create state.
-
-Do not browse by default, invent missing behavior, rewrite application code, create
-business tasks, stage files, or commit as part of initialization.
+Derive project metadata from repository evidence. Call `task.init_project` with
+`mode: "auto"`. Pass `scope` when the user selected a monorepo boundary; otherwise use
+the repository root. Use an explicit mode only when the user supplied an authoritative
+classification.
+
+Verify `repository_profile`, selected scope, detected mode, baseline lifecycle, schema
+version, copied templates, initial projection, and `project_initialized` event.
+
+## Import projection-only state
+
+Call `task.init_project` with `resume: true` as the single authority check and run the
+exact supported backup-first import command returned in its structured error. Do not
+infer an import path or edit the projection manually.
+
+Verify imported task and event counts, backup path, current schema state, projection
+parity, and the `migrated/adopting` compatibility baseline. Then call `baseline.start` with a
+new id, `mode: "brownfield"`, `replace_migrated: true`, the selected scope, current
+revision, and repository classification. Never treat the compatibility row as owner
+approval.
+
+For an older database schema, run `ultra-tools system doctor --repair`; verify both the
+pre-migration backup and post-repair backup plus the current schema before continuing.
+Then resume initialization to merge missing scaffold assets without overwriting the
+project's existing baseline documents.
+
+## Complete the selected mode
+
+For `brownfield`, `migrated`, or an incomplete existing adoption, read
+`references/brownfield-adoption.md` completely and execute it through owner approval.
+
+For `greenfield`, keep the baseline in `draft` until product and architecture intent is
+evidence-backed. Route unresolved intent through `ultra-research`, record the complete
+baseline snapshot, obtain owner approval, and converge it before planning.
+
+## Recovery handling
+
+- `ULTRA_DIR_EXISTS`: inspect and resume the existing state.
+- `LEGACY_STATE_MIGRATION_REQUIRED`: execute the returned migration command.
+- `BASELINE_IN_PROGRESS`: resume the named row; never create a parallel authority.
+- `BASELINE_EXISTS`: return the healthy route. Replacing a ready baseline is outside
+  ordinary initialization; stop for owner authorization before calling
+  `baseline.start` with a new id, `replace_ready: true`, and
+  `replacement_authorization: { approved_by, reason }`. The approval identity and
+  rationale must be persisted in the `baseline_started` event.
+- `BASELINE_SCOPE_MISSING`: correct the selected monorepo boundary.
+- `TEMPLATE_MISSING`: run installer doctor and reinstall through the host adapter.
+- `STATE_DB_CORRUPT`: retain the database, inspect `.ultra/backups`, and obtain the
+  restore-or-rebaseline decision. Restore only a verified managed backup with
+  `ultra-tools system restore --backup <path> --confirm REPLACE_CORRUPT_ULTRA_STATE`.
+  When no valid backup exists and the owner explicitly accepts rebuilding authority,
+  run `ultra-tools system rebaseline --project-name <name> [--scope <path>] --confirm
+  REBASELINE_CORRUPT_ULTRA_STATE`; verify the quarantined database and legacy
+  projection paths before continuing adoption.
+- `IO_ERROR`: verify rollback restoration and preserve every reported backup path.
+
+## Completion
+
+Initialization is complete only when:
+
+- current schema authority is readable;
+- repository classification and scope are recorded;
+- product and architecture baseline files exist;
+- verification, unknowns, gaps, evidence, and provider references are recorded;
+- explicit owner approval has converged the baseline to `ready`;
+- `baseline.get` reports current health and project doctor has no authority failure.
+
+Report the target, classification evidence, migration and backup paths, baseline id,
+mode, status, revision, branch, worktree snapshot, verification results, gap summary,
+approval state, and one exact next action. Stop at the approval step when owner consent
+has not yet been provided.

package/skills/ultra-init/references/brownfield-adoption.md

@@ -1,65 +1,93 @@
 # Brownfield adoption
 
-Use this procedure only after `task.init_project` selects `brownfield`, or when an
-existing baseline remains `adopting` or `blocked`.
+Execute this procedure for a detected brownfield repository, a migrated compatibility
+baseline, or an existing adoption in `adopting` or `blocked` state.
 
-## Establish the snapshot boundary
+## Bind the repository boundary
 
-Bind the repository root, current Git HEAD when available, included paths, excluded
-generated or vendored paths, project manifests, and the user-visible or public seams.
-Use the revision returned by `baseline.record`; non-Git projects receive a deterministic
-workspace revision from the recorded evidence.
+Record the repository root, selected scope, workspace roots, branch, HEAD, dirty files,
+generated and vendored exclusions, manifests, verification commands, and public seams.
+Use `.` for a whole-repository adoption. Use selected workspace roots only when the
+user's requested ownership is narrower than the monorepo.
 
-## Read current behavior
+The authoritative worktree snapshot contains only selected-scope paths. Report dirty
+files outside that scope separately as repository context, but do not include them in
+the baseline digest. Require `accept_dirty_worktree: true` only after the owner confirms
+the exact in-scope `worktree_files` returned by the server.
 
-Inspect only the evidence needed to explain the maintained system:
+## Build the evidence model
 
-- entry points and consumers;
-- persisted state and its writers;
-- external interfaces, events, permissions, and failure paths;
-- tests and their live seams;
-- deployment, migration, and recovery paths when present;
-- maintained documents and their relationship to source.
+Inspect the maintained system through its live boundaries:
 
-Classify every statement as observed, verified, decided, or unknown. Source and runtime
-evidence outrank stale prose. External memory and code-graph providers may supply
-references, but their content remains outside Ultra state.
+- product behavior, actors, entry points, and public acceptance;
+- runtime modules, consumers, data flow, persistence, and authority;
+- APIs, events, integrations, permissions, security, and failure paths;
+- build, test, lint, typecheck, deployment, migration, observability, and recovery;
+- maintained documents and every detected source-to-document conflict.
 
-## Capture the baseline
+Classify each material statement as `Observed`, `Verified`, `Decided`, or `Unknown`.
+Record document/source conflicts as drift. Keep provider payloads outside Ultra and
+record only bounded metadata references.
 
-Update `.ultra/specs/product.md` with confirmed behavior, actors, entry points, failures,
-and acceptance. Update `.ultra/specs/architecture.md` with actual boundaries, authority,
-runtime paths, dependencies, permissions, and recovery. Use `discovery.md` only for
-evidence or decisions that affect scope.
+## Write baseline artifacts
 
-Do not redesign the project, normalize it to a preferred architecture, manufacture
-personas or alternatives, or convert every source file into documentation.
+Update `.ultra/specs/product.md` with current delivered behavior and acceptance. Update
+`.ultra/specs/architecture.md` with real boundaries, owners, writers, consumers,
+consistency rules, permissions, failures, and recovery. Use `discovery.md` for scope
+evidence, decisions, and unresolved questions.
+
+Capture current facts without redesigning the application or manufacturing product
+narratives that are absent from evidence.
+
+## Run characterization verification
 
 Run the repository's existing verification commands. Record each result as `pass`,
 `known_red`, or `not_run`. A known-red item needs evidence and a rationale; a missing
-command is not a passing result. Mark an unknown blocking when it can change accepted
-behavior, authority, security, data integrity, or the next implementation plan.
+command is not a passing result. Record a characterization gap for a critical public
+seam that has no stable verification signal; create its ordinary task only after the
+baseline is ready.
+
+## Maintain the gap ledger
+
+Record every adoption gap with a stable id, evidence references, owner, blocking flag,
+and one category:
+
+- `baseline_blocker`: prevents trustworthy adoption;
+- `documentation_drift`: maintained prose conflicts with observed behavior;
+- `known_defect`: reproducible incorrect behavior;
+- `technical_debt`: accepted maintainability or quality cost;
+- `unknown`: evidence is insufficient;
+- `future_change`: desired behavior outside the current baseline.
+
+Use `open` for unresolved gaps, `accepted` for owner-accepted non-blocking debt,
+`resolved` when evidence closes the gap, and `deferred` for explicitly postponed
+non-blocking work. Every open `baseline_blocker` remains blocking. Do not convert the
+ledger into hundreds of application tasks.
+
+## Record authority
 
 Call `baseline.record` with full replacement arrays for:
 
 - scope and repository revision;
+- repository classification;
 - product and architecture specification paths;
 - bounded source, documentation, runtime, test, deployment, or external references;
 - verification results;
 - blocking and non-blocking unknowns;
+- the complete gap ledger;
 - external provider metadata references, when supplied.
 
-The server computes specification digests. Do not send prompt, transcript, memory, or
-code-graph payloads.
+Use the server-returned revision, branch, worktree digest, and specification digests.
 
-## Converge
+## Obtain approval and converge
 
-Present the observed behavior, known-red verification, blocking unknowns, and material
-decisions to the project owner. After explicit approval, call `baseline.converge` with
-the recorded revision, approver, approval note, and `accept_known_red` only when the
-owner accepted those failures.
+Present scope, observed behavior, drift, known-red verification, unknowns, gaps, dirty
+worktree state, and material decisions to the owner. Call `baseline.converge` only after
+explicit approval. Set `accept_known_red` and `accept_dirty_worktree` only for the exact
+items the owner accepted.
 
 Resolve returned blockers through evidence or an owner decision, record the replacement
-snapshot, and retry. Adoption is complete only when `baseline.get` and `system.doctor`
-report the baseline ready and current. Route the first new outcome to `ultra-change`, or
-route planning of already accepted work to `ultra-plan`.
+snapshot, and retry. Adoption is complete only when `baseline.get` is `ready` and
+current, the gap ledger has no open blocker, and project doctor has no authority
+failure. Route new work through `ultra-change`; route already accepted planned work
+through `ultra-plan`.

package/skills/ultra-plan/SKILL.md

@@ -16,8 +16,10 @@ route to `ultra-doctor`. Never read or write `.ultra/tasks/tasks.json` as a fall
 Call `baseline.get`. Initial product planning is blocked until the baseline is
 `ready` and current; route its missing, adopting, blocked, or stale state to
 `ultra-init`. Planning an already active bounded change may continue with the
-baseline condition recorded as a warning. Convergence still requires approved
-adoption, and archive atomically reconciles and verifies revision/spec drift.
+baseline condition recorded as a warning. Ordinary convergence still requires
+approved adoption, and archive atomically reconciles revision and specification
+drift. An approved break-glass incident follows its recorded recovery contract and
+creates a blocking reconciliation gap at archive.
 
 Choose one input:
 
@@ -63,11 +65,12 @@ id when applicable.
 
 ## PRD mode
 
-1. Call `task.parse_prd` with `dry_run: true`.
+1. Call `task.parse_prd` with `dry_run: true` and the active `change_id` when
+   applicable.
 2. Show the proposed slices, topology, conflict surface, and cost estimate.
 3. Require explicit approval; rejection performs no state write.
-4. On approval, repeat with `dry_run: false`, export the plan, and verify that the
-   dry-run and persisted task identities agree.
+4. On approval, repeat with `dry_run: false` and the same change ownership, export
+   the plan, and verify that the dry-run and persisted task identities agree.
 
 ## Completion gate