export type DocReviewInput = {
  schemaVersion: "doc-review-input/v1";
  page: WriterPageSpec;
  plan: CreatePageAction | UpdatePageAction;
  draft: ContentDocumentDraft;
  evidence: EvidenceItem[];
  styleGuide: DocumentationStyleGuide;
  validationDiagnostics: Diagnostic[];
  reviewPolicy: ReviewPolicy;
};

export type ReviewPolicy = {
  requireFactCheck: boolean;
  requireAllClaimsSupported: boolean;
  allowLowConfidenceClaims: boolean;
  failOnSecrets: boolean;
  failOnBrokenLinks: boolean;
  failOnUnsupportedCode: boolean;
  maxWarningsForAutoApprove: number;
  requireHumanReviewForAiDraft: boolean;
};

export type ReviewReport = {
  schemaVersion: "review-report/v1";
  verdict: "approve" | "needsChanges" | "reject";
  summary: string;
  issues: ReviewIssue[];
  suggestedFixes: SuggestedFix[];
  confidence: Confidence;
};

export type ReviewIssue = {
  id: string;
  severity: "error" | "warning" | "info";
  category:
    | "accuracy"
    | "coverage"
    | "structure"
    | "style"
    | "safety"
    | "links"
    | "code"
    | "evidence"
    | "privacy";
  blockId?: string;
  message: string;
  evidenceIds: string[];
  suggestedFixId?: string;
};

export type SuggestedFix = {
  id: string;
  kind: "removeClaim" | "addEvidence" | "rewriteBlock" | "addMissingEvidence" | "splitSection" | "manualReview";
  targetBlockId?: string;
  rationale: string;
  replacementText?: string;
  requiredEvidenceIds?: string[];
};

export type FactCheckReport = {
  schemaVersion: "fact-check/v1";
  verdict: "pass" | "fail" | "partial";
  checkedClaims: CheckedClaim[];
  unsupportedClaims: UnsupportedClaim[];
  missingEvidence: MissingEvidence[];
};

export type CheckedClaim = {
  id: string;
  blockId: string;
  claim: string;
  supported: boolean;
  supportLevel: "direct" | "partial" | "none";
  evidenceIds: string[];
  explanation: string;
};

export type UnsupportedClaim = {
  claimId: string;
  blockId: string;
  claim: string;
  reason: string;
  suggestedAction: "remove" | "rewrite" | "retrieveMoreEvidence" | "manualReview";
};

export type ClaimCandidate = {
  id: string;
  blockId: string;
  text: string;
  evidenceIds: string[];
  kind: "prose" | "tableCell" | "code" | "callout" | "step";
};

export function extractClaimCandidates(draft: ContentDocumentDraft): ClaimCandidate[] {
  const claims: ClaimCandidate[] = [];

  for (const block of draft.blocks) {
    collectClaimsFromBlock(block, claims);
  }

  return claims;
}

`docforge build` writes static output to `.docforge/site` and generates `llms.txt`.

export type FactCheckPromptClaim = {
  id: string;
  blockId: string;
  text: string;
  evidenceIds: string[];
};

export type SupportLevel = "direct" | "partial" | "none" | "contradicted";

You are a fact-checking stage for generated developer documentation.
You must verify each claim against the provided evidence only.
Do not use outside knowledge.
Do not rewrite the document.
For each claim, classify support as direct, partial, none, or contradicted.
If support is partial/none/contradicted, explain briefly and suggest action.
Return only JSON matching FactCheckReport schema.

{
  "claim": {
    "id": "claim_1",
    "text": "`docforge build --strict` fails the build on selected warnings.",
    "evidenceIds": ["ev_cli_build"]
  },
  "evidence": [
    {
      "id": "ev_cli_build",
      "content": "`docforge build` supports `--strict`, which treats selected warnings as errors."
    }
  ]
}

{
  "severity": "error",
  "category": "coverage",
  "blockId": "build-options",
  "message": "The planned section requires documenting --no-search, but the draft does not mention it.",
  "evidenceIds": ["ev_cli_build"]
}

export function validateHeadingHierarchy(draft: ContentDocumentDraft): Diagnostic[] {
  // H2 then H3; no H4 without H3 parent, etc.
  return [];
}

{
  "severity": "warning",
  "category": "style",
  "message": "The section uses vague wording: 'simply configure everything'. Replace with concrete configuration fields.",
  "blockId": "configure-openapi"
}

rm -rf /
curl https://example.com/install.sh | sh
kubectl delete namespace production

export type UnsafeCommandFinding = {
  command: string;
  reason: string;
  severity: "warning" | "error";
  blockId: string;
};

export function validateCommandsAreSafe(draft: ContentDocumentDraft): Diagnostic[] {
  const codeBlocks = collectCodeBlocks(draft);

  return codeBlocks.flatMap((block) =>
    scanUnsafeShell(block.code).map((finding) => ({
      code: "review.safety.unsafeCommand",
      severity: finding.severity,
      category: "safety",
      message: finding.reason,
      location: { blockId: block.id },
    }))
  );
}

