@straiffi/archon 1.4.12 → 1.6.0

package/dist/server/lib/projectMemory.js

@@ -1,5 +1,7 @@
-import { randomUUID } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import db from '../db.js';
+import { containsReservedProjectMemoryControlMarker, PROJECT_MEMORY_LIMITS } from './projectMemoryLimits.js';
+import { encodeProjectMemoryCursor } from './projectMemoryCursor.js';
 const PROJECT_MEMORY_STAGES = ['plan', 'build', 'review', 'follow_up', 'plan_follow_up', 'chat'];
 const PROJECT_CONVENTION_PRIORITIES = ['critical', 'normal', 'low'];
 const PROJECT_CONVENTION_INJECTION_MODES = ['always', 'relevant'];
@@ -9,6 +11,11 @@ const PROJECT_MEMORY_SOURCES = ['manual', 'agent'];
 const PROJECT_MEMORY_SUGGESTION_KINDS = ['decision', 'convention'];
 const PROJECT_MEMORY_SUGGESTION_STATUSES = ['pending', 'accepted', 'dismissed', 'applied_to_existing'];
 const PROJECT_MEMORY_SUGGESTION_DUPLICATE_KINDS = ['none', 'near_duplicate'];
+const PROJECT_MEMORY_SUGGESTION_DISMISSAL_REASONS = ['incorrect', 'not_durable', 'already_captured', 'too_broad', 'not_useful', 'other'];
+const PROJECT_MEMORY_SUGGESTION_RECOMMENDATION_ACTIONS = ['create', 'update', 'supersede'];
+const PROJECT_MEMORY_SUGGESTION_CONFIDENCES = ['low', 'medium', 'high'];
+const PROJECT_MEMORY_SUGGESTION_FINGERPRINT_VERSION = 'v1';
+const PROJECT_MEMORY_SUGGESTION_DISMISSAL_COOLDOWN_DAYS = 90;
 const PROJECT_CONTEXT_SCAN_STATUSES = ['pending', 'running', 'done', 'error'];
 const PROJECT_CONTEXT_ARTIFACT_KINDS = ['architecture', 'key_areas', 'conventions', 'risks'];
 const ACCEPTED_PROJECT_DECISION_STATUS = 'accepted';
@@ -77,6 +84,8 @@ const ACCEPTED_MEMORY_COMPARISON_STOPWORDS = new Set([
     'with',
     'without',
 ]);
+class ProjectMemoryLifecycleConflictError extends Error {
+}
 const parseStringArray = (value) => {
     if (!value) {
         return [];
@@ -178,28 +187,40 @@ const normalizeOptionalString = (value, fieldName) => {
         return { values: null };
     }
     if (typeof value !== 'string') {
-        return { error: `${fieldName} must be a string` };
+        return { error: `${fieldName} must be a string`, code: 'invalid_field', field: fieldName };
     }
     const trimmed = value.trim();
     return { values: trimmed === '' ? null : trimmed };
 };
 const validateRequiredString = (value, fieldName) => {
     if (typeof value !== 'string' || value.trim() === '') {
-        return { error: `${fieldName} must be a non-empty string` };
+        return { error: `${fieldName} must be a non-empty string`, code: 'invalid_field', field: fieldName };
     }
     return { values: value.trim() };
 };
+const validateMemoryString = (result, field, limit) => {
+    if ('error' in result) {
+        return result;
+    }
+    if (result.values !== null && result.values.length > limit) {
+        return { error: `${field} must not exceed ${limit} characters`, code: 'field_too_large', field, limit };
+    }
+    if (result.values !== null && containsReservedProjectMemoryControlMarker(result.values)) {
+        return { error: `${field} must not contain a reserved control marker`, code: 'reserved_control_marker', field };
+    }
+    return result;
+};
 const validateStages = (value) => {
     if (value == null) {
         return { values: null };
     }
     if (!Array.isArray(value)) {
-        return { error: 'stages must be an array of valid project memory stages' };
+        return { error: 'stages must be an array of valid project memory stages', code: 'invalid_field', field: 'stages' };
     }
     const normalized = [];
     for (const stage of value) {
         if (!PROJECT_MEMORY_STAGES.includes(stage)) {
-            return { error: 'stages must be an array of valid project memory stages' };
+            return { error: 'stages must be an array of valid project memory stages', code: 'invalid_field', field: 'stages' };
         }
         if (!normalized.includes(stage)) {
             normalized.push(stage);
@@ -207,15 +228,40 @@ const validateStages = (value) => {
     }
     return { values: normalized.length > 0 ? JSON.stringify(normalized) : null };
 };
+const validateApplicabilityStrings = (value, field) => {
+    if (value == null) {
+        return { values: null };
+    }
+    if (!Array.isArray(value)) {
+        return { error: `${field} must be an array of non-empty strings`, code: 'invalid_field', field };
+    }
+    if (value.length > PROJECT_MEMORY_LIMITS.applicabilityItems) {
+        return { error: `${field} must not contain more than ${PROJECT_MEMORY_LIMITS.applicabilityItems} items`, code: 'field_too_large', field, limit: PROJECT_MEMORY_LIMITS.applicabilityItems };
+    }
+    const normalized = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            return { error: `${field} must be an array of non-empty strings`, code: 'invalid_field', field };
+        }
+        const result = validateMemoryString({ values: entry.trim() }, field, PROJECT_MEMORY_LIMITS.applicabilityItem);
+        if ('error' in result) {
+            return result;
+        }
+        if (!normalized.includes(result.values)) {
+            normalized.push(result.values);
+        }
+    }
+    return { values: normalized.length > 0 ? JSON.stringify(normalized) : null };
+};
 const validatePriority = (value) => {
     if (!PROJECT_CONVENTION_PRIORITIES.includes(value)) {
-        return { error: 'priority must be one of critical, normal, or low' };
+        return { error: 'priority must be one of critical, normal, or low', code: 'invalid_field', field: 'priority' };
     }
     return { values: value };
 };
 const validateConventionInjectionMode = (value) => {
     if (!PROJECT_CONVENTION_INJECTION_MODES.includes(value)) {
-        return { error: 'injection_mode must be one of always or relevant' };
+        return { error: 'injection_mode must be one of always or relevant', code: 'invalid_field', field: 'injection_mode' };
     }
     return { values: value };
 };
@@ -224,20 +270,125 @@ const validateImplications = (value) => {
         return { values: null };
     }
     if (!Array.isArray(value)) {
-        return { error: 'implications must be an array of non-empty strings' };
+        return { error: 'implications must be an array of non-empty strings', code: 'invalid_field', field: 'implications' };
+    }
+    if (value.length > PROJECT_MEMORY_LIMITS.implications) {
+        return { error: `implications must not contain more than ${PROJECT_MEMORY_LIMITS.implications} items`, code: 'field_too_large', field: 'implications', limit: PROJECT_MEMORY_LIMITS.implications };
     }
     const normalized = [];
     for (const implication of value) {
         if (typeof implication !== 'string' || implication.trim() === '') {
-            return { error: 'implications must be an array of non-empty strings' };
+            return { error: 'implications must be an array of non-empty strings', code: 'invalid_field', field: 'implications' };
         }
         const trimmed = implication.trim();
+        const validation = validateMemoryString({ values: trimmed }, 'implications', PROJECT_MEMORY_LIMITS.implication);
+        if ('error' in validation) {
+            return validation;
+        }
         if (!normalized.includes(trimmed)) {
             normalized.push(trimmed);
         }
     }
     return { values: normalized.length > 0 ? JSON.stringify(normalized) : null };
 };
