@ai-content-space/loopx 0.1.3 → 0.1.5

package/src/workflow.mjs

@@ -16,6 +16,7 @@ import {
 import { doctorRuntime, ensureLoopxRoot, resolveLoopxRoot } from './runtime-maintenance.mjs';
 import { DEFAULT_BUILD_MAX_ITERATIONS, createDefaultBuildAdapter } from './build-runtime.mjs';
 import { DEFAULT_MAX_ITERATIONS, createDefaultPlanAdapter } from './plan-runtime.mjs';
+import { inspectProjectConventions } from './project-discovery.mjs';
 import { createDefaultReviewAdapter } from './review-runtime.mjs';
 import { appendWorkspaceJournal } from './workspace-memory.mjs';
 import { inspectWorkspaceContext, setupWorkspaceContext } from './workspace-context.mjs';
@@ -251,6 +252,10 @@ function resolveSpecsRoot(cwd) {
   return join(resolveWorkspaceRoot(cwd), 'specs');
 }
 
+function resolveIntakeRoot(cwd) {
+  return join(resolveWorkspaceRoot(cwd), 'intake');
+}
+
 function resolveChangesRoot(cwd) {
   return join(resolveWorkspaceRoot(cwd), 'changes');
 }
@@ -299,7 +304,7 @@ function resolveBuildSupportPaths(root, iteration) {
 }
 
 function canonicalClarifySpecPath(cwd, slug, stamp) {
-  return join(resolveSpecsRoot(cwd), `clarify-${normalizeSlug(slug)}-${stamp}.md`);
+  return join(resolveIntakeRoot(cwd), `clarify-${normalizeSlug(slug)}-${stamp}.md`);
 }
 
 export async function readWorkspaceConfig(cwd) {
@@ -336,11 +341,39 @@ function buildWorkspaceReadme() {
     '- `loopx plan <slug>`',
     '- `loopx build <slug>`',
     '- `loopx review <slug> [--reviewer <name>]`',
+    '- `loopx archive <slug>`',
     '- `loopx autopilot <slug> [--reviewer <name>]`',
+    '- `loopx render [slug|--all]`',
     '- `loopx status [slug] [--json]`',
+    '- `loopx setup-context`',
     '- `loopx doctor`',
     '- `loopx migrate`',
     '- `loopx repair-install`',
+    '',
+    '## Document Boundaries',
+    '',
+    'User-facing documents to watch:',
+    '',
+    '- `workflows/<slug>/spec.md`',
+    '- `workflows/<slug>/plan.md`, `architecture.md`, `development-plan.md`, and `test-plan.md`',
+    '- `workflows/<slug>/execution-record.md` and `review-report.md`',
+    '- `views/index.html` and `workflows/<slug>/view/index.html` after `loopx render`',
+    '',
+    'Documents users may read and edit as workflow fact sources:',
+    '',
+    '- `workflows/<slug>/*.md` for the active workflow working copy',
+    '- `context/domain.md` and `agents/*.md` for project context and collaboration guidance',
+    '- `changes/active/<change-id>/*.md` for proposal, design, tasks, and spec delta',
+    '- `specs/<domain>/spec.md` for archived long-lived behavior specs',
+    '',
+    'Tool-owned or derived files:',
+    '',
+    '- `workflows/<slug>/state.json`, `build-context.jsonl`, and `review-context.jsonl`',
+    '- `workflows/<slug>/plan-reviews/`, `build-support/`, and `review-support/`',
+    '- `intake/clarify-*.md` clarify snapshots',
+    '- `changes/active/<change-id>/slices.json` and `artifact-graph.json`',
+    '- `autopilot/<slug>/run.json` and `build-active.json`',
+    '- `views/` and `workflows/<slug>/view/` generated HTML views',
   ].join('\n');
 }
 
@@ -384,6 +417,7 @@ function createInitialState(slug, profile) {
     plan_docs_status: 'missing',
     plan_docs_artifact_paths: null,
     plan_review_artifact_paths: [],
+    plan_review_history: [],
     plan_blockers: [],
     plan_source_spec_path: null,
     change_id: changeIdForWorkflowSlug(slug),
@@ -576,28 +610,217 @@ function targetDomainsForChange(slug, sourceText) {
   return ['general'];
 }
 
-function sectionTextForHeading(text, heading, level = 2) {
-  const hashes = '#'.repeat(level);
-  const pattern = new RegExp(`${hashes} ${heading}\\n\\n([\\s\\S]*?)(?=\\n${hashes} |$)`, 'i');
-  return text.match(pattern)?.[1] || '';
+function declaredTargetDomainsForDelta(sourceText) {
+  const explicit = bulletsFromSectionText(sourceText, 'Target Spec Domains');
+  if (explicit.length > 0) {
+    return dedupeStrings(explicit.map((item) => item.replace(/`/g, '')));
+  }
+  const frontmatterDomains = frontmatterList(sourceText, 'target_domains');
+  if (frontmatterDomains.length > 0) {
+    return dedupeStrings(frontmatterDomains.map((item) => item.replace(/`/g, '')));
+  }
+  return [];
 }
 
-function parseLegacyDomainDeltas(text) {
-  const domains = targetDomainsForChange('general', text);
-  const entries = new Map();
-  for (const domain of domains) {
-    const domainText = sectionTextForHeading(text, domain, 2);
-    if (!domainText.trim()) {
-      continue;
+function stripFrontmatter(text) {
+  if (!text.startsWith('---\n')) {
+    return text;
+  }
+  const end = text.indexOf('\n---\n', 4);
+  return end === -1 ? text : text.slice(end + 5);
+}
+
+function normalizeRequirementName(raw) {
+  return String(raw || '').trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+function requirementDisplayName(raw) {
+  return String(raw || '').trim().replace(/\s+/g, ' ');
+}
+
+function sentenceToRequirementName(text, fallback) {
+  const cleaned = String(text || '')
+    .replace(/[`*_#]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/[.。:：]+$/, '');
+  if (!cleaned) {
+    return fallback;
+  }
+  const withoutModal = cleaned
+    .replace(/\bSHALL\b.*$/i, '')
+    .replace(/\bMUST\b.*$/i, '')
+    .trim();
+  const value = withoutModal || cleaned;
+  return value.length > 80 ? value.slice(0, 77).trim() : value;
+}
+
+function normativeRequirementText(text, slug, index) {
+  const cleaned = String(text || '').replace(/\s+/g, ' ').trim().replace(/[.。]+$/, '');
+  if (/\b(SHALL|MUST)\b/i.test(cleaned)) {
+    return `${cleaned}.`;
+  }
+  return `Workflow ${slug} SHALL satisfy: ${cleaned || `approved requirement ${index + 1}`}.`;
+}
+
+function scenarioNameForRequirement(name) {
+  const cleaned = requirementDisplayName(name).replace(/[.。]+$/, '');
+  return cleaned.length > 70 ? cleaned.slice(0, 67).trim() : cleaned;
+}
+
+function requirementBlockFromText({ slug, text, index }) {
+  const name = sentenceToRequirementName(text, `Approved requirement ${index + 1}`);
+  return [
+    `### Requirement: ${name}`,
+    normativeRequirementText(text, slug, index),
+    '',
+    `#### Scenario: ${scenarioNameForRequirement(name)}`,
+    `- GIVEN workflow ${slug} has an approved plan`,
+    `- WHEN the accepted implementation is archived`,
+    `- THEN the system satisfies: ${String(text || '').replace(/\s+/g, ' ').trim() || name}`,
+  ].join('\n');
+}
+
+function splitDeltaSections(text) {
+  const body = stripFrontmatter(text);
+  const pattern = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/gim;
+  const matches = [...body.matchAll(pattern)];
+  const sections = new Map();
+  for (let index = 0; index < matches.length; index += 1) {
+    const match = matches[index];
+    const kind = match[1].toUpperCase();
+    const start = match.index + match[0].length;
+    const end = index + 1 < matches.length ? matches[index + 1].index : body.length;
+    sections.set(kind, body.slice(start, end).trim());
+  }
+  return sections;
+}
+
+function parseRequirementBlocks(sectionText) {
+  const pattern = /^###\s+Requirement:\s*(.+?)\s*$/gm;
+  const matches = [...String(sectionText || '').matchAll(pattern)];
+  return matches.map((match, index) => {
+    const start = match.index;
+    const end = index + 1 < matches.length ? matches[index + 1].index : sectionText.length;
+    return {
+      name: requirementDisplayName(match[1]),
+      raw: sectionText.slice(start, end).trim(),
+    };
+  }).filter((block) => block.name && block.raw);
+}
+
+function parseRenamedRequirement(block) {
+  const inline = block.name.match(/^(.*?)\s*(?:->|=>)\s*(.*?)$/);
+  if (inline) {
+    return {
+      from: requirementDisplayName(inline[1]),
+      to: requirementDisplayName(inline[2]),
+    };
+  }
+  const from = block.raw.match(/^FROM:\s*(.+?)\s*$/im)?.[1];
+  const to = block.raw.match(/^TO:\s*(.+?)\s*$/im)?.[1];
+  return {
+    from: requirementDisplayName(from || block.name),
+    to: requirementDisplayName(to || ''),
+  };
+}
+
+function countRequirementScenarios(raw) {
+  return (String(raw || '').match(/^####\s+Scenario:\s*.+$/gim) || []).length;
+}
+
+function requirementTextBeforeScenarios(raw) {
+  const lines = String(raw || '').split('\n').slice(1);
+  const scenarioIndex = lines.findIndex((line) => /^####\s+Scenario:/i.test(line.trim()));
+  const requirementLines = scenarioIndex === -1 ? lines : lines.slice(0, scenarioIndex);
+  return requirementLines.map((line) => line.trim()).filter(Boolean).join(' ');
+}
+
+function parseRequirementDelta(text) {
+  const sections = splitDeltaSections(text);
+  const added = parseRequirementBlocks(sections.get('ADDED') || '');
+  const modified = parseRequirementBlocks(sections.get('MODIFIED') || '');
+  const removed = parseRequirementBlocks(sections.get('REMOVED') || '').map((block) => block.name);
+  const renamed = parseRequirementBlocks(sections.get('RENAMED') || '').map(parseRenamedRequirement);
+  return { added, modified, removed, renamed };
+}
+
+function deltaOperationCount(delta) {
+  return delta.added.length + delta.modified.length + delta.removed.length + delta.renamed.length;
+}
+
+function validateRequirementDelta(text) {
+  const delta = parseRequirementDelta(text);
+  const blockers = [];
+  if (deltaOperationCount(delta) === 0) {
+    blockers.push('spec_delta_missing_requirement_operations');
+    return { delta, blockers };
+  }
+  const seenBySection = {
+    added: new Set(),
+    modified: new Set(),
+    removed: new Set(),
+    renamedFrom: new Set(),
+    renamedTo: new Set(),
+  };
+  for (const [section, blocks] of [['added', delta.added], ['modified', delta.modified]]) {
+    for (const block of blocks) {
+      const key = normalizeRequirementName(block.name);
+      if (seenBySection[section].has(key)) {
+        blockers.push(`spec_delta_duplicate_${section}_${key}`);
+      }
+      seenBySection[section].add(key);
+      const requirementText = requirementTextBeforeScenarios(block.raw);
+      if (!requirementText) {
+        blockers.push(`spec_delta_${section}_${key}_missing_text`);
+      }
+      if (!/\b(SHALL|MUST)\b/i.test(requirementText)) {
+        blockers.push(`spec_delta_${section}_${key}_missing_shall_must`);
+      }
+      if (countRequirementScenarios(block.raw) === 0) {
+        blockers.push(`spec_delta_${section}_${key}_missing_scenario`);
+      }
     }
-    entries.set(domain, {
-      added: bulletsFromSectionText(domainText, 'Added Requirements').filter((item) => item !== 'none'),
-      modified: bulletsFromSectionText(domainText, 'Modified Requirements').filter((item) => item !== 'none'),
-      removed: bulletsFromSectionText(domainText, 'Removed Requirements').filter((item) => item !== 'none'),
-      scenarios: bulletsFromSectionText(domainText, 'Scenarios'),
-    });
   }
-  return entries;
+  for (const name of delta.removed) {
+    const key = normalizeRequirementName(name);
+    if (seenBySection.removed.has(key)) {
+      blockers.push(`spec_delta_duplicate_removed_${key}`);
+    }
+    seenBySection.removed.add(key);
+  }
+  for (const item of delta.renamed) {
+    const from = normalizeRequirementName(item.from);
+    const to = normalizeRequirementName(item.to);
+    if (!from || !to) {
+      blockers.push('spec_delta_renamed_missing_from_or_to');
+    }
+    if (seenBySection.renamedFrom.has(from)) {
+      blockers.push(`spec_delta_duplicate_renamed_from_${from}`);
+    }
+    if (seenBySection.renamedTo.has(to)) {
+      blockers.push(`spec_delta_duplicate_renamed_to_${to}`);
+    }
+    seenBySection.renamedFrom.add(from);
+    seenBySection.renamedTo.add(to);
+  }
+  for (const name of seenBySection.added) {
+    if (seenBySection.modified.has(name)) {
+      blockers.push(`spec_delta_conflict_added_modified_${name}`);
+    }
+    if (seenBySection.removed.has(name)) {
+      blockers.push(`spec_delta_conflict_added_removed_${name}`);
+    }
+  }
+  for (const name of seenBySection.modified) {
+    if (seenBySection.removed.has(name)) {
+      blockers.push(`spec_delta_conflict_modified_removed_${name}`);
+    }
+    if (seenBySection.renamedFrom.has(name)) {
+      blockers.push(`spec_delta_conflict_modified_renamed_from_${name}`);
+    }
+  }
+  return { delta, blockers: dedupeStrings(blockers) };
 }
 
 function requirementsForDelta(slug, plannerDraft) {
@@ -724,29 +947,18 @@ async function writeChangeArtifacts(cwd, root, slug, sourceText, plannerDraft, c
   ].join('\n'));
 
   await writeText(paths.specDelta, [
-    `# loopx Spec Delta: ${normalizedChangeId}`,
-    '',
-    '## Target Spec Domains',
-    '',
-    ...domains.map((domain) => `- ${domain}`),
-    '',
-    '## Added Requirements',
-    '',
-    ...requirements.map((item) => `- ${item}`),
-    '',
-    '## Modified Requirements',
+    '---',
+    `change_id: ${normalizedChangeId}`,
+    `slug: ${slug}`,
+    'target_domains:',
+    ...domains.map((domain) => `  - ${domain}`),
+    '---',
     '',
-    '- none',
-    '',
-    '## Removed Requirements',
-    '',
-    '- none',
+    `# loopx Spec Delta: ${normalizedChangeId}`,
     '',
-    '## Scenarios',
+    '## ADDED Requirements',
     '',
-    `- GIVEN workflow ${slug} has an approved plan`,
-    '- WHEN build and review complete successfully',
-    '- THEN the accepted behavior is merged into long-lived loopx specs during archive',
+    ...requirements.flatMap((item, index) => [requirementBlockFromText({ slug, text: item, index }), '']),
   ].join('\n'));
 
   await writeText(paths.design, [
@@ -805,26 +1017,43 @@ async function readChangeArtifactStatus(paths) {
   let specDeltaStatus = 'missing';
   if (paths.specDelta && existsSync(paths.specDelta)) {
     const text = await readFile(paths.specDelta, 'utf8');
-    const parsedDelta = parseSpecDelta(text);
-    const domainDeltas = Array.from(parsedDelta.domainDeltas?.values() || []);
-    const hasDomains = parsedDelta.domains.length > 0;
-    const hasRequirements = parsedDelta.added.length > 0
-      || parsedDelta.modified.length > 0
-      || domainDeltas.some((delta) => delta.added.length > 0 || delta.modified.length > 0);
+    const parsedDelta = validateRequirementDelta(text);
+    const declaredDomains = declaredTargetDomainsForDelta(text);
+    const hasDomains = declaredDomains.length > 0;
     if (!text.trim()) {
       specDeltaStatus = 'partial';
       blockers.push('spec_delta_empty');
-    } else if (!hasDomains || !hasRequirements) {
+    } else if (!hasDomains || parsedDelta.blockers.length > 0) {
       specDeltaStatus = 'partial';
       if (!hasDomains) {
         blockers.push('spec_delta_missing_domains');
       }
-      if (!hasRequirements) {
-        blockers.push('spec_delta_missing_requirements');
-      }
+      blockers.push(...parsedDelta.blockers);
     } else {
       specDeltaStatus = 'complete';
     }
+    const specsRoot = paths.root ? join(paths.root, 'specs') : null;
+    if (specsRoot && existsSync(specsRoot)) {
+      const entries = await readdir(specsRoot, { withFileTypes: true });
+      const declaredDomainSet = new Set(declaredDomains);
+      for (const entry of entries) {
+        if (!entry.isDirectory() || declaredDomainSet.has(entry.name)) {
+          continue;
+        }
+        const candidate = join(specsRoot, entry.name, 'spec.md');
+        if (!existsSync(candidate)) {
+          continue;
+        }
+        const domainDelta = await readFile(candidate, 'utf8');
+        const validation = validateRequirementDelta(domainDelta);
+        if (validation.blockers.length > 0) {
+          specDeltaStatus = 'partial';
+          blockers.push(
+            ...validation.blockers.map((blocker) => `spec_delta_${entry.name}_${blocker.replace(/^spec_delta_/, '')}`),
+          );
+        }
+      }
+    }
   }
   if (paths.slices && existsSync(paths.slices)) {
     try {
@@ -891,14 +1120,10 @@ async function ensureArchiveSlicesArtifact(cwd, root, slug, state) {
 }
 
 function parseSpecDelta(text) {
-  const domainDeltas = parseLegacyDomainDeltas(text);
+  const parsed = parseRequirementDelta(text);
   return {
-    domains: targetDomainsForChange('general', text),
-    added: bulletsFromSectionText(text, 'Added Requirements').filter((item) => item !== 'none'),
-    modified: bulletsFromSectionText(text, 'Modified Requirements').filter((item) => item !== 'none'),
-    removed: bulletsFromSectionText(text, 'Removed Requirements').filter((item) => item !== 'none'),
-    scenarios: bulletsFromSectionText(text, 'Scenarios'),
-    domainDeltas,
+    domains: declaredTargetDomainsForDelta(text),
+    ...parsed,
   };
 }
 
@@ -942,28 +1167,146 @@ async function writeAdrCandidate(cwd, changeId, state, archivedSpecPaths) {
   return path;
 }
 
-function replaceChangeBlock(existing, slug, nextBlock) {
-  if (!existing) {
-    return nextBlock;
+function splitSpecRequirements(existing) {
+  const text = String(existing || '');
+  const match = text.match(/^##\s+Requirements\s*$/im);
+  if (!match) {
+    return {
+      before: text.trimEnd(),
+      header: '## Requirements',
+      body: '',
+      after: '',
+    };
   }
-  const marker = `### Change: ${slug}`;
-  const start = existing.indexOf(marker);
-  if (start === -1) {
-    return [existing.replace(/\s+$/, ''), '', nextBlock].join('\n');
+  const headerStart = match.index;
+  const bodyStart = headerStart + match[0].length;
+  const rest = text.slice(bodyStart);
+  const nextTopHeading = rest.search(/\n##\s+/);
+  const body = nextTopHeading === -1 ? rest : rest.slice(0, nextTopHeading);
+  const after = nextTopHeading === -1 ? '' : rest.slice(nextTopHeading);
+  return {
+    before: text.slice(0, headerStart).trimEnd(),
+    header: match[0],
+    body: body.trim(),
+    after: after.trimEnd(),
+  };
+}
+
+function requirementMapFromSpec(existing) {
+  const parts = splitSpecRequirements(existing);
+  const blocks = parseRequirementBlocks(parts.body);
+  const map = new Map();
+  const order = [];
+  for (const block of blocks) {
+    const key = normalizeRequirementName(block.name);
+    if (!map.has(key)) {
+      order.push(key);
+    }
+    map.set(key, block);
   }
-  const before = existing.slice(0, start).replace(/\s+$/, '');
-  const rest = existing.slice(start);
-  const nextStart = rest.slice(marker.length).search(/\n### Change: /);
-  const after = nextStart === -1 ? '' : rest.slice(marker.length + nextStart).replace(/^\s+/, '\n');
-  return [before, nextBlock, after.trimEnd()].filter(Boolean).join('\n\n');
+  return { parts, map, order };
+}
+
+function applyRequirementDelta(existing, delta, domain) {
+  const { parts, map, order } = requirementMapFromSpec(existing);
+  const ensureExisting = (key, label, name) => {
+    if (!map.has(key)) {
+      throw new Error(`${domain} ${label} failed for "### Requirement: ${name}" - not found`);
+    }
+  };
+
+  for (const item of delta.renamed) {
+    const fromKey = normalizeRequirementName(item.from);
+    const toKey = normalizeRequirementName(item.to);
+    ensureExisting(fromKey, 'RENAMED', item.from);
+    if (map.has(toKey)) {
+      throw new Error(`${domain} RENAMED failed for "### Requirement: ${item.to}" - target already exists`);
+    }
+    const block = map.get(fromKey);
+    const rawLines = block.raw.split('\n');
+    rawLines[0] = `### Requirement: ${item.to}`;
+    map.delete(fromKey);
+    map.set(toKey, { name: item.to, raw: rawLines.join('\n') });
+    const orderIndex = order.indexOf(fromKey);
+    if (orderIndex !== -1) {
+      order[orderIndex] = toKey;
+    }
+  }
+
+  for (const name of delta.removed) {
+    const key = normalizeRequirementName(name);
+    ensureExisting(key, 'REMOVED', name);
+    map.delete(key);
+    const orderIndex = order.indexOf(key);
+    if (orderIndex !== -1) {
+      order.splice(orderIndex, 1);
+    }
+  }
+
+  for (const block of delta.modified) {
+    const key = normalizeRequirementName(block.name);
+    ensureExisting(key, 'MODIFIED', block.name);
+    map.set(key, block);
+  }
+
+  for (const block of delta.added) {
+    const key = normalizeRequirementName(block.name);
+    if (map.has(key)) {
+      if (map.get(key).raw.trim() === block.raw.trim()) {
+        continue;
+      }
+      throw new Error(`${domain} ADDED failed for "### Requirement: ${block.name}" - already exists`);
+    }
+    map.set(key, block);
+    order.push(key);
+  }
+
+  const requirementBody = order.map((key) => map.get(key)?.raw).filter(Boolean).join('\n\n').trimEnd();
+  return [
+    parts.before,
+    parts.header,
+    requirementBody,
+    parts.after,
+  ].filter((part) => String(part || '').trim()).join('\n\n').replace(/\n{3,}/g, '\n\n');
+}
+
+async function specDeltaFilesForArchive(cwd, specDeltaPath) {
+  const changeRoot = dirname(specDeltaPath);
+  const mainText = await readFile(specDeltaPath, 'utf8');
+  const files = new Map();
+  const declaredDomains = declaredTargetDomainsForDelta(mainText);
+  if (declaredDomains.length === 0) {
+    throw new Error('archive_blocked:spec_delta_missing_domains');
+  }
+  for (const domain of declaredDomains) {
+    files.set(domain, specDeltaPath);
+  }
+  const specsRoot = join(changeRoot, 'specs');
+  if (existsSync(specsRoot)) {
+    const entries = await readdir(specsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const candidate = join(specsRoot, entry.name, 'spec.md');
+      if (existsSync(candidate) && !files.has(entry.name)) {
+        files.set(entry.name, candidate);
+      }
+    }
+  }
+  return files;
 }
 
 async function mergeSpecDeltaIntoLongLivedSpecs(cwd, slug, specDeltaPath) {
-  const deltaText = await readFile(specDeltaPath, 'utf8');
-  const delta = parseSpecDelta(deltaText);
+  const deltaFiles = await specDeltaFilesForArchive(cwd, specDeltaPath);
   const updated = [];
-  for (const domain of delta.domains) {
-    const domainDelta = delta.domainDeltas?.get(domain) || delta;
+  for (const [domain, deltaPath] of deltaFiles.entries()) {
+    const deltaText = await readFile(deltaPath, 'utf8');
+    const validation = validateRequirementDelta(deltaText);
+    if (validation.blockers.length > 0) {
+      throw new Error(`archive_blocked:${domain}:${validation.blockers.join(',')}`);
+    }
+    const domainDelta = parseSpecDelta(deltaText);
     const path = specDomainPath(cwd, domain);
     await ensureDir(dirname(path));
     const existing = await readTextIfExists(path);
@@ -976,15 +1319,7 @@ async function mergeSpecDeltaIntoLongLivedSpecs(cwd, slug, specDeltaPath) {
       '',
       '## Requirements',
     ].join('\n');
-    const changeBlock = [
-      `### Change: ${slug}`,
-      '',
-      ...(domainDelta.added.length > 0 ? ['#### Added Requirements', '', ...domainDelta.added.map((item) => `- ${item}`), ''] : []),
-      ...(domainDelta.modified.length > 0 ? ['#### Modified Requirements', '', ...domainDelta.modified.map((item) => `- ${item}`), ''] : []),
-      ...(domainDelta.removed.length > 0 ? ['#### Removed Requirements', '', ...domainDelta.removed.map((item) => `- ${item}`), ''] : []),
-      ...(domainDelta.scenarios.length > 0 ? ['#### Scenarios', '', ...domainDelta.scenarios.map((item) => `- ${item}`)] : []),
-    ].join('\n');
-    const next = replaceChangeBlock(base, slug, changeBlock);
+    const next = applyRequirementDelta(base, domainDelta, domain);
     await writeText(path, next);
     updated.push(path);
   }
@@ -1109,6 +1444,34 @@ async function writePlanReviewArtifacts(root, iteration, plannerDraft, architect
   return paths;
 }
 
+function planReviewSummary(iteration, architectReview, criticReview) {
+  return {
+    iteration,
+    architectReview: {
+      status: architectReview.status,
+      verdict: architectReview.verdict,
+      findings: Array.isArray(architectReview.findings) ? architectReview.findings : [],
+      strongestObjection: architectReview.strongestObjection || null,
+      tradeoffTension: architectReview.tradeoffTension || null,
+    },
+    criticReview: {
+      verdict: criticReview.verdict,
+      findings: Array.isArray(criticReview.findings) ? criticReview.findings : [],
+      acceptanceCriteriaTestable: Boolean(criticReview.acceptanceCriteriaTestable),
+      verificationStepsResolved: Boolean(criticReview.verificationStepsResolved),
+      executionInputsResolved: Boolean(criticReview.executionInputsResolved),
+    },
+  };
+}
+
+function initialPlanReviewHistory(state) {
+  const history = Array.isArray(state.plan_review_history) ? state.plan_review_history : [];
+  if (state.current_stage !== STAGES.PLAN || state.stage_status !== 'blocked' || history.length === 0) {
+    return [];
+  }
+  return [history[history.length - 1]];
+}
+
 async function readPlanCompletion(cwd, root, slug, state) {
   const blockers = [];
   if (state.plan_architect_review_status !== 'complete') {
@@ -1260,6 +1623,10 @@ async function readJsonIfExists(path) {
 
 async function buildCompletionAudit({ cwd, root, slug, state, reviewReworkArtifactPath = null, iterationData, ledger, baseBlockers }) {
   const checklist = [];
+  const iterationEvidence = [
+    ...(iterationData.executionEvidence || []),
+    ...(iterationData.verificationEvidence || []),
+  ].filter(Boolean).map(String);
   const addChecklistItem = (item) => {
     checklist.push({
       status: 'covered',
@@ -1297,15 +1664,17 @@ async function buildCompletionAudit({ cwd, root, slug, state, reviewReworkArtifa
   const slicesPayload = await readJsonIfExists(state.change_artifact_paths?.slices);
   const slices = Array.isArray(slicesPayload?.slices) ? slicesPayload.slices : [];
   for (const slice of slices) {
+    const signal = String(slice.verification_signal || '').trim();
+    const usesLegacyGenericSignal = signal === 'execution-record.md verification evidence';
+    const sliceEvidence = usesLegacyGenericSignal
+      ? iterationEvidence
+      : iterationEvidence.filter((item) => item.includes(signal));
     addChecklistItem({
       id: slice.id || `slice-${checklist.length + 1}`,
       source: 'vertical-slice',
-      requirement: slice.behavior || slice.verification_signal || 'vertical slice',
-      evidence: [
-        slice.verification_signal,
-        ...(iterationData.executionEvidence || []),
-        ...(iterationData.verificationEvidence || []),
-      ].filter(Boolean),
+      status: sliceEvidence.length > 0 ? 'covered' : 'missing-evidence',
+      requirement: slice.behavior || signal || 'vertical slice',
+      evidence: sliceEvidence,
     });
   }
 
@@ -1362,6 +1731,7 @@ function buildExecutionRecordContent({ slug, iterationData, complete }) {
       completed_at: nowIso(),
       checkpoint_count: iterationData.lanes.length,
       evidence_manifest: iterationData.lanes.flatMap((lane) => lane.evidence || []),
+      changed_files: iterationData.changedFiles || [],
     }),
     `# loopx Execution Record: ${slug}`,
     '',
@@ -2140,8 +2510,10 @@ async function refreshExecutionStatus(root, state) {
 
 export async function initWorkspace(cwd, { slug } = {}) {
   const workspaceRoot = resolveWorkspaceRoot(cwd);
+  const projectConventions = await inspectProjectConventions(cwd);
   await ensureLoopxRoot(cwd);
   await ensureDir(join(workspaceRoot, 'context'));
+  await ensureDir(join(workspaceRoot, 'intake'));
   await ensureDir(join(workspaceRoot, 'workflows'));
   await ensureDir(join(workspaceRoot, 'specs'));
   await ensureDir(join(workspaceRoot, 'changes'));
@@ -2157,6 +2529,12 @@ export async function initWorkspace(cwd, { slug } = {}) {
     product_contract: 'skill-first-v1',
     default_flow: ['clarify', 'plan', 'build', 'review', 'done', 'archive'],
     preferred_surface: ['clarify', 'plan', 'build', 'review', 'archive', 'autopilot'],
+    source_of_truth_policy: projectConventions.source_of_truth_policy,
+    project_conventions: {
+      existing_ai_rules: projectConventions.existing_ai_rules,
+      existing_spec_sources: projectConventions.existing_spec_sources,
+    },
+    verification_commands: projectConventions.verification_commands,
   };
 
   if (!existsSync(workspaceConfigPath(workspaceRoot))) {
@@ -2497,13 +2875,17 @@ export async function planStage(cwd, slug, options = {}) {
   const resumesConsumedReviewPlan = state.current_stage === STAGES.PLAN
     && state.last_confirmed_transition === TRANSITIONS.REVIEW_TO_PLAN
     && state.approval.rollback === APPROVAL_STATES.APPROVED;
+  const resumesClarifyPlan = state.current_stage === STAGES.PLAN
+    && state.stage_status === 'blocked'
+    && state.last_confirmed_transition === TRANSITIONS.CLARIFY_TO_PLAN
+    && state.approval.plan === APPROVAL_STATES.APPROVED;
   if (!options.directSpecPath) {
-    if (consumesReviewPlan || resumesConsumedReviewPlan) {
-      // A no-go review may route back to plan; the printed Next command is $plan.
+    if (consumesReviewPlan || resumesConsumedReviewPlan || resumesClarifyPlan) {
+      // A no-go review or a blocked planning run may route back to plan; the printed Next command is $plan.
     } else {
       ensureApprovedTransition(state, TRANSITIONS.CLARIFY_TO_PLAN, 'plan');
     }
-    if (!consumesReviewPlan && !resumesConsumedReviewPlan && state.spec_artifact_path) {
+    if (!consumesReviewPlan && !resumesConsumedReviewPlan && !resumesClarifyPlan && state.spec_artifact_path) {
       await copyArtifact(root, state.spec_artifact_path, 'spec.md');
     }
   }
@@ -2516,6 +2898,7 @@ export async function planStage(cwd, slug, options = {}) {
   let architectReview = null;
   let criticReview = null;
   const reviewArtifactPaths = [];
+  const reviewHistory = initialPlanReviewHistory(state);
 
   while (iteration <= maxIterations) {
     const plannerDraft = await adapter.planner({
@@ -2524,6 +2907,7 @@ export async function planStage(cwd, slug, options = {}) {
       slug: normalized,
       sourceText,
       iteration,
+      reviewHistory: [...reviewHistory],
       deliberateMode: Boolean(options.deliberate),
       interactiveMode: Boolean(options.interactive),
     });
@@ -2554,6 +2938,7 @@ export async function planStage(cwd, slug, options = {}) {
     });
     const reviewPaths = await writePlanReviewArtifacts(root, iteration, plannerDraft, architectReview, criticReview);
     reviewArtifactPaths.push(reviewPaths);
+    reviewHistory.push(planReviewSummary(iteration, architectReview, criticReview));
 
     state = {
       ...state,
@@ -2573,6 +2958,7 @@ export async function planStage(cwd, slug, options = {}) {
       plan_package_status: 'complete',
       plan_docs_artifact_paths: null,
       plan_review_artifact_paths: reviewArtifactPaths,
+      plan_review_history: reviewHistory,
       plan_artifact_path: artifactPaths.planPath,
       test_spec_artifact_path: artifactPaths.testSpecPath,
       change_id: normalizeSlug(changeId),
@@ -2662,6 +3048,7 @@ export async function buildStage(cwd, slug, options = {}) {
   const ownerId = buildOwnerId(normalized);
   let iteration = 1;
   let current = null;
+  let accumulatedChangedFiles = [];
   let blockers = ['build_not_started'];
   let delegationLedger = null;
   let completionAudit = null;
@@ -2736,6 +3123,14 @@ export async function buildStage(cwd, slug, options = {}) {
       contextManifestRows: buildManifest.rows,
       contextManifestStatus,
     });
+    accumulatedChangedFiles = dedupeStrings([
+      ...accumulatedChangedFiles,
+      ...(Array.isArray(current.changedFiles) ? current.changedFiles : []),
+    ]);
+    current = {
+      ...current,
+      changedFiles: accumulatedChangedFiles,
+    };
     const supportPaths = resolveBuildSupportPaths(root, current.iteration);
     delegationLedgerPath = supportPaths.delegationLedger;
     completionAuditPath = supportPaths.completionAudit;
@@ -2903,14 +3298,14 @@ function reviewFindings({ executionMeta, executionStatus, reviewer, codeReview,
   if (executionStatus !== 'complete') {
     findings.push('execution-record.md 缺少必要的执行或验证证据。');
     verdict = 'REQUEST CHANGES';
-    rollbackTarget = 'plan';
-    rollbackRationale = '执行证据不完整，工作流需要回退到计划阶段后再重新执行。';
+    rollbackTarget = STAGES.BUILD;
+    rollbackRationale = '执行证据不完整，工作流需要回到 build 阶段补齐执行和验证证据后重新 review。';
   }
   if (!Array.isArray(executionMeta.evidence_manifest) || executionMeta.evidence_manifest.length === 0) {
     findings.push('execution-record.md 缺少必需的 evidence_manifest 结构。');
     verdict = 'REQUEST CHANGES';
-    rollbackTarget = 'plan';
-    rollbackRationale = '执行证据结构不完整，review 不能接受本次运行。';
+    rollbackTarget = STAGES.BUILD;
+    rollbackRationale = '执行证据结构不完整，review 不能接受本次运行，需要回到 build 阶段补齐 evidence_manifest。';
   }
   if (executionMeta.actor_id === reviewer) {
     findings.push('Reviewer 来源与执行者一致，不满足独立审查要求。');
@@ -3133,6 +3528,12 @@ export async function reviewStage(cwd, slug, { reviewer = 'independent-reviewer'
     ensureApprovedTransition(state, TRANSITIONS.BUILD_TO_REVIEW, 'review');
   }
   const { state: refreshed, executionSummary } = await refreshExecutionStatus(root, state);
+  const buildOwnedChangedFilesStatus = Object.hasOwn(executionSummary.meta, 'changed_files')
+    ? 'present'
+    : 'unavailable';
+  const buildOwnedChangedFiles = buildOwnedChangedFilesStatus === 'present' && Array.isArray(executionSummary.meta.changed_files)
+    ? executionSummary.meta.changed_files
+    : [];
   const reviewManifest = await readContextManifest(reviewContextManifestPath(root), { cwd });
   ensureValidContextManifest(reviewManifest, STAGES.REVIEW);
   const reviewAdapter = adapter || createDefaultReviewAdapter();
@@ -3146,9 +3547,11 @@ export async function reviewStage(cwd, slug, { reviewer = 'independent-reviewer'
       executionRecordPath: artifactPath(root, 'execution-record.md'),
       planArtifactPath: refreshed.plan_artifact_path,
       testSpecArtifactPath: refreshed.test_spec_artifact_path,
+      buildOwnedChangedFiles,
       contextManifestStatus: reviewManifest.status,
       contextManifestPath: reviewContextManifestPath(root),
       contextManifestRows: reviewManifest.rows,
+      buildOwnedChangedFilesStatus,
     });
   } catch (error) {
     codeReview = codeReviewFailureResult(error);
@@ -3168,9 +3571,11 @@ export async function reviewStage(cwd, slug, { reviewer = 'independent-reviewer'
         planArtifactPath: refreshed.plan_artifact_path,
         testSpecArtifactPath: refreshed.test_spec_artifact_path,
         changeArtifactPaths: refreshed.change_artifact_paths,
+        buildOwnedChangedFiles,
         contextManifestStatus: reviewManifest.status,
         contextManifestPath: reviewContextManifestPath(root),
         contextManifestRows: reviewManifest.rows,
+        buildOwnedChangedFilesStatus,
       });
     } catch (error) {
       architectureReview = architectureReviewFailureResult(error);