@surlymochan/evalid 0.0.0-stage → 0.3.1

package/src/core/competitive-score.js

@@ -0,0 +1,265 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+const STATUS_POINTS = {
+  strong: 10,
+  improving: 8,
+  needs_work: 5,
+  weak: 2,
+};
+
+const DIMENSIONS = [
+  {
+    id: 'local_delivery_closure',
+    label: 'Local delivery closure',
+    evidence: [
+      ['file', 'workflows/yolo.yaml'],
+      ['file', 'workflows/corps.yaml'],
+      ['text', 'HANDOFF.md', /archive/i],
+    ],
+  },
+  {
+    id: 'executable_workflow_data',
+    label: 'Executable workflow data',
+    evidence: [
+      ['file', 'schemas/workflow.schema.json'],
+      ['text', 'test/workflow-loader.test.js', /Workflow: yolo\.yaml/],
+      ['text', 'test/workflow-loader.test.js', /Workflow: corps\.yaml/],
+    ],
+  },
+  {
+    id: 'goal_alignment',
+    label: 'Goal alignment',
+    evidence: [
+      ['file', 'docs/goal-vs-codex.md'],
+      ['text', 'bin/xflow.js', /case 'goal'/],
+      ['text', 'bin/xflow.js', /goal audit/],
+      ['text', 'bin/xflow.js', /codex-goal/],
+      ['text', 'README.md', /xflow goal set/],
+      ['text', 'README.md', /docs\/goal-vs-codex\.md/],
+      ['text', 'docs/tooling-matrix.md', /skill family as a ladder/],
+      ['text', 'docs/tooling-matrix.md', /xflow goal set/],
+      ['text', 'docs/competitive-benchmark.md', /Goal alignment/],
+      ['text', 'docs/competitive-benchmark.md', /xflow compare codex-goal/],
+      ['text', 'docs/competitive-benchmark.md', /xflow goal show --json/],
+      ['text', 'docs/competitive-benchmark.md', /xflow goal audit --json/],
+      ['text', 'xflow/goal/SKILL.md', /Advantage Over Codex Native Goal/],
+      ['text', 'xflow/yolo/SKILL.md', /aligns with it, intentionally narrows it, or conflicts with it/],
+      ['text', 'xflow/corps/SKILL.md', /final proof review/],
+      ['text', 'xflow/ralph/SKILL.md', /intentionally diverges from the goal/],
+    ],
+  },
+  {
+    id: 'verification_rigor',
+    label: 'Verification rigor',
+    evidence: [
+      ['text', 'package.json', /"drift:scan"/],
+      ['text', 'package.json', /"skill:diff"/],
+      ['file', 'test/release-checklist.test.js'],
+    ],
+  },
+  {
+    id: 'tdd_code_quality_push',
+    label: 'TDD / code quality push',
+    evidence: [
+      ['text', 'xflow/atoms/i6a_tdd_run.py', /Red expects a failing test/],
+      ['text', 'xflow/atoms/i6b_tdd_proof_validate.py', /Red must prove a failing test/],
+      ['text', 'xflow/atoms/i6c_tdd_quality_review.py', /code changes should be accompanied by test changes/],
+      ['file', 'test/tdd-proof.test.js'],
+      ['text', 'workflows/yolo.yaml', /tdd-red[\s\S]*execute[\s\S]*tdd-green/],
+      ['text', 'workflows/corps.yaml', /I6c\.tdd\.quality_review/],
+    ],
+  },
+  {
+    id: 'operator_onboarding',
+    label: 'Operator onboarding',
+    evidence: [
+      ['text', 'README.md', /3 Minute Start/],
+      ['text', 'bin/xflow.js', /case 'init'/],
+      ['text', 'bin/xflow.js', /case 'doctor'/],
+      ['text', 'bin/xflow.js', /case 'guide'/],
+      ['text', 'docs/quickstart.md', /xflow init --project-root \./],
+      ['file', 'docs/walkthrough.md'],
+    ],
+  },
+  {
+    id: 'spec_durability',
+    label: 'Spec durability',
+    evidence: [
+      ['file', 'specs/workflow.md'],
+      ['file', 'AHA.md'],
+      ['file', 'HANDOFF.md'],
+      ['file', 'docs/openspec-migration.md'],
+      ['text', 'xflow/atoms/j4b_spec_delta_review.py', /Spec Delta Review/],
+      ['text', 'xflow/atoms/j4c_openspec_migration_map.py', /OpenSpec project to evalid surfaces/],
+    ],
+  },
+  {
+    id: 'cross_tool_portability',
+    label: 'Cross-tool portability',
+    evidence: [
+      ['file', 'docs/tooling-matrix.md'],
+      ['file', 'docs/integrations.md'],
+      ['text', 'docs/tooling-matrix.md', /Codex CLI \/ App/],
+      ['text', 'docs/tooling-matrix.md', /Gemini CLI/],
+      ['text', 'docs/compatibility.md', /Claude Code/],
+      ['text', 'docs/compatibility.md', /Cursor/],
+      ['text', 'docs/compatibility.md', /OpenCode/],
+      ['text', 'bin/xflow.js', /case 'adapter'/],
+      ['text', 'docs/integrations.md', /xflow adapter import-file/],
+      ['text', 'xflow/openissue/scripts/open_issue_flow.py', /configured_issue_repo/],
+      ['text', 'xflow/scripts/sync_installed_xflow_skill.sh', /config_value/],
+    ],
+  },
+  {
+    id: 'public_product_clarity',
+    label: 'Public product clarity',
+    evidence: [
+      ['file', 'README.md'],
+      ['file', 'docs/competitive-benchmark.md'],
+      ['file', 'docs/superpowers-comparison.md'],
+      ['file', 'docs/quality-assessment.md'],
+      ['file', 'docs/launch-demo.md'],
+      ['file', 'docs/launch-dossier.md'],
+      ['file', 'docs/examples-gallery.md'],
+      ['file', 'docs/corps-operator-guide.md'],
+      ['file', 'docs/adoption/README.md'],
+      ['file', 'docs/adoption/openflow-release-hardening.md'],
+      ['file', 'docs/demo-proof.md'],
+      ['file', 'docs/openspec-migration.md'],
+      ['file', 'docs/spec-kit-benchmark.md'],
+      ['file', 'docs/public-benchmark.md'],
+      ['file', 'docs/npm-publish-handoff.md'],
+      ['file', 'docs/walkthrough.md'],
+      ['file', 'docs/methodology.md'],
+      ['file', 'RELEASE_NOTES.md'],
+      ['file', 'docs/quickstart.md'],
+      ['text', 'xflow/README.md', /docs\/quickstart\.md/],
+      ['text', 'bin/xflow.js', /case 'assess'/],
+      ['text', 'bin/xflow.js', /case 'demo'/],
+      ['text', 'bin/xflow.js', /case 'launch'/],
+      ['text', 'bin/xflow.js', /case 'quickstart'/],
+      ['text', 'bin/xflow.js', /launch dossier/],
+      ['text', 'bin/xflow.js', /case 'adoption'/],
+      ['text', 'bin/xflow.js', /case 'package'/],
+      ['text', 'docs/quality-assessment.md', /xflow assess --json/],
+      ['text', 'docs/launch-demo.md', /goal -> yolo/],
+      ['text', 'docs/launch-demo.md', /goal -> corps proof/],
+      ['text', 'docs/examples-gallery.md', /Goal To yolo/],
+      ['text', 'docs/examples-gallery.md', /External Tracker Import/],
+      ['text', 'docs/launch-dossier.md', /Missing Before Splash Launch/],
+      ['text', 'docs/launch-dossier.md', /published_package/],
+      ['text', 'docs/corps-operator-guide.md', /xflow corps --explain/],
+      ['text', 'docs/launch-demo.md', /xflow launch dossier/],
+      ['text', 'docs/public-release.md', /xflow launch audit --strict --json/],
+      ['text', 'docs/public-release.md', /xflow launch audit --pre-publish --strict --json/],
+      ['text', 'docs/public-release.md', /xflow adoption validate --json/],
+      ['text', 'docs/public-release.md', /xflow package preflight --check-registry --check-auth --json/],
+      ['text', 'docs/public-release.md', /xflow package audit --check-registry --json/],
+      ['text', 'docs/npm-publish-handoff.md', /npm publish --access public/],
+      ['text', 'docs/adoption/README.md', /Required Shape/],
+      ['text', 'docs/adoption/README.md', /Acceptance Bar/],
+      ['text', 'docs/adoption/README.md', /xflow adoption init/],
+      ['text', 'docs/adoption/README.md', /xflow adoption validate --json/],
+      ['text', 'docs/adoption/openflow-release-hardening.md', /xflow launch audit --strict --json/],
+      ['text', 'bin/xflow.js', /case 'spec'/],
+      ['text', 'bin/xflow.js', /case 'adapter'/],
+      ['text', 'bin/xflow.js', /case 'compare'/],
+      ['text', 'bin/xflow.js', /superpowers/],
+      ['text', 'bin/xflow.js', /case 'score'/],
+    ],
+  },
+  {
+    id: 'team_collaboration',
+    label: 'Team collaboration',
+    evidence: [
+      ['file', 'docs/reviewer-guide.md'],
+      ['text', 'docs/reviewer-guide.md', /verify_proof\.json/],
+      ['text', 'docs/reviewer-guide.md', /A5\.archive\.commit_push_close/],
+      ['file', 'docs/team-adoption.md'],
+      ['text', 'docs/team-adoption.md', /95 Percent Readiness Gate/],
+      ['text', 'docs/team-adoption.md', /Operator/],
+      ['text', 'docs/team-adoption.md', /Release owner/],
+      ['text', 'docs/team-adoption.md', /PR Acceptance Checklist/],
+      ['text', 'README.md', /docs\/team-adoption\.md/],
+    ],
+  },
+  {
+    id: 'control_plane_observability',
+    label: 'Control-plane observability',
+    evidence: [
+      ['file', 'src/server.js'],
+      ['text', 'test/server.test.js', /timeline analytics/],
+      ['text', 'test/server.test.js', /orphaned/],
+    ],
+  },
+  {
+    id: 'ecosystem_packaging',
+    label: 'Ecosystem packaging',
+    evidence: [
+      ['text', 'package.json', /"bin"/],
+      ['text', 'package.json', /"pack:check"/],
+      ['text', 'package.json', /"release:pack"/],
+      ['text', 'package.json', /"publish:check"/],
+      ['text', 'package.json', /"README\.md"/],
+      ['text', 'package.json', /"RELEASE_NOTES\.md"/],
+      ['file', 'docs/install-upgrade.md'],
+      ['file', 'docs/public-release.md'],
+      ['file', 'docs/public-benchmark.md'],
+      ['file', 'docs/npm-publish-handoff.md'],
+      ['text', 'docs/install-upgrade.md', /npm install -g @surlymochan\/evalid/],
+      ['text', 'docs/install-upgrade.md', /xflow package preflight --check-registry --check-auth --json/],
+      ['file', 'docs/demo-proof.md'],
+      ['file', 'docs/fixtures/tracker-item.json'],
+      ['text', '.github/workflows/ci.yml', /Minimal External Adoption Example/],
+    ],
+  },
+];
+
+export function buildCompetitiveScore({ root = ROOT } = {}) {
+  const dimensions = DIMENSIONS.map((dimension) => {
+    const evidence = dimension.evidence.map((item) => evaluateEvidence(root, item));
+    const passed = evidence.filter((item) => item.ok).length;
+    const status = passed === evidence.length ? 'strong' : passed > 0 ? 'improving' : 'weak';
+    return {
+      id: dimension.id,
+      label: dimension.label,
+      status,
+      points: STATUS_POINTS[status],
+      evidence,
+    };
+  });
+  const total = dimensions.reduce((sum, dimension) => sum + dimension.points, 0);
+  const max = dimensions.length * 10;
+  const weakDimensions = dimensions.filter((dimension) => dimension.status !== 'strong');
+
+  return {
+    ok: weakDimensions.length === 0,
+    score: Math.round((total / max) * 100),
+    max_score: 100,
+    dimensions,
+    next_wins: weakDimensions.length
+      ? weakDimensions.map((dimension) => `Strengthen evidence for ${dimension.label}.`)
+      : ['Keep score evidence generated from repo files as new competitive surfaces are added.'],
+  };
+}
+
+function evaluateEvidence(root, [type, relativePath, pattern]) {
+  const path = resolve(root, relativePath);
+  if (type === 'file') {
+    return { type, path: relativePath, ok: existsSync(path) };
+  }
+
+  if (type === 'text') {
+    if (!existsSync(path)) {
+      return { type, path: relativePath, ok: false, pattern: String(pattern) };
+    }
+    const content = readFileSync(path, 'utf8');
+    return { type, path: relativePath, ok: pattern.test(content), pattern: String(pattern) };
+  }
+
+  return { type, path: relativePath, ok: false };
+}