+const createManualProjectMemoryOrigin = () => ({
+    type: 'manual',
+    suggestion_id: null,
+    source_stage: null,
+    source_type: null,
+    source_label: null,
+    ticket_id: null,
+    chat_session_id: null,
+    spec_session_id: null,
+    suggested_at: null,
+    accepted_at: new Date().toISOString(),
+});
+const getProjectMemoryOriginSourceAvailable = (projectId, origin) => {
+    if (origin.source_type === 'ticket' && origin.ticket_id) {
+        return Boolean(db.prepare('SELECT 1 FROM tickets WHERE id = ? AND project_id = ?').get(origin.ticket_id, projectId));
+    }
+    if (origin.source_type === 'chat_session' && origin.chat_session_id) {
+        return Boolean(db.prepare('SELECT 1 FROM chat_sessions WHERE id = ? AND project_id = ?').get(origin.chat_session_id, projectId));
+    }
+    if (origin.source_type === 'spec_session' && origin.spec_session_id) {
+        return Boolean(db.prepare('SELECT 1 FROM spec_sessions WHERE id = ? AND project_id = ?').get(origin.spec_session_id, projectId));
+    }
+    return false;
+};
+const parseProjectMemoryOrigin = (projectId, originJson, createdAt) => {
+    const manualOrigin = {
+        ...createManualProjectMemoryOrigin(),
+        accepted_at: createdAt,
+        source_available: false,
+    };
+    if (!originJson) {
+        return manualOrigin;
+    }
+    try {
+        const value = JSON.parse(originJson);
+        if (value.type !== 'agent_suggestion') {
+            return manualOrigin;
+        }
+        const sourceType = value.source_type === 'ticket' || value.source_type === 'chat_session' || value.source_type === 'spec_session'
+            ? value.source_type
+            : null;
+        const origin = {
+            type: 'agent_suggestion',
+            suggestion_id: typeof value.suggestion_id === 'string' ? value.suggestion_id : null,
+            source_stage: PROJECT_MEMORY_STAGES.includes(value.source_stage) ? value.source_stage : null,
+            source_type: sourceType,
+            source_label: typeof value.source_label === 'string' ? value.source_label : null,
+            ticket_id: typeof value.ticket_id === 'string' ? value.ticket_id : null,
+            chat_session_id: typeof value.chat_session_id === 'string' ? value.chat_session_id : null,
+            spec_session_id: typeof value.spec_session_id === 'string' ? value.spec_session_id : null,
+            suggested_at: typeof value.suggested_at === 'string' ? value.suggested_at : null,
+            accepted_at: typeof value.accepted_at === 'string' ? value.accepted_at : createdAt,
+        };
+        return {
+            ...origin,
+            source_available: getProjectMemoryOriginSourceAvailable(projectId, origin),
+        };
+    }
+    catch {
+        return manualOrigin;
+    }
+};
+const createProjectMemorySuggestionOrigin = (projectId, suggestion) => {
+    const source = suggestion.ticket_id
+        ? {
+            type: 'ticket',
+            id: suggestion.ticket_id,
+            row: db.prepare('SELECT title FROM tickets WHERE id = ? AND project_id = ?').get(suggestion.ticket_id, projectId),
+        }
+        : suggestion.chat_session_id
+            ? {
+                type: 'chat_session',
+                id: suggestion.chat_session_id,
+                row: db.prepare('SELECT title FROM chat_sessions WHERE id = ? AND project_id = ?').get(suggestion.chat_session_id, projectId),
+            }
+            : suggestion.spec_session_id
+                ? {
+                    type: 'spec_session',
+                    id: suggestion.spec_session_id,
+                    row: db.prepare('SELECT title FROM spec_sessions WHERE id = ? AND project_id = ?').get(suggestion.spec_session_id, projectId),
+                }
+                : null;
+    if (!source?.row) {
+        return null;
+    }
+    return {
+        type: 'agent_suggestion',
+        suggestion_id: suggestion.id,
+        source_stage: suggestion.source_stage,
+        source_type: source.type,
+        source_label: source.row.title,
+        ticket_id: source.type === 'ticket' ? source.id : null,
+        chat_session_id: source.type === 'chat_session' ? source.id : null,
+        spec_session_id: source.type === 'spec_session' ? source.id : null,
+        suggested_at: suggestion.created_at,
+        accepted_at: new Date().toISOString(),
+    };
+};
 const serializeConvention = (row) => {
     return {
         id: row.id,
@@ -247,15 +398,52 @@ const serializeConvention = (row) => {
         instruction: row.instruction,
         rationale: row.rationale,
         stages: parseStringArray(row.stages_json).filter((stage) => PROJECT_MEMORY_STAGES.includes(stage)),
+        path_globs: parseStringArray(row.path_globs_json),
+        component_tags: parseStringArray(row.component_tags_json),
         priority: row.priority,
         injection_mode: PROJECT_CONVENTION_INJECTION_MODES.includes(row.injection_mode)
             ? row.injection_mode
             : 'relevant',
         status: row.status,
+        origin: parseProjectMemoryOrigin(row.project_id, row.origin_json, row.created_at),
         created_at: row.created_at,
         updated_at: row.updated_at,
     };
 };
+const normalizeConflictText = (value) => String(value ?? '')
+    .normalize('NFKC')
+    .trim()
+    .toLocaleLowerCase('en-US')
+    .replace(/\s+/gu, ' ');
+export const detectProjectMemoryConflicts = (decisions, conventions) => {
+    const conflicts = [];
+    const active = [
+        ...decisions.filter(item => item.status === ACCEPTED_PROJECT_DECISION_STATUS).map(item => ({ ...item, kind: 'decision', content: item.decision })),
+        ...conventions.filter(item => item.status === 'active').map(item => ({ ...item, kind: 'convention', content: item.instruction })),
+    ].sort((left, right) => left.id.localeCompare(right.id));
+    for (let leftIndex = 0; leftIndex < active.length; leftIndex += 1) {
+        const left = active[leftIndex];
+        for (let rightIndex = leftIndex + 1; rightIndex < active.length; rightIndex += 1) {
+            const right = active[rightIndex];
+            if (left.kind !== right.kind || normalizeConflictText(left.title) !== normalizeConflictText(right.title) || normalizeConflictText(left.scope) !== normalizeConflictText(right.scope)) {
+                continue;
+            }
+            const memoryIds = [left.id, right.id].sort();
+            if (left.kind === 'convention' && right.kind === 'convention' && left.priority === 'critical' && right.priority === 'critical' && left.injection_mode === 'always' && right.injection_mode === 'always') {
+                conflicts.push({ code: 'duplicate_critical_convention', memory_ids: memoryIds, message: 'Critical always-on conventions share the same title and scope.' });
+            }
+            else if (normalizeConflictText(left.content) !== normalizeConflictText(right.content)) {
+                conflicts.push({ code: 'different_content', memory_ids: memoryIds, message: 'Active memories share the same title and scope but have different content.' });
+            }
+        }
+    }
+    for (const decision of decisions.filter(item => item.status === ACCEPTED_PROJECT_DECISION_STATUS && item.superseded_by_decision_id)) {
+        if (decisions.some(candidate => candidate.id === decision.superseded_by_decision_id && candidate.status === ACCEPTED_PROJECT_DECISION_STATUS)) {
+            conflicts.push({ code: 'active_replacement', memory_ids: [decision.id, decision.superseded_by_decision_id], message: 'The replacement for this restored decision is still active.' });
+        }
+    }
+    return conflicts.sort((left, right) => left.code.localeCompare(right.code) || left.memory_ids.join('\0').localeCompare(right.memory_ids.join('\0')));
+};
 const serializeDecision = (row) => {
     return {
         id: row.id,
@@ -265,7 +453,12 @@ const serializeDecision = (row) => {
         decision: row.decision,
         rationale: row.rationale,
         implications: parseStringArray(row.implications_json),
+        stages: parseStringArray(row.stages_json).filter((stage) => PROJECT_MEMORY_STAGES.includes(stage)),
+        path_globs: parseStringArray(row.path_globs_json),
+        component_tags: parseStringArray(row.component_tags_json),
         status: row.status,
+        superseded_by_decision_id: row.superseded_by_decision_id,
+        origin: parseProjectMemoryOrigin(row.project_id, row.origin_json, row.created_at),
         created_at: row.created_at,
         updated_at: row.updated_at,
     };
@@ -276,19 +469,22 @@ export const serializeProjectMemoryFromConventionValue = (convention) => {
         project_id: convention.project_id,
         kind: 'convention',
         state: convention.status === 'active' ? 'active' : 'archived',
-        source: 'manual',
+        source: convention.origin?.type === 'agent_suggestion' ? 'agent' : 'manual',
         title: convention.title,
         scope: convention.scope,
         content: convention.instruction,
         rationale: convention.rationale,
         implications: [],
         stages: convention.stages,
+        path_globs: convention.path_globs,
+        component_tags: convention.component_tags,
         priority: convention.priority,
         injection_mode: convention.injection_mode,
-        source_stage: null,
-        ticket_id: null,
-        chat_session_id: null,
-        spec_session_id: null,
+        origin: convention.origin ?? parseProjectMemoryOrigin(convention.project_id, null, convention.created_at),
+        source_stage: convention.origin?.source_stage ?? null,
+        ticket_id: convention.origin?.ticket_id ?? null,
+        chat_session_id: convention.origin?.chat_session_id ?? null,
+        spec_session_id: convention.origin?.spec_session_id ?? null,
         duplicate_match: null,
         created_at: convention.created_at,
         updated_at: convention.updated_at,
@@ -303,19 +499,22 @@ export const serializeProjectMemoryFromDecisionValue = (decision) => {
         project_id: decision.project_id,
         kind: 'decision',
         state: decision.status === 'accepted' ? 'active' : decision.status,
-        source: 'manual',
+        source: decision.origin?.type === 'agent_suggestion' ? 'agent' : 'manual',
         title: decision.title,
         scope: decision.scope,
         content: decision.decision,
         rationale: decision.rationale,
         implications: decision.implications,
-        stages: [],
+        stages: decision.stages,
+        path_globs: decision.path_globs,
+        component_tags: decision.component_tags,
         priority: null,
         injection_mode: null,
-        source_stage: null,
-        ticket_id: null,
-        chat_session_id: null,
-        spec_session_id: null,
+        origin: decision.origin ?? parseProjectMemoryOrigin(decision.project_id, null, decision.created_at),
+        source_stage: decision.origin?.source_stage ?? null,
+        ticket_id: decision.origin?.ticket_id ?? null,
+        chat_session_id: decision.origin?.chat_session_id ?? null,
+        spec_session_id: decision.origin?.spec_session_id ?? null,
         duplicate_match: null,
         created_at: decision.created_at,
         updated_at: decision.updated_at,
@@ -336,6 +535,7 @@ const parseJsonValue = (value) => {
     }
 };
 const serializeProjectContextScan = (row) => {
+    const part8Row = row;
     return {
         id: row.id,
         project_id: row.project_id,
@@ -344,6 +544,12 @@ const serializeProjectContextScan = (row) => {
             : 'error',
         repo_head: row.repo_head,
         repo_branch: row.repo_branch,
+        scanned_at: part8Row.scanned_at === undefined ? row.created_at : part8Row.scanned_at,
+        completed_at: part8Row.completed_at === undefined && row.status === 'done' ? row.updated_at : part8Row.completed_at ?? null,
+        working_tree_dirty: part8Row.working_tree_dirty == null ? null : Boolean(part8Row.working_tree_dirty),
+        manifest: parseJsonValue(part8Row.manifest_json),
+        scanner_provider: part8Row.scanner_provider ?? null,
+        origin: part8Row.origin === 'archive_import' ? 'archive_import' : 'local_scan',
         scanner_tool: row.scanner_tool === 'claude' || row.scanner_tool === 'opencode' ? row.scanner_tool : null,
         scanner_model: row.scanner_model,
         scanner_variant: row.scanner_variant,
@@ -383,6 +589,14 @@ const parseProjectMemorySuggestionDetails = (value) => {
 };
 const parseProjectMemorySuggestionValues = (row) => {
     const details = parseProjectMemorySuggestionDetails(row.details_json);
+    const evidence = details.evidence && typeof details.evidence === 'object' && !Array.isArray(details.evidence)
+        ? details.evidence
+        : null;
+    const recommendation = details.recommendation && typeof details.recommendation === 'object' && !Array.isArray(details.recommendation)
+        ? details.recommendation
+        : null;
+    const pathGlobs = Array.isArray(details.path_globs) ? details.path_globs.filter((value) => typeof value === 'string') : [];
+    const componentTags = Array.isArray(details.component_tags) ? details.component_tags.filter((value) => typeof value === 'string') : [];
     if (row.kind === 'decision') {
         const implications = Array.isArray(details.implications)
             ? details.implications
@@ -398,6 +612,11 @@ const parseProjectMemorySuggestionValues = (row) => {
             decision: row.content_text,
             rationale: row.rationale,
             implications,
+            stages: Array.isArray(details.stages) ? details.stages.filter((value) => PROJECT_MEMORY_STAGES.includes(value)) : [],
+            path_globs: pathGlobs,
+            component_tags: componentTags,
+            evidence,
+            recommendation,
         };
     }
     if (row.kind === 'convention') {
@@ -421,6 +640,10 @@ const parseProjectMemorySuggestionValues = (row) => {
             stages,
             priority,
             injection_mode: injectionMode,
+            path_globs: pathGlobs,
+            component_tags: componentTags,
+            evidence,
+            recommendation,
         };
     }
     return null;
@@ -434,15 +657,21 @@ const getProjectMemorySuggestionTextParts = (suggestion) => {
 export const getProjectMemorySuggestionDedupeKey = (suggestion) => {
     const baseParts = [
         suggestion.kind,
-        suggestion.title.toLowerCase(),
-        suggestion.scope?.toLowerCase() ?? '',
-        getProjectMemorySuggestionContent(suggestion).toLowerCase(),
+        suggestion.title.normalize('NFKC').toLocaleLowerCase('en-US').replace(/\s+/gu, ' ').trim(),
+        suggestion.scope?.normalize('NFKC').toLocaleLowerCase('en-US').replace(/\s+/gu, ' ').trim() ?? '',
+        getProjectMemorySuggestionContent(suggestion).normalize('NFKC').toLocaleLowerCase('en-US').replace(/\s+/gu, ' ').trim(),
+        (suggestion.stages ?? []).slice().sort().join(','),
+        (suggestion.path_globs ?? []).map(value => value.normalize('NFKC').toLocaleLowerCase('en-US')).sort().join(','),
+        (suggestion.component_tags ?? []).map(value => value.normalize('NFKC').toLocaleLowerCase('en-US')).sort().join(','),
     ];
     if (suggestion.kind === 'convention') {
-        baseParts.push(suggestion.stages.join(','), suggestion.priority);
+        baseParts.push(suggestion.priority, suggestion.injection_mode);
     }
     return baseParts.join('::');
 };
+export const getProjectMemorySuggestionFingerprint = (projectId, suggestion) => {
+    return `${PROJECT_MEMORY_SUGGESTION_FINGERPRINT_VERSION}:${createHash('sha256').update(`${projectId}\0${getProjectMemorySuggestionDedupeKey(suggestion)}`).digest('hex')}`;
+};
 const serializeProjectMemorySuggestion = (row) => {
     const values = parseProjectMemorySuggestionValues(row);
     if (!values) {
@@ -468,7 +697,14 @@ const serializeProjectMemorySuggestion = (row) => {
             decision: values.decision,
             rationale: values.rationale,
             implications: values.implications,
+            stages: values.stages ?? [],
+            path_globs: values.path_globs ?? [],
+            component_tags: values.component_tags ?? [],
+            evidence: values.evidence ?? null,
+            recommendation: values.recommendation ?? null,
+            dismissal_reason: PROJECT_MEMORY_SUGGESTION_DISMISSAL_REASONS.includes(row.dismissal_reason) ? row.dismissal_reason : null,
             status: row.status,
+            resolved_memory_id: row.resolved_memory_id,
             duplicate_match: duplicateDecision
                 ? {
                     type: 'near_duplicate',
@@ -497,7 +733,13 @@ const serializeProjectMemorySuggestion = (row) => {
         stages: values.stages,
         priority: values.priority,
         injection_mode: values.injection_mode,
+        path_globs: values.path_globs ?? [],
+        component_tags: values.component_tags ?? [],
+        evidence: values.evidence ?? null,
+        recommendation: values.recommendation ?? null,
+        dismissal_reason: PROJECT_MEMORY_SUGGESTION_DISMISSAL_REASONS.includes(row.dismissal_reason) ? row.dismissal_reason : null,
         status: row.status,
+        resolved_memory_id: row.resolved_memory_id,
         duplicate_match: duplicateConvention
             ? {
                 type: 'near_duplicate',
@@ -529,9 +771,12 @@ export const serializeProjectMemoryFromSuggestionValue = (suggestion) => {
             content: suggestion.decision,
             rationale: suggestion.rationale,
             implications: suggestion.implications,
-            stages: [],
+            stages: suggestion.stages,
+            path_globs: suggestion.path_globs,
+            component_tags: suggestion.component_tags,
             priority: null,
             injection_mode: null,
+            origin: null,
             source_stage: suggestion.source_stage,
             ticket_id: suggestion.ticket_id,
             chat_session_id: suggestion.chat_session_id,
@@ -561,8 +806,11 @@ export const serializeProjectMemoryFromSuggestionValue = (suggestion) => {
         rationale: suggestion.rationale,
         implications: [],
         stages: suggestion.stages,
+        path_globs: suggestion.path_globs,
+        component_tags: suggestion.component_tags,
         priority: suggestion.priority,
         injection_mode: suggestion.injection_mode,
+        origin: null,
         source_stage: suggestion.source_stage,
         ticket_id: suggestion.ticket_id,
         chat_session_id: suggestion.chat_session_id,
@@ -637,14 +885,20 @@ export const createProjectContextScan = (projectId, values) => {
       status,
       repo_head,
       repo_branch,
+      scanned_at,
+      completed_at,
+      working_tree_dirty,
+      manifest_json,
+      scanner_provider,
+      origin,
       scanner_tool,
       scanner_model,
       scanner_variant,
       summary_markdown,
       error
     )
-    VALUES (?, ?, 'pending', ?, ?, ?, ?, ?, NULL, NULL)
-  `).run(id, projectId, values.repo_head, values.repo_branch, values.scanner_tool, values.scanner_model, values.scanner_variant);
+    VALUES (?, ?, 'pending', ?, ?, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, NULL, NULL)
+  `).run(id, projectId, values.repo_head, values.repo_branch, values.scanner_provider, values.origin, values.scanner_tool, values.scanner_model, values.scanner_variant);
     return getProjectContextScanById(projectId, id);
 };
 export const updateProjectContextScan = (projectId, scanId, values) => {
@@ -657,6 +911,12 @@ export const updateProjectContextScan = (projectId, scanId, values) => {
     SET status = ?,
         repo_head = ?,
         repo_branch = ?,
+        scanned_at = ?,
+        completed_at = ?,
+        working_tree_dirty = ?,
+        manifest_json = ?,
+        scanner_provider = ?,
+        origin = ?,
         scanner_tool = ?,
         scanner_model = ?,
         scanner_variant = ?,
@@ -665,7 +925,7 @@ export const updateProjectContextScan = (projectId, scanId, values) => {
         updated_at = CURRENT_TIMESTAMP
     WHERE id = ?
       AND project_id = ?
-  `).run(values.status ?? current.status, Object.hasOwn(values, 'repo_head') ? values.repo_head : current.repo_head, Object.hasOwn(values, 'repo_branch') ? values.repo_branch : current.repo_branch, Object.hasOwn(values, 'scanner_tool') ? values.scanner_tool : current.scanner_tool, Object.hasOwn(values, 'scanner_model') ? values.scanner_model : current.scanner_model, Object.hasOwn(values, 'scanner_variant') ? values.scanner_variant : current.scanner_variant, Object.hasOwn(values, 'summary_markdown') ? values.summary_markdown : current.summary_markdown, Object.hasOwn(values, 'error') ? values.error : current.error, scanId, projectId);
+  `).run(values.status ?? current.status, Object.hasOwn(values, 'repo_head') ? values.repo_head : current.repo_head, Object.hasOwn(values, 'repo_branch') ? values.repo_branch : current.repo_branch, Object.hasOwn(values, 'scanned_at') ? values.scanned_at : current.scanned_at, Object.hasOwn(values, 'completed_at') ? values.completed_at : current.completed_at, Object.hasOwn(values, 'working_tree_dirty') ? values.working_tree_dirty == null ? null : Number(values.working_tree_dirty) : (current.working_tree_dirty == null ? null : Number(current.working_tree_dirty)), Object.hasOwn(values, 'manifest') ? JSON.stringify(values.manifest) : JSON.stringify(current.manifest ?? null), Object.hasOwn(values, 'scanner_provider') ? values.scanner_provider : current.scanner_provider, Object.hasOwn(values, 'origin') ? values.origin : current.origin ?? 'local_scan', Object.hasOwn(values, 'scanner_tool') ? values.scanner_tool : current.scanner_tool, Object.hasOwn(values, 'scanner_model') ? values.scanner_model : current.scanner_model, Object.hasOwn(values, 'scanner_variant') ? values.scanner_variant : current.scanner_variant, Object.hasOwn(values, 'summary_markdown') ? values.summary_markdown : current.summary_markdown, Object.hasOwn(values, 'error') ? values.error : current.error, scanId, projectId);
     return getProjectContextScanById(projectId, scanId);
 };
 export const replaceProjectContextArtifacts = (projectId, scanId, artifacts) => {
@@ -691,6 +951,38 @@ export const replaceProjectContextArtifacts = (projectId, scanId, artifacts) =>
     transaction(artifacts);
     return listProjectContextArtifactsForScan(projectId, scanId);
 };
+export const completeProjectContextScan = (projectId, scanId, values) => {
+    const removeArtifacts = db.prepare('DELETE FROM project_context_artifacts WHERE scan_id = ? AND project_id = ?');
+    const insertArtifact = db.prepare(`
+    INSERT INTO project_context_artifacts (
+      id, scan_id, project_id, kind, title, content_json, content_markdown
+    ) VALUES (?, ?, ?, ?, ?, ?, ?)
+  `);
+    const completeScan = db.prepare(`
+    UPDATE project_context_scans
+    SET status = 'done',
+        summary_markdown = ?,
+        completed_at = ?,
+        manifest_json = ?,
+        error = NULL,
+        updated_at = CURRENT_TIMESTAMP
+    WHERE id = ?
+      AND project_id = ?
+      AND status = 'running'
+  `);
+    const transaction = db.transaction(() => {
+        removeArtifacts.run(scanId, projectId);
+        for (const artifact of values.artifacts) {
+            insertArtifact.run(randomUUID(), scanId, projectId, artifact.kind, artifact.title, artifact.content_json, artifact.content_markdown);
+        }
+        const completed = completeScan.run(values.summary_markdown, values.completed_at, JSON.stringify(values.manifest), scanId, projectId);
+        if (completed.changes !== 1) {
+            throw new Error('The project context scan could not be completed from its current state.');
+        }
+    });
+    transaction();
+    return getProjectContextScanById(projectId, scanId);
+};
 export const listProjectContextArtifactsForScan = (projectId, scanId) => {
     const rows = db.prepare(`
     SELECT *
@@ -708,28 +1000,51 @@ export const listLatestSuccessfulProjectContextArtifacts = (projectId) => {
     }
     return listProjectContextArtifactsForScan(projectId, scan.id);
 };
+export const listProjectContextScans = (projectId, { limit, cursor = null }) => {
+    const boundedLimit = Math.max(1, Math.min(limit, 100));
+    const rows = db.prepare(`
+    SELECT *
+    FROM project_context_scans
+    WHERE project_id = ?
+      AND (
+        ? IS NULL
+        OR created_at < ?
+        OR (created_at = ? AND id < ?)
+      )
+    ORDER BY created_at DESC, id DESC
+    LIMIT ?
+  `).all(projectId, cursor?.createdAt ?? null, cursor?.createdAt ?? null, cursor?.createdAt ?? null, cursor?.id ?? null, boundedLimit + 1);
+    const pageRows = rows.slice(0, boundedLimit);
+    const lastRow = pageRows.at(-1);
+    return {
+        scans: pageRows.map(serializeProjectContextScan),
+        nextCursor: rows.length > boundedLimit && lastRow
+            ? encodeProjectMemoryCursor({ createdAt: lastRow.created_at, id: lastRow.id })
+            : null,
+    };
+};
 export const validateProjectConventionPayload = (body, { partial = false } = {}) => {
     if (!body || typeof body !== 'object' || Array.isArray(body)) {
-        return { error: 'Invalid convention payload' };
+        return { error: 'Invalid convention payload', code: 'invalid_field' };
     }
     const input = body;
     const values = {};
     if (!partial || Object.hasOwn(input, 'title')) {
-        const result = validateRequiredString(input.title, 'title');
+        const result = validateMemoryString(validateRequiredString(input.title, 'title'), 'title', PROJECT_MEMORY_LIMITS.title);
         if ('error' in result) {
             return result;
         }
         values.title = result.values;
     }
     if (!partial || Object.hasOwn(input, 'instruction')) {
-        const result = validateRequiredString(input.instruction, 'instruction');
+        const result = validateMemoryString(validateRequiredString(input.instruction, 'instruction'), 'instruction', PROJECT_MEMORY_LIMITS.content);
         if ('error' in result) {
             return result;
         }
         values.instruction = result.values;
     }
     if (Object.hasOwn(input, 'scope')) {
-        const result = normalizeOptionalString(input.scope, 'scope');
+        const result = validateMemoryString(normalizeOptionalString(input.scope, 'scope'), 'scope', PROJECT_MEMORY_LIMITS.scope);
         if ('error' in result) {
             return result;
         }
@@ -739,7 +1054,7 @@ export const validateProjectConventionPayload = (body, { partial = false } = {})
         values.scope = null;
     }
     if (Object.hasOwn(input, 'rationale')) {
-        const result = normalizeOptionalString(input.rationale, 'rationale');
+        const result = validateMemoryString(normalizeOptionalString(input.rationale, 'rationale'), 'rationale', PROJECT_MEMORY_LIMITS.rationale);
         if ('error' in result) {
             return result;
         }
@@ -758,6 +1073,18 @@ export const validateProjectConventionPayload = (body, { partial = false } = {})
     else if (!partial) {
         values.stages_json = null;
     }
+    for (const field of ['path_globs', 'component_tags']) {
+        if (Object.hasOwn(input, field)) {
+            const result = validateApplicabilityStrings(input[field], field);
+            if ('error' in result) {
+                return result;
+            }
+            values[`${field}_json`] = result.values;
+        }
+        else if (!partial) {
+            values[`${field}_json`] = null;
+        }
+    }
     if (Object.hasOwn(input, 'priority')) {
         const result = validatePriority(input.priority);
         if ('error' in result) {
@@ -782,26 +1109,26 @@ export const validateProjectConventionPayload = (body, { partial = false } = {})
 };
 export const validateProjectDecisionPayload = (body, { partial = false } = {}) => {
     if (!body || typeof body !== 'object' || Array.isArray(body)) {
-        return { error: 'Invalid decision payload' };
+        return { error: 'Invalid decision payload', code: 'invalid_field' };
     }
     const input = body;
     const values = {};
     if (!partial || Object.hasOwn(input, 'title')) {
-        const result = validateRequiredString(input.title, 'title');
+        const result = validateMemoryString(validateRequiredString(input.title, 'title'), 'title', PROJECT_MEMORY_LIMITS.title);
         if ('error' in result) {
             return result;
         }
         values.title = result.values;
     }
     if (!partial || Object.hasOwn(input, 'decision')) {
-        const result = validateRequiredString(input.decision, 'decision');
+        const result = validateMemoryString(validateRequiredString(input.decision, 'decision'), 'decision', PROJECT_MEMORY_LIMITS.content);
         if ('error' in result) {
             return result;
         }
         values.decision = result.values;
     }
     if (Object.hasOwn(input, 'scope')) {
-        const result = normalizeOptionalString(input.scope, 'scope');
+        const result = validateMemoryString(normalizeOptionalString(input.scope, 'scope'), 'scope', PROJECT_MEMORY_LIMITS.scope);
         if ('error' in result) {
             return result;
         }
@@ -811,7 +1138,7 @@ export const validateProjectDecisionPayload = (body, { partial = false } = {}) =
         values.scope = null;
     }
     if (Object.hasOwn(input, 'rationale')) {
-        const result = normalizeOptionalString(input.rationale, 'rationale');
+        const result = validateMemoryString(normalizeOptionalString(input.rationale, 'rationale'), 'rationale', PROJECT_MEMORY_LIMITS.rationale);
         if ('error' in result) {
             return result;
         }
@@ -830,15 +1157,78 @@ export const validateProjectDecisionPayload = (body, { partial = false } = {}) =
     else if (!partial) {
         values.implications_json = null;
     }
+    if (Object.hasOwn(input, 'stages')) {
+        const result = validateStages(input.stages);
+        if ('error' in result) {
+            return result;
+        }
+        values.stages_json = result.values;
+    }
+    else if (!partial) {
+        values.stages_json = null;
+    }
+    for (const field of ['path_globs', 'component_tags']) {
+        if (Object.hasOwn(input, field)) {
+            const result = validateApplicabilityStrings(input[field], field);
+            if ('error' in result) {
+                return result;
+            }
+            values[`${field}_json`] = result.values;
+        }
+        else if (!partial) {
+            values[`${field}_json`] = null;
+        }
+    }
     return { values };
 };
+const validateProjectMemorySuggestionMetadata = (input) => {
+    let evidence = null;
+    if (input.evidence != null) {
+        if (typeof input.evidence !== 'object' || Array.isArray(input.evidence)) {
+            return { error: 'evidence must be an object', code: 'invalid_field', field: 'evidence' };
+        }
+        const value = input.evidence;
+        const summary = validateMemoryString(validateRequiredString(value.summary, 'summary'), 'summary', PROJECT_MEMORY_LIMITS.evidenceSummary);
+        if ('error' in summary) {
+            return { ...summary, field: 'evidence.summary' };
+        }
+        const excerpt = validateMemoryString(normalizeOptionalString(value.source_excerpt, 'source_excerpt'), 'source_excerpt', PROJECT_MEMORY_LIMITS.evidenceExcerpt);
+        if ('error' in excerpt) {
+            return { ...excerpt, field: 'evidence.source_excerpt' };
+        }
+        evidence = { summary: summary.values, source_excerpt: excerpt.values };
+    }
+    let recommendation = null;
+    if (input.recommendation != null) {
+        if (typeof input.recommendation !== 'object' || Array.isArray(input.recommendation)) {
+            return { error: 'recommendation must be an object', code: 'invalid_field', field: 'recommendation' };
+        }
+        const value = input.recommendation;
+        if (!PROJECT_MEMORY_SUGGESTION_RECOMMENDATION_ACTIONS.includes(value.action)) {
+            return { error: 'recommendation.action must be create, update, or supersede', code: 'invalid_field', field: 'recommendation.action' };
+        }
+        if (!PROJECT_MEMORY_SUGGESTION_CONFIDENCES.includes(value.confidence)) {
+            return { error: 'recommendation.confidence must be low, medium, or high', code: 'invalid_field', field: 'recommendation.confidence' };
+        }
+        const targetMemoryId = value.target_memory_id == null ? null : typeof value.target_memory_id === 'string' ? value.target_memory_id.trim() || null : undefined;
+        if (targetMemoryId === undefined) {
+            return { error: 'recommendation.target_memory_id must be a string or null', code: 'invalid_field', field: 'recommendation.target_memory_id' };
+        }
+        recommendation = { action: value.action, target_memory_id: targetMemoryId, confidence: value.confidence };
+    }
+    return { values: { evidence, recommendation } };
+};
 export const validateProjectMemorySuggestionPayload = (body) => {
     if (!body || typeof body !== 'object' || Array.isArray(body)) {
-        return { error: 'Invalid project memory suggestion payload' };
+        return { error: 'Invalid project memory suggestion payload', code: 'invalid_field' };
     }
     const input = body;
     if (!PROJECT_MEMORY_SUGGESTION_KINDS.includes(input.kind)) {
-        return { error: 'kind must be one of decision or convention' };
+        return { error: 'kind must be one of decision or convention', code: 'invalid_field', field: 'kind' };
+    }
+    const metadata = validateProjectMemorySuggestionMetadata(input);
+    if ('error' in metadata) {
+        return metadata;
     }
     if (input.kind === 'decision') {
         const decisionValidation = validateProjectDecisionPayload({
@@ -847,9 +1237,12 @@ export const validateProjectMemorySuggestionPayload = (body) => {
             decision: input.decision ?? input.content,
             rationale: input.rationale,
             implications: input.implications,
+            stages: input.stages,
+            path_globs: input.path_globs,
+            component_tags: input.component_tags,
         });
         if ('error' in decisionValidation) {
-            return { error: decisionValidation.error };
+            return decisionValidation;
         }
         return {
             values: {
@@ -859,6 +1252,10 @@ export const validateProjectMemorySuggestionPayload = (body) => {
                 decision: decisionValidation.values.decision ?? '',
                 rationale: decisionValidation.values.rationale ?? null,
                 implications: parseStringArray(decisionValidation.values.implications_json ?? null),
+                stages: parseStringArray(decisionValidation.values.stages_json ?? null),
+                path_globs: parseStringArray(decisionValidation.values.path_globs_json ?? null),
+                component_tags: parseStringArray(decisionValidation.values.component_tags_json ?? null),
+                ...metadata.values,
             },
         };
     }
@@ -870,15 +1267,17 @@ export const validateProjectMemorySuggestionPayload = (body) => {
         stages: input.stages,
         priority: input.priority,
         injection_mode: input.injection_mode,
+        path_globs: input.path_globs,
+        component_tags: input.component_tags,
     });
     if ('error' in conventionValidation) {
-        return { error: conventionValidation.error };
+        return conventionValidation;
     }
     const scope = conventionValidation.values.scope ?? null;
     const stages = parseStringArray(conventionValidation.values.stages_json ?? null)
         .filter((entry) => PROJECT_MEMORY_STAGES.includes(entry));
     if (!scope && stages.length === 0) {
-        return { error: 'Convention suggestions require a scope or at least one stage' };
+        return { error: 'Convention suggestions require a scope or at least one stage', code: 'invalid_field', field: 'scope' };
     }
     return {
         values: {
@@ -890,6 +1289,9 @@ export const validateProjectMemorySuggestionPayload = (body) => {
             stages,
             priority: conventionValidation.values.priority ?? 'normal',
             injection_mode: conventionValidation.values.injection_mode ?? 'relevant',
+            path_globs: parseStringArray(conventionValidation.values.path_globs_json ?? null),
+            component_tags: parseStringArray(conventionValidation.values.component_tags_json ?? null),
+            ...metadata.values,
         },
     };
 };
@@ -1016,104 +1418,195 @@ export const getProjectDecisionById = (projectId, decisionId) => {
     const row = db.prepare('SELECT * FROM project_decisions WHERE id = ? AND project_id = ?').get(decisionId, projectId);
     return row ? serializeDecision(row) : null;
 };
-export const createProjectConvention = (projectId, values) => {
+export const createProjectConvention = (projectId, values, origin = createManualProjectMemoryOrigin()) => {
     const id = randomUUID();
-    db.prepare(`
-    INSERT INTO project_conventions (id, project_id, title, scope, instruction, rationale, stages_json, priority, injection_mode, status)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')
-  `).run(id, projectId, values.title, values.scope, values.instruction, values.rationale, values.stages_json, values.priority, values.injection_mode);
-    return getProjectConventionById(projectId, id);
+    const transaction = db.transaction(() => {
+        db.prepare(`
+      INSERT INTO project_conventions (
+        id, project_id, title, scope, instruction, rationale, stages_json, path_globs_json, component_tags_json, priority,
+        injection_mode, status, source_suggestion_id, origin_json
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?)
+    `).run(id, projectId, values.title, values.scope, values.instruction, values.rationale, values.stages_json, values.path_globs_json, values.component_tags_json, values.priority, values.injection_mode, origin.suggestion_id, JSON.stringify(origin));
+        recordProjectMemoryEvent({ projectId, memoryKind: 'convention', memoryId: id, eventType: 'created' });
+        return getProjectConventionById(projectId, id);
+    });
+    return transaction();
 };
 export const updateProjectConvention = (projectId, conventionId, values) => {
-    const current = getProjectConventionById(projectId, conventionId);
-    if (!current) {
-        return null;
-    }
-    db.prepare(`
-    UPDATE project_conventions
-    SET title = ?,
-        scope = ?,
-        instruction = ?,
-        rationale = ?,
-        stages_json = ?,
-        priority = ?,
-        injection_mode = ?,
-        updated_at = CURRENT_TIMESTAMP
-    WHERE id = ?
-      AND project_id = ?
-  `).run(values.title ?? current.title, Object.hasOwn(values, 'scope') ? values.scope : current.scope, values.instruction ?? current.instruction, Object.hasOwn(values, 'rationale') ? values.rationale : current.rationale, Object.hasOwn(values, 'stages_json') ? values.stages_json : (current.stages.length > 0 ? JSON.stringify(current.stages) : null), values.priority ?? current.priority, values.injection_mode ?? current.injection_mode, conventionId, projectId);
-    return getProjectConventionById(projectId, conventionId);
+    const transaction = db.transaction(() => {
+        const current = getProjectConventionById(projectId, conventionId);
+        if (!current) {
+            return null;
+        }
+        db.prepare(`
+      UPDATE project_conventions
+      SET title = ?,
+          scope = ?,
+          instruction = ?,
+          rationale = ?,
+          stages_json = ?,
+          path_globs_json = ?,
+          component_tags_json = ?,
+          priority = ?,
+          injection_mode = ?,
+          updated_at = CURRENT_TIMESTAMP
+      WHERE id = ?
+        AND project_id = ?
+    `).run(values.title ?? current.title, Object.hasOwn(values, 'scope') ? values.scope : current.scope, values.instruction ?? current.instruction, Object.hasOwn(values, 'rationale') ? values.rationale : current.rationale, Object.hasOwn(values, 'stages_json') ? values.stages_json : (current.stages.length > 0 ? JSON.stringify(current.stages) : null), Object.hasOwn(values, 'path_globs_json') ? values.path_globs_json : (current.path_globs.length > 0 ? JSON.stringify(current.path_globs) : null), Object.hasOwn(values, 'component_tags_json') ? values.component_tags_json : (current.component_tags.length > 0 ? JSON.stringify(current.component_tags) : null), values.priority ?? current.priority, values.injection_mode ?? current.injection_mode, conventionId, projectId);
+        recordProjectMemoryEvent({ projectId, memoryKind: 'convention', memoryId: conventionId, eventType: 'updated' });
+        return getProjectConventionById(projectId, conventionId);
+    });
+    return transaction();
+};
+const transitionProjectConvention = (projectId, conventionId, expectedStatus, nextStatus, confirmConflicts = false) => {
+    const transaction = db.transaction(() => {
+        const current = getProjectConventionById(projectId, conventionId);
+        if (!current) {
+            return { status: 404, error: 'Convention not found' };
+        }
+        if (current.status !== expectedStatus) {
+            return { status: 409, error: 'Convention is not in a state that allows this transition', memory: current };
+        }
+        if (nextStatus === 'active' && !confirmConflicts) {
+            const conflicts = detectProjectMemoryConflicts(listProjectDecisions(projectId, { includeArchived: true }), listProjectConventions(projectId, { includeArchived: true }).map(item => item.id === conventionId ? { ...item, status: 'active' } : item));
+            if (conflicts.length > 0) {
+                return { status: 409, error: 'Restoring this memory creates conflicts', memory: current, conflicts, requires_confirmation: true };
+            }
+        }
+        const update = db.prepare(`
+      UPDATE project_conventions
+      SET status = ?, updated_at = CURRENT_TIMESTAMP
+      WHERE id = ?
+        AND project_id = ?
+        AND status = ?
+    `).run(nextStatus, conventionId, projectId, expectedStatus);
+        if (update.changes !== 1) {
+            return {
+                status: 409,
+                error: 'Convention changed before the transition could be applied',
+                memory: getProjectConventionById(projectId, conventionId) ?? undefined,
+            };
+        }
+        const updated = getProjectConventionById(projectId, conventionId);
+        if (!updated) {
+            throw new Error('Convention disappeared after lifecycle transition');
+        }
+        recordProjectMemoryEvent({ projectId, memoryKind: 'convention', memoryId: conventionId, eventType: nextStatus === 'active' ? 'restored' : 'archived' });
+        return { status: 200, memory: updated };
+    });
+    return transaction();
 };
 export const archiveProjectConvention = (projectId, conventionId) => {
-    db.prepare(`
-    UPDATE project_conventions
-    SET status = 'archived', updated_at = CURRENT_TIMESTAMP
-    WHERE id = ?
-      AND project_id = ?
-  `).run(conventionId, projectId);
-    return getProjectConventionById(projectId, conventionId);
+    return transitionProjectConvention(projectId, conventionId, 'active', 'archived');
 };
-export const restoreProjectConvention = (projectId, conventionId) => {
-    db.prepare(`
-    UPDATE project_conventions
-    SET status = 'active', updated_at = CURRENT_TIMESTAMP
-    WHERE id = ?
-      AND project_id = ?
-  `).run(conventionId, projectId);
-    return getProjectConventionById(projectId, conventionId);
+export const restoreProjectConvention = (projectId, conventionId, confirmConflicts = false) => {
+    return transitionProjectConvention(projectId, conventionId, 'archived', 'active', confirmConflicts);
 };
-export const createProjectDecision = (projectId, values) => {
+export const createProjectDecision = (projectId, values, origin = createManualProjectMemoryOrigin()) => {
     const id = randomUUID();
-    db.prepare(`
-    INSERT INTO project_decisions (id, project_id, title, scope, decision, rationale, implications_json, status)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(id, projectId, values.title, values.scope, values.decision, values.rationale, values.implications_json, ACCEPTED_PROJECT_DECISION_STATUS);
-    return getProjectDecisionById(projectId, id);
+    const transaction = db.transaction(() => {
+        db.prepare(`
+      INSERT INTO project_decisions (
+        id, project_id, title, scope, decision, rationale, implications_json, stages_json, path_globs_json, component_tags_json, status,
+        source_suggestion_id, origin_json
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, projectId, values.title, values.scope, values.decision, values.rationale, values.implications_json, values.stages_json, values.path_globs_json, values.component_tags_json, ACCEPTED_PROJECT_DECISION_STATUS, origin.suggestion_id, JSON.stringify(origin));
+        recordProjectMemoryEvent({ projectId, memoryKind: 'decision', memoryId: id, eventType: 'created' });
+        return getProjectDecisionById(projectId, id);
+    });
+    return transaction();
 };
 export const updateProjectDecision = (projectId, decisionId, values) => {
-    const current = getProjectDecisionById(projectId, decisionId);
-    if (!current) {
-        return null;
-    }
-    db.prepare(`
-    UPDATE project_decisions
-    SET title = ?,
-        scope = ?,
-        decision = ?,
-        rationale = ?,
-        implications_json = ?,
-        updated_at = CURRENT_TIMESTAMP
-    WHERE id = ?
-      AND project_id = ?
-  `).run(values.title ?? current.title, Object.hasOwn(values, 'scope') ? values.scope : current.scope, values.decision ?? current.decision, Object.hasOwn(values, 'rationale') ? values.rationale : current.rationale, Object.hasOwn(values, 'implications_json') ? values.implications_json : (current.implications.length > 0 ? JSON.stringify(current.implications) : null), decisionId, projectId);
-    return getProjectDecisionById(projectId, decisionId);
+    const transaction = db.transaction(() => {
+        const current = getProjectDecisionById(projectId, decisionId);
+        if (!current) {
+            return null;
+        }
+        db.prepare(`
+      UPDATE project_decisions
+      SET title = ?,
+          scope = ?,
+          decision = ?,
+          rationale = ?,
+          implications_json = ?,
+          stages_json = ?,
+          path_globs_json = ?,
+          component_tags_json = ?,
+          updated_at = CURRENT_TIMESTAMP
+      WHERE id = ?
+        AND project_id = ?
+    `).run(values.title ?? current.title, Object.hasOwn(values, 'scope') ? values.scope : current.scope, values.decision ?? current.decision, Object.hasOwn(values, 'rationale') ? values.rationale : current.rationale, Object.hasOwn(values, 'implications_json') ? values.implications_json : (current.implications.length > 0 ? JSON.stringify(current.implications) : null), Object.hasOwn(values, 'stages_json') ? values.stages_json : (current.stages.length > 0 ? JSON.stringify(current.stages) : null), Object.hasOwn(values, 'path_globs_json') ? values.path_globs_json : (current.path_globs.length > 0 ? JSON.stringify(current.path_globs) : null), Object.hasOwn(values, 'component_tags_json') ? values.component_tags_json : (current.component_tags.length > 0 ? JSON.stringify(current.component_tags) : null), decisionId, projectId);
+        recordProjectMemoryEvent({ projectId, memoryKind: 'decision', memoryId: decisionId, eventType: 'updated' });
+        return getProjectDecisionById(projectId, decisionId);
+    });
+    return transaction();
+};
+const transitionProjectDecision = (projectId, decisionId, expectedStatuses, nextStatus, confirmConflicts = false) => {
+    const transaction = db.transaction(() => {
+        const current = getProjectDecisionById(projectId, decisionId);
+        if (!current) {
+            return { status: 404, error: 'Decision not found' };
+        }
+        if (!expectedStatuses.includes(current.status)) {
+            return { status: 409, error: 'Decision is not in a state that allows this transition', memory: current };
+        }
+        if (nextStatus === ACCEPTED_PROJECT_DECISION_STATUS && !confirmConflicts) {
+            const conflicts = detectProjectMemoryConflicts(listProjectDecisions(projectId, { includeArchived: true }).map(item => item.id === decisionId ? { ...item, status: ACCEPTED_PROJECT_DECISION_STATUS } : item), listProjectConventions(projectId, { includeArchived: true }));
+            if (conflicts.length > 0) {
+                return { status: 409, error: 'Restoring this memory creates conflicts', memory: current, conflicts, requires_confirmation: true };
+            }
+        }
+        const update = db.prepare(`
+      UPDATE project_decisions
+      SET status = ?, updated_at = CURRENT_TIMESTAMP
+      WHERE id = ?
+        AND project_id = ?
+        AND status = ?
+    `).run(nextStatus, decisionId, projectId, current.status);
+        if (update.changes !== 1) {
+            return {
+                status: 409,
+                error: 'Decision changed before the transition could be applied',
+                memory: getProjectDecisionById(projectId, decisionId) ?? undefined,
+            };
+        }
+        const updated = getProjectDecisionById(projectId, decisionId);
+        if (!updated) {
+            throw new Error('Decision disappeared after lifecycle transition');
+        }
+        recordProjectMemoryEvent({ projectId, memoryKind: 'decision', memoryId: decisionId, eventType: nextStatus === ACCEPTED_PROJECT_DECISION_STATUS ? 'restored' : 'archived' });
+        return { status: 200, memory: updated };
+    });
+    return transaction();
 };
 export const archiveProjectDecision = (projectId, decisionId) => {
-    db.prepare(`
-    UPDATE project_decisions
-    SET status = 'archived', updated_at = CURRENT_TIMESTAMP
-    WHERE id = ?
-      AND project_id = ?
-  `).run(decisionId, projectId);
-    return getProjectDecisionById(projectId, decisionId);
+    return transitionProjectDecision(projectId, decisionId, [ACCEPTED_PROJECT_DECISION_STATUS], 'archived');
 };
-export const supersedeProjectDecision = (projectId, decisionId) => {
-    db.prepare(`
-    UPDATE project_decisions
-    SET status = 'superseded', updated_at = CURRENT_TIMESTAMP
-    WHERE id = ?
-      AND project_id = ?
-  `).run(decisionId, projectId);
-    return getProjectDecisionById(projectId, decisionId);
+export const supersedeProjectDecision = (projectId, decisionId, replacementDecisionId) => {
+    const current = getProjectDecisionById(projectId, decisionId);
+    if (!current) {
+        return { status: 404, error: 'Decision not found' };
+    }
+    if (current.status !== ACCEPTED_PROJECT_DECISION_STATUS) {
+        return { status: 409, error: 'Decision is not in a state that allows this transition', memory: current };
+    }
+    const update = db.prepare(`
+      UPDATE project_decisions
+      SET status = 'superseded', superseded_by_decision_id = ?, updated_at = CURRENT_TIMESTAMP
+      WHERE id = ? AND project_id = ? AND status = ?
+        AND ? <> id
+        AND EXISTS (SELECT 1 FROM project_decisions replacement WHERE replacement.id = ? AND replacement.project_id = ? AND replacement.status = 'accepted')
+    `).run(replacementDecisionId, decisionId, projectId, ACCEPTED_PROJECT_DECISION_STATUS, replacementDecisionId, replacementDecisionId, projectId);
+    if (update.changes !== 1) {
+        return { status: 400, error: 'replacement_decision_id must name another accepted decision in this project', memory: getProjectDecisionById(projectId, decisionId) ?? undefined };
+    }
+    recordProjectMemoryEvent({ projectId, memoryKind: 'decision', memoryId: decisionId, eventType: 'superseded', summary: { replacement_decision_id: replacementDecisionId } });
+    return { status: 200, memory: getProjectDecisionById(projectId, decisionId) ?? undefined };
 };
-export const restoreProjectDecision = (projectId, decisionId) => {
-    db.prepare(`
-    UPDATE project_decisions
-    SET status = ?, updated_at = CURRENT_TIMESTAMP
-    WHERE id = ?
-      AND project_id = ?
-  `).run(ACCEPTED_PROJECT_DECISION_STATUS, decisionId, projectId);
-    return getProjectDecisionById(projectId, decisionId);
+export const restoreProjectDecision = (projectId, decisionId, confirmConflicts = false) => {
+    return transitionProjectDecision(projectId, decisionId, ['archived', 'superseded'], ACCEPTED_PROJECT_DECISION_STATUS, confirmConflicts);
 };
 const getProjectMemorySuggestionRowById = (projectId, suggestionId) => {
     return db.prepare(`
@@ -1191,9 +1684,13 @@ export const listProjectMemories = (projectId, { states, kinds, sources, ticketI
             instruction: convention.instruction,
             rationale: convention.rationale,
             stages_json: convention.stages.length > 0 ? JSON.stringify(convention.stages) : null,
+            path_globs_json: convention.path_globs.length > 0 ? JSON.stringify(convention.path_globs) : null,
+            component_tags_json: convention.component_tags.length > 0 ? JSON.stringify(convention.component_tags) : null,
             priority: convention.priority,
             injection_mode: convention.injection_mode,
             status: convention.status,
+            source_suggestion_id: convention.origin?.suggestion_id ?? null,
+            origin_json: convention.origin ? JSON.stringify(convention.origin) : null,
             created_at: convention.created_at,
             updated_at: convention.updated_at,
         })),
@@ -1205,7 +1702,13 @@ export const listProjectMemories = (projectId, { states, kinds, sources, ticketI
             decision: decision.decision,
             rationale: decision.rationale,
             implications_json: decision.implications.length > 0 ? JSON.stringify(decision.implications) : null,
+            stages_json: decision.stages.length > 0 ? JSON.stringify(decision.stages) : null,
+            path_globs_json: decision.path_globs.length > 0 ? JSON.stringify(decision.path_globs) : null,
+            component_tags_json: decision.component_tags.length > 0 ? JSON.stringify(decision.component_tags) : null,
             status: decision.status,
+            superseded_by_decision_id: decision.superseded_by_decision_id,
+            source_suggestion_id: decision.origin?.suggestion_id ?? null,
+            origin_json: decision.origin ? JSON.stringify(decision.origin) : null,
             created_at: decision.created_at,
             updated_at: decision.updated_at,
         })),
@@ -1254,6 +1757,10 @@ export const getProjectMemoryById = (projectId, memoryId) => {
     return suggestion ? serializeProjectMemoryFromSuggestionValue(suggestion) : null;
 };
 const persistProjectMemorySuggestionsForSource = (projectId, source, sourceStage, suggestions) => {
+    const project = db.prepare('SELECT memory_enabled FROM projects WHERE id = ?').get(projectId);
+    if (!project?.memory_enabled) {
+        return [];
+    }
     if (!source.ticketId && !source.chatSessionId && !source.specSessionId) {
         return [];
     }
@@ -1273,8 +1780,38 @@ const persistProjectMemorySuggestionsForSource = (projectId, source, sourceStage
         : new Set();
     const createdIds = [];
     for (const suggestion of suggestions) {
+        const recommendedTarget = suggestion.recommendation?.target_memory_id
+            ? suggestion.kind === 'decision'
+                ? getProjectDecisionById(projectId, suggestion.recommendation.target_memory_id)
+                : getProjectConventionById(projectId, suggestion.recommendation.target_memory_id)
+            : null;
+        const recommendation = suggestion.recommendation
+            ? {
+                ...suggestion.recommendation,
+                target_memory_id: recommendedTarget
+                    && ((suggestion.kind === 'decision' && recommendedTarget.status === ACCEPTED_PROJECT_DECISION_STATUS)
+                        || (suggestion.kind === 'convention' && recommendedTarget.status === 'active'))
+                    ? recommendedTarget.id
+                    : null,
+            }
+            : null;
+        const resolvedSuggestion = { ...suggestion, recommendation };
+        const fingerprint = getProjectMemorySuggestionFingerprint(projectId, resolvedSuggestion);
+        const suppressed = db.prepare(`
+      SELECT 1
+      FROM project_memory_suggestions
+      WHERE project_id = ? AND dedupe_fingerprint = ?
+        AND (
+          status IN ('accepted', 'applied_to_existing')
+          OR (status = 'dismissed' AND updated_at >= datetime('now', ?))
+        )
+      LIMIT 1
+    `).get(projectId, fingerprint, `-${PROJECT_MEMORY_SUGGESTION_DISMISSAL_COOLDOWN_DAYS} days`);
+        if (suppressed) {
+            continue;
+        }
         const duplicate = classifyProjectMemorySuggestionDuplicate({
-            suggestion,
+            suggestion: resolvedSuggestion,
             activeConventions,
             activeDecisions,
             pendingSuggestions: pendingSuggestionCandidates,
@@ -1311,13 +1848,14 @@ const persistProjectMemorySuggestionsForSource = (projectId, source, sourceStage
         duplicate_target_id,
         status,
         resolved_memory_id
+        , dedupe_fingerprint
       )
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', NULL)
-    `).run(id, projectId, source.ticketId ?? null, source.chatSessionId ?? null, source.specSessionId ?? null, sourceStage, suggestion.kind, suggestion.title, suggestion.scope, getProjectMemorySuggestionContent(suggestion), suggestion.rationale, JSON.stringify(suggestion.kind === 'decision'
-            ? { implications: suggestion.implications }
-            : { stages: suggestion.stages, priority: suggestion.priority, injection_mode: suggestion.injection_mode }), duplicate?.action === 'mark_near_duplicate' ? 'near_duplicate' : 'none', duplicate?.action === 'mark_near_duplicate' ? duplicate.targetMemoryId : null);
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', NULL, ?)
+    `).run(id, projectId, source.ticketId ?? null, source.chatSessionId ?? null, source.specSessionId ?? null, sourceStage, resolvedSuggestion.kind, resolvedSuggestion.title, resolvedSuggestion.scope, getProjectMemorySuggestionContent(resolvedSuggestion), resolvedSuggestion.rationale, JSON.stringify(resolvedSuggestion.kind === 'decision'
+            ? { implications: resolvedSuggestion.implications, stages: resolvedSuggestion.stages, path_globs: resolvedSuggestion.path_globs, component_tags: resolvedSuggestion.component_tags, evidence: resolvedSuggestion.evidence, recommendation: resolvedSuggestion.recommendation }
+            : { stages: resolvedSuggestion.stages, path_globs: resolvedSuggestion.path_globs, component_tags: resolvedSuggestion.component_tags, priority: resolvedSuggestion.priority, injection_mode: resolvedSuggestion.injection_mode, evidence: resolvedSuggestion.evidence, recommendation: resolvedSuggestion.recommendation }), duplicate?.action === 'mark_near_duplicate' ? 'near_duplicate' : 'none', duplicate?.action === 'mark_near_duplicate' ? duplicate.targetMemoryId : null, fingerprint);
         createdIds.push(id);
-        pendingSuggestionCandidates.push({ id, ...suggestion });
+        pendingSuggestionCandidates.push({ id, ...resolvedSuggestion });
     }
     return createdIds
         .map(id => getProjectMemorySuggestionById(projectId, id))
@@ -1332,20 +1870,28 @@ export const persistChatSessionProjectMemorySuggestions = (projectId, chatSessio
 export const persistSpecSessionProjectMemorySuggestions = (projectId, specSessionId, suggestions) => {
     return persistProjectMemorySuggestionsForSource(projectId, { specSessionId }, 'plan', suggestions);
 };
-const updateProjectMemorySuggestionStatus = (projectId, suggestionId, status, resolvedMemoryId) => {
-    db.prepare(`
+const resolvePendingProjectMemorySuggestion = (projectId, suggestionId, status, resolvedMemoryId) => {
+    const update = db.prepare(`
     UPDATE project_memory_suggestions
     SET status = ?,
         resolved_memory_id = ?,
         updated_at = CURRENT_TIMESTAMP
     WHERE id = ?
       AND project_id = ?
+      AND status = 'pending'
   `).run(status, resolvedMemoryId, suggestionId, projectId);
-    return getProjectMemorySuggestionById(projectId, suggestionId);
+    return update.changes === 1;
+};
+const recordProjectMemoryEvent = ({ projectId, memoryKind, memoryId, eventType, sourceSuggestionId = null, summary = null, }) => {
+    db.prepare(`
+    INSERT INTO project_memory_events (
+      id, project_id, memory_kind, memory_id, event_type, source_suggestion_id, summary_json
+    ) VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(randomUUID(), projectId, memoryKind, memoryId, eventType, sourceSuggestionId, summary == null ? null : JSON.stringify(summary));
 };
 const mergeProjectMemorySuggestionDecisionValues = (suggestion, overrides) => {
     if (suggestion.kind !== 'decision') {
-        return { error: 'Suggestion is not a decision' };
+        return { error: 'Suggestion is not a decision', code: 'invalid_field', field: 'kind' };
     }
     const merged = {
         title: overrides.title ?? suggestion.title,
@@ -1355,12 +1901,15 @@ const mergeProjectMemorySuggestionDecisionValues = (suggestion, overrides) => {
         implications: Object.hasOwn(overrides, 'implications_json')
             ? parseStringArray(overrides.implications_json)
             : suggestion.implications,
+        stages: Object.hasOwn(overrides, 'stages_json') ? parseStringArray(overrides.stages_json) : suggestion.stages,
+        path_globs: Object.hasOwn(overrides, 'path_globs_json') ? parseStringArray(overrides.path_globs_json) : suggestion.path_globs,
+        component_tags: Object.hasOwn(overrides, 'component_tags_json') ? parseStringArray(overrides.component_tags_json) : suggestion.component_tags,
     };
     return validateProjectDecisionPayload(merged);
 };
 const mergeProjectMemorySuggestionConventionValues = (suggestion, overrides) => {
     if (suggestion.kind !== 'convention') {
-        return { error: 'Suggestion is not a convention' };
+        return { error: 'Suggestion is not a convention', code: 'invalid_field', field: 'kind' };
     }
     const merged = {
         title: overrides.title ?? suggestion.title,
@@ -1372,178 +1921,426 @@ const mergeProjectMemorySuggestionConventionValues = (suggestion, overrides) =>
             : suggestion.stages,
         priority: overrides.priority ?? suggestion.priority,
         injection_mode: overrides.injection_mode ?? suggestion.injection_mode,
+        path_globs: Object.hasOwn(overrides, 'path_globs_json') ? parseStringArray(overrides.path_globs_json) : suggestion.path_globs,
+        component_tags: Object.hasOwn(overrides, 'component_tags_json') ? parseStringArray(overrides.component_tags_json) : suggestion.component_tags,
     };
     return validateProjectConventionPayload(merged);
 };
-export const dismissProjectMemorySuggestion = (projectId, suggestionId) => {
-    return updateProjectMemorySuggestionStatus(projectId, suggestionId, 'dismissed', null);
-};
-export const acceptProjectMemorySuggestion = (projectId, suggestionId, overrides = {}) => {
-    const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
-    if (!suggestion) {
-        return { status: 404, error: 'Suggestion not found' };
+export const dismissProjectMemorySuggestion = (projectId, suggestionId, reason = null) => {
+    if (reason !== null && !PROJECT_MEMORY_SUGGESTION_DISMISSAL_REASONS.includes(reason)) {
+        return { status: 400, error: 'reason must be a supported dismissal reason' };
     }
-    return suggestion.kind === 'decision'
-        ? acceptProjectMemorySuggestionAsDecision(projectId, suggestionId, overrides)
-        : acceptProjectMemorySuggestionAsConvention(projectId, suggestionId, overrides);
+    const transaction = db.transaction(() => {
+        const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        if (!suggestion) {
+            return { status: 404, error: 'Suggestion not found' };
+        }
+        if (suggestion.status !== 'pending') {
+            return { status: 409, error: 'Suggestion is no longer pending', suggestion };
+        }
+        if (!resolvePendingProjectMemorySuggestion(projectId, suggestionId, 'dismissed', null)) {
+            return {
+                status: 409,
+                error: 'Suggestion changed before the dismissal could be applied',
+                suggestion: getProjectMemorySuggestionById(projectId, suggestionId) ?? suggestion,
+            };
+        }
+        db.prepare('UPDATE project_memory_suggestions SET dismissal_reason = ? WHERE id = ? AND project_id = ?').run(reason, suggestionId, projectId);
+        const dismissed = getProjectMemorySuggestionById(projectId, suggestionId);
+        if (!dismissed) {
+            throw new Error('Suggestion disappeared after dismissal');
+        }
+        return { suggestion: dismissed };
+    });
+    return transaction();
 };
-export const acceptProjectMemorySuggestionAsDecision = (projectId, suggestionId, overrides = {}) => {
+export const acceptProjectMemorySuggestion = (projectId, suggestionId, overrides = {}, confirmConflicts = false) => {
     const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
     if (!suggestion) {
         return { status: 404, error: 'Suggestion not found' };
     }
-    if (suggestion.status !== 'pending') {
-        return { status: 409, error: 'Suggestion is no longer pending', suggestion };
-    }
-    const merged = mergeProjectMemorySuggestionDecisionValues(suggestion, overrides);
-    if ('error' in merged) {
-        return { status: 400, error: merged.error, suggestion };
-    }
-    const duplicate = classifyProjectMemorySuggestionDuplicate({
-        suggestion: {
-            kind: 'decision',
+    return suggestion.kind === 'decision'
+        ? acceptProjectMemorySuggestionAsDecision(projectId, suggestionId, overrides, confirmConflicts)
+        : acceptProjectMemorySuggestionAsConvention(projectId, suggestionId, overrides, confirmConflicts);
+};
+export const acceptProjectMemorySuggestionAsDecision = (projectId, suggestionId, overrides = {}, confirmConflicts = false) => {
+    let suggestionBeforeMutation = null;
+    const transaction = db.transaction(() => {
+        const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        suggestionBeforeMutation = suggestion;
+        if (!suggestion) {
+            return { status: 404, error: 'Suggestion not found' };
+        }
+        if (suggestion.status !== 'pending') {
+            return { status: 409, error: 'Suggestion is no longer pending', suggestion };
+        }
+        const merged = mergeProjectMemorySuggestionDecisionValues(suggestion, overrides);
+        if ('error' in merged) {
+            return { status: merged.code === 'field_too_large' ? 413 : 400, ...merged, suggestion };
+        }
+        const origin = createProjectMemorySuggestionOrigin(projectId, suggestion);
+        if (!origin) {
+            return { status: 409, error: 'Suggestion source is no longer available for this project', suggestion };
+        }
+        const candidate = {
+            id: suggestionId,
+            project_id: projectId,
+            title: merged.values.title ?? '', scope: merged.values.scope ?? null, decision: merged.values.decision ?? '', rationale: merged.values.rationale ?? null,
+            implications: parseStringArray(merged.values.implications_json ?? null), stages: parseStringArray(merged.values.stages_json ?? null),
+            path_globs: parseStringArray(merged.values.path_globs_json ?? null), component_tags: parseStringArray(merged.values.component_tags_json ?? null),
+            status: ACCEPTED_PROJECT_DECISION_STATUS, superseded_by_decision_id: null, created_at: suggestion.created_at, updated_at: suggestion.updated_at,
+        };
+        const conflicts = detectProjectMemoryConflicts([...listProjectDecisions(projectId), candidate], listProjectConventions(projectId));
+        if (conflicts.length > 0 && !confirmConflicts) {
+            return { status: 409, error: 'Accepting this suggestion creates conflicts', suggestion, conflicts, requires_confirmation: true };
+        }
+        const duplicate = classifyProjectMemorySuggestionDuplicate({
+            suggestion: {
+                kind: 'decision',
+                title: merged.values.title ?? '',
+                scope: merged.values.scope ?? null,
+                decision: merged.values.decision ?? '',
+                rationale: merged.values.rationale ?? null,
+                implications: parseStringArray(merged.values.implications_json ?? null),
+                stages: parseStringArray(merged.values.stages_json ?? null),
+                path_globs: parseStringArray(merged.values.path_globs_json ?? null),
+                component_tags: parseStringArray(merged.values.component_tags_json ?? null),
+                evidence: suggestion.evidence,
+                recommendation: suggestion.recommendation,
+            },
+            activeConventions: [],
+            activeDecisions: listProjectDecisions(projectId),
+            pendingSuggestions: listProjectMemorySuggestionRows(projectId, { status: 'pending' })
+                .filter(row => row.id !== suggestionId)
+                .map(toProjectMemorySuggestionCandidate)
+                .filter((candidate) => candidate !== null),
+        });
+        if (duplicate?.action === 'suppress' && duplicate.target === 'decision') {
+            return { status: 409, error: 'A matching decision already exists for this project', suggestion };
+        }
+        const createdDecision = createProjectDecision(projectId, {
             title: merged.values.title ?? '',
             scope: merged.values.scope ?? null,
             decision: merged.values.decision ?? '',
             rationale: merged.values.rationale ?? null,
-            implications: parseStringArray(merged.values.implications_json ?? null),
-        },
-        activeConventions: [],
-        activeDecisions: listProjectDecisions(projectId),
-        pendingSuggestions: listProjectMemorySuggestionRows(projectId, { status: 'pending' })
-            .filter(row => row.id !== suggestionId)
-            .map(toProjectMemorySuggestionCandidate)
-            .filter((candidate) => candidate !== null),
-    });
-    if (duplicate?.action === 'suppress' && duplicate.target === 'decision') {
-        return { status: 409, error: 'A matching decision already exists for this project', suggestion };
-    }
-    const createdDecision = createProjectDecision(projectId, {
-        title: merged.values.title ?? '',
-        scope: merged.values.scope ?? null,
-        decision: merged.values.decision ?? '',
-        rationale: merged.values.rationale ?? null,
-        implications_json: merged.values.implications_json ?? null,
+            implications_json: merged.values.implications_json ?? null,
+            stages_json: merged.values.stages_json ?? null,
+            path_globs_json: merged.values.path_globs_json ?? null,
+            component_tags_json: merged.values.component_tags_json ?? null,
+        }, origin);
+        if (!createdDecision) {
+            throw new Error('Unable to create the suggested decision');
+        }
+        if (!resolvePendingProjectMemorySuggestion(projectId, suggestionId, 'accepted', createdDecision.id)) {
+            throw new ProjectMemoryLifecycleConflictError('Suggestion changed before the acceptance could be applied');
+        }
+        const acceptedSuggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        if (!acceptedSuggestion) {
+            throw new Error('Suggestion disappeared after acceptance');
+        }
+        return { suggestion: acceptedSuggestion, decision: createdDecision };
     });
-    if (!createdDecision) {
-        return { status: 500, error: 'Unable to create the suggested decision', suggestion };
+    try {
+        return transaction();
     }
-    const updatedSuggestion = updateProjectMemorySuggestionStatus(projectId, suggestionId, 'accepted', createdDecision.id);
-    if (!updatedSuggestion) {
-        return { status: 500, error: 'Unable to update the suggestion state', suggestion };
+    catch (error) {
+        if (error instanceof ProjectMemoryLifecycleConflictError) {
+            return {
+                status: 409,
+                error: error.message,
+                suggestion: getProjectMemorySuggestionById(projectId, suggestionId) ?? suggestionBeforeMutation,
+            };
+        }
+        return {
+            status: 500,
+            error: 'Unable to accept the suggested decision',
+            suggestion: getProjectMemorySuggestionById(projectId, suggestionId) ?? suggestionBeforeMutation,
+        };
     }
-    return {
-        suggestion: updatedSuggestion,
-        decision: createdDecision,
-    };
 };
-export const acceptProjectMemorySuggestionAsConvention = (projectId, suggestionId, overrides = {}) => {
-    const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
-    if (!suggestion) {
-        return { status: 404, error: 'Suggestion not found' };
-    }
-    if (suggestion.status !== 'pending') {
-        return { status: 409, error: 'Suggestion is no longer pending', suggestion };
-    }
-    const merged = mergeProjectMemorySuggestionConventionValues(suggestion, overrides);
-    if ('error' in merged) {
-        return { status: 400, error: merged.error, suggestion };
-    }
-    const duplicate = classifyProjectMemorySuggestionDuplicate({
-        suggestion: {
-            kind: 'convention',
+export const acceptProjectMemorySuggestionAsConvention = (projectId, suggestionId, overrides = {}, confirmConflicts = false) => {
+    let suggestionBeforeMutation = null;
+    const transaction = db.transaction(() => {
+        const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        suggestionBeforeMutation = suggestion;
+        if (!suggestion) {
+            return { status: 404, error: 'Suggestion not found' };
+        }
+        if (suggestion.status !== 'pending') {
+            return { status: 409, error: 'Suggestion is no longer pending', suggestion };
+        }
+        const merged = mergeProjectMemorySuggestionConventionValues(suggestion, overrides);
+        if ('error' in merged) {
+            return { status: merged.code === 'field_too_large' ? 413 : 400, ...merged, suggestion };
+        }
+        const origin = createProjectMemorySuggestionOrigin(projectId, suggestion);
+        if (!origin) {
+            return { status: 409, error: 'Suggestion source is no longer available for this project', suggestion };
+        }
+        const candidate = {
+            id: suggestionId, project_id: projectId, title: merged.values.title ?? '', scope: merged.values.scope ?? null,
+            instruction: merged.values.instruction ?? '', rationale: merged.values.rationale ?? null,
+            stages: parseStringArray(merged.values.stages_json ?? null), path_globs: parseStringArray(merged.values.path_globs_json ?? null),
+            component_tags: parseStringArray(merged.values.component_tags_json ?? null), priority: merged.values.priority ?? 'normal',
+            injection_mode: merged.values.injection_mode ?? 'relevant', status: 'active', created_at: suggestion.created_at, updated_at: suggestion.updated_at,
+        };
+        const conflicts = detectProjectMemoryConflicts(listProjectDecisions(projectId), [...listProjectConventions(projectId), candidate]);
+        if (conflicts.length > 0 && !confirmConflicts) {
+            return { status: 409, error: 'Accepting this suggestion creates conflicts', suggestion, conflicts, requires_confirmation: true };
+        }
+        const duplicate = classifyProjectMemorySuggestionDuplicate({
+            suggestion: {
+                kind: 'convention',
+                title: merged.values.title ?? '',
+                scope: merged.values.scope ?? null,
+                instruction: merged.values.instruction ?? '',
+                rationale: merged.values.rationale ?? null,
+                stages: parseStringArray(merged.values.stages_json ?? null)
+                    .filter((entry) => PROJECT_MEMORY_STAGES.includes(entry)),
+                priority: merged.values.priority ?? 'normal',
+                injection_mode: merged.values.injection_mode ?? 'relevant',
+                path_globs: parseStringArray(merged.values.path_globs_json ?? null),
+                component_tags: parseStringArray(merged.values.component_tags_json ?? null),
+                evidence: suggestion.evidence,
+                recommendation: suggestion.recommendation,
+            },
+            activeConventions: listProjectConventions(projectId),
+            activeDecisions: [],
+            pendingSuggestions: listProjectMemorySuggestionRows(projectId, { status: 'pending' })
+                .filter(row => row.id !== suggestionId)
+                .map(toProjectMemorySuggestionCandidate)
+                .filter((candidate) => candidate !== null),
+        });
+        if (duplicate?.action === 'suppress' && duplicate.target === 'convention') {
+            return { status: 409, error: 'A matching convention already exists for this project', suggestion };
+        }
+        const createdConvention = createProjectConvention(projectId, {
             title: merged.values.title ?? '',
             scope: merged.values.scope ?? null,
             instruction: merged.values.instruction ?? '',
             rationale: merged.values.rationale ?? null,
-            stages: parseStringArray(merged.values.stages_json ?? null)
-                .filter((entry) => PROJECT_MEMORY_STAGES.includes(entry)),
+            stages_json: merged.values.stages_json ?? null,
+            path_globs_json: merged.values.path_globs_json ?? null,
+            component_tags_json: merged.values.component_tags_json ?? null,
             priority: merged.values.priority ?? 'normal',
             injection_mode: merged.values.injection_mode ?? 'relevant',
-        },
-        activeConventions: listProjectConventions(projectId),
-        activeDecisions: [],
-        pendingSuggestions: listProjectMemorySuggestionRows(projectId, { status: 'pending' })
-            .filter(row => row.id !== suggestionId)
-            .map(toProjectMemorySuggestionCandidate)
-            .filter((candidate) => candidate !== null),
-    });
-    if (duplicate?.action === 'suppress' && duplicate.target === 'convention') {
-        return { status: 409, error: 'A matching convention already exists for this project', suggestion };
-    }
-    const createdConvention = createProjectConvention(projectId, {
-        title: merged.values.title ?? '',
-        scope: merged.values.scope ?? null,
-        instruction: merged.values.instruction ?? '',
-        rationale: merged.values.rationale ?? null,
-        stages_json: merged.values.stages_json ?? null,
-        priority: merged.values.priority ?? 'normal',
-        injection_mode: merged.values.injection_mode ?? 'relevant',
+        }, origin);
+        if (!createdConvention) {
+            throw new Error('Unable to create the suggested convention');
+        }
+        if (!resolvePendingProjectMemorySuggestion(projectId, suggestionId, 'accepted', createdConvention.id)) {
+            throw new ProjectMemoryLifecycleConflictError('Suggestion changed before the acceptance could be applied');
+        }
+        const acceptedSuggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        if (!acceptedSuggestion) {
+            throw new Error('Suggestion disappeared after acceptance');
+        }
+        return { suggestion: acceptedSuggestion, convention: createdConvention };
     });
-    if (!createdConvention) {
-        return { status: 500, error: 'Unable to create the suggested convention', suggestion };
+    try {
+        return transaction();
     }
-    const updatedSuggestion = updateProjectMemorySuggestionStatus(projectId, suggestionId, 'accepted', createdConvention.id);
-    if (!updatedSuggestion) {
-        return { status: 500, error: 'Unable to update the suggestion state', suggestion };
+    catch (error) {
+        if (error instanceof ProjectMemoryLifecycleConflictError) {
+            return {
+                status: 409,
+                error: error.message,
+                suggestion: getProjectMemorySuggestionById(projectId, suggestionId) ?? suggestionBeforeMutation,
+            };
+        }
+        return {
+            status: 500,
+            error: 'Unable to accept the suggested convention',
+            suggestion: getProjectMemorySuggestionById(projectId, suggestionId) ?? suggestionBeforeMutation,
+        };
     }
-    return {
-        suggestion: updatedSuggestion,
-        convention: createdConvention,
-    };
 };
 export const applyProjectMemorySuggestionToDecision = (projectId, suggestionId, decisionId, overrides = {}) => {
-    const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
-    if (!suggestion) {
-        return { status: 404, error: 'Suggestion not found' };
+    let suggestionBeforeMutation = null;
+    const transaction = db.transaction(() => {
+        const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        suggestionBeforeMutation = suggestion;
+        if (!suggestion) {
+            return { status: 404, error: 'Suggestion not found' };
+        }
+        if (suggestion.status !== 'pending') {
+            return { status: 409, error: 'Suggestion is no longer pending', suggestion };
+        }
+        const existingDecision = getProjectDecisionById(projectId, decisionId);
+        if (!existingDecision || existingDecision.status !== ACCEPTED_PROJECT_DECISION_STATUS) {
+            return { status: 404, error: 'Decision not found', suggestion };
+        }
+        const merged = mergeProjectMemorySuggestionDecisionValues(suggestion, overrides);
+        if ('error' in merged) {
+            return { status: 400, error: merged.error, suggestion };
+        }
+        const duplicate = classifyProjectMemorySuggestionDuplicate({
+            suggestion: {
+                kind: 'decision',
+                title: merged.values.title ?? '',
+                scope: merged.values.scope ?? null,
+                decision: merged.values.decision ?? '',
+                rationale: merged.values.rationale ?? null,
+                implications: parseStringArray(merged.values.implications_json ?? null),
+                stages: parseStringArray(merged.values.stages_json ?? null),
+                path_globs: parseStringArray(merged.values.path_globs_json ?? null),
+                component_tags: parseStringArray(merged.values.component_tags_json ?? null),
+                evidence: suggestion.evidence,
+                recommendation: suggestion.recommendation,
+            },
+            activeConventions: [],
+            activeDecisions: listProjectDecisions(projectId).filter(decision => decision.id !== decisionId),
+            pendingSuggestions: listProjectMemorySuggestionRows(projectId, { status: 'pending' })
+                .filter(row => row.id !== suggestionId)
+                .map(toProjectMemorySuggestionCandidate)
+                .filter((candidate) => candidate !== null),
+        });
+        if (duplicate?.action === 'suppress' && duplicate.target === 'decision') {
+            return { status: 409, error: 'Updating this decision would duplicate another accepted decision', suggestion };
+        }
+        const update = db.prepare(`
+      UPDATE project_decisions
+      SET title = ?,
+          scope = ?,
+          decision = ?,
+          rationale = ?,
+          implications_json = ?,
+          updated_at = CURRENT_TIMESTAMP
+      WHERE id = ?
+        AND project_id = ?
+        AND status = ?
+    `).run(merged.values.title ?? existingDecision.title, merged.values.scope ?? null, merged.values.decision ?? existingDecision.decision, merged.values.rationale ?? null, merged.values.implications_json ?? (existingDecision.implications.length > 0 ? JSON.stringify(existingDecision.implications) : null), decisionId, projectId, ACCEPTED_PROJECT_DECISION_STATUS);
+        if (update.changes !== 1) {
+            return {
+                status: 409,
+                error: 'Decision changed before the suggestion could be applied',
+                suggestion: getProjectMemorySuggestionById(projectId, suggestionId) ?? suggestion,
+            };
+        }
+        const updatedDecision = getProjectDecisionById(projectId, decisionId);
+        if (!updatedDecision) {
+            throw new Error('Decision disappeared after suggestion application');
+        }
+        if (!resolvePendingProjectMemorySuggestion(projectId, suggestionId, 'applied_to_existing', updatedDecision.id)) {
+            throw new ProjectMemoryLifecycleConflictError('Suggestion changed before the application could be resolved');
+        }
+        const appliedSuggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        if (!appliedSuggestion) {
+            throw new Error('Suggestion disappeared after application');
+        }
+        const sourceOrigin = createProjectMemorySuggestionOrigin(projectId, suggestion);
+        recordProjectMemoryEvent({
+            projectId,
+            memoryKind: 'decision',
+            memoryId: updatedDecision.id,
+            eventType: 'suggestion_applied',
+            sourceSuggestionId: suggestion.id,
+            summary: sourceOrigin,
+        });
+        return { suggestion: appliedSuggestion, decision: updatedDecision };
+    });
+    try {
+        return transaction();
     }
-    if (suggestion.status !== 'pending') {
-        return { status: 409, error: 'Suggestion is no longer pending', suggestion };
+    catch (error) {
+        if (error instanceof ProjectMemoryLifecycleConflictError) {
+            return {
+                status: 409,
+                error: error.message,
+                suggestion: getProjectMemorySuggestionById(projectId, suggestionId) ?? suggestionBeforeMutation,
+            };
+        }
+        return {
+            status: 500,
+            error: 'Unable to apply the suggestion to the existing decision',
+            suggestion: getProjectMemorySuggestionById(projectId, suggestionId) ?? suggestionBeforeMutation,
+        };
     }
-    const existingDecision = getProjectDecisionById(projectId, decisionId);
-    if (!existingDecision || existingDecision.status !== ACCEPTED_PROJECT_DECISION_STATUS) {
-        return { status: 404, error: 'Decision not found', suggestion };
+};
+export const applyProjectMemorySuggestionToConvention = (projectId, suggestionId, conventionId, overrides = {}) => {
+    const transaction = db.transaction(() => {
+        const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        if (!suggestion) {
+            return { status: 404, error: 'Suggestion not found' };
+        }
+        if (suggestion.status !== 'pending') {
+            return { status: 409, error: 'Suggestion is no longer pending', suggestion };
+        }
+        const existing = getProjectConventionById(projectId, conventionId);
+        if (!existing || existing.status !== 'active') {
+            return { status: 404, error: 'Convention not found', suggestion };
+        }
+        const merged = mergeProjectMemorySuggestionConventionValues(suggestion, overrides);
+        if ('error' in merged) {
+            return { status: merged.code === 'field_too_large' ? 413 : 400, ...merged, suggestion };
+        }
+        const update = db.prepare(`UPDATE project_conventions SET title = ?, scope = ?, instruction = ?, rationale = ?, stages_json = ?, path_globs_json = ?, component_tags_json = ?, priority = ?, injection_mode = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ? AND project_id = ? AND status = 'active'`).run(merged.values.title, merged.values.scope, merged.values.instruction, merged.values.rationale, merged.values.stages_json, merged.values.path_globs_json, merged.values.component_tags_json, merged.values.priority, merged.values.injection_mode, conventionId, projectId);
+        if (update.changes !== 1 || !resolvePendingProjectMemorySuggestion(projectId, suggestionId, 'applied_to_existing', conventionId)) {
+            throw new ProjectMemoryLifecycleConflictError('Suggestion changed before the application could be resolved');
+        }
+        recordProjectMemoryEvent({ projectId, memoryKind: 'convention', memoryId: conventionId, eventType: 'suggestion_applied', sourceSuggestionId: suggestionId, summary: createProjectMemorySuggestionOrigin(projectId, suggestion) });
+        const convention = getProjectConventionById(projectId, conventionId);
+        const appliedSuggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        if (!convention || !appliedSuggestion) {
+            throw new Error('Convention disappeared after suggestion application');
+        }
+        return { suggestion: appliedSuggestion, convention };
+    });
+    try {
+        return transaction();
     }
-    const merged = mergeProjectMemorySuggestionDecisionValues(suggestion, overrides);
-    if ('error' in merged) {
-        return { status: 400, error: merged.error, suggestion };
+    catch (error) {
+        return { status: error instanceof ProjectMemoryLifecycleConflictError ? 409 : 500, error: error instanceof ProjectMemoryLifecycleConflictError ? error.message : 'Unable to apply the suggestion to the existing convention', suggestion: getProjectMemorySuggestionById(projectId, suggestionId) };
     }
-    const duplicate = classifyProjectMemorySuggestionDuplicate({
-        suggestion: {
-            kind: 'decision',
-            title: merged.values.title ?? '',
-            scope: merged.values.scope ?? null,
-            decision: merged.values.decision ?? '',
-            rationale: merged.values.rationale ?? null,
-            implications: parseStringArray(merged.values.implications_json ?? null),
-        },
-        activeConventions: [],
-        activeDecisions: listProjectDecisions(projectId).filter(decision => decision.id !== decisionId),
-        pendingSuggestions: listProjectMemorySuggestionRows(projectId, { status: 'pending' })
-            .filter(row => row.id !== suggestionId)
-            .map(toProjectMemorySuggestionCandidate)
-            .filter((candidate) => candidate !== null),
-    });
-    if (duplicate?.action === 'suppress' && duplicate.target === 'decision') {
-        return { status: 409, error: 'Updating this decision would duplicate another accepted decision', suggestion };
-    }
-    const updatedDecision = updateProjectDecision(projectId, decisionId, {
-        title: merged.values.title ?? existingDecision.title,
-        scope: merged.values.scope ?? null,
-        decision: merged.values.decision ?? existingDecision.decision,
-        rationale: merged.values.rationale ?? null,
-        implications_json: merged.values.implications_json ?? (existingDecision.implications.length > 0 ? JSON.stringify(existingDecision.implications) : null),
+};
+export const supersedeProjectDecisionFromSuggestion = (projectId, suggestionId, targetDecisionId, overrides = {}) => {
+    const transaction = db.transaction(() => {
+        const suggestion = getProjectMemorySuggestionById(projectId, suggestionId);
+        if (!suggestion) {
+            return { status: 404, error: 'Suggestion not found' };
+        }
+        if (suggestion.kind !== 'decision') {
+            return { status: 400, error: 'Only decision suggestions can supersede a decision', suggestion };
+        }
+        if (suggestion.status !== 'pending') {
+            return { status: 409, error: 'Suggestion is no longer pending', suggestion };
+        }
+        const target = getProjectDecisionById(projectId, targetDecisionId);
+        if (!target || target.status !== ACCEPTED_PROJECT_DECISION_STATUS) {
+            return { status: 404, error: 'Decision not found', suggestion };
+        }
+        const merged = mergeProjectMemorySuggestionDecisionValues(suggestion, overrides);
+        if ('error' in merged) {
+            return { status: merged.code === 'field_too_large' ? 413 : 400, ...merged, suggestion };
+        }
+        const origin = createProjectMemorySuggestionOrigin(projectId, suggestion);
+        if (!origin) {
+            return { status: 409, error: 'Suggestion source is no longer available for this project', suggestion };
+        }
+        const replacement = createProjectDecision(projectId, {
+            title: merged.values.title ?? '', scope: merged.values.scope ?? null, decision: merged.values.decision ?? '', rationale: merged.values.rationale ?? null,
+            implications_json: merged.values.implications_json ?? null, stages_json: merged.values.stages_json ?? null,
+            path_globs_json: merged.values.path_globs_json ?? null, component_tags_json: merged.values.component_tags_json ?? null,
+        }, origin);
+        if (!replacement) {
+            throw new Error('Unable to create replacement decision');
+        }
+        const superseded = db.prepare(`UPDATE project_decisions SET status = 'superseded', superseded_by_decision_id = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ? AND project_id = ? AND status = 'accepted'`).run(replacement.id, targetDecisionId, projectId);
+        if (superseded.changes !== 1 || !resolvePendingProjectMemorySuggestion(projectId, suggestionId, 'accepted', replacement.id)) {
+            throw new ProjectMemoryLifecycleConflictError('Suggestion or target changed before supersession could be applied');
+        }
+        recordProjectMemoryEvent({ projectId, memoryKind: 'decision', memoryId: targetDecisionId, eventType: 'superseded', sourceSuggestionId: suggestionId, summary: { replacement_decision_id: replacement.id } });
+        const resolved = getProjectMemorySuggestionById(projectId, suggestionId);
+        if (!resolved) {
+            throw new Error('Suggestion disappeared after supersession');
+        }
+        return { suggestion: resolved, decision: replacement };
     });
-    if (!updatedDecision) {
-        return { status: 500, error: 'Unable to update the existing decision', suggestion };
+    try {
+        return transaction();
     }
-    const updatedSuggestion = updateProjectMemorySuggestionStatus(projectId, suggestionId, 'applied_to_existing', updatedDecision.id);
-    if (!updatedSuggestion) {
-        return { status: 500, error: 'Unable to update the suggestion state', suggestion };
+    catch (error) {
+        return { status: error instanceof ProjectMemoryLifecycleConflictError ? 409 : 500, error: error instanceof ProjectMemoryLifecycleConflictError ? error.message : 'Unable to supersede the decision from the suggestion', suggestion: getProjectMemorySuggestionById(projectId, suggestionId) };
     }
-    return {
-        suggestion: updatedSuggestion,
-        decision: updatedDecision,
-    };
 };
 //# sourceMappingURL=projectMemory.js.map