youmd 0.11.0 → 0.13.0

package/dist/lib/brain/proposal.js

@@ -1,20 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROJECT_BRAIN_PROPOSAL_VERSION = exports.PROJECT_BRAIN_PROPOSAL_SCHEMA = exports.PROJECT_BRAIN_OVERRIDE_VERSION = void 0;
+exports.PROJECT_BRAIN_TASK_MUTATION_VERSION = exports.PROJECT_BRAIN_PROPOSAL_VERSION = exports.PROJECT_BRAIN_PROPOSAL_SCHEMA = exports.PROJECT_BRAIN_OVERRIDE_VERSION = void 0;
 exports.validateProjectBrainPatch = validateProjectBrainPatch;
 exports.validateProjectBrainUnifiedDiffPatch = validateProjectBrainUnifiedDiffPatch;
 exports.validateProjectBrainProposal = validateProjectBrainProposal;
+exports.validateProjectBrainAdoptionDescriptor = validateProjectBrainAdoptionDescriptor;
+exports.proposeProjectBrainAdoptions = proposeProjectBrainAdoptions;
 exports.proposeProjectBrainAdoption = proposeProjectBrainAdoption;
 exports.importProjectBrainOverrides = importProjectBrainOverrides;
 const redact_1 = require("../redact");
 const canonical_1 = require("./canonical");
+const descriptor_validator_1 = require("./descriptor-validator");
 exports.PROJECT_BRAIN_OVERRIDE_VERSION = "you-md/project-brain-override/v1";
 exports.PROJECT_BRAIN_PROPOSAL_SCHEMA = "https://you.md/schemas/project-brain-proposal/v1";
 exports.PROJECT_BRAIN_PROPOSAL_VERSION = "you-md/project-brain-proposal/v1";
