@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

package/dist/services/memory-layer.js

@@ -0,0 +1,156 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+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 { readBoundedReleaseFile } from "./release-source.js";
+import { normalizeFlowContract } from "../domain/flow-contract.js";
+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"];
+const supportDirectories = ["common", "prime", "mb-sdlc", "aspects", "def", "workers", "mb-audit", "schemas", "vnext", "specify", "stage-reports", "dashboard", "plan", "code", "merge"];
+const required = ["README.md", "index.md", "flow-contract.json", "compatibility.json", "prime.md", "go.md",
+    "common/style.md", "common/runtime-contract.md", "common/lifecycle-guards.md", "common/workspace-bootstrap.md", "common/worker-session.md",
+    "vnext/start.md", "vnext/specify.md", "vnext/protocolize.md", "vnext/plan.md", "vnext/plan-review.md", "vnext/code.md", "vnext/code-review.md", "vnext/merge.md",
+    "schemas/flow-run.schema.json", "schemas/project-flow-pack-manifest.schema.json"];
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("memory_layer_invalid", "Selected Memory Bank layer cannot be prepared", 1, { reason, phase: "prepare", effect: "no_effect" });
+}
+function directory(file) { if (!fs.lstatSync(file).isDirectory())
+    refuse("unsafe_source_directory"); }
+/** Canonical-layer bytes only, not project facts, a productive bootstrap receipt or qualification.
+ * The source must be the independently selected, verified installed release cache.
+ */
+export class PreparedMemoryLayer {
+    sha256;
+    packSha256;
+    installationSha256;
+    #files;
+    constructor(files, installationSha256) {
+        this.#files = files;
+        this.installationSha256 = installationSha256;
+        const inventory = [...files].map(([logical, bytes]) => ({ path: logical, sha256: hash(bytes) }));
+        this.sha256 = hybridDigest(inventory);
+        this.packSha256 = hybridDigest(inventory.filter(item => item.path.startsWith("dd-flow/")));
+        Object.freeze(this);
+    }
+    static fromInstalledRelease(home, expectedInstallationSha256, installedAt) {
+        try {
+            if (!path.isAbsolute(home) || !/^[a-f0-9]{64}$/.test(expectedInstallationSha256)
+                || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(installedAt) || !Number.isFinite(Date.parse(installedAt)))
+                refuse("invalid_selection");
+            const selection = readSetupStatus(home);
+            if (!selection.installation || selection.installation_readiness !== "installed")
+                refuse("installed_release_unavailable");
+            const installation = selection.installation;
+            if (installation.manifest_sha256 !== expectedInstallationSha256)
+                refuse("installation_selection_changed");
+            directory(installation.canon_root);
+            const roots = fs.readdirSync(installation.canon_root);
+            if (roots.length !== 1)
+                refuse("ambiguous_archive_root");
+            const canonRoot = path.join(installation.canon_root, roots[0]);
+            directory(canonRoot);
+            const dotRoot = path.join(canonRoot, ".memory-bank");
+            const memoryRoot = fs.existsSync(dotRoot) ? dotRoot : canonRoot;
+            directory(memoryRoot);
+            const files = new Map(), folded = new Set();
+            let total = 0;
+            const put = (logical, bytes) => {
+                if (bytes.length < 1 || bytes.length > 1024 * 1024 || !/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(logical) || logical.split("/").some(part => [".", ".."].includes(part))
+                    || folded.has(logical.toLowerCase()) || (total += bytes.length) > 64 * 1024 * 1024)
+                    refuse("unsafe_or_unbounded_inventory");
+                folded.add(logical.toLowerCase());
+                files.set(logical, Buffer.from(bytes));
+            };
+            const collect = (source, logical) => {
+                directory(source);
+                for (const name of fs.readdirSync(source).sort()) {
+                    const file = path.join(source, name), target = `${logical}/${name}`, stat = fs.lstatSync(file);
+                    if (stat.isDirectory())
+                        collect(file, target);
+                    else if (stat.isFile())
+                        put(target, readBoundedReleaseFile(file, 1024 * 1024));
+                    else
+                        refuse("unsafe_source_file");
+                }
+            };
+            collect(path.join(memoryRoot, "mbb"), "mbb");
+            if (!files.has("mbb/index.md"))
+                refuse("missing_mbb_entrypoint");
+            const flowRoot = path.join(memoryRoot, "dd-flow");
+            directory(flowRoot);
+            for (const name of rootFiles)
+                if (fs.existsSync(path.join(flowRoot, name)))
+                    put(`dd-flow/${name}`, readBoundedReleaseFile(path.join(flowRoot, name), 1024 * 1024));
+            for (const name of supportDirectories)
+                if (fs.existsSync(path.join(flowRoot, name)))
+                    collect(path.join(flowRoot, name), `dd-flow/${name}`);
+            if (required.some(logical => !files.has(`dd-flow/${logical}`)))
+                refuse("incomplete_project_pack");
+            const contract = normalizeFlowContract(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(files.get("dd-flow/flow-contract.json"))));
+            const compatibility = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(files.get("dd-flow/compatibility.json")));
+            const compatibilitySchema = JSON.parse(fs.readFileSync(new URL("../schemas/compatibility.schema.json", import.meta.url), "utf8"));
+            if (!new Ajv({ strict: false, validateFormats: false }).compile(compatibilitySchema)(compatibility))
+                refuse("invalid_compatibility");
+            if (compatibility.memory_bank_version !== installation.manifest.canon.version
+                || compatibility.dd_flow_cli.flow_contract !== contract.id
+                || compatibility.dd_flow_cli.package_name !== installation.manifest.engine.package
+                || compatibility.engine.package_name !== installation.manifest.engine.package
+                || !semver.validRange(compatibility.engine.version_range)
+                || !semver.satisfies(installation.manifest.engine.version, compatibility.engine.version_range, { includePrerelease: true })
+                || !semver.valid(compatibility.dd_flow_cli.min_version)
+                || semver.lt(installation.manifest.engine.version, compatibility.dd_flow_cli.min_version))
+                refuse("incompatible_selected_release");
+            const included = [...files.keys()].filter(logical => logical.startsWith("dd-flow/")).map(logical => logical.slice(8)).sort();
+            const manifest = { schema_id: "dd-flow/project-flow-pack-manifest@2", 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,
+                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/**"] };
+            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");
+            const retainedSchema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(files.get("dd-flow/schemas/project-flow-pack-manifest.schema.json")));
+            if (retainedSchema.$id !== "dd-flow/project-flow-pack-manifest@2"
+                || !new Ajv({ strict: false, validateFormats: false }).compile(retainedSchema)(manifest))
+                refuse("invalid_retained_manifest_schema");
+            put("dd-flow/manifest.json", Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`));
+            return new PreparedMemoryLayer(new Map([...files].sort(([left], [right]) => left.localeCompare(right, "en"))), expectedInstallationSha256);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "memory_layer_invalid")
+                throw error;
+            return refuse("source_unavailable_or_changed");
+        }
+    }
+    files() { return new Map([...this.#files].map(([logical, bytes]) => [logical, Buffer.from(bytes)])); }
+    /** 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) {
+        if (!/^[a-f0-9]{64}$/.test(expectedSha256) || !/^[a-f0-9]{64}$/.test(installationSha256)
+            || files.size < 1 || files.size > 20_000)
+            refuse("invalid_retained_selection");
+        let total = 0;
+        const folded = new Set(), retained = new Map();
+        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
+                || (total += content.length) > 64 * 1024 * 1024)
+                refuse("unsafe_or_unbounded_inventory");
+            folded.add(logical.toLowerCase());
+            retained.set(logical, Buffer.from(content));
+        }
+        const result = new PreparedMemoryLayer(new Map([...retained].sort(([left], [right]) => left.localeCompare(right, "en"))), installationSha256);
+        if (result.sha256 !== expectedSha256)
+            refuse("retained_layer_changed");
+        return result;
+    }
+}

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

@@ -0,0 +1,85 @@
+import { AppError } from "../shared/errors.js";
+/** 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 = []) {
+    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))];
+}
+/** Bootstrap-owned policy for immutable guidance, never project knowledge or
+ * the two project-owned JSON defaults beside the canonical flow pack. */
+export function defaultMemoryLintConfiguration() {
+    return Buffer.from(`${JSON.stringify({
+        ignorePaths: [".memory-bank/dd-flow/*.md", ".memory-bank/dd-flow/**/*.md", ".memory-bank/mbb/templates/**"],
+        ignoreFindings: [{ ruleId: "def/required-fields", file: ".memory-bank/mbb/named-deferrals-guide.md",
+                target: "DEF-UI-PROTECTED-BROWSER-PROOF", reason: "Illustrative DEF in immutable canonical guidance, not a project deferral." }]
+    }, null, 2)}\n`);
+}
+function refuse(reason) {
+    throw new AppError("memory_lint_config_invalid", "Lint configuration cannot suppress active memory verification", 2, { reason, effect: "no_effect" });
+}
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        refuse("invalid_config_object");
+    return value;
+}
+function patterns(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some(pattern => typeof pattern !== "string" || !pattern.trim() || pattern.includes("\0")))
+        refuse("invalid_ignore_paths");
+    return value;
+}
+// mb-lint's documented matcher uses literal characters plus * and **, not
+// shell/extglob semantics. Backslashes are normalized to portable separators.
+function matches(pattern, file) {
+    const portable = pattern.replaceAll("\\", "/");
+    if (["?", "[", "]", "{", "}", "!", "(", ")"].some(character => portable.includes(character)) || portable.split("/").some(segment => !segment || segment === "." || segment === ".."))
+        refuse("unsupported_ignore_pattern");
+    const chunks = portable.split(/(\*\*|\*)/);
+    const source = chunks.map(chunk => chunk === "**" ? ".*" : chunk === "*" ? "[^/]*" : chunk.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&")).join("");
+    return new RegExp(`^${source}$`).test(file.replaceAll("\\", "/"));
+}
+/** Pure admission, no writes or inference of semantic completeness. Protected
+ * paths come from accepted composition plus required active root documents.
+ * Existing config bytes remain user-owned; exclusion repair is not automatic.
+ */
+export function validateMemoryLintConfig(bytes, activePaths) {
+    if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > 1024 * 1024)
+        refuse("invalid_config_bytes");
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_config_json");
+    }
+    const config = record(parsed), allowed = new Set(["ignorePaths", "ignoreFindings", "ignore", "git"]);
+    if (Object.keys(config).some(key => !allowed.has(key)))
+        refuse("unsupported_config_field");
+    const nested = config.ignore === undefined ? {} : record(config.ignore);
+    if (Object.keys(nested).some(key => !['files', 'findings'].includes(key)))
+        refuse("unsupported_ignore_field");
+    const paths = [...patterns(config.ignorePaths), ...patterns(nested.files)];
+    if (paths.some(pattern => activePaths.some(file => matches(pattern, file))))
+        refuse("active_document_ignored");
+    for (const list of [config.ignoreFindings, nested.findings]) {
+        if (list === undefined)
+            continue;
+        if (!Array.isArray(list))
+            refuse("invalid_ignore_findings");
+        for (const item of list) {
+            const finding = record(item);
+            if (Object.keys(finding).some(key => !['ruleId', 'file', 'target', 'reason'].includes(key))
+                || Object.values(finding).some(value => typeof value !== "string" || !value.trim() || value.includes("\0")))
+                refuse("invalid_ignore_finding");
+            if (typeof finding.file !== "string" || activePaths.some(file => matches(finding.file, file)))
+                refuse("active_finding_suppressed");
+        }
+    }
+    if (config.git !== undefined) {
+        const git = record(config.git);
+        if (Object.keys(git).some(key => key !== "respectIgnore") || git.respectIgnore !== undefined && typeof git.respectIgnore !== "boolean")
+            refuse("invalid_git_config");
+    }
+}

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

