@deksden-com/dd-flow-cli 0.9.0-beta.143 → 0.9.0-beta.145

package/dist/services/memory-layer.js

@@ -5,9 +5,14 @@ import { Ajv } from "ajv/dist/ajv.js";
 import semver from "semver";
 import { AppError } from "../shared/errors.js";
 import { hybridDigest } from "./hybrid-contracts.js";
-import { readSetupStatus } from "./setup.js";
+import { readSetupStatus, readCommittedCanonRelease } from "./setup.js";
 import { readBoundedReleaseFile } from "./release-source.js";
 import { normalizeFlowContract } from "../domain/flow-contract.js";
+import { inspectReleaseArchive } from "./release-archive.js";
+import { canonicalOnlyFlowNames } from "./version-status.js";
+export function isCanonicalOnlyMemoryPath(logical) {
+    return canonicalOnlyFlowNames.some(name => logical === `dd-flow/${name}` || logical.startsWith(`dd-flow/${name.slice(0, -3)}/`));
+}
 const rootFiles = ["README.md", "index.md", "compatibility.json", "flow-contract.json", "go.md", "f.md", "prime.md", "protocol.md",
     "protocol-implement.md", "plan.md", "code.md", "merge.md", "merge-start.md", "merge-stop.md", "release.md", "deploy.md", "publish.md",
     "review.md", "review-fix.md", "mb-audit.md", "mb-fix.md", "mb-lint.md", "interactive.md", "finish.md", "fix-def.md"];
@@ -112,7 +117,7 @@ export class PreparedMemoryLayer {
                 source_commit: installation.manifest.canon.commit, canon_version_at_source_commit: installation.manifest.canon.version,
                 flow_contract: contract.id, installed_at: installedAt, included_files: included,
                 file_hashes: Object.fromEntries(included.map(logical => [logical, hash(files.get(`dd-flow/${logical}`))])),
-                excluded_canonical_only_flows: ["mb-init.md", "mb-upgrade.md", "mb-distill.md"], generated_allow_patterns: [".generated/**"] };
+                excluded_canonical_only_flows: canonicalOnlyFlowNames, generated_allow_patterns: [".generated/**"] };
             const schema = JSON.parse(fs.readFileSync(new URL("../schemas/project-flow-pack-manifest.schema.json", import.meta.url), "utf8"));
             if (!new Ajv({ strict: false, validateFormats: false }).compile(schema)(manifest))
                 refuse("invalid_pack_manifest");
