agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/src/application/services/intake-service.ts

@@ -0,0 +1,1468 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { atomicWriteJson, nowIso, readJson } from '../../core/fs.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import type {
+  BootstrapManifest,
+  IntakeClarificationAnswer,
+  IntakeReview,
+  IntakeSubmission,
+  IntakeSummary,
+  ManifestConfidence,
+  ManifestObligation,
+  ManifestObligationKind,
+  ManifestSourceRef,
+  ManifestVerificationHint,
+  VerifiedManifest,
+} from '../../core/intake-artifacts.js';
+import {
+  normalizeManifestConfidence,
+  obligationsMeetConfidenceThreshold,
+} from '../../core/intake-artifacts.js';
+import { GATE_RESULT, STATUS } from '../../core/constants.js';
+import { fail } from '../../core/response.js';
+import { BootstrapManifestGeneratorService } from './bootstrap-manifest-generator-service.js';
+
+type StateRecord = Record<string, unknown>;
+type QuestionEvidenceRecord = {
+  question_id: string | null;
+  status: string;
+  question_type: string | null;
+  phase: string | null;
+  resume_status: string | null;
+  resume_phase: string | null;
+  prompt: string | null;
+  answer: string | Record<string, unknown> | null;
+  answered_at: string | null;
+  answered_by: string | null;
+  details: Record<string, unknown>;
+};
+
+type StateUpdater = (
+  frontMatter: StateRecord,
+  body: string,
+) => Promise<{ frontMatter?: StateRecord; body?: string }>;
+
+const AMBIGUITY_ID_TOKEN_PATTERN = /\bAMB[\s_-]*(\d{1,})\b/gi;
+const OBLIGATION_ID_TOKEN_PATTERN = /\bOBL(?:[\s_-]*V)?[\s_-]*(\d{1,})\b/gi;
+const MANIFEST_REVIEW_AMBIGUITY_ID = 'AMB-MANIFEST-REVIEW';
+
+const OBLIGATION_KIND_ALIASES: Record<string, ManifestObligationKind> = {
+  artifact: 'artifact',
+  behavior: 'behavior',
+  component: 'artifact',
+  constraint: 'contract',
+  contract: 'contract',
+  endpoint: 'endpoint',
+  flow: 'workflow',
+  integration: 'integration',
+  route: 'endpoint',
+  schema: 'contract',
+  screen: 'artifact',
+  test: 'verification',
+  ui: 'artifact',
+  validation: 'verification',
+  verification: 'verification',
+  view: 'artifact',
+  workflow: 'workflow',
+};
+
+const VERIFICATION_HINT_ALIASES: Record<string, ManifestVerificationHint> = {
+  must: 'required',
+  optional: 'optional',
+  required: 'required',
+  shall: 'required',
+};
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function asAnswerValue(value: unknown): string | Record<string, unknown> | null {
+  const stringValue = asString(value);
+  if (stringValue !== null) {
+    return stringValue;
+  }
+  return asRecord(value);
+}
+
+function normalizeUniqueStrings(values: string[]): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function extractCanonicalIdMatches(
+  value: unknown,
+  pattern: RegExp,
+  prefix: 'AMB' | 'OBL',
+): string[] {
+  if (typeof value === 'string') {
+    return Array.from(value.matchAll(new RegExp(pattern.source, 'gi')), (match) => {
+      const digits = match[1] ?? '';
+      return `${prefix}-${digits.padStart(3, '0')}`;
+    });
+  }
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((entry) => extractCanonicalIdMatches(entry, pattern, prefix));
+}
+
+function normalizeAmbiguityIds(value: unknown): string[] {
+  return normalizeUniqueStrings(
+    extractCanonicalIdMatches(value, AMBIGUITY_ID_TOKEN_PATTERN, 'AMB'),
+  );
+}
+
+function normalizeObligationIds(value: unknown): string[] {
+  return normalizeUniqueStrings(
+    extractCanonicalIdMatches(value, OBLIGATION_ID_TOKEN_PATTERN, 'OBL'),
+  );
+}
+
+function normalizeVerificationBasis(value: unknown): VerifiedManifest['verification_basis'] | null {
+  return value === 'structured_spec' ||
+    value === 'questions_resolved' ||
+    value === 'policy_approved_auto_promotion' ||
+    value === 'human_review_confirmed'
+    ? value
+    : null;
+}
+
+function normalizeReviewStatus(value: unknown): IntakeReview['status'] {
+  return value === 'proposed' || value === 'awaiting_input' || value === 'verified'
+    ? value
+    : 'proposed';
+}
+
+function readPositiveInteger(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 1
+    ? Math.floor(value)
+    : null;
+}
+
+function readNonNegativeInteger(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : null;
+}
+
+function normalizeAmbiguityStatus(
+  value: unknown,
+  fallback: IntakeReview['ambiguities'][number]['status'] = 'open',
+): IntakeReview['ambiguities'][number]['status'] {
+  if (value === 'open' || value === 'resolved') {
+    return value;
+  }
+  return fallback;
+}
+
+function normalizeReviewAmbiguity(
+  value: unknown,
+  fallback: IntakeReview['ambiguities'][number] | null = null,
+): IntakeReview['ambiguities'][number] | null {
+  const record = asRecord(value);
+  const id =
+    normalizeAmbiguityIds(record?.id)[0] ??
+    normalizeAmbiguityIds(record?.ambiguity_id)[0] ??
+    fallback?.id ??
+    null;
+  const summary = asString(record?.summary) ?? fallback?.summary ?? null;
+  if (!id || !summary) {
+    return null;
+  }
+
+  const fallbackResolution =
+    asString(record?.resolution) ?? asString(asRecord(record?.resolution)?.status);
+  const status = normalizeAmbiguityStatus(
+    record?.status ?? fallbackResolution,
+    fallback?.status ?? 'open',
+  );
+  const obligationIds = normalizeObligationIds(record?.obligation_ids);
+  const normalized: IntakeReview['ambiguities'][number] = {
+    id,
+    summary,
+    status,
+  };
+  const finalObligationIds =
+    obligationIds.length > 0 ? obligationIds : normalizeObligationIds(fallback?.obligation_ids);
+  if (finalObligationIds.length > 0) {
+    normalized.obligation_ids = finalObligationIds;
+  }
+  return normalized;
+}
+
+function normalizeReviewClarificationAnswer(
+  value: unknown,
+  ambiguityStatus: Map<string, IntakeReview['ambiguities'][number]['status']>,
+): IntakeClarificationAnswer | null {
+  const record = asRecord(value);
+  const questionId = asString(record?.question_id);
+  const prompt = asString(record?.prompt);
+  const answer = asAnswerValue(record?.answer);
+  const answeredAt = asString(record?.answered_at);
+  const answeredBy = asString(record?.answered_by);
+  const ambiguityIds = normalizeAmbiguityIds(record?.ambiguity_ids);
+  if (
+    !questionId ||
+    !prompt ||
+    answer === null ||
+    !answeredAt ||
+    !answeredBy ||
+    ambiguityIds.length === 0
+  ) {
+    return null;
+  }
+
+  const resolutionStatus =
+    record?.resolution_status === 'candidate' || record?.resolution_status === 'applied'
+      ? record.resolution_status
+      : ambiguityIds.every((ambiguityId) => ambiguityStatus.get(ambiguityId) === 'resolved')
+        ? 'applied'
+        : 'candidate';
+
+  return {
+    question_id: questionId,
+    ambiguity_ids: ambiguityIds,
+    obligation_ids: normalizeObligationIds(record?.obligation_ids),
+    prompt,
+    answer,
+    answered_at: answeredAt,
+    answered_by: answeredBy,
+    resolution_status: resolutionStatus,
+  };
+}
+
+function mergeReviewAmbiguities(
+  bootstrapAmbiguities: BootstrapManifest['ambiguities'],
+  reviewAmbiguities: unknown,
+): IntakeReview['ambiguities'] {
+  const normalizedReview = Array.isArray(reviewAmbiguities)
+    ? reviewAmbiguities
+        .map((item) => normalizeReviewAmbiguity(item))
+        .filter((item): item is IntakeReview['ambiguities'][number] => item !== null)
+    : [];
+  const reviewById = new Map(normalizedReview.map((item) => [item.id, item]));
+  const merged = bootstrapAmbiguities
+    .map((item) => normalizeReviewAmbiguity(item, item))
+    .filter((item): item is IntakeReview['ambiguities'][number] => item !== null)
+    .map((item) => {
+      const existing = reviewById.get(item.id);
+      return existing
+        ? {
+            ...item,
+            status: existing.status,
+            ...(existing.obligation_ids && existing.obligation_ids.length > 0
+              ? { obligation_ids: existing.obligation_ids }
+              : {}),
+          }
+        : item;
+    });
+  const bootstrapIds = new Set(merged.map((item) => item.id));
+  const extras = normalizedReview.filter((item) => !bootstrapIds.has(item.id));
+  return [...merged, ...extras];
+}
+
+function normalizeReviewClarificationAnswers(
+  value: unknown,
+  ambiguities: IntakeReview['ambiguities'],
+): IntakeClarificationAnswer[] {
+  const ambiguityStatus = new Map(ambiguities.map((item) => [item.id, item.status]));
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((item) => normalizeReviewClarificationAnswer(item, ambiguityStatus))
+    .filter((item): item is IntakeClarificationAnswer => item !== null)
+    .sort((left, right) => {
+      if (left.answered_at === right.answered_at) {
+        return left.question_id.localeCompare(right.question_id);
+      }
+      return left.answered_at.localeCompare(right.answered_at);
+    });
+}
+
+function normalizeSubmissionAmbiguities(
+  value: unknown,
+  status: IntakeReview['ambiguities'][number]['status'],
+  bootstrapManifest: BootstrapManifest,
+): IntakeReview['ambiguities'] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const bootstrapById = new Map(bootstrapManifest.ambiguities.map((item) => [item.id, item]));
+  const normalized = value
+    .map((item) => {
+      const raw = asRecord(item);
+      const candidateId =
+        normalizeAmbiguityIds(raw?.id)[0] ?? normalizeAmbiguityIds(raw?.ambiguity_id)[0] ?? null;
+      const fallback = candidateId ? (bootstrapById.get(candidateId) ?? null) : null;
+      const normalizedItem = normalizeReviewAmbiguity(item, fallback);
+      if (!normalizedItem) {
+        return null;
+      }
+      return {
+        ...normalizedItem,
+        status,
+      };
+    })
+    .filter((item): item is IntakeReview['ambiguities'][number] => item !== null);
+
+  return normalized
+    .filter(
+      (item, index, items) => items.findIndex((candidate) => candidate.id === item.id) === index,
+    )
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function normalizeManifestObligationKind(value: unknown): ManifestObligationKind | null {
+  const normalized = asString(value)?.toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  return OBLIGATION_KIND_ALIASES[normalized] ?? null;
+}
+
+function normalizeManifestVerificationHint(value: unknown): ManifestVerificationHint | null {
+  const normalized = asString(value)?.toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  return VERIFICATION_HINT_ALIASES[normalized] ?? null;
+}
+
+function normalizeManifestSourceRef(value: unknown): ManifestSourceRef | null {
+  const record = asRecord(value);
+  const lineStart = readPositiveInteger(record?.line_start);
+  const lineEnd = readPositiveInteger(record?.line_end);
+  if (lineStart === null || lineEnd === null) {
+    return null;
+  }
+  return {
+    line_start: lineStart,
+    line_end: Math.max(lineStart, lineEnd),
+    heading: asString(record?.heading),
+  };
+}
+
+function normalizeManifestSourceRefs(value: unknown): ManifestSourceRef[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((item) => normalizeManifestSourceRef(item))
+    .filter((item): item is ManifestSourceRef => item !== null);
+}
+
+function normalizeSubmittedManifestObligation(
+  value: unknown,
+  verificationBasis: VerifiedManifest['verification_basis'] | null,
+): ManifestObligation | null {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+
+  const obligationId = normalizeObligationIds(record.obligation_id)[0] ?? null;
+  const kind = normalizeManifestObligationKind(record.kind);
+  const name = asString(record.name) ?? asString(record.title);
+  const description = asString(record.description) ?? asString(record.summary) ?? name;
+  const sourceRefs = normalizeManifestSourceRefs(
+    record.source_refs ?? (record.source_ref ? [record.source_ref] : []),
+  );
+  const verificationHint = normalizeManifestVerificationHint(record.verification_hint);
+  const confidence = normalizeManifestConfidence(record.confidence);
+
+  if (
+    !obligationId ||
+    !kind ||
+    !name ||
+    !description ||
+    !verificationHint ||
+    !confidence ||
+    (sourceRefs.length === 0 && verificationBasis !== 'human_review_confirmed')
+  ) {
+    return null;
+  }
+
+  return {
+    obligation_id: obligationId,
+    kind,
+    name,
+    description,
+    source_refs: sourceRefs,
+    verification_hint: verificationHint,
+    confidence,
+  };
+}
+
+function asBootstrapManifest(value: unknown): BootstrapManifest | null {
+  const record = asRecord(value);
+  if (!record || record.artifact_type !== 'bootstrap') {
+    return null;
+  }
+  return record as unknown as BootstrapManifest;
+}
+
+function asVerifiedManifest(value: unknown): VerifiedManifest | null {
+  const record = asRecord(value);
+  if (!record || record.artifact_type !== 'verified') {
+    return null;
+  }
+  return record as unknown as VerifiedManifest;
+}
+
+function asIntakeReview(value: unknown): IntakeReview | null {
+  const record = asRecord(value);
+  if (!record || typeof record.feature_id !== 'string') {
+    return null;
+  }
+  const ambiguities = Array.isArray(record.ambiguities)
+    ? record.ambiguities
+        .map((item) => normalizeReviewAmbiguity(item))
+        .filter((item): item is IntakeReview['ambiguities'][number] => item !== null)
+    : [];
+  const clarificationAnswers = normalizeReviewClarificationAnswers(
+    record.clarification_answers,
+    ambiguities,
+  );
+  return {
+    feature_id: record.feature_id,
+    version: readPositiveInteger(record.version) ?? 1,
+    status: normalizeReviewStatus(record.status),
+    questions_open: readNonNegativeInteger(record.questions_open) ?? 0,
+    questions_resolved:
+      readNonNegativeInteger(record.questions_resolved) ?? clarificationAnswers.length,
+    ambiguities,
+    clarification_answers: clarificationAnswers,
+    bootstrap_manifest_version: readPositiveInteger(record.bootstrap_manifest_version),
+    verified_manifest_version: readPositiveInteger(record.verified_manifest_version),
+    promotion_basis: normalizeVerificationBasis(record.promotion_basis),
+    last_updated_at: asString(record.last_updated_at) ?? nowIso(),
+  };
+}
+
+function readIntakeRecord(frontMatter: StateRecord): Record<string, unknown> {
+  const intake = asRecord(frontMatter.intake);
+  return intake ?? {};
+}
+
+function readPlanningIntakePolicy(policy: Record<string, unknown>): Record<string, unknown> {
+  return asRecord(asRecord(policy.planning)?.intake) ?? {};
+}
+
+function buildDefaultReview(featureId: string, bootstrapManifest: BootstrapManifest): IntakeReview {
+  return {
+    feature_id: featureId,
+    version: 1,
+    status: 'proposed',
+    questions_open: 0,
+    questions_resolved: 0,
+    ambiguities: bootstrapManifest.ambiguities,
+    clarification_answers: [],
+    bootstrap_manifest_version: bootstrapManifest.manifest_version,
+    verified_manifest_version: null,
+    promotion_basis: null,
+    last_updated_at: nowIso(),
+  };
+}
+
+function summarizeIntake(
+  frontMatter: StateRecord,
+  bootstrapManifest: BootstrapManifest | null,
+  verifiedManifest: VerifiedManifest | null,
+  review: IntakeReview | null,
+): IntakeSummary {
+  const intake = readIntakeRecord(frontMatter);
+  const normalizedIntakeStatus =
+    intake.status === 'not_started' ||
+    intake.status === 'in_progress' ||
+    intake.status === 'awaiting_input'
+      ? intake.status
+      : intake.status === 'verified'
+        ? verifiedManifest
+          ? 'verified'
+          : frontMatter.status === STATUS.AWAITING_INPUT
+            ? 'awaiting_input'
+            : 'in_progress'
+        : null;
+  const openAmbiguityCount =
+    typeof intake.open_ambiguity_count === 'number'
+      ? Math.max(0, Math.floor(intake.open_ambiguity_count))
+      : (review?.ambiguities.filter((item) => item.status === 'open').length ??
+        bootstrapManifest?.ambiguities.filter((item) => item.status === 'open').length ??
+        0);
+  return {
+    status:
+      normalizedIntakeStatus ??
+      (verifiedManifest
+        ? 'verified'
+        : frontMatter.status === STATUS.AWAITING_INPUT
+          ? 'awaiting_input'
+          : 'in_progress'),
+    bootstrap_manifest_version:
+      typeof intake.bootstrap_manifest_version === 'number'
+        ? Math.floor(intake.bootstrap_manifest_version)
+        : (bootstrapManifest?.manifest_version ?? null),
+    verified_manifest_version: verifiedManifest
+      ? typeof intake.verified_manifest_version === 'number'
+        ? Math.floor(intake.verified_manifest_version)
+        : verifiedManifest.manifest_version
+      : null,
+    open_ambiguity_count: openAmbiguityCount,
+    last_verified_at: verifiedManifest
+      ? typeof intake.last_verified_at === 'string'
+        ? intake.last_verified_at
+        : verifiedManifest.verified_at
+      : null,
+    promotion_basis: verifiedManifest
+      ? intake.promotion_basis === 'structured_spec' ||
+        intake.promotion_basis === 'questions_resolved' ||
+        intake.promotion_basis === 'policy_approved_auto_promotion' ||
+        intake.promotion_basis === 'human_review_confirmed'
+        ? intake.promotion_basis
+        : (review?.promotion_basis ?? null)
+      : null,
+  };
+}
+
+function normalizeQuestionEvidence(value: unknown): QuestionEvidenceRecord | null {
+  const record = asRecord(value);
+  const status = asString(record?.status);
+  if (!record || !status) {
+    return null;
+  }
+  return {
+    question_id: asString(record.question_id),
+    status,
+    question_type: asString(record.question_type),
+    phase: asString(record.phase),
+    resume_status: asString(record.resume_status),
+    resume_phase: asString(record.resume_phase),
+    prompt: asString(record.prompt),
+    answer: asAnswerValue(record.answer),
+    answered_at: asString(record.answered_at),
+    answered_by: asString(record.answered_by),
+    details: asRecord(record.details) ?? {},
+  };
+}
+
+function isAnsweredIntakeQuestion(
+  question: QuestionEvidenceRecord,
+  bootstrapManifest: BootstrapManifest,
+): boolean {
+  if (question.status !== 'answered' || !question.answered_by || !question.answered_at) {
+    return false;
+  }
+  const answeredAt = Date.parse(question.answered_at);
+  const generatedAt = Date.parse(bootstrapManifest.generated_at);
+  if (Number.isFinite(answeredAt) && Number.isFinite(generatedAt) && answeredAt < generatedAt) {
+    return false;
+  }
+  return (
+    question.resume_status === STATUS.INTAKE ||
+    question.resume_phase === STATUS.INTAKE ||
+    question.phase === STATUS.INTAKE
+  );
+}
+
+function questionReferencesAmbiguity(
+  question: QuestionEvidenceRecord,
+  ambiguityId: string,
+): boolean {
+  const singular =
+    normalizeAmbiguityIds(question.details.ambiguity_id)[0] ??
+    asString(question.details.ambiguity_id);
+  if (singular === ambiguityId) {
+    return true;
+  }
+  return normalizeAmbiguityIds(question.details.ambiguity_ids).includes(ambiguityId);
+}
+
+function questionConfirmsVerifiedManifest(question: QuestionEvidenceRecord): boolean {
+  return (
+    asString(question.details.confirmation_kind) === 'manifest_review' ||
+    asString(question.details.review_target) === 'verified_manifest' ||
+    asString(question.details.ambiguity_id) === MANIFEST_REVIEW_AMBIGUITY_ID
+  );
+}
+
+function isIntakeQuestion(question: QuestionEvidenceRecord): boolean {
+  return (
+    question.resume_status === STATUS.INTAKE ||
+    question.resume_phase === STATUS.INTAKE ||
+    question.phase === STATUS.INTAKE
+  );
+}
+
+function isOpenIntakeQuestion(question: QuestionEvidenceRecord): boolean {
+  return question.status === 'open' && isIntakeQuestion(question);
+}
+
+function isAnsweredIntakeClarification(question: QuestionEvidenceRecord): boolean {
+  return (
+    question.status === 'answered' &&
+    question.question_id !== null &&
+    question.prompt !== null &&
+    question.answer !== null &&
+    question.answered_at !== null &&
+    question.answered_by !== null &&
+    isIntakeQuestion(question) &&
+    normalizeAmbiguityIds(question.details.ambiguity_ids).length > 0
+  );
+}
+
+function buildClarificationAnswers(
+  review: IntakeReview,
+  questions: QuestionEvidenceRecord[],
+): IntakeClarificationAnswer[] {
+  const ambiguityStatus = new Map(review.ambiguities.map((item) => [item.id, item.status]));
+  return questions
+    .filter((question) => isAnsweredIntakeClarification(question))
+    .map((question) => {
+      const ambiguityIds = normalizeAmbiguityIds(question.details.ambiguity_ids);
+      const obligationIds = normalizeObligationIds(question.details.obligation_ids);
+      const resolutionStatus = ambiguityIds.every(
+        (ambiguityId) => ambiguityStatus.get(ambiguityId) === 'resolved',
+      )
+        ? 'applied'
+        : 'candidate';
+      return {
+        question_id: question.question_id,
+        ambiguity_ids: ambiguityIds,
+        obligation_ids: obligationIds,
+        prompt: question.prompt,
+        answer: question.answer,
+        answered_at: question.answered_at,
+        answered_by: question.answered_by,
+        resolution_status: resolutionStatus,
+      } satisfies IntakeClarificationAnswer;
+    })
+    .sort((left, right) => {
+      if (left.answered_at === right.answered_at) {
+        return left.question_id.localeCompare(right.question_id);
+      }
+      return left.answered_at.localeCompare(right.answered_at);
+    });
+}
+
+export interface IntakeServicePort {
+  featurePath(featureId: string): string;
+  specPath(featureId: string): string;
+  withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
+  readState(featureId: string): Promise<{ frontMatter: StateRecord; body: string }>;
+  updateState(
+    featureId: string,
+    expectedVersion: number | null,
+    updater: StateUpdater,
+  ): Promise<StateRecord>;
+  validateSchema(schemaName: string, value: unknown): Promise<{ valid: boolean; errors?: unknown }>;
+  getPolicySnapshot(): Record<string, unknown>;
+}
+
+export class IntakeService {
+  private readonly port: IntakeServicePort;
+  private readonly generator: BootstrapManifestGeneratorService;
+
+  constructor(
+    port: IntakeServicePort,
+    generator: BootstrapManifestGeneratorService = new BootstrapManifestGeneratorService(),
+  ) {
+    this.port = port;
+    this.generator = generator;
+  }
+
+  bootstrapManifestPath(featureId: string): string {
+    return path.join(this.port.featurePath(featureId), 'spec.manifest.bootstrap.json');
+  }
+
+  verifiedManifestPath(featureId: string): string {
+    return path.join(this.port.featurePath(featureId), 'spec.manifest.verified.json');
+  }
+
+  intakeReviewPath(featureId: string): string {
+    return path.join(this.port.featurePath(featureId), 'intake.review.json');
+  }
+
+  questionsPath(featureId: string): string {
+    return path.join(this.port.featurePath(featureId), 'questions.json');
+  }
+
+  planPath(featureId: string): string {
+    return path.join(this.port.featurePath(featureId), 'plan.json');
+  }
+
+  planMarkdownPath(featureId: string): string {
+    return path.join(this.port.featurePath(featureId), 'plan.md');
+  }
+
+  async readBootstrapManifest(featureId: string): Promise<BootstrapManifest | null> {
+    return asBootstrapManifest(await readJson(this.bootstrapManifestPath(featureId), null));
+  }
+
+  async readVerifiedManifest(featureId: string): Promise<VerifiedManifest | null> {
+    const rawManifest = await readJson(this.verifiedManifestPath(featureId), null);
+    if (!rawManifest) {
+      return null;
+    }
+    const validation = await this.port.validateSchema(
+      'spec.manifest.verified.schema.json',
+      rawManifest,
+    );
+    if (!validation.valid) {
+      return null;
+    }
+    return asVerifiedManifest(rawManifest);
+  }
+
+  async readIntakeReview(featureId: string): Promise<IntakeReview | null> {
+    return asIntakeReview(await readJson(this.intakeReviewPath(featureId), null));
+  }
+
+  private normalizeSubmittedVerifiedManifest(
+    featureId: string,
+    verifiedManifest: unknown,
+  ): Record<string, unknown> {
+    const record = asRecord(verifiedManifest);
+    if (!record) {
+      return {};
+    }
+
+    const verificationBasis = normalizeVerificationBasis(record.verification_basis);
+    const rawObligations = Array.isArray(record.obligations) ? record.obligations : [];
+    const normalizedObligations = rawObligations
+      .map((item) => normalizeSubmittedManifestObligation(item, verificationBasis))
+      .filter((item): item is ManifestObligation => item !== null);
+
+    const invalidObligations = rawObligations
+      .map((item, index) => {
+        const obligation = normalizeSubmittedManifestObligation(item, verificationBasis);
+        if (obligation) {
+          return null;
+        }
+        const raw = asRecord(item);
+        return {
+          index,
+          obligation_id: asString(raw?.obligation_id),
+          kind: asString(raw?.kind),
+          name: asString(raw?.name) ?? asString(raw?.title),
+        };
+      })
+      .filter(
+        (
+          item,
+        ): item is {
+          index: number;
+          obligation_id: string | null;
+          kind: string | null;
+          name: string | null;
+        } => item !== null,
+      );
+
+    if (invalidObligations.length > 0) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'verified manifest contains malformed obligations that could not be normalized',
+          {
+            feature_id: featureId,
+            invalid_obligations: invalidObligations,
+            retryable: false,
+            requires_human: true,
+            suggested_next_actions: [
+              'Use canonical obligation ids such as OBL-001 or draft ids such as OBL-V01',
+              'Use only supported obligation kinds or constraint aliases that normalize to contract',
+              'Include source_refs for non-human-review verification bases',
+            ],
+          },
+        ),
+      };
+    }
+
+    const seenObligationIds = new Set<string>();
+    const duplicateObligationIds = normalizedObligations
+      .map((obligation) => obligation.obligation_id)
+      .filter((obligationId) => {
+        if (seenObligationIds.has(obligationId)) {
+          return true;
+        }
+        seenObligationIds.add(obligationId);
+        return false;
+      });
+    if (duplicateObligationIds.length > 0) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'verified manifest contains duplicate obligation ids after normalization',
+          {
+            feature_id: featureId,
+            duplicate_obligation_ids: normalizeUniqueStrings(duplicateObligationIds),
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    return {
+      feature_id: asString(record.feature_id) ?? featureId,
+      manifest_version: readPositiveInteger(record.manifest_version) ?? record.manifest_version,
+      artifact_type:
+        record.artifact_type === 'verified' ? 'verified' : (record.artifact_type ?? null),
+      verification_basis: verificationBasis ?? record.verification_basis,
+      verified_at: asString(record.verified_at) ?? record.verified_at,
+      source_bootstrap_version:
+        record.source_bootstrap_version === null
+          ? null
+          : (readPositiveInteger(record.source_bootstrap_version) ??
+            record.source_bootstrap_version),
+      obligations: normalizedObligations,
+    };
+  }
+
+  private async validateArtifact(
+    schemaName: string,
+    value: unknown,
+    message: string,
+  ): Promise<void> {
+    const validation = await this.port.validateSchema(schemaName, value);
+    if (!validation.valid) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.STATE_VALIDATION_FAILED, message, {
+          errors: validation.errors,
+          retryable: false,
+          requires_human: true,
+        }),
+      };
+    }
+  }
+
+  private async validateSubmittedVerifiedManifest(
+    featureId: string,
+    verifiedManifest: unknown,
+  ): Promise<void> {
+    const validation = await this.port.validateSchema(
+      'spec.manifest.verified.schema.json',
+      verifiedManifest,
+    );
+    if (!validation.valid) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'verified manifest failed schema validation',
+          {
+            feature_id: featureId,
+            errors: validation.errors,
+            retryable: false,
+            requires_human: true,
+            suggested_next_actions: [
+              'Normalize obligation ids to OBL-### before emitting INTAKE_SUBMISSION',
+              'Use supported obligation kinds only',
+              'For human-review additions, keep source_refs empty rather than adding unsupported fields',
+            ],
+          },
+        ),
+      };
+    }
+  }
+
+  private async syncIntakeState(
+    featureId: string,
+    patch: (frontMatter: StateRecord) => StateRecord,
+  ): Promise<void> {
+    await this.port.updateState(featureId, null, (frontMatter, body) =>
+      Promise.resolve({
+        frontMatter: patch(frontMatter),
+        body,
+      }),
+    );
+  }
+
+  private isAutoPromotionEnabled(): boolean {
+    const intake = readPlanningIntakePolicy(this.port.getPolicySnapshot());
+    return intake.allow_auto_promotion === true;
+  }
+
+  private readAutoPromotionMinConfidence(): ManifestConfidence {
+    const intake = readPlanningIntakePolicy(this.port.getPolicySnapshot());
+    return normalizeManifestConfidence(intake.auto_promotion_min_confidence) ?? 'high';
+  }
+
+  private canAutoPromoteBootstrapManifest(bootstrapManifest: BootstrapManifest): boolean {
+    return (
+      this.isAutoPromotionEnabled() &&
+      bootstrapManifest.ambiguities.length === 0 &&
+      obligationsMeetConfidenceThreshold(
+        bootstrapManifest.obligations,
+        this.readAutoPromotionMinConfidence(),
+      )
+    );
+  }
+
+  private async readQuestionEvidence(featureId: string): Promise<QuestionEvidenceRecord[]> {
+    const artifact = await readJson(this.questionsPath(featureId), null);
+    const items = Array.isArray(artifact?.items) ? artifact.items : [];
+    return items
+      .map((item) => normalizeQuestionEvidence(item))
+      .filter((item): item is QuestionEvidenceRecord => item !== null);
+  }
+
+  private async buildSyncedReview(
+    featureId: string,
+    bootstrapManifest: BootstrapManifest,
+    verifiedManifest: VerifiedManifest | null,
+  ): Promise<IntakeReview> {
+    const existingReview =
+      (await this.readIntakeReview(featureId)) ?? buildDefaultReview(featureId, bootstrapManifest);
+    const ambiguities = mergeReviewAmbiguities(
+      bootstrapManifest.ambiguities,
+      existingReview.ambiguities,
+    );
+    const unverifiedReviewStatus =
+      existingReview.status === 'verified' && !verifiedManifest
+        ? 'proposed'
+        : existingReview.status;
+    const questions = await this.readQuestionEvidence(featureId);
+    if (questions.length === 0) {
+      return {
+        ...existingReview,
+        ambiguities,
+        clarification_answers: normalizeReviewClarificationAnswers(
+          existingReview.clarification_answers,
+          ambiguities,
+        ),
+        status: verifiedManifest ? 'verified' : unverifiedReviewStatus,
+        bootstrap_manifest_version: bootstrapManifest.manifest_version,
+        verified_manifest_version: verifiedManifest?.manifest_version ?? null,
+        promotion_basis:
+          verifiedManifest?.verification_basis ??
+          normalizeVerificationBasis(existingReview.promotion_basis) ??
+          null,
+      };
+    }
+    const openIntakeQuestions = questions.filter((question) => isOpenIntakeQuestion(question));
+    const clarificationAnswers = buildClarificationAnswers(
+      {
+        ...existingReview,
+        ambiguities,
+      },
+      questions,
+    );
+    return {
+      ...existingReview,
+      ambiguities,
+      status: verifiedManifest
+        ? 'verified'
+        : openIntakeQuestions.length > 0
+          ? 'awaiting_input'
+          : 'proposed',
+      questions_open: openIntakeQuestions.length,
+      questions_resolved: clarificationAnswers.length,
+      clarification_answers: clarificationAnswers,
+      bootstrap_manifest_version: bootstrapManifest.manifest_version,
+      verified_manifest_version: verifiedManifest?.manifest_version ?? null,
+      promotion_basis:
+        verifiedManifest?.verification_basis ??
+        normalizeVerificationBasis(existingReview.promotion_basis) ??
+        null,
+      last_updated_at: nowIso(),
+    };
+  }
+
+  async syncReviewFromQuestions(featureId: string): Promise<void> {
+    const bootstrapManifest = await this.readBootstrapManifest(featureId);
+    if (!bootstrapManifest) {
+      return;
+    }
+    const verifiedManifest = await this.readVerifiedManifest(featureId);
+    const nextReview = await this.buildSyncedReview(featureId, bootstrapManifest, verifiedManifest);
+    await this.validateArtifact(
+      'intake.review.schema.json',
+      nextReview,
+      'intake review failed schema validation',
+    );
+    await atomicWriteJson(this.intakeReviewPath(featureId), nextReview);
+  }
+
+  private async validateVerificationBasisEvidence(
+    featureId: string,
+    submission: IntakeSubmission,
+    bootstrapManifest: BootstrapManifest,
+  ): Promise<void> {
+    const verificationBasis = submission.verified_manifest.verification_basis;
+    if (verificationBasis === 'policy_approved_auto_promotion') {
+      return;
+    }
+
+    if (
+      verificationBasis === 'structured_spec' &&
+      (bootstrapManifest.ambiguities.length > 0 || submission.resolved_ambiguities.length > 0)
+    ) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'structured_spec verification cannot resolve inferred intake ambiguities',
+          {
+            feature_id: featureId,
+            bootstrap_ambiguity_ids: bootstrapManifest.ambiguities.map((item) => item.id),
+            resolved_ambiguity_ids: submission.resolved_ambiguities.map((item) => item.id),
+            retryable: false,
+            requires_human: true,
+            suggested_next_actions: [
+              'Emit REQUEST.action=ask_user_input for the blocking ambiguity',
+              'Use verification_basis=questions_resolved after the operator answers',
+            ],
+          },
+        ),
+      };
+    }
+
+    if (
+      verificationBasis !== 'questions_resolved' &&
+      verificationBasis !== 'human_review_confirmed'
+    ) {
+      return;
+    }
+
+    const questions = await this.readQuestionEvidence(featureId);
+    const openIntakeQuestions = questions.filter(
+      (question) =>
+        question.status === 'open' &&
+        (question.resume_status === STATUS.INTAKE ||
+          question.resume_phase === STATUS.INTAKE ||
+          question.phase === STATUS.INTAKE),
+    );
+    if (openIntakeQuestions.length > 0) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'verified manifest cannot be promoted while intake questions remain open',
+          {
+            feature_id: featureId,
+            open_question_count: openIntakeQuestions.length,
+            retryable: false,
+            requires_human: true,
+            suggested_next_actions: [
+              'Wait for the operator to answer the open intake question',
+              'Resubmit INTAKE_SUBMISSION after the answered question is persisted',
+            ],
+          },
+        ),
+      };
+    }
+
+    const answeredIntakeQuestions = questions.filter((question) =>
+      isAnsweredIntakeQuestion(question, bootstrapManifest),
+    );
+    if (answeredIntakeQuestions.length === 0) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'verified manifest requires persisted answered intake-question evidence',
+          {
+            feature_id: featureId,
+            verification_basis: verificationBasis,
+            retryable: false,
+            requires_human: true,
+            suggested_next_actions: [
+              'Emit REQUEST.action=ask_user_input instead of resolving the ambiguity yourself',
+              'Resubmit INTAKE_SUBMISSION only after the operator answer is stored in questions.json',
+            ],
+          },
+        ),
+      };
+    }
+
+    if (verificationBasis === 'questions_resolved') {
+      if (submission.resolved_ambiguities.length === 0) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+            'questions_resolved verification requires at least one resolved ambiguity',
+            {
+              feature_id: featureId,
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+      const missingEvidence = submission.resolved_ambiguities
+        .map((ambiguity) => ambiguity.id)
+        .filter(
+          (ambiguityId) =>
+            !answeredIntakeQuestions.some((question) =>
+              questionReferencesAmbiguity(question, ambiguityId),
+            ),
+        );
+      if (missingEvidence.length > 0) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+            'resolved intake ambiguities must map to answered intake questions',
+            {
+              feature_id: featureId,
+              verification_basis: verificationBasis,
+              missing_ambiguity_evidence_ids: missingEvidence,
+              retryable: false,
+              requires_human: true,
+              suggested_next_actions: [
+                'Include ambiguity_id or ambiguity_ids on the blocking intake question',
+                'Only mark ambiguities resolved after their answered question is persisted',
+              ],
+            },
+          ),
+        };
+      }
+      return;
+    }
+
+    if (!answeredIntakeQuestions.some((question) => questionConfirmsVerifiedManifest(question))) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'human_review_confirmed requires an explicit answered manifest-review confirmation question',
+          {
+            feature_id: featureId,
+            verification_basis: verificationBasis,
+            retryable: false,
+            requires_human: true,
+            suggested_next_actions: [
+              'Use verification_basis=questions_resolved for answered ambiguity questions',
+              'Reserve human_review_confirmed for explicit manifest confirmation responses',
+            ],
+          },
+        ),
+      };
+    }
+  }
+
+  async ensureBootstrapManifest(featureId: string): Promise<BootstrapManifest> {
+    const existing = await this.readBootstrapManifest(featureId);
+    if (existing) {
+      return existing;
+    }
+
+    const specText = await fs.readFile(this.port.specPath(featureId), 'utf8').catch(() => '');
+    const manifest = this.generator.generate(featureId, specText);
+    await this.validateArtifact(
+      'spec.manifest.bootstrap.schema.json',
+      manifest,
+      'bootstrap manifest failed schema validation',
+    );
+
+    const persistedManifest = await this.port.withFeatureLock(featureId, async () => {
+      const current = await this.readBootstrapManifest(featureId);
+      if (current) {
+        return current;
+      }
+
+      await atomicWriteJson(this.bootstrapManifestPath(featureId), manifest);
+
+      const existingReview = await this.readIntakeReview(featureId);
+      if (!existingReview) {
+        const review = buildDefaultReview(featureId, manifest);
+        await this.validateArtifact(
+          'intake.review.schema.json',
+          review,
+          'intake review failed schema validation',
+        );
+        await atomicWriteJson(this.intakeReviewPath(featureId), review);
+      }
+
+      return manifest;
+    });
+
+    await this.syncReviewFromQuestions(featureId);
+
+    await this.syncIntakeState(featureId, (frontMatter) => ({
+      ...frontMatter,
+      intake: {
+        ...readIntakeRecord(frontMatter),
+        status: frontMatter.status === STATUS.AWAITING_INPUT ? 'awaiting_input' : 'in_progress',
+        bootstrap_manifest_version: persistedManifest.manifest_version,
+        verified_manifest_version:
+          typeof readIntakeRecord(frontMatter).verified_manifest_version === 'number'
+            ? readIntakeRecord(frontMatter).verified_manifest_version
+            : null,
+        open_ambiguity_count: persistedManifest.ambiguities.filter((item) => item.status === 'open')
+          .length,
+        last_verified_at:
+          typeof readIntakeRecord(frontMatter).last_verified_at === 'string'
+            ? readIntakeRecord(frontMatter).last_verified_at
+            : null,
+        promotion_basis:
+          typeof readIntakeRecord(frontMatter).promotion_basis === 'string'
+            ? readIntakeRecord(frontMatter).promotion_basis
+            : null,
+      },
+    }));
+
+    return persistedManifest;
+  }
+
+  async ensureIntakeArtifacts(featureId: string): Promise<{
+    bootstrapManifest: BootstrapManifest;
+    verifiedManifest: VerifiedManifest | null;
+    review: IntakeReview;
+    summary: IntakeSummary;
+  }> {
+    const bootstrapManifest = await this.ensureBootstrapManifest(featureId);
+    await this.syncReviewFromQuestions(featureId);
+    const [initialVerifiedManifest, initialReview, initialState] = await Promise.all([
+      this.readVerifiedManifest(featureId),
+      this.readIntakeReview(featureId),
+      this.port.readState(featureId),
+    ]);
+    let verifiedManifest = initialVerifiedManifest;
+    let review = initialReview ?? buildDefaultReview(featureId, bootstrapManifest);
+    let state = initialState;
+
+    if (!verifiedManifest && this.canAutoPromoteBootstrapManifest(bootstrapManifest)) {
+      await this.intakeSubmit(featureId, {
+        verified_manifest: {
+          feature_id: featureId,
+          manifest_version: bootstrapManifest.manifest_version,
+          artifact_type: 'verified',
+          verification_basis: 'policy_approved_auto_promotion',
+          verified_at: nowIso(),
+          source_bootstrap_version: bootstrapManifest.manifest_version,
+          obligations: bootstrapManifest.obligations,
+        },
+        open_ambiguities: [],
+        resolved_ambiguities: [],
+        requires_user_input: false,
+      });
+      [verifiedManifest, review, state] = await Promise.all([
+        this.readVerifiedManifest(featureId),
+        this.readIntakeReview(featureId),
+        this.port.readState(featureId),
+      ]);
+    }
+
+    return {
+      bootstrapManifest,
+      verifiedManifest,
+      review: review ?? buildDefaultReview(featureId, bootstrapManifest),
+      summary: summarizeIntake(state.frontMatter, bootstrapManifest, verifiedManifest, review),
+    };
+  }
+
+  async intakeSubmit(
+    featureId: string,
+    submission: IntakeSubmission,
+  ): Promise<{
+    data: {
+      feature_id: string;
+      accepted: boolean;
+      feature_status: string;
+      verified_manifest_version: number;
+    };
+  }> {
+    if (!submission || !submission.verified_manifest) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INVALID_ARGUMENT,
+          'verified_manifest is required for intake submission',
+          {
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    const normalizedVerifiedManifest = this.normalizeSubmittedVerifiedManifest(
+      featureId,
+      submission.verified_manifest,
+    );
+    const verifiedManifest = normalizedVerifiedManifest as unknown as VerifiedManifest;
+    if (verifiedManifest.feature_id !== featureId) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INVALID_ARGUMENT,
+          'verified_manifest.feature_id must match feature_id',
+          {
+            feature_id: featureId,
+            manifest_feature_id: verifiedManifest.feature_id,
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    await this.validateSubmittedVerifiedManifest(featureId, normalizedVerifiedManifest);
+    const bootstrapManifest = await this.ensureBootstrapManifest(featureId);
+    const normalizedSubmission: IntakeSubmission = {
+      verified_manifest: verifiedManifest,
+      open_ambiguities: normalizeSubmissionAmbiguities(
+        submission.open_ambiguities,
+        'open',
+        bootstrapManifest,
+      ),
+      resolved_ambiguities: normalizeSubmissionAmbiguities(
+        submission.resolved_ambiguities,
+        'resolved',
+        bootstrapManifest,
+      ),
+      requires_user_input: submission.requires_user_input === true,
+    };
+    if (
+      normalizedSubmission.requires_user_input === true ||
+      normalizedSubmission.open_ambiguities.some((item) => item.status === 'open')
+    ) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'verified manifest cannot be promoted while intake ambiguities remain unresolved',
+          {
+            feature_id: featureId,
+            requires_user_input: normalizedSubmission.requires_user_input,
+            open_ambiguity_ids: normalizedSubmission.open_ambiguities
+              .filter((item) => item.status === 'open')
+              .map((item) => item.id),
+            retryable: false,
+            requires_human: true,
+            suggested_next_actions: [
+              'Emit REQUEST.action=ask_user_input for the unresolved ambiguity',
+              'Resubmit INTAKE_SUBMISSION only after the ambiguity is resolved',
+            ],
+          },
+        ),
+      };
+    }
+    if (
+      verifiedManifest.verification_basis === 'policy_approved_auto_promotion' &&
+      !this.canAutoPromoteBootstrapManifest(bootstrapManifest)
+    ) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'policy-approved auto-promotion is not allowed for this bootstrap manifest',
+          {
+            feature_id: featureId,
+            allow_auto_promotion: this.isAutoPromotionEnabled(),
+            minimum_confidence: this.readAutoPromotionMinConfidence(),
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+    if (
+      verifiedManifest.source_bootstrap_version !== null &&
+      verifiedManifest.source_bootstrap_version !== bootstrapManifest.manifest_version
+    ) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+          'verified manifest must reference the current bootstrap manifest version',
+          {
+            feature_id: featureId,
+            expected_source_bootstrap_version: bootstrapManifest.manifest_version,
+            received_source_bootstrap_version: verifiedManifest.source_bootstrap_version,
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+    await this.validateVerificationBasisEvidence(
+      featureId,
+      normalizedSubmission,
+      bootstrapManifest,
+    );
+
+    const result = await this.port.withFeatureLock(featureId, async () => {
+      const questionEvidence = await this.readQuestionEvidence(featureId);
+      const ambiguities = [
+        ...normalizedSubmission.open_ambiguities,
+        ...normalizedSubmission.resolved_ambiguities,
+      ];
+      const clarificationAnswers = buildClarificationAnswers(
+        {
+          feature_id: featureId,
+          version: ((await this.readIntakeReview(featureId))?.version ?? 0) + 1,
+          status: 'verified',
+          questions_open: 0,
+          questions_resolved: 0,
+          ambiguities,
+          clarification_answers: [],
+          bootstrap_manifest_version: bootstrapManifest.manifest_version,
+          verified_manifest_version: verifiedManifest.manifest_version,
+          promotion_basis: verifiedManifest.verification_basis,
+          last_updated_at: nowIso(),
+        },
+        questionEvidence,
+      );
+      const review: IntakeReview = {
+        feature_id: featureId,
+        version: ((await this.readIntakeReview(featureId))?.version ?? 0) + 1,
+        status: 'verified',
+        questions_open: 0,
+        questions_resolved: clarificationAnswers.length,
+        ambiguities,
+        clarification_answers: clarificationAnswers,
+        bootstrap_manifest_version: bootstrapManifest.manifest_version,
+        verified_manifest_version: verifiedManifest.manifest_version,
+        promotion_basis: verifiedManifest.verification_basis,
+        last_updated_at: nowIso(),
+      };
+      await this.validateArtifact(
+        'intake.review.schema.json',
+        review,
+        'intake review failed schema validation',
+      );
+
+      await atomicWriteJson(this.verifiedManifestPath(featureId), verifiedManifest);
+      await atomicWriteJson(this.intakeReviewPath(featureId), review);
+      await Promise.all([
+        fs.rm(this.planPath(featureId), { force: true }),
+        fs.rm(this.planMarkdownPath(featureId), { force: true }),
+      ]);
+
+      return {
+        verified_manifest_version: verifiedManifest.manifest_version,
+      };
+    });
+
+    await this.syncIntakeState(featureId, (frontMatter) => ({
+      ...frontMatter,
+      status: STATUS.PLANNING,
+      gates: {
+        ...(asRecord(frontMatter.gates) ?? {}),
+        plan: GATE_RESULT.NA,
+      },
+      intake: {
+        ...readIntakeRecord(frontMatter),
+        status: 'verified',
+        bootstrap_manifest_version: bootstrapManifest.manifest_version,
+        verified_manifest_version: verifiedManifest.manifest_version,
+        open_ambiguity_count: 0,
+        last_verified_at: verifiedManifest.verified_at,
+        promotion_basis: verifiedManifest.verification_basis,
+      },
+    }));
+
+    return {
+      data: {
+        feature_id: featureId,
+        accepted: true,
+        feature_status: STATUS.PLANNING,
+        verified_manifest_version: result.verified_manifest_version,
+      },
+    };
+  }
+}