package/src/core/concurrency-policy.js

@@ -0,0 +1,35 @@
+const DEFAULT_MAX_AGENTS = 3;
+
+function normalizePositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    return fallback;
+  }
+  return Math.floor(parsed);
+}
+
+export function createConcurrencyPolicy({ workflow = {}, maxParallelAgentsOverride = null } = {}) {
+  const workflowParallel = workflow.parallel || {};
+  const configuredMaxAgents = normalizePositiveInteger(workflowParallel.max_agents, DEFAULT_MAX_AGENTS);
+  const hasOverride = maxParallelAgentsOverride !== null && maxParallelAgentsOverride !== undefined;
+  const maxAgents = hasOverride
+    ? normalizePositiveInteger(maxParallelAgentsOverride, configuredMaxAgents)
+    : configuredMaxAgents;
+  const mode = workflowParallel.policy || 'weighted';
+
+  return {
+    mode,
+    maxAgents,
+    source: hasOverride ? 'mission_override' : 'workflow',
+    weightFor(atomRef = {}, registry = {}) {
+      const atomDef = registry.atoms?.[atomRef.id] || {};
+      return normalizePositiveInteger(atomRef.parallel_weight ?? atomDef.parallel_weight, 1);
+    },
+    chargeFor(atomRef = {}, registry = {}) {
+      if (mode === 'fixed') {
+        return 1;
+      }
+      return Math.min(this.weightFor(atomRef, registry), maxAgents);
+    },
+  };
+}

