agentic-dev 0.1.0 → 0.2.0

package/sdd/99_toolchain/01_automation/ui-parity/core/capture-runner.mjs

@@ -0,0 +1,55 @@
+import path from "node:path";
+
+import { ensureDirectory } from "./paths.mjs";
+
+export function sanitizeFileName(raw) {
+  return String(raw || "screen")
+    .replace(/[^a-zA-Z0-9._-]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 120);
+}
+
+export async function captureScreen({
+  browser,
+  screen,
+  adapter,
+  outputPath,
+  baseUrl,
+  viewport,
+}) {
+  ensureDirectory(path.dirname(outputPath));
+  const page = await browser.newPage({ viewport });
+  try {
+    if (typeof adapter.preparePage === "function") {
+      await adapter.preparePage(page, { route: screen.route, screen, baseUrl, viewport });
+    }
+    if (typeof adapter.beforeNavigate === "function") {
+      await adapter.beforeNavigate(page, { route: screen.route, screen, baseUrl, viewport });
+    }
+    const targetUrl = new URL(screen.route, baseUrl).toString();
+    await page.goto(targetUrl, { waitUntil: "networkidle" });
+    if (screen.readySelector) {
+      await page.waitForSelector(screen.readySelector, {
+        timeout: Number.isFinite(Number(screen.readyTimeoutMs)) ? Number(screen.readyTimeoutMs) : 10000,
+      });
+    }
+    if (typeof adapter.waitForReady === "function") {
+      await adapter.waitForReady(page, { route: screen.route, screen, baseUrl, viewport });
+    }
+    if (typeof adapter.afterPageReady === "function") {
+      await adapter.afterPageReady(page, { route: screen.route, screen, baseUrl, viewport });
+    }
+    await page.screenshot({
+      path: outputPath,
+      fullPage: Boolean(screen.captureFullPage ?? false),
+    });
+    return {
+      targetUrl,
+      status: "captured",
+      detail: "capture_ok",
+    };
+  } finally {
+    await page.close();
+  }
+}

package/sdd/99_toolchain/01_automation/ui-parity/core/load-adapter.mjs

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export async function loadAdapter(adapterPath) {
+  const resolvedPath = path.resolve(adapterPath);
+  const moduleUrl = pathToFileURL(resolvedPath).href;
+  const loaded = await import(moduleUrl);
+  const adapter = loaded.default ?? loaded.adapter ?? loaded;
+  if (!adapter || typeof adapter !== "object") {
+    throw new Error(`Invalid adapter module: ${resolvedPath}`);
+  }
+  if (typeof adapter.service !== "string" || !adapter.service.trim()) {
+    throw new Error(`Adapter is missing required string field: service (${resolvedPath})`);
+  }
+  if (typeof adapter.targetBaseUrl !== "string" || !adapter.targetBaseUrl.trim()) {
+    throw new Error(`Adapter is missing required string field: targetBaseUrl (${resolvedPath})`);
+  }
+  if (!Array.isArray(adapter.screens) || adapter.screens.length === 0) {
+    throw new Error(`Adapter must expose a non-empty screens array (${resolvedPath})`);
+  }
+  return {
+    resolvedPath,
+    adapter,
+  };
+}

