@su-record/vibe 3.0.0 → 3.2.0

package/hooks/scripts/sentinel-guard.js

@@ -30,22 +30,6 @@ const SENTINEL_PATH_RE =
 const DANGEROUS_BASH_RE =
   /\b(rm\s+-rf|kill\s+-9|drop\s+table|truncate|shutdown|reboot|mkfs|dd\s+if=)\b/i;
 
-/**
- * Extract file path from tool input
- */
-function extractFilePath(toolName, input) {
-  if (!input) return null;
-  try {
-    const parsed = typeof input === 'string' ? JSON.parse(input) : input;
-    if (toolName === 'Write' || toolName === 'Edit' || toolName === 'Read') {
-      return parsed.file_path || parsed.filePath || null;
-    }
-  } catch {
-    return typeof input === 'string' ? input : null;
-  }
-  return null;
-}
-
 /**
  * Extract command from Bash tool input
  */
@@ -72,10 +56,11 @@ function isSentinelPath(filePath) {
 /**
  * Main guard logic
  */
-function guard(toolName, toolInput) {
+function guard(ctx) {
+  const { toolName, toolInput } = ctx;
   // Write/Edit targeting sentinel files → block
   if (toolName === 'Write' || toolName === 'Edit') {
-    const filePath = extractFilePath(toolName, toolInput);
+    const filePath = ctx.filePath;
     if (isSentinelPath(filePath)) {
       return {
         decision: 'block',
@@ -111,11 +96,11 @@ import { buildCliCtx, isDirectRun } from './lib/hook-context.js';
 
 /**
  * in-process 진입점 — 디스패처가 ctx를 전달해 직접 호출.
- * @param {{ toolName: string, toolInput: string }} ctx
+ * @param {{ toolName: string, toolInput: string, filePath: string }} ctx
  * @returns {Promise<number>} exit code (2 = deny 규약, 0 = allow)
  */
 export async function run(ctx) {
-  const result = guard(ctx.toolName, ctx.toolInput);
+  const result = guard(ctx);
   if (result) {
     logHookDecision('sentinel-guard', ctx.toolName, 'block', result.reason);
     console.log(JSON.stringify(result));

package/hooks/scripts/session-start.js

@@ -89,7 +89,7 @@ async function main() {
     // 인덱스만 주입 (harness-review-2026-07-01 P1-5):
     // 이전에는 startSession 전체 요약(git log·테스트 상태·관찰·리플렉션·RAG
     // goals/constraints/decisions)을 매 세션 덤프했다. 이제는 1줄 인덱스만
-    // 주입하고, 전체 컨텍스트 복원은 명시적 `/vibe.utils --continue` 전용.
+    // 주입하고, 전체 컨텍스트 복원은 명시적 `/vibe.continue` 전용.
     const [time, memories, latestVersion] = await Promise.all([
       timeModule.getCurrentTime({ format: 'human', timezone: 'Asia/Seoul' }),
       memoryModule.listMemories({ limit: 5, projectPath: PROJECT_DIR }),
@@ -104,7 +104,7 @@ async function main() {
       const iterMod = await import(`${LIB_BASE_P}IterationTracker.js`);
       const progressLine = iterMod.getProgressSummary(PROJECT_DIR);
       if (progressLine) {
-        console.log(`\n📋 ${progressLine} — resume full context: /vibe.utils --continue`);
+        console.log(`\n📋 ${progressLine} — resume full context: /vibe.continue`);
       }
     } catch { /* progress index is best-effort */ }
 

package/hooks/scripts/step-counter.js

@@ -25,6 +25,7 @@
 import fs from 'fs';
 import path from 'path';
 import { PROJECT_DIR, projectVibePath } from './utils.js';
+import { buildCliCtx } from './lib/hook-context.js';
 
 const METRICS_DIR = projectVibePath(PROJECT_DIR, 'metrics');
 const ANTI_PATTERNS_DIR = projectVibePath(PROJECT_DIR, 'anti-patterns');
@@ -44,36 +45,14 @@ const READ_ONLY_TOOLS = new Set([
   'TodoWrite', 'ToolSearch', 'ListMcpResourcesTool',
 ]);
 
-// ─────────────────────────────────────────────────────
-// stdin / env 에서 PostToolUse payload 추출
-// ─────────────────────────────────────────────────────
-function readStdinSync() {
-  try {
-    if (process.stdin.isTTY) return null;
-    const buf = Buffer.alloc(65536);
-    const bytesRead = fs.readSync(0, buf, 0, buf.length, null);
-    if (bytesRead > 0) return JSON.parse(buf.toString('utf-8', 0, bytesRead));
-  } catch { /* ignore */ }
-  return null;
-}
-
-function parseToolInput(raw) {
-  if (!raw) return {};
-  if (typeof raw === 'string') {
-    try { return JSON.parse(raw); } catch { return {}; }
-  }
-  return raw;
-}
-
-function extractTargetFile(toolInput) {
-  const fp = toolInput.file_path || toolInput.notebook_path || toolInput.path || null;
-  if (!fp) return null;
+function extractTargetFile(filePath) {
+  if (!filePath) return null;
   try {
-    const abs = path.isAbsolute(fp) ? fp : path.resolve(PROJECT_DIR, fp);
+    const abs = path.isAbsolute(filePath) ? filePath : path.resolve(PROJECT_DIR, filePath);
     const rel = path.relative(path.resolve(PROJECT_DIR), abs).replace(/\\/g, '/');
-    return rel || path.basename(fp);
+    return rel || path.basename(filePath);
   } catch {
-    return fp;
+    return filePath;
   }
 }
 
@@ -180,19 +159,18 @@ function bumpCounter(toolName, currentLineCount) {
 // 책임 2: current-run.jsonl append + error_category 채움
 // 항상 즉시 append — 스로틀 없음 (3-fail detector, recipe-extractor 가 소비)
 // ─────────────────────────────────────────────────────
-function appendJsonl(stdinPayload) {
-  const toolName = stdinPayload?.tool_name || process.argv[2] || '';
+function appendJsonl(ctx) {
+  const toolName = ctx.toolName;
   if (!toolName) return null;
 
-  const toolInput = parseToolInput(stdinPayload?.tool_input ?? process.env.TOOL_INPUT);
-  const ok = !isResponseError(stdinPayload?.tool_response);
-  const errorCategory = ok ? null : classifyError(stdinPayload?.tool_response);
+  const ok = !isResponseError(ctx.payload?.tool_response);
+  const errorCategory = ok ? null : classifyError(ctx.payload?.tool_response);
 
   const record = {
     ts: new Date().toISOString(),
     tool: toolName,
     ok,
-    target_file: extractTargetFile(toolInput),
+    target_file: extractTargetFile(ctx.filePath),
     error_category: errorCategory,
   };
 
@@ -214,18 +192,27 @@ function appendJsonl(stdinPayload) {
 }
 
 /**
- * jsonl 의 현재 라인 수를 반환 (stat 으로만 — 전체 파일 읽기 없음).
- * 경합 안전 — 정확한 값이 아니어도 스로틀 판단에 충분하다.
+ * current-run.jsonl 을 1회만 읽어 (a) 스로틀 판단용 총 라인 수와
+ * (b) 3-fail detector 용 최근 FAIL_WINDOW 줄을 함께 파생한다.
+ *
+ * 이전에는 jsonlLineCount()·readTailWindow() 가 각자 파일 전체를 다시 읽어
+ * 실패 이벤트마다 이벤트당 최대 2회 풀리드가 발생했다 — 여기서 1회로 통합.
+ * 파일은 회전 상한(2MB / MAX_JSONL_LINES)을 벗어나지 않도록 유지되므로
+ * (appendJsonl의 회전 로직 참고) 이 read 로도 기존과 동일하게 정확한 라인 수를
+ * 얻는다 — 스로틀/3-fail 판정 결과는 회전 상한 이내 파일에서 이전과 동일하다.
+ * @returns {{ lineCount: number, tail: object[] }}
  */
-function jsonlLineCount() {
+function readJsonlState() {
+  let lines;
   try {
-    // 라인 수 근사: 파일 크기 / 평균 라인 길이(100바이트) — 정확도 불필요
-    // 실제 라인 수는 appendJsonl 직후 여기서 읽으면 +1 반영됨
-    const content = fs.readFileSync(CURRENT_RUN_JSONL, 'utf-8');
-    return content.split('\n').filter(Boolean).length;
+    lines = fs.readFileSync(CURRENT_RUN_JSONL, 'utf-8').split('\n').filter(Boolean);
   } catch {
-    return 1; // 파일 없음 → 첫 이벤트로 간주
+    return { lineCount: 1, tail: [] }; // 파일 없음 → 첫 이벤트로 간주
   }
+  const tail = lines.slice(-FAIL_WINDOW).map((l) => {
+    try { return JSON.parse(l); } catch { return null; }
+  }).filter(Boolean);
+  return { lineCount: lines.length, tail };
 }
 
 // ─────────────────────────────────────────────────────
@@ -248,16 +235,7 @@ function fileSlug(targetFile) {
   return targetFile.replace(/[\/\.]/g, '-');
 }
 
-function readTailWindow() {
-  if (!fs.existsSync(CURRENT_RUN_JSONL)) return [];
-  const raw = fs.readFileSync(CURRENT_RUN_JSONL, 'utf-8').split('\n').filter(Boolean);
-  return raw.slice(-FAIL_WINDOW).map((l) => {
-    try { return JSON.parse(l); } catch { return null; }
-  }).filter(Boolean);
-}
-
-function detectThreeFail() {
-  const window = readTailWindow();
+function detectThreeFail(window) {
   const groups = new Map();
   for (const r of window) {
     if (r.ok || !r.error_category) continue;
@@ -318,8 +296,8 @@ try {
     fs.mkdirSync(METRICS_DIR, { recursive: true });
   }
 
-  const stdinPayload = readStdinSync();
-  const toolName = stdinPayload?.tool_name || process.argv[2] || '';
+  const ctx = buildCliCtx();
+  const toolName = ctx.toolName;
 
   // defense-in-depth: 읽기 전용 툴은 조기 종료 (matcher 단에서 이미 제거됨)
   if (toolName && READ_ONLY_TOOLS.has(toolName)) {
@@ -328,16 +306,16 @@ try {
 
   // 책임 2를 먼저 실행 — jsonl 라인 수가 bumpCounter 스로틀 판단에 쓰임
   let lastRecord = null;
-  try { lastRecord = appendJsonl(stdinPayload); } catch { /* 로깅 실패 무시 */ }
+  try { lastRecord = appendJsonl(ctx); } catch { /* 로깅 실패 무시 */ }
 
-  // 책임 1: jsonl append 후 라인 수로 스로틀 판단
-  const lineCount = jsonlLineCount();
+  // 책임 1: jsonl append 후 라인 수로 스로틀 판단 (책임 3의 tail window 와 1회 읽기 공유)
+  const { lineCount, tail } = readJsonlState();
   try { bumpCounter(toolName, lineCount); } catch { /* 카운터 실패 무시 */ }
 
   // 책임 3
   try {
     if (lastRecord && !lastRecord.ok && lastRecord.error_category) {
-      const trip = detectThreeFail();
+      const trip = detectThreeFail(tail);
       if (trip) writeAntiPattern(trip);
     }
   } catch { /* anti-pattern 작성 실패 무시 */ }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@su-record/vibe",
-  "version": "3.0.0",
-  "description": "AI Coding Framework for Claude Code — 10+ agents, 59 skills, multi-LLM orchestration",
+  "version": "3.2.0",
+  "description": "AI Coding Framework for Claude Code — 7+ agents, 60 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
   "exports": {
@@ -33,7 +33,7 @@
     "test:watch": "vitest",
     "prepublishOnly": "pnpm build",
     "postinstall": "node -e \"import('./dist/cli/postinstall/main.js').then(m=>m.main()).catch(()=>{})\"",
-    "release": "pnpm version patch && npm publish --access public"
+    "release": "pnpm version patch && git push origin main --follow-tags"
   },
   "keywords": [
     "ai",
@@ -58,6 +58,9 @@
     "type": "git",
     "url": "git+https://github.com/su-record/vibe.git"
   },
+  "bugs": {
+    "url": "https://github.com/su-record/vibe/issues"
+  },
   "homepage": "https://github.com/su-record/vibe#readme",
   "publishConfig": {
     "access": "public"
@@ -91,7 +94,6 @@
     "dist/",
     "vibe/",
     "languages/",
-    "commands/",
     "agents/",
     "skills/",
     "hooks/",

package/skills/clone/SKILL.md

@@ -24,8 +24,14 @@ The rendered DOM is the source of truth for markup. Screenshots are for pixel ve
 
 ```
 1. Do NOT generate CSS values by guessing or eyeballing screenshots.
-   ✅ Use clone-extract.js computed CSS output as-is.
-   ❌ Do NOT write CSS values directly inside scoped <style> blocks.
+   ✅ clone-to-scss.js output is a DRAFT (skeleton), not a frozen artifact. You MAY
+      rewrite SCSS values/selectors — but ONLY with evidence cited from computed.json /
+      states.json / behaviors.json (value correction, dedupe, selector restructuring).
+   ✅ clone-validate.js PASS is the sole judge of value correctness — not self-report.
+   ❌ Do NOT invent values with no extraction evidence ("looks like 18px" is forbidden).
+   ❌ Do NOT write CSS values directly inside scoped <style> blocks — style LOCATION
+      rule: all values live in styles/{feature}/ SCSS (value authority and style
+      location are separate rules; both hold).
 
 2. Do NOT hotlink remote assets. All images/fonts must be downloaded and rewritten.
 
@@ -34,6 +40,9 @@ The rendered DOM is the source of truth for markup. Screenshots are for pixel ve
 4. Do NOT copy textual content verbatim from copyrighted sources for production use.
    This skill is for layout/markup learning ("클론 코딩"). Replace text with placeholders
    or user-provided copy when shipping a real product.
+   Exception: `--real-content` — the user confirms (once, explicitly) they own the site
+   or have permission. Then keep text verbatim; clone-spec.js is invoked with
+   `--real-content` so specs mark copy as verbatim.
 
 5. Do NOT build a section without confirming its interaction model. The model in
    sections.json is a static-DOM heuristic — verify scroll-driven vs click-driven vs
@@ -42,10 +51,11 @@ The rendered DOM is the source of truth for markup. Screenshots are for pixel ve
 6. Do NOT ship default-state-only. Implement every harvested state (hover/focus/active/open/
    tab-switch) from states.json / the section spec.
 
-7. Do NOT ignore behaviors.json. The ACTIVE interaction sweep (scroll-state diffs +
-   click-driven tab content-swap detection) catches JS-set state that static CSS harvesting
-   is blind to. When the spec's "Dynamic behaviors" block conflicts with the static
-   interaction heuristic, the active capture wins.
+7. Do NOT ignore behaviors.json. The ACTIVE interaction sweep (scroll-state diffs,
+   click-driven tab content-swap detection, hover diffs, in-view entrance animations,
+   time-driven mutation candidates, smooth-scroll-lib detection) catches JS-set state
+   that static CSS harvesting is blind to. When the spec's "Dynamic behaviors" block
+   conflicts with the static interaction heuristic, the active capture wins.
 ```
 
 ## Full Flow
@@ -56,37 +66,20 @@ Input: a URL (or multiple URLs for multi-page clones)
 → Phase 0: Setup (stack detection, feature naming, working dir)
 → Phase 1: Capture (Puppeteer → rendered HTML + computed CSS + screenshots + assets)
 → Phase 2: Refine (DOM → sections.json per breakpoint; + interaction model + states)
-→ Phase 3: Scaffold (spec gate → SCSS auto-gen + Claude-authored HTML/components)
+→ Phase 2.5: Foundation (fonts / favicon / OG / SVG icons — sequential, before any section)
+→ Phase 3: Scaffold (spec gate → SCSS draft + builder dispatch, parallel per section)
+→ Phase 3C: Responsive merge (clone-merge-responsive.js — mobile-first @media)
 → Phase 4: Compile gate
-→ Phase 5: Pixel verification loop
-
-Working directory:
-  /tmp/{feature}/
-  ├── mo/ (375×812)  — rendered.html, computed.json, screenshot.png, assets/, sections.json
-  ├── pc/ (1440×900) — rendered.html, computed.json, screenshot.png, assets/, sections.json
-  └── tokens.json    — extracted design tokens (colors/fonts/spacing)
-
-Code output: placed directly in the project directory per detected stack
-  components/{feature}/, components/{feature}/_specs/, styles/{feature}/, public/images/{feature}/
+→ Phase 5: Pixel verification loop (BOTH viewports after merge)
 ```
 
+> Read `references/setup-and-layout.md` for the working-directory layout and code-output paths.
+
 ---
 
 ## Phase 0: Setup
 
-```
-1. Stack detection:
-   - .vibe/config.json → stack (react/vue/next/svelte/vanilla, scss/tailwind/css-modules)
-   - Fallback: package.json deps
-2. Feature name: URL hostname → kebab-case (e.g. stripe.com → stripe-clone)
-   - User may override with --name=<custom>
-3. Directories:
-   - components/{feature}/, styles/{feature}/, public/images/{feature}/
-4. Component indexing → /tmp/{feature}/component-index.json
-   (scan up to 50 existing components, extract props/slots/classes, within 2 minutes)
-5. Design token scan → /tmp/{feature}/project-tokens.json
-   (SCSS > CSS Variables > Tailwind > CSS-in-JS)
-```
+> Read `references/setup-and-layout.md` for the full Phase 0 setup steps (stack detection, feature naming, directories, component indexing, design token scan).
 
 ---
 
@@ -116,41 +109,7 @@ node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <URL> \
 ⛔ **Do NOT use WebFetch or curl** — they cannot render JS-driven SPAs.
 ✅ Use clone-extract.js. If output is unsatisfactory, modify the script.
 
-### Output per breakpoint
-
-```
-/tmp/{feature}/{bp}/
-  ├── rendered.html       — final DOM after JS execution
-  ├── computed.json       — per-element computed CSS + bounding box
-  ├── screenshot.png      — full-page screenshot
-  ├── states.json         — non-default state rules (hover/focus/active/checked/tab/aria/data-state)
-  ├── behaviors.json      — ACTIVE sweep: scroll-triggered header/nav diffs + click-driven tab groups
-  ├── assets/
-  │   ├── images/         — all <img>, background-image, <picture> sources
-  │   └── fonts/          — @font-face srcs
-  └── asset-map.json      — remote URL → local path mapping
-```
-
-### Capture rules
-
-```
-1. Wait for `networkidle2` (no in-flight requests for 500ms) before snapshot
-2. Scroll to bottom slowly to trigger lazy-loaded content
-3. Resolve all <img src>, srcset, and computed background-image URLs
-4. Resolve @font-face src() URLs from all stylesheets
-5. Download assets in parallel (concurrency=8), preserve original extensions
-6. Rewrite asset URLs in rendered.html and computed.json to local paths
-7. Strip inline analytics/tracking scripts before saving rendered.html
-8. Harvest non-default state rules from all stylesheets → states.json
-   (deterministic: read :hover/:focus/:active/:checked/[aria-*]/[data-state]/.is-*/.active/
-    .scrolled/.sticky/.pinned/… declarations straight from CSS — NO scripted clicking)
-9. ACTIVE interaction sweep → behaviors.json (runs after lazy-load, before freeze).
-   Drives the live page to capture JS-set state that CSS harvesting can't see:
-   - Scroll-state diff: tag sticky/fixed/top-bar headers+nav, snapshot computed CSS at
-     scroll 0, scroll past threshold, re-snapshot, diff → {prop: {from, to}, triggerScrollY}
-   - Tab groups: click tab-like sibling sets, detect whether content swaps on click
-   Disable with --no-interact (restores the old fully-deterministic, screenshot-stable capture).
-```
+> Read `references/capture-rules.md` for the full per-breakpoint output directory listing and the deterministic capture rule set (networkidle wait, asset resolution, states/behaviors harvesting, SEO asset harvest).
 
 ---
 
@@ -180,62 +139,26 @@ node {{VIBE_PATH}}/hooks/scripts/clone-refine.js \
 ⛔ **Do NOT parse rendered.html with custom Python/Node scripts.**
 ✅ Use clone-refine.js output as-is. If unsatisfactory, modify the script.
 
-### Refinement rules
+> Read `references/refine-rules.md` for the full refinement rule set and the sections.json output schema.
 
-```
-Refinement applied when converting rendered.html + computed.json → sections.json:
-  1. Strip <script>, <noscript>, <style>, tracking pixels
-  2. Strip nodes with display:none, visibility:hidden, opacity:0, size 0
-  3. Detect sections: <header>, <nav>, top-level <section>/<main> children, <footer>
-     Fallback: top-level children of <body> with height > 100px
-  4. Detect repeated patterns (sibling nodes with same tag+class signature, count >= 3)
-     → mark as component candidates
-  5. Extract design tokens:
-     - colors: unique color/background-color values, sorted by frequency
-     - typography: font-family/size/weight combinations
-     - spacing: padding/margin values (px), bucketed to nearest 4px
-  6. Background images (background-image: url) → images.bg
-  7. Inline <img> → images.content
-  8. Keep CSS subset: layout (display/flex/grid/position/inset/margin/padding/width/height/gap),
-     typography (font-*, line-height, letter-spacing, text-*, color),
-     decoration (background, border, border-radius, box-shadow, opacity),
-     transform/transition
-  9. Classify interaction model per section (static-DOM heuristic) → section.interaction
-     = { model, confidence, signals[], note }. model ∈ static | click-driven | scroll-driven
-     | time-driven | hover. This is a best-guess + ranked SIGNALS, NOT a silent decision —
-     the builder confirms it against the live site (Phase 5). Misidentifying the interaction
-     model is the #1 clone failure mode (scroll-driven original built as a click UI, etc.).
- 10. Attach matching state rules from states.json to each section → section.states
-     (rules whose selector references a class/leaf-tag inside that section's subtree)
-```
+---
 
-### Output
+## Phase 2.5: Foundation ← sequential, BEFORE any section build
+
+Nothing renders right until the foundation exists. Do this yourself (not delegated) — it
+touches shared files:
 
 ```
-/tmp/{feature}/{bp}/sections.json:
-  {
-    meta: { feature, url, viewport, bp },
-    tokens: { colors: [...], typography: [...], spacing: [...] },
-    sections: [
-      {
-        name: "Header" | "Hero" | "Features" | ...,
-        nodeRef, tag, size, css,
-        interaction: {        // static-DOM heuristic — builder confirms in Phase 5
-          model: "static" | "click-driven" | "scroll-driven" | "time-driven" | "hover",
-          confidence: "high" | "medium" | "low",
-          signals: [...],     // ranked evidence (sticky, infinite animation, role=tab, …)
-          note
-        },
-        text,                 // text content (placeholder candidates)
-        components: [...],    // detected repeated patterns
-        states: [             // non-default state rules scoped to this section
-          { selector, media, css }
-        ],
-        children: [...],      // full recursive subtree
-        images: { bg, content: [...] }
-      }
-    ]
-  }
+1. Fonts: verify _base.scss @font-face srcs point at downloaded assets/fonts/ files.
+   Next.js stack → wire via next/font/local in the layout instead of raw @font-face.
+2. Favicon / OG / manifest: copy assets/seo/* → public/ (project convention path),
+   wire metadata (layout.tsx metadata / <head>) to the local files.
+3. SVG icons: collect inline <svg> from rendered.html, dedupe by path data,
+   emit one stack-appropriate icon module (e.g. components/{feature}/icons.tsx).
+   Name by visual function (SearchIcon, ArrowRightIcon, LogoIcon).
+4. Global behaviors from behaviors.json: scrollLib detected → install/wire page-level
+   (Lenis etc.); global keyframes/scroll-snap → styles/{feature}/_shared.scss.
+5. Verify: compile passes before moving on.
 ```
 
 ---
@@ -251,81 +174,57 @@ Refinement applied when converting rendered.html + computed.json → sections.js
 # Step 0: Generate per-section build-contract specs (run once per BP)
 node {{VIBE_PATH}}/hooks/scripts/clone-spec.js \
   /tmp/{feature}/{bp}/sections.json \
-  --out=/path/to/project/components/{feature}/_specs/ \
-  --feature={feature}
+  --out=/path/to/project/components/{feature}/_specs/{bp}/ \
+  --feature={feature} [--real-content]
 
-# Step A: Auto-generate SCSS skeleton (run once per BP)
+# Step A: Auto-generate SCSS draft (run once per BP — note the per-BP out dir)
 node {{VIBE_PATH}}/hooks/scripts/clone-to-scss.js \
   /tmp/{feature}/{bp}/sections.json \
-  --out=/path/to/project/styles/{feature}/ \
+  --out=/path/to/project/styles/{feature}/{bp}/ \
   --token-file=/tmp/{feature}/project-tokens.json
 
 # Step B: Per-section validation (after writing each section's component code)
 node {{VIBE_PATH}}/hooks/scripts/clone-validate.js \
-  /path/to/project/styles/{feature}/ \
+  /path/to/project/styles/{feature}/{bp}/ \
   /tmp/{feature}/{bp}/sections.json \
   --section={SectionName}
 ```
 
 ⛔ **No section is built without a completed spec.** Step 0 emits `_specs/{Section}.spec.md`
-   (interaction model + **active-capture Dynamic behaviors** + states + computed CSS + assets +
-   text + checklist). clone-spec.js auto-loads `behaviors.json` from the sections.json dir and
-   attaches matching scroll/tab behaviors per section. Before writing a
-   section's component, Claude reviews its spec and resolves every `TODO` (confirm interaction
-   model, list states to implement, choose tags, replace copyrighted text). The spec is the
-   contract AND the audit trail — it forces extraction rigor before any code is written.
-⛔ **Writing SCSS files directly without calling clone-to-scss.js invalidates Phase 3.**
+   (interaction model + **active-capture Dynamic behaviors** (scroll/tab/hover/in-view/
+   time-driven/scroll-lib) + states + computed CSS + assets + text + checklist).
+   clone-spec.js auto-loads `behaviors.json` from the sections.json dir and attaches matching
+   behaviors per section. Before dispatching a section's builder, Claude reviews its spec and
+   resolves every `TODO` (confirm interaction model, list states to implement, choose tags,
+   replace copyrighted text — skipped with --real-content). The spec is the contract AND the
+   audit trail — it forces extraction rigor before any code is written.
+⛔ **clone-to-scss.js must run first (Step A) — its output is the DRAFT every section starts
+   from.** After that, SCSS edits are allowed per Immutable Rule 1 (evidence-cited only);
+   clone-validate.js PASS is the judge.
 ⛔ **Do NOT write custom SCSS / spec generation scripts.**
-⛔ **Do NOT proceed to the next section without a clone-validate.js PASS.**
-✅ Use clone-spec.js / clone-to-scss.js output as-is. If unsatisfactory, modify the script.
+⛔ **Do NOT proceed past a section without a clone-validate.js PASS for it.**
 
-```
-Phase 3A: MO Scaffold
+Phase 3A: MO Scaffold — parallel builder dispatch
   Input: /tmp/{feature}/mo/sections.json
-  Step 0 once: clone-spec.js → emit _specs/{Section}.spec.md for every section
-  ⛔ No parallelism. Process one section at a time:
-    1. Read the target section's spec → resolve every TODO:
-       ├─ Confirm the interaction model (spec.interaction is a heuristic guess)
-       ├─ List the states to implement (spec.states)
-       └─ Mark copyrighted text for placeholder replacement
-    2. Map component candidates against component-index.json
-       ├─ Match → import existing
-       └─ No match → create new in components/{feature}/
-    3. clone-to-scss.js → auto-generate SCSS skeleton (computed values as-is) — Step A once
-    4. Claude: HTML structure + semantic tags + framework-specific component file
-       ⛔ No CSS written directly in <style> blocks — only @import/@use allowed
-       ⛔ Build for the CONFIRMED interaction model (don't build a click UI for a
-          scroll-driven original); wire every state from the spec (hover/active/open/…)
-       Framework mapping:
-         - React/Next → .tsx with CSS Modules or styled-components per stack
-         - Vue/Nuxt   → .vue with scoped <style lang="scss"> @import only
-         - Svelte     → .svelte with <style> @import only
-         - Vanilla    → .html + linked .scss
-    5. Asset references → public/images/{feature}/ (already populated in Phase 1)
-    6. clone-validate.js → compare SCSS vs sections.json — Step B
-       ├─ PASS → next section
-       └─ FAIL → fix discrepancies → re-run step 6 (loop until P1=0, no round cap)
   → Phase 4 (MO compile) → Phase 5 (MO pixel verification)
 
 Phase 3B: PC Scaffold
-  Same process as MO, input /tmp/{feature}/pc/sections.json
+  Same process as MO, input /tmp/{feature}/pc/sections.json → styles/{feature}/pc/
   → Phase 4 (PC compile) → Phase 5 (PC pixel verification)
 
-Phase 3C: Responsive Integration (after both MO+PC pass verification)
-  → Merge MO+PC styles into @media-based responsive layout (separate flow, TODO)
-
-Claude's role (restricted):
-  ✅ Component candidates: decide which patterns become reusable components
-  ✅ HTML semantics: section/h1/p/button/nav tag selection
-  ✅ Text replacement: substitute copyrighted copy with placeholders or user-supplied text
-  ✅ Interaction model: confirm the spec's heuristic guess, then build for the real model
-  ✅ Interactions: implement every state in the spec (hover/focus/active/open), click handlers
-  ❌ Do NOT modify SCSS CSS values (use clone-to-scss.js output as-is)
-  ❌ Do NOT write CSS directly in <style> blocks
-  ❌ Do NOT use vw/clamp/@media or create custom mixins in Phase 3A/3B
-  ❌ Do NOT hotlink remote URLs — all assets must use local public/images/ paths
+Phase 3C: Responsive Integration (after both MO+PC pass Phase 5)
+  1. node {{VIBE_PATH}}/hooks/scripts/clone-merge-responsive.js \
+       --mo=/path/to/project/styles/{feature}/mo/ \
+       --pc=/path/to/project/styles/{feature}/pc/ \
+       --out=/path/to/project/styles/{feature}/ \
+       [--breakpoint=1024]
+     → mobile-first merge: MO declarations = base, PC diffs → @media (min-width) block
+  → Phase 4 (compile) → Phase 5 at BOTH viewports against each BP's screenshot.
+     ⛔ The clone is NOT complete until the MERGED build passes Phase 5 at both.
 ```
 
+> Read `references/scaffold-phases.md` for the full Phase 3A prep/dispatch/merge builder contract (framework mapping, 150-line split rule, clone-validate.js PASS/FAIL loop detail), Phase 3C steps 2–3 (import switch, pc-only/mo-only selector review), and Claude's role checklist.
+
 ---
 
 ## Phase 4: Compile Gate
@@ -382,6 +281,9 @@ Termination:
   ultrawork mode: on stuck, record TODO without prompting and complete
 
 Responsive: after MO verification → change viewport → repeat against PC screenshot
+Post-merge (Phase 3C): re-run at BOTH viewports (375×812 vs mo/screenshot.png,
+  1440×900 vs pc/screenshot.png) — either failing means the merge regressed; fix the
+  merged SCSS (evidence: the per-BP sections.json), never by re-guessing values
 Cleanup: shut down browser + dev server
 
 ⛔ "Completion summary" output only allowed after Phase 5 completes.
@@ -389,37 +291,6 @@ Cleanup: shut down browser + dev server
 
 ---
 
-## Legal & Ethical Notes
-
-```
-This skill is intended for:
-  ✅ "Clone coding" learning exercises (markup/layout study)
-  ✅ Rebuilding the user's own previously-deployed sites
-  ✅ Authorized redesigns where the user has rights to the source
-
-NOT intended for:
-  ❌ Republishing copyrighted content (text, images, logos) without permission
-  ❌ Deceptive look-alike sites (phishing, brand impersonation)
-  ❌ Bypassing robots.txt or rate-limiting protections
-
-Claude must:
-  - Replace copyrighted text content with placeholders (e.g. "[Lorem ipsum]") by default
-  - Skip and warn when robots.txt disallows fetching the target path
-  - Refuse if the user's stated intent is brand impersonation or deception
-```
-
----
+## Legal, Ethical & Error Recovery Reference
 
-## Error Recovery
-
-| Failure | Recovery |
-|---------|----------|
-| clone-extract.js Puppeteer launch failure | Verify Node ≥18 and that Chromium is installed (`npx puppeteer browsers install chrome`). Retry once. |
-| Target site blocks headless (403/Cloudflare) | Retry with `--stealth` flag (uses puppeteer-extra stealth plugin). If still blocked, report to user. |
-| Asset download 404 | Log to asset-map.json with `status: missing`. Use a 1×1 transparent placeholder. Continue. |
-| robots.txt disallows path | Halt Phase 1. Inform user; require explicit `--ignore-robots` flag to proceed. |
-| clone-refine.js produces empty sections | Site likely uses Shadow DOM or canvas rendering. Report and ask whether to fall back to screenshot-only mode. |
-| Pixel diff stuck > 0.05 after 5 rounds | Likely font fallback or anti-aliasing. Report metric, allow user to accept threshold. |
-| Interaction model guess wrong (Phase 5) | section.interaction is a static-DOM heuristic. Re-observe the live site, correct the model in the spec, rebuild the section for the confirmed model. |
-| states.json empty but site has hover/tabs | States may be set via inline JS, not CSS rules. Check behaviors.json (active sweep captures scroll/tab JS state). If still missing, note in the spec and capture manually during Phase 5. |
-| behaviors.json missing or empty | Active sweep was disabled (--no-interact), hit no sticky/tab elements, or errored (logged, non-fatal). Falls back to static states.json. Re-run without --no-interact to retry. |
+> Read `references/legal-and-error-recovery.md` for the full legal/ethical usage notes (intended use, prohibited use, --real-content flow) and the Error Recovery troubleshooting table.