@deksden-com/dd-flow-cli 0.9.0-beta.144 → 0.9.0-beta.149

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.149
+
+### Patch Changes
+
+- 54899ed: Publish explicit proven Codex and OpenCode shutdown activity, reject unknown activity as clean settlement, and decode OpenCode finite log synchronization markers consistently for revision and completion.
+
+## 0.9.0-beta.148
+
+### Patch Changes
+
+- Validate lifecycle issuance before accessing storage, and align native readiness,
+  shutdown and overload regression fixtures with the current execution contract.
+
+## 0.9.0-beta.147
+
+### Patch Changes
+
+- Use the shared setup startup budget for silent prerequisite probes and preserve
+  typed subprocess failure diagnostics for init and upgrade without leaking output.
+
+## 0.9.0-beta.146
+
+### Patch Changes
+
+- d031e09: Add owned, trajectory-bound read-only AGY node-state inspection for native qualification. Capture parent executor idle independently from required-tree readiness, native task inventories and pending completion messages. Preserve qualified production prompt/stop ordering and owned fixture cleanup in native acceptance tooling.
+- acee374: Dispatch independent architectural criticism for Memory Bank audits when their accepted architecture aspect is applicable, matching the frozen review instructions.
+- 709f281: Reject diagnostic citation hash mismatches as correctable no-effect proposal errors, returning only the assigned relative path and computed digest. Retain bounded lifecycle correction, strict evidence acceptance and fatal snapshot/custody protection.
+- 18b0593: Treat unchanged-scope coverage annotations as correctable proposal errors and assign global diagnostic finding IDs from exact completed Work results during analysis settlement. Preserve strict scope, content, source and independent-review custody checks.
+- 7457963: Reject rewritten diagnostic focus as a bounded, no-effect proposal correction
+  requiring an exact copy of the accepted predecessor. Foreign focus modes,
+  changed aspect applicability and ownership violations remain fatal; no changed
+  focus is accepted and no frozen source selection is rewritten.
+- 1b315bf: Issue the exact immediate predecessor in diagnostic coordinator bindings and
+  align the frozen schema's list bound with the runtime contract. Transitive
+  history is a correctable proposal shape error; foreign direct bindings still
+  fail without acceptance.
+- da5bbf0: Allow diagnostics to record newly discovered unavailable sources without treating
+  them as a scope change. Retain accepted source-gap observations independently of
+  coordinator paraphrasing, while keeping focus, coverage and source-custody guards.
+- 6825b76: Allow diagnostic reports to disclose additional limitations while retaining all reviewed evidence, decisions and existing uncertainty unchanged.
+- e779d4d: Express diagnostic analyst/critic field restrictions in the frozen Work schema.
+  An analyst supplying review decisions remains rejected, but uses the existing
+  correctable schema-output path rather than a fatal foreign-aspect error.
+- 9939c87: Carry accepted predecessor and independently settled Work limitations into diagnostic analytical and review results in the CLI. Preserve coordinator annotations and raw proposals; retain schema bounds, scope, evidence and independent-review checks.
+- b765022: Clarify that generated review observations are not original project evidence.
+  Reject missing snapshot citations as correctable no-effect result errors while
+  preserving fatal containment, non-file and filesystem-access failures.
+- 249e5e3: Express preflight and analytical coordinator output boundaries in the frozen
+  stage schema, so unsupported findings or review decisions use existing format
+  correction while independent review remains mandatory.
+- 6f4011f: Separate required native execution readiness from owned resource retirement across harnesses. Require versioned, incarnation-bound shutdown phase proofs and retain process birth identities before provider shutdown. Qualify AGY daemon readiness independently from physical cleanup; ambiguous ancestry and native service identities remain unproven.
+
+  Fence retained recovery by the current control generation and preserve late activity during shutdown publication. Add metadata-bound AGY native tree control for typed services, gated by complete native qualification; control acknowledgements never substitute for physical retirement.
+
+- a5461c9: Preserve validated repair authority through lifecycle settlement, atomically issue
+  nonterminal successors, and retain accepted HITL context across same-session
+  overload continuation. Support versioned bounded runner and browser evidence,
+  and separate AGY physical shutdown from current native idle proof.
+- e00cda9: Use the verified relocated engine when launching a forked hybrid RUN. Preserve
+  the original bundle and manifest bytes as provenance; reject changed executable
+  content, semantic manifest metadata, or an unbound relocation path.
+- 759138b: Start restored generic-flow coordinator sessions in the current admitted RUN
+  workspace instead of the historical frozen execution path, without changing
+  retained execution bytes or profiles.
+- 5bea245: Use the verified current RUN project and workspace paths when settling restored
+  descriptor stages and terminal RUNs. Preserve frozen provenance, ownership,
+  Git-drift checks and exact replay rather than querying historical project roots.
+- 42cb47b: Read retained descriptor stage-input custody through trusted RUN publication
+  relocations after restore, preserving original packet bytes and rejecting
+  ambiguous or changed custody.
+
+## 0.9.0-beta.145
+
+### Patch Changes
+
+- Normalize Git diagnostics for gitless workspace inventories without masking damaged repositories; keep integration fixture tools on an explicitly selected PATH and scope simulated journal stalls to failure persistence.
+
+- Select Gemini's encoded reasoning level without an unsupported AGY `--effort` override; reject conflicting requested levels before native launch, while retaining explicit effort for other model families.
+
+- Preserve the effective environment across pinned engine dispatch. Isolate package-consumer routing and own executable test discovery; reduce duplicate gate preparation without removing release guarantees.
+
+- ea4e88e: Add hybrid mb-upgrade with retained current/target selection, scoped migration
+  bootstrap, preserved old-bank evidence, independent Work review and marker-free
+  ordinary flow readiness. Keep existing RUN engine bindings and reconcile partial
+  startup and publication through their original requests.
+
+  Retain bounded Codex admission phase diagnostics and separate native-host startup
+  headroom from the shared admission deadline. Refuse writer migration while a
+  MERGE request remains unresolved, including same-session integration without a
+  live process; terminal historical requests do not block migration.
+
+  Preserve project lint exclusions while independently checking affected active
+  Markdown through a separate mb-lint configuration when needed (`--config`
+  support required). Retain both reports and the effective configuration as check
+  evidence. Allow malformed terminal proposal JSON to be corrected through the
+  existing no-effect lifecycle successor without repeating Git integration.
+  Align generated FINISH guidance with the minimal proposal and CLI-owned sealed
+  coverage, findings and evidence for both initialization and upgrade.
+  Keep exact source-canon spec/protocol provenance relations distinct from
+  consumer-owned link targets when checking customized guidance. Derive scoped
+  exceptions from retained target bytes; new project/body links and Git-aware
+  ignored-target checks remain active, and project configuration stays unchanged.
+  Reject malformed bounded JSON at the shared Memory finish ingress as a
+  correctable proposal before stage-specific projections can misclassify it as
+  retained-custody corruption. Reuse the existing issued lifecycle successor;
+  empty/oversized input, unknown stages and downstream identity/effect checks
+  remain strict. Never repair proposal bytes or rerun settled work implicitly.
+
+  Keep the native hook's per-call deadline out of project-check input identity so
+  VERIFY can accept unchanged passed checks across ordinary CLI and hook calls.
+  Continue to invalidate evidence when application environment, files, policy or
+  physical receipts change.
+
+  Check retained process birth after a permission-denied existence probe, so a
+  reused macOS system PID cannot keep an already closed agent scope unresolved.
+  Unknown identity remains conservative and foreign processes are never signaled.
+
+  Validate a current completed correction wave as one synchronous SQL snapshot,
+  sharing private successful proofs across its registration and settled histories.
+  Fresh traversals, failures, allocation fences and physical file checks remain
+  independent; no proof is reused across commands or asynchronous boundaries.
+
+- 481702b: Keep native hook admission within its qualified shared deadline without loading execution/recovery graphs. Retain matched late native terminal outcomes before shutdown, support AGY ordered stream request evidence and recovered lifecycle boundaries, and publish exact current instruction packets as readable Markdown without replaying committed lifecycle operations.
+
+  Distinguish repeated real checksum scans from duplicate progress notifications. Retry only effect-free physical self-start observations within the existing owner-bound startup horizon, without relaunching processes or renewing unconfirmed leases.
+
+  Allow an initially bound maintenance cancellation signal to drain its owned heartbeat transport during daemon shutdown.
+
+  Retain startup failures only for the exact physical owner, preventing duplicate workers from overwriting or cleaning up a winner. Keep setup progress distinct across owned CLI producers without admitting stale or duplicate notifications.
+
 ## 0.9.0-beta.144
 
 ### Patch Changes