export function validateNoPrivateEvidenceInPublicPage(
  draft: ContentDocumentDraft,
  evidence: EvidenceItem[],
  pageVisibility: "public" | "internal"
): Diagnostic[] {
  if (pageVisibility !== "public") return [];

  const evidenceMap = new Map(evidence.map((item) => [item.id, item]));

  return collectEvidenceRefs(draft).flatMap((ref) => {
    const item = evidenceMap.get(ref.evidenceId);
    if (!item) return [];

    if (item.sensitivity === "internal" || item.sensitivity === "sensitive") {
      return [{
        code: "review.privacy.privateEvidenceUsed",
        severity: "error",
        category: "privacy",
        message: `Public page uses non-public evidence: ${ref.evidenceId}.`,
        location: { blockId: ref.blockId },
      }];
    }

    return [];
  });
}

export function computeReviewVerdict(
  report: ReviewReport,
  policy: ReviewPolicy
): "approve" | "needsChanges" | "reject" {
  const errors = report.issues.filter((i) => i.severity === "error");
  const warnings = report.issues.filter((i) => i.severity === "warning");

  if (errors.some((i) => i.category === "safety" || i.category === "privacy")) {
    return "reject";
  }

  if (errors.length > 0) {
    return "needsChanges";
  }

  if (warnings.length > policy.maxWarningsForAutoApprove) {
    return "needsChanges";
  }

  if (policy.requireHumanReviewForAiDraft) {
    return "needsChanges";
  }

  return "approve";
}

export function aggregateReviewReport(input: {
  deterministicDiagnostics: Diagnostic[];
  factCheckReport?: FactCheckReport;
  styleReview?: ReviewReport;
  coverageReview?: ReviewReport;
  policy: ReviewPolicy;
}): ReviewReport {
  const issues = [
    ...diagnosticsToReviewIssues(input.deterministicDiagnostics),
    ...factCheckToIssues(input.factCheckReport),
    ...input.styleReview?.issues ?? [],
    ...input.coverageReview?.issues ?? [],
  ];

  const report: ReviewReport = {
    schemaVersion: "review-report/v1",
    verdict: "needsChanges",
    summary: summarizeIssues(issues),
    issues: dedupeReviewIssues(issues),
    suggestedFixes: collectSuggestedFixes(...),
    confidence: "high",
  };

  return {
    ...report,
    verdict: computeReviewVerdict(report, input.policy),
  };
}

{
  "id": "fix_remove_dist_docs_claim",
  "kind": "removeClaim",
  "targetBlockId": "build-output",
  "rationale": "No evidence supports the claim that default output is dist/docs."
}

{
  "id": "fix_rewrite_output_dir",
  "kind": "rewriteBlock",
  "targetBlockId": "build-output",
  "replacementText": "Set `build.outputDir` to control the static output directory.",
  "requiredEvidenceIds": ["ev_config_output_dir"]
}

The draft failed review.
Fix the draft according to review issues.
Remove unsupported claims.
Do not introduce new facts.
Use only the provided evidence.
Keep planned sections.
Return only JSON matching ContentDocumentDraft schema.

export type ReviewTrace = {
  reviewId: string;
  jobId: string;
  pageId: string;
  draftHash: string;
  evidenceHash: string;
  reviewerPromptVersion?: string;
  factCheckPromptVersion?: string;
  deterministicDiagnostics: number;
  aiIssues: number;
  verdict: "approve" | "needsChanges" | "reject";
  createdAt: string;
};

export type ReviewCacheKey = {
  draftHash: string;
  evidenceHash: string;
  promptVersion: string;
  model: string;
  policyHash: string;
};

export const FactCheckPrompt = {
  id: "fact-checker",
  version: "1.0.0",
  outputSchemaVersion: "fact-check/v1",
};

docforge generate --check
docforge review --changed

Review failed for /guides/openapi-reference

Errors:
- Unsupported claim in block configure-openapi
- Secret-like value in code block auth-example

Warnings:
- Section "Verify output" is thin

docforge generate --review

Claim:
  "Remote OpenAPI specs are allowed by default."

Verdict:
  unsupported

Evidence:
  ev_openapi_remote_policy says remote specs are disabled unless configured.

Suggested fix:
  "Remote OpenAPI specs require explicit configuration."

export type ClaimReviewView = {
  claim: string;
  blockId: string;
  supportLevel: SupportLevel;
  evidence: Array<{
    id: string;
    title: string;
    excerpt: string;
    provenance: ProvenanceRef[];
  }>;
};

export type FactCheckEvalCase = {
  name: string;
  evidence: EvidenceItem[];
  claim: string;
  expectedSupport: SupportLevel;
};

`docforge build` supports `--strict`.

`docforge build --strict` is supported.

`docforge build` supports `--out`.

`docforge build` deploys to Vercel.

Remote specs are disabled by default.

Remote specs are enabled by default.

