@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/memory-layer.js

@@ -0,0 +1,225 @@
+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, 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 logical.startsWith("dd-flow/project-review/")
+        || logical.startsWith("dd-flow/delivery/")
+        || logical === "dd-flow/mb-sdlc/review-fix.md"
+        || 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",
+    "mb-lint.md", "interactive.md", "finish.md", "fix-def.md"];
+const supportDirectories = ["common", "prime", "mb-sdlc", "aspects", "def", "workers", "schemas", "vnext", "specify", "stage-reports", "dashboard", "plan", "code", "merge", "interactive"];
+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 (isCanonicalOnlyMemoryPath(target))
+                        continue;
+                    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 (!isCanonicalOnlyMemoryPath(`dd-flow/${name}`) && 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: 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");
+            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)])); }
+    /** 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, 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");
+        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()) || !allowEmpty && 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,194 @@
+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 = [], 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" && !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. */
+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");
+    }
+}
+/** 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

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+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";
+import { memoryReviewPhysicalDestination } from "./hook-memory-routing.js";
+import { assertSharedReviewInput } from "./work-registry.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { PreparedInteractiveWorkStart } from "./interactive-work-start.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" }); }
+export { memoryNativeReviewAssignedHookCwd } from "./hook-memory-routing.js";
+function prepareInteractiveReviewOwner(context, work, run, generation) {
+    const bundle = readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: work.run_id });
+    if (bundle?.manifest.flow_id !== "interactive" || JSON.parse(work.payload_json ?? "null")?.kind !== "interactive-review")
+        refuse("registered_interactive_review_required");
+    const input = assertSharedReviewInput(context, work, { ...run, id: work.run_id }, generation);
+    if (!input)
+        refuse("registered_interactive_review_required");
+    const start = PreparedInteractiveWorkStart.prepare(context, { projectId: work.project_id, runId: work.run_id, workId: work.work_id, projectRoot: run.project_root });
+    return { bundle, input, assertCustody: (writer) => start.assertCustody(writer),
+        revalidate: (reader) => {
+            start.revalidate();
+            if (hybridDigest(assertSharedReviewInput(reader, work, { ...run, id: work.run_id }, generation)) !== hybridDigest(input))
+                refuse("review_input_changed");
+        } };
+}
+/** Existing source/copy policy, separate native physical custody: no external
+ * launch row is invented. An interrupted allocation is never overwritten.
+ * Interactive review reuses this owner and its historical copy event format. */
+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 interactive = work.result_schema === "dd-flow/interactive-work-result@1";
+    if (interactive && preparedOwner)
+        refuse("foreign_prepared_review_input");
+    const memoryOwner = interactive ? null : preparedOwner ?? prepareMemoryReviewWorkInput(context, work, run, generation);
+    if (memoryOwner)
+        assertPreparedMemoryReviewWorkInput(context, memoryOwner, work, run, generation);
+    const owner = memoryOwner ?? prepareInteractiveReviewOwner(context, 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);
+    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";
+    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 });
+            memoryReviewPhysicalDestination(runRoot, relative);
+            fs.mkdirSync(root, { mode: 0o700 }); // Exclusive: never adopt an existing or partial destination.
+            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)
+                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,87 @@
+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"];
+/** 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" });
+}
+/** 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 };
+}