package/sdd/99_toolchain/01_automation/ui-parity/core/load-contract.mjs

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === "boolean") return value;
+  if (value == null) return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return fallback;
+}
+
+function normalizeNumber(value, fallback = 0) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function parseViewport(value) {
+  if (!value || typeof value !== "object") return null;
+  const width = normalizeNumber(value.width, NaN);
+  const height = normalizeNumber(value.height, NaN);
+  if (![width, height].every(Number.isFinite) || width <= 0 || height <= 0) return null;
+  return { width, height };
+}
+
+function parseRect(value) {
+  if (!value || typeof value !== "object") return null;
+  const x = normalizeNumber(value.x, NaN);
+  const y = normalizeNumber(value.y, NaN);
+  const width = normalizeNumber(value.width, NaN);
+  const height = normalizeNumber(value.height, NaN);
+  if (![x, y, width, height].every(Number.isFinite) || width <= 0 || height <= 0) return null;
+  return { x, y, width, height };
+}
+
+function parseRectList(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map(parseRect).filter(Boolean);
+}
+
+function inferRepoRoot(contractPath) {
+  const parts = path.resolve(contractPath).split(path.sep);
+  const sddIndex = parts.lastIndexOf("sdd");
+  if (sddIndex <= 0) {
+    return path.dirname(path.resolve(contractPath));
+  }
+  const rootParts = parts.slice(0, sddIndex);
+  return rootParts.length === 0 ? path.sep : rootParts.join(path.sep) || path.sep;
+}
+
+export function loadContract(contractPath, loadYaml) {
+  const resolvedPath = path.resolve(contractPath);
+  const raw = fs.readFileSync(resolvedPath, "utf8");
+  const parsed = loadYaml(raw) ?? {};
+  const screens = Array.isArray(parsed.screens)
+    ? parsed.screens.map((screen) => ({
+        id: screen.id,
+        route: screen.route,
+        referenceImage: screen.reference_image ?? screen.referenceImage ?? null,
+        captureFullPage: screen.capture_full_page ?? screen.captureFullPage ?? false,
+        allowResize: normalizeBoolean(screen.allow_resize, false),
+        pixelmatchThreshold: normalizeNumber(screen.pixelmatch_threshold, 0.1),
+        includeAA: normalizeBoolean(screen.include_aa, true),
+        viewport: parseViewport(screen.viewport),
+        maskRects: parseRectList(screen.mask_rects),
+        maxDiffRatio: Number.isFinite(Number(screen.max_diff_ratio))
+          ? Number(screen.max_diff_ratio)
+          : 0,
+      }))
+    : [];
+  const targetBaseUrl = parsed?.spec?.target_base_url ?? parsed?.target_base_url ?? "";
+  return {
+    resolvedPath,
+    contract: {
+      ...parsed,
+      screens,
+      targetBaseUrl,
+      repoRoot: inferRepoRoot(resolvedPath),
+    },
+  };
+}