+exports.PROJECT_BRAIN_TASK_MUTATION_VERSION = "you-md/task-mutation-proposal/v1";
 const PROJECT_REF_PATTERN = /^project:[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 const REVISION_PATTERN = /^sha256:[a-f0-9]{64}$/;
 const OVERRIDE_SOURCE_PATTERN = /^(?:overrides|notes)\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\.json$/;
 const ARTIFACT_REF_PATTERN = /^artifact:[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?\/[a-z0-9][a-z0-9._-]{0,95}$/;
+const SAFE_RELATIVE_PATH = /^(?!\/)(?![A-Za-z]:)(?!.*\\)(?!.*\/\/)(?!.*(?:^|\/)(?:\.{1,2})(?:\/|$))(?!.*[\u0000-\u001f\u007f])(?!.*\/$)[^/]+(?:\/[^/]+)*$/;
 const FORBIDDEN_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
 const MAX_PATCH_OPERATIONS = 100;
 const MAX_PATCH_BYTES = 256 * 1024;
@@ -29,6 +34,22 @@ const APPROVAL_BINDINGS = [
     "patchFormat",
     "patchDigest",
 ];
+const TASK_APPROVAL_BINDINGS = [
+    ...APPROVAL_BINDINGS,
+    "taskMutation.mutationRef",
+];
+const TASK_MUTATION_REF_PATTERN = /^task-mutation:sha256:[a-f0-9]{64}$/;
+const TASK_ID_PATTERN = /^t-[A-Za-z0-9][A-Za-z0-9_-]{0,94}$/;
+const EXACT_ISO_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const TASK_STATUSES = new Set(["proposed", "open", "in_progress", "done", "snoozed", "cancelled"]);
+const TASK_PRIORITIES = new Set(["low", "normal", "high", "urgent"]);
+const TASK_TAG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const TASK_TEXT_CONTROL_PATTERN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+const TASK_CREATE_RICH_KEYS = [
+    "requestedDescription", "requestedGoal", "requestedSuccessCriteria", "requestedParentId",
+    "requestedDependencyIds", "requestedScope", "requestedBlockers", "requestedClarification",
+    "requestedReview", "requestedEvidence", "requestedTags", "requestedVerify", "requestedOwnerLabel",
+];
 function proposalError(sourceRef, code, message, operationIndex) {
     return operationIndex === undefined ? { sourceRef, code, message } : { sourceRef, code, message, operationIndex };
 }
@@ -353,6 +374,77 @@ function validateProjectBrainUnifiedDiffPatch(raw, sourceRef = "proposal:input")
         return { valid: false, errors: [proposalError(sourceRef, "secret_detected", "unified diff contains a secret or private-data pattern")] };
     return { valid: true, errors: [], patch, patchDigest: digest(normalizeJson(patch)) };
 }
+function validTaskMutationText(value, max) {
+    return value === undefined || typeof value === "string" && Boolean(value.trim()) && value === value.trim()
+        && value.length <= max && !TASK_TEXT_CONTROL_PATTERN.test(value);
+}
+function validTaskMutationList(value, maxItems, maxText, pattern) {
+    return value === undefined || Array.isArray(value) && value.length <= maxItems
+        && new Set(value).size === value.length
+        && value.every((item) => validTaskMutationText(item, maxText)
+            && typeof item === "string" && (!pattern || pattern.test(item)));
+}
+function validateTaskMutation(value, baseContentHash, patchDigest) {
+    if (!value || typeof value !== "object" || Array.isArray(value)
+        || !REVISION_PATTERN.test(baseContentHash || "") || !REVISION_PATTERN.test(patchDigest || ""))
+        return false;
+    const mutation = value;
+    const commonValid = mutation.schemaVersion === exports.PROJECT_BRAIN_TASK_MUTATION_VERSION
+        && typeof mutation.mutationRef === "string" && TASK_MUTATION_REF_PATTERN.test(mutation.mutationRef)
+        && typeof mutation.localTaskId === "string" && TASK_ID_PATTERN.test(mutation.localTaskId)
+        && typeof mutation.requestedAt === "string" && EXACT_ISO_PATTERN.test(mutation.requestedAt)
+        && Number.isFinite(Date.parse(mutation.requestedAt));
+    if (!commonValid)
+        return false;
+    const commonKeys = ["schemaVersion", "mutationRef", "operation", "localTaskId", "requestedStatus", "requestedAt"];
+    if (mutation.operation === "create") {
+        const requiredKeys = [...commonKeys, "requestedTitle", "requestedOwner", "requestedPriority"];
+        const allowedKeys = new Set([...requiredKeys, ...TASK_CREATE_RICH_KEYS]);
+        if (requiredKeys.some((key) => !Object.prototype.hasOwnProperty.call(mutation, key))
+            || Object.keys(mutation).some((key) => !allowedKeys.has(key))
+            || typeof mutation.requestedTitle !== "string" || !mutation.requestedTitle.trim()
+            || mutation.requestedTitle !== mutation.requestedTitle.trim() || mutation.requestedTitle.length > 240
+            || TASK_TEXT_CONTROL_PATTERN.test(mutation.requestedTitle) || mutation.requestedStatus !== "open"
+            || (mutation.requestedOwner !== "human" && mutation.requestedOwner !== "agent")
+            || typeof mutation.requestedPriority !== "string" || !TASK_PRIORITIES.has(mutation.requestedPriority)
+            || !validTaskMutationText(mutation.requestedDescription, 10000)
+            || !validTaskMutationText(mutation.requestedGoal, 10000)
+            || !validTaskMutationText(mutation.requestedSuccessCriteria, 10000)
+            || !validTaskMutationText(mutation.requestedParentId, 95)
+            || (mutation.requestedParentId !== undefined
+                && (typeof mutation.requestedParentId !== "string" || !TASK_ID_PATTERN.test(mutation.requestedParentId)))
+            || !validTaskMutationList(mutation.requestedDependencyIds, 256, 95, TASK_ID_PATTERN)
+            || !validTaskMutationText(mutation.requestedScope, 4000)
+            || !validTaskMutationList(mutation.requestedBlockers, 128, 2000)
+            || !validTaskMutationText(mutation.requestedClarification, 10000)
+            || !validTaskMutationText(mutation.requestedReview, 10000)
+            || !validTaskMutationList(mutation.requestedEvidence, 256, 4000)
+            || !validTaskMutationList(mutation.requestedTags, 32, 64, TASK_TAG_PATTERN)
+            || !validTaskMutationText(mutation.requestedVerify, 2000)
+            || !validTaskMutationText(mutation.requestedOwnerLabel, 120)
+            || mutation.requestedParentId === mutation.localTaskId
+            || (Array.isArray(mutation.requestedDependencyIds)
+                && mutation.requestedDependencyIds.includes(mutation.localTaskId)))
+            return false;
+    }
+    else if (mutation.operation === "update_status") {
+        const keys = new Set([...commonKeys, "portfolioTaskId", "expectedPortfolioUpdatedAt"]);
+        if (Object.keys(mutation).length !== keys.size || Object.keys(mutation).some((key) => !keys.has(key))
+            || typeof mutation.portfolioTaskId !== "string" || !mutation.portfolioTaskId
+            || mutation.portfolioTaskId.length > 160 || /[\u0000-\u001f\u007f]/.test(mutation.portfolioTaskId)
+            || typeof mutation.expectedPortfolioUpdatedAt !== "number" || !Number.isFinite(mutation.expectedPortfolioUpdatedAt)
+            || typeof mutation.requestedStatus !== "string" || !TASK_STATUSES.has(mutation.requestedStatus))
+            return false;
+    }
+    else
+        return false;
+    const { mutationRef: _mutationRef, ...bindingWithoutRef } = mutation;
+    return mutation.mutationRef === `task-mutation:${digest(normalizeJson({
+        ...bindingWithoutRef,
+        baseContentHash,
+        patchDigest,
+    }))}`;
+}
 /** Validate a transport proposal envelope without approving or applying it. */
 function validateProjectBrainProposal(value) {
     const sourceRef = value && typeof value === "object" && typeof value.proposalRef === "string"
@@ -371,11 +463,14 @@ function validateProjectBrainProposal(value) {
     const proposal = normalized;
     const record = normalized;
     const errors = [];
+    const hasTaskMutation = Object.prototype.hasOwnProperty.call(record, "taskMutation");
     const requiredKeys = new Set([
         "$schema", "schemaVersion", "kind", "proposalRef", "proposalType", "projectRef", "machineRef", "workspaceRef",
         "baseRevision", "requestedCapability", "rationale", "status", "target", "patchFormat", "patchDigest", "patch", "diff",
         "approval", "source",
     ]);
+    if (hasTaskMutation)
+        requiredKeys.add("taskMutation");
     if (Object.keys(record).length !== requiredKeys.size || Object.keys(record).some((key) => !requiredKeys.has(key))
         || proposal.$schema !== exports.PROJECT_BRAIN_PROPOSAL_SCHEMA || proposal.schemaVersion !== exports.PROJECT_BRAIN_PROPOSAL_VERSION
         || proposal.kind !== "project-brain-proposal" || proposal.status !== "proposed"
@@ -384,7 +479,7 @@ function validateProjectBrainProposal(value) {
         || typeof proposal.rationale !== "string" || proposal.rationale.trim().length < 3 || proposal.rationale.length > 1000
         || !proposal.target || proposal.target.humanOwned !== true || !ARTIFACT_REF_PATTERN.test(proposal.target.artifactRef)
         || !REVISION_PATTERN.test(proposal.target.baseContentHash) || !proposal.source
-        || !/^(?:sha256|heuristic|git):[A-Za-z0-9._-]{7,128}$/.test(proposal.source.sourceRevision)) {
+        || !/^(?:git|sha256|foldermd|eve|heuristic):[A-Za-z0-9._-]{7,128}$/.test(proposal.source.sourceRevision)) {
         errors.push(proposalError(sourceRef, "invalid_proposal", "proposal envelope or identity is invalid"));
     }
     if (!safeSecretScan(proposal))
@@ -419,7 +514,7 @@ function validateProjectBrainProposal(value) {
         errors.push(proposalError(sourceRef, "invalid_proposal", "proposal patchFormat is unsupported"));
     if (!proposal.approval || proposal.approval.required !== true || proposal.approval.policy !== "fresh_exact_patch"
         || proposal.approval.reusable !== false || proposal.approval.maxAgeSeconds !== 900
-        || JSON.stringify(proposal.approval.bindingFields) !== JSON.stringify(APPROVAL_BINDINGS)) {
+        || JSON.stringify(proposal.approval.bindingFields) !== JSON.stringify(hasTaskMutation ? TASK_APPROVAL_BINDINGS : APPROVAL_BINDINGS)) {
         errors.push(proposalError(sourceRef, "approval_binding_mismatch", "proposal requires a fresh approval bound to every exact identity and patch field"));
     }
     const { proposalRef: _proposalRef, ...preimage } = proposal;
@@ -428,8 +523,9 @@ function validateProjectBrainProposal(value) {
     }
     const descriptorAdoptionPatchValid = proposal.patchFormat === "rfc6902"
         && Array.isArray(proposal.patch) && proposal.patch.length === 1
+        && proposal.target?.exists === true
         && proposal.patch[0]?.path === ""
-        && proposal.patch[0]?.op === (proposal.target?.exists ? "replace" : "add")
+        && proposal.patch[0]?.op === "replace"
         && "value" in proposal.patch[0];
     const typeValid = proposal.proposalType === "descriptor_adoption"
         ? proposal.requestedCapability === "brain.descriptor.adopt" && proposal.patchFormat === "rfc6902"
@@ -443,6 +539,12 @@ function validateProjectBrainProposal(value) {
                 && proposal.target.kind === "repository_file" && typeof proposal.target.path === "string" && proposal.target.exists === true;
     if (!typeValid)
         errors.push(proposalError(sourceRef, "invalid_proposal", "proposal type, capability, target, and patch format are inconsistent"));
+    if (hasTaskMutation && (!validateTaskMutation(proposal.taskMutation, proposal.target?.baseContentHash, proposal.patchDigest)
+        || proposal.proposalType !== "artifact_update" || proposal.requestedCapability !== "brain.artifact.update"
+        || proposal.patchFormat !== "unified_diff" || proposal.target?.kind !== "repository_file"
+        || proposal.target.path?.split("/").at(-1) !== "tasks.json")) {
+        errors.push(proposalError(sourceRef, "invalid_proposal", "task mutation is not an exact, safe repository task binding"));
+    }
     return errors.length ? { valid: false, errors } : { valid: true, errors: [], proposal };
 }
 function buildProposal(seed) {
@@ -470,6 +572,7 @@ function buildProposal(seed) {
 function stripFactProvenance(project) {
     const paths = new Set(project.artifacts.map((artifact) => artifact.path));
     return project.artifacts
+        .filter((artifact) => artifact.path !== ".you-project" && artifact.path !== ".youmd-project")
         .filter((artifact) => !(artifact.kind === "tasks" && artifact.path.endsWith("/tasks.md")
         && paths.has(`${artifact.path.slice(0, -"tasks.md".length)}tasks.json`)))
         .map((artifact) => ({
@@ -479,7 +582,7 @@ function stripFactProvenance(project) {
         path: artifact.path,
         owner: artifact.owner,
         authority: artifact.authority,
-        writePolicy: "read_only",
+        writePolicy: artifact.owner === "repository" && artifact.authority === "canonical" ? "propose" : "read_only",
         provenance: {
             source: artifact.provenance.source,
             sourceRef: artifact.provenance.sourceRef,
@@ -487,12 +590,53 @@ function stripFactProvenance(project) {
             indexedAt: artifact.provenance.indexedAt,
             freshness: artifact.provenance.freshness,
         },
-    }));
+    }))
+        .sort((a, b) => (0, canonical_1.canonicalize)(a).localeCompare((0, canonical_1.canonicalize)(b)));
 }
 const PROJECT_REVISION_FIELDS = [
-    "$schema", "schemaVersion", "kind", "projectRef", "slug", "name", "contextRoot",
-    "agentRoots", "artifacts", "relationships", "writePolicy", "generatedExcludes", "provenance",
+    "$schema", "schemaVersion", "kind", "projectRef", "slug", "name", "aliases", "contextRoot",
+    "agentRoots", "workspaces", "repositoryBinding", "legacySource", "artifacts", "relationships",
+    "writePolicy", "generatedExcludes", "provenance",
 ];
+/**
+ * Validate the deliberately authority-free descriptor produced by first-time
+ * adoption. Adoption may establish catalog ownership, but it must never grant
+ * managed or task writes as a side effect of replacing a legacy marker.
+ */
+function validateProjectBrainAdoptionDescriptor(value, projectRef) {
+    const validation = (0, descriptor_validator_1.validateProjectBrainDescriptor)(value);
+    if (!validation.valid)
+        return null;
+    let descriptor;
+    try {
+        descriptor = normalizeJson(value);
+    }
+    catch {
+        return null;
+    }
+    const record = descriptor;
+    const writePolicy = record.writePolicy;
+    if (record.projectRef !== projectRef || !writePolicy || typeof writePolicy !== "object" || Array.isArray(writePolicy))
+        return null;
+    const policy = writePolicy;
+    const taskWrite = policy.taskWrite;
+    const artifacts = record.artifacts;
+    if (policy.default !== "propose" || !Array.isArray(policy.managedPaths) || policy.managedPaths.length !== 0
+        || !taskWrite || typeof taskWrite !== "object" || Array.isArray(taskWrite)
+        || taskWrite.enabled !== false
+        || Object.keys(taskWrite).some((key) => key !== "enabled"))
+        return null;
+    if (!Array.isArray(artifacts))
+        return null;
+    for (const artifact of artifacts) {
+        if (!artifact || typeof artifact !== "object" || Array.isArray(artifact))
+            return null;
+        const claim = artifact;
+        if (claim.writePolicy !== "propose" && claim.writePolicy !== "read_only")
+            return null;
+    }
+    return descriptor;
+}
 function withoutVolatile(value) {
     if (Array.isArray(value))
         return value.map(withoutVolatile);
@@ -504,25 +648,50 @@ function withoutVolatile(value) {
             result[key] = withoutVolatile(child);
     return result;
 }
-function adoptionDescriptor(scan, project, name) {
+function adoptionBaseRevision(workspaces) {
+    if (workspaces.length === 1)
+        return workspaces[0].scan.revision.digest;
+    return digest(workspaces.map(({ scan }) => ({ workspaceRef: scan.workspaceRef, revision: scan.revision.digest })));
+}
+function adoptionDescriptor(workspaces, name) {
+    const { scan, project } = workspaces[0];
     const slug = project.projectRef.slice("project:".length);
+    const baseRevision = adoptionBaseRevision(workspaces);
+    const repositoryRef = scan.workspaceIdentity.repositoryRef;
+    const repositoryBinding = project.repositoryBinding || {
+        repositoryRef,
+        evidence: { source: "local_workspace", sourceRevision: repositoryRef.replace(/^repository:/, "") },
+    };
+    const displayName = name?.trim() || project.displayName?.trim()
+        || slug.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+    const workspaceBindings = workspaces.map(({ scan: workspace }) => ({
+        workspaceRef: workspace.workspaceRef,
+        ...workspace.workspaceIdentity,
+        sourceRevision: workspace.revision.digest,
+    })).sort((a, b) => a.workspaceRef.localeCompare(b.workspaceRef));
     const descriptor = {
         $schema: "https://you.md/schemas/project-brain/v1",
         schemaVersion: "you-md/project-brain/v1",
         kind: "project",
         projectRef: project.projectRef,
         slug,
-        name: name?.trim() || slug.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" "),
+        name: displayName,
+        aliases: [slug],
         contextRoot: project.contextRoot,
-        agentRoots: project.artifacts.filter((artifact) => artifact.kind === "agent").map((artifact) => artifact.path),
+        agentRoots: [...new Set(project.artifacts.filter((artifact) => artifact.kind === "agent").map((artifact) => artifact.path))].sort(),
+        workspaces: workspaceBindings,
+        repositoryBinding: normalizeJson(repositoryBinding),
+        legacySource: project.management === "legacy-adopted"
+            ? { path: ".youmd-project", baseContentHash: project.provenance.sourceRevision, preserved: true }
+            : null,
         artifacts: stripFactProvenance(project),
         relationships: [],
-        writePolicy: { default: "read_only", managedPaths: [], taskWrite: { enabled: false } },
+        writePolicy: { default: "propose", managedPaths: [], taskWrite: { enabled: false } },
         generatedExcludes: [...scan.generatedExcludes],
         provenance: {
-            source: project.management === "legacy-adopted" ? "legacy-adoption" : "declared",
+            source: project.management === "legacy-adopted" ? "legacy-adoption" : "heuristic-adoption",
             descriptorPath: ".you-project",
-            sourceRevision: scan.revision.digest,
+            sourceRevision: baseRevision,
             indexedAt: project.provenance.indexedAt,
             freshness: project.provenance.freshness,
         },
@@ -542,94 +711,161 @@ function adoptionDescriptor(scan, project, name) {
     };
     return normalizeJson(descriptor);
 }
-/** Generate review-only `.you-project` adoption proposals. No target file is created or changed. */
-function proposeProjectBrainAdoption(scan, options = {}) {
+function adoptionSemantics(project) {
+    return (0, canonical_1.canonicalize)({
+        contextRoot: project.contextRoot,
+        artifacts: stripFactProvenance(project).map((artifact) => {
+            const value = artifact;
+            return {
+                artifactRef: value.artifactRef,
+                subjectRef: value.subjectRef,
+                kind: value.kind,
+                path: value.path,
+                owner: value.owner,
+                authority: value.authority,
+                writePolicy: value.writePolicy,
+            };
+        }),
+    });
+}
+function proposalForAdoptionGroup(workspaces, options) {
     const proposals = [];
     const errors = [];
-    const projects = scan.projects.filter((project) => !options.projectRef || project.projectRef === options.projectRef);
-    if (options.projectRef && projects.length === 0)
-        errors.push(proposalError(options.projectRef, "unknown_project", "project is not present in the exact scan"));
-    for (const project of projects) {
-        if (project.management === "declared" || project.descriptorPath === ".you-project") {
-            errors.push(proposalError(project.projectRef, "not_adoptable", "project already has a declared .you-project descriptor"));
-            continue;
-        }
-        if (project.artifacts.length === 0) {
-            errors.push(proposalError(project.projectRef, "not_adoptable", "project has no attributable artifacts for descriptor adoption"));
-            continue;
-        }
-        const descriptor = adoptionDescriptor(scan, project, options.name);
-        const existingDescriptor = project.artifacts.find((artifact) => artifact.path === ".you-project");
-        if (existingDescriptor && !/^sha256:[a-f0-9]{64}$/.test(existingDescriptor.provenance.sourceRevision)) {
-            errors.push(proposalError(project.projectRef, "not_adoptable", "existing .you-project lacks a verified content hash; rescan in content mode"));
-            continue;
-        }
-        const patchResult = existingDescriptor
-            ? (() => {
-                const patch = [{ op: "replace", path: "", value: descriptor }];
-                const normalized = normalizePatch(patch, project.projectRef);
-                if (!normalized.patch)
-                    return { valid: false, errors: normalized.errors };
-                return {
-                    valid: true,
-                    errors: [],
-                    patch: normalized.patch,
-                    patchDigest: digest(normalized.patch),
-                    result: descriptor,
-                    diff: {
-                        format: "rfc6902",
-                        beforeDigest: existingDescriptor.provenance.sourceRevision,
-                        afterDigest: digest(descriptor),
-                        operations: [{
-                                index: 0,
-                                op: "replace",
-                                path: "",
-                                before: { present: true },
-                                after: { present: true, value: descriptor },
-                            }],
-                    },
-                };
-            })()
-            : validateProjectBrainPatch(null, [{ op: "add", path: "", value: descriptor }], project.projectRef);
-        if (!patchResult.valid || !patchResult.patch || !patchResult.patchDigest || !patchResult.diff) {
-            errors.push(...patchResult.errors);
+    const primary = workspaces[0];
+    const { project, scan } = primary;
+    if (workspaces.some(({ project: candidate }) => candidate.management === "declared" || candidate.descriptorPath === ".you-project")) {
+        return { proposals, errors: [proposalError(project.projectRef, "not_adoptable", "project already has a declared .you-project descriptor")] };
+    }
+    if (stripFactProvenance(project).length === 0) {
+        return { proposals, errors: [proposalError(project.projectRef, "not_adoptable", "project has no attributable non-marker artifacts for descriptor adoption")] };
+    }
+    if (!SAFE_RELATIVE_PATH.test(project.contextRoot)
+        || workspaces.some(({ project: candidate }) => candidate.artifacts.some((artifact) => !SAFE_RELATIVE_PATH.test(artifact.path)))) {
+        return { proposals, errors: [proposalError(project.projectRef, "not_adoptable", "project contains an unsafe descriptor path")] };
+    }
+    const repositoryRefs = new Set(workspaces.map(({ scan: candidate }) => candidate.workspaceIdentity.repositoryRef));
+    const bindingRefs = new Set(workspaces.map(({ project: candidate }) => candidate.repositoryBinding?.repositoryRef).filter(Boolean));
+    const githubSubjects = new Set(workspaces.map(({ project: candidate }) => candidate.repositoryBinding?.subjectRef).filter(Boolean));
+    if (repositoryRefs.size !== 1 || bindingRefs.size > 1 || githubSubjects.size > 1
+        || (bindingRefs.size === 1 && !bindingRefs.has(scan.workspaceIdentity.repositoryRef))) {
+        return { proposals, errors: [proposalError(project.projectRef, "identity_conflict", "logical project maps to conflicting repository evidence; owner review is required")] };
+    }
+    const semantics = new Set(workspaces.map(({ project: candidate }) => adoptionSemantics(candidate)));
+    const legacyRevisions = new Set(workspaces
+        .filter(({ project: candidate }) => candidate.management === "legacy-adopted")
+        .map(({ project: candidate }) => candidate.provenance.sourceRevision));
+    if (semantics.size !== 1 || legacyRevisions.size > 1) {
+        return { proposals, errors: [proposalError(project.projectRef, "semantic_review_required", "workspace artifact or legacy-marker claims differ; exact automatic adoption is unsafe")] };
+    }
+    if (project.management === "legacy-adopted" && !/^sha256:[a-f0-9]{64}$/.test(project.provenance.sourceRevision)) {
+        return { proposals, errors: [proposalError(project.projectRef, "not_adoptable", "legacy .youmd-project lacks a verified byte hash; rescan in content mode")] };
+    }
+    const existingDescriptors = workspaces.flatMap(({ project: candidate }) => candidate.artifacts.filter((artifact) => artifact.path === ".you-project"));
+    const existingHashes = new Set(existingDescriptors.map((artifact) => artifact.provenance.sourceRevision));
+    if (existingDescriptors.some((artifact) => !/^sha256:[a-f0-9]{64}$/.test(artifact.provenance.sourceRevision))) {
+        return { proposals, errors: [proposalError(project.projectRef, "not_adoptable", "existing .you-project lacks a verified content hash; rescan in content mode")] };
+    }
+    if (existingHashes.size > 1 || (existingDescriptors.length > 0 && existingDescriptors.length !== workspaces.length)) {
+        return { proposals, errors: [proposalError(project.projectRef, "semantic_review_required", "workspaces do not share the same exact .you-project base")] };
+    }
+    if (existingDescriptors.length !== workspaces.length) {
+        return { proposals, errors: [proposalError(project.projectRef, "not_adoptable", "descriptor adoption apply is replacement-only; create a valid .you-project through an explicit reviewed repository change before adoption")] };
+    }
+    const descriptor = adoptionDescriptor(workspaces, options.name);
+    const existingDescriptor = existingDescriptors[0];
+    const patchResult = (() => {
+        const patch = [{ op: "replace", path: "", value: descriptor }];
+        const normalized = normalizePatch(patch, project.projectRef);
+        if (!normalized.patch)
+            return { valid: false, errors: normalized.errors };
+        return {
+            valid: true,
+            errors: [],
+            patch: normalized.patch,
+            patchDigest: digest(normalized.patch),
+            result: descriptor,
+            diff: {
+                format: "rfc6902",
+                beforeDigest: existingDescriptor.provenance.sourceRevision,
+                afterDigest: digest(descriptor),
+                operations: [{
+                        index: 0,
+                        op: "replace",
+                        path: "",
+                        before: { present: true },
+                        after: { present: true, value: descriptor },
+                    }],
+            },
+        };
+    })();
+    if (!patchResult.valid || !patchResult.patch || !patchResult.patchDigest || !patchResult.diff) {
+        errors.push(...patchResult.errors);
+        return { proposals, errors };
+    }
+    const slug = project.projectRef.slice("project:".length);
+    const baseRevision = adoptionBaseRevision(workspaces);
+    proposals.push(buildProposal({
+        proposalType: "descriptor_adoption",
+        projectRef: project.projectRef,
+        machineRef: scan.workspaceIdentity.machineRef,
+        workspaceRef: scan.workspaceRef,
+        baseRevision,
+        requestedCapability: "brain.descriptor.adopt",
+        patchFormat: "rfc6902",
+        patchDigest: patchResult.patchDigest,
+        rationale: options.rationale?.trim() || `Adopt ${project.projectRef} with a reviewable .you-project descriptor.`,
+        target: {
+            kind: "repository_file",
+            artifactRef: `artifact:${slug}/project-descriptor`,
+            path: ".you-project",
+            owner: "repository",
+            authority: "canonical",
+            humanOwned: true,
+            exists: Boolean(existingDescriptor),
+            baseContentHash: existingDescriptor?.provenance.sourceRevision || digest(null),
+        },
+        patch: patchResult.patch,
+        diff: patchResult.diff,
+        source: {
+            kind: project.management === "legacy-adopted" ? "legacy_marker" : "heuristic_scan",
+            sourceRef: project.provenance.sourceRef,
+            sourceRevision: project.management === "legacy-adopted" ? project.provenance.sourceRevision : baseRevision,
+            ...(project.legacyMarkerPath ? { path: project.legacyMarkerPath } : {}),
+        },
+    }));
+    return { proposals, errors };
+}
+/** Generate review-only replacement proposals for an existing invalid `.you-project`. */
+function proposeProjectBrainAdoptions(scans, options = {}) {
+    const proposals = [];
+    const errors = [];
+    const candidates = scans.flatMap((scan) => scan.projects.map((project) => ({ scan, project })))
+        .filter(({ project }) => !options.projectRef || project.projectRef === options.projectRef)
+        .sort((a, b) => a.project.projectRef.localeCompare(b.project.projectRef)
+        || a.scan.workspaceRef.localeCompare(b.scan.workspaceRef)
+        || a.scan.revision.digest.localeCompare(b.scan.revision.digest));
+    if (options.projectRef && candidates.length === 0) {
+        return { proposals, errors: [proposalError(options.projectRef, "unknown_project", "project is not present in the exact scans")] };
+    }
+    const grouped = new Map();
+    for (const candidate of candidates)
+        grouped.set(candidate.project.projectRef, [...(grouped.get(candidate.project.projectRef) || []), candidate]);
+    for (const [projectRef, workspaces] of [...grouped].sort(([a], [b]) => a.localeCompare(b))) {
+        if (options.name && !options.projectRef && grouped.size > 1) {
+            errors.push(proposalError(projectRef, "semantic_review_required", "--name requires a selected project when adopting multiple logical projects"));
             continue;
         }
-        const slug = project.projectRef.slice("project:".length);
-        proposals.push(buildProposal({
-            proposalType: "descriptor_adoption",
-            projectRef: project.projectRef,
-            machineRef: scan.workspaceIdentity.machineRef,
-            workspaceRef: scan.workspaceRef,
-            baseRevision: scan.revision.digest,
-            requestedCapability: "brain.descriptor.adopt",
-            patchFormat: "rfc6902",
-            patchDigest: patchResult.patchDigest,
-            rationale: options.rationale?.trim() || `Adopt ${project.projectRef} with a reviewable .you-project descriptor.`,
-            target: {
-                kind: "repository_file",
-                artifactRef: `artifact:${slug}/project-descriptor`,
-                path: ".you-project",
-                owner: "repository",
-                authority: "canonical",
-                humanOwned: true,
-                exists: Boolean(existingDescriptor),
-                baseContentHash: existingDescriptor?.provenance.sourceRevision || digest(null),
-            },
-            patch: patchResult.patch,
-            diff: patchResult.diff,
-            source: {
-                kind: project.management === "legacy-adopted" ? "legacy_marker" : "heuristic_scan",
-                sourceRef: project.provenance.sourceRef,
-                sourceRevision: project.provenance.sourceRevision,
-                ...(project.legacyMarkerPath ? { path: project.legacyMarkerPath } : {}),
-            },
-        }));
+        const generated = proposalForAdoptionGroup(workspaces, options);
+        proposals.push(...generated.proposals);
+        errors.push(...generated.errors);
     }
-    proposals.sort((a, b) => a.proposalRef.localeCompare(b.proposalRef));
+    proposals.sort((a, b) => a.projectRef.localeCompare(b.projectRef) || a.proposalRef.localeCompare(b.proposalRef));
     errors.sort((a, b) => a.sourceRef.localeCompare(b.sourceRef) || a.code.localeCompare(b.code));
     return { proposals, errors };
 }
+function proposeProjectBrainAdoption(scan, options = {}) {
+    return proposeProjectBrainAdoptions([scan], options);
+}
 function parseOverride(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return null;