package/README.md

@@ -161,6 +161,8 @@ dd-flow canon status --json
 
 `canon resolve` checks explicit `--root`, then `DD_MEMORYBANK`, then the globally registered value in `DD_FLOW_HOME`, then known nearby `dd-memorybank` checkouts from the current working directory. If two different valid canonical roots are discovered, it fails closed with structured blockers and bootstrap hints. Use `DD_MEMORYBANK` for the local canonical `dd-memorybank` checkout.
 
+With no explicit, environment or registered source, the release installed by `setup` in `DD_FLOW_HOME` takes precedence over nearby checkouts. Archive provenance comes from its retained release manifest. A degraded installation does not silently fall back to a local checkout. Discovery remains read-only and does not open SQLite before runtime context admission.
+
 Register a project:
 
 ```bash
@@ -508,22 +510,25 @@ remain invalid and receive a standalone retry.
 
 ## Verification
 
-Local verification for this repository:
+For a code merge, start with the cheap common contracts, then select affected
+storage/process/flow checks explicitly and record the selection reason:
 
 ```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
+pnpm gate:merge
 ```
 
-Build once before testing: release contracts and native fixtures verify the
-copied `dist` bytes. `pnpm test` remains release → integration → runtime-sensitive.
+For release acceptance, freeze source/canon, build once, then use
+`DD_FLOW_GATE_REPORT_ROOT=/absolute/external/report pnpm gate:release`.
+Node family selection lives in `package.json`, Vitest membership in
+`vitest.config.ts`, and required release receipts in `scripts/release-candidate.mjs`.
+The local and CI profiles cover the same required guarantees; qualification-only
+cases report their prerequisites/skips separately. Tests invoking compiled CLI
+must use the current frozen build, even for a partial merge check.
 For development use `pnpm test:fast`, `pnpm test:core` or `pnpm test:flow` plus
 the affected native contracts; these subsets are not full acceptance.
 New files default to serial core execution. A forced serial fallback is
 `pnpm test:integration --no-file-parallelism --maxWorkers=1`.
-The [test-suite verification runbook](https://github.com/deksden-com/dd-eval/blob/docs/066-test-suite-optimization/runbooks/flow-test-suite-verification.md)
+The [test-suite verification runbook](https://github.com/deksden-com/dd-eval/blob/main/runbooks/flow-test-suite-verification.md)
 owns group qualification, complete reports and cross-repository commands.
 
 Manual smoke checks should use a temporary `DD_FLOW_HOME` when they do not intentionally inspect the operator's real local state.

package/dist/build-info.json

@@ -1,15 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.144",
-  "cli_commit": "fc729af5d6f9865bab178e40b34dd9b0a99a0318",
-  "built_at": "2026-10-20T05:55:05.754Z",
+  "cli_version": "0.9.0-beta.149",
+  "cli_commit": "7d17167f768483ffdb5d37f64cc385035c7d4658",
+  "built_at": "2026-10-24T10:44:58.080Z",
   "built_with_canon": {
     "version": "4.1.2",
-    "commit": "a1cfe8b06329c691c314064b6ea6a3da6628cceb",
+    "commit": "925ef10ecc0b683f7feba6f74913e15560842500",
     "flow_contract": "dd-flow-canonical-2026-08",
-    "repo_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-canon-plan092",
-    "memorybank_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-canon-plan092/.memory-bank",
-    "flow_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-canon-plan092/.memory-bank/dd-flow",
+    "repo_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-canon-release146",
+    "memorybank_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-canon-release146/.memory-bank",
+    "flow_root": "/Users/deksden/Documents/_Projects/_worktrees/dd-canon-release146/.memory-bank/dd-flow",
     "layout": "dot_memory_bank"
   }
 }

package/dist/cli/command-inputs.js

@@ -15,7 +15,8 @@ const control = "project-root run";
 const protocolTransitionInput = route(1, "to", `${scoped} payload-file json-file reason`, "force");
 const setupInput = route(0, "request-id trust-file", "canon-source canon-version release-registry channel profile profile-file save-profile-intent", "non-interactive skip-agent-setup", "", { channel: ["stable", "preview", "development"] });
 const memoryInitInput = route(0, "project-root workspace-root request-id", "intake-file intake-sha256 profile profile-file stage-profile work-profile max-parallel delegation native-config-home git-route integration-branch", "detach non-interactive prepare-only allow-live-probe", "stage-profile work-profile", { "git-route": ["integration_branch_direct", "feature_worktree"], delegation: ["external", "native"] });
-export const commandAliases = { transition: "protocol transition", init: "flow mb-init" };
+const diagnosticInput = route(0, "project-root request-id", "intake-file profile profile-file stage-profile work-profile max-parallel", "detach non-interactive prepare-only", "stage-profile work-profile");
+export const commandAliases = { transition: "protocol transition", init: "flow mb-init", upgrade: "flow mb-upgrade", review: "flow project-review" };
 /** Path-shaped arguments default to physical paths unless the route explicitly
  * opts into contextualPaths. This inventory does not expand arbitrary strings. */
 export const physicalPathOptions = new Set(words("canon-source trust-file root project-root workspace-root workspace-path workspace-path path dir file schema-dir output result-file semantic-file data decision-file verification-file reason-file task-file intake-file context-file observations-file observation-file summary-file question-file answer-file payload-file json-file task-profile-file execution-routing-file protocol-override-file manifest-file routing-file config-file input-file report-file snapshot-file output-dir state-dir capture-root capture-path destination source archive snapshot plan-file backup-path database backup source-home target-home stdout stderr adapter-executable memory-bank flow stage-report dashboard report"));
@@ -33,8 +34,15 @@ export const commandInputs = {
     "flow show": route(1),
     "flow mb-init": memoryInitInput,
     "init": memoryInitInput,
-    "runtime storage admit": route(0, "operation", "", "", "", { operation: ["memory-init"] }),
-    "runtime flow admit": route(0, "operation", "", "", "", { operation: ["memory-init"] }),
+    "flow mb-upgrade": memoryInitInput,
+    "upgrade": memoryInitInput,
+    "flow mb-audit": diagnosticInput,
+    "flow project-review": diagnosticInput,
+    "review": diagnosticInput,
+    "runtime storage admit": route(0, "operation", "", "", "", { operation: ["memory-init", "memory-upgrade"] }),
+    "runtime storage qualify": route(0, "operation", "", "", "", { operation: ["memory-upgrade"] }),
+    "runtime storage transition": route(0, "action project-root workspace-root request-id selection-sha256", "expected-sha256 recovery-id", "offline", "", { action: ["plan", "apply", "status", "recovery-plan", "recover", "recovery-status"] }),
+    "runtime flow admit": route(0, "operation", "", "", "", { operation: ["memory-init", "memory-upgrade", "mb-audit", "project-review"] }),
     "completion bash": route(0),
     "completion zsh": route(0),
     "completion fish": route(0),
@@ -218,6 +226,7 @@ export const commandInputs = {
     "canon status": route(0, "", "root"),
     "canon resolve": route(0, "", "root"),
     "migration impact": route(0, project, "target-version mode"),
+    "migration readiness": route(0, `${project} workspace-root request-id`),
     "migration plan": route(0, project, "source-version target-version run backup-path backup-created-at"),
     "migration report": route(0, project, "source-version target-version run backup-path backup-created-at"),
     "migration verify": route(0, "file"),
@@ -265,6 +274,7 @@ export const commandInputs = {
     "schema validate": { ...route(0, "schema file", "schema-dir project-root run"), contextualPaths: words("project-root file") },
     "memory permissions preflight": route(0, "root memory-bank flow mode", "tasks"),
     "memory compose register": route(0, "project-root run request-key result-file"),
+    "memory upgrade publish": route(0, "project-root run"),
     "memory verify checks": route(0, "project-root run"),
     "memory review register": route(0, "project-root run"),
     "memory review collect": route(0, "project-root run"),

package/dist/cli/command-metadata.js

@@ -1,4 +1,4 @@
-import { commandInputs, physicalPathOptions } from "./command-inputs.js";
+import { commandInputs, commandAliases, physicalPathOptions } from "./command-inputs.js";
 import { runtimeOptionDescriptions } from "./command-option-descriptions.js";
 const optionDescriptions = {
     "intake-sha256": "SHA-256 of the exact original intake file bytes. Fresh execution verifies the bytes; replay compares the retained hash without reopening the original file.",
@@ -61,10 +61,27 @@ const memoryInitOptions = {
     "non-interactive": "Never open the first-flow executor dialog, even on a terminal. Without an explicit profile/file or configured default, refuse before project effects; init cannot skip its executor."
 };
 const commandOptionDescriptions = {
+    "flow mb-audit": {
+        "project-root": "Canonical absolute project identity. The runtime creates an isolated read-only source snapshot; neither the project nor its Memory Bank is a write destination.",
+        "intake-file": "Bounded UTF-8 original diagnostic request, including audit mode/focus and constraints. Required for a fresh request; optional on exact replay, where supplied bytes must match.",
+        "stage-profile": "Repeatable preflight/audit/review/report=profile override. Each stage may occur once and all profiles are frozen before dispatch.",
+        "prepare-only": "Retain the request, source snapshot and RUN without starting its controller or provider Sessions. Runtime state is created; this is not a dry run.",
+        "max-parallel": "External Work concurrency from 1 to 64; default 1. Never claims native child qualification."
+    },
+    "flow project-review": {
+        "project-root": "Canonical absolute project identity, assessed through an isolated read-only snapshot. Findings never authorize implicit repair.",
+        "intake-file": "Bounded UTF-8 original project-conformance review request and focus. Required fresh; supplied replay bytes must match the retained objective.",
+        "stage-profile": "Repeatable preflight/analyze/review/report=profile override. This is project review, not the SDLC CODE-REVIEW stage.",
+        "prepare-only": "Retain the request, source snapshot and RUN without launching a controller or provider Sessions. Not a dry run.",
+        "max-parallel": "External Work concurrency from 1 to 64; default 1."
+    },
     "flow mb-init": memoryInitOptions,
     init: memoryInitOptions,
-    "runtime storage admit": { operation: "Operation-specific writable-connection admission: memory-init only. Requires explicit canonical DD_FLOW_HOME and an existing compatible resource registry. Never initializes, migrates, repairs or starts agents." },
-    "runtime flow admit": { operation: "Memory-init handler admission in the executing engine. Reads bounded UTF-8 JSON stdin with source and source_sha256; optional startup_input_schema additionally requires support by this engine's startup reader. Validates the exact six-stage descriptor using actual registered handlers. Does not establish release trust, storage/provider readiness or semantic completion, and never creates Home, RUN or agents." },
+    "flow mb-upgrade": { ...memoryInitOptions, "stage-profile": "Repeatable stage=profile assignment for preflight, diff-analysis, upgrade, verify, review or finish. The original selection is frozen before dispatch.", "prepare-only": "Prepare or replay the upgrade RUN and accepted storage/bootstrap selection without launching its controller or a productive Session. This is not a dry run; it does not publish the upgraded canonical layer or accept semantic preservation." },
+    upgrade: { ...memoryInitOptions, "stage-profile": "Repeatable stage=profile assignment for preflight, diff-analysis, upgrade, verify, review or finish. The original selection is frozen before dispatch.", "prepare-only": "Prepare or replay the upgrade RUN and accepted storage/bootstrap selection without launching its controller or a productive Session. This is not a dry run; it does not publish the upgraded canonical layer or accept semantic preservation." },
+    "runtime storage admit": { operation: "Operation-specific writable-connection admission: memory-init or memory-upgrade. Upgrade also checks retained request storage. Requires explicit canonical DD_FLOW_HOME and an existing compatible resource registry. Never initializes, migrates, repairs or starts agents." },
+    "runtime storage qualify": { operation: "memory-upgrade only. Qualify the selected engine before a native probe. Incompatible drained stores are copied privately with committed WAL; the actual transition and operation admission run on those copies. Requires both explicit canonical Homes. Never migrates real stores, grants productive admission, creates a RUN or starts agents." },
+    "runtime flow admit": { operation: "Handler admission for memory-init or memory-upgrade in the executing engine. Reads bounded UTF-8 JSON stdin with source and source_sha256; memory-init additionally accepts startup_input_schema to require its startup reader. Validates the matching six-stage descriptor using actual registered handlers. Does not establish release trust, storage/provider readiness or semantic completion, and never creates Home, RUN or agents." },
     "profiles create": { file: "Regular UTF-8 JSON file containing one complete validated agent profile. The ID must be unused. Credentials and unknown fields are refused; creation uses --expected-revision and never starts a model Turn." },
     "profiles edit": { file: "Regular UTF-8 JSON file containing the complete replacement agent profile, not a patch. Its ID must already exist. Revision conflicts refuse the edit; retained RUN snapshots are unchanged." },
     "profiles alias": {
@@ -79,6 +96,11 @@ const commandOptionDescriptions = {
     },
     "schema validate": { file: "JSON document to validate against --schema in the selected schema directory. Validation does not execute a flow or accept semantic completion." },
     "migration verify": { file: "Existing dd-flow/mb-upgrade-migration-report@1 JSON report to verify against migration evidence; verification does not apply a storage migration." },
+    "migration readiness": {
+        "request-id": "Stable upgrade request ID. Retains a physically verified content-only storage proof; identical replay reuses it and changed inputs refuse. Does not create a RUN, sync content or migrate stores.",
+        "workspace-root": "Existing canonical absolute assigned workspace. Recorded with the project and request; this storage-only operation does not establish Git/workspace eligibility for the full upgrade.",
+        "project-root": "Registered active project requiring a complete release-impact chain and valid current provenance. Existing compatible run/resource stores are mandatory; this command never initializes or repairs them. Explicit mb-upgrade mode is required."
+    },
     "migration apply": { file: "Explicit migration report JSON file used for admission to the requested apply operation; backup and ownership gates remain mandatory." },
     "prompt render": { profile: "Prompt profile name required by the assigned Work execution context; not an operator executor profile ID or a Codex home profile." },
     "runtime process register": { harness: "Harness family associated with the registered process/budget; registration is not a discovery or doctor probe.", "state-dir": "Adapter runtime state directory retained with the physical process for later ownership/admission checks." },
@@ -105,17 +127,28 @@ const commandOptionDescriptions = {
     "run control resume": { from: "Exact retained pause/stop control ID whose captured state authorizes this resume request; not a snapshot path." },
     "stage block": { kind: "Blocker category: engine, harness or environment; code and summary identify the actionable cause." },
     "migration impact": { mode: "Optional full_migration request forces the strict full-migration assessment; otherwise impact evidence determines patch, targeted_minor or full_migration." },
+    "runtime storage transition": {
+        "selection-sha256": "Exact independently retained full upgrade selection; checked before any storage effect. Commands issued by the selected engine include this value.",
+        action: "Selected frozen engine transport: plan retains the pair; apply performs its explicit cutover; status observes it. recovery-plan selects and fences separate recovery; recover executes it; recovery-status observes recovery. No command starts a model or RUN.",
+        "expected-sha256": "Exact retained migration request SHA for apply/status/recovery-plan, or retained recovery request SHA for recover/recovery-status. Not a fresh selector or permission to replace a request.",
+        "recovery-id": "Explicit recovery identity (1..86 safe ASCII characters); required only for recovery-plan. Recovery aborts the original apply.",
+        offline: "Required for apply, recovery-plan and recover after all local/external writers are drained. The engine independently checks registered logical and physical owners; it never kills them.",
+        "project-root": "Original retained upgrade project identity. No project or database is initialized by this transport.",
+        "workspace-root": "Original assigned upgrade workspace; must match the frozen request.",
+        "request-id": "Original upgrade request identity; the engine and migration files come only from that request."
+    },
     "memory permissions preflight": { mode: "Permission contour to check: read, write, repair or report_only; write checks may create temporary permission probes.", flow: "Workflow permission contour: mb-init, mb-upgrade, mb-audit, mb-fix, mb-upgrade-review or custom. Not a filesystem path." },
-    "memory compose register": { "run": "Active registered mb-init RUN whose accepted discovery and immutable execution bind the composition graph.", "request-key": "Stable composition registration identity; exact replay retains the original Work graph.", "result-file": "Bounded proposed composition JSON. Bytes are prepared before registration; agent fields do not grant Work or write authority." },
-    "memory verify checks": { "run": "Active registered mb-init RUN. Execute only its independently selected declared verification checks." },
-    "memory review register": { "run": "Active registered mb-init RUN with accepted verification. Register initial independent reviewers; this does not launch providers." },
-    "memory review collect": { "run": "Active registered mb-init RUN. Collect genuine registered initial-wave results without accepting the Stage or granting correction authority." },
-    "memory finish evidence": { "run": "Active registered mb-init finish RUN. Publish independently prepared coverage, integration and readiness evidence; publication does not complete Stage or RUN." },
-    "memory finish integrate": { "run": "Active mb-init finish RUN. Commit only accepted Memory Bank and owned lint files under retained Git policy, then integrate the admitted workspace locally. Preserve unrelated staged/dirty files; never push. Lost-response replay observes the original effects without another commit." },
-    "memory corrections register": { run: "Active registered mb-init review RUN. Register only the correction plan bound to the independently retained preceding review.", wave: "Correction wave 1 follows initial review; wave 2 requires settled first selective review. A third wave is unsupported.", "result-file": "Bounded correction-plan JSON prepared before graph registration; exact retained replay cannot substitute another plan." },
-    "memory corrections checks": { run: "Active registered mb-init review RUN with a genuinely settled correction view.", wave: "Run only the independently selected finite check profile for correction wave 1 or 2; this does not accept semantic quality." },
-    "memory review selective-register": { run: "Active registered mb-init review RUN. Allocate selective reviewers only after their wave's committed checks.", wave: "Select correction wave 1 or 2. Unaffected accepted units remain retained; registration does not launch providers." },
-    "memory review selective-collect": { run: "Active registered mb-init review RUN. Return genuine selective reviewer references, not Stage or RUN acceptance.", wave: "Select independently registered review of correction wave 1 or 2; missing wave custody never falls back to initial review." },
+    "memory compose register": { "run": "Active mb-init or mb-upgrade RUN whose accepted discovery/diff-analysis and immutable execution bind the composition graph.", "request-key": "Stable composition registration identity; exact replay retains the original Work graph.", "result-file": "Bounded proposed composition JSON. Bytes are prepared before registration; agent fields do not grant Work or write authority." },
+    "memory upgrade publish": { run: "Active mb-upgrade authoring Stage with a registered blueprint and settled Work. Apply only its retained canonical publication plan and recovery archive; this does not accept the Stage or complete the RUN." },
+    "memory verify checks": { "run": "Active mb-init or mb-upgrade RUN. Execute only its independently selected declared verification checks." },
+    "memory review register": { "run": "Active mb-init or mb-upgrade RUN with accepted verification. Register initial independent reviewers; this does not launch providers." },
+    "memory review collect": { "run": "Active mb-init or mb-upgrade RUN. Collect genuine registered initial-wave results without accepting the Stage or granting correction authority." },
+    "memory finish evidence": { "run": "Active mb-init or mb-upgrade finish RUN. Publish independently prepared coverage, integration and readiness evidence; publication does not complete Stage or RUN." },
+    "memory finish integrate": { "run": "Active mb-init or mb-upgrade finish RUN. Commit only accepted Memory Bank and owned lint files under retained Git policy, then integrate the admitted workspace locally. Preserve unrelated staged/dirty files; never push. Lost-response replay observes the original effects without another commit." },
+    "memory corrections register": { run: "Active mb-init or mb-upgrade review RUN. Register only the correction plan bound to the independently retained preceding review.", wave: "Correction wave 1 follows initial review; wave 2 requires settled first selective review. A third wave is unsupported.", "result-file": "Bounded correction-plan JSON prepared before graph registration; exact retained replay cannot substitute another plan." },
+    "memory corrections checks": { run: "Active mb-init or mb-upgrade review RUN with a genuinely settled correction view.", wave: "Run only the independently selected finite check profile for correction wave 1 or 2; this does not accept semantic quality." },
+    "memory review selective-register": { run: "Active mb-init or mb-upgrade review RUN. Allocate selective reviewers only after their wave's committed checks.", wave: "Select correction wave 1 or 2. Unaffected accepted units remain retained; registration does not launch providers." },
+    "memory review selective-collect": { run: "Active mb-init or mb-upgrade review RUN. Return genuine selective reviewer references, not Stage or RUN acceptance.", wave: "Select independently registered review of correction wave 1 or 2; missing wave custody never falls back to initial review." },
     "memory repair baseline": { ...memoryRepairOptions, work: "Register the immutable prelaunch baseline for this repair Work; dependent/peer changes require explicit current-view registration first. Does not launch providers." },
     "memory repair copy-reserve": { ...memoryRepairOptions, work: "Reserve the owned private copy for this repair Work after its committed baseline; reservation does not create the copy or launch providers." },
     "memory repair copy-materialize": { ...memoryRepairOptions, work: "Materialize the reserved private copy for this repair Work with retained build/ready receipts; no provider launch or shared document publication." },
@@ -143,7 +176,8 @@ export function optionsForCommand(input, command) {
     }));
 }
 function optionDescription(name, command) {
-    const description = (command ? commandOptionDescriptions[command]?.[name] : undefined) ?? optionDescriptions[name] ?? runtimeOptionDescriptions[name];
+    const description = (command ? commandOptionDescriptions[command]?.[name]
+        ?? commandOptionDescriptions[commandAliases[command] ?? command]?.[name] : undefined) ?? optionDescriptions[name] ?? runtimeOptionDescriptions[name];
     if (!description)
         throw new Error(`Missing CLI option documentation: ${command ?? "inventory"} --${name}`);
     return description;
@@ -162,8 +196,9 @@ export function optionsForCommandTree(command) {
 /** One exact native routing classification shared by router and compatibility admission. */
 export function routerNativeRoute(key) {
     return key === "version" || key.startsWith("engine ") || key === "schema validate"
-        || key === "flow list" || key === "flow show" || key === "flow mb-init" || key === "init"
-        || key === "run reconcile" || key === "runtime storage admit"
+        || key === "flow list" || key === "flow show" || key === "flow mb-init" || key === "init" || key === "flow mb-upgrade" || key === "upgrade"
+        || key === "flow mb-audit" || key === "flow project-review" || key === "review"
+        || key === "run reconcile" || key === "runtime storage admit" || key === "runtime storage qualify" || key === "runtime storage transition"
         || key === "runtime flow admit"
         || key.startsWith("profiles ") || key.startsWith("models ") || key.startsWith("harnesses ") || key.startsWith("completion ") || key === "setup" || key.startsWith("setup ")
         || key === "storage migrate-writer" || key === "codex hook handle"

package/dist/cli/diagnostic-invocation.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { diagnosticFlowStages } from "../domain/diagnostic-flows.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+function refuse(message) { throw new AppError("usage", message, 2, { effect: "no_effect" }); }
+/** Parser only: no files, operator settings, project mutation or runtime state. */
+export function prepareDiagnosticInvocation(args) {
+    const route = prepareCommandRoute(args), options = route.parsed.options;
+    const flowId = route.key === "flow mb-audit" ? "mb-audit"
+        : ["review", "flow project-review"].includes(route.key) ? "project-review" : refuse("Use flow mb-audit or review / flow project-review");
+    const value = (key) => options.get(key)?.[0];
+    const projectRoot = value("project-root"), requestId = value("request-id");
+    if (!path.isAbsolute(projectRoot) || path.resolve(projectRoot) !== projectRoot
+        || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuse("Use a canonical absolute project root and a bounded request ID");
+    if (value("profile") && value("profile-file"))
+        refuse("Use either --profile or --profile-file");
+    if (options.has("detach") && options.has("prepare-only"))
+        refuse("--detach and --prepare-only are exclusive");
+    const execution = {};
+    if (value("profile"))
+        execution.rootProfile = value("profile");
+    const stageProfiles = {};
+    for (const assignment of options.get("stage-profile") ?? []) {
+        const match = /^([^=]+)=([^=]+)$/.exec(assignment);
+        if (!match || !diagnosticFlowStages[flowId].includes(match[1]) || Object.hasOwn(stageProfiles, match[1]))
+            refuse("--stage-profile requires one known stage=profile assignment per stage");
+        stageProfiles[match[1]] = match[2];
+    }
+    if (Object.keys(stageProfiles).length)
+        execution.stageProfiles = stageProfiles;
+    const workProfiles = options.get("work-profile");
+    if (workProfiles) {
+        if (workProfiles.some(id => !id.trim()) || new Set(workProfiles).size !== workProfiles.length)
+            refuse("Work profiles must be nonempty and unique");
+        execution.workProfiles = [...workProfiles];
+    }
+    if (value("max-parallel") !== undefined) {
+        const raw = value("max-parallel"), n = Number(raw);
+        if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(n) || n > 64)
+            refuse("--max-parallel must be an integer from 1 to 64");
+        execution.delegation = { mode: "external", max_parallel: n };
+    }
+    return { scope: { projectRoot, requestId, flowId }, execution, profileFile: value("profile-file"), intakeFile: value("intake-file"),
+        detach: options.has("detach"), prepareOnly: options.has("prepare-only"), nonInteractive: options.has("non-interactive") };
+}

package/dist/cli/diagnostic.js

@@ -0,0 +1,120 @@
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { resolveDdFlowHome, resolveProjectRoot } from "../storage/paths.js";
+import { readSetupStatus } from "../services/setup.js";
+import { PreparedInstalledFlowSource } from "../services/installed-flow-source.js";
+import { selectMemoryInitInstalledEngine } from "../services/memory-init-engine-release.js";
+import { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+import { FrozenGenericExecution } from "../services/generic-execution.js";
+import { openMemoryInitStores } from "../services/memory-init-stores.js";
+import { registerProject, requireProjectByRoot } from "../services/projects.js";
+import { diagnosticSnapshotRoot } from "../services/diagnostic-snapshot.js";
+import { readDiagnosticRequest, retainDiagnosticRequest, startDiagnosticRun } from "../services/diagnostic-start.js";
+import { readFlowRunExecutionBundle } from "../services/runs.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { onboardExecutor } from "../services/executor-onboarding.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { prepareDiagnosticInvocation } from "./diagnostic-invocation.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination } from "./response-file.js";
+import { prepareFileBytes } from "./input-preparation.js";
+import { writePreparationError } from "./error-output.js";
+import { launchAndObserveMemoryFlow } from "./memory-init.js";
+import { publishSetup } from "../harness-runtime/lib/setup-progress.mjs";
+export async function runDiagnosticCli(args, env = process.env, io = process) {
+    let context, effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareDiagnosticInvocation(output.args), home = resolveDdFlowHome(env);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const scope = invocation.scope;
+        if (resolveProjectRoot(scope.projectRoot) !== scope.projectRoot)
+            throw new AppError("usage", "Project root must be canonical", 2, { effect: "no_effect" });
+        const reader = createContext(env, "read_existing");
+        let retained = null;
+        try {
+            const project = reader.db.get("SELECT status FROM projects WHERE root=?", [scope.projectRoot]);
+            if (project?.status && project.status !== "active")
+                throw new AppError("diagnostic_project_inactive", "Activate the selected project explicitly before diagnosis", 2, { effect: "no_effect" });
+            if (project)
+                retained = readDiagnosticRequest(reader, scope);
+        }
+        finally {
+            reader.db.close?.();
+        }
+        if (invocation.profileFile)
+            invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+        const readIntake = () => {
+            if (!invocation.intakeFile)
+                throw new AppError("usage", "Fresh diagnosis requires --intake-file with the requested focus and constraints", 2, { effect: "no_effect" });
+            const bytes = prepareFileBytes(invocation.intakeFile, "diagnostic intake", 64 * 1024).bytes;
+            let text;
+            try {
+                text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+            }
+            catch {
+                throw new AppError("usage", "Diagnostic intake must be UTF-8", 2, { effect: "no_effect" });
+            }
+            if (!text.trim())
+                throw new AppError("usage", "Diagnostic intake cannot be empty", 2, { effect: "no_effect" });
+            return text;
+        };
+        if (retained) {
+            if (Object.entries(invocation.execution).some(([key, value]) => !Object.hasOwn(retained.selection, key) || hybridDigest(value) !== hybridDigest(retained.selection[key]))
+                || invocation.intakeFile && readIntake() !== retained.objective)
+                throw new AppError("diagnostic_request_conflict", "Supplied selectors differ from the original diagnostic request", 2, { effect: "no_effect" });
+        }
+        const objective = retained?.objective ?? readIntake();
+        let source, engine;
+        let rootProfile = invocation.execution.rootProfile;
+        if (!retained) {
+            const setup = readSetupStatus(home), installation = setup.installation;
+            if (!installation || setup.installation_readiness !== "installed")
+                throw new AppError("diagnostic_setup_required", "Install the desired canon and CLI with setup before diagnosis", 2, { effect: "no_effect" });
+            publishSetup("dependency_check_completed", "diagnostic:installation");
+            source = PreparedInstalledFlowSource.fromInstalledRelease(home, installation.manifest_sha256, scope.flowId);
+            publishSetup("dependency_check_completed", "diagnostic:canon");
+            engine = selectMemoryInitInstalledEngine(home, installation.manifest_sha256);
+            publishSetup("dependency_check_completed", "diagnostic:engine");
+            engine.admitDiagnosticFlow(source, scope.flowId);
+            publishSetup("dependency_check_completed", "diagnostic:handlers");
+            const stdin = io.stdin ?? process.stdin;
+            const selected = await onboardExecutor({ ...(typeof rootProfile === "string" ? { profileId: rootProfile } : {}),
+                ...(invocation.profileFile ? { profileFile: invocation.profileFile } : {}) }, () => readOperatorProfiles(home), { allowSkip: false, nonInteractive: invocation.nonInteractive || output.json || output.progressJsonl
+                    || !stdin.isTTY || !io.stderr.isTTY }, settings => askExecutorChoice(settings, { stdin, stderr: io.stderr }, { allowSave: false, allowSkip: false }));
+            if (!selected.profile)
+                throw new AppError("diagnostic_executor_required", "Select an executor profile before diagnosis", 2, { effect: "no_effect" });
+            rootProfile ??= selected.profile;
+        }
+        effects = true;
+        context = openMemoryInitStores(env, { scope: { projectRoot: scope.projectRoot, workspaceRoot: scope.projectRoot, requestId: scope.requestId },
+            selectionSha256: hybridDigest({ scope, objective, selection: retained?.selection ?? invocation.execution }) }).context;
+        publishSetup("dependency_check_completed", "diagnostic:stores");
+        registerProject(context, { root: scope.projectRoot });
+        if (!retained) {
+            const project = requireProjectByRoot(context, scope.projectRoot);
+            const workspace = diagnosticSnapshotRoot(context, { projectId: project.id, projectRoot: scope.projectRoot, sourceRoot: scope.projectRoot,
+                requestId: scope.requestId, flowId: scope.flowId });
+            const execution = FrozenGenericExecution.prepare(source.resolveRegisteredFlow(), readOperatorProfiles(home), {
+                ...invocation.execution, ...(rootProfile !== undefined ? { rootProfile } : {}), execution: "managed", stageSessionMode: "new_session",
+                delegation: invocation.execution.delegation ?? { mode: "external", max_parallel: 1 }
+            }, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspace });
+            retainDiagnosticRequest(context, { scope, source: source, execution, engine: engine, objective, selection: invocation.execution });
+        }
+        const started = startDiagnosticRun(context, scope), bundle = readFlowRunExecutionBundle(context, { projectRoot: scope.projectRoot, runId: started.runId });
+        if (!bundle)
+            throw new AppError("diagnostic_bundle_missing", "Restore the retained diagnostic bundle", 1, { effect: "committed" });
+        return await launchAndObserveMemoryFlow(context, { ...invocation,
+            scope: { projectRoot: scope.projectRoot, workspaceRoot: bundle.execution.snapshot().scope.workspace, requestId: scope.requestId } }, started, scope.flowId, output, env, io);
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: ["unknown", "committed", "partial"].includes(String(record.details.effect)) ? record.details.effect : "partial", next_action: "reconcile_exact_request" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        context?.db.close?.();
+    }
+}