@@ -130,10 +135,69 @@ export class PreparedMemoryLayer {
         }
     }
     files() { return new Map([...this.#files].map(([logical, bytes]) => [logical, Buffer.from(bytes)])); }
+    /** Historical content baseline, not an executable target layer. Project
+     * paths select a subset; every byte/provenance fact comes from the committed
+     * setup canon. Old runtime compatibility and current installation defaults
+     * are irrelevant, and no release is activated or downloaded here.
+     */
+    static fromCommittedCanon(home, current, expectedInstallationSha256) {
+        if (!path.isAbsolute(home) || !current || !Array.isArray(current.included_files) || current.included_files.length > 20_000
+            || typeof current.installed_at !== "string" || !current.installed_at || current.installed_at.length > 256)
+            refuse("invalid_baseline_selection");
+        const installation = readCommittedCanonRelease(home, current.canon_version_at_source_commit, current.source_commit, expectedInstallationSha256);
+        if (!installation)
+            return null;
+        const archive = inspectReleaseArchive(installation.manifest.canon.archive, readBoundedReleaseFile(path.join(path.dirname(installation.canon_root), "archive.tgz"), installation.manifest.canon.archive.bytes));
+        const roots = [...new Set(archive.map(entry => entry.path.split("/")[0]))];
+        if (roots.length !== 1)
+            refuse("ambiguous_archive_root");
+        const prefix = archive.some(entry => entry.path.startsWith(`${roots[0]}/.memory-bank/`)) ? `${roots[0]}/.memory-bank` : roots[0];
+        const canonRoot = path.join(installation.canon_root, roots[0]), memoryRoot = path.join(installation.canon_root, prefix);
+        const sourceFiles = new Map(archive.filter(entry => entry.kind === "file").map(entry => [entry.path, entry.bytes]));
+        const files = new Map(), folded = new Set();
+        let total = 0;
+        const put = (logical, content) => {
+            if (!/^(?:dd-flow|mbb)\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(logical)
+                || content.length > 1024 * 1024 || files.size >= 20_000 || (total += content.length) > 64 * 1024 * 1024
+                || folded.has(logical.toLowerCase()))
+                refuse("unsafe_or_unbounded_baseline");
+            folded.add(logical.toLowerCase());
+            files.set(logical, Buffer.from(content));
+        };
+        const flowRoot = path.join(memoryRoot, "dd-flow");
+        for (const logical of [...new Set(current.included_files)].sort()) {
+            if (typeof logical !== "string" || !/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(logical)
+                || logical.split("/").some(part => [".", ".."].includes(part)))
+                refuse("unsafe_baseline_path");
+            if (logical === "manifest.json")
+                continue;
+            const content = sourceFiles.get(`${prefix}/dd-flow/${logical}`);
+            if (content)
+                put(`dd-flow/${logical}`, content);
+        }
+        const included = [...files.keys()].map(logical => logical.slice("dd-flow/".length));
+        if (!included.length)
+            return null;
+        for (const [logical, content] of sourceFiles) {
+            const relative = logical.slice(prefix.length + 1);
+            if (logical.startsWith(`${prefix}/`) && (relative.startsWith("mbb/") || isCanonicalOnlyMemoryPath(relative)))
+                put(relative, content);
+        }
+        const manifestBytes = Buffer.from(JSON.stringify({ schema_id: "dd-flow/project-flow-pack-manifest@1",
+            pack_version: installation.manifest.canon.version, flow_origin_policy: "project_local_pack", canon_root: canonRoot,
+            canon_memory_bank_root: memoryRoot, canon_flow_root: flowRoot, source_commit: installation.manifest.canon.commit,
+            canon_version_at_source_commit: installation.manifest.canon.version, installed_at: current.installed_at,
+            included_files: included, file_hashes: Object.fromEntries(included.map(logical => [logical, hash(files.get(`dd-flow/${logical}`))])),
+            excluded_canonical_only_flows: canonicalOnlyFlowNames }));
+        if (files.size >= 20_000 || manifestBytes.length > 1024 * 1024 || total + manifestBytes.length > 64 * 1024 * 1024)
+            refuse("unsafe_or_unbounded_baseline");
+        files.set("dd-flow/manifest.json", manifestBytes);
+        return new PreparedMemoryLayer(new Map([...files].sort(([left], [right]) => left.localeCompare(right, "en"))), installation.manifest_sha256);
+    }
     /** Restore only with an independently retained hash of an already admitted layer.
      * SHA admission proves the original verified bytes; mutable installation sources are not read.
      */
-    static restoreRetained(files, expectedSha256, installationSha256) {
+    static restoreRetained(files, expectedSha256, installationSha256, allowEmpty = false) {
         if (!/^[a-f0-9]{64}$/.test(expectedSha256) || !/^[a-f0-9]{64}$/.test(installationSha256)
             || files.size < 1 || files.size > 20_000)
             refuse("invalid_retained_selection");
@@ -142,7 +206,7 @@ export class PreparedMemoryLayer {
         for (const [logical, content] of files) {
             if (!/^(?:mbb|dd-flow)\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(logical)
                 || logical.split("/").some(segment => segment === "." || segment === "..")
-                || folded.has(logical.toLowerCase()) || content.length < 1 || content.length > 1024 * 1024
+                || folded.has(logical.toLowerCase()) || !allowEmpty && content.length < 1 || content.length > 1024 * 1024
                 || (total += content.length) > 64 * 1024 * 1024)
                 refuse("unsafe_or_unbounded_inventory");
             folded.add(logical.toLowerCase());

package/dist/services/memory-lint-config.js

@@ -1,10 +1,101 @@
 import { AppError } from "../shared/errors.js";
+import { createHash } from "node:crypto";
+import { parseDocument } from "yaml";
+/** Source templates are assets, not instantiated project documents. A known
+ * canonical asset may retain customized placement or a fixed example date;
+ * its header must still be a template. A directory name grants no exemption. */
+export function memoryCanonicalTemplatePaths(entries, files, current) {
+    const result = new Set();
+    const placeholder = (value) => typeof value === "string" && /<[^>]+>/.test(value);
+    const header = (bytes) => {
+        const match = new TextDecoder("utf-8", { fatal: true }).decode(bytes).match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+        if (!match)
+            return null;
+        const document = parseDocument(match[1]);
+        return document.errors.length ? null : document.toJS();
+    };
+    for (const entry of entries) {
+        if (!/^mbb\/templates\/.+\.(?:md|markdown)$/.test(entry.path) || !entry.target || !["canonical", "local-customized"].includes(entry.ownership))
+            continue;
+        const target = files.get(entry.path);
+        if (!target || createHash("sha256").update(target).digest("hex") !== entry.target.sha256)
+            refuse("canonical_template_source_changed");
+        const bytes = current.get(entry.path);
+        if (!bytes)
+            continue;
+        try {
+            const source = header(target), observed = header(bytes);
+            if (source && observed && typeof observed.date === "string" && /^(?:YYYY-MM-DD|\d{4}-\d{2}-\d{2})$/.test(observed.date)
+                && ["file", "description", "purpose"].some(key => placeholder(source[key]) && placeholder(observed[key])))
+                result.add(`.memory-bank/${entry.path}`);
+        }
+        catch { /* Malformed headers remain active and are linted. */ }
+    }
+    return result;
+}
+/** A copied canonical guide may name its source repository's specs/protocols.
+ * Only those exact frozen relations are foreign provenance, not a promise that
+ * the consumer contains them. New project targets and body links stay checked. */
+export function memoryCanonicalLintExceptions(entries, files, selected) {
+    const result = [];
+    for (const file of new Set(selected)) {
+        if (!/^\.memory-bank\/(?:dd-flow|mbb)\/.+\.(?:md|markdown)$/.test(file))
+            continue;
+        if (["*", "?", "[", "]", "{", "}", "!", "(", ")", "\\"].some(character => file.includes(character)))
+            continue;
+        const logical = file.slice(13), entry = entries.find(entry => entry.path === logical);
+        if (!entry?.target || !["canonical", "local-customized"].includes(entry.ownership))
+            continue;
+        const bytes = files.get(logical);
+        if (!bytes || createHash("sha256").update(bytes).digest("hex") !== entry.target.sha256)
+            refuse("canonical_guidance_source_changed");
+        let header;
+        try {
+            const match = new TextDecoder("utf-8", { fatal: true }).decode(bytes).match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+            if (!match)
+                continue;
+            const document = parseDocument(match[1]);
+            if (document.errors.length)
+                continue;
+            const value = document.toJS();
+            if (!value || typeof value !== "object" || Array.isArray(value) || value.file !== file)
+                continue;
+            header = value;
+        }
+        catch {
+            continue;
+        }
+        const targets = new Set(["related_specs", "related_protocols"].flatMap(key => Array.isArray(header[key]) ? header[key] : [])
+            .filter((target) => typeof target === "string" && /^\.memory-bank\/(?:spec|protocol)\//.test(target)
+            && !["*", "?", "[", "]", "{", "}", "!", "(", ")"].some(character => target.includes(character))
+            && !target.includes("\\") && !target.includes("\0") && target.split("/").every(part => part && part !== "." && part !== "..")));
+        for (const target of targets)
+            result.push({ ruleId: "links/frontmatter-target-exists", file, target,
+                reason: "Source-canon spec/protocol provenance, not a required consumer-owned document; source resolution is not claimed." });
+    }
+    return result;
+}
+/** Pure ownership projection from retained inventory and accepted diff. Exact
+ * retained-only bytes keep their existing lint policy; they are preservation
+ * artifacts, not new authoring. Changed or semantic-work files stay protected.
+ * Mechanical canonical references remain verified by their publication owner. */
+export function memoryUpgradeLintGuidance(entries, changes) {
+    const authored = new Set(changes.filter(change => change.action === "semantic-work").map(change => change.to));
+    const retained = new Set(changes.filter(change => change.action === "retain" && change.from === change.to).map(change => change.from));
+    const preserved = entries.filter(entry => entry.current?.kind === "file" && /\.(?:md|markdown)$/.test(entry.path)
+        && retained.has(`.memory-bank/${entry.path}`) && !authored.has(`.memory-bank/${entry.path}`))
+        .map(entry => [`.memory-bank/${entry.path}`, entry.current.sha256]);
+    return new Map([...preserved, ...entries.filter(entry => entry.ownership === "canonical" && entry.target
+            && /^(?:dd-flow|mbb)\//.test(entry.path) && !authored.has(`.memory-bank/${entry.path}`))
+            .map(entry => [`.memory-bank/${entry.path}`, entry.target.sha256])]);
+}
 /** Review inputs also contain immutable guidance; only accepted current unit
  * artifacts are project output that lint configuration must not suppress. */
-export function memoryVerificationActivePaths(units, assignments = []) {
+export function memoryVerificationActivePaths(units, assignments = [], guidance, templates) {
     return [".memory-bank/index.md", ".memory-bank/structure.md", ".memory-bank/project-policy.md",
         ...units.flatMap(unit => (assignments.find(assignment => assignment.unit.id === unit.id)?.unit ?? unit).artifacts
-            .filter(artifact => artifact.root === "workspace").map(artifact => artifact.path))];
+            .filter(artifact => artifact.root === "workspace" && !templates?.has(artifact.path) && !(typeof artifact.sha256 === "string" && guidance?.get(artifact.path) === artifact.sha256))
+            .map(artifact => artifact.path))];
 }
 /** Bootstrap-owned policy for immutable guidance, never project knowledge or
  * the two project-owned JSON defaults beside the canonical flow pack. */
@@ -83,3 +174,21 @@ export function validateMemoryLintConfig(bytes, activePaths) {
             refuse("invalid_git_config");
     }
 }
+/** Preserve project lint policy, but independently check every active Markdown
+ * document it suppresses. JSON artifacts belong to their schema owners, not
+ * mb-lint's Markdown scanner. Invalid policy still refuses instead of fallback. */
+export function memoryVerificationSupplementalLintFiles(bytes, activePaths) {
+    validateMemoryLintConfig(bytes, []);
+    return [...new Set(activePaths)].filter(file => file.startsWith(".memory-bank/") && /\.(?:md|markdown)$/.test(file)).filter(file => {
+        try {
+            validateMemoryLintConfig(bytes, [file]);
+            return false;
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "memory_lint_config_invalid"
+                && ["active_document_ignored", "active_finding_suppressed"].includes(String(error.details.reason)))
+                return true;
+            throw error;
+        }
+    });
+}

package/dist/services/memory-native-review-copy.js

@@ -1,6 +1,5 @@
 import fs from "node:fs";
 import path from "node:path";
-import { createHash } from "node:crypto";
 import { AppError } from "../shared/errors.js";
 import { appendAudit } from "./audit.js";
 import { hybridDigest } from "./hybrid-contracts.js";
@@ -8,70 +7,9 @@ import { prepareMemoryReviewWorkInput, assertPreparedMemoryReviewWorkInput } fro
 import { assertRunMutationAllowed } from "./run-recovery-guard.js";
 import { reviewSourceFilter, reviewSourceHash, reviewExecutionCopyHash } from "./review-copy.js";
 import { writeReviewGitEvidence } from "./external-work-launch.js";
+import { memoryReviewPhysicalDestination } from "./hook-memory-routing.js";
 function refuse(reason) { throw new AppError("memory_native_review_copy_invalid", "Native Memory review requires an independently owned immutable execution copy", 1, { reason, effect: "no_effect" }); }
-function physicalDestination(runRoot, relative) {
-    if (fs.realpathSync(runRoot) !== path.resolve(runRoot) || !fs.lstatSync(runRoot).isDirectory())
-        refuse("noncanonical_run_root");
-    let current = runRoot;
-    for (const part of relative.split("/")) {
-        if (!part || part === "." || part === "..")
-            refuse("invalid_copy_path");
-        current = path.join(current, part);
-        const stat = fs.lstatSync(current, { throwIfNoEntry: false });
-        if (stat && !stat.isDirectory())
-            refuse("linked_or_non_directory_copy_path");
-        if (!stat)
-            break;
-    }
-}
-/** Routing is not fresh source admission: an already claimed reviewer retains
- * its committed private directory even after a later correction changes MB. */
-export function memoryNativeReviewAssignedHookCwd(context, input) {
-    const work = context.db.get("SELECT status,payload_json FROM works WHERE project_id=? AND run_id=? AND work_id=?", [input.projectId, input.runId, input.workId]);
-    const payload = JSON.parse(work?.payload_json ?? "null");
-    if (payload?.kind !== "memory-review" || payload.read_only !== true)
-        return null;
-    const ready = context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.native_review_copy_ready' AND json_extract(payload_json,'$.intent.run_id')=? AND json_extract(payload_json,'$.intent.work_id')=?", [input.projectId, input.runId, input.workId]);
-    if (!ready)
-        return null;
-    if (work?.status === "created") {
-        // Hook ingress routes an already allocated copy. Source admission belongs
-        // to the actual work-start owner, not a second physical graph in the Hook.
-        const generation = assertRunMutationAllowed(context, input.projectId, input.runId);
-        const run = context.db.get("SELECT run_root,run_dir FROM runs WHERE project_id=? AND id=?", [input.projectId, input.runId]);
-        if (!run)
-            refuse("owned_run_required");
-        const rows = (event) => context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND COALESCE(json_extract(payload_json,'$.run_id'),json_extract(payload_json,'$.intent.run_id'))=? AND COALESCE(json_extract(payload_json,'$.work_id'),json_extract(payload_json,'$.intent.work_id'))=? AND COALESCE(json_extract(payload_json,'$.generation'),json_extract(payload_json,'$.intent.generation'))=? LIMIT 2", [input.projectId, event, input.runId, input.workId, generation]);
-        const intents = rows("memory.native_review_copy_intent"), copies = rows("memory.native_review_copy_ready");
-        if (intents.length !== 1 || copies.length !== 1)
-            refuse("registered_copy_required");
-        const intent = JSON.parse(intents[0].payload_json), copy = JSON.parse(copies[0].payload_json);
-        const relative = `works/${input.workId}/native-review-workspaces/generation-${generation}`, runRoot = run.run_root ?? run.run_dir;
-        if (intent.schema_id !== "dd-flow/memory-native-review-copy@1" || intent.project_id !== input.projectId || intent.run_id !== input.runId
-            || intent.work_id !== input.workId || intent.generation !== generation || intent.root !== relative
-            || !/^[a-f0-9]{64}$/.test(intent.input_sha256) || !/^[a-f0-9]{64}$/.test(intent.source_sha256)
-            || hybridDigest(copy.intent) !== hybridDigest(intent) || !/^[a-f0-9]{64}$/.test(copy.sha256))
-            refuse("registered_copy_changed");
-        physicalDestination(runRoot, relative);
-        const root = path.join(runRoot, relative);
-        if (!fs.lstatSync(root, { throwIfNoEntry: false })?.isDirectory())
-            refuse("registered_copy_required");
-        return root;
-    }
-    const rows = context.db.all("SELECT ws.start_receipt_json,r.run_root,r.run_dir,s.cwd FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id JOIN runs r ON r.project_id=w.project_id AND r.id=w.run_id JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id WHERE w.project_id=? AND w.run_id=? AND w.work_id=? AND s.provider_session_id=? AND s.worker_id=w.work_id AND EXISTS(SELECT 1 FROM audit_events a WHERE a.project_id=w.project_id AND a.event_type='memory.native_review_binding' AND json_extract(a.payload_json,'$.work_session_id')=ws.id AND json_extract(a.payload_json,'$.run_id')=w.run_id AND json_extract(a.payload_json,'$.work_id')=w.work_id) LIMIT 2", [input.projectId, input.runId, input.workId, input.providerSessionId]);
-    if (rows.length !== 1)
-        refuse("registered_session_required");
-    const row = rows[0];
-    if (typeof row.start_receipt_json !== "string" || Buffer.byteLength(row.start_receipt_json) > 16 * 1024 * 1024)
-        refuse("registered_copy_required");
-    const receipt = JSON.parse(row.start_receipt_json), packet = JSON.parse(receipt.context);
-    const relative = `works/${input.workId}/native-review-workspaces/generation-${receipt.generation}`, root = path.join(row.run_root ?? row.run_dir, relative);
-    if (receipt.version !== 2 || createHash("sha256").update(receipt.context).digest("hex") !== receipt.context_sha256
-        || packet.work_id !== input.workId || packet.run_id !== input.runId || packet.workspace_root !== root
-        || packet.review_copy?.root !== relative || row.cwd !== root)
-        refuse("registered_copy_changed");
-    return root;
-}
+export { memoryNativeReviewAssignedHookCwd } from "./hook-memory-routing.js";
 /** Existing source/copy policy, separate native physical custody: no external
  * launch row is invented. An interrupted allocation is never overwritten. */
 export function prepareMemoryNativeReviewCopy(context, workId, allocate = false, preparedOwner) {
@@ -89,7 +27,7 @@ export function prepareMemoryNativeReviewCopy(context, workId, allocate = false,
         refuse("native_route_required");
     const relative = `works/${workId}/native-review-workspaces/generation-${generation}`;
     const runRoot = run.run_root ?? run.run_dir, root = path.join(runRoot, relative);
-    physicalDestination(runRoot, relative);
+    memoryReviewPhysicalDestination(runRoot, relative);
     const inputs = owner.input.run_inputs.filter(ref => ref.root === "workspace").map(ref => ref.path);
     const selectedBase = JSON.parse(run.index_json).workspace?.base;
     const base = selectedBase && selectedBase !== "unknown" ? selectedBase : "HEAD";
@@ -125,9 +63,9 @@ export function prepareMemoryNativeReviewCopy(context, workId, allocate = false,
         });
         try {
             fs.mkdirSync(path.dirname(root), { recursive: true, mode: 0o700 });
-            physicalDestination(runRoot, relative);
+            memoryReviewPhysicalDestination(runRoot, relative);
             fs.mkdirSync(root, { mode: 0o700 }); // Exclusive: never adopt an existing or partial destination.
-            physicalDestination(runRoot, relative);
+            memoryReviewPhysicalDestination(runRoot, relative);
             fs.cpSync(run.workspace_root, root, { recursive: true, verbatimSymlinks: true, force: false, errorOnExist: true, filter: reviewSourceFilter(run.workspace_root, inputs, base) });
             if (reviewSourceHash(run.workspace_root, inputs, base) !== intent.source_sha256
                 || reviewExecutionCopyHash(root, run.workspace_root, false, inputs, base) !== intent.source_sha256)

package/dist/services/memory-normal-flow-entry.js

@@ -9,6 +9,18 @@ import { prepareVnextSpecifyStart } from "./vnext-specify.js";
 import { loadVnextWorkspacePolicy } from "./vnext-workspace-policy.js";
 import { hybridDigest } from "./hybrid-contracts.js";
 const identity = [".memory-bank/index.md", ".memory-bank/structure.md", ".memory-bank/project-policy.md"];
+/** VERIFY diagnostics must remain reviewable when preparation fails. Neither
+ * outcome creates a future task or establishes provider access. */
+export function observeMemoryNormalFlowEntryDiagnostic(context, projectRoot) {
+    try {
+        return { status: "prepared", observation: observeMemoryNormalFlowEntry(context, projectRoot) };
+    }
+    catch (error) {
+        if (!(error instanceof AppError))
+            throw error;
+        return { status: "unavailable", error: { code: error.code, reason: error.details?.reason ?? null } };
+    }
+}
 function refuse(reason) {
     throw new AppError("memory_normal_flow_entry_invalid", "Ordinary SDLC entry cannot be prepared from initialized memory", 2, { reason, effect: "no_effect" });
 }

package/dist/services/memory-ordinary-defaults.js

@@ -28,7 +28,7 @@ function retainedUnbornBranch(context, workspace, scope) {
     return policy.integration_branch;
 }
 /** Project-owned technical defaults only; never grants authority to a future task. */
-export function prepareMemoryOrdinaryDefaults(context, workspace, selectedProfile, scope) {
+export function prepareMemoryOrdinaryDefaults(context, workspace, selectedProfile, scope, integrationBranch, targetFeatureBranchTemplate) {
     const proposals = [], missing = [];
     const existing = ordinaryConfigurationPaths.map(logical => fs.existsSync(path.join(workspace, logical)));
     if (existing[0])
@@ -61,14 +61,20 @@ export function prepareMemoryOrdinaryDefaults(context, workspace, selectedProfil
         const remote = git(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]);
         const branches = git(["for-each-ref", "--format=%(refname:short)", "refs/heads/"])?.split("\n").filter(Boolean) ?? [];
         const unborn = !remote && !branches.length ? retainedUnbornBranch(context, workspace, scope) : null;
-        const branch = remote?.startsWith("refs/remotes/origin/") ? remote.slice("refs/remotes/origin/".length) : branches.length === 1 ? branches[0] : unborn;
-        reason = remote ? "verified_origin_head" : unborn ? "retained_unborn_init_branch_technical_default" : branch ? "verified_single_local_branch_technical_default" : "integration_branch_choice_required";
-        if (!branch || !unborn && !git(["rev-parse", "--verify", `${remote ? `refs/remotes/origin/${branch}` : `refs/heads/${branch}`}^{commit}`]))
+        const remoteBranch = remote?.startsWith("refs/remotes/origin/") ? remote.slice("refs/remotes/origin/".length) : null;
+        // The Memory flow's retained explicit choice is also a technical default, not
+        // new merge/push authority. Existing ordinary configuration wins above.
+        const branch = integrationBranch ?? remoteBranch ?? (branches.length === 1 ? branches[0] : unborn);
+        reason = integrationBranch !== undefined ? "retained_explicit_integration_branch" : remoteBranch ? "verified_origin_head" : unborn ? "retained_unborn_init_branch_technical_default" : branch ? "verified_single_local_branch_technical_default" : "integration_branch_choice_required";
+        if (!branch || branch !== unborn && !git(["rev-parse", "--verify", `${integrationBranch === undefined && remoteBranch ? `refs/remotes/origin/${branch}` : `refs/heads/${branch}`}^{commit}`]))
             missing.push("ordinary integration branch (multiple or unavailable candidates)");
         else {
             const contractFile = path.join(workspace, ".memory-bank/dd-flow/flow-contract.json");
             const contract = fs.existsSync(contractFile) ? JSON.parse(fs.readFileSync(contractFile, "utf8")) : null;
-            const template = contract?.workspace?.feature_branch_template;
+            const localTemplate = contract?.workspace?.feature_branch_template;
+            // Preserve compatible project routing; legacy PRT contracts use the
+            // retained upgrade target's default, not an unrelated local canon.
+            const template = typeof localTemplate === "string" && localTemplate.includes("<RUN>") ? localTemplate : targetFeatureBranchTemplate;
             if (typeof template !== "string" || !template.includes("<RUN>"))
                 missing.push("ordinary feature branch template from selected flow contract");
             else
@@ -110,3 +116,14 @@ export function assertMemoryOrdinaryConfigurationCoverage(value, defaults) {
             throw new AppError("memory_stage_result_invalid", "Compose must assign the missing ordinary configuration to a reviewed unit and an exact write scope", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_unassigned", path: logical });
         }
 }
+/** Upgrade must admit missing project-owned paths before its diff is immutable. */
+export function assertMemoryOrdinaryUpgradeConfigurationCoverage(value, defaults) {
+    const changes = value.details.path_map;
+    if (changes.some(change => change.action !== "retain" && [change.from, change.to].some(path => path !== null && defaults.preserved_paths.includes(path)))) {
+        throw new AppError("memory_stage_result_invalid", "Upgrade preserves valid existing ordinary configuration", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "existing_ordinary_configuration_write" });
+    }
+    for (const logical of defaults.required_paths)
+        if (!changes.some(change => change.from === null && change.to === logical && change.ownership === "project" && change.action === "add")) {
+            throw new AppError("memory_stage_result_invalid", "Upgrade analysis must assign each missing ordinary configuration as an exact project-owned addition", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_unassigned", path: logical });
+        }
+}

package/dist/services/memory-preflight-handler.js

@@ -20,6 +20,7 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { readAcceptedStageData } from "./stage-report-renderer.js";
 import { readMemoryCompositionRegistration } from "./memory-composition-registration.js";
 import { hybridDigest } from "./hybrid-contracts.js";
+import { captureMemoryUpgradeSources } from "./memory-upgrade-analysis-handler.js";
 function refuse(reason) {
     throw new AppError("memory_preflight_handler_invalid", "Memory preflight cannot accept this execution or result", 2, { reason, effect: "no_effect" });
 }
@@ -51,6 +52,20 @@ export function captureRegisteredMemoryCompositionSources(context, bundle, regis
     const registration = readMemoryCompositionRegistration(context, registrationScope);
     if (registration.run_id !== bundle.manifest.run_id || registration.execution_sha256 !== bundle.execution.sha256)
         refuse("foreign_composition_registration");
+    if (bundle.descriptor.descriptor.id === "mb-upgrade") {
+        const blueprint = JSON.parse(Buffer.from(registration.result_base64, "base64").toString("utf8"));
+        const historical = new Map();
+        // Only restoring the independently registered blueprint. Its initial
+        // artifact references are not freshly produced Work or current outputs;
+        // final acceptance selects those independently from settled SQL results.
+        for (const unit of blueprint.units) {
+            for (const artifact of unit.artifacts)
+                historical.set(`${artifact.root}\0${artifact.path}`, artifact.sha256);
+            unit.artifacts = [];
+        }
+        return { sources: captureMemoryUpgradeSources(context, bundle, registrationScope.stage, Buffer.from(JSON.stringify(blueprint))),
+            historical, registrationSha256: hybridDigest(registration), inputSha256: registration.input_sha256 };
+    }
     return { ...captureSources(context, bundle, Buffer.from(registration.result_base64, "base64"), true),
         registrationSha256: hybridDigest(registration), inputSha256: registration.input_sha256 };
 }

package/dist/services/memory-repair-current-view.js

@@ -115,7 +115,7 @@ function compose(histories, paths, registration) {
     for (const history of histories) {
         if (!versions.has(hybridDigest(history.before().entries())))
             refuse("unexplained_historical_input_view");
-        baseline = baseline.composeSettledDelta(history.before(), history.after());
+        baseline = baseline.composeSettledDelta(history.before(), history.after(), history.result().outcome);
         versions.add(hybridDigest(baseline.entries()));
     }
     return baseline;