package/src/core/execution-log.js

@@ -0,0 +1,108 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { buildLogEntryHash, validateExecutionLogChain } from './workflow-integrity.js';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+let appendQueue = Promise.resolve();
+
+export function resolveExecutionLogPath(projectRoot = process.cwd()) {
+  return resolve(projectRoot, '.as-xflow', 'logs', 'execution.ndjson');
+}
+
+export async function appendExecutionLog(projectRoot, entry = {}) {
+  const append = appendQueue.then(
+    () => appendExecutionLogUnlocked(projectRoot, entry),
+    () => appendExecutionLogUnlocked(projectRoot, entry),
+  );
+  appendQueue = append.catch(() => {});
+  return append;
+}
+
+async function appendExecutionLogUnlocked(projectRoot, entry = {}) {
+  const file = resolveExecutionLogPath(projectRoot);
+  await mkdir(dirname(file), { recursive: true });
+  const previousHash = await readLastEntryHash(file);
+  const payload = {
+    timestamp: nowIso(),
+    ...entry,
+    prev_hash: previousHash,
+  };
+  payload.entry_hash = buildLogEntryHash(payload);
+  await appendFile(file, `${JSON.stringify(payload)}\n`, 'utf8');
+  return file;
+}
+
+export function appendExecutionLogSync(projectRoot, entry = {}) {
+  const file = resolveExecutionLogPath(projectRoot);
+  mkdirSync(dirname(file), { recursive: true });
+  const previousHash = readLastEntryHashSync(file);
+  const payload = {
+    timestamp: nowIso(),
+    ...entry,
+    prev_hash: previousHash,
+  };
+  payload.entry_hash = buildLogEntryHash(payload);
+  appendFileSync(file, `${JSON.stringify(payload)}\n`, 'utf8');
+  return file;
+}
+
+export async function readExecutionLog(projectRoot, options = {}) {
+  const file = resolveExecutionLogPath(projectRoot);
+  const limit = Math.max(1, Number(options.limit || 20));
+
+  try {
+    const raw = await readFile(file, 'utf8');
+    const chronological = raw
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return { kind: 'invalid_log_line', raw: line };
+        }
+      });
+    const chain = validateExecutionLogChain(chronological);
+    const entries = chronological.slice(-limit).reverse();
+
+    return { file, entries, entries_chronological: chronological, chain };
+  } catch {
+    return { file, entries: [], entries_chronological: [], chain: { ok: true, issues: [], entries_checked: 0 } };
+  }
+}
+
+async function readLastEntryHash(file) {
+  try {
+    const raw = await readFile(file, 'utf8');
+    return lastEntryHashFromRaw(raw);
+  } catch {
+    return null;
+  }
+}
+
+function readLastEntryHashSync(file) {
+  try {
+    const raw = readFileSync(file, 'utf8');
+    return lastEntryHashFromRaw(raw);
+  } catch {
+    return null;
+  }
+}
+
+function lastEntryHashFromRaw(raw) {
+  const lines = raw.split('\n').map((line) => line.trim()).filter(Boolean);
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    try {
+      const entry = JSON.parse(lines[index]);
+      if (entry.entry_hash) return entry.entry_hash;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}

package/src/core/intake-recommendation.js

@@ -0,0 +1,134 @@
+import { resolveChangePath, writeJsonFile } from './change-artifacts.js';
+
+const TYPE_PATTERNS = [
+  ['hotfix', ['hotfix', '紧急修复', '线上问题', 'p0']],
+  ['bugfix', ['bug', 'fix', '修复', '缺陷', '报错']],
+  ['config-change', ['config', '配置', '开关', '阈值', '环境变量']],
+  ['docs', ['doc', 'docs', 'readme', '文档', '说明']],
+  ['refactor', ['refactor', '重构', '技术债', '解耦']],
+  ['feature', ['feature', '新增', '功能', '需求']],
+];
+
+export function buildWorkflowRecommendation(input = {}, effectivePolicy = {}) {
+  const profile = buildDemandProfile(input);
+  const mode = effectivePolicy.execution_mode || input.execution_mode || 'personal';
+  const recommendedTrack = chooseTrack(profile);
+  const requiresCoverageGate = shouldRequireCoverage(profile, effectivePolicy);
+  const requiresHumanCheckpoint = ['critical', 'elevated'].includes(profile.risk_level)
+    || profile.complexity === 'critical';
+  const requiresTeamNotification = mode === 'team' && (requiresHumanCheckpoint || recommendedTrack === 'corps');
+
+  return {
+    version: 1,
+    generated_at: new Date().toISOString(),
+    recommended_track: recommendedTrack,
+    requires_coverage_gate: requiresCoverageGate,
+    requires_human_checkpoint: requiresHumanCheckpoint,
+    requires_team_notification: requiresTeamNotification,
+    profile,
+    policy_overlay: {
+      execution_mode: mode,
+      workflows_remain: ['yolo', 'corps'],
+      creates_team_workflow_fork: false,
+    },
+    reasons: buildReasons(profile, recommendedTrack, {
+      requiresCoverageGate,
+      requiresHumanCheckpoint,
+      requiresTeamNotification,
+    }),
+  };
+}
+
+export function writeWorkflowRecommendation({ projectRoot, changeId, input = {}, effectivePolicy = {} }) {
+  const recommendation = buildWorkflowRecommendation(input, effectivePolicy);
+  const outputPath = resolveChangePath(projectRoot, changeId, 'workflow_recommendation.json');
+  writeJsonFile(outputPath, recommendation);
+  return { ok: true, recommendation, workflow_recommendation_file: outputPath };
+}
+
+export function buildDemandProfile(input = {}) {
+  const title = String(input.title || input.requirement_title || input.req_name || '').trim();
+  const description = String(input.description || input.requirement_description || '').trim();
+  const combined = `${title} ${description}`.toLowerCase();
+  const repoCount = normalizeRepoCount(input);
+  const estimatedFileCount = Number(input.estimated_file_count || input.file_count || 1);
+  const demandType = input.demand_type || input.change_type || classifyDemandType(combined);
+  const affectsApi = hasAny(combined, ['api', '接口', 'endpoint', 'rpc', 'grpc']);
+  const affectsDatabase = hasAny(combined, ['database', 'db', '数据库', 'ddl', 'migration', 'schema']);
+  const involvesPayment = hasAny(combined, ['payment', '支付', 'pay', 'billing', '结算']);
+  const involvesUserData = hasAny(combined, ['user data', '用户数据', '隐私', '个人信息']);
+  const riskLevel = assessRisk({ involvesPayment, involvesUserData, affectsDatabase, repoCount });
+  const complexity = assessComplexity({ repoCount, estimatedFileCount, affectsApi, affectsDatabase, riskLevel });
+
+  return {
+    demand_type: normalizeDemandType(demandType),
+    complexity,
+    risk_level: riskLevel,
+    repo_count: repoCount,
+    estimated_file_count: estimatedFileCount,
+    cross_service: repoCount > 1,
+    affects_api: affectsApi,
+    affects_database: affectsDatabase,
+    involves_payment: involvesPayment,
+    involves_user_data: involvesUserData,
+    title,
+  };
+}
+
+function classifyDemandType(text) {
+  for (const [type, patterns] of TYPE_PATTERNS) {
+    if (patterns.some((pattern) => text.includes(pattern))) return type;
+  }
+  return 'feature';
+}
+
+function normalizeDemandType(type) {
+  if (type === 'documentation') return 'docs';
+  if (type === 'backend' || type === 'frontend' || type === 'full-stack') return 'feature';
+  return type || 'feature';
+}
+
+function normalizeRepoCount(input = {}) {
+  if (Array.isArray(input.repositories)) return input.repositories.length || 1;
+  const value = Number(input.repo_count || input.repositories || 1);
+  return Number.isFinite(value) && value > 0 ? value : 1;
+}
+
+function assessRisk({ involvesPayment, involvesUserData, affectsDatabase, repoCount }) {
+  if (involvesPayment || involvesUserData) return 'critical';
+  if (affectsDatabase || repoCount > 1) return 'elevated';
+  return 'standard';
+}
+
+function assessComplexity({ repoCount, estimatedFileCount, affectsApi, affectsDatabase, riskLevel }) {
+  if (riskLevel === 'critical' || repoCount > 3 || estimatedFileCount > 20) return 'critical';
+  if (repoCount > 1 || estimatedFileCount > 8 || affectsDatabase) return 'high';
+  if (estimatedFileCount > 3 || affectsApi) return 'medium';
+  return 'low';
+}
+
+function chooseTrack(profile) {
+  if (profile.demand_type === 'docs' && profile.risk_level === 'standard') return 'yolo';
+  if (profile.risk_level === 'critical' || profile.complexity === 'critical' || profile.cross_service) return 'corps';
+  return 'yolo';
+}
+
+function shouldRequireCoverage(profile, policy = {}) {
+  if (profile.demand_type === 'docs') return false;
+  if (policy?.coding?.min_changed_line_coverage !== undefined) return true;
+  return ['feature', 'bugfix', 'hotfix', 'refactor'].includes(profile.demand_type);
+}
+
+function buildReasons(profile, track, flags) {
+  const reasons = [`track:${track}`];
+  if (profile.cross_service) reasons.push('cross_service');
+  if (profile.risk_level !== 'standard') reasons.push(`risk:${profile.risk_level}`);
+  if (flags.requiresCoverageGate) reasons.push('coverage_gate');
+  if (flags.requiresHumanCheckpoint) reasons.push('human_checkpoint');
+  if (flags.requiresTeamNotification) reasons.push('team_notification');
+  return reasons;
+}
+
+function hasAny(text, patterns) {
+  return patterns.some((pattern) => text.includes(pattern));
+}

package/src/core/memory-state.js

@@ -0,0 +1,62 @@
+import { resolveBoundMissionId } from './bindings.js';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function ensureArray(value) {
+  return Array.isArray(value) ? value : value ? [value] : [];
+}
+
+function makeId() {
+  return `mem_${Math.random().toString(36).slice(2, 14)}`;
+}
+
+export function createMemoryItem(state, input = {}) {
+  state.memories = ensureArray(state.memories);
+  const timestamp = nowIso();
+  const item = {
+    memory_id: makeId(),
+    mission_id: input.mission_id || null,
+    scope: input.scope || (input.mission_id ? 'mission' : 'project'),
+    scope_ref: input.scope_ref || input.mission_id || input.workspace_id || 'default-workspace',
+    kind: input.kind || 'fact',
+    category: input.category || 'workflow',
+    status: input.status || 'active',
+    canonical_text: input.canonical_text || input.text || '',
+    structured_payload: input.structured_payload || {},
+    source_events: ensureArray(input.source_events),
+    evidence_refs: ensureArray(input.evidence_refs),
+    created_at: timestamp,
+    updated_at: timestamp,
+  };
+  state.memories.unshift(item);
+  return item;
+}
+
+export function listMemoryItems(state, filter = {}) {
+  return ensureArray(state.memories).filter((item) => {
+    if (filter.mission_id && item.mission_id !== filter.mission_id) return false;
+    if (filter.scope && item.scope !== filter.scope) return false;
+    if (filter.status && item.status !== filter.status) return false;
+    return true;
+  });
+}
+
+export function buildMemoryMount(state, input = {}) {
+  const items = listMemoryItems(state, input).slice(0, Number(input.limit || 20));
+  return {
+    mission_id: input.mission_id || null,
+    total: items.length,
+    items,
+  };
+}
+
+export function resolveMemoryMissionId(input = {}, context = {}) {
+  return resolveBoundMissionId({
+    projectRoot: context.projectRoot || process.cwd(),
+    changeId: context.changeId || input.change_id || null,
+    missionId: input.mission_id || null,
+    runtimeMissionId: context.runtime?.missionId || null,
+  });
+}