@devport-kr/portki 0.1.1

package/dist/cli.js

@@ -0,0 +1,4465 @@
+// src/agent.ts
+import path13 from "node:path";
+import { mkdir as mkdir2, writeFile as writeFile2, readFile as readFile2 } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+// src/shared/load-env.ts
+import { readFileSync } from "node:fs";
+import path from "node:path";
+var DEFAULT_ENV_FILES = [".env.local", ".env"];
+function loadEnvFiles(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const files = options.files ?? [...DEFAULT_ENV_FILES];
+  const loadedFiles = [];
+  const loadedKeys = [];
+  for (const file of files) {
+    const absolute = path.resolve(cwd, file);
+    let source;
+    try {
+      source = readFileSync(absolute, "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of source.split(/\r?\n/)) {
+      const entry = parseEnvLine(line);
+      if (!entry) {
+        continue;
+      }
+      if (process.env[entry.key] !== void 0) {
+        continue;
+      }
+      process.env[entry.key] = entry.value;
+      loadedKeys.push(entry.key);
+    }
+    loadedFiles.push(absolute);
+  }
+  return {
+    loadedFiles,
+    loadedKeys
+  };
+}
+function parseEnvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) {
+    return null;
+  }
+  const withoutExport = trimmed.startsWith("export ") ? trimmed.slice(7).trim() : trimmed;
+  const separatorIndex = withoutExport.indexOf("=");
+  if (separatorIndex <= 0) {
+    return null;
+  }
+  const key = withoutExport.slice(0, separatorIndex).trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    return null;
+  }
+  const rawValue = withoutExport.slice(separatorIndex + 1).trim();
+  const value = unquote(rawValue);
+  return { key, value };
+}
+function unquote(value) {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1).replace(/\\n/g, "\n").replace(/\\r/g, "\r");
+  }
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+// src/ingestion/run.ts
+import { createHash as createHash4 } from "node:crypto";
+
+// src/ingestion/types.ts
+import { z } from "zod";
+var repoRefInputSchema = z.object({
+  repo: z.string().trim().min(1),
+  ref: z.string().trim().min(1).optional()
+}).strict();
+var resolvedIngestRefSchema = z.object({
+  repo_full_name: z.string().trim().min(1),
+  owner: z.string().trim().min(1),
+  repo: z.string().trim().min(1),
+  requested_ref: z.string().trim().min(1).nullable(),
+  requested_ref_type: z.enum(["branch", "sha", "default"]),
+  resolved_ref: z.string().trim().min(1),
+  commit_sha: z.string().trim().min(4),
+  resolved_via: z.string().trim().min(1),
+  source_default_branch: z.string().trim().min(1),
+  resolved_at: z.string().datetime()
+}).strict();
+var ingestRunInputSchema = z.object({
+  repo_ref: repoRefInputSchema,
+  force_rebuild: z.boolean().default(false),
+  snapshot_root: z.string().trim().min(1).default("devport-output/snapshots"),
+  now: z.function().args().returns(z.string()).optional(),
+  fixture_commit: z.string().trim().min(4).optional()
+}).strict();
+var treeSummarySchema = z.object({
+  total_files: z.number().int().nonnegative(),
+  total_directories: z.number().int().nonnegative(),
+  max_depth: z.number().int().nonnegative(),
+  by_extension: z.record(z.string(), z.number().int().nonnegative())
+}).strict();
+var languageMixSchema = z.record(z.string().trim().min(1), z.number().nonnegative()).default({});
+var ingestMetadataSchema = z.object({
+  tree_summary: treeSummarySchema,
+  language_mix: languageMixSchema,
+  key_paths: z.array(z.string().trim().min(1)),
+  files_scanned: z.number().int().nonnegative(),
+  total_bytes: z.number().int().nonnegative(),
+  manifest_signature: z.string().trim().min(1)
+}).strict();
+var ingestRunArtifactSchema = z.object({
+  ingest_run_id: z.string().trim().min(1),
+  repo_ref: z.string().trim().min(1),
+  requested_ref: z.string().trim().min(1).nullable(),
+  resolved_ref: z.string().trim().min(1),
+  commit_sha: z.string().trim().min(4),
+  snapshot_path: z.string().trim().min(1),
+  snapshot_id: z.string().trim().min(1),
+  manifest_signature: z.string().trim().min(1),
+  files_scanned: z.number().int().nonnegative(),
+  idempotent_hit: z.boolean(),
+  metadata: ingestMetadataSchema,
+  trend_artifacts: z.object({
+    window_days: z.number().int().positive(),
+    releases_path: z.string().trim().min(1),
+    tags_path: z.string().trim().min(1),
+    changelog_summary_path: z.string().trim().min(1),
+    release_count: z.number().int().nonnegative(),
+    tag_count: z.number().int().nonnegative()
+  }).strict().optional(),
+  official_docs: z.object({
+    index_path: z.string().trim().min(1),
+    discovered_count: z.number().int().nonnegative(),
+    mirrored_count: z.number().int().nonnegative()
+  }).strict().optional(),
+  created_at: z.string().datetime(),
+  completed_at: z.string().datetime(),
+  ingest_ms: z.number().int().nonnegative()
+}).strict();
+
+// src/ingestion/snapshot.ts
+import { createHash as createHash2 } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import path2 from "node:path";
+
+// src/ingestion/ref.ts
+import { createHash } from "node:crypto";
+var ALLOWED_SEGMENT = /^(?:[a-zA-Z0-9._-]+)$/;
+var SHA_7 = /^[a-fA-F0-9]{7}$/;
+var SHA_40 = /^[a-fA-F0-9]{40}$/;
+function parseRepoRef(input) {
+  const trimmed = input.trim();
+  const atSplit = trimmed.split("@");
+  if (atSplit.length > 2) {
+    throw new Error("Invalid repository reference format");
+  }
+  const repoPart = atSplit[0];
+  const refPart = atSplit[1];
+  if (!repoPart) {
+    throw new Error("Missing repository path");
+  }
+  const repoSegments = repoPart.split("/");
+  if (repoSegments.length !== 2) {
+    throw new Error("Repository must be in owner/repo format");
+  }
+  const [owner, repo] = repoSegments;
+  if (!ALLOWED_SEGMENT.test(owner) || !ALLOWED_SEGMENT.test(repo)) {
+    throw new Error("Invalid owner/repo characters");
+  }
+  return {
+    repo_full_name: `${owner.toLowerCase()}/${repo.toLowerCase()}`,
+    owner: owner.toLowerCase(),
+    repo: repo.toLowerCase(),
+    requested_ref: refPart && refPart.trim().length ? refPart.trim() : null
+  };
+}
+function normalizeRef(raw) {
+  if (!raw) {
+    return null;
+  }
+  const trimmed = raw.trim();
+  if (!trimmed.length) {
+    return null;
+  }
+  if (trimmed.startsWith("refs/heads/")) {
+    return trimmed.replace("refs/heads/", "");
+  }
+  return trimmed;
+}
+function isLikelyCommitSha(value) {
+  return SHA_7.test(value) || SHA_40.test(value);
+}
+function inferRefType(normalizedRef) {
+  if (!normalizedRef) {
+    return "default";
+  }
+  return isLikelyCommitSha(normalizedRef) ? "sha" : "branch";
+}
+function formatIngestKey({ owner, repo, commitSha }) {
+  const normalized = `${owner.toLowerCase()}-${repo.toLowerCase()}-${commitSha.toLowerCase()}`;
+  return createHash("sha1").update(normalized).digest("hex");
+}
+
+// src/ingestion/snapshot.ts
+var MANIFEST_FILE_NAME = "snapshot-manifest.json";
+var GIT_DIRECTORY = ".git";
+function normalizeRelativePath(raw) {
+  return path2.relative(".", raw).replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function isManifestFile(entryPath) {
+  return path2.basename(entryPath) === MANIFEST_FILE_NAME;
+}
+function sortEntries(entries) {
+  return [...entries].sort((left, right) => left.path.localeCompare(right.path));
+}
+function hashFile(filePath) {
+  return fs.readFile(filePath).then((content) => {
+    return createHash2("sha1").update(content).digest("hex");
+  });
+}
+async function walkFiles(root, current, entries) {
+  const absolute = path2.join(root, current);
+  const normalizedCurrent = normalizeRelativePath(current);
+  if (isManifestFile(normalizedCurrent)) {
+    return;
+  }
+  const stat = await fs.lstat(absolute);
+  if (stat.isSymbolicLink()) {
+    return;
+  }
+  if (stat.isDirectory()) {
+    if (normalizedCurrent === GIT_DIRECTORY) {
+      return;
+    }
+    if (path2.basename(absolute) === GIT_DIRECTORY) {
+      return;
+    }
+    const items = await fs.readdir(absolute, { withFileTypes: true });
+    const sorted = items.sort((left, right) => left.name.localeCompare(right.name));
+    for (const item of sorted) {
+      if (item.name === GIT_DIRECTORY) {
+        continue;
+      }
+      if (item.isDirectory()) {
+        await walkFiles(root, path2.join(current, item.name), entries);
+        continue;
+      }
+      if (item.isFile()) {
+        const fileAbsolute = path2.join(root, current, item.name);
+        const fileStat = await fs.stat(fileAbsolute);
+        entries.push({
+          path: normalizeRelativePath(path2.join(current, item.name)),
+          bytes: fileStat.size,
+          hash: await hashFile(fileAbsolute)
+        });
+      }
+    }
+    return;
+  }
+  if (stat.isFile()) {
+    entries.push({
+      path: path2.relative(root, absolute).replace(/\\/g, "/"),
+      bytes: stat.size,
+      hash: await hashFile(absolute)
+    });
+  }
+}
+function manifestDigest(entries) {
+  const normalized = sortEntries(entries);
+  const hash = createHash2("sha1");
+  for (const entry of normalized) {
+    hash.update(`${entry.path}:`);
+    hash.update(String(entry.bytes));
+    hash.update(`:${entry.hash}`);
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+async function runGitCommand(args, cwd) {
+  await new Promise((resolve, reject) => {
+    const processRef = spawn("git", args, {
+      cwd,
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    processRef.once("error", reject);
+    processRef.once("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`git command failed: git ${args.join(" ")}`));
+    });
+  });
+}
+var defaultGitShell = {
+  async materialize({ repoFullName, snapshotPath }) {
+    const repoUrl = `https://github.com/${repoFullName}.git`;
+    await runGitCommand(["clone", "--depth", "1", "--quiet", repoUrl, snapshotPath], process.cwd());
+  }
+};
+var LocalSourceShell = class {
+  constructor(sourcePath) {
+    this.sourcePath = sourcePath;
+  }
+  async materialize({ snapshotPath }) {
+    await fs.rm(snapshotPath, { recursive: true, force: true });
+    await fs.cp(this.sourcePath, snapshotPath, { recursive: true, force: true });
+  }
+};
+async function readManifest(snapshotPath) {
+  const manifestPath = path2.join(snapshotPath, MANIFEST_FILE_NAME);
+  try {
+    const raw = await fs.readFile(manifestPath, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    return null;
+  }
+}
+async function buildManifest(request, now, snapshotPath) {
+  const files = [];
+  await walkFiles(snapshotPath, ".", files);
+  const filtered = files.filter((entry) => !isManifestFile(entry.path));
+  const signature = manifestDigest(filtered);
+  const fileCount = filtered.length;
+  const totalBytes2 = filtered.reduce((sum, entry) => sum + entry.bytes, 0);
+  return {
+    repo_full_name: request.repoFullName,
+    owner: request.owner,
+    repo: request.repo,
+    commit_sha: request.commitSha,
+    resolved_ref: request.resolvedRef,
+    source_ref: request.sourceRef || request.resolvedRef,
+    source_default_branch: request.sourceDefaultBranch,
+    file_count: fileCount,
+    total_bytes: totalBytes2,
+    manifest_signature: signature,
+    created_at: now()
+  };
+}
+async function pruneOldSnapshots(repoDir, keepId) {
+  let entries;
+  try {
+    entries = await fs.readdir(repoDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name !== keepId) {
+      await fs.rm(path2.join(repoDir, entry.name), { recursive: true, force: true });
+      process.stderr.write(`  [snapshot] pruned old snapshot: ${entry.name}
+`);
+    }
+  }
+}
+var RepoSnapshotManager = class {
+  constructor(config) {
+    this.config = config;
+    this.now = config.now || (() => (/* @__PURE__ */ new Date()).toISOString());
+    this.forceRebuild = Boolean(config.forceRebuild);
+    this.rootPath = path2.resolve(config.snapshotRoot || "devport-output/snapshots");
+    this.gitShell = config.gitShell || (config.sourcePath ? new LocalSourceShell(config.sourcePath) : defaultGitShell);
+  }
+  now;
+  forceRebuild;
+  rootPath;
+  gitShell;
+  async createSnapshot(request) {
+    const snapshotId = formatIngestKey({
+      owner: request.owner,
+      repo: request.repo,
+      commitSha: request.commitSha
+    });
+    const repoDir = path2.join(this.rootPath, request.owner, request.repo);
+    await pruneOldSnapshots(repoDir, snapshotId);
+    const snapshotPath = path2.join(repoDir, snapshotId);
+    const manifestPath = path2.join(snapshotPath, MANIFEST_FILE_NAME);
+    const existing = existsSync(snapshotPath) ? await readManifest(snapshotPath) : null;
+    if (!this.forceRebuild && existing) {
+      const files = [];
+      await walkFiles(snapshotPath, ".", files);
+      const filtered = files.filter((entry) => !isManifestFile(entry.path));
+      const currentSignature = manifestDigest(filtered);
+      if (existing.commit_sha === request.commitSha && existing.manifest_signature === currentSignature) {
+        return {
+          snapshotPath,
+          snapshotId,
+          manifest: existing,
+          idempotentHit: true
+        };
+      }
+    }
+    await fs.rm(snapshotPath, { recursive: true, force: true });
+    await this.gitShell.materialize({
+      repoFullName: request.repoFullName,
+      commitSha: request.commitSha,
+      snapshotPath
+    });
+    const manifest = await buildManifest(request, this.now, snapshotPath);
+    await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+    return {
+      snapshotPath,
+      snapshotId,
+      manifest,
+      idempotentHit: false
+    };
+  }
+};
+
+// src/ingestion/metadata.ts
+import { promises as fs2 } from "node:fs";
+import path3 from "node:path";
+var DEFAULT_MAX_KEY_PATHS = 120;
+var DEFAULT_MAX_EXTENSION_BUCKETS = 64;
+var DEFAULT_MAX_LANGUAGE_BUCKETS = 32;
+var NO_EXTENSION_LABEL = "[no_ext]";
+var KEY_PATH_HINTS = [
+  /^readme/i,
+  /^license/i,
+  /^changelog/i,
+  /^dockerfile/i,
+  /^package\.json$/i,
+  /^pnpm-lock\.yaml$/i,
+  /^yarn\.lock$/i,
+  /^package-lock\.json$/i,
+  /^tsconfig\.json$/i,
+  /^vite\.config\./i,
+  /^jest\.config\./i,
+  /^next\.config\./i,
+  /^turbo\.json$/i,
+  /^go\.mod$/i,
+  /^pyproject\.toml$/i,
+  /^Cargo\.toml$/i,
+  /^requirements\.txt$/i,
+  /^Pipfile$/i,
+  /^pom\.xml$/i,
+  /^build\.gradle$/i,
+  /^gradle\.properties$/i,
+  /^docker-compose\.ya?ml$/i,
+  /^mkdocs\.ya?ml$/i,
+  /^Makefile$/i
+].map((entry) => new RegExp(entry));
+function normalizePath(relativePath) {
+  return relativePath.replace(/\\/g, "/");
+}
+function normalizeExtension(rawPath) {
+  const extension = path3.extname(rawPath).toLowerCase().replace(/^\./, "");
+  return extension || NO_EXTENSION_LABEL;
+}
+function truncateSortedObject(input, limit) {
+  const sortedKeys = Object.keys(input).sort();
+  const bounded = sortedKeys.slice(0, Math.max(0, limit));
+  return bounded.reduce((acc, key) => {
+    acc[key] = input[key];
+    return acc;
+  }, {});
+}
+function extensionToLanguage(extension) {
+  const ext = extension.toLowerCase();
+  const map = {
+    ts: "TypeScript",
+    tsx: "TypeScript",
+    js: "JavaScript",
+    jsx: "JavaScript",
+    mjs: "JavaScript",
+    cjs: "JavaScript",
+    py: "Python",
+    rb: "Ruby",
+    rs: "Rust",
+    go: "Go",
+    java: "Java",
+    kt: "Kotlin",
+    kts: "Kotlin",
+    cs: "C#",
+    cpp: "C++",
+    cc: "C++",
+    cxx: "C++",
+    h: "C",
+    c: "C",
+    md: "Markdown",
+    mdx: "Markdown",
+    yaml: "YAML",
+    yml: "YAML",
+    toml: "TOML",
+    json: "JSON",
+    xml: "XML",
+    sh: "Shell",
+    bash: "Shell",
+    dockerfile: "Dockerfile",
+    php: "PHP",
+    swift: "Swift",
+    scala: "Scala",
+    dart: "Dart"
+  };
+  return map[ext] ?? "Other";
+}
+function collectTree(rootPath) {
+  const entries = [];
+  const skipDirs = /* @__PURE__ */ new Set([".git", ".husky", "node_modules", "dist", ".next", "target"]);
+  const walk = async (relative) => {
+    const absolute = path3.join(rootPath, relative);
+    const dirents = await fs2.readdir(absolute, { withFileTypes: true });
+    const sorted = dirents.sort((left, right) => left.name.localeCompare(right.name));
+    for (const dirent of sorted) {
+      if (dirent.name === "snapshot-manifest.json") {
+        continue;
+      }
+      if (dirent.isSymbolicLink()) {
+        continue;
+      }
+      if (dirent.isDirectory()) {
+        if (skipDirs.has(dirent.name.toLowerCase())) {
+          continue;
+        }
+        await walk(path3.join(relative, dirent.name));
+        continue;
+      }
+      if (dirent.isFile()) {
+        const filePath = path3.join(relative, dirent.name);
+        const stat = await fs2.stat(path3.join(rootPath, filePath));
+        entries.push({ path: normalizePath(filePath), bytes: stat.size });
+      }
+    }
+  };
+  return walk(".").then(() => entries);
+}
+function calculateSummary(entries, extensionBucketLimit) {
+  const byExtension = {};
+  let totalDirectories = 0;
+  let maxDepth = 0;
+  for (const entry of entries) {
+    const extension = normalizeExtension(entry.path);
+    byExtension[extension] = (byExtension[extension] ?? 0) + 1;
+    const segments = entry.path.split("/");
+    totalDirectories += segments.length > 1 ? segments.length - 1 : 0;
+    maxDepth = Math.max(maxDepth, segments.length);
+  }
+  const maxTotalDirectories = entries.length > 0 ? totalDirectories : 0;
+  return {
+    total_files: entries.length,
+    total_directories: maxTotalDirectories,
+    max_depth: maxDepth,
+    by_extension: truncateSortedObject(byExtension, extensionBucketLimit)
+  };
+}
+function buildKeyPaths(entries, maxCount) {
+  const keyPaths = /* @__PURE__ */ new Set();
+  const seenDirectories = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    const basename = path3.basename(entry.path);
+    if (!basename || basename.startsWith(".")) {
+      continue;
+    }
+    const depthSegments = entry.path.split("/");
+    if (depthSegments.length > 1) {
+      seenDirectories.add(depthSegments[0]);
+    }
+    if (KEY_PATH_HINTS.some((pattern) => pattern.test(basename))) {
+      keyPaths.add(entry.path);
+    }
+  }
+  for (const dir of ["src", "packages", "apps", "docs", "examples", "test", "tests", "scripts", "tools", "config"]) {
+    if (seenDirectories.has(dir)) {
+      keyPaths.add(dir);
+    }
+  }
+  return Array.from(keyPaths).sort().slice(0, maxCount);
+}
+function deriveLanguageMix(entries, manifestLanguageMix, languageBucketLimit) {
+  if (manifestLanguageMix && Object.keys(manifestLanguageMix).length > 0) {
+    const sanitized = Object.entries(manifestLanguageMix).reduce((acc, [name, bytes]) => {
+      if (typeof name !== "string" || !name.trim().length) {
+        return acc;
+      }
+      if (!Number.isFinite(bytes) || bytes < 0) {
+        return acc;
+      }
+      acc[name] = bytes;
+      return acc;
+    }, {});
+    return truncateSortedObject(sanitized, languageBucketLimit);
+  }
+  const byLanguage = {};
+  for (const entry of entries) {
+    const language = extensionToLanguage(normalizeExtension(entry.path));
+    byLanguage[language] = (byLanguage[language] ?? 0) + entry.bytes;
+  }
+  return truncateSortedObject(byLanguage, languageBucketLimit);
+}
+function totalBytes(entries) {
+  return entries.reduce((sum, entry) => sum + entry.bytes, 0);
+}
+async function extractMetadata(snapshotPath, options) {
+  const files = await collectTree(snapshotPath);
+  const summary = calculateSummary(
+    files,
+    options.extensionBucketLimit ?? DEFAULT_MAX_EXTENSION_BUCKETS
+  );
+  const keyPaths = buildKeyPaths(files, options.keyPathLimit ?? DEFAULT_MAX_KEY_PATHS);
+  const languageMix = deriveLanguageMix(
+    files,
+    options.languageMix,
+    options.languageBucketLimit ?? DEFAULT_MAX_LANGUAGE_BUCKETS
+  );
+  return {
+    tree_summary: {
+      total_files: summary.total_files,
+      total_directories: summary.total_directories,
+      max_depth: summary.max_depth,
+      by_extension: summary.by_extension
+    },
+    language_mix: languageMix,
+    key_paths: keyPaths,
+    files_scanned: files.length,
+    total_bytes: totalBytes(files),
+    manifest_signature: options.manifestSignature
+  };
+}
+
+// src/ingestion/github.ts
+import { Octokit } from "@octokit/rest";
+var IngestResolverError = class extends Error {
+  constructor(message, code, detail) {
+    super(message);
+    this.code = code;
+    this.detail = detail;
+    this.name = "IngestResolverError";
+  }
+};
+function normalizeGitHubRepoIdentityForResolver(rawRepoRef) {
+  const parsed = parseRepoRef(rawRepoRef);
+  if (parsed.requested_ref !== null) {
+    throw new Error("repo_ref must not include @ref for freshness detection");
+  }
+  return {
+    owner: parsed.owner,
+    repo: parsed.repo,
+    repo_ref: parsed.repo_full_name
+  };
+}
+var OctokitGitHubResolver = class {
+  octokit;
+  constructor(token) {
+    this.octokit = new Octokit(
+      token ? {
+        auth: token
+      } : void 0
+    );
+  }
+  async getRepositoryMeta(repo) {
+    try {
+      const response = await this.octokit.rest.repos.get({
+        owner: repo.owner,
+        repo: repo.repo
+      });
+      return {
+        owner: response.data.owner.login.toLowerCase(),
+        repo: response.data.name.toLowerCase(),
+        full_name: response.data.full_name.toLowerCase(),
+        default_branch: response.data.default_branch,
+        homepage_url: response.data.homepage ?? null
+      };
+    } catch (error) {
+      if (isHttpError(error, 404)) {
+        throw new IngestResolverError(
+          `Repository not found: ${repo.repo_full_name}`,
+          "REPO_NOT_FOUND",
+          error
+        );
+      }
+      throw new IngestResolverError(
+        `Failed to load repository metadata: ${repo.repo_full_name}`,
+        "INVALID_REPO",
+        error
+      );
+    }
+  }
+  async resolveRefToCommit(repo, ref) {
+    try {
+      const resolved = await this.octokit.rest.repos.getCommit({
+        owner: repo.owner,
+        repo: repo.repo,
+        ref
+      });
+      return resolved.data.sha;
+    } catch (error) {
+      if (isHttpError(error, 404)) {
+        throw new IngestResolverError(
+          `Unable to resolve ref '${ref}' for ${repo.repo_full_name}`,
+          "REF_NOT_FOUND",
+          error
+        );
+      }
+      throw new IngestResolverError(
+        `Failed to resolve ref '${ref}' for ${repo.repo_full_name}`,
+        "UNRESOLVED_REF",
+        error
+      );
+    }
+  }
+  async getRepositoryLanguages(repo) {
+    try {
+      const response = await this.octokit.rest.repos.listLanguages({
+        owner: repo.owner,
+        repo: repo.repo
+      });
+      return response.data;
+    } catch {
+      return null;
+    }
+  }
+  async getRepositoryReleases(repo, input) {
+    const perPage = Math.max(1, Math.min(100, input.per_page ?? 100));
+    const maxItems = Math.max(1, Math.min(500, input.max_items ?? 200));
+    const releases = [];
+    let page = 1;
+    while (releases.length < maxItems) {
+      const response = await this.octokit.rest.repos.listReleases({
+        owner: repo.owner,
+        repo: repo.repo,
+        per_page: perPage,
+        page
+      });
+      const list = response.data ?? [];
+      if (list.length === 0) {
+        break;
+      }
+      for (const release of list) {
+        const publishedAt = release.published_at ?? null;
+        if (publishedAt && publishedAt < input.since) {
+          continue;
+        }
+        releases.push({
+          id: release.id,
+          tag_name: release.tag_name,
+          name: release.name ?? null,
+          published_at: publishedAt,
+          prerelease: Boolean(release.prerelease),
+          draft: Boolean(release.draft),
+          html_url: release.html_url ?? null
+        });
+        if (releases.length >= maxItems) {
+          break;
+        }
+      }
+      if (list.length < perPage) {
+        break;
+      }
+      page += 1;
+    }
+    return releases;
+  }
+  async getRepositoryTags(repo, input = {}) {
+    const perPage = Math.max(1, Math.min(100, input.per_page ?? 100));
+    const maxItems = Math.max(1, Math.min(500, input.max_items ?? 200));
+    const tags = [];
+    let page = 1;
+    while (tags.length < maxItems) {
+      const response = await this.octokit.rest.repos.listTags({
+        owner: repo.owner,
+        repo: repo.repo,
+        per_page: perPage,
+        page
+      });
+      const list = response.data ?? [];
+      if (list.length === 0) {
+        break;
+      }
+      for (const tag of list) {
+        tags.push({
+          name: tag.name,
+          commit_sha: tag.commit?.sha ?? null,
+          tarball_url: tag.tarball_url ?? null,
+          zipball_url: tag.zipball_url ?? null
+        });
+        if (tags.length >= maxItems) {
+          break;
+        }
+      }
+      if (list.length < perPage) {
+        break;
+      }
+      page += 1;
+    }
+    return tags;
+  }
+};
+async function resolveToCommitSha(repo, resolver) {
+  const normalizedRef = normalizeRef(repo.requested_ref);
+  let metadata;
+  try {
+    metadata = await resolver.getRepositoryMeta(repo);
+  } catch (error) {
+    if (error instanceof Error) {
+      throw error;
+    }
+    throw new IngestResolverError("Unable to load repository metadata", "INVALID_REPO");
+  }
+  const refType = inferRefType(normalizedRef);
+  const requestedRef = refType === "default" ? metadata.default_branch : normalizedRef;
+  try {
+    const commitSha = await resolver.resolveRefToCommit(
+      {
+        ...repo,
+        requested_ref: normalizedRef
+      },
+      requestedRef
+    );
+    return {
+      requested_ref: repo.requested_ref,
+      requested_ref_type: refType,
+      resolved_ref: requestedRef,
+      commit_sha: commitSha.toLowerCase(),
+      source_default_branch: metadata.default_branch
+    };
+  } catch (error) {
+    if (error instanceof IngestResolverError) {
+      if (refType === "default") {
+        throw error;
+      }
+      throw error;
+    }
+    throw new IngestResolverError(
+      `Failed to resolve ref for ${repo.repo_full_name}`,
+      "UNRESOLVED_REF",
+      error
+    );
+  }
+}
+function isHttpError(error, status) {
+  return !!(error && typeof error === "object" && "status" in error && error.status === status);
+}
+
+// src/ingestion/official-docs.ts
+import { promises as fs4 } from "node:fs";
+import path5 from "node:path";
+
+// src/ingestion/trends.ts
+import { createHash as createHash3 } from "node:crypto";
+import { promises as fs3 } from "node:fs";
+import path4 from "node:path";
+var MANIFEST_FILE_NAME2 = "snapshot-manifest.json";
+var TRENDS_DIR = "__devport__/trends";
+var DEFAULT_TREND_WINDOW_DAYS = 180;
+var MAX_RELEASE_ITEMS = 120;
+var MAX_TAG_ITEMS = 120;
+function normalizePath2(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
+}
+function normalizeWindowDays(raw) {
+  const numeric = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    return DEFAULT_TREND_WINDOW_DAYS;
+  }
+  return Math.max(1, Math.min(3650, Math.floor(numeric)));
+}
+function cutoffIso(now, windowDays) {
+  const timestamp = new Date(now).getTime();
+  if (!Number.isFinite(timestamp)) {
+    return new Date(Date.now() - windowDays * 24 * 60 * 60 * 1e3).toISOString();
+  }
+  return new Date(timestamp - windowDays * 24 * 60 * 60 * 1e3).toISOString();
+}
+async function collectReleases(repo, resolver, since) {
+  if (typeof resolver.getRepositoryReleases !== "function") {
+    return [];
+  }
+  try {
+    const releases = await resolver.getRepositoryReleases(repo, {
+      since,
+      per_page: 100,
+      max_items: MAX_RELEASE_ITEMS
+    });
+    return (releases ?? []).filter((release) => {
+      const publishedAt = release.published_at ?? "";
+      return publishedAt.length === 0 || publishedAt >= since;
+    }).sort((left, right) => {
+      const leftPublished = left.published_at ?? "";
+      const rightPublished = right.published_at ?? "";
+      const byPublishedDesc = rightPublished.localeCompare(leftPublished);
+      if (byPublishedDesc !== 0) {
+        return byPublishedDesc;
+      }
+      return (left.tag_name ?? "").localeCompare(right.tag_name ?? "", "en", {
+        numeric: true,
+        sensitivity: "base"
+      });
+    }).slice(0, MAX_RELEASE_ITEMS);
+  } catch {
+    return [];
+  }
+}
+async function collectTags(repo, resolver) {
+  if (typeof resolver.getRepositoryTags !== "function") {
+    return [];
+  }
+  try {
+    const tags = await resolver.getRepositoryTags(repo, {
+      per_page: 100,
+      max_items: MAX_TAG_ITEMS
+    });
+    return (tags ?? []).sort(
+      (left, right) => left.name.localeCompare(right.name, "en", {
+        numeric: true,
+        sensitivity: "base"
+      })
+    ).slice(0, MAX_TAG_ITEMS);
+  } catch {
+    return [];
+  }
+}
+async function writeJsonFile(filePath, payload) {
+  await fs3.mkdir(path4.dirname(filePath), { recursive: true });
+  await fs3.writeFile(filePath, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+}
+async function readSnapshotManifest(snapshotPath) {
+  const manifestPath = path4.join(snapshotPath, MANIFEST_FILE_NAME2);
+  const raw = await fs3.readFile(manifestPath, "utf8");
+  return JSON.parse(raw);
+}
+async function hashFile2(filePath) {
+  const content = await fs3.readFile(filePath);
+  return createHash3("sha1").update(content).digest("hex");
+}
+async function walkSnapshotFiles(rootPath, relativeDir, entries) {
+  const absoluteDir = path4.join(rootPath, relativeDir);
+  const dirents = await fs3.readdir(absoluteDir, { withFileTypes: true });
+  const sorted = dirents.sort((left, right) => left.name.localeCompare(right.name));
+  for (const dirent of sorted) {
+    if (dirent.isSymbolicLink()) {
+      continue;
+    }
+    const nextRelative = normalizePath2(path4.join(relativeDir, dirent.name));
+    if (nextRelative === ".git" || nextRelative.startsWith(".git/")) {
+      continue;
+    }
+    if (path4.basename(nextRelative) === MANIFEST_FILE_NAME2) {
+      continue;
+    }
+    if (dirent.isDirectory()) {
+      await walkSnapshotFiles(rootPath, nextRelative, entries);
+      continue;
+    }
+    if (!dirent.isFile()) {
+      continue;
+    }
+    const absoluteFile = path4.join(rootPath, nextRelative);
+    const stat = await fs3.stat(absoluteFile);
+    entries.push({
+      path: nextRelative,
+      bytes: stat.size,
+      hash: await hashFile2(absoluteFile)
+    });
+  }
+}
+function buildManifestSignature(entries) {
+  const sorted = [...entries].sort((left, right) => left.path.localeCompare(right.path));
+  const hash = createHash3("sha1");
+  for (const entry of sorted) {
+    hash.update(`${entry.path}:`);
+    hash.update(String(entry.bytes));
+    hash.update(`:${entry.hash}`);
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+async function refreshSnapshotManifest(snapshotPath) {
+  const manifestPath = path4.join(snapshotPath, MANIFEST_FILE_NAME2);
+  const manifest = await readSnapshotManifest(snapshotPath);
+  const entries = [];
+  await walkSnapshotFiles(snapshotPath, ".", entries);
+  const manifestSignature = buildManifestSignature(entries);
+  const fileCount = entries.length;
+  const totalBytes2 = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+  const updatedManifest = {
+    ...manifest,
+    file_count: fileCount,
+    total_bytes: totalBytes2,
+    manifest_signature: manifestSignature
+  };
+  await fs3.writeFile(manifestPath, `${JSON.stringify(updatedManifest, null, 2)}
+`, "utf8");
+  return manifestSignature;
+}
+async function persistTrendArtifacts(input) {
+  const now = (input.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()))();
+  const windowDays = normalizeWindowDays(
+    input.trendWindowDays ?? process.env.DEVPORT_TREND_WINDOW_DAYS
+  );
+  const since = cutoffIso(now, windowDays);
+  const releases = await collectReleases(input.repo, input.resolver, since);
+  const tags = await collectTags(input.repo, input.resolver);
+  const trendDir = path4.join(input.snapshotPath, TRENDS_DIR);
+  const releasesPath = path4.join(trendDir, "releases.json");
+  const tagsPath = path4.join(trendDir, "tags.json");
+  const changelogSummaryPath = path4.join(trendDir, "changelog-summary.json");
+  await writeJsonFile(releasesPath, {
+    repo_ref: input.repo.repo_full_name,
+    commit_sha: input.commitSha,
+    window_days: windowDays,
+    since,
+    releases
+  });
+  await writeJsonFile(tagsPath, {
+    repo_ref: input.repo.repo_full_name,
+    commit_sha: input.commitSha,
+    window_days: windowDays,
+    tags
+  });
+  await writeJsonFile(changelogSummaryPath, {
+    repo_ref: input.repo.repo_full_name,
+    commit_sha: input.commitSha,
+    window_days: windowDays,
+    release_count: releases.length,
+    tag_count: tags.length,
+    latest_release_tags: releases.slice(0, 10).map((release) => release.tag_name),
+    latest_tags: tags.slice(0, 10).map((tag) => tag.name)
+  });
+  const manifestSignature = await refreshSnapshotManifest(input.snapshotPath);
+  return {
+    window_days: windowDays,
+    releases_path: normalizePath2(path4.relative(input.snapshotPath, releasesPath)),
+    tags_path: normalizePath2(path4.relative(input.snapshotPath, tagsPath)),
+    changelog_summary_path: normalizePath2(path4.relative(input.snapshotPath, changelogSummaryPath)),
+    release_count: releases.length,
+    tag_count: tags.length,
+    manifest_signature: manifestSignature
+  };
+}
+
+// src/ingestion/official-docs.ts
+var OFFICIAL_DOCS_DIR = "__devport__/official-docs";
+var MAX_DISCOVERED_URLS = 20;
+var MAX_MIRRORED_BYTES = 256e3;
+var MARKDOWN_LINK_PATTERN = /\[[^\]]+\]\((https?:\/\/[^)\s]+)\)/giu;
+var RAW_URL_PATTERN = /\bhttps?:\/\/[^\s<>"]+/giu;
+function normalizePath3(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
+}
+function normalizeUrl(raw) {
+  try {
+    const parsed = new URL(raw.trim());
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return null;
+    }
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+async function loadRootReadme(snapshotPath) {
+  const candidates = ["README.md", "README.MD", "Readme.md", "readme.md"];
+  for (const candidate of candidates) {
+    try {
+      return await fs4.readFile(path5.join(snapshotPath, candidate), "utf8");
+    } catch {
+    }
+  }
+  return "";
+}
+function extractHttpUrls(text) {
+  const urls = /* @__PURE__ */ new Set();
+  for (const match of text.matchAll(MARKDOWN_LINK_PATTERN)) {
+    const normalized = normalizeUrl(match[1]);
+    if (normalized) {
+      urls.add(normalized);
+    }
+  }
+  for (const match of text.matchAll(RAW_URL_PATTERN)) {
+    const normalized = normalizeUrl(match[0]);
+    if (normalized) {
+      urls.add(normalized);
+    }
+  }
+  return [...urls].sort((left, right) => left.localeCompare(right, "en", { sensitivity: "base" })).slice(0, MAX_DISCOVERED_URLS);
+}
+function resolveFetchImpl(fetchImpl) {
+  if (fetchImpl) {
+    return fetchImpl;
+  }
+  const globalFetch = globalThis.fetch;
+  if (typeof globalFetch === "function") {
+    return globalFetch;
+  }
+  return void 0;
+}
+async function mirrorUrlToSnapshot(snapshotPath, sourceUrl, index, fetchImpl) {
+  if (!fetchImpl) {
+    return {
+      source_url: sourceUrl,
+      mirror_path: null,
+      status: "fetch-unavailable"
+    };
+  }
+  try {
+    const response = await fetchImpl(sourceUrl, { redirect: "follow" });
+    if (!response.ok) {
+      return {
+        source_url: sourceUrl,
+        mirror_path: null,
+        status: "fetch-failed"
+      };
+    }
+    const rawText = await response.text();
+    const text = rawText.slice(0, MAX_MIRRORED_BYTES);
+    const mirrorRelativePath = normalizePath3(
+      path5.join(OFFICIAL_DOCS_DIR, `doc-${String(index + 1).padStart(2, "0")}.md`)
+    );
+    const mirrorAbsolutePath = path5.join(snapshotPath, mirrorRelativePath);
+    await fs4.mkdir(path5.dirname(mirrorAbsolutePath), { recursive: true });
+    await fs4.writeFile(
+      mirrorAbsolutePath,
+      `# ${sourceUrl}
+
+${text}
+`,
+      "utf8"
+    );
+    return {
+      source_url: sourceUrl,
+      mirror_path: mirrorRelativePath,
+      status: "mirrored"
+    };
+  } catch {
+    return {
+      source_url: sourceUrl,
+      mirror_path: null,
+      status: "fetch-failed"
+    };
+  }
+}
+async function persistOfficialDocsArtifacts(input) {
+  const discoveryMode = (process.env.DEVPORT_OFFICIAL_DOC_DISCOVERY ?? "auto").trim().toLowerCase();
+  const readmeContent = await loadRootReadme(input.snapshotPath);
+  const discoveredUrls = discoveryMode === "off" ? [] : extractHttpUrls(readmeContent);
+  let homepageUrl = null;
+  if (discoveryMode !== "off") {
+    try {
+      const meta = await input.resolver.getRepositoryMeta(input.repo);
+      homepageUrl = normalizeUrl(meta.homepage_url ?? "");
+    } catch {
+      homepageUrl = null;
+    }
+  }
+  const discoveredWithHomepage = new Set(discoveredUrls);
+  if (homepageUrl) {
+    discoveredWithHomepage.add(homepageUrl);
+  }
+  const finalDiscoveredUrls = [...discoveredWithHomepage].sort((left, right) => left.localeCompare(right, "en", { sensitivity: "base" })).slice(0, MAX_DISCOVERED_URLS);
+  const fetchImpl = discoveryMode === "off" ? void 0 : resolveFetchImpl(input.fetchImpl);
+  const docs = [];
+  for (let index = 0; index < finalDiscoveredUrls.length; index += 1) {
+    docs.push(
+      await mirrorUrlToSnapshot(
+        input.snapshotPath,
+        finalDiscoveredUrls[index],
+        index,
+        fetchImpl
+      )
+    );
+  }
+  const indexRelativePath = normalizePath3(path5.join(OFFICIAL_DOCS_DIR, "index.json"));
+  const indexAbsolutePath = path5.join(input.snapshotPath, indexRelativePath);
+  await fs4.mkdir(path5.dirname(indexAbsolutePath), { recursive: true });
+  await fs4.writeFile(
+    indexAbsolutePath,
+    `${JSON.stringify(
+      {
+        repo_ref: input.repo.repo_full_name,
+        commit_sha: input.commitSha,
+        discovery_mode: discoveryMode,
+        discovered_count: finalDiscoveredUrls.length,
+        mirrored_count: docs.filter((entry) => entry.status === "mirrored").length,
+        docs
+      },
+      null,
+      2
+    )}
+`,
+    "utf8"
+  );
+  const manifestSignature = await refreshSnapshotManifest(input.snapshotPath);
+  return {
+    index_path: indexRelativePath,
+    discovered_count: finalDiscoveredUrls.length,
+    mirrored_count: docs.filter((entry) => entry.status === "mirrored").length,
+    manifest_signature: manifestSignature
+  };
+}
+
+// src/ingestion/run.ts
+function safeNow(now = () => (/* @__PURE__ */ new Date()).toISOString()) {
+  return now();
+}
+function buildIngestRunId(repoFullName, snapshotId, manifestSignature) {
+  return createHash4("sha1").update(`${repoFullName}|${snapshotId}|${manifestSignature}`).digest("hex");
+}
+async function resolveReference(repo, requestedRef, resolver, fixtureCommit) {
+  if (fixtureCommit && requestedRef) {
+    return {
+      requested_ref: requestedRef,
+      requested_ref_type: inferRefType(requestedRef),
+      resolved_ref: requestedRef,
+      commit_sha: fixtureCommit.toLowerCase(),
+      source_default_branch: requestedRef
+    };
+  }
+  const metadata = await resolver.getRepositoryMeta(repo);
+  const sourceDefaultBranch = metadata.default_branch;
+  if (fixtureCommit) {
+    const resolvedRef = requestedRef || sourceDefaultBranch;
+    return {
+      requested_ref: requestedRef,
+      requested_ref_type: inferRefType(requestedRef),
+      resolved_ref: resolvedRef,
+      commit_sha: fixtureCommit.toLowerCase(),
+      source_default_branch: sourceDefaultBranch
+    };
+  }
+  const resolution = await resolveToCommitSha(
+    {
+      ...repo,
+      requested_ref: requestedRef
+    },
+    resolver
+  );
+  return {
+    requested_ref: requestedRef,
+    requested_ref_type: resolution.requested_ref_type,
+    resolved_ref: resolution.resolved_ref,
+    commit_sha: resolution.commit_sha.toLowerCase(),
+    source_default_branch: resolution.source_default_branch
+  };
+}
+async function createOrReuseSnapshot(snapshotManager, repo, resolved) {
+  const request = {
+    repoFullName: repo.repo_full_name,
+    owner: repo.owner,
+    repo: repo.repo,
+    commitSha: resolved.commit_sha,
+    resolvedRef: resolved.resolved_ref,
+    sourceRef: resolved.requested_ref,
+    sourceDefaultBranch: resolved.source_default_branch
+  };
+  return snapshotManager.createSnapshot(request);
+}
+async function extractRunMetadata(snapshotPath, manifestSignature, resolver, languageResolver, allowResolverLanguageLookup, languageArgs) {
+  const languageMix = languageResolver ? await languageResolver(languageArgs) : allowResolverLanguageLookup ? await loadLanguageMixFromResolver(resolver, languageArgs) : null;
+  return extractMetadata(snapshotPath, {
+    manifestSignature,
+    keyPathLimit: 120,
+    languageMix
+  });
+}
+async function loadLanguageMixFromResolver(resolver, languageArgs) {
+  if (typeof resolver.getRepositoryLanguages !== "function") {
+    return null;
+  }
+  try {
+    return await resolver.getRepositoryLanguages({
+      owner: languageArgs.owner,
+      repo: languageArgs.repo,
+      repo_full_name: languageArgs.fullName,
+      requested_ref: languageArgs.commitSha
+    });
+  } catch {
+    return null;
+  }
+}
+function pushStage(stageHistory, stage, startedAt, status = "ok") {
+  stageHistory.push({
+    stage,
+    started_at: startedAt,
+    ended_at: safeNow(),
+    status
+  });
+}
+async function runIngest(rawInput, config = {}) {
+  const now = config.now || (() => (/* @__PURE__ */ new Date()).toISOString());
+  const parsedInput = ingestRunInputSchema.parse(rawInput);
+  const startedAt = safeNow(now);
+  const startedMs = Date.now();
+  const stageHistory = [];
+  const repo = parseRepoRef(parsedInput.repo_ref.repo);
+  const normalizedRequestedRef = normalizeRef(parsedInput.repo_ref.ref);
+  const resolver = config.resolver || new OctokitGitHubResolver(process.env.GITHUB_TOKEN);
+  const gitShell = config.sourcePath ? void 0 : defaultGitShell;
+  const snapshotManager = config.snapshotManager || new RepoSnapshotManager({
+    snapshotRoot: parsedInput.snapshot_root,
+    now,
+    forceRebuild: parsedInput.force_rebuild,
+    sourcePath: config.sourcePath,
+    gitShell
+  });
+  let resolved;
+  const resolveStart = safeNow(now);
+  try {
+    resolved = await resolveReference(
+      repo,
+      normalizedRequestedRef,
+      resolver,
+      config.fixtureCommit || parsedInput.fixture_commit
+    );
+    pushStage(stageHistory, "resolve_ref", resolveStart);
+  } catch (error) {
+    pushStage(stageHistory, "resolve_ref", resolveStart, "failed");
+    throw error;
+  }
+  const snapshotStart = safeNow(now);
+  let snapshot;
+  try {
+    snapshot = await createOrReuseSnapshot(snapshotManager, repo, resolved);
+    pushStage(stageHistory, "snapshot", snapshotStart);
+  } catch (error) {
+    pushStage(stageHistory, "snapshot", snapshotStart, "failed");
+    throw error;
+  }
+  const metadataStart = safeNow(now);
+  let metadata;
+  let trendArtifacts;
+  let officialDocsArtifacts;
+  try {
+    const persistedTrendArtifacts = await persistTrendArtifacts({
+      snapshotPath: snapshot.snapshotPath,
+      repo,
+      resolver,
+      commitSha: resolved.commit_sha,
+      now
+    });
+    trendArtifacts = {
+      window_days: persistedTrendArtifacts.window_days,
+      releases_path: persistedTrendArtifacts.releases_path,
+      tags_path: persistedTrendArtifacts.tags_path,
+      changelog_summary_path: persistedTrendArtifacts.changelog_summary_path,
+      release_count: persistedTrendArtifacts.release_count,
+      tag_count: persistedTrendArtifacts.tag_count
+    };
+    if (persistedTrendArtifacts.manifest_signature !== snapshot.manifest.manifest_signature) {
+      snapshot.manifest.manifest_signature = persistedTrendArtifacts.manifest_signature;
+    }
+    const persistedOfficialDocsArtifacts = await persistOfficialDocsArtifacts({
+      snapshotPath: snapshot.snapshotPath,
+      repo,
+      resolver,
+      commitSha: resolved.commit_sha
+    });
+    officialDocsArtifacts = {
+      index_path: persistedOfficialDocsArtifacts.index_path,
+      discovered_count: persistedOfficialDocsArtifacts.discovered_count,
+      mirrored_count: persistedOfficialDocsArtifacts.mirrored_count
+    };
+    if (persistedOfficialDocsArtifacts.manifest_signature !== snapshot.manifest.manifest_signature) {
+      snapshot.manifest.manifest_signature = persistedOfficialDocsArtifacts.manifest_signature;
+    }
+    const fixtureCommit = config.fixtureCommit || parsedInput.fixture_commit;
+    metadata = await extractRunMetadata(
+      snapshot.snapshotPath,
+      snapshot.manifest.manifest_signature,
+      resolver,
+      config.languageResolver,
+      !fixtureCommit,
+      {
+        owner: repo.owner,
+        repo: repo.repo,
+        fullName: repo.repo_full_name,
+        commitSha: resolved.commit_sha
+      }
+    );
+    pushStage(stageHistory, "metadata", metadataStart);
+  } catch (error) {
+    pushStage(stageHistory, "metadata", metadataStart, "failed");
+    throw error;
+  }
+  const finalizeStart = safeNow(now);
+  const ingestMs = Math.max(0, Date.now() - startedMs);
+  const completedAt = safeNow(now);
+  pushStage(stageHistory, "finalize", finalizeStart);
+  return ingestRunArtifactSchema.parse({
+    ingest_run_id: buildIngestRunId(
+      repo.repo_full_name,
+      snapshot.snapshotId,
+      snapshot.manifest.manifest_signature
+    ),
+    repo_ref: repo.repo_full_name,
+    requested_ref: resolved.requested_ref,
+    resolved_ref: resolved.resolved_ref,
+    commit_sha: resolved.commit_sha,
+    snapshot_path: snapshot.snapshotPath,
+    snapshot_id: snapshot.snapshotId,
+    manifest_signature: snapshot.manifest.manifest_signature,
+    files_scanned: metadata.files_scanned,
+    idempotent_hit: snapshot.idempotentHit,
+    metadata,
+    trend_artifacts: trendArtifacts,
+    official_docs: officialDocsArtifacts,
+    created_at: startedAt,
+    completed_at: completedAt,
+    ingest_ms: ingestMs
+  });
+}
+
+// src/contracts/wiki-delivery.ts
+import { z as z2 } from "zod";
+var COMMIT_SHA_PATTERN = /^[a-f0-9]{7,40}$/;
+var REPO_FULL_NAME_PATTERN = /^[a-z0-9_.-]+\/[a-z0-9_.-]+$/;
+function normalizeAnchor(value) {
+  const anchor = value.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9가-힣-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+  return anchor;
+}
+var RequiredSectionTextSchema = z2.string().trim().min(1);
+var DeliveryProjectIdentitySchema = z2.object({
+  repoFullName: z2.string().trim().regex(REPO_FULL_NAME_PATTERN),
+  commitSha: z2.string().trim().regex(COMMIT_SHA_PATTERN),
+  ingestRunId: z2.string().trim().min(1).optional()
+}).strict();
+var DeliverySectionSchema = z2.object({
+  sectionId: RequiredSectionTextSchema,
+  heading: z2.string().trim().min(1).optional(),
+  anchor: z2.string().trim().min(1).optional(),
+  summary: RequiredSectionTextSchema,
+  deepDiveMarkdown: RequiredSectionTextSchema,
+  order: z2.number().int().min(0),
+  subsectionIds: z2.array(z2.string().trim().min(1)).min(1)
+}).strict().transform((section) => {
+  const heading = section.heading?.trim() ?? section.sectionId;
+  const normalizedAnchor = normalizeAnchor(section.anchor ?? section.sectionId);
+  return {
+    ...section,
+    heading,
+    anchor: normalizedAnchor.length > 0 ? normalizedAnchor : normalizeAnchor(section.sectionId),
+    subsectionIds: section.subsectionIds.map((subsectionId) => subsectionId.trim())
+  };
+});
+var DeliveryProvenanceSchema = z2.object({
+  generatedAt: z2.string().datetime(),
+  commitSha: z2.string().trim().regex(COMMIT_SHA_PATTERN),
+  counters: z2.object({
+    sectionCount: z2.number().int().min(1),
+    subsectionCount: z2.number().int().min(1),
+    claimCount: z2.number().int().min(0),
+    citationCount: z2.number().int().min(0)
+  }).strict(),
+  run: z2.object({
+    generationRunId: z2.string().trim().min(1),
+    ingestRunId: z2.string().trim().min(1).optional(),
+    modelId: z2.string().trim().min(1)
+  }).strict()
+}).strict();
+var DeliveryMetadataSchema = z2.object({
+  artifactType: z2.literal("wiki-delivery"),
+  sourceArtifactType: z2.literal("wiki-draft"),
+  contractVersion: z2.literal("out-01.v1"),
+  generatedAt: z2.string().datetime(),
+  sectionCount: z2.number().int().min(1),
+  subsectionCount: z2.number().int().min(1),
+  deterministicOrdering: z2.object({
+    sections: z2.literal("sectionId:asc"),
+    subsections: z2.literal("subsectionId:asc")
+  }).strict(),
+  provenance: DeliveryProvenanceSchema
+}).strict();
+var DeliveryWikiArtifactSchema = z2.object({
+  project: DeliveryProjectIdentitySchema,
+  sections: z2.array(DeliverySectionSchema).min(1),
+  metadata: DeliveryMetadataSchema
+}).strict().superRefine((value, ctx) => {
+  if (value.metadata.sectionCount !== value.sections.length) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "metadata.sectionCount must equal sections length",
+      path: ["metadata", "sectionCount"]
+    });
+  }
+  const subsectionCount = value.sections.reduce((count, section) => count + section.subsectionIds.length, 0);
+  if (value.metadata.subsectionCount !== subsectionCount) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "metadata.subsectionCount must equal subsectionIds aggregate",
+      path: ["metadata", "subsectionCount"]
+    });
+  }
+  if (value.metadata.generatedAt !== value.metadata.provenance.generatedAt) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "metadata.generatedAt must equal provenance.generatedAt",
+      path: ["metadata", "generatedAt"]
+    });
+  }
+  if (value.project.commitSha !== value.metadata.provenance.commitSha) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "provenance.commitSha must equal project.commitSha",
+      path: ["metadata", "provenance", "commitSha"]
+    });
+  }
+  if (value.metadata.provenance.counters.sectionCount !== value.metadata.sectionCount) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "provenance.counters.sectionCount must equal metadata.sectionCount",
+      path: ["metadata", "provenance", "counters", "sectionCount"]
+    });
+  }
+  if (value.metadata.provenance.counters.subsectionCount !== value.metadata.subsectionCount) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "provenance.counters.subsectionCount must equal metadata.subsectionCount",
+      path: ["metadata", "provenance", "counters", "subsectionCount"]
+    });
+  }
+  const sectionIds = /* @__PURE__ */ new Set();
+  const anchors = /* @__PURE__ */ new Set();
+  for (let index = 0; index < value.sections.length; index += 1) {
+    const section = value.sections[index];
+    if (section.order !== index) {
+      ctx.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: "sections must use contiguous deterministic order values starting at 0",
+        path: ["sections", index, "order"]
+      });
+    }
+    if (sectionIds.has(section.sectionId)) {
+      ctx.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: `duplicate sectionId: ${section.sectionId}`,
+        path: ["sections", index, "sectionId"]
+      });
+    }
+    sectionIds.add(section.sectionId);
+    if (anchors.has(section.anchor)) {
+      ctx.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: `duplicate anchor: ${section.anchor}`,
+        path: ["sections", index, "anchor"]
+      });
+    }
+    anchors.add(section.anchor);
+  }
+});
+
+// src/packaging/provenance.ts
+var DEFAULT_GENERATION_RUN_ID = "delivery-packaging";
+var DEFAULT_MODEL_ID = "unknown-model";
+function buildDeliveryProvenance(input) {
+  const subsectionCount = input.sections.reduce((count, section) => count + section.subsectionIds.length, 0);
+  return {
+    generatedAt: input.generatedAt,
+    commitSha: input.commitSha,
+    counters: {
+      sectionCount: input.sections.length,
+      subsectionCount,
+      claimCount: input.claimCount,
+      citationCount: input.citationCount
+    },
+    run: {
+      generationRunId: input.generationRunId?.trim() || DEFAULT_GENERATION_RUN_ID,
+      ingestRunId: input.ingestRunId?.trim() || void 0,
+      modelId: input.modelId?.trim() || DEFAULT_MODEL_ID
+    }
+  };
+}
+
+// src/packaging/adapter.ts
+var SECTION_SORT = "sectionId:asc";
+var SUBSECTION_SORT = "subsectionId:asc";
+function adaptAcceptedOutputToDelivery(acceptedOutput, options = {}) {
+  return adaptWikiDraftToDelivery(acceptedOutput.draft, {
+    ...options,
+    ingestRunId: acceptedOutput.ingest_run_id,
+    generationRunId: acceptedOutput.ingest_run_id
+  });
+}
+function adaptWikiDraftToDelivery(draft, options = {}) {
+  const sections = draft.sections.slice().sort((left, right) => compareByDeterministicId(left.sectionId, right.sectionId)).map((section, index) => {
+    const subsections = section.subsections.slice().sort((left, right) => compareByDeterministicId(left.subsectionId, right.subsectionId));
+    const summary = requireNonEmpty(section.summaryKo, `summaryKo:${section.sectionId}`);
+    const deepDiveMarkdown = buildDeepDiveMarkdown(subsections, section.sectionId);
+    const payload = {
+      sectionId: section.sectionId,
+      heading: section.titleKo,
+      anchor: section.sectionId,
+      summary,
+      deepDiveMarkdown,
+      order: index,
+      subsectionIds: subsections.map((subsection) => subsection.subsectionId)
+    };
+    return payload;
+  });
+  const subsectionCount = sections.reduce((count, section) => count + section.subsectionIds.length, 0);
+  const generatedAt = options.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const provenance = buildDeliveryProvenance({
+    sections,
+    commitSha: draft.commitSha,
+    generatedAt,
+    claimCount: draft.claims.length,
+    citationCount: draft.citations.length,
+    ingestRunId: options.ingestRunId,
+    generationRunId: options.generationRunId,
+    modelId: options.modelId
+  });
+  return DeliveryWikiArtifactSchema.parse({
+    project: {
+      repoFullName: draft.repoFullName,
+      commitSha: draft.commitSha,
+      ingestRunId: options.ingestRunId
+    },
+    sections,
+    metadata: {
+      artifactType: "wiki-delivery",
+      sourceArtifactType: draft.artifactType,
+      contractVersion: "out-01.v1",
+      generatedAt,
+      sectionCount: sections.length,
+      subsectionCount,
+      deterministicOrdering: {
+        sections: SECTION_SORT,
+        subsections: SUBSECTION_SORT
+      },
+      provenance
+    }
+  });
+}
+function buildDeepDiveMarkdown(subsections, sectionId) {
+  const blocks = subsections.map((subsection) => {
+    const title = requireNonEmpty(subsection.titleKo, `titleKo:${sectionId}:${subsection.subsectionId}`);
+    const body = requireNonEmpty(subsection.bodyKo, `bodyKo:${sectionId}:${subsection.subsectionId}`);
+    return `## ${title}
+
+${body}`;
+  });
+  return requireNonEmpty(blocks.join("\n\n"), `deepDiveMarkdown:${sectionId}`);
+}
+function compareByDeterministicId(left, right) {
+  return left.localeCompare(right, "en", { numeric: true, sensitivity: "base" });
+}
+function requireNonEmpty(value, field) {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new Error(`OUT-01 mapping violation: ${field} must be non-empty`);
+  }
+  return normalized;
+}
+
+// src/packaging/glossary.ts
+import { z as z3 } from "zod";
+var PLACEHOLDER_PATTERN = /^(?:n\/?a|na|none|null|tbd|todo|미정|없음|-|_)$/i;
+var KOREAN_ENGLISH_PAIR_PATTERN = /([가-힣][가-힣a-z0-9\s\-_/]{0,80}?)\s*\(\s*([a-z][a-z0-9\s\-_/]{1,80})\s*\)/gi;
+var ENGLISH_KOREAN_PAIR_PATTERN = /([a-z][a-z0-9\s\-_/]{1,80})\s*\(\s*([가-힣][가-힣a-z0-9\s\-_/]{0,80}?)\s*\)/gi;
+var GlossaryEntrySchema = z3.object({
+  termKo: z3.string().trim().min(1),
+  termEn: z3.string().trim().min(1),
+  definition: z3.string().trim().min(10)
+}).strict();
+function buildGlossaryFromAcceptedOutput(acceptedOutput) {
+  return buildGlossaryFromDraft(acceptedOutput.draft);
+}
+function buildGlossaryFromDraft(draft) {
+  const candidates = [];
+  for (const text of collectDraftText(draft)) {
+    candidates.push(...extractGlossaryCandidatesFromText(text));
+  }
+  return normalizeGlossaryEntries(candidates);
+}
+function normalizeGlossaryEntries(candidates) {
+  const canonicalEntries = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    const parsed = GlossaryEntrySchema.safeParse({
+      termKo: normalizeTermKo(candidate.termKo),
+      termEn: normalizeTermEn(candidate.termEn),
+      definition: normalizeWhitespace(candidate.definition)
+    });
+    if (!parsed.success) {
+      continue;
+    }
+    const normalized = parsed.data;
+    if (isPlaceholder(normalized.termKo) || isPlaceholder(normalized.termEn) || isPlaceholder(normalized.definition)) {
+      continue;
+    }
+    const canonicalKey = toCanonicalEn(normalized.termEn);
+    const existing = canonicalEntries.get(canonicalKey);
+    if (!existing) {
+      canonicalEntries.set(canonicalKey, normalized);
+      continue;
+    }
+    canonicalEntries.set(canonicalKey, {
+      termKo: pickLexicographicallyStable(existing.termKo, normalized.termKo),
+      termEn: pickLexicographicallyStable(existing.termEn, normalized.termEn),
+      definition: pickPreferredDefinition(existing.definition, normalized.definition)
+    });
+  }
+  return Array.from(canonicalEntries.values()).sort(compareGlossaryEntry);
+}
+function collectDraftText(draft) {
+  const texts = [draft.overviewKo];
+  for (const section of draft.sections) {
+    texts.push(section.titleKo, section.summaryKo);
+    for (const subsection of section.subsections) {
+      texts.push(subsection.titleKo, subsection.bodyKo);
+    }
+  }
+  for (const claim of draft.claims) {
+    texts.push(claim.statementKo);
+  }
+  for (const citation of draft.citations) {
+    if (citation.rationale) {
+      texts.push(citation.rationale);
+    }
+  }
+  return texts;
+}
+function extractGlossaryCandidatesFromText(text) {
+  const candidates = [];
+  const sentences = splitSentences(text);
+  for (const sentence of sentences) {
+    candidates.push(...extractPairMatches(sentence, KOREAN_ENGLISH_PAIR_PATTERN));
+    candidates.push(...extractPairMatches(sentence, ENGLISH_KOREAN_PAIR_PATTERN, true));
+  }
+  return candidates;
+}
+function extractPairMatches(sentence, pattern, reverse = false) {
+  const matches = [];
+  const regex = new RegExp(pattern.source, pattern.flags);
+  let match = regex.exec(sentence);
+  while (match) {
+    const left = normalizeWhitespace(match[1]);
+    const right = normalizeWhitespace(match[2]);
+    matches.push(
+      reverse ? { termKo: right, termEn: left, definition: sentence } : { termKo: left, termEn: right, definition: sentence }
+    );
+    match = regex.exec(sentence);
+  }
+  return matches;
+}
+function splitSentences(text) {
+  return text.split(/[\n\r]+|(?<=[.!?다])\s+/u).map((item) => normalizeWhitespace(item)).filter((item) => item.length > 0);
+}
+function toCanonicalEn(value) {
+  return value.toLowerCase().replace(/\s+/g, " ").replace(/[^a-z0-9 ]/g, "").trim();
+}
+function pickPreferredDefinition(current, incoming) {
+  if (incoming.length > current.length) {
+    return incoming;
+  }
+  if (incoming.length < current.length) {
+    return current;
+  }
+  return pickLexicographicallyStable(current, incoming);
+}
+function pickLexicographicallyStable(left, right) {
+  return left.localeCompare(right, "en", { sensitivity: "base" }) <= 0 ? left : right;
+}
+function compareGlossaryEntry(left, right) {
+  const byEnglish = left.termEn.localeCompare(right.termEn, "en", {
+    sensitivity: "base",
+    numeric: true
+  });
+  if (byEnglish !== 0) {
+    return byEnglish;
+  }
+  return left.termKo.localeCompare(right.termKo, "ko", {
+    sensitivity: "base",
+    numeric: true
+  });
+}
+function normalizeWhitespace(value) {
+  return (value ?? "").replace(/\s+/g, " ").trim();
+}
+function normalizeTermKo(value) {
+  const normalized = normalizeWhitespace(value);
+  if (normalized.length === 0) {
+    return normalized;
+  }
+  let tokens = normalized.split(" ").filter(Boolean);
+  if (tokens.length > 3) {
+    tokens = tokens.slice(tokens.length - 3);
+  }
+  while (tokens.length > 0 && /^(?:와|과|및|그리고|이|그|해당)$/u.test(tokens[0])) {
+    tokens = tokens.slice(1);
+  }
+  if (tokens.length === 0) {
+    return "";
+  }
+  const lastIndex = tokens.length - 1;
+  tokens[lastIndex] = tokens[lastIndex].replace(/(은|는|이|가|을|를|와|과|의|에|에서|로|으로)$/u, "");
+  return tokens.join(" ").trim();
+}
+function normalizeTermEn(value) {
+  return normalizeWhitespace(value).replace(/[.,;:]+$/g, "");
+}
+function isPlaceholder(value) {
+  return PLACEHOLDER_PATTERN.test(value.trim());
+}
+
+// src/packaging/validate.ts
+import { z as z5 } from "zod";
+
+// src/contracts/wiki-generation.ts
+import { z as z4 } from "zod";
+var COMMIT_SHA_PATTERN2 = /^[a-f0-9]{7,40}$/;
+var REPO_PATH_PATTERN = /^(?!\/)(?!.*\.\.)(?!.*\s$).+/;
+var LineRangeSchema = z4.object({
+  start: z4.number().int().min(1),
+  end: z4.number().int().min(1)
+}).superRefine((value, ctx) => {
+  if (value.end < value.start) {
+    ctx.addIssue({
+      code: z4.ZodIssueCode.custom,
+      message: "line range end must be greater than or equal to start",
+      path: ["end"]
+    });
+  }
+});
+var CitationSchema = z4.object({
+  citationId: z4.string().min(1),
+  evidenceId: z4.string().min(1),
+  repoPath: z4.string().regex(REPO_PATH_PATTERN),
+  lineRange: LineRangeSchema,
+  commitSha: z4.string().regex(COMMIT_SHA_PATTERN2),
+  permalink: z4.string().url().optional(),
+  rationale: z4.string().min(1).optional()
+}).strict();
+var ClaimSchema = z4.object({
+  claimId: z4.string().min(1),
+  sectionId: z4.string().min(1),
+  subsectionId: z4.string().min(1),
+  statementKo: z4.string().min(20),
+  citationIds: z4.array(z4.string().min(1)).min(1)
+}).strict();
+var EvidenceChunkSchema = z4.object({
+  evidenceId: z4.string().min(1),
+  repoPath: z4.string().regex(REPO_PATH_PATTERN),
+  lineRange: LineRangeSchema,
+  snippet: z4.string().min(1),
+  language: z4.string().min(1).optional(),
+  symbol: z4.string().min(1).optional(),
+  lexicalScore: z4.number().min(0).max(1),
+  semanticScore: z4.number().min(0).max(1)
+}).strict();
+var SectionSubsectionPlanSchema = z4.object({
+  sectionId: z4.string().min(1),
+  subsectionId: z4.string().min(1),
+  titleKo: z4.string().min(3),
+  objectiveKo: z4.string().min(10),
+  targetEvidenceKinds: z4.array(z4.enum(["code", "config", "tests", "docs"])).min(1),
+  targetCharacterCount: z4.number().int().min(700)
+}).strict();
+var SectionPlanSectionSchema = z4.object({
+  sectionId: z4.string().min(1),
+  titleKo: z4.string().min(3),
+  summaryKo: z4.string().min(10),
+  subsections: z4.array(SectionSubsectionPlanSchema).min(3)
+}).strict();
+var SectionCrossReferenceSchema = z4.object({
+  fromSectionId: z4.string().min(1),
+  toSectionId: z4.string().min(1),
+  relation: z4.string().min(3)
+}).strict();
+var SectionPlanSchema = z4.object({
+  artifactType: z4.literal("section-plan"),
+  repoFullName: z4.string().regex(/^[a-z0-9_.-]+\/[a-z0-9_.-]+$/),
+  commitSha: z4.string().regex(COMMIT_SHA_PATTERN2),
+  generatedAt: z4.string().datetime(),
+  overviewKo: z4.string().min(30),
+  sections: z4.array(SectionPlanSectionSchema).min(6),
+  crossReferences: z4.array(SectionCrossReferenceSchema)
+}).strict().superRefine((value, ctx) => {
+  const sectionIds = /* @__PURE__ */ new Set();
+  const subsectionIds = /* @__PURE__ */ new Set();
+  for (const section of value.sections) {
+    if (sectionIds.has(section.sectionId)) {
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: `duplicate sectionId: ${section.sectionId}`,
+        path: ["sections"]
+      });
+    }
+    sectionIds.add(section.sectionId);
+    for (const subsection of section.subsections) {
+      if (subsection.sectionId !== section.sectionId) {
+        ctx.addIssue({
+          code: z4.ZodIssueCode.custom,
+          message: "subsection.sectionId must match parent sectionId",
+          path: ["sections"]
+        });
+      }
+      const key = `${subsection.sectionId}:${subsection.subsectionId}`;
+      if (subsectionIds.has(key)) {
+        ctx.addIssue({
+          code: z4.ZodIssueCode.custom,
+          message: `duplicate subsection key: ${key}`,
+          path: ["sections"]
+        });
+      }
+      subsectionIds.add(key);
+    }
+  }
+  for (const reference of value.crossReferences) {
+    if (!sectionIds.has(reference.fromSectionId) || !sectionIds.has(reference.toSectionId)) {
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: "cross reference must target existing section ids",
+        path: ["crossReferences"]
+      });
+    }
+  }
+});
+var DraftSubsectionSchema = z4.object({
+  sectionId: z4.string().min(1),
+  subsectionId: z4.string().min(1),
+  titleKo: z4.string().min(3),
+  bodyKo: z4.string().min(80)
+}).strict();
+var DraftSectionSchema = z4.object({
+  sectionId: z4.string().min(1),
+  titleKo: z4.string().min(3),
+  summaryKo: z4.string().min(20),
+  subsections: z4.array(DraftSubsectionSchema).min(3)
+}).strict();
+var SourceDocSchema = z4.object({
+  sourceId: z4.string().min(1),
+  path: z4.string().regex(REPO_PATH_PATTERN)
+}).strict();
+var TrendFactSchema = z4.object({
+  factId: z4.string().min(1),
+  category: z4.string().min(1),
+  summaryKo: z4.string().min(10)
+}).strict();
+var GroundingIssueSchema = z4.object({
+  code: z4.enum([
+    "MISSING_CITATION",
+    "INVALID_PATH",
+    "INVALID_LINE_RANGE",
+    "UNRESOLVABLE_EVIDENCE",
+    "SEMANTIC_MISMATCH",
+    "LOW_SIGNAL_CITATION",
+    "ANTI_TEMPLATE",
+    "DUPLICATE_GENERIC_CITATION",
+    "UNKNOWN"
+  ]),
+  message: z4.string().min(1),
+  claimId: z4.string().min(1).optional(),
+  citationId: z4.string().min(1).optional()
+}).strict();
+var TerminologyDiagnosticsSchema = z4.object({
+  consistencyScore: z4.number().min(0).max(1),
+  untranslatedTokenRatio: z4.number().min(0).max(1),
+  analyzedTokenCount: z4.number().int().min(0),
+  notes: z4.array(z4.string().min(1))
+}).strict();
+var QualityScorecardSchema = z4.object({
+  semanticFaithfulness: z4.number().min(0).max(1),
+  conceptualDepth: z4.number().min(0).max(1),
+  operationalClarity: z4.number().min(0).max(1),
+  citationQuality: z4.number().min(0).max(1),
+  novelty: z4.number().min(0).max(1)
+}).strict();
+var GroundingReportSchema = z4.object({
+  artifactType: z4.literal("grounding-report"),
+  gateId: z4.enum(["GND-01", "GND-03", "GND-04"]),
+  checkedAt: z4.string().datetime(),
+  passed: z4.boolean(),
+  totalClaims: z4.number().int().min(0),
+  claimsWithCitations: z4.number().int().min(0),
+  citationCoverage: z4.number().min(0).max(1),
+  issues: z4.array(GroundingIssueSchema),
+  diagnostics: TerminologyDiagnosticsSchema.optional()
+}).strict().superRefine((value, ctx) => {
+  if (value.claimsWithCitations > value.totalClaims) {
+    ctx.addIssue({
+      code: z4.ZodIssueCode.custom,
+      message: "claimsWithCitations cannot exceed totalClaims",
+      path: ["claimsWithCitations"]
+    });
+  }
+  if (value.totalClaims === 0 && value.citationCoverage !== 0) {
+    ctx.addIssue({
+      code: z4.ZodIssueCode.custom,
+      message: "citationCoverage must be 0 when totalClaims is 0",
+      path: ["citationCoverage"]
+    });
+  }
+  if (value.totalClaims > 0) {
+    const expected = Number((value.claimsWithCitations / value.totalClaims).toFixed(6));
+    const actual = Number(value.citationCoverage.toFixed(6));
+    if (expected !== actual) {
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: "citationCoverage must match claimsWithCitations / totalClaims",
+        path: ["citationCoverage"]
+      });
+    }
+  }
+});
+var WikiDraftArtifactSchema = z4.object({
+  artifactType: z4.literal("wiki-draft"),
+  repoFullName: z4.string().regex(/^[a-z0-9_.-]+\/[a-z0-9_.-]+$/),
+  commitSha: z4.string().regex(COMMIT_SHA_PATTERN2),
+  generatedAt: z4.string().datetime(),
+  overviewKo: z4.string().min(50),
+  sections: z4.array(DraftSectionSchema).min(6),
+  sourceDocs: z4.array(SourceDocSchema).min(1),
+  trendFacts: z4.array(TrendFactSchema).optional(),
+  claims: z4.array(ClaimSchema).min(1).optional(),
+  citations: z4.array(CitationSchema).min(1).optional(),
+  groundingReport: GroundingReportSchema.optional()
+}).strict().superRefine((value, ctx) => {
+  const sectionIds = new Set(value.sections.map((section) => section.sectionId));
+  const subsectionIds = /* @__PURE__ */ new Set();
+  for (const section of value.sections) {
+    for (const subsection of section.subsections) {
+      if (subsection.sectionId !== section.sectionId) {
+        ctx.addIssue({
+          code: z4.ZodIssueCode.custom,
+          message: "draft subsection sectionId must match parent sectionId",
+          path: ["sections"]
+        });
+      }
+      subsectionIds.add(`${subsection.sectionId}:${subsection.subsectionId}`);
+    }
+  }
+  const citations = value.citations ?? [];
+  const claims = value.claims ?? [];
+  const citationIds = /* @__PURE__ */ new Set();
+  for (const citation of citations) {
+    if (citationIds.has(citation.citationId)) {
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: `duplicate citationId: ${citation.citationId}`,
+        path: ["citations"]
+      });
+    }
+    citationIds.add(citation.citationId);
+  }
+  for (const claim of claims) {
+    if (!sectionIds.has(claim.sectionId)) {
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: `claim references unknown sectionId: ${claim.sectionId}`,
+        path: ["claims"]
+      });
+    }
+    const subsectionKey = `${claim.sectionId}:${claim.subsectionId}`;
+    if (!subsectionIds.has(subsectionKey)) {
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: `claim references unknown subsection: ${subsectionKey}`,
+        path: ["claims"]
+      });
+    }
+    for (const citationId of claim.citationIds) {
+      if (!citationIds.has(citationId)) {
+        ctx.addIssue({
+          code: z4.ZodIssueCode.custom,
+          message: `claim references unknown citationId: ${citationId}`,
+          path: ["claims"]
+        });
+      }
+    }
+  }
+});
+
+// src/packaging/validate.ts
+var SOURCE_ARTIFACT_TYPE = "wiki-draft";
+var CONTRACT_VERSION = "out-04.v1";
+var DeliverySourceSchema = z5.object({
+  ingestRunId: z5.string().trim().min(1),
+  sourceDocCount: z5.number().int().min(0),
+  trendFactCount: z5.number().int().min(0)
+}).strict();
+var DeliveryPackagingMetadataSchema = z5.object({
+  generatedAt: z5.string().datetime(),
+  deterministicOrdering: z5.object({
+    sections: z5.literal("sectionId:asc"),
+    subsections: z5.literal("subsectionId:asc"),
+    glossary: z5.literal("termEn:asc,termKo:asc")
+  }).strict(),
+  sourceArtifactType: z5.literal(SOURCE_ARTIFACT_TYPE),
+  qualityScorecard: QualityScorecardSchema
+}).strict();
+var DeliveryArtifactEnvelopeSchema = z5.object({
+  contractVersion: z5.literal(CONTRACT_VERSION),
+  project: z5.object({
+    repoRef: z5.string().trim().regex(/^[a-z0-9_.-]+\/[a-z0-9_.-]+$/),
+    commitSha: z5.string().trim().regex(/^[a-f0-9]{7,40}$/),
+    ingestRunId: z5.string().trim().min(1)
+  }).strict(),
+  sections: z5.array(DeliverySectionSchema).min(1),
+  provenance: DeliveryProvenanceSchema,
+  glossary: z5.array(GlossaryEntrySchema).min(1),
+  source: DeliverySourceSchema,
+  metadata: DeliveryPackagingMetadataSchema
+}).strict().superRefine((value, ctx) => {
+  const parsedDelivery = DeliveryWikiArtifactSchema.safeParse({
+    project: {
+      repoFullName: value.project.repoRef,
+      commitSha: value.project.commitSha,
+      ingestRunId: value.project.ingestRunId
+    },
+    sections: value.sections,
+    metadata: {
+      artifactType: "wiki-delivery",
+      sourceArtifactType: value.metadata.sourceArtifactType,
+      contractVersion: "out-01.v1",
+      generatedAt: value.metadata.generatedAt,
+      sectionCount: value.sections.length,
+      subsectionCount: value.sections.reduce((count, section) => count + section.subsectionIds.length, 0),
+      deterministicOrdering: {
+        sections: value.metadata.deterministicOrdering.sections,
+        subsections: value.metadata.deterministicOrdering.subsections
+      },
+      provenance: value.provenance
+    }
+  });
+  if (!parsedDelivery.success) {
+    for (const issue of parsedDelivery.error.issues) {
+      ctx.addIssue({
+        code: z5.ZodIssueCode.custom,
+        message: issue.message,
+        path: ["sections", ...issue.path]
+      });
+    }
+  }
+  if (value.project.commitSha !== value.provenance.commitSha) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      message: "provenance.commitSha must equal project.commitSha",
+      path: ["provenance", "commitSha"]
+    });
+  }
+  if (value.metadata.generatedAt !== value.provenance.generatedAt) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      message: "metadata.generatedAt must equal provenance.generatedAt",
+      path: ["metadata", "generatedAt"]
+    });
+  }
+  if (value.source.ingestRunId !== value.project.ingestRunId) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      message: "source.ingestRunId must equal project.ingestRunId",
+      path: ["source", "ingestRunId"]
+    });
+  }
+  const duplicateTerms = /* @__PURE__ */ new Set();
+  const canonicalTerms = /* @__PURE__ */ new Set();
+  for (const entry of value.glossary) {
+    const canonical = entry.termEn.toLowerCase().replace(/\s+/g, " ").trim();
+    if (canonicalTerms.has(canonical)) {
+      duplicateTerms.add(canonical);
+    }
+    canonicalTerms.add(canonical);
+  }
+  if (duplicateTerms.size > 0) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      message: `glossary contains duplicate canonical termEn keys: ${Array.from(duplicateTerms).join(", ")}`,
+      path: ["glossary"]
+    });
+  }
+  if (!isGlossaryDeterministic(value.glossary)) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      message: "glossary must be sorted deterministically by termEn then termKo",
+      path: ["glossary"]
+    });
+  }
+});
+function validateDeliveryEnvelope(input) {
+  const parsed = DeliveryArtifactEnvelopeSchema.safeParse(input);
+  if (parsed.success) {
+    return {
+      ok: true,
+      issues: [],
+      envelope: parsed.data
+    };
+  }
+  return {
+    ok: false,
+    issues: parsed.error.issues.map((issue) => ({
+      path: issue.path.length > 0 ? issue.path.join(".") : "<root>",
+      message: issue.message
+    }))
+  };
+}
+function assertValidDeliveryEnvelope(input) {
+  const result = validateDeliveryEnvelope(input);
+  if (result.ok && result.envelope) {
+    return result.envelope;
+  }
+  const reason = (result.issues || []).map((issue, index) => `${index + 1}) ${issue.path}: ${issue.message}`).join("; ");
+  throw new Error(`OUT-04 validation failed: ${reason || "unknown validation error"}`);
+}
+function isGlossaryDeterministic(glossary) {
+  for (let index = 1; index < glossary.length; index += 1) {
+    const previous = glossary[index - 1];
+    const current = glossary[index];
+    const byEnglish = previous.termEn.localeCompare(current.termEn, "en", {
+      sensitivity: "base",
+      numeric: true
+    });
+    if (byEnglish > 0) {
+      return false;
+    }
+    if (byEnglish === 0) {
+      const byKorean = previous.termKo.localeCompare(current.termKo, "ko", {
+        sensitivity: "base",
+        numeric: true
+      });
+      if (byKorean > 0) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+// src/quality/scorecard.ts
+var LOW_SIGNAL_PATH_PATTERN = /(\/|^)(readme|license|changelog)(\.|$)|^docs\/vendor\//i;
+function buildQualityScorecard(acceptedOutput) {
+  const draft = acceptedOutput.draft;
+  const claims = draft.claims ?? [];
+  const citations = draft.citations ?? [];
+  const trendFacts = draft.trendFacts ?? [];
+  const subsectionEntries = draft.sections.flatMap(
+    (section) => section.subsections.map((subsection) => ({
+      sectionId: section.sectionId,
+      subsectionId: subsection.subsectionId,
+      bodyKo: subsection.bodyKo
+    }))
+  );
+  const totalClaims = Math.max(1, claims.length);
+  const totalCitations = Math.max(1, citations.length);
+  const totalSubsections = Math.max(1, subsectionEntries.length);
+  const readabilityScore = calculateReadabilityScore(subsectionEntries.map((entry) => entry.bodyKo));
+  const semanticFaithfulness = readabilityScore;
+  const averageBodyChars = subsectionEntries.reduce((sum, subsection) => sum + subsection.bodyKo.length, 0) / totalSubsections;
+  const conceptualDepth = clamp01(averageBodyChars / 3200);
+  const citationsById = new Map(citations.map((citation) => [citation.citationId, citation]));
+  const claimsBySubsection = /* @__PURE__ */ new Map();
+  for (const claim of claims) {
+    const key = `${claim.sectionId}:${claim.subsectionId}`;
+    const list = claimsBySubsection.get(key) ?? [];
+    list.push(claim);
+    claimsBySubsection.set(key, list);
+  }
+  let anchoredSubsectionCount = 0;
+  for (const subsection of subsectionEntries) {
+    const key = `${subsection.sectionId}:${subsection.subsectionId}`;
+    const claims2 = claimsBySubsection.get(key) ?? [];
+    const citedPaths = claims2.flatMap((claim) => claim.citationIds).map((citationId) => citationsById.get(citationId)?.repoPath).filter((repoPath) => Boolean(repoPath));
+    if (citedPaths.some((repoPath) => subsection.bodyKo.includes(repoPath))) {
+      anchoredSubsectionCount += 1;
+    }
+  }
+  const operationalClarity = clamp01(anchoredSubsectionCount / totalSubsections);
+  const lowSignalCitationCount = citations.filter(
+    (citation) => LOW_SIGNAL_PATH_PATTERN.test(citation.repoPath)
+  ).length;
+  const trendMentionCount = subsectionEntries.filter((entry) => /트렌드|릴리스|release|tag|changelog/iu.test(entry.bodyKo)).length;
+  const trendCoverage = clamp01(
+    (trendFacts.length > 0 ? 0.5 : 0) + trendMentionCount / totalSubsections * 0.5
+  );
+  const citationQuality = clamp01(1 - lowSignalCitationCount / totalCitations);
+  const canonicalBodies = subsectionEntries.map(
+    (subsection) => subsection.bodyKo.normalize("NFKC").replace(/\s+/g, " ").replace(/[.,:;!?()\[\]{}"'`-]/g, "").trim()
+  );
+  const uniqueBodyRatio = new Set(canonicalBodies).size / totalSubsections;
+  const novelty = clamp01(uniqueBodyRatio * 0.7 + trendCoverage * 0.3);
+  return QualityScorecardSchema.parse({
+    semanticFaithfulness: round4(semanticFaithfulness),
+    conceptualDepth: round4(conceptualDepth),
+    operationalClarity: round4(operationalClarity),
+    citationQuality: round4((citationQuality + trendCoverage) / 2),
+    novelty: round4(novelty)
+  });
+}
+function calculateReadabilityScore(bodies) {
+  if (bodies.length === 0) {
+    return 0;
+  }
+  const scores = bodies.map((body) => {
+    const normalized = body.replace(/\s+/g, " ").trim();
+    if (normalized.length === 0) {
+      return 0;
+    }
+    const sentenceCount = Math.max(1, normalized.split(/[.!?]|다\s+/u).filter((part) => part.trim().length > 0).length);
+    const averageSentenceLength = normalized.length / sentenceCount;
+    const sentenceBandScore = clamp01(1 - Math.abs(averageSentenceLength - 95) / 95);
+    const hasPathLikeToken = /[a-z0-9_.-]+\/[a-z0-9_.-]+/i.test(normalized) ? 1 : 0.5;
+    return clamp01(sentenceBandScore * 0.7 + hasPathLikeToken * 0.3);
+  });
+  return clamp01(scores.reduce((sum, score) => sum + score, 0) / scores.length);
+}
+function clamp01(value) {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  if (value < 0) {
+    return 0;
+  }
+  if (value > 1) {
+    return 1;
+  }
+  return value;
+}
+function round4(value) {
+  return Number(value.toFixed(4));
+}
+
+// src/orchestration/package-delivery.ts
+function detectBodyKoRepetitionInBodies(bodies) {
+  const errors = [];
+  for (const sub of bodies) {
+    const sentences = splitKoreanSentences(sub.bodyKo).filter((s) => s.length > 50);
+    const seenSentences = /* @__PURE__ */ new Set();
+    for (const sentence of sentences) {
+      if (seenSentences.has(sentence)) {
+        errors.push(
+          `${sub.subsectionId} (${sub.sectionId}): repeated sentence detected \u2014 "${sentence.slice(0, 60)}..."`
+        );
+        break;
+      }
+      seenSentences.add(sentence);
+    }
+    const repeatedChunk = findRepeatedChunkWithinText(sub.bodyKo, {
+      windowChars: 240,
+      strideChars: 40,
+      minimumRepeatChars: 200
+    });
+    if (repeatedChunk) {
+      errors.push(
+        `${sub.subsectionId} (${sub.sectionId}): repeated long chunk detected \u2014 "${repeatedChunk.slice(0, 60)}..."`
+      );
+    }
+  }
+  return errors;
+}
+function detectBodyKoRepetition(acceptedOutput) {
+  const bodies = [];
+  for (const section of acceptedOutput.draft.sections) {
+    for (const sub of section.subsections) {
+      bodies.push({ sectionId: section.sectionId, subsectionId: sub.subsectionId, bodyKo: sub.bodyKo });
+    }
+  }
+  return detectBodyKoRepetitionInBodies(bodies);
+}
+function detectCrossSubsectionRepetitionInBodies(bodies) {
+  const occurrencesByHash = /* @__PURE__ */ new Map();
+  const bodyEntries = [];
+  for (const sub of bodies) {
+    bodyEntries.push({ sectionId: sub.sectionId, subsectionId: sub.subsectionId, body: sub.bodyKo });
+    const chunks = chunkText(sub.bodyKo, { windowChars: 320, strideChars: 60 });
+    for (const chunk of chunks) {
+      if (chunk.length < 300) {
+        continue;
+      }
+      const canonical = normalizeForRepetition(chunk);
+      if (canonical.length < 280) {
+        continue;
+      }
+      const hash = fnv1a32(canonical);
+      const list = occurrencesByHash.get(hash) ?? [];
+      list.push({ sectionId: sub.sectionId, subsectionId: sub.subsectionId, chunk: canonical });
+      occurrencesByHash.set(hash, list);
+    }
+  }
+  const errors = [];
+  for (const list of occurrencesByHash.values()) {
+    if (list.length < 2) {
+      continue;
+    }
+    const grouped = /* @__PURE__ */ new Map();
+    for (const item of list) {
+      const key = item.chunk;
+      const bucket = grouped.get(key) ?? [];
+      bucket.push(item);
+      grouped.set(key, bucket);
+    }
+    for (const bucket of grouped.values()) {
+      if (bucket.length < 2) {
+        continue;
+      }
+      const uniqueSubsections = /* @__PURE__ */ new Map();
+      for (const occ of bucket) {
+        uniqueSubsections.set(`${occ.sectionId}:${occ.subsectionId}`, occ);
+      }
+      if (uniqueSubsections.size < 2) {
+        continue;
+      }
+      const occurrences = Array.from(uniqueSubsections.values()).slice(0, 4);
+      const locations = occurrences.map((o) => `${o.subsectionId} (${o.sectionId})`).join(", ");
+      const excerpt = bucket[0].chunk.slice(0, 80);
+      errors.push(
+        `cross-subsection repeated chunk detected in: ${locations} \u2014 "${excerpt}..."`
+      );
+    }
+  }
+  const shingleSize = 80;
+  const shingleStep = 40;
+  const minimumCharsForSimilarity = 1800;
+  const shingleSets = bodyEntries.map((item) => ({
+    ...item,
+    shingles: buildShingleSet(item.body, { shingleSize, step: shingleStep, minimumChars: minimumCharsForSimilarity })
+  }));
+  for (let i = 0; i < shingleSets.length; i += 1) {
+    for (let j = i + 1; j < shingleSets.length; j += 1) {
+      const left = shingleSets[i];
+      const right = shingleSets[j];
+      if (left.shingles.size === 0 || right.shingles.size === 0) {
+        continue;
+      }
+      const similarity = jaccard(left.shingles, right.shingles);
+      if (similarity >= 0.9) {
+        errors.push(
+          `near-duplicate bodyKo detected (${similarity.toFixed(3)} Jaccard): ${left.subsectionId} (${left.sectionId}) \u2194 ${right.subsectionId} (${right.sectionId})`
+        );
+      }
+    }
+  }
+  return errors;
+}
+function detectCrossSubsectionBodyKoRepetition(acceptedOutput) {
+  const bodies = [];
+  for (const section of acceptedOutput.draft.sections) {
+    for (const sub of section.subsections) {
+      bodies.push({ sectionId: section.sectionId, subsectionId: sub.subsectionId, bodyKo: sub.bodyKo });
+    }
+  }
+  return detectCrossSubsectionRepetitionInBodies(bodies);
+}
+function splitKoreanSentences(text) {
+  return normalizeForRepetition(text).split(/[\n\r]+|(?<=[.!?]|다)\s+/u).map((item) => item.trim()).filter((item) => item.length > 0);
+}
+function normalizeForRepetition(text) {
+  return (text ?? "").normalize("NFKC").replace(/\r\n/g, "\n").replace(/\s+/g, " ").replace(/\[deterministic-prompt-hash:[^\]]+\]/g, "").replace(/\[reference:[^\]]+\]/g, "").trim();
+}
+function chunkText(text, input) {
+  const normalized = normalizeForRepetition(text);
+  const windowChars = Math.max(50, input.windowChars);
+  const strideChars = Math.max(1, input.strideChars);
+  if (normalized.length < windowChars) {
+    return [];
+  }
+  const chunks = [];
+  for (let offset = 0; offset + windowChars <= normalized.length; offset += strideChars) {
+    chunks.push(normalized.slice(offset, offset + windowChars));
+  }
+  return chunks;
+}
+function findRepeatedChunkWithinText(text, input) {
+  const chunks = chunkText(text, { windowChars: input.windowChars, strideChars: input.strideChars });
+  if (chunks.length === 0) {
+    return null;
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const canonical = normalizeForRepetition(chunk);
+    if (canonical.length < input.minimumRepeatChars) {
+      continue;
+    }
+    const hash = fnv1a32(canonical);
+    const count = (seen.get(hash) ?? 0) + 1;
+    if (count > 1) {
+      return canonical;
+    }
+    seen.set(hash, count);
+  }
+  return null;
+}
+function buildShingleSet(text, input) {
+  const normalized = normalizeForRepetition(text);
+  if (normalized.length < input.minimumChars) {
+    return /* @__PURE__ */ new Set();
+  }
+  const shingleSize = Math.max(20, input.shingleSize);
+  const step = Math.max(1, input.step);
+  if (normalized.length < shingleSize) {
+    return /* @__PURE__ */ new Set();
+  }
+  const set = /* @__PURE__ */ new Set();
+  for (let offset = 0; offset + shingleSize <= normalized.length; offset += step) {
+    const shingle = normalized.slice(offset, offset + shingleSize);
+    set.add(fnv1a32(shingle));
+  }
+  return set;
+}
+function jaccard(left, right) {
+  const [small, large] = left.size <= right.size ? [left, right] : [right, left];
+  let intersection = 0;
+  for (const token of small) {
+    if (large.has(token)) {
+      intersection += 1;
+    }
+  }
+  const union = left.size + right.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+function fnv1a32(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+var DELIVERY_CONTRACT_VERSION = "out-04.v1";
+function packageAcceptedOutputsForDelivery(acceptedOutputs, options = {}) {
+  const sortedOutputs = acceptedOutputs.slice().sort((left, right) => compareAcceptedOutputs(left, right));
+  const artifacts = [];
+  const failures = [];
+  for (const acceptedOutput of sortedOutputs) {
+    try {
+      const qualityGateLevel = options.qualityGateLevel ?? "standard";
+      const normalizedAcceptedOutput = normalizeAcceptedOutputForPackaging(acceptedOutput);
+      const legacyCitationSourcePathCount = new Set(
+        normalizedAcceptedOutput.draft.citations.map((citation) => citation.repoPath)
+      ).size;
+      const sourceDocCount = normalizedAcceptedOutput.source_doc_count ?? normalizedAcceptedOutput.draft.sourceDocs?.length ?? legacyCitationSourcePathCount;
+      const trendFactCount = normalizedAcceptedOutput.trend_fact_count ?? normalizedAcceptedOutput.draft.trendFacts?.length ?? 0;
+      const repetitionErrors = detectBodyKoRepetition(normalizedAcceptedOutput);
+      if (repetitionErrors.length > 0) {
+        throw new Error(
+          `OUT-04 validation failed: bodyKo repetition detected (${repetitionErrors.length} subsection(s)):
+` + repetitionErrors.map((e) => `  - ${e}`).join("\n") + "\n  Do not repeat sentences to pad character count. Write unique content for each subsection."
+        );
+      }
+      const crossRepetitionErrors = detectCrossSubsectionBodyKoRepetition(normalizedAcceptedOutput);
+      if (crossRepetitionErrors.length > 0) {
+        throw new Error(
+          `OUT-04 validation failed: cross-subsection bodyKo repetition detected (${crossRepetitionErrors.length} finding(s)):
+` + crossRepetitionErrors.map((e) => `  - ${e}`).join("\n") + "\n  Do not paste the same long padding block into multiple subsections."
+        );
+      }
+      if (qualityGateLevel === "strict" && sourceDocCount <= 0) {
+        throw new Error("strict quality gate failed: source_doc_count must be greater than 0");
+      }
+      const qualityScorecard = buildQualityScorecard(normalizedAcceptedOutput);
+      const delivery = adaptAcceptedOutputToDelivery(normalizedAcceptedOutput, {
+        generatedAt: options.generatedAt,
+        modelId: options.modelId
+      });
+      const envelope = assertValidDeliveryEnvelope({
+        contractVersion: DELIVERY_CONTRACT_VERSION,
+        project: {
+          repoRef: acceptedOutput.repo_ref,
+          commitSha: acceptedOutput.commit_sha,
+          ingestRunId: acceptedOutput.ingest_run_id
+        },
+        sections: delivery.sections,
+        provenance: delivery.metadata.provenance,
+        glossary: buildGlossaryFromAcceptedOutput(normalizedAcceptedOutput),
+        source: {
+          ingestRunId: normalizedAcceptedOutput.ingest_run_id,
+          sourceDocCount,
+          trendFactCount
+        },
+        metadata: {
+          generatedAt: delivery.metadata.generatedAt,
+          deterministicOrdering: {
+            sections: delivery.metadata.deterministicOrdering.sections,
+            subsections: delivery.metadata.deterministicOrdering.subsections,
+            glossary: "termEn:asc,termKo:asc"
+          },
+          sourceArtifactType: delivery.metadata.sourceArtifactType,
+          qualityScorecard
+        }
+      });
+      artifacts.push(envelope);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failures.push(`${acceptedOutput.repo_ref}@${acceptedOutput.commit_sha.slice(0, 12)}: ${message}`);
+    }
+  }
+  if (failures.length > 0) {
+    throw new Error(
+      `OUT-04 packaging blocked (${failures.length}/${sortedOutputs.length}): ${failures.join(" | ")}`
+    );
+  }
+  return {
+    artifacts,
+    summary: {
+      attempted: sortedOutputs.length,
+      packaged: artifacts.length,
+      blocked: sortedOutputs.length - artifacts.length
+    }
+  };
+}
+function normalizeAcceptedOutputForPackaging(acceptedOutput) {
+  return {
+    ...acceptedOutput,
+    draft: {
+      ...acceptedOutput.draft,
+      claims: acceptedOutput.draft.claims ?? [],
+      citations: acceptedOutput.draft.citations ?? [],
+      trendFacts: acceptedOutput.draft.trendFacts ?? []
+    }
+  };
+}
+function compareAcceptedOutputs(left, right) {
+  const leftKey = `${left.repo_ref.toLowerCase()}|${left.commit_sha.toLowerCase()}|${left.ingest_run_id}`;
+  const rightKey = `${right.repo_ref.toLowerCase()}|${right.commit_sha.toLowerCase()}|${right.ingest_run_id}`;
+  return leftKey.localeCompare(rightKey, "en", { sensitivity: "base", numeric: true });
+}
+
+// src/freshness/detect.ts
+import { Octokit as Octokit2 } from "@octokit/rest";
+
+// src/contracts/wiki-freshness.ts
+import { z as z6 } from "zod";
+var COMMIT_SHA_PATTERN3 = /^[a-f0-9]{7,40}$/;
+var REPO_REF_PATTERN = /^[a-z0-9_.-]+\/[a-z0-9_.-]+$/;
+var REPO_PATH_PATTERN2 = /^(?!\/)(?!.*\.\.)(?!.*\s$).+/;
+var FreshnessRepoRefSchema = z6.string().trim().regex(REPO_REF_PATTERN);
+var FreshnessSectionEvidenceSchema = z6.object({
+  sectionId: z6.string().trim().min(1),
+  repoPaths: z6.array(z6.string().trim().regex(REPO_PATH_PATTERN2)).min(1)
+}).strict();
+var FreshnessBaselineSchema = z6.object({
+  repo_ref: FreshnessRepoRefSchema,
+  last_delivery_commit: z6.string().trim().regex(COMMIT_SHA_PATTERN3),
+  etag: z6.string().trim().min(1).optional(),
+  sectionEvidenceIndex: z6.array(FreshnessSectionEvidenceSchema).default([])
+}).strict();
+var FreshnessStateFileSchema = z6.object({
+  schema_version: z6.literal(1),
+  repos: z6.record(FreshnessRepoRefSchema, FreshnessBaselineSchema)
+}).strict().superRefine((value, ctx) => {
+  for (const [repoKey, baseline] of Object.entries(value.repos)) {
+    if (repoKey !== baseline.repo_ref) {
+      ctx.addIssue({
+        code: z6.ZodIssueCode.custom,
+        message: "repo map key must match baseline.repo_ref",
+        path: ["repos", repoKey, "repo_ref"]
+      });
+    }
+  }
+});
+var ChangedFileStatusSchema = z6.enum([
+  "added",
+  "modified",
+  "removed",
+  "renamed",
+  "copied",
+  "changed",
+  "unchanged"
+]);
+var FreshnessChangedFileSchema = z6.object({
+  path: z6.string().trim().min(1),
+  status: ChangedFileStatusSchema,
+  previous_path: z6.string().trim().min(1).optional()
+}).strict();
+var FreshnessAmbiguityReasonSchema = z6.enum([
+  "COMPARE_FILE_LIST_MISSING",
+  "COMPARE_PAGINATED",
+  "COMPARE_FILE_CAP_REACHED",
+  "COMPARE_STATUS_DIVERGED",
+  "COMPARE_STATUS_UNKNOWN",
+  "COMPARE_FILE_ENTRY_INVALID"
+]);
+var DetectorBaseSchema = z6.object({
+  repo_ref: FreshnessRepoRefSchema,
+  base_commit: z6.string().trim().regex(COMMIT_SHA_PATTERN3),
+  head_commit: z6.string().trim().regex(COMMIT_SHA_PATTERN3),
+  changed_paths: z6.array(z6.string().trim().min(1))
+}).strict();
+var FreshnessNoopOutcomeSchema = DetectorBaseSchema.extend({
+  mode: z6.literal("noop"),
+  changed_files: z6.array(FreshnessChangedFileSchema).length(0),
+  ambiguity_reasons: z6.array(FreshnessAmbiguityReasonSchema).length(0)
+});
+var FreshnessIncrementalCandidateOutcomeSchema = DetectorBaseSchema.extend({
+  mode: z6.literal("incremental-candidate"),
+  changed_files: z6.array(FreshnessChangedFileSchema).min(1),
+  ambiguity_reasons: z6.array(FreshnessAmbiguityReasonSchema).length(0)
+});
+var FreshnessFullRebuildRequiredOutcomeSchema = DetectorBaseSchema.extend({
+  mode: z6.literal("full-rebuild-required"),
+  changed_files: z6.array(FreshnessChangedFileSchema),
+  ambiguity_reasons: z6.array(FreshnessAmbiguityReasonSchema).min(1)
+});
+var FreshnessDetectorOutcomeSchema = z6.union([
+  FreshnessNoopOutcomeSchema,
+  FreshnessIncrementalCandidateOutcomeSchema,
+  FreshnessFullRebuildRequiredOutcomeSchema
+]);
+
+// src/freshness/detect.ts
+function createClient(token) {
+  return new Octokit2(token ? { auth: token } : void 0);
+}
+function normalizeChangedPath(value) {
+  return value.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
+}
+function normalizeChangedFiles(files) {
+  if (!Array.isArray(files)) {
+    return {
+      changed_files: [],
+      changed_paths: [],
+      ambiguity_reasons: ["COMPARE_FILE_LIST_MISSING"]
+    };
+  }
+  const changedFiles = [];
+  const changedPaths = /* @__PURE__ */ new Set();
+  const reasons = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const status = typeof file.status === "string" ? file.status : "";
+    const filename = typeof file.filename === "string" ? normalizeChangedPath(file.filename) : "";
+    const previousFilenameRaw = typeof file.previous_filename === "string" ? file.previous_filename : void 0;
+    const previousFilename = previousFilenameRaw ? normalizeChangedPath(previousFilenameRaw) : void 0;
+    if (!filename || !status) {
+      reasons.add("COMPARE_FILE_ENTRY_INVALID");
+      continue;
+    }
+    try {
+      const parsed = FreshnessChangedFileSchema.parse({
+        path: filename,
+        status,
+        previous_path: previousFilename
+      });
+      changedFiles.push(parsed);
+      changedPaths.add(filename);
+      if (status === "renamed" && previousFilename) {
+        changedPaths.add(previousFilename);
+      }
+    } catch {
+      reasons.add("COMPARE_FILE_ENTRY_INVALID");
+    }
+  }
+  const sortedFiles = changedFiles.slice().sort((left, right) => {
+    const pathOrder = left.path.localeCompare(right.path);
+    if (pathOrder !== 0) {
+      return pathOrder;
+    }
+    const previousOrder = (left.previous_path ?? "").localeCompare(right.previous_path ?? "");
+    if (previousOrder !== 0) {
+      return previousOrder;
+    }
+    return left.status.localeCompare(right.status);
+  });
+  return {
+    changed_files: sortedFiles,
+    changed_paths: [...changedPaths].sort((left, right) => left.localeCompare(right)),
+    ambiguity_reasons: [...reasons].sort((left, right) => left.localeCompare(right))
+  };
+}
+function collectAmbiguityReasons(compare) {
+  const reasons = /* @__PURE__ */ new Set();
+  const status = compare.data.status;
+  const files = compare.data.files;
+  if (!Array.isArray(files)) {
+    reasons.add("COMPARE_FILE_LIST_MISSING");
+  }
+  const linkHeader = compare.headers?.link ?? "";
+  if (linkHeader.includes('rel="next"')) {
+    reasons.add("COMPARE_PAGINATED");
+  }
+  if (Array.isArray(files) && files.length >= 300) {
+    reasons.add("COMPARE_FILE_CAP_REACHED");
+  }
+  if (status === "diverged") {
+    reasons.add("COMPARE_STATUS_DIVERGED");
+  }
+  if (typeof status !== "string" || status.length === 0) {
+    reasons.add("COMPARE_STATUS_UNKNOWN");
+  }
+  return [...reasons].sort((left, right) => left.localeCompare(right));
+}
+async function detectRepoFreshness(input, options = {}) {
+  const normalizedRepo = normalizeGitHubRepoIdentityForResolver(input.repo_ref);
+  const baseline = FreshnessBaselineSchema.parse({
+    ...input.baseline,
+    repo_ref: normalizeGitHubRepoIdentityForResolver(input.baseline.repo_ref).repo_ref,
+    last_delivery_commit: input.baseline.last_delivery_commit.toLowerCase()
+  });
+  if (baseline.repo_ref !== normalizedRepo.repo_ref) {
+    throw new Error("baseline.repo_ref must match detection repo_ref");
+  }
+  const client = options.client ?? createClient(options.token);
+  const repository = await client.rest.repos.get({
+    owner: normalizedRepo.owner,
+    repo: normalizedRepo.repo
+  });
+  const defaultBranch = repository.data.default_branch;
+  const branch = await client.rest.repos.getBranch({
+    owner: normalizedRepo.owner,
+    repo: normalizedRepo.repo,
+    branch: defaultBranch
+  });
+  const headCommit = branch.data.commit.sha.toLowerCase();
+  const baseCommit = baseline.last_delivery_commit.toLowerCase();
+  if (headCommit === baseCommit) {
+    return FreshnessDetectorOutcomeSchema.parse({
+      mode: "noop",
+      repo_ref: normalizedRepo.repo_ref,
+      base_commit: baseCommit,
+      head_commit: headCommit,
+      changed_paths: [],
+      changed_files: [],
+      ambiguity_reasons: []
+    });
+  }
+  const compare = await client.rest.repos.compareCommits({
+    owner: normalizedRepo.owner,
+    repo: normalizedRepo.repo,
+    base: baseCommit,
+    head: headCommit,
+    per_page: 100,
+    page: 1
+  });
+  const normalizedFiles = normalizeChangedFiles(compare.data.files);
+  const reasons = new Set(collectAmbiguityReasons(compare));
+  for (const reason of normalizedFiles.ambiguity_reasons) {
+    reasons.add(reason);
+  }
+  const payload = {
+    repo_ref: normalizedRepo.repo_ref,
+    base_commit: baseCommit,
+    head_commit: headCommit,
+    changed_paths: normalizedFiles.changed_paths,
+    changed_files: normalizedFiles.changed_files,
+    ambiguity_reasons: [...reasons].sort((left, right) => left.localeCompare(right))
+  };
+  if (payload.ambiguity_reasons.length > 0) {
+    return FreshnessDetectorOutcomeSchema.parse({
+      mode: "full-rebuild-required",
+      ...payload
+    });
+  }
+  return FreshnessDetectorOutcomeSchema.parse({
+    mode: "incremental-candidate",
+    ...payload
+  });
+}
+
+// src/freshness/impact-map.ts
+function normalizeRepoPath(value) {
+  return value.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
+}
+function compareDeterministic(left, right) {
+  return left.localeCompare(right, "en", { numeric: true, sensitivity: "base" });
+}
+function toOrderedUniquePaths(paths) {
+  const unique = /* @__PURE__ */ new Set();
+  for (const path14 of paths) {
+    const normalized = normalizeRepoPath(path14);
+    if (normalized.length > 0) {
+      unique.add(normalized);
+    }
+  }
+  return [...unique].sort(compareDeterministic);
+}
+function mapChangedPathsToImpactedSections(input) {
+  const changedPaths = toOrderedUniquePaths(input.changed_paths);
+  if (changedPaths.length === 0) {
+    return {
+      mode: "impact-mapped",
+      impacted_section_ids: [],
+      unmatched_changed_paths: []
+    };
+  }
+  const matchedPaths = /* @__PURE__ */ new Set();
+  const impacted = /* @__PURE__ */ new Set();
+  const normalizedSectionPaths = input.sectionEvidenceIndex.map((section) => ({
+    sectionId: section.sectionId,
+    repoPaths: new Set(toOrderedUniquePaths(section.repoPaths))
+  }));
+  for (const section of normalizedSectionPaths) {
+    const sectionPaths = section.repoPaths;
+    for (const path14 of changedPaths) {
+      if (sectionPaths.has(path14)) {
+        impacted.add(section.sectionId);
+        matchedPaths.add(path14);
+      }
+    }
+  }
+  const impacted_section_ids = [...impacted].sort(compareDeterministic);
+  const unmatched_changed_paths = changedPaths.filter((path14) => !matchedPaths.has(path14));
+  if (impacted_section_ids.length === 0) {
+    return {
+      mode: "full-rebuild-required",
+      impacted_section_ids,
+      unmatched_changed_paths
+    };
+  }
+  return {
+    mode: "impact-mapped",
+    impacted_section_ids,
+    unmatched_changed_paths
+  };
+}
+
+// src/freshness/section-evidence.ts
+function compareDeterministic2(left, right) {
+  return left.localeCompare(right, "en", { numeric: true, sensitivity: "base" });
+}
+function normalizeRepoPath2(value) {
+  return value.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
+}
+function buildSectionEvidenceFromAcceptedOutput(acceptedOutput, sectionIds) {
+  const allowed = sectionIds && sectionIds.length > 0 ? new Set(sectionIds.map((sectionId) => sectionId.trim()).filter(Boolean).sort(compareDeterministic2)) : void 0;
+  const claims = acceptedOutput.draft.claims ?? [];
+  const citations = acceptedOutput.draft.citations ?? [];
+  const citationById = new Map(citations.map((citation) => [citation.citationId, citation]));
+  const pathsBySection = /* @__PURE__ */ new Map();
+  for (const section of acceptedOutput.draft.sections) {
+    const sectionId = section.sectionId.trim();
+    if (!sectionId || allowed && !allowed.has(sectionId)) {
+      continue;
+    }
+    const sectionPaths = pathsBySection.get(sectionId) ?? /* @__PURE__ */ new Set();
+    const directSourcePaths = section.sourcePaths ?? [];
+    for (const sourcePath of directSourcePaths) {
+      const normalized = normalizeRepoPath2(sourcePath);
+      if (normalized.length > 0) {
+        sectionPaths.add(normalized);
+      }
+    }
+    if (sectionPaths.size === 0 && claims.length > 0 && citations.length > 0) {
+      const claimSourcePaths = claims.filter((claim) => claim.sectionId.trim() === sectionId).flatMap((claim) => claim.citationIds).map((citationId) => citationById.get(citationId)?.repoPath ?? "").map((repoPath) => normalizeRepoPath2(repoPath)).filter((repoPath) => repoPath.length > 0);
+      for (const repoPath of claimSourcePaths) {
+        sectionPaths.add(repoPath);
+      }
+    }
+    if (sectionPaths.size === 0) {
+      const globalSourceDocs = acceptedOutput.draft.sourceDocs ?? [];
+      for (const sourceDoc of globalSourceDocs) {
+        const normalized = normalizeRepoPath2(sourceDoc.path);
+        if (normalized.length > 0) {
+          sectionPaths.add(normalized);
+        }
+      }
+    }
+    if (sectionPaths.size > 0) {
+      pathsBySection.set(sectionId, sectionPaths);
+    }
+  }
+  const sectionIdsToEmit = allowed ? [...allowed].sort(compareDeterministic2) : [...new Set(acceptedOutput.draft.sections.map((section) => section.sectionId.trim()).filter(Boolean))].sort(
+    compareDeterministic2
+  );
+  return sectionIdsToEmit.map((sectionId) => {
+    const sectionPaths = pathsBySection.get(sectionId);
+    if (!sectionPaths || sectionPaths.size === 0) {
+      throw new Error(`UPDT-02 regeneration blocked: missing section evidence paths (${sectionId})`);
+    }
+    return {
+      sectionId,
+      repoPaths: [...sectionPaths].sort(compareDeterministic2)
+    };
+  });
+}
+function extractSectionEvidenceFromAcceptedOutput(acceptedOutput, sectionIds) {
+  return buildSectionEvidenceFromAcceptedOutput(acceptedOutput, sectionIds);
+}
+
+// src/freshness/state.ts
+import { promises as fs5 } from "node:fs";
+import path6 from "node:path";
+var EMPTY_STATE = {
+  schema_version: 1,
+  repos: {}
+};
+function normalizeFreshnessRepoRef(repoRef) {
+  const parsed = parseRepoRef(repoRef);
+  if (parsed.requested_ref !== null) {
+    throw new Error("freshness baseline repo_ref must not include @ref");
+  }
+  return parsed.repo_full_name;
+}
+function normalizePathList(paths) {
+  const unique = new Set(paths.map((entry) => entry.trim()));
+  return [...unique].sort((left, right) => left.localeCompare(right));
+}
+function canonicalizeBaseline(input) {
+  const parsed = FreshnessBaselineSchema.parse({
+    ...input,
+    repo_ref: normalizeFreshnessRepoRef(input.repo_ref),
+    last_delivery_commit: input.last_delivery_commit.toLowerCase(),
+    sectionEvidenceIndex: input.sectionEvidenceIndex.map((section) => ({
+      sectionId: section.sectionId.trim(),
+      repoPaths: normalizePathList(section.repoPaths)
+    }))
+  });
+  const sections = [...parsed.sectionEvidenceIndex].sort((left, right) => {
+    const sectionOrder = left.sectionId.localeCompare(right.sectionId);
+    if (sectionOrder !== 0) {
+      return sectionOrder;
+    }
+    const leftSig = left.repoPaths.join("\n");
+    const rightSig = right.repoPaths.join("\n");
+    return leftSig.localeCompare(rightSig);
+  });
+  return {
+    ...parsed,
+    sectionEvidenceIndex: sections
+  };
+}
+function canonicalizeState(input) {
+  const parsed = FreshnessStateFileSchema.parse(input);
+  const sortedRepoKeys = Object.keys(parsed.repos).sort((left, right) => left.localeCompare(right));
+  const repos = {};
+  for (const repoKey of sortedRepoKeys) {
+    const normalizedRepo = normalizeFreshnessRepoRef(repoKey);
+    repos[normalizedRepo] = canonicalizeBaseline(parsed.repos[repoKey]);
+  }
+  return {
+    schema_version: 1,
+    repos
+  };
+}
+function parseFreshnessState(raw) {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    throw new Error("Invalid freshness state JSON payload");
+  }
+  try {
+    return canonicalizeState(payload);
+  } catch {
+    throw new Error("Invalid freshness state schema");
+  }
+}
+async function loadFreshnessState(statePath) {
+  const absolute = path6.resolve(statePath);
+  let raw;
+  try {
+    raw = await fs5.readFile(absolute, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return EMPTY_STATE;
+    }
+    throw error;
+  }
+  return parseFreshnessState(raw);
+}
+function serializeFreshnessState(state) {
+  const canonical = canonicalizeState(state);
+  return `${JSON.stringify(canonical, null, 2)}
+`;
+}
+async function saveFreshnessState(statePath, state) {
+  const absolute = path6.resolve(statePath);
+  await fs5.mkdir(path6.dirname(absolute), { recursive: true });
+  await fs5.writeFile(absolute, serializeFreshnessState(state), "utf8");
+}
+
+// src/chunked/plan-sections.ts
+import { promises as fs6 } from "node:fs";
+import path7 from "node:path";
+
+// src/contracts/chunked-generation.ts
+import { z as z7 } from "zod";
+var COMMIT_SHA_PATTERN4 = /^[a-f0-9]{7,40}$/;
+var REPO_REF_PATTERN2 = /^[a-z0-9_.-]+\/[a-z0-9_.-]+$/;
+var PlanContextProfileSchema = z7.object({
+  repoName: z7.string().min(1),
+  primaryLanguage: z7.string().min(1),
+  projectType: z7.string().min(1),
+  domainHint: z7.string().min(1),
+  topLevelDirs: z7.array(z7.string().min(1)),
+  filesScanned: z7.number().int().nonnegative()
+}).strict();
+var PlanContextFileTreeEntrySchema = z7.object({
+  dir: z7.string().min(1),
+  files: z7.array(z7.string().min(1)),
+  totalBytes: z7.number().int().nonnegative()
+}).strict();
+var PlanContextConstraintsSchema = z7.object({
+  minSections: z7.number().int().min(1),
+  maxSections: z7.number().int().min(1),
+  minSubsectionsPerSection: z7.number().int().min(1),
+  minBodyKoChars: z7.number().int().min(1),
+  requiredElements: z7.array(z7.string().min(1)),
+  sectionIdPattern: z7.string().min(1),
+  subsectionIdPattern: z7.string().min(1)
+}).strict();
+var PlanContextSchema = z7.object({
+  artifactType: z7.literal("plan-context"),
+  repoFullName: z7.string().regex(REPO_REF_PATTERN2),
+  commitSha: z7.string().regex(COMMIT_SHA_PATTERN4),
+  ingestRunId: z7.string().min(1),
+  snapshotPath: z7.string().min(1),
+  generatedAt: z7.string().datetime(),
+  profile: PlanContextProfileSchema,
+  readmeExcerpt: z7.string(),
+  keyPaths: z7.array(z7.string().min(1)),
+  fileTree: z7.array(PlanContextFileTreeEntrySchema),
+  constraints: PlanContextConstraintsSchema
+}).strict();
+var ChunkedSubsectionPlanSchema = z7.object({
+  subsectionId: z7.string().min(1),
+  titleKo: z7.string().min(3),
+  objectiveKo: z7.string().min(10),
+  targetEvidenceKinds: z7.array(z7.enum(["code", "config", "tests", "docs"])).min(1),
+  targetCharacterCount: z7.number().int().min(700)
+}).strict();
+var ChunkedSectionPlanEntrySchema = z7.object({
+  sectionId: z7.string().min(1),
+  titleKo: z7.string().min(3),
+  summaryKo: z7.string().min(10),
+  focusPaths: z7.array(z7.string().min(1)),
+  subsectionCount: z7.number().int().min(3),
+  subsections: z7.array(ChunkedSubsectionPlanSchema).min(3)
+}).strict();
+var SectionPlanCrossReferenceSchema = z7.object({
+  fromSectionId: z7.string().min(1),
+  toSectionId: z7.string().min(1),
+  relation: z7.string().min(3)
+}).strict();
+var SectionPlanOutputSchema = z7.object({
+  artifactType: z7.literal("chunked-section-plan"),
+  repoFullName: z7.string().regex(REPO_REF_PATTERN2),
+  commitSha: z7.string().regex(COMMIT_SHA_PATTERN4),
+  ingestRunId: z7.string().min(1),
+  snapshotPath: z7.string().min(1),
+  generatedAt: z7.string().datetime(),
+  overviewKo: z7.string().min(30),
+  totalSections: z7.number().int().min(4).max(6),
+  sections: z7.array(ChunkedSectionPlanEntrySchema).min(4).max(6),
+  crossReferences: z7.array(SectionPlanCrossReferenceSchema)
+}).strict().superRefine((value, ctx) => {
+  if (value.totalSections !== value.sections.length) {
+    ctx.addIssue({
+      code: z7.ZodIssueCode.custom,
+      message: `totalSections (${value.totalSections}) must match sections array length (${value.sections.length})`,
+      path: ["totalSections"]
+    });
+  }
+  const sectionIds = /* @__PURE__ */ new Set();
+  for (const section of value.sections) {
+    if (sectionIds.has(section.sectionId)) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        message: `duplicate sectionId: ${section.sectionId}`,
+        path: ["sections"]
+      });
+    }
+    sectionIds.add(section.sectionId);
+    if (section.subsectionCount !== section.subsections.length) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        message: `section ${section.sectionId}: subsectionCount (${section.subsectionCount}) must match subsections length (${section.subsections.length})`,
+        path: ["sections"]
+      });
+    }
+    const subsectionIds = /* @__PURE__ */ new Set();
+    for (const sub of section.subsections) {
+      if (subsectionIds.has(sub.subsectionId)) {
+        ctx.addIssue({
+          code: z7.ZodIssueCode.custom,
+          message: `duplicate subsectionId: ${sub.subsectionId} in section ${section.sectionId}`,
+          path: ["sections"]
+        });
+      }
+      subsectionIds.add(sub.subsectionId);
+    }
+  }
+  for (const ref of value.crossReferences) {
+    if (!sectionIds.has(ref.fromSectionId) || !sectionIds.has(ref.toSectionId)) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        message: `cross reference targets non-existent section id`,
+        path: ["crossReferences"]
+      });
+    }
+  }
+});
+var SectionOutputSubsectionSchema = z7.object({
+  sectionId: z7.string().min(1),
+  subsectionId: z7.string().min(1),
+  titleKo: z7.string().min(3),
+  bodyKo: z7.string().min(80)
+}).strict();
+var SectionOutputClaimSchema = z7.object({
+  claimId: z7.string().min(1),
+  sectionId: z7.string().min(1),
+  subsectionId: z7.string().min(1),
+  statementKo: z7.string().min(20),
+  citationIds: z7.array(z7.string().min(1)).min(1)
+}).strict();
+var SectionOutputCitationSchema = z7.object({
+  citationId: z7.string().min(1),
+  evidenceId: z7.string().min(1),
+  repoPath: z7.string().min(1),
+  lineRange: z7.object({
+    start: z7.number().int().min(1),
+    end: z7.number().int().min(1)
+  }).strict().refine((v) => v.end >= v.start, { message: "lineRange.end must be >= start" }),
+  commitSha: z7.string().regex(COMMIT_SHA_PATTERN4),
+  permalink: z7.string().url(),
+  rationale: z7.string().min(1)
+}).strict();
+var SectionOutputSchema = z7.object({
+  sectionId: z7.string().min(1),
+  titleKo: z7.string().min(3),
+  summaryKo: z7.string().min(20),
+  sourcePaths: z7.array(z7.string().min(1)).min(1),
+  subsections: z7.array(SectionOutputSubsectionSchema).min(3)
+}).strict().superRefine((value, ctx) => {
+  for (const sub of value.subsections) {
+    if (sub.sectionId !== value.sectionId) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        message: `subsection ${sub.subsectionId} sectionId "${sub.sectionId}" must match parent "${value.sectionId}"`,
+        path: ["subsections"]
+      });
+    }
+  }
+  const seenSourcePaths = /* @__PURE__ */ new Set();
+  for (const sourcePath of value.sourcePaths) {
+    if (seenSourcePaths.has(sourcePath)) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        message: `duplicate sourcePath: ${sourcePath}`,
+        path: ["sourcePaths"]
+      });
+    }
+    seenSourcePaths.add(sourcePath);
+  }
+});
+var ChunkedSectionStatusSchema = z7.object({
+  status: z7.enum(["pending", "persisted"]),
+  sectionOutputPath: z7.string().min(1).optional(),
+  persistedAt: z7.string().datetime().optional(),
+  chunksInserted: z7.number().int().nonnegative().optional(),
+  claimCount: z7.number().int().nonnegative().optional(),
+  citationCount: z7.number().int().nonnegative().optional(),
+  subsectionCount: z7.number().int().nonnegative().optional(),
+  koreanChars: z7.number().int().nonnegative().optional()
+}).strict();
+var ChunkedSessionSchema = z7.object({
+  sessionId: z7.string().min(1),
+  repoFullName: z7.string().regex(REPO_REF_PATTERN2),
+  commitSha: z7.string().regex(COMMIT_SHA_PATTERN4),
+  ingestRunId: z7.string().min(1),
+  planPath: z7.string().min(1),
+  startedAt: z7.string().datetime(),
+  sections: z7.record(z7.string(), ChunkedSectionStatusSchema)
+}).strict();
+
+// src/chunked/plan-sections.ts
+var MAX_README_CHARS = 3e3;
+var MAX_FILES_PER_DIR = 30;
+var SKIP_DIRS = /* @__PURE__ */ new Set([".git", ".husky", "node_modules", "dist", ".next", "target"]);
+var DOMAIN_HINTS = [
+  { patterns: ["model", "inference", "llm", "ai", "ml", "neural", "torch", "tensorflow"], hintKo: "AI/ML \uBAA8\uB378 \uCD94\uB860" },
+  { patterns: ["runner", "scheduler", "executor", "orchestrat"], hintKo: "\uC791\uC5C5 \uC2E4\uD589 \uBC0F \uC2A4\uCF00\uC904\uB9C1" },
+  { patterns: ["database", "db", "storage", "redis", "mongo", "sql", "cache", "kv"], hintKo: "\uB370\uC774\uD130 \uC800\uC7A5\uC18C" },
+  { patterns: ["network", "http", "grpc", "rpc", "protocol", "proxy", "gateway"], hintKo: "\uB124\uD2B8\uC6CC\uD06C \uD1B5\uC2E0" },
+  { patterns: ["auth", "oauth", "credential", "token", "session"], hintKo: "\uC778\uC99D \uBC0F \uBCF4\uC548" },
+  { patterns: ["container", "docker", "kubernetes", "k8s", "pod"], hintKo: "\uCEE8\uD14C\uC774\uB108 \uC624\uCF00\uC2A4\uD2B8\uB808\uC774\uC158" },
+  { patterns: ["compiler", "parser", "ast", "lexer", "syntax", "lang"], hintKo: "\uC5B8\uC5B4 \uCC98\uB9AC \uBC0F \uCEF4\uD30C\uC77C" },
+  { patterns: ["render", "ui", "component", "widget", "canvas", "graphics"], hintKo: "UI \uB80C\uB354\uB9C1" },
+  { patterns: ["crypto", "encrypt", "hash", "cipher", "tls", "ssl"], hintKo: "\uC554\uD638\uD654 \uBC0F \uBCF4\uC548" },
+  { patterns: ["stream", "event", "queue", "message", "pubsub", "kafka"], hintKo: "\uC774\uBCA4\uD2B8/\uC2A4\uD2B8\uB9BC \uCC98\uB9AC" },
+  { patterns: ["api", "rest", "endpoint", "route", "handler"], hintKo: "API \uC11C\uBE44\uC2A4" },
+  { patterns: ["agent", "tool", "prompt", "chain", "rag", "embed"], hintKo: "AI \uC5D0\uC774\uC804\uD2B8" },
+  { patterns: ["build", "bundle", "webpack", "vite", "rollup", "esbuild"], hintKo: "\uBE4C\uB4DC \uB3C4\uAD6C" },
+  { patterns: ["plugin", "extension", "addon", "module", "hook"], hintKo: "\uD50C\uB7EC\uADF8\uC778 \uC2DC\uC2A4\uD15C" },
+  { patterns: ["cli", "cmd", "command", "terminal", "shell"], hintKo: "\uBA85\uB839\uC904 \uC778\uD130\uD398\uC774\uC2A4" }
+];
+function detectPrimaryLanguage(languageMix) {
+  const entries = Object.entries(languageMix).sort((a, b) => b[1] - a[1]);
+  if (entries.length === 0) return "Unknown";
+  return entries[0][0];
+}
+function detectProjectType(topDirs, primaryLang) {
+  const dirSet = new Set(topDirs.map((d) => d.toLowerCase()));
+  const hasCli = dirSet.has("cmd") || dirSet.has("cli") || dirSet.has("bin");
+  const hasServer = dirSet.has("server") || dirSet.has("api") || dirSet.has("routes");
+  const hasWebApp = dirSet.has("app") || dirSet.has("pages") || dirSet.has("components") || dirSet.has("views");
+  const hasLib = dirSet.has("lib") || dirSet.has("pkg") || dirSet.has("crate") || dirSet.has("packages");
+  const isNative = ["C", "C++", "Zig", "Rust"].includes(primaryLang) && (dirSet.has("deps") || dirSet.has("vendor"));
+  if (hasCli && hasServer) return "cli-server";
+  if (hasCli) return "cli-tool";
+  if (hasServer && hasWebApp) return "web-app";
+  if (hasServer) return "server";
+  if (hasWebApp) return "web-app";
+  if (isNative) return "native-system";
+  if (hasLib) return "library";
+  return "project";
+}
+function detectDomainHint(topDirs, keyPaths) {
+  const tokens = [
+    ...topDirs.map((d) => d.toLowerCase()),
+    ...keyPaths.flatMap((p) => p.toLowerCase().split("/"))
+  ];
+  let bestHint = "\uD575\uC2EC \uAE30\uB2A5";
+  let bestScore = 0;
+  for (const { patterns, hintKo } of DOMAIN_HINTS) {
+    const score = patterns.filter((p) => tokens.some((t) => t.includes(p))).length;
+    if (score > bestScore) {
+      bestScore = score;
+      bestHint = hintKo;
+    }
+  }
+  return bestHint;
+}
+function normalizeRepoPath3(value) {
+  return value.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
+}
+async function collectFiles(rootPath) {
+  const entries = [];
+  const walk = async (relativeDir) => {
+    const absolute = path7.join(rootPath, relativeDir);
+    let dirents;
+    try {
+      dirents = await fs6.readdir(absolute, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const sorted = dirents.sort((a, b) => a.name.localeCompare(b.name, "en", { sensitivity: "base" }));
+    for (const dirent of sorted) {
+      if (dirent.name === "snapshot-manifest.json" || dirent.isSymbolicLink()) {
+        continue;
+      }
+      if (dirent.isDirectory()) {
+        if (SKIP_DIRS.has(dirent.name.toLowerCase())) {
+          continue;
+        }
+        await walk(path7.join(relativeDir, dirent.name));
+        continue;
+      }
+      if (!dirent.isFile()) {
+        continue;
+      }
+      const filePath = normalizeRepoPath3(path7.join(relativeDir, dirent.name));
+      try {
+        const stat = await fs6.stat(path7.join(rootPath, filePath));
+        entries.push({ relativePath: filePath, bytes: stat.size });
+      } catch {
+      }
+    }
+  };
+  await walk(".");
+  return entries;
+}
+function buildFileTree(files) {
+  const byDir = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const parts = file.relativePath.split("/");
+    const dir = parts.length > 1 ? parts[0] : ".";
+    const entry = byDir.get(dir) ?? { files: [], totalBytes: 0 };
+    entry.totalBytes += file.bytes;
+    if (entry.files.length < MAX_FILES_PER_DIR) {
+      entry.files.push(file.relativePath);
+    }
+    byDir.set(dir, entry);
+  }
+  return Array.from(byDir.entries()).map(([dir, data]) => ({ dir, files: data.files, totalBytes: data.totalBytes })).sort((a, b) => b.totalBytes - a.totalBytes);
+}
+async function readReadmeExcerpt(snapshotPath) {
+  const candidates = ["README.md", "readme.md", "Readme.md", "README.rst", "README.txt", "README"];
+  for (const name of candidates) {
+    try {
+      const content = await fs6.readFile(path7.join(snapshotPath, name), "utf8");
+      return content.slice(0, MAX_README_CHARS);
+    } catch {
+    }
+  }
+  return "";
+}
+function compareDeterministic3(left, right) {
+  return left.localeCompare(right, "en", { numeric: true, sensitivity: "base" });
+}
+async function planContext(artifact) {
+  const files = await collectFiles(artifact.snapshot_path);
+  const keyPaths = (artifact.metadata.key_paths ?? []).map((value) => normalizeRepoPath3(value)).filter((value) => value.length > 0).sort(compareDeterministic3);
+  const topDirSet = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const firstSegment = file.relativePath.split("/")[0];
+    if (firstSegment && firstSegment !== file.relativePath) {
+      topDirSet.add(firstSegment);
+    }
+  }
+  const topDirs = Array.from(topDirSet).sort(compareDeterministic3);
+  const primaryLanguage = detectPrimaryLanguage(artifact.metadata.language_mix);
+  const projectType = detectProjectType(topDirs, primaryLanguage);
+  const domainHint = detectDomainHint(topDirs, keyPaths);
+  const repoRef = artifact.repo_ref;
+  const repoName = repoRef.includes("/") ? repoRef.split("/")[1] : repoRef;
+  const displayName = repoName.charAt(0).toUpperCase() + repoName.slice(1);
+  const readmeExcerpt = await readReadmeExcerpt(artifact.snapshot_path);
+  const fileTree = buildFileTree(files);
+  const context = {
+    artifactType: "plan-context",
+    repoFullName: artifact.repo_ref.toLowerCase(),
+    commitSha: artifact.commit_sha,
+    ingestRunId: artifact.ingest_run_id,
+    snapshotPath: artifact.snapshot_path,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    profile: {
+      repoName: displayName,
+      primaryLanguage,
+      projectType,
+      domainHint,
+      topLevelDirs: topDirs,
+      filesScanned: artifact.files_scanned
+    },
+    readmeExcerpt,
+    keyPaths,
+    fileTree,
+    constraints: {
+      minSections: 4,
+      maxSections: 6,
+      minSubsectionsPerSection: 3,
+      minBodyKoChars: 3e3,
+      requiredElements: ["mermaid-architecture"],
+      sectionIdPattern: "sec-{N} where N starts at 1",
+      subsectionIdPattern: "sub-{sectionN}-{subN} (e.g. sub-1-1, sub-1-2, sub-2-1)"
+    }
+  };
+  return PlanContextSchema.parse(context);
+}
+
+// src/chunked/validate-plan.ts
+import { existsSync as existsSync2 } from "node:fs";
+import path8 from "node:path";
+function validatePlan(raw, options) {
+  const parsed = SectionPlanOutputSchema.parse(raw);
+  const errors = [];
+  for (const section of parsed.sections) {
+    for (const focusPath of section.focusPaths) {
+      const absolute = path8.join(options.snapshotPath, focusPath);
+      if (!existsSync2(absolute)) {
+        errors.push(
+          `${section.sectionId}: focusPath "${focusPath}" does not exist in snapshot`
+        );
+      }
+    }
+  }
+  const seenTitles = /* @__PURE__ */ new Set();
+  for (const section of parsed.sections) {
+    const normalized = section.titleKo.trim().toLowerCase();
+    if (seenTitles.has(normalized)) {
+      errors.push(
+        `Duplicate section title: "${section.titleKo}"`
+      );
+    }
+    seenTitles.add(normalized);
+  }
+  for (let i = 0; i < parsed.sections.length; i++) {
+    const expected = `sec-${i + 1}`;
+    if (parsed.sections[i].sectionId !== expected) {
+      errors.push(
+        `Section at index ${i} has sectionId "${parsed.sections[i].sectionId}", expected "${expected}"`
+      );
+    }
+  }
+  for (const section of parsed.sections) {
+    const sectionNum = section.sectionId.replace("sec-", "");
+    for (let i = 0; i < section.subsections.length; i++) {
+      const expected = `sub-${sectionNum}-${i + 1}`;
+      if (section.subsections[i].subsectionId !== expected) {
+        errors.push(
+          `${section.sectionId}: subsection at index ${i} has id "${section.subsections[i].subsectionId}", expected "${expected}"`
+        );
+      }
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(
+      `Plan validation failed (${errors.length} issue(s)):
+` + errors.map((e) => `  - ${e}`).join("\n")
+    );
+  }
+  return parsed;
+}
+
+// src/chunked/validate-section.ts
+import { existsSync as existsSync3 } from "node:fs";
+import path9 from "node:path";
+function validateSection(section, options) {
+  const errors = [];
+  if (section.subsections.length < 3) {
+    errors.push(
+      `${section.sectionId}: must have at least 3 subsections, got ${section.subsections.length}`
+    );
+  }
+  for (const sub of section.subsections) {
+    if (sub.sectionId !== section.sectionId) {
+      errors.push(
+        `${sub.subsectionId}: sectionId "${sub.sectionId}" must match parent "${section.sectionId}"`
+      );
+    }
+  }
+  for (const sub of section.subsections) {
+    if (sub.bodyKo.length < 3e3) {
+      errors.push(
+        `${sub.subsectionId} (${section.sectionId}): bodyKo is ${sub.bodyKo.length} chars, minimum is 3,000`
+      );
+    }
+  }
+  const bodies = section.subsections.map((sub) => ({
+    sectionId: section.sectionId,
+    subsectionId: sub.subsectionId,
+    bodyKo: sub.bodyKo
+  }));
+  const repetitionErrors = detectBodyKoRepetitionInBodies(bodies);
+  errors.push(...repetitionErrors);
+  if (section.sourcePaths.length === 0) {
+    errors.push(`${section.sectionId}: sourcePaths must contain at least one path`);
+  }
+  for (const sourcePath of section.sourcePaths) {
+    const fullPath = path9.join(options.snapshotPath, sourcePath);
+    if (!existsSync3(fullPath)) {
+      errors.push(
+        `${section.sectionId}: sourcePath "${sourcePath}" does not exist in snapshot`
+      );
+    }
+  }
+  const hasArchitectureMermaid = section.subsections.some(
+    (sub) => /```mermaid[\s\S]*?```/i.test(sub.bodyKo)
+  );
+  if (!hasArchitectureMermaid) {
+    errors.push(
+      `${section.sectionId}: must include at least one architecture mermaid block (\`\`\`mermaid ... \`\`\`)`
+    );
+  }
+  if (options.qualityGateLevel === "strict") {
+    if (!hasArchitectureMermaid) {
+      errors.push(
+        `${section.sectionId}: strict quality requires architecture mermaid block for beginner/trend output`
+      );
+    }
+  }
+  const PREFIX_LENGTH = 20;
+  const PREFIX_REPEAT_THRESHOLD = 5;
+  for (const sub of section.subsections) {
+    const lines = sub.bodyKo.split(/[\n\r]+/).map((line) => line.trim()).filter((line) => line.length >= PREFIX_LENGTH);
+    const prefixCounts = /* @__PURE__ */ new Map();
+    for (const line of lines) {
+      const prefix = line.slice(0, PREFIX_LENGTH);
+      prefixCounts.set(prefix, (prefixCounts.get(prefix) ?? 0) + 1);
+    }
+    for (const [prefix, count] of prefixCounts) {
+      if (count >= PREFIX_REPEAT_THRESHOLD) {
+        errors.push(
+          `${sub.subsectionId} (${section.sectionId}): padding detected \u2014 line prefix "${prefix}..." repeated ${count} times. Write unique content instead of filler lines.`
+        );
+        break;
+      }
+    }
+  }
+  const CODEBLOCK_RE = /```[\s\S]*?```/g;
+  for (const sub of section.subsections) {
+    const proseOnly = sub.bodyKo.replace(CODEBLOCK_RE, "");
+    const haeraCnt = (proseOnly.match(/(?<![합습입]니)다\./g) ?? []).length;
+    const totalSentences = (proseOnly.match(/[.!?]\s/g) ?? []).length || 1;
+    if (haeraCnt / totalSentences > 0.3) {
+      errors.push(
+        `${sub.subsectionId} (${section.sectionId}): bodyKo uses \uD574\uB77C\uCCB4 endings (${haeraCnt} occurrences out of ~${totalSentences} sentences). Use \uD569\uB2C8\uB2E4\uCCB4 (formal polite): ~\uD569\uB2C8\uB2E4, ~\uB429\uB2C8\uB2E4, ~\uC788\uC2B5\uB2C8\uB2E4.`
+      );
+    }
+  }
+  for (const sub of section.subsections) {
+    const escapedNewlineCount = (sub.bodyKo.match(/\\\\n/g) ?? []).length;
+    if (escapedNewlineCount >= 5) {
+      errors.push(
+        `${sub.subsectionId} (${section.sectionId}): bodyKo contains ${escapedNewlineCount} escaped newline sequences (\\\\n). Use real line breaks and write genuine content.`
+      );
+    }
+  }
+  return errors;
+}
+
+// src/chunked/session.ts
+import { promises as fs7 } from "node:fs";
+import path10 from "node:path";
+import crypto from "node:crypto";
+function sessionPathForRepo(repoFullName, rootDir = "devport-output/chunked") {
+  const [owner, repo] = repoFullName.split("/");
+  if (!owner || !repo) {
+    throw new Error(`Invalid repoFullName: ${repoFullName}`);
+  }
+  return path10.resolve(rootDir, owner, repo, "session.json");
+}
+async function loadSession(sessionPath) {
+  const absolute = path10.resolve(sessionPath);
+  let raw;
+  try {
+    raw = await fs7.readFile(absolute, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+  const parsed = JSON.parse(raw);
+  return ChunkedSessionSchema.parse(parsed);
+}
+function initSession(plan, planPath) {
+  const sections = {};
+  for (const section of plan.sections) {
+    sections[section.sectionId] = { status: "pending" };
+  }
+  return {
+    sessionId: crypto.randomUUID(),
+    repoFullName: plan.repoFullName,
+    commitSha: plan.commitSha,
+    ingestRunId: plan.ingestRunId,
+    planPath: path10.resolve(planPath),
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    sections
+  };
+}
+async function saveSession(sessionPath, session) {
+  const validated = ChunkedSessionSchema.parse(session);
+  const absolute = path10.resolve(sessionPath);
+  await fs7.mkdir(path10.dirname(absolute), { recursive: true });
+  await fs7.writeFile(absolute, `${JSON.stringify(validated, null, 2)}
+`, "utf8");
+}
+function markSectionPersisted(session, sectionId, details) {
+  const existing = session.sections[sectionId];
+  if (!existing) {
+    throw new Error(`Section ${sectionId} not found in session`);
+  }
+  return {
+    ...session,
+    sections: {
+      ...session.sections,
+      [sectionId]: {
+        status: "persisted",
+        sectionOutputPath: details.sectionOutputPath,
+        persistedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        chunksInserted: details.chunksInserted,
+        claimCount: details.claimCount,
+        citationCount: details.citationCount,
+        subsectionCount: details.subsectionCount,
+        koreanChars: details.koreanChars
+      }
+    }
+  };
+}
+
+// src/chunked/finalize.ts
+import { readFile, rm } from "node:fs/promises";
+import path12 from "node:path";
+
+// src/output/markdown.ts
+import path11 from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+function compareDeterministic4(left, right) {
+  return left.localeCompare(right, "en", { numeric: true, sensitivity: "base" });
+}
+function normalizeRepoPath4(value) {
+  return value.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
+}
+function buildOutputDir(rootDir, repoRef) {
+  const [owner, repo] = repoRef.split("/");
+  if (!owner || !repo) {
+    throw new Error(`repo_ref must be owner/repo, got: ${repoRef}`);
+  }
+  return path11.resolve(rootDir, owner, repo);
+}
+function buildSectionFileName(sectionId, sectionIndex) {
+  return `${String(sectionIndex + 1).padStart(2, "0")}-${sectionId}.md`;
+}
+function uniquePaths(paths) {
+  return Array.from(
+    new Set(
+      paths.map((value) => normalizeRepoPath4(value)).filter((value) => value.length > 0)
+    )
+  ).sort(compareDeterministic4);
+}
+function resolveSectionSourcePaths(section, acceptedOutput) {
+  const directSourcePaths = Array.isArray(section.sourcePaths) ? uniquePaths(section.sourcePaths) : [];
+  if (directSourcePaths.length > 0) {
+    return directSourcePaths;
+  }
+  const citedSourcePaths = uniquePaths(
+    (acceptedOutput.draft.claims ?? []).filter((claim) => claim.sectionId === section.sectionId).flatMap((claim) => claim.citationIds).map(
+      (citationId) => (acceptedOutput.draft.citations ?? []).find((citation) => citation.citationId === citationId)?.repoPath ?? ""
+    )
+  );
+  if (citedSourcePaths.length > 0) {
+    return citedSourcePaths;
+  }
+  return [];
+}
+function renderSourceList(paths, heading = "## \uCC38\uACE0 \uC18C\uC2A4") {
+  if (paths.length === 0) {
+    return [];
+  }
+  return [
+    heading,
+    "",
+    ...paths.map((sourcePath) => `- \`${sourcePath}\``),
+    ""
+  ];
+}
+function renderOverviewMarkdown(acceptedOutput, sectionFiles) {
+  const trendFacts = acceptedOutput.draft.trendFacts ?? [];
+  const sourceDocs = uniquePaths(acceptedOutput.draft.sourceDocs.map((sourceDoc) => sourceDoc.path));
+  return [
+    `# ${acceptedOutput.repo_ref}`,
+    "",
+    `- Commit: \`${acceptedOutput.commit_sha}\``,
+    `- Generated: \`${acceptedOutput.draft.generatedAt}\``,
+    `- Sections: ${acceptedOutput.section_count}`,
+    `- Subsections: ${acceptedOutput.subsection_count}`,
+    "",
+    acceptedOutput.draft.overviewKo.trim(),
+    "",
+    "## \uC77D\uAE30 \uC21C\uC11C",
+    "",
+    ...sectionFiles.map(
+      (section, index) => `${index + 1}. [${section.titleKo}](${section.fileName})${section.summaryKo.trim().length > 0 ? ` - ${section.summaryKo.trim()}` : ""}`
+    ),
+    "",
+    ...renderSourceList(sourceDocs, "## \uC804\uCCB4 \uC18C\uC2A4 \uBB38\uC11C"),
+    ...trendFacts.length > 0 ? [
+      "## \uD2B8\uB80C\uB4DC \uC694\uC57D",
+      "",
+      ...trendFacts.map((fact) => `- ${fact.summaryKo.trim()}`),
+      ""
+    ] : []
+  ].join("\n");
+}
+function renderSectionMarkdown(section, sectionIndex, sourcePaths) {
+  const lines = [
+    `# ${sectionIndex + 1}. ${section.titleKo}`,
+    "",
+    section.summaryKo.trim(),
+    "",
+    ...renderSourceList(sourcePaths)
+  ];
+  for (const subsection of section.subsections) {
+    lines.push(`## ${subsection.titleKo}`);
+    lines.push("");
+    lines.push(subsection.bodyKo.trim());
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+async function writeMarkdownBundle(acceptedOutput, options = {}) {
+  const outputDir = buildOutputDir(options.outDir ?? "devport-output/wiki", acceptedOutput.repo_ref);
+  await mkdir(outputDir, { recursive: true });
+  const files = [];
+  const sectionFiles = acceptedOutput.draft.sections.map((section, index) => ({
+    sectionId: section.sectionId,
+    titleKo: section.titleKo,
+    summaryKo: section.summaryKo,
+    fileName: buildSectionFileName(section.sectionId, index)
+  }));
+  const readmePath = path11.join(outputDir, "README.md");
+  await writeFile(readmePath, `${renderOverviewMarkdown(acceptedOutput, sectionFiles)}
+`, "utf8");
+  files.push({
+    relativePath: "README.md",
+    absolutePath: readmePath
+  });
+  for (let index = 0; index < acceptedOutput.draft.sections.length; index += 1) {
+    const section = acceptedOutput.draft.sections[index];
+    const sourcePaths = resolveSectionSourcePaths(section, acceptedOutput);
+    const fileName = buildSectionFileName(section.sectionId, index);
+    const absolutePath = path11.join(outputDir, fileName);
+    const markdown = renderSectionMarkdown(section, index, sourcePaths);
+    await writeFile(absolutePath, `${markdown}
+`, "utf8");
+    files.push({
+      relativePath: fileName,
+      absolutePath
+    });
+  }
+  return {
+    outputDir,
+    files
+  };
+}
+
+// src/chunked/finalize.ts
+async function loadAllSectionOutputs(session) {
+  const outputs = [];
+  for (const [sectionId, status] of Object.entries(session.sections)) {
+    if (status.status !== "persisted") {
+      throw new Error(`Section ${sectionId} is not persisted (status: ${status.status})`);
+    }
+    if (!status.sectionOutputPath) {
+      throw new Error(`Section ${sectionId} has no sectionOutputPath`);
+    }
+    const raw = await readFile(path12.resolve(status.sectionOutputPath), "utf8");
+    const parsed = SectionOutputSchema.parse(JSON.parse(raw));
+    outputs.push(parsed);
+  }
+  outputs.sort((a, b) => a.sectionId.localeCompare(b.sectionId, "en", { numeric: true }));
+  return outputs;
+}
+function crossSectionValidation(sections) {
+  const errors = [];
+  const allBodies = [];
+  for (const section of sections) {
+    for (const sub of section.subsections) {
+      allBodies.push({
+        sectionId: section.sectionId,
+        subsectionId: sub.subsectionId,
+        bodyKo: sub.bodyKo
+      });
+    }
+  }
+  const crossRepErrors = detectCrossSubsectionRepetitionInBodies(allBodies);
+  errors.push(...crossRepErrors);
+  return errors;
+}
+function assembleAcceptedOutput(plan, sections) {
+  const allSourcePaths = Array.from(
+    new Set(
+      sections.flatMap(
+        (section) => section.sourcePaths.map((sourcePath) => sourcePath.trim()).filter((sourcePath) => sourcePath.length > 0)
+      )
+    )
+  ).sort((left, right) => left.localeCompare(right, "en", { numeric: true, sensitivity: "base" }));
+  const draftSections = sections.map((s) => ({
+    sectionId: s.sectionId,
+    titleKo: s.titleKo,
+    summaryKo: s.summaryKo,
+    sourcePaths: s.sourcePaths.map((sourcePath) => sourcePath.trim()).filter((sourcePath) => sourcePath.length > 0).sort((left, right) => left.localeCompare(right, "en", { numeric: true, sensitivity: "base" })),
+    subsections: s.subsections.map((sub) => ({
+      sectionId: sub.sectionId,
+      subsectionId: sub.subsectionId,
+      titleKo: sub.titleKo,
+      bodyKo: sub.bodyKo
+    }))
+  }));
+  const subsectionCount = sections.reduce((sum, s) => sum + s.subsections.length, 0);
+  let totalKoreanChars = plan.overviewKo.length;
+  for (const s of sections) {
+    totalKoreanChars += s.summaryKo.length;
+    for (const sub of s.subsections) {
+      totalKoreanChars += sub.bodyKo.length;
+    }
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    ingest_run_id: plan.ingestRunId,
+    repo_ref: plan.repoFullName,
+    commit_sha: plan.commitSha,
+    section_count: sections.length,
+    subsection_count: subsectionCount,
+    total_korean_chars: totalKoreanChars,
+    source_doc_count: allSourcePaths.length,
+    trend_fact_count: 0,
+    draft: {
+      artifactType: "wiki-draft",
+      repoFullName: plan.repoFullName,
+      commitSha: plan.commitSha,
+      generatedAt: now,
+      overviewKo: plan.overviewKo,
+      sections: draftSections,
+      sourceDocs: allSourcePaths.map((sourcePath, index) => ({
+        sourceId: `src-${index + 1}`,
+        path: sourcePath
+      })),
+      trendFacts: []
+    }
+  };
+}
+async function finalize(session, plan, options) {
+  const { advanceBaseline, statePath } = options;
+  const pendingSections = Object.entries(session.sections).filter(([_, status]) => status.status !== "persisted").map(([id]) => id);
+  if (pendingSections.length > 0) {
+    throw new Error(
+      `Cannot finalize: sections not yet persisted: ${pendingSections.join(", ")}`
+    );
+  }
+  const sectionOutputs = await loadAllSectionOutputs(session);
+  const crossErrors = crossSectionValidation(sectionOutputs);
+  if (crossErrors.length > 0) {
+    throw new Error(
+      `Cross-section validation failed (${crossErrors.length} issue(s)):
+` + crossErrors.map((e) => `  - ${e}`).join("\n")
+    );
+  }
+  const acceptedOutput = assembleAcceptedOutput(plan, sectionOutputs);
+  const markdownBundle = await writeMarkdownBundle(acceptedOutput, {
+    outDir: options.outDir
+  });
+  if (advanceBaseline) {
+    try {
+      const evidence = extractSectionEvidenceFromAcceptedOutput(acceptedOutput);
+      const state = await loadFreshnessState(statePath);
+      const repoRef = session.repoFullName.toLowerCase();
+      const nextState = {
+        ...state,
+        repos: {
+          ...state.repos,
+          [repoRef]: {
+            repo_ref: repoRef,
+            last_delivery_commit: session.commitSha,
+            sectionEvidenceIndex: evidence
+          }
+        }
+      };
+      await saveFreshnessState(statePath, nextState);
+      process.stderr.write(`  \u2713 freshness baseline \u2192 ${session.commitSha.slice(0, 7)}
+`);
+    } catch (err) {
+      process.stderr.write(
+        `  \u26A0 freshness baseline not saved: ${String(err)}
+    Re-run finalize --advance_baseline after fixing source paths
+`
+      );
+    }
+  }
+  const totalSubsections = sectionOutputs.reduce((sum, section) => sum + section.subsections.length, 0);
+  const result = {
+    sectionsAssembled: sectionOutputs.length,
+    totalSubsections,
+    totalSourceDocs: acceptedOutput.source_doc_count,
+    totalTrendFacts: acceptedOutput.trend_fact_count,
+    totalKoreanChars: acceptedOutput.total_korean_chars,
+    outputDir: markdownBundle.outputDir,
+    filesWritten: markdownBundle.files.map((file) => file.relativePath)
+  };
+  if (options.deleteSnapshot) {
+    try {
+      await rm(plan.snapshotPath, { recursive: true, force: true });
+      process.stderr.write(`  \u2713 snapshot deleted \u2192 ${plan.snapshotPath}
+`);
+    } catch (err) {
+      process.stderr.write(`  \u26A0 snapshot delete failed: ${String(err)}
+`);
+    }
+  }
+  return result;
+}
+
+// src/agent.ts
+function getQualityGateLevel(env) {
+  const val = env.DEVPORT_QUALITY_GATE_LEVEL;
+  return val === "standard" || val === "strict" ? val : "strict";
+}
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const eqIndex = arg.indexOf("=");
+    if (eqIndex !== -1) {
+      flags[arg.slice(2, eqIndex)] = arg.slice(eqIndex + 1);
+    } else {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = "true";
+      }
+    }
+  }
+  return flags;
+}
+function parseRepo(repoFlag, refFlag) {
+  const at = repoFlag.indexOf("@");
+  if (at !== -1) {
+    return { repo: repoFlag.slice(0, at), ref: repoFlag.slice(at + 1) };
+  }
+  return { repo: repoFlag, ref: refFlag };
+}
+function requireFlag(flags, name) {
+  const val = flags[name];
+  if (!val) throw new Error(`--${name} is required`);
+  return val;
+}
+function fmtNum(n) {
+  return n.toLocaleString("en-US");
+}
+function resolveQualityGateLevel(flags, defaultLevel) {
+  const flag = flags["quality_gate_level"];
+  if (!flag) return defaultLevel;
+  if (flag !== "standard" && flag !== "strict") {
+    throw new Error(`--quality_gate_level must be standard or strict, got: ${flag}`);
+  }
+  return flag;
+}
+async function ingestCommand(flags) {
+  const { repo, ref } = parseRepo(requireFlag(flags, "repo"), flags["ref"]);
+  const snapshotRoot = flags["snapshot_root"] ?? "devport-output/snapshots";
+  const outFile = flags["out"];
+  process.stderr.write(`[devport-agent] ingest: ${repo}${ref ? `@${ref}` : ""}
+`);
+  const artifact = await runIngest({
+    repo_ref: { repo, ...ref ? { ref } : {} },
+    snapshot_root: path13.resolve(snapshotRoot),
+    force_rebuild: flags["force_rebuild"] === "true"
+  });
+  const cacheLabel = artifact.idempotent_hit ? "cache hit" : "downloaded";
+  process.stderr.write(
+    `  \u2713 ${artifact.commit_sha.slice(0, 7)} \u2014 ${fmtNum(artifact.files_scanned)} files (${cacheLabel})
+`
+  );
+  process.stderr.write(`  snapshot_path: ${artifact.snapshot_path}
+`);
+  const json = `${JSON.stringify(artifact, null, 2)}
+`;
+  if (outFile) {
+    const outPath = path13.resolve(outFile);
+    await mkdir2(path13.dirname(outPath), { recursive: true });
+    await writeFile2(outPath, json, "utf8");
+    process.stderr.write(`  artifact \u2192 ${outPath}
+`);
+  } else {
+    process.stdout.write(json);
+  }
+}
+async function detectCommand(flags) {
+  const repoFlag = requireFlag(flags, "repo");
+  const parts = repoFlag.toLowerCase().split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(`--repo must be owner/repo, got: ${repoFlag}`);
+  }
+  const repoRef = `${parts[0]}/${parts[1]}`;
+  const statePath = flags["state_path"] ?? "devport-output/freshness/state.json";
+  process.stderr.write(`[devport-agent] detect: ${repoRef}
+`);
+  const state = await loadFreshnessState(statePath);
+  const baseline = state.repos[repoRef];
+  if (!baseline) {
+    process.stderr.write(`  \u2192 no baseline \u2014 full rebuild required
+`);
+    process.stderr.write(
+      `    (run \`package --advance_baseline\` or \`finalize --advance_baseline\` after first generation)
+`
+    );
+    process.stdout.write(
+      `${JSON.stringify(
+        { status: "full-rebuild", reason: "BASELINE_MISSING", repo_ref: repoRef, changed_paths: [], impacted_section_ids: [] },
+        null,
+        2
+      )}
+`
+    );
+    return;
+  }
+  process.stderr.write(`  base: ${baseline.last_delivery_commit.slice(0, 7)}
+`);
+  const detection = await detectRepoFreshness(
+    { repo_ref: repoRef, baseline },
+    { token: process.env["GITHUB_TOKEN"] }
+  );
+  if (detection.mode === "noop") {
+    process.stderr.write(`  \u2713 no changes \u2014 delivery is current at ${detection.head_commit.slice(0, 7)}
+`);
+    process.stdout.write(
+      `${JSON.stringify(
+        { status: "noop", repo_ref: repoRef, base_commit: detection.base_commit, head_commit: detection.head_commit, changed_paths: [], impacted_section_ids: [] },
+        null,
+        2
+      )}
+`
+    );
+    return;
+  }
+  const mapped = mapChangedPathsToImpactedSections({
+    changed_paths: detection.changed_paths,
+    sectionEvidenceIndex: baseline.sectionEvidenceIndex
+  });
+  const status = mapped.mode === "full-rebuild-required" || detection.mode === "full-rebuild-required" ? "full-rebuild" : "incremental";
+  process.stderr.write(
+    `  \u2192 ${status}: ${detection.changed_paths.length} paths changed, ${mapped.impacted_section_ids.length} sections impacted
+`
+  );
+  if (mapped.impacted_section_ids.length > 0) {
+    process.stderr.write(`  sections: ${mapped.impacted_section_ids.join(", ")}
+`);
+  }
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        status,
+        repo_ref: repoRef,
+        base_commit: detection.base_commit,
+        head_commit: detection.head_commit,
+        changed_paths: detection.changed_paths,
+        impacted_section_ids: mapped.impacted_section_ids
+      },
+      null,
+      2
+    )}
+`
+  );
+}
+async function packageCommand(flags) {
+  const outDir = flags["out_dir"] ?? "devport-output/wiki";
+  const inputFile = flags["input"];
+  const advanceBaseline = flags["advance_baseline"] === "true";
+  const statePath = flags["state_path"] ?? "devport-output/freshness/state.json";
+  const qualityGateLevel = resolveQualityGateLevel(flags, getQualityGateLevel(process.env));
+  let raw;
+  if (inputFile) {
+    raw = await readFile2(path13.resolve(inputFile), "utf8");
+  } else {
+    raw = await readStdin();
+  }
+  const acceptedOutput = JSON.parse(raw);
+  process.stderr.write(
+    `[devport-agent] package: ${acceptedOutput.repo_ref}@${acceptedOutput.commit_sha.slice(0, 7)}
+`
+  );
+  const packaged = packageAcceptedOutputsForDelivery([acceptedOutput], { qualityGateLevel });
+  const envelope = packaged.artifacts[0];
+  const glossaryCount = Array.isArray(envelope.glossary) ? envelope.glossary.length : 0;
+  const sectionCount = Array.isArray(envelope.sections) ? envelope.sections.length : 0;
+  const markdownBundle = await writeMarkdownBundle(acceptedOutput, {
+    outDir
+  });
+  process.stderr.write(
+    `  \u2713 ${sectionCount} sections validated, glossary: ${glossaryCount} terms
+`
+  );
+  process.stderr.write(`  markdown \u2192 ${markdownBundle.outputDir}
+`);
+  if (advanceBaseline) {
+    try {
+      const evidence = extractSectionEvidenceFromAcceptedOutput(acceptedOutput);
+      const state = await loadFreshnessState(statePath);
+      const repoRef = envelope.project.repoRef.toLowerCase();
+      const nextState = {
+        ...state,
+        repos: {
+          ...state.repos,
+          [repoRef]: {
+            repo_ref: repoRef,
+            last_delivery_commit: envelope.project.commitSha,
+            sectionEvidenceIndex: evidence
+          }
+        }
+      };
+      await saveFreshnessState(statePath, nextState);
+      process.stderr.write(`  \u2713 freshness baseline \u2192 ${envelope.project.commitSha.slice(0, 7)}
+`);
+    } catch (err) {
+      process.stderr.write(
+        `  \u26A0 freshness baseline not saved: ${String(err)}
+    markdown wiki is written; re-run package --advance_baseline after fixing section evidence paths
+`
+      );
+    }
+  }
+}
+async function planSectionsCommand(flags) {
+  const artifactFile = requireFlag(flags, "artifact");
+  const outFile = flags["out"];
+  const raw = await readFile2(path13.resolve(artifactFile), "utf8");
+  const artifact = ingestRunArtifactSchema.parse(JSON.parse(raw));
+  process.stderr.write(
+    `[devport-agent] plan-sections: ${artifact.repo_ref} (${fmtNum(artifact.files_scanned)} files)
+`
+  );
+  const context = await planContext(artifact);
+  process.stderr.write(
+    `  \u2713 plan context generated for ${context.profile.repoName}
+    type: ${context.profile.projectType}, lang: ${context.profile.primaryLanguage}, domain: ${context.profile.domainHint}
+    ${context.fileTree.length} directory groups, ${context.keyPaths.length} key paths
+    README excerpt: ${context.readmeExcerpt.length} chars
+`
+  );
+  const json = `${JSON.stringify(context, null, 2)}
+`;
+  if (outFile) {
+    const outPath = path13.resolve(outFile);
+    await mkdir2(path13.dirname(outPath), { recursive: true });
+    await writeFile2(outPath, json, "utf8");
+    process.stderr.write(`  context \u2192 ${outPath}
+`);
+  } else {
+    process.stdout.write(json);
+  }
+}
+async function validatePlanCommand(flags) {
+  const inputFile = requireFlag(flags, "input");
+  const contextFile = requireFlag(flags, "context");
+  const outFile = flags["out"];
+  const contextRaw = await readFile2(path13.resolve(contextFile), "utf8");
+  const context = PlanContextSchema.parse(JSON.parse(contextRaw));
+  const planRaw = await readFile2(path13.resolve(inputFile), "utf8");
+  const planJson = JSON.parse(planRaw);
+  process.stderr.write(
+    `[devport-agent] validate-plan: ${context.repoFullName}
+`
+  );
+  const validated = validatePlan(planJson, {
+    snapshotPath: context.snapshotPath
+  });
+  process.stderr.write(
+    `  \u2713 plan validated: ${validated.totalSections} sections
+`
+  );
+  for (const section of validated.sections) {
+    process.stderr.write(
+      `    ${section.sectionId}: ${section.titleKo} (${section.focusPaths.length} focus files, ${section.subsectionCount} subsections)
+`
+    );
+  }
+  const json = `${JSON.stringify(validated, null, 2)}
+`;
+  if (outFile) {
+    const outPath = path13.resolve(outFile);
+    await mkdir2(path13.dirname(outPath), { recursive: true });
+    await writeFile2(outPath, json, "utf8");
+    process.stderr.write(`  validated plan \u2192 ${outPath}
+`);
+  } else {
+    process.stdout.write(json);
+  }
+}
+async function persistSectionCommand(flags) {
+  const planFile = requireFlag(flags, "plan");
+  const sectionId = requireFlag(flags, "section");
+  const inputFile = requireFlag(flags, "input");
+  const sessionFile = flags["session"];
+  const planRaw = await readFile2(path13.resolve(planFile), "utf8");
+  const plan = SectionPlanOutputSchema.parse(JSON.parse(planRaw));
+  const sectionRaw = await readFile2(path13.resolve(inputFile), "utf8");
+  const sectionOutput = SectionOutputSchema.parse(JSON.parse(sectionRaw));
+  if (sectionOutput.sectionId !== sectionId) {
+    throw new Error(
+      `Section ID mismatch: --section ${sectionId} but input has sectionId "${sectionOutput.sectionId}"`
+    );
+  }
+  process.stderr.write(
+    `[devport-agent] persist-section: ${plan.repoFullName} / ${sectionId}
+`
+  );
+  const qualityGateLevel = resolveQualityGateLevel(flags, getQualityGateLevel(process.env));
+  const validationErrors = validateSection(sectionOutput, {
+    snapshotPath: plan.snapshotPath,
+    qualityGateLevel
+  });
+  if (validationErrors.length > 0) {
+    throw new Error(
+      `Section validation failed for ${sectionId} (${validationErrors.length} issue(s)):
+` + validationErrors.map((e) => `  - ${e}`).join("\n")
+    );
+  }
+  process.stderr.write(`  \u2713 section validation passed
+`);
+  const sessionPath = sessionFile ? path13.resolve(sessionFile) : sessionPathForRepo(plan.repoFullName);
+  let session = await loadSession(sessionPath);
+  if (!session) {
+    session = initSession(plan, planFile);
+    process.stderr.write(`  created new session: ${session.sessionId}
+`);
+  }
+  let koreanChars = sectionOutput.summaryKo.length;
+  for (const sub of sectionOutput.subsections) {
+    koreanChars += sub.bodyKo.length;
+  }
+  session = markSectionPersisted(session, sectionId, {
+    sectionOutputPath: path13.resolve(inputFile),
+    chunksInserted: 0,
+    claimCount: 0,
+    citationCount: 0,
+    subsectionCount: sectionOutput.subsections.length,
+    koreanChars
+  });
+  await saveSession(sessionPath, session);
+  process.stderr.write(
+    `  \u2713 ${sectionId}: locally validated, ${sectionOutput.sourcePaths.length} source paths
+`
+  );
+  process.stderr.write(`  session \u2192 ${sessionPath}
+`);
+  const totalSections = Object.keys(session.sections).length;
+  const persistedCount = Object.values(session.sections).filter((s) => s.status === "persisted").length;
+  process.stderr.write(`  progress: ${persistedCount}/${totalSections} sections ready
+`);
+}
+async function finalizeCommand(flags) {
+  const planFile = requireFlag(flags, "plan");
+  const sessionFile = flags["session"];
+  const advanceBaseline = flags["advance_baseline"] === "true";
+  const statePath = flags["state_path"] ?? "devport-output/freshness/state.json";
+  const deleteSnapshot = flags["delete_snapshot"] === "true";
+  const outDir = flags["out_dir"] ?? "devport-output/wiki";
+  const planRaw = await readFile2(path13.resolve(planFile), "utf8");
+  const plan = SectionPlanOutputSchema.parse(JSON.parse(planRaw));
+  const sessionPath = sessionFile ? path13.resolve(sessionFile) : sessionPathForRepo(plan.repoFullName);
+  const session = await loadSession(sessionPath);
+  if (!session) {
+    throw new Error(
+      `No session found at ${sessionPath}. Run persist-section for at least one section first.`
+    );
+  }
+  process.stderr.write(
+    `[devport-agent] finalize: ${plan.repoFullName} (session ${session.sessionId})
+`
+  );
+  const result = await finalize(session, plan, {
+    advanceBaseline,
+    statePath,
+    deleteSnapshot,
+    outDir
+  });
+  process.stderr.write(
+    `  \u2713 finalized: ${result.sectionsAssembled} sections, ${result.totalSubsections} subsections, ${result.totalSourceDocs} source docs, ${result.totalTrendFacts} trend facts, ${fmtNum(result.totalKoreanChars)} Korean chars
+`
+  );
+  process.stderr.write(`  markdown \u2192 ${result.outputDir} (${result.filesWritten.length} files)
+`);
+}
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) {
+      reject(new Error("No input provided. Pipe JSON or use --input <file>"));
+      return;
+    }
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    process.stdin.on("error", reject);
+  });
+}
+function printHelp() {
+  process.stderr.write(
+    [
+      "",
+      "portki \u2014 public CLI for generating Korean Markdown wikis from GitHub repositories",
+      "Run as an installed package with `portki <command>` or from source with `npx tsx src/agent.ts <command>`.",
+      "",
+      "Commands:",
+      "  ingest   Snapshot a GitHub repo and emit the ingest artifact",
+      "           --repo owner/repo     (required)",
+      "           --ref  branch|sha     (optional, uses default branch if omitted)",
+      "           --out  artifact.json  (optional, prints to stdout if omitted)",
+      "           --snapshot_root       (default: devport-output/snapshots)",
+      "           --force_rebuild       (re-download even if cache is valid)",
+      "",
+      "  detect   Detect what changed since the last delivery",
+      "           --repo owner/repo     (required)",
+      "           --state_path          (default: devport-output/freshness/state.json)",
+      "           stdout: { status, changed_paths, impacted_section_ids, ... }",
+      "           status values: noop | incremental | full-rebuild",
+      "",
+      "  package  Validate AI-generated GroundedAcceptedOutput, write markdown wiki files",
+      "           --input accepted-output.json  (optional, reads stdin if omitted)",
+      "           --out_dir                     (default: devport-output/wiki)",
+      "           --quality_gate_level          standard|strict (default from DEVPORT_QUALITY_GATE_LEVEL)",
+      "           --advance_baseline            save freshness state for future detect",
+      "           --state_path                  (default: devport-output/freshness/state.json)",
+      "",
+      "  plan-sections  Analyze repo and produce planning context for AI section generation",
+      "                 --artifact artifact.json  (required)",
+      "                 --out plan-context.json   (optional, prints to stdout if omitted)",
+      "",
+      "  validate-plan  Validate an AI-generated section plan against the schema",
+      "                 --input section-plan.json    (required)",
+      "                 --context plan-context.json  (required)",
+      "                 --out section-plan.json      (optional, prints to stdout if omitted)",
+      "",
+      "  persist-section  Validate a single section and register it in the local session",
+      "                   --plan section-plan.json   (required)",
+      "                   --section sec-1            (required)",
+      "                   --input section-1.json     (required)",
+      "                   --quality_gate_level       standard|strict (default from DEVPORT_QUALITY_GATE_LEVEL)",
+      "                   --session session.json     (optional, auto-derived from repo name)",
+      "",
+      "  finalize  Cross-validate all sections and write the final markdown wiki bundle",
+      "            --plan section-plan.json   (required)",
+      "            --session session.json     (optional, auto-derived from repo name)",
+      "            --out_dir                  (default: devport-output/wiki)",
+      "            --advance_baseline         save freshness state for future detect",
+      "            --state_path               (default: devport-output/freshness/state.json)",
+      "            --delete_snapshot          delete snapshot directory after successful finalize",
+      "",
+      "First-run workflow (monolithic):",
+      "  1. portki ingest --repo owner/repo --out artifact.json",
+      "  2. AI reads artifact.json + files under snapshot_path, generates GroundedAcceptedOutput",
+      "  3. portki package --input accepted-output.json --advance_baseline",
+      "",
+      "Chunked workflow (higher quality, section-at-a-time):",
+      "  1. portki ingest --repo owner/repo --out artifact.json",
+      "  2. portki plan-sections --artifact artifact.json --out plan-context.json",
+      "  3. AI reads plan-context.json + README + code, generates section-plan.json",
+      "  4. portki validate-plan --input section-plan.json --context plan-context.json --out section-plan.json",
+      "  5. For each section: AI reads focus files, writes section-N.json",
+      "     portki persist-section --plan section-plan.json --section sec-N --input section-N.json",
+      "  6. portki finalize --plan section-plan.json --advance_baseline",
+      "     \u2192 writes README.md + section markdown files under devport-output/wiki/{owner}/{repo}/",
+      "",
+      "Incremental update workflow:",
+      "  1. portki detect --repo owner/repo",
+      "     \u2192 noop: done. incremental/full-rebuild: continue below",
+      "  2. portki ingest --repo owner/repo --out artifact.json",
+      "  3. AI regenerates (all or only impacted sections) \u2192 accepted-output.json",
+      "  4. portki package --input accepted-output.json --advance_baseline",
+      ""
+    ].join("\n")
+  );
+}
+async function main() {
+  loadEnvFiles();
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    process.exitCode = command ? 0 : 1;
+    return;
+  }
+  const flags = parseFlags(argv.slice(1));
+  if (command === "ingest") {
+    await ingestCommand(flags);
+    return;
+  }
+  if (command === "detect") {
+    await detectCommand(flags);
+    return;
+  }
+  if (command === "package") {
+    await packageCommand(flags);
+    return;
+  }
+  if (command === "plan-sections") {
+    await planSectionsCommand(flags);
+    return;
+  }
+  if (command === "validate-plan") {
+    await validatePlanCommand(flags);
+    return;
+  }
+  if (command === "persist-section") {
+    await persistSectionCommand(flags);
+    return;
+  }
+  if (command === "finalize") {
+    await finalizeCommand(flags);
+    return;
+  }
+  process.stderr.write(`[devport-agent] unknown command: ${command}
+`);
+  printHelp();
+  process.exitCode = 1;
+}
+function isDirectExecution() {
+  const entry = process.argv[1];
+  if (!entry) {
+    return false;
+  }
+  return import.meta.url === pathToFileURL(entry).href;
+}
+if (isDirectExecution()) {
+  main().catch((error) => {
+    process.stderr.write(`
+[devport-agent] error: ${String(error)}
+`);
+    process.exitCode = 1;
+  });
+}
+
+// src/cli.ts
+main().catch((error) => {
+  process.stderr.write(`
+[portki] error: ${String(error)}
+`);
+  process.exitCode = 1;
+});