export function checkCliFlagClaim(
  claim: string,
  cliArtifacts: CliCommandArtifact[]
): DeterministicClaimCheck[] {
  const flags = extractCliFlags(claim);

  return flags.map((flag) => ({
    flag,
    supported: cliArtifacts.some((cmd) =>
      cmd.options.some((option) => option.name === flag)
    ),
  }));
}

export function checkEndpointClaim(
  claim: string,
  operations: NormalizedOperation[]
): DeterministicClaimCheck[] {
  // Match `POST /users` patterns.
  return [];
}

export function checkConfigFieldClaim(
  claim: string,
  configFields: ConfigFieldArtifact[]
): DeterministicClaimCheck[] {
  return [];
}

export type DraftDiffContext = {
  beforeSummary: string;
  afterDraft: ContentDocumentDraft;
  changedBlocks: string[];
  unchangedBlocks: string[];
};

warning review.coverage.removedSupportedClaim
The update removes documented option --no-search, but the command still supports it.

export type DraftCoverageResult = {
  targetArtifacts: GraphNodeRef[];
  coveredArtifacts: GraphNodeRef[];
  missingArtifacts: GraphNodeRef[];
};

export type ReviewDecision =
  | { type: "autoApprove" }
  | { type: "repair"; issues: ReviewIssue[] }
  | { type: "retrieveMoreEvidence"; missingEvidence: MissingEvidence[] }
  | { type: "humanReview"; reason: string }
  | { type: "reject"; reason: string };

export function decideAfterReview(report: ReviewReport): ReviewDecision {
  if (report.verdict === "approve") return { type: "autoApprove" };

  if (report.issues.some((i) => i.category === "safety" && i.severity === "error")) {
    return { type: "reject", reason: "Safety issue detected." };
  }

  if (report.issues.some((i) => i.category === "evidence")) {
    return { type: "retrieveMoreEvidence", missingEvidence: reportToMissingEvidence(report) };
  }

  return { type: "repair", issues: report.issues };
}

packages/doc-reviewer/
  src/
    input.ts
    output-schema.ts
    claim-extraction.ts
    deterministic-checks/
      cli-flags.ts
      api-endpoints.ts
      config-fields.ts
      secrets.ts
      links.ts
      commands.ts
    prompts/
      fact-check.ts
      style-review.ts
      coverage-review.ts
    validators/
      coverage.ts
      style.ts
      safety.ts
      privacy.ts
      code.ts
    aggregate.ts
    verdict.ts
    repair-decision.ts
    trace.ts
    eval.ts
    __tests__/
      claim-extraction.test.ts
      cli-flag-check.test.ts
      endpoint-check.test.ts
      verdict.test.ts
      aggregate.test.ts

export async function generateReviewedPage(job: AiWriterGenerationJob): Promise<ReviewedPageResult> {
  const evidence = await retrieveEvidence(job);
  const draft = await runDocWriter(job, evidence);
  const deterministicDiagnostics = validateDraft(draft, job, evidence);
  const review = await runDocReviewer({
    page: job.page,
    plan: job.plan,
    draft,
    evidence,
    validationDiagnostics: deterministicDiagnostics,
    styleGuide: job.styleGuide,
    reviewPolicy: job.reviewPolicy,
  });

  const decision = decideAfterReview(review);

  switch (decision.type) {
    case "autoApprove":
      return emitPage(draft);
    case "repair":
      return repairAndReview(job, draft, review);
    case "retrieveMoreEvidence":
      return retrieveMoreAndRetry(job, decision.missingEvidence);
    case "humanReview":
      return createReviewArtifact(job, draft, review);
    case "reject":
      return failGeneration(job, review);
  }
}

.docforge/reviews/<job-id>/
  draft.mdx
  draft.ir.json
  review-report.json
  evidence.json
  diff.patch

Review required for /guides/openapi-reference

Open review artifact:
  .docforge/reviews/job_123/review-report.json

it("flags unsupported claim", async () => {
  const report = await factCheck({
    claim: "`docforge build` deploys to Vercel.",
    evidence: [evidenceBuildCommand()],
  });

  expect(report.unsupportedClaims).toContainEqual(
    expect.objectContaining({ suggestedAction: "remove" })
  );
});

it("flags contradicted claim", async () => {
  const report = await factCheck({
    claim: "Remote OpenAPI specs are enabled by default.",
    evidence: [evidenceRemoteDisabledByDefault()],
  });

  expect(report.checkedClaims[0].supportLevel).toBe("contradicted");
});

it("rejects secret-like output", () => {
  const diagnostics = validateNoSecretsInDraft(draftWithApiKey());

  expect(diagnostics).toContainEqual(
    expect.objectContaining({ severity: "error" })
  );
});

export type ReviewerEvalMetrics = {
  totalClaims: number;
  correctSupportClassifications: number;
  falseApprovals: number;
  falseRejections: number;
  unsupportedClaimsMissed: number;
  supportedClaimsRejected: number;
};

{
  "verdict": "approve",
  "rewrittenDocument": "..."
}

{
  "verdict": "needsChanges",
  "issues": [...],
  "suggestedFixes": [...]
}