package/sdd/99_toolchain/01_automation/ui-parity/core/paths.mjs

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function ensureDirectory(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+export function timestampUtc(now = new Date()) {
+  const parts = [
+    now.getUTCFullYear(),
+    String(now.getUTCMonth() + 1).padStart(2, "0"),
+    String(now.getUTCDate()).padStart(2, "0"),
+    String(now.getUTCHours()).padStart(2, "0"),
+    String(now.getUTCMinutes()).padStart(2, "0"),
+    String(now.getUTCSeconds()).padStart(2, "0"),
+  ];
+  return `${parts[0]}${parts[1]}${parts[2]}${parts[3]}${parts[4]}${parts[5]}`;
+}
+
+export function writeJson(filePath, payload) {
+  ensureDirectory(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}

package/sdd/99_toolchain/01_automation/ui-parity/core/proof-runner.mjs

@@ -0,0 +1,255 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { ensureDirectory, timestampUtc, writeJson } from "./paths.mjs";
+import { captureScreen, sanitizeFileName } from "./capture-runner.mjs";
+
+function loadPng(filePath) {
+  const { PNG } = globalThis.__TEMPLATE_UI_PARITY_DEPS__;
+  return PNG.sync.read(fs.readFileSync(filePath));
+}
+
+function clonePng(png) {
+  const { PNG } = globalThis.__TEMPLATE_UI_PARITY_DEPS__;
+  const next = new PNG({ width: png.width, height: png.height });
+  png.data.copy(next.data);
+  return next;
+}
+
+function writePng(filePath, png) {
+  const { PNG } = globalThis.__TEMPLATE_UI_PARITY_DEPS__;
+  ensureDirectory(path.dirname(filePath));
+  fs.writeFileSync(filePath, PNG.sync.write(png));
+}
+
+function createBlankDiff(width, height) {
+  const { PNG } = globalThis.__TEMPLATE_UI_PARITY_DEPS__;
+  return new PNG({ width, height });
+}
+
+function applyMaskRects(png, rects) {
+  if (!Array.isArray(rects) || rects.length === 0) return png;
+  const masked = clonePng(png);
+  for (const rect of rects) {
+    const xStart = Math.max(0, Math.floor(rect.x));
+    const yStart = Math.max(0, Math.floor(rect.y));
+    const xEnd = Math.min(masked.width, xStart + Math.floor(rect.width));
+    const yEnd = Math.min(masked.height, yStart + Math.floor(rect.height));
+    for (let y = yStart; y < yEnd; y += 1) {
+      for (let x = xStart; x < xEnd; x += 1) {
+        const index = (masked.width * y + x) * 4;
+        masked.data[index] = 255;
+        masked.data[index + 1] = 255;
+        masked.data[index + 2] = 255;
+        masked.data[index + 3] = 255;
+      }
+    }
+  }
+  return masked;
+}
+
+function resizeNearestNeighbor(source, targetWidth, targetHeight) {
+  const { PNG } = globalThis.__TEMPLATE_UI_PARITY_DEPS__;
+  const resized = new PNG({ width: targetWidth, height: targetHeight });
+  for (let y = 0; y < targetHeight; y += 1) {
+    for (let x = 0; x < targetWidth; x += 1) {
+      const srcX = Math.min(source.width - 1, Math.floor((x / targetWidth) * source.width));
+      const srcY = Math.min(source.height - 1, Math.floor((y / targetHeight) * source.height));
+      const srcIndex = (source.width * srcY + srcX) * 4;
+      const dstIndex = (targetWidth * y + x) * 4;
+      resized.data[dstIndex] = source.data[srcIndex];
+      resized.data[dstIndex + 1] = source.data[srcIndex + 1];
+      resized.data[dstIndex + 2] = source.data[srcIndex + 2];
+      resized.data[dstIndex + 3] = source.data[srcIndex + 3];
+    }
+  }
+  return resized;
+}
+
+function compareImages(referencePath, actualPath, diffPath, options = {}) {
+  const { pixelmatch } = globalThis.__TEMPLATE_UI_PARITY_DEPS__;
+  let reference = loadPng(referencePath);
+  let actual = loadPng(actualPath);
+  reference = applyMaskRects(reference, options.maskRects);
+  actual = applyMaskRects(actual, options.maskRects);
+  if (reference.width !== actual.width || reference.height !== actual.height) {
+    if (options.allowResize) {
+      actual = resizeNearestNeighbor(actual, reference.width, reference.height);
+    } else {
+      return {
+        diffRatio: 1,
+        status: "size_mismatch",
+        detail: `reference=${reference.width}x${reference.height} actual=${actual.width}x${actual.height}`,
+      };
+    }
+  }
+
+  if (reference.width !== actual.width || reference.height !== actual.height) {
+    return {
+      diffRatio: 1,
+      status: "size_mismatch",
+      detail: `reference=${reference.width}x${reference.height} actual=${actual.width}x${actual.height}`,
+    };
+  }
+
+  const diff = createBlankDiff(reference.width, reference.height);
+  const diffPixels = pixelmatch(
+    reference.data,
+    actual.data,
+    diff.data,
+    reference.width,
+    reference.height,
+    {
+      threshold: options.pixelmatchThreshold ?? 0.1,
+      includeAA: options.includeAA ?? true,
+    },
+  );
+  writePng(diffPath, diff);
+  return {
+    diffRatio: diffPixels / (reference.width * reference.height),
+    status: diffPixels === 0 ? "passed" : "failed",
+    detail: `reference=${reference.width}x${reference.height} actual=${actual.width}x${actual.height} diff_pixels=${diffPixels}`,
+  };
+}
+
+export async function runProof({
+  adapterPath,
+  contractPath,
+  outPath,
+  adapter,
+  contract,
+  browser,
+  requireFromAdapter,
+}) {
+  const pixelmatchModule = await import(pathToFileURL(requireFromAdapter.resolve("pixelmatch")).href);
+  const { PNG } = requireFromAdapter("pngjs");
+  globalThis.__TEMPLATE_UI_PARITY_DEPS__ = {
+    pixelmatch: pixelmatchModule.default ?? pixelmatchModule,
+    PNG,
+  };
+  const evidenceRoot = path.dirname(path.resolve(outPath));
+  const timestamp = timestampUtc();
+  const timestampRoot = path.join(evidenceRoot, timestamp);
+  const actualRoot = path.join(timestampRoot, "actual");
+  const diffRoot = path.join(timestampRoot, "diff");
+  ensureDirectory(actualRoot);
+  ensureDirectory(diffRoot);
+
+  const configuredScreens = Array.isArray(contract?.screens) && contract.screens.length > 0 ? contract.screens : adapter.screens ?? [];
+  const baseUrl = adapter.targetBaseUrl ?? contract?.targetBaseUrl ?? "http://127.0.0.1:4301";
+  const defaultViewport = adapter.viewport ?? { width: 1440, height: 1024 };
+  const repoRoot = contract?.repoRoot ?? process.cwd();
+
+  const results = [];
+  for (const configuredScreen of configuredScreens) {
+    const screen = {
+      ...configuredScreen,
+      referenceImage:
+        configuredScreen.referenceImage ??
+        configuredScreen.reference_image ??
+        `sdd/04_verify/10_test/ui_parity/reference/${configuredScreen.id}.png`,
+    };
+    const stem = sanitizeFileName(screen.id || screen.route);
+    const actualPath = path.join(actualRoot, `${stem}.png`);
+    const diffPath = path.join(diffRoot, `${stem}.png`);
+    const referencePath = screen.referenceImage ? path.resolve(screen.referenceImage) : null;
+    const resolvedReferencePath =
+      screen.referenceImage && !path.isAbsolute(screen.referenceImage)
+        ? path.resolve(repoRoot, screen.referenceImage)
+        : referencePath;
+
+    try {
+      const capture = await captureScreen({
+        browser,
+        screen,
+        adapter,
+        outputPath: actualPath,
+        baseUrl,
+        viewport: screen.viewport ?? defaultViewport,
+      });
+      const actualRelative = path.relative(path.dirname(outPath), actualPath).split(path.sep).join("/");
+
+      if (!resolvedReferencePath || !fs.existsSync(resolvedReferencePath)) {
+        results.push({
+          id: screen.id,
+          title: screen.title ?? null,
+          route: screen.route,
+          tags: Array.isArray(screen.tags) ? screen.tags : [],
+          status: "missing_reference",
+          diff_ratio: 1,
+          reference_image: screen.referenceImage ?? null,
+          actual_image: actualRelative,
+          diff_image: null,
+          detail: "Reference image is missing. Capture succeeded but comparison was skipped.",
+          target_url: capture.targetUrl,
+        });
+        continue;
+      }
+
+      const compared = compareImages(resolvedReferencePath, actualPath, diffPath, {
+        allowResize: Boolean(screen.allowResize),
+        pixelmatchThreshold: screen.pixelmatchThreshold,
+        includeAA: screen.includeAA,
+        maskRects:
+          typeof adapter.resolveMaskRects === "function"
+            ? await adapter.resolveMaskRects({ screen, baseUrl, defaultViewport })
+            : screen.maskRects,
+      });
+      const threshold = Number.isFinite(Number(screen.maxDiffRatio)) ? Number(screen.maxDiffRatio) : 0;
+      const withinThreshold = compared.diffRatio <= threshold;
+      results.push({
+        id: screen.id,
+        title: screen.title ?? null,
+        route: screen.route,
+        tags: Array.isArray(screen.tags) ? screen.tags : [],
+        status: compared.status === "size_mismatch" ? compared.status : withinThreshold ? "passed" : "failed",
+        diff_ratio: compared.diffRatio,
+        max_diff_ratio: threshold,
+        reference_image: screen.referenceImage,
+        actual_image: actualRelative,
+        diff_image: path.relative(path.dirname(outPath), diffPath).split(path.sep).join("/"),
+        detail: compared.detail,
+        target_url: capture.targetUrl,
+      });
+    } catch (error) {
+      results.push({
+        id: screen.id,
+        title: screen.title ?? null,
+        route: screen.route,
+        tags: Array.isArray(screen.tags) ? screen.tags : [],
+        status: "capture_error",
+        diff_ratio: 1,
+        max_diff_ratio: Number.isFinite(Number(screen.maxDiffRatio)) ? Number(screen.maxDiffRatio) : 0,
+        reference_image: screen.referenceImage ?? null,
+        actual_image: null,
+        diff_image: null,
+        detail: error instanceof Error ? error.message : String(error),
+        target_url: new URL(screen.route, baseUrl).toString(),
+      });
+    }
+  }
+
+  const summary = {
+    total: results.length,
+    passed: results.filter((screen) => screen.status === "passed").length,
+    failed: results.filter((screen) => screen.status === "failed" || screen.status === "size_mismatch").length,
+    missing_reference: results.filter((screen) => screen.status === "missing_reference").length,
+    capture_error: results.filter((screen) => screen.status === "capture_error").length,
+    matched: results.filter((screen) => screen.status === "passed").length === results.length && results.length > 0,
+  };
+
+  const payload = {
+    generated_at: new Date().toISOString(),
+    service: adapter.service ?? "replace-service-name",
+    adapter_path: adapterPath,
+    contract_path: contractPath,
+    target_base_url: baseUrl,
+    default_viewport: defaultViewport,
+    screens: results,
+    summary,
+  };
+
+  writeJson(outPath, payload);
+  delete globalThis.__TEMPLATE_UI_PARITY_DEPS__;
+  return payload;
+}

package/sdd/99_toolchain/01_automation/ui-parity/interfaces/ui-parity-artifact-layout.md

@@ -0,0 +1,23 @@
+# UI Parity Artifact Layout
+
+권장 루트:
+
+- `sdd/04_verify/10_test/ui_parity/`
+
+필수 파일:
+
+- latest proof json
+  - 예: `templates_platform_agentic_dev_latest.json`
+
+권장 하위 구조:
+
+- `reference/`
+- `<timestamp>/actual/`
+- `<timestamp>/diff/`
+- `loop_runs/`
+- `staged_runs/`
+
+정책:
+
+- latest proof json은 항상 고정 경로를 사용한다.
+- timestamp run directory는 회차별 evidence 보존용이다.

package/sdd/99_toolchain/01_automation/ui-parity/interfaces/ui-parity-proof-interface.md

@@ -0,0 +1,60 @@
+# UI Parity Proof Interface
+
+입력:
+
+- `--adapter`
+  - app adapter module path
+- `--contract`
+  - parity contract yaml path
+- `--out`
+  - latest proof json output path
+
+adapter contract:
+
+- `service`
+- `targetBaseUrl`
+- optional `viewport`
+- optional `preparePage(page, context)`
+- optional `beforeNavigate(page, context)`
+- optional `waitForReady(page, context)`
+- optional `afterPageReady(page, context)`
+- optional `resolveMaskRects(context)`
+- `screens[]`
+  - `id`
+  - optional `title`
+  - `route`
+  - optional `referenceImage`
+  - optional `maxDiffRatio`
+  - optional `viewport`
+  - optional `allowResize`
+  - optional `pixelmatchThreshold`
+  - optional `includeAA`
+  - optional `maskRects`
+  - optional `readySelector`
+  - optional `readyTimeoutMs`
+  - optional `tags`
+
+출력 JSON:
+
+- `generated_at`
+- `service`
+- `adapter_path`
+- `contract_path`
+- `target_base_url`
+- `default_viewport`
+- `screens[]`
+  - `id`
+  - optional `title`
+  - `route`
+  - optional `tags`
+  - `status`
+  - `diff_ratio`
+  - optional `max_diff_ratio`
+  - optional `reference_image`
+- `summary`
+  - `total`
+  - `passed`
+  - `failed`
+  - `missing_reference`
+  - `capture_error`
+  - `matched`

package/sdd/99_toolchain/01_automation/ui-parity/interfaces/ui-parity-route-gap-interface.md

@@ -0,0 +1,82 @@
+# UI Parity Route Gap Interface
+
+입력:
+
+- `--service`
+  - 화면 카탈로그를 소유하는 프론트 디렉터리 또는 서비스 이름
+- `--screens`
+  - spec screen catalog json path
+- `--routes`
+  - route catalog json path
+- `--out`
+  - route gap json output path
+- `--markdown-out`
+  - optional markdown summary output path
+
+분류 규칙:
+
+- `direct`
+  - route가 1:1로 연결된 화면
+- `shared`
+  - 여러 screen id가 같은 route를 공유하거나 route entry가 `binding=shared`
+- `stateful`
+  - direct route 대신 상태 전이에 의존하거나 `binding=stateful`
+- `missing`
+  - route entry가 없거나 `binding=missing`
+
+planning evidence 필드:
+
+- `binding_source`
+  - `explicit` 또는 `inferred`
+- `coverage_state`
+  - `route_bound`, `shared_route`, `state_transition`, `unmapped`
+- `evidence_level`
+  - `strong`, `medium`, `weak`, `missing`
+- `duplicate_route_groups`
+  - 같은 route를 여러 screen id가 공유하는 그룹
+
+출력 JSON:
+
+- `generated_at`
+- `service`
+- `screens_path`
+- `routes_path`
+- `summary`
+  - `total`
+  - `direct`
+  - `shared`
+  - `stateful`
+  - `missing`
+  - `coverage_ratio`
+  - `explicit_bindings`
+  - `strong_evidence`
+  - `medium_evidence`
+  - `weak_evidence`
+  - `with_notes`
+  - `with_tags`
+  - `duplicate_route_groups`
+- `duplicate_route_groups[]`
+  - `route`
+  - `screen_ids[]`
+- `screens[]`
+  - `id`
+  - `title`
+  - `route`
+  - `binding`
+  - `binding_source`
+  - `coverage_state`
+  - `evidence_level`
+  - `route_defined`
+  - `has_notes`
+  - `has_tags`
+  - `duplicate_route_ids[]`
+  - `tags[]`
+  - `status`
+  - `notes[]`
+
+주요 생성 경로 예시:
+
+- `sdd/02_plan/99_generated/from_planning/ui_parity/platform.route_gap_report.json`
+- `sdd/02_plan/99_generated/from_planning/ui_parity/platform.route_gap_report.md`
+- `sdd/02_plan/99_generated/from_planning/ui_parity/mobile.route_gap_report.json`
+- `sdd/02_plan/99_generated/from_planning/ui_parity/mobile.route_gap_report.md`

package/sdd/99_toolchain/01_automation/ui-parity/runtime/playwright-runtime.mjs

@@ -0,0 +1,16 @@
+export async function createPlaywrightRuntime(requireFromAdapter) {
+  const playwright = requireFromAdapter("@playwright/test");
+  const chromium = playwright.chromium ?? playwright.default?.chromium;
+  if (!chromium) {
+    throw new Error("Failed to load Playwright chromium runtime from the app workspace.");
+  }
+  const browser = await chromium.launch({
+    headless: true,
+  });
+  return {
+    browser,
+    async dispose() {
+      await browser.close();
+    },
+  };
+}

package/sdd/99_toolchain/01_automation/ui-parity/runtime/static-runtime.mjs

@@ -0,0 +1,6 @@
+export function createStaticRuntime() {
+  return {
+    name: "static-runtime",
+    description: "Template placeholder runtime. Replace with Playwright or Stagehand-backed capture runtime.",
+  };
+}

package/sdd/99_toolchain/02_policies/.gitkeep

@@ -0,0 +1 @@
+

package/sdd/99_toolchain/02_policies/build-ast-governance-policy.md

@@ -0,0 +1,22 @@
+# Build AST Governance Policy
+
+## Purpose
+
+`sdd/03_build`를 implementation history가 아니라 runtime assembly current-state 문서로 고정한다.
+
+## Rules
+
+- service build summary는 실제 entrypoint부터 읽혀야 한다.
+- 기본 설명 순서는 `entry -> provider/router -> auth/session gate -> shell -> route leaf -> backend contract leaf`다.
+- shared shell, auth/session, data contract, transport split은 route leaf 이후 cross-cutting link로 연결한다.
+- `sdd/03_build`에는 dated memo, Ralph iteration narrative, run id, turn-specific 회고를 남기지 않는다.
+- 구조 current-state 적합성은 `scripts/dev/audit_sdd_build_ast.py`로 검증하고 결과는 `sdd/04_verify/03_architecture`에 유지한다.
+- downstream 저장소는 이 정책과 audit script를 함께 복제해야 한다.
+
+## Canonical References
+
+- `AGENTS.md`
+- `scripts/dev/audit_sdd_build_ast.py`
+- `sdd/02_plan/03_architecture/build_ast_runtime_tree_governance.md`
+- `sdd/03_build/03_architecture/build_ast_runtime_tree_governance.md`
+- `sdd/04_verify/03_architecture/build_ast_runtime_tree_governance.md`

package/sdd/99_toolchain/02_policies/compose-runtime-baseline-policy.md

@@ -0,0 +1,24 @@
+# Compose Runtime Baseline Policy
+
+## Purpose
+
+템플릿 저장소의 compose/runtime 기준선을 root compose 중심 current-state로 고정하고, dedicated host overlay와 provider-first delivery split의 역할을 분리한다.
+
+## Rules
+
+- 루트 `compose.yml`은 템플릿 저장소의 canonical dev-focused runtime baseline이다.
+- root compose는 4개 frontend surface, `server`, 기본 `postgres`, optional DB profile(`mysql`, `mariadb`, `mongo`)을 한 graph로 유지한다.
+- `infra/compose/dev.yml`, `infra/compose/prod.yml`은 dedicated DEV(개발계)/PROD host나 분리된 runtime stack이 필요할 때 사용하는 overlay/example set이다.
+- compose 문서는 root compose baseline과 dedicated overlay를 혼동하지 않고 current-state 역할로만 설명한다.
+- browser-facing 환경 변수(`VITE_API_BASE_URL` 등)는 컨테이너 내부 DNS가 아니라 실제 브라우저가 도달 가능한 URL을 사용한다.
+- remote delivery topology는 `AWS edge/domain -> OpenStack backend compute -> AWS data plane` current split을 기준으로 설명한다.
+- compose baseline이나 topology가 바뀌면 `README.md`, `infra/compose/README.md`, `sdd/02_plan/06_iac`, `sdd/03_build/06_iac`, `sdd/04_verify/06_iac`를 같은 변경 단위로 동기화한다.
+
+## Canonical References
+
+- `README.md`
+- `infra/compose/README.md`
+- `infra/terraform/README.md`
+- `sdd/02_plan/06_iac/template_runtime_delivery.md`
+- `sdd/03_build/06_iac/template_runtime_delivery.md`
+- `sdd/04_verify/06_iac/template_runtime_delivery.md`