agentic-dev 0.2.4 → 0.2.7

package/lib/scaffold.mjs

@@ -1,68 +1,56 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
-import { fileURLToPath } from "node:url";
-
-export const TEMPLATE_CONFIG = {
-  landing: {
-    id: "landing",
-    serviceName: "client-landing",
-    composePortVar: "CLIENT_LANDING_PORT",
-    composeApiVar: "CLIENT_LANDING_VITE_API_BASE_URL",
-    defaultPort: 3000,
-  },
-  web: {
-    id: "web",
-    serviceName: "client-web",
-    composePortVar: "CLIENT_WEB_PORT",
-    composeApiVar: "CLIENT_WEB_VITE_API_BASE_URL",
-    defaultPort: 3001,
-  },
-  mobile: {
-    id: "mobile",
-    serviceName: "client-mobile",
-    composePortVar: "CLIENT_MOBILE_PORT",
-    composeApiVar: "CLIENT_MOBILE_VITE_API_BASE_URL",
-    defaultPort: 3002,
-  },
-  admin: {
-    id: "admin",
-    serviceName: "client-admin",
-    composePortVar: "CLIENT_ADMIN_PORT",
-    composeApiVar: "CLIENT_ADMIN_VITE_API_BASE_URL",
-    defaultPort: 4000,
-  },
-};
-
-const ROOT_FILES = [
-  ".dockerignore",
-  ".env.example",
-  ".gitignore",
-  "AGENTS.md",
-  "README.md",
-  "SDD_SKILL.md",
-];
-
-const ROOT_DIRS = [
-  ".agent",
-  ".claude",
-  ".codex",
-  "infra",
-  "scripts",
-  "sdd",
-  "server",
-];
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const PACKAGE_ROOT = path.resolve(__dirname, "..");
-
-export function listTemplates() {
-  return Object.keys(TEMPLATE_CONFIG);
+import { spawnSync } from "node:child_process";
+
+export const DEFAULT_TEMPLATE_OWNER = "say828";
+
+function runCommand(command, args, { cwd = process.cwd(), label = "" } = {}) {
+  if (label) {
+    console.log(`\n> ${label}`);
+  }
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: "inherit",
+  });
+  if (result.status !== 0) {
+    throw new Error(`Command failed: ${command} ${args.join(" ")}`);
+  }
+}
+
+function commandExists(command) {
+  const result = spawnSync("bash", ["-lc", `command -v ${command}`], {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+function copyDirectoryContents(sourceRoot, destinationRoot) {
+  for (const entry of fs.readdirSync(sourceRoot, { withFileTypes: true })) {
+    if (entry.name === ".git" || entry.name === "node_modules" || entry.name === "dist") {
+      continue;
+    }
+    fs.cpSync(path.join(sourceRoot, entry.name), path.join(destinationRoot, entry.name), {
+      recursive: true,
+      force: true,
+      filter: (source) => {
+        const baseName = path.basename(source);
+        return baseName !== ".git" && baseName !== "node_modules" && baseName !== "dist";
+      },
+    });
+  }
 }
 
-export function resolvePackageRoot() {
-  return PACKAGE_ROOT;
+function fetchPage(url) {
+  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || process.env.AGENTIC_GITHUB_TOKEN;
+  return fetch(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "agentic-dev",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+  });
 }
 
 export function parseArgs(argv) {
@@ -71,8 +59,10 @@ export function parseArgs(argv) {
     command: "init",
     targetDir: "",
     template: "",
+    owner: DEFAULT_TEMPLATE_OWNER,
     force: false,
     yes: false,
+    skipBootstrap: false,
   };
 
   if (args.length > 0 && !args[0].startsWith("-")) {
@@ -86,6 +76,9 @@ export function parseArgs(argv) {
       case "-t":
         options.template = args.shift() ?? "";
         break;
+      case "--owner":
+        options.owner = args.shift() ?? DEFAULT_TEMPLATE_OWNER;
+        break;
       case "--force":
         options.force = true;
         break;
@@ -93,6 +86,9 @@ export function parseArgs(argv) {
       case "-y":
         options.yes = true;
         break;
+      case "--skip-bootstrap":
+        options.skipBootstrap = true;
+        break;
       case "--help":
       case "-h":
         options.command = "help";
@@ -112,29 +108,24 @@ export function parseArgs(argv) {
 export function usage() {
   return [
     "Usage:",
-    "  agentic-dev init <target-dir> --template <landing|web|mobile|admin>",
+    "  agentic-dev",
+    "  agentic-dev init <target-dir>",
     "",
     "Examples:",
-    "  npx agentic-dev init my-app --template web",
-    "  npx agentic-dev my-app --template mobile",
+    "  npx agentic-dev",
+    "  npx agentic-dev init my-app",
+    "  npx agentic-dev init my-app --template template-web --yes",
     "",
     "Options:",
-    "  --template, -t   Frontend template to install",
-    "  --force          Allow scaffolding into a non-empty directory",
-    "  --yes, -y        Skip interactive confirmation",
-    "  --help, -h       Show this help",
+    "  --template, -t     Template repo name or suffix to use",
+    "  --owner            GitHub owner for template-* repos (default: say828)",
+    "  --force            Allow scaffolding into a non-empty directory",
+    "  --yes, -y          Skip interactive prompts",
+    "  --skip-bootstrap   Copy the template but skip install/bootstrap",
+    "  --help, -h         Show this help",
   ].join("\n");
 }
 
-export function validateTemplate(template) {
-  if (!TEMPLATE_CONFIG[template]) {
-    throw new Error(
-      `Unsupported template: ${template}. Expected one of: ${listTemplates().join(", ")}.`,
-    );
-  }
-  return TEMPLATE_CONFIG[template];
-}
-
 export function ensureTargetDir(targetDir, { force = false } = {}) {
   if (!targetDir) {
     throw new Error("Missing target directory.");
@@ -150,230 +141,214 @@ export function ensureTargetDir(targetDir, { force = false } = {}) {
   return resolved;
 }
 
-function copyPath(relativePath, destinationRoot) {
-  let sourcePath = path.join(PACKAGE_ROOT, relativePath);
-  if (!fs.existsSync(sourcePath) && relativePath === ".gitignore") {
-    const npmIgnorePath = path.join(PACKAGE_ROOT, ".npmignore");
-    if (fs.existsSync(npmIgnorePath)) {
-      sourcePath = npmIgnorePath;
+export async function fetchTemplateRepos({ owner = DEFAULT_TEMPLATE_OWNER } = {}) {
+  const repos = [];
+  let page = 1;
+
+  while (true) {
+    const response = await fetchPage(
+      `https://api.github.com/users/${owner}/repos?per_page=100&page=${page}&sort=updated`,
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to fetch template repos from GitHub: ${response.status}`);
     }
+    const payload = await response.json();
+    if (!Array.isArray(payload)) {
+      throw new Error("Unexpected GitHub response while listing template repos.");
+    }
+    const publicRepos = payload
+      .filter((repo) => !repo.private && typeof repo.name === "string")
+      .filter((repo) => repo.name.startsWith("template-"))
+      .map((repo) => ({
+        name: repo.name,
+        description: repo.description ?? "",
+        cloneUrl: repo.clone_url,
+        htmlUrl: repo.html_url,
+        defaultBranch: repo.default_branch || "main",
+      }));
+    repos.push(...publicRepos);
+    if (payload.length < 100) {
+      break;
+    }
+    page += 1;
   }
-  const destinationPath = path.join(destinationRoot, relativePath);
-  fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
-  fs.cpSync(sourcePath, destinationPath, {
-    recursive: true,
-    force: true,
-    filter: (source) => {
-      const baseName = path.basename(source);
-      return baseName !== ".git" && baseName !== "node_modules" && baseName !== "dist";
-    },
-  });
+
+  repos.sort((a, b) => a.name.localeCompare(b.name));
+  return repos;
+}
+
+export function resolveTemplateRepo(input, repos) {
+  const normalized = (input || "").trim();
+  if (!normalized) {
+    return null;
+  }
+
+  const exact = repos.find((repo) => repo.name === normalized);
+  if (exact) {
+    return exact;
+  }
+
+  const normalizedSuffix = normalized.startsWith("template-") ? normalized.slice(9) : normalized;
+  const matches = repos.filter((repo) => repo.name === `template-${normalizedSuffix}`);
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length > 1) {
+    throw new Error(`Ambiguous template repo: ${normalized}`);
+  }
+  throw new Error(`Template repo not found: ${normalized}`);
 }
 
-function writeFile(destinationPath, content) {
-  fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
-  fs.writeFileSync(destinationPath, content, "utf8");
+export function selectTemplateRepo(choice, repos) {
+  const normalized = (choice || "").trim();
+  if (!normalized) {
+    throw new Error("Missing template selection.");
+  }
+
+  if (/^\d+$/.test(normalized)) {
+    const index = Number.parseInt(normalized, 10) - 1;
+    if (index < 0 || index >= repos.length) {
+      throw new Error(`Invalid selection: ${normalized}`);
+    }
+    return repos[index];
+  }
+
+  return resolveTemplateRepo(normalized, repos);
 }
 
-function renderWorkspace(template) {
-  return `packages:\n  - client/${template}\n`;
+function ensurePnpm() {
+  if (commandExists("pnpm")) {
+    return ["pnpm"];
+  }
+  if (commandExists("corepack")) {
+    runCommand("corepack", ["enable"], { label: "Enabling corepack" });
+    return ["corepack", "pnpm"];
+  }
+  runCommand("npm", ["install", "-g", "pnpm"], { label: "Installing pnpm globally" });
+  return ["pnpm"];
 }
 
-function renderCompose(template) {
-  const config = TEMPLATE_CONFIG[template];
-  return `name: templates
-
-services:
-  postgres:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_DB: \${POSTGRES_DB:-template}
-      POSTGRES_USER: \${POSTGRES_USER:-template}
-      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:-template}
-    ports:
-      - "\${POSTGRES_PORT:-5432}:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          "pg_isready -U \${POSTGRES_USER:-template} -d \${POSTGRES_DB:-template}",
-        ]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    networks:
-      - template-dev
-
-  mysql:
-    image: mysql:8.4
-    profiles: ["mysql"]
-    environment:
-      MYSQL_DATABASE: \${MYSQL_DATABASE:-template}
-      MYSQL_USER: \${MYSQL_USER:-template}
-      MYSQL_PASSWORD: \${MYSQL_PASSWORD:-template}
-      MYSQL_ROOT_PASSWORD: \${MYSQL_ROOT_PASSWORD:-template-root}
-    ports:
-      - "\${MYSQL_PORT:-3306}:3306"
-    volumes:
-      - mysql_data:/var/lib/mysql
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          "mysqladmin ping -h 127.0.0.1 -u\${MYSQL_USER:-template} -p\${MYSQL_PASSWORD:-template}",
-        ]
-      interval: 10s
-      timeout: 5s
-      retries: 10
-      start_period: 20s
-    networks:
-      - template-dev
-
-  mariadb:
-    image: mariadb:11.7
-    profiles: ["mariadb"]
-    environment:
-      MARIADB_DATABASE: \${MARIADB_DATABASE:-template}
-      MARIADB_USER: \${MARIADB_USER:-template}
-      MARIADB_PASSWORD: \${MARIADB_PASSWORD:-template}
-      MARIADB_ROOT_PASSWORD: \${MARIADB_ROOT_PASSWORD:-template-root}
-    ports:
-      - "\${MARIADB_PORT:-3307}:3306"
-    volumes:
-      - mariadb_data:/var/lib/mysql
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          "mariadb-admin ping -h 127.0.0.1 -u\${MARIADB_USER:-template} -p\${MARIADB_PASSWORD:-template}",
-        ]
-      interval: 10s
-      timeout: 5s
-      retries: 10
-      start_period: 20s
-    networks:
-      - template-dev
-
-  mongo:
-    image: mongo:8
-    profiles: ["mongo"]
-    ports:
-      - "\${MONGO_PORT:-27017}:27017"
-    volumes:
-      - mongo_data:/data/db
-    networks:
-      - template-dev
-
-  server:
-    build:
-      context: .
-      dockerfile: server/Dockerfile.dev
-      network: host
-    environment:
-      APP_NAME: \${SERVER_APP_NAME:-Template Server}
-      ENVIRONMENT: \${SERVER_ENVIRONMENT:-development}
-      API_PREFIX: \${SERVER_API_PREFIX:-/api/v1}
-      DATABASE_BACKEND: \${SERVER_DATABASE_BACKEND:-postgres}
-      POSTGRES_URL: \${SERVER_POSTGRES_URL:-postgresql+psycopg://template:template@postgres:5432/template}
-      MYSQL_URL: \${SERVER_MYSQL_URL:-mysql+pymysql://template:template@mysql:3306/template}
-      MARIADB_URL: \${SERVER_MARIADB_URL:-mysql+pymysql://template:template@mariadb:3306/template}
-      MONGODB_URL: \${SERVER_MONGODB_URL:-mongodb://mongo:27017}
-      MONGODB_DATABASE: \${SERVER_MONGODB_DATABASE:-template}
-      JWT_SECRET: \${SERVER_JWT_SECRET:-template-local-dev-secret}
-      JWT_ALGORITHM: \${SERVER_JWT_ALGORITHM:-HS256}
-      ACCESS_TOKEN_TTL_MINUTES: \${SERVER_ACCESS_TOKEN_TTL_MINUTES:-120}
-      BOOTSTRAP_ADMIN_EMAIL: \${SERVER_BOOTSTRAP_ADMIN_EMAIL:-admin@example.com}
-      BOOTSTRAP_ADMIN_PASSWORD: \${SERVER_BOOTSTRAP_ADMIN_PASSWORD:-change-me-admin}
-      BOOTSTRAP_ADMIN_NAME: \${SERVER_BOOTSTRAP_ADMIN_NAME:-Template Admin}
-      BOOTSTRAP_OPERATOR_EMAIL: \${SERVER_BOOTSTRAP_OPERATOR_EMAIL:-operator@example.com}
-      BOOTSTRAP_OPERATOR_PASSWORD: \${SERVER_BOOTSTRAP_OPERATOR_PASSWORD:-change-me-operator}
-      BOOTSTRAP_OPERATOR_NAME: \${SERVER_BOOTSTRAP_OPERATOR_NAME:-Template Operator}
-      CORS_ORIGINS: '\${SERVER_CORS_ORIGINS:-["http://localhost:${config.defaultPort}","http://127.0.0.1:${config.defaultPort}"]}'
-      SERVER_HTTP_PORT: \${SERVER_HTTP_PORT:-8000}
-    ports:
-      - "\${SERVER_HTTP_PORT:-8000}:\${SERVER_HTTP_PORT:-8000}"
-    volumes:
-      - ./server:/app/server
-    depends_on:
-      postgres:
-        condition: service_healthy
-    networks:
-      - template-dev
-
-  ${config.serviceName}:
-    build:
-      context: .
-      dockerfile: client/${template}/Dockerfile.dev
-      network: host
-    environment:
-      PORT: \${${config.composePortVar}:-${config.defaultPort}}
-      VITE_API_BASE_URL: \${${config.composeApiVar}:-http://127.0.0.1:8000/api/v1}
-      CHOKIDAR_USEPOLLING: \${CLIENT_WATCH_USE_POLLING:-false}
-    ports:
-      - "\${${config.composePortVar}:-${config.defaultPort}}:\${${config.composePortVar}:-${config.defaultPort}}"
-    volumes:
-      - ./client/${template}:/app/client/${template}
-    depends_on:
-      server:
-        condition: service_started
-    networks:
-      - template-dev
-
-networks:
-  template-dev:
-    driver: bridge
-
-volumes:
-  postgres_data:
-  mysql_data:
-  mariadb_data:
-  mongo_data:
-`;
+function maybeCreateEnvFile(destinationRoot) {
+  const envExample = path.join(destinationRoot, ".env.example");
+  const envFile = path.join(destinationRoot, ".env");
+  if (fs.existsSync(envExample) && !fs.existsSync(envFile)) {
+    fs.copyFileSync(envExample, envFile);
+  }
 }
 
-function updateRepoContract(destinationRoot, template) {
-  const contractPath = path.join(
+function bootstrapScriptPath(destinationRoot) {
+  return path.join(
     destinationRoot,
-    "sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json",
+    "sdd/99_toolchain/01_automation/agentic-dev/bootstrap_frontend_parity.sh",
   );
-  const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"));
-  const selectedTarget = contract.frontend.targets[template];
-  contract.frontend.default_target = template;
-  contract.frontend.targets = {
-    [template]: selectedTarget,
-  };
-  contract.commands.verify_dev = `test -f "$PWD/${selectedTarget.proof_output}" && echo verify-dev-placeholder-ok`;
-  contract.artifacts.route_gap_output = selectedTarget.route_gap_output;
-  contract.artifacts.proof_output = selectedTarget.proof_output;
-  writeFile(contractPath, `${JSON.stringify(contract, null, 2)}\n`);
 }
 
-export function scaffoldTemplate({ destinationRoot, template }) {
-  validateTemplate(template);
+function detectClientSurfaces(destinationRoot) {
+  const clientDir = path.join(destinationRoot, "client");
+  if (!fs.existsSync(clientDir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(clientDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function validateTemplateRepoContents(destinationRoot, templateRepo) {
+  const requiredPaths = [
+    ".env.example",
+    "pnpm-workspace.yaml",
+    "sdd/99_toolchain/01_automation/agentic-dev/bootstrap_frontend_parity.sh",
+  ];
+
+  const missing = requiredPaths.filter(
+    (relativePath) => !fs.existsSync(path.join(destinationRoot, relativePath)),
+  );
+  if (missing.length > 0) {
+    throw new Error(
+      `Template repo ${templateRepo.name} is missing required files: ${missing.join(", ")}`,
+    );
+  }
+}
 
-  for (const relativePath of ROOT_FILES) {
-    copyPath(relativePath, destinationRoot);
+function runInstallSteps(destinationRoot) {
+  maybeCreateEnvFile(destinationRoot);
+  const clientSurfaces = detectClientSurfaces(destinationRoot);
+  if (clientSurfaces.length !== 1) {
+    throw new Error(`Expected exactly one client surface in template repo, found ${clientSurfaces.length}.`);
   }
-  for (const relativePath of ROOT_DIRS) {
-    copyPath(relativePath, destinationRoot);
+  const clientDir = path.join("client", clientSurfaces[0]);
+
+  const pnpmCommand = ensurePnpm();
+  runCommand(pnpmCommand[0], [...pnpmCommand.slice(1), "install"], {
+    cwd: destinationRoot,
+    label: "Installing workspace dependencies",
+  });
+
+  runCommand(
+    pnpmCommand[0],
+    [...pnpmCommand.slice(1), "--dir", clientDir, "exec", "playwright", "install", "chromium"],
+    {
+      cwd: destinationRoot,
+      label: "Installing Playwright Chromium",
+    },
+  );
+
+  return ["pnpm install", "pnpm exec playwright install chromium"];
+}
+
+function runBootstrapStep(destinationRoot) {
+  const bootstrapScript = bootstrapScriptPath(destinationRoot);
+  if (!fs.existsSync(bootstrapScript)) {
+    throw new Error(
+      `Missing bootstrap script in template repo: ${path.relative(destinationRoot, bootstrapScript)}`,
+    );
   }
 
-  copyPath(path.join("client", template), destinationRoot);
+  runCommand("bash", [bootstrapScript, "."], {
+    cwd: destinationRoot,
+    label: "Running frontend parity bootstrap",
+  });
 
-  writeFile(path.join(destinationRoot, "pnpm-workspace.yaml"), renderWorkspace(template));
-  writeFile(path.join(destinationRoot, "compose.yml"), renderCompose(template));
-  updateRepoContract(destinationRoot, template);
+  return ["bootstrap_frontend_parity.sh ."];
+}
 
+export function scaffoldFromTemplateRepo({ destinationRoot, templateRepo }) {
+  const cloneRoot = fs.mkdtempSync(path.join(os.tmpdir(), "agentic-dev-template-"));
+  const repoRoot = path.join(cloneRoot, templateRepo.name);
+
+  try {
+    runCommand("git", ["clone", "--depth", "1", templateRepo.cloneUrl, repoRoot], {
+      label: `Cloning ${templateRepo.name}`,
+    });
+    copyDirectoryContents(repoRoot, destinationRoot);
+  } finally {
+    fs.rmSync(cloneRoot, { recursive: true, force: true });
+  }
+}
+
+export function installTemplateRepo({
+  destinationRoot,
+  templateRepo,
+  skipBootstrap = false,
+}) {
+  scaffoldFromTemplateRepo({ destinationRoot, templateRepo });
+  validateTemplateRepoContents(destinationRoot, templateRepo);
+
+  const executedSteps = runInstallSteps(destinationRoot);
+  if (!skipBootstrap) {
+    executedSteps.push(...runBootstrapStep(destinationRoot));
+  }
+  const clientSurfaces = detectClientSurfaces(destinationRoot);
+  const bootstrapHint =
+    clientSurfaces.length === 1
+      ? `cd client/${clientSurfaces[0]} && npm run ui:parity:bootstrap`
+      : "npm run ui:parity:bootstrap";
   return {
     destinationRoot,
-    template,
-    nextSteps: [
-      "cp .env.example .env",
-      "npm install -g pnpm",
-      "pnpm install",
-      `cd client/${template} && npm run ui:parity:bootstrap`,
-    ],
+    templateRepo: templateRepo.name,
+    executedSteps,
+    nextSteps: skipBootstrap ? [bootstrapHint] : [],
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-dev",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "description": "Scaffold an agentic template repo with the selected frontend surface and shared toolchain assets.",
   "type": "module",
   "packageManager": "pnpm@10.32.0",
@@ -28,7 +28,7 @@
     "pnpm-workspace.yaml"
   ],
   "scripts": {
-    "smoke:init": "node ./bin/agentic-dev.mjs init ./.tmp-agentic-smoke --template web --yes --force"
+    "smoke:init": "node ./bin/agentic-dev.mjs init ./.tmp-agentic-smoke --template template-web --yes --force"
   },
   "keywords": [
     "agentic",

package/sdd/02_plan/03_architecture/repository_governance.md

@@ -36,4 +36,4 @@
 - current references:
   - `AGENTS.md`
   - `sdd/03_build/03_architecture/repository_governance.md`
-  - `sdd/04_verify/03_architecture/repository_governance.md`
+  - `sdd/03_verify/03_architecture/repository_governance.md`

package/sdd/02_plan/03_architecture/runtime_and_structure_governance.md

@@ -35,4 +35,4 @@
 - current references:
   - `sdd/01_planning/README.md`
   - `sdd/03_build/03_architecture/repository_governance.md`
-  - `sdd/04_verify/03_architecture/repository_governance.md`
+  - `sdd/03_verify/03_architecture/repository_governance.md`

package/sdd/02_plan/03_architecture/toolchain_governance.md

@@ -61,7 +61,7 @@
 - toolchain은 `sdd/99_toolchain/01_automation`, `02_policies`, `03_templates` current split을 따른다.
 - Playwright local exactness는 `run_playwright_exactness.py`와 `playwright_exactness_manifest.py`를 canonical entrypoint로 사용한다.
 - screen 작업은 가능하면 `npx playwright test ...`를 직접 쓰지 않고 toolchain runner를 통해 suite id 기준으로 실행한다.
-- proof artifact는 `sdd/04_verify/10_test/ui_parity/` current path를 기준으로 관리한다.
+- proof artifact는 `sdd/03_verify/10_test/ui_parity/` current path를 기준으로 관리한다.
 - toolchain 정책 문서의 정본은 `sdd/99_toolchain/02_policies`에 둔다.
 - skill/tooling 사용 여부는 개별 dated memo가 아니라 현재 workflow rule로만 유지한다.
 - 화면명세서의 icon/image/logo 등 재사용 가능한 정적 자산은 `spec_asset_builder.py` 또는 wrapper를 먼저 사용해 추출하고, 수동 재작성은 builder가 표현하지 못하는 경우에만 예외로 허용한다.
@@ -93,6 +93,6 @@
   - `sdd/99_toolchain/01_automation/playwright_exactness_manifest.py`
   - `sdd/99_toolchain/01_automation/run_playwright_exactness.py`
   - `sdd/02_plan/10_test/verification_strategy.md`
-  - `sdd/04_verify/10_test/verification_harness.md`
+  - `sdd/03_verify/10_test/verification_harness.md`
   - `sdd/99_toolchain/02_policies/regression-verification-policy.md`
   - `sdd/02_plan/10_test/regression_verification.md`

package/sdd/02_plan/06_iac/dev_runtime_delivery.md

@@ -33,4 +33,4 @@
 
 - current references:
   - `sdd/03_build/06_iac/dev_runtime_delivery.md`
-  - `sdd/04_verify/06_iac/dev_runtime_delivery.md`
+  - `sdd/03_verify/06_iac/dev_runtime_delivery.md`

package/sdd/02_plan/10_test/regression_verification.md

@@ -15,7 +15,7 @@
 ## Acceptance Criteria
 
 - [x] 회귀 검수는 direct target-only로 끝내지 않는다.
-- [x] selected regression surface는 `sdd/02_plan`, `sdd/03_build`, `sdd/04_verify`에 current-state로 이어진다.
+- [x] selected regression surface는 `sdd/02_plan`, `sdd/03_build`, `sdd/03_verify`에 current-state로 이어진다.
 - [x] automation gap은 scope 축소가 아니라 residual risk로 기록한다.
 
 ## Execution Checklist
@@ -36,4 +36,4 @@
   - `AGENTS.md`
   - `.codex/skills/sdd/SKILL.md`
   - `sdd/99_toolchain/01_automation/README.md`
-  - `sdd/04_verify/10_test/verification_harness.md`
+  - `sdd/03_verify/10_test/verification_harness.md`