@@ -0,0 +1,165 @@
+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";
+import { prepareMemoryReviewWorkInput, assertPreparedMemoryReviewWorkInput } from "./memory-review-work-input.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { reviewSourceFilter, reviewSourceHash, reviewExecutionCopyHash } from "./review-copy.js";
+import { writeReviewGitEvidence } from "./external-work-launch.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;
+}
+/** 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) {
+    const work = context.db.get("SELECT * FROM works WHERE work_id=?", [workId]);
+    if (!work)
+        refuse("owned_work_required");
+    const run = context.db.get("SELECT * FROM runs WHERE project_id=? AND id=?", [work.project_id, work.run_id]);
+    if (!run)
+        refuse("owned_run_required");
+    const generation = assertRunMutationAllowed(context, work.project_id, work.run_id);
+    const owner = preparedOwner ?? prepareMemoryReviewWorkInput(context, work, run, generation);
+    assertPreparedMemoryReviewWorkInput(context, owner, work, run, generation);
+    const route = owner.bundle.execution.work("review");
+    if (route.delegation.mode !== "native")
+        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);
+    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";
+    const intent = { schema_id: "dd-flow/memory-native-review-copy@1", project_id: work.project_id, run_id: work.run_id,
+        work_id: workId, generation, root: relative, input_sha256: hybridDigest(owner.input), source_sha256: reviewSourceHash(run.workspace_root, inputs, base) };
+    // A recovery generation gets a new owned copy; never adopt the previous
+    // generation's journal or overwrite its physical evidence.
+    const retained = (event, reader = context) => reader.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", [work.project_id, event, work.run_id, workId, generation]);
+    const ready = retained("memory.native_review_copy_ready");
+    let copy;
+    if (ready.length) {
+        if (ready.length !== 1)
+            refuse("ambiguous_copy");
+        const intents = retained("memory.native_review_copy_intent");
+        if (intents.length !== 1 || hybridDigest(JSON.parse(intents[0].payload_json)) !== hybridDigest(intent))
+            refuse("copy_custody_changed");
+        const value = JSON.parse(ready[0].payload_json);
+        if (hybridDigest(value.intent) !== hybridDigest(intent) || !/^[a-f0-9]{64}$/.test(value.sha256))
+            refuse("copy_or_source_changed");
+        copy = { root: relative, sha256: value.sha256, source_sha256: intent.source_sha256 };
+    }
+    else {
+        if (!allocate)
+            refuse("ready_copy_required");
+        if (retained("memory.native_review_copy_intent").length || fs.lstatSync(root, { throwIfNoEntry: false }))
+            refuse("copy_allocation_unsettled");
+        owner.revalidate(context);
+        context.db.writeTransaction(() => {
+            owner.assertCustody(context);
+            if (retained("memory.native_review_copy_intent").length)
+                refuse("copy_allocation_unsettled");
+            appendAudit(context, { projectId: work.project_id, eventType: "memory.native_review_copy_intent", payload: intent });
+        });
+        try {
+            fs.mkdirSync(path.dirname(root), { recursive: true, mode: 0o700 });
+            physicalDestination(runRoot, relative);
+            fs.mkdirSync(root, { mode: 0o700 }); // Exclusive: never adopt an existing or partial destination.
+            physicalDestination(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)
+                refuse("copy_or_source_changed");
+            writeReviewGitEvidence(run.workspace_root, root, base, inputs);
+            owner.revalidate(context);
+            if (reviewSourceHash(run.workspace_root, inputs, base) !== intent.source_sha256
+                || reviewExecutionCopyHash(root, run.workspace_root, false, inputs, base) !== intent.source_sha256)
+                refuse("copy_or_source_changed");
+            copy = { root: relative, source_sha256: intent.source_sha256, sha256: reviewExecutionCopyHash(root, run.workspace_root, true, inputs, base) };
+            context.db.writeTransaction(() => {
+                owner.assertCustody(context);
+                if (retained("memory.native_review_copy_ready").length)
+                    refuse("copy_allocation_unsettled");
+                appendAudit(context, { projectId: work.project_id, eventType: "memory.native_review_copy_ready", payload: { intent, sha256: copy.sha256 } });
+            });
+        }
+        catch (error) {
+            throw new AppError("memory_native_review_copy_pending", "Native review copy allocation is retained and cannot be replayed or overwritten", 1, { effect: "partial", recoverable: false, work_id: workId, copy_root: root, next_action: "Inspect the exact retained copy intent and private destination; do not relaunch or adopt partial files.",
+                cause: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    if (reviewExecutionCopyHash(root, run.workspace_root, true, inputs, base) !== copy.sha256)
+        refuse("copy_changed");
+    const assertCustody = (writer) => {
+        owner.assertCustody(writer);
+        assertRunMutationAllowed(writer, work.project_id, work.run_id, generation);
+        const rows = retained("memory.native_review_copy_ready", writer);
+        const intents = retained("memory.native_review_copy_intent", writer);
+        if (intents.length !== 1 || hybridDigest(JSON.parse(intents[0].payload_json)) !== hybridDigest(intent)
+            || rows.length !== 1 || hybridDigest(JSON.parse(rows[0].payload_json)) !== hybridDigest({ intent, sha256: copy.sha256 }))
+            refuse("copy_custody_changed");
+    };
+    return { root, copy, route, assertCustody };
+}

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

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { parse as parseYaml } from "yaml";
+import { AppError } from "../shared/errors.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+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"];
+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" });
+}
+/** Real ordinary-entry preparation only. No launch, protocol, Work, Session,
+ * provider, command execution or runtime receipt is created. Callers still
+ * need independent semantic review, selected pack/tools and integration. */
+export function observeMemoryNormalFlowEntry(context, projectRoot) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    if (typeof projectRoot !== "string" || !path.isAbsolute(projectRoot))
+        refuse("absolute_project_root_required");
+    const root = fs.realpathSync(projectRoot);
+    const paths = [...identity, ".memory-bank/mbb/index.md", ".memory-bank/dd-flow/flow-contract.json",
+        ".memory-bank/dd-flow/project-execution.json", ".memory-bank/dd-flow/project-workspace.json",
+        ".memory-bank/dd-flow/vnext/specify.md"];
+    for (const name of ["mb-sdlc-vnext-specify.json", "mb-sdlc-vnext-protocolize.json"]) {
+        const logical = `.memory-bank/dd-flow/vnext/${name}`;
+        try {
+            fs.lstatSync(path.join(root, logical));
+            paths.push(logical);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const observe = (selected) => ObservedMemorySources.capture({ project: root }, selected.map(path => ({ root: "project", path })));
+    const before = observe(paths);
+    for (const logical of identity) {
+        const text = before.bytes({ root: "project", path: logical }).toString("utf8");
+        if (!text.startsWith("---\n") && !text.startsWith("---\r\n"))
+            refuse("identity_frontmatter_required");
+        const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+        if (!match)
+            refuse("identity_frontmatter_required");
+        const header = parseYaml(match[1]);
+        if (!header || typeof header !== "object" || Array.isArray(header))
+            refuse("identity_frontmatter_required");
+    }
+    // This diagnostic intake is never persisted or dispatched as a user task.
+    const prepared = prepareVnextSpecifyStart(context, { projectRoot: root,
+        intakeMarkdown: "Internal ordinary-entry readiness preparation; do not launch a RUN.", slug: "memory-readiness" });
+    const policy = loadVnextWorkspacePolicy(root), profile = prepared.start?.executionProfile;
+    if (!profile || prepared.preflight.ok !== true || prepared.start?.projectRoot !== root)
+        refuse("ordinary_preparation_incomplete");
+    const policyPath = profile.settings.code_bootstrap?.policy_ref;
+    if (policyPath !== undefined && (typeof policyPath !== "string" || !policyPath.startsWith(".memory-bank/") || policyPath.includes("\\")
+        || policyPath.includes("\0") || policyPath.split("/").some(segment => !segment || segment === "." || segment === "..")))
+        refuse("bootstrap_policy_reference_required");
+    const selected = [...new Set([...paths, ...(policyPath === undefined ? [] : [policyPath]), ...prepared.grounding.map(item => item.source)])].sort();
+    const observed = observe(selected), hashes = observed.hashes();
+    before.revalidate();
+    if (hashes.get(memorySourceKey("project", ".memory-bank/dd-flow/project-execution.json")) !== profile.source_checksum)
+        refuse("ordinary_profile_changed");
+    observed.revalidate();
+    return { schema_id: "dd-flow/memory-normal-flow-entry-observation@1", project_root: root,
+        operation: "stage.start.bootstrap.specify", runtime_state: "not_created", model_access: "unknown",
+        source_sha256: observed.sha256, sources: selected.map(path => ({ root: "project", path,
+            sha256: hashes.get(memorySourceKey("project", path)) })),
+        profile_sha256: profile.source_checksum, execution_sha256: hybridDigest({ settings: profile.settings,
+            profiles: profile.agent_profiles ?? null, operational_decision: profile.operational_decision ?? null }),
+        template_sha256: createHash("sha256").update(prepared.template).digest("hex"),
+        workspace_policy: policy, handoff: prepared.handoff };
+}

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

@@ -0,0 +1,112 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { isDeepStrictEqual } from "node:util";
+import { AppError } from "../shared/errors.js";
+import { readOperatorProfiles, resolveOperatorProfile } from "./operator-profiles.js";
+import { validateVnextExecutionProfile } from "./vnext-execution-profile.js";
+import { loadVnextWorkspacePolicy } from "./vnext-workspace-policy.js";
+import { readMemoryInitGitPolicy } from "./memory-init-git-policy.js";
+export const ordinaryConfigurationPaths = [".memory-bank/dd-flow/project-execution.json", ".memory-bank/dd-flow/project-workspace.json"];
+function gitObservation(context, workspace, args) {
+    const env = Object.fromEntries(Object.entries(context.env ?? process.env).filter(([key]) => !key.startsWith("GIT_")));
+    const result = spawnSync("git", ["-C", workspace, ...args], { env: { ...env, GIT_OPTIONAL_LOCKS: "0" }, encoding: "utf8", timeout: 10000, maxBuffer: 65536 });
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+function retainedUnbornBranch(context, workspace, scope) {
+    if (!scope || scope.projectRoot !== workspace || scope.workspaceRoot !== workspace)
+        return null;
+    const policy = readMemoryInitGitPolicy(context, scope);
+    if (!policy || policy.initial_head !== null || policy.route !== "integration_branch_direct")
+        return null;
+    const git = (args) => gitObservation(context, workspace, args), common = git(["rev-parse", "--git-common-dir"]);
+    if (!common || fs.realpathSync(path.resolve(workspace, common)) !== policy.repository
+        || git(["symbolic-ref", "--quiet", "--short", "HEAD"]) !== policy.workspace_branch
+        || policy.workspace_branch !== policy.integration_branch || git(["rev-parse", "--verify", "HEAD"]) !== null
+        || git(["for-each-ref", "--format=%(refname)", "refs/heads/"]) !== "")
+        return null;
+    return policy.integration_branch;
+}
+/** Project-owned technical defaults only; never grants authority to a future task. */
+export function prepareMemoryOrdinaryDefaults(context, workspace, selectedProfile, scope) {
+    const proposals = [], missing = [];
+    const existing = ordinaryConfigurationPaths.map(logical => fs.existsSync(path.join(workspace, logical)));
+    if (existing[0])
+        validateVnextExecutionProfile(JSON.parse(fs.readFileSync(path.join(workspace, ordinaryConfigurationPaths[0]), "utf8")));
+    if (existing[1])
+        loadVnextWorkspacePolicy(workspace);
+    if (!existing[0]) {
+        const settings = readOperatorProfiles(context.ddFlowHome);
+        let profile;
+        try {
+            profile = resolveOperatorProfile(settings, selectedProfile);
+        }
+        catch {
+            if (settings.default_profile)
+                profile = resolveOperatorProfile(settings);
+        }
+        if (!profile)
+            missing.push("configured ordinary executor profile");
+        else {
+            const value = { schema_id: "dd-flow/project-execution@3", stage_session_mode: "new_session", plan_review_mode: "auto", code_review_mode: "auto",
+                merge_mode: "server", merge_delivery: { strategy: "local" }, merge_cleanup: { source: "retain" }, stop_target: "merge_completed",
+                execution: { agent_profile_id: profile.id, delegation: { mode: "external", max_parallel: 1 } } };
+            validateVnextExecutionProfile(value);
+            proposals.push({ path: ordinaryConfigurationPaths[0], value });
+        }
+    }
+    let reason = "existing_valid_project_configuration";
+    if (!existing[1]) {
+        const git = (args) => gitObservation(context, workspace, args);
+        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}`]))
+            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;
+            if (typeof template !== "string" || !template.includes("<RUN>"))
+                missing.push("ordinary feature branch template from selected flow contract");
+            else
+                proposals.push({ path: ordinaryConfigurationPaths[1], value: { schema_id: "dd-flow/project-workspace@1", workspace: {
+                            route: "feature_worktree", integration_branch: branch, feature_branch_template: template, provision_stage: "protocolize_start"
+                        } } });
+        }
+    }
+    return { proposals, preserved_paths: ordinaryConfigurationPaths.filter((_, index) => existing[index]), required_paths: ordinaryConfigurationPaths.filter((_, index) => !existing[index]), missing, reason };
+}
+/** Existing compose output custody selects these files; this checks their executable meaning. */
+export function assertMemoryOrdinaryConfigurationOutputs(context, workspace, defaults, artifacts, scope) {
+    for (const logical of defaults.required_paths)
+        if (!artifacts.some(artifact => artifact.root === "workspace" && artifact.path === logical)) {
+            throw new AppError("memory_stage_result_invalid", "Compose must retain each required ordinary configuration as an accepted Work output", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_output_missing", path: logical });
+        }
+    const values = new Map(ordinaryConfigurationPaths.map(logical => [logical, JSON.parse(fs.readFileSync(path.join(workspace, logical), "utf8"))]));
+    const profile = validateVnextExecutionProfile(values.get(ordinaryConfigurationPaths[0]));
+    const policy = loadVnextWorkspacePolicy(workspace);
+    if (profile.execution)
+        resolveOperatorProfile(readOperatorProfiles(context.ddFlowHome), profile.execution.agent_profile_id);
+    for (const item of defaults.proposals)
+        if (!isDeepStrictEqual(values.get(item.path), item.value)) {
+            throw new AppError("memory_stage_result_invalid", "Compose changed supplied technical defaults", 2, { phase: "prepare", effect: "no_effect", reason: "ordinary_configuration_changed", path: item.path });
+        }
+    const branch = policy.workspace.integration_branch;
+    const exists = gitObservation(context, workspace, ["rev-parse", "--verify", `refs/heads/${branch}^{commit}`]);
+    const remote = exists ? null : gitObservation(context, workspace, ["rev-parse", "--verify", `refs/remotes/origin/${branch}^{commit}`]);
+    if (!exists && !remote && retainedUnbornBranch(context, workspace, scope) !== branch)
+        throw new AppError("memory_stage_result_invalid", "Ordinary integration branch is not an existing repository branch", 2, { phase: "prepare", effect: "no_effect", reason: "ordinary_integration_branch_unavailable" });
+}
+export function assertMemoryOrdinaryConfigurationCoverage(value, defaults) {
+    const plan = value;
+    if (plan.details?.works?.some(work => work.write_scopes.some(scope => scope.root === "workspace" && defaults.preserved_paths.includes(scope.path)))) {
+        throw new AppError("memory_stage_result_invalid", "Fresh init preserves valid existing ordinary configuration; remove that configuration write scope", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "existing_ordinary_configuration_write" });
+    }
+    for (const logical of defaults.required_paths)
+        if (!plan.details?.works?.some(work => work.unit_ids.length && work.write_scopes.some(scope => scope.root === "workspace" && scope.path === logical))) {
+            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 });
+        }
+}