@su-record/vibe 3.0.0 → 3.1.0

package/hooks/scripts/clone-merge-responsive.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+/**
+ * clone-merge-responsive.js — MO/PC per-BP SCSS → mobile-first responsive merge
+ *
+ * Usage:
+ *   node clone-merge-responsive.js --mo=<styles-dir> --pc=<styles-dir> --out=<dir> [--breakpoint=1024]
+ *
+ * Why this exists (clone Phase 3C):
+ *   Phase 3A/3B produce two fixed-viewport SCSS trees (styles/{feature}/mo, /pc).
+ *   This merges them mobile-first: MO declarations become the base, and only the
+ *   declarations where PC differs go into a single @media (min-width: <bp>) block.
+ *   Deterministic text merge — no value invention. Post-merge correctness is judged
+ *   by Phase 5 (pixel + computed-CSS verification at BOTH viewports).
+ *
+ * Fail-open:
+ *   - PC-only selectors → whole rule inside the media block
+ *   - MO-only selectors → base as-is (reported)
+ *   - unparseable/missing files → reported and skipped, never a hard abort
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { parseScss, normalize } from './clone-validate.js';
+
+// ─── CLI ────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const opts = { breakpoint: 1024 };
+  for (const a of argv.slice(2)) {
+    if (a.startsWith('--mo=')) opts.mo = a.slice(5);
+    else if (a.startsWith('--pc=')) opts.pc = a.slice(5);
+    else if (a.startsWith('--out=')) opts.out = a.slice(6);
+    else if (a.startsWith('--breakpoint=')) opts.breakpoint = Number(a.slice(13)) || 1024;
+  }
+  return opts;
+}
+
+// ─── Merge core (pure — exported for tests) ─────────────────────────
+// moRules/pcRules: Map<selector, {prop: value}> (parseScss output)
+// → { base: Map, media: Map, stats }
+function mergeRules(moRules, pcRules) {
+  const base = new Map();
+  const media = new Map();
+  const stats = { selectors: 0, moOnly: 0, pcOnly: 0, overrides: 0, shared: 0 };
+
+  const selectors = new Set([...moRules.keys(), ...pcRules.keys()]);
+  for (const sel of selectors) {
+    stats.selectors++;
+    const mo = moRules.get(sel);
+    const pc = pcRules.get(sel);
+    if (mo && Object.keys(mo).length) base.set(sel, mo);
+
+    if (!pc || !Object.keys(pc).length) { if (mo) stats.moOnly++; continue; }
+    if (!mo || !Object.keys(mo).length) {
+      // PC 전용 셀렉터 — 데스크탑에서만 존재하는 노드
+      media.set(sel, pc);
+      stats.pcOnly++;
+      continue;
+    }
+
+    const diff = {};
+    for (const [prop, val] of Object.entries(pc)) {
+      if (mo[prop] === undefined || normalize(mo[prop]) !== normalize(val)) diff[prop] = val;
+    }
+    if (Object.keys(diff).length) { media.set(sel, diff); stats.overrides++; }
+    else stats.shared++;
+  }
+  return { base, media, stats };
+}
+
+function emitRules(rules, indent) {
+  const out = [];
+  for (const [sel, decls] of rules) {
+    const body = Object.entries(decls).map(([p, v]) => `${indent}  ${p}: ${v};`).join('\n');
+    if (!body) continue;
+    out.push(`${indent}${sel} {\n${body}\n${indent}}`);
+  }
+  return out.join('\n\n');
+}
+
+// Merged partial: MO base rules + one @media (min-width) block with PC diffs.
+function emitMerged(moRules, pcRules, breakpoint, header) {
+  const { base, media, stats } = mergeRules(moRules, pcRules);
+  const parts = [header, '', emitRules(base, '')];
+  if (media.size) {
+    parts.push('');
+    parts.push(`@media (min-width: ${breakpoint}px) {`);
+    parts.push(emitRules(media, '  '));
+    parts.push('}');
+  }
+  return { scss: parts.filter((p) => p !== null).join('\n') + '\n', stats };
+}
+
+// ─── File-level orchestration ───────────────────────────────────────
+function readScssRules(file) {
+  if (!fs.existsSync(file)) return null;
+  try { return parseScss(fs.readFileSync(file, 'utf8')); }
+  catch (e) {
+    console.error(`[clone-merge] parse skipped (${e.message}): ${file}`);
+    return null;
+  }
+}
+
+function listSections(dir) {
+  const d = path.join(dir, 'sections');
+  if (!fs.existsSync(d)) return [];
+  return fs.readdirSync(d).filter((f) => f.startsWith('_') && f.endsWith('.scss'));
+}
+
+function mergeTokens(moDir, pcDir, outDir, breakpoint) {
+  const mo = readScssRules(path.join(moDir, '_tokens.scss')) || new Map();
+  const pc = readScssRules(path.join(pcDir, '_tokens.scss')) || new Map();
+  const { scss } = emitMerged(mo, pc, breakpoint, '// Auto-merged by clone-merge-responsive.js (mobile-first)');
+  fs.writeFileSync(path.join(outDir, '_tokens.scss'), scss);
+}
+
+function copyIfExists(src, dst) {
+  if (fs.existsSync(src)) fs.copyFileSync(src, dst);
+}
+
+function mergeClassPlans(moDir, pcDir, outDir) {
+  const read = (d) => {
+    const f = path.join(d, 'class-plan.json');
+    return fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, 'utf8')) : {};
+  };
+  // MO 우선 — 동일 노드 id가 다른 클래스면 MO가 base이므로 MO를 채택
+  const merged = { ...read(pcDir), ...read(moDir) };
+  fs.writeFileSync(path.join(outDir, 'class-plan.json'), JSON.stringify(merged, null, 2));
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  if (!opts.mo || !opts.pc || !opts.out) {
+    console.error('Usage: node clone-merge-responsive.js --mo=<styles-dir> --pc=<styles-dir> --out=<dir> [--breakpoint=1024]');
+    process.exit(2);
+  }
+
+  fs.mkdirSync(path.join(opts.out, 'sections'), { recursive: true });
+
+  const files = [...new Set([...listSections(opts.mo), ...listSections(opts.pc)])].sort();
+  const totals = { selectors: 0, moOnly: 0, pcOnly: 0, overrides: 0, shared: 0 };
+  const merged = [];
+
+  for (const f of files) {
+    const mo = readScssRules(path.join(opts.mo, 'sections', f)) || new Map();
+    const pc = readScssRules(path.join(opts.pc, 'sections', f)) || new Map();
+    if (!mo.size && !pc.size) { console.error(`[clone-merge] empty on both BPs, skipped: ${f}`); continue; }
+    const { scss, stats } = emitMerged(mo, pc, opts.breakpoint, `// Section: ${f} — merged mobile-first`);
+    fs.writeFileSync(path.join(opts.out, 'sections', f), scss);
+    for (const k of Object.keys(totals)) totals[k] += stats[k];
+    merged.push(f);
+  }
+
+  mergeTokens(opts.mo, opts.pc, opts.out, opts.breakpoint);
+  copyIfExists(path.join(opts.mo, '_base.scss'), path.join(opts.out, '_base.scss'));
+  copyIfExists(path.join(opts.mo, '_shared.scss'), path.join(opts.out, '_shared.scss'));
+  mergeClassPlans(opts.mo, opts.pc, opts.out);
+
+  const index = [
+    '// Auto-merged by clone-merge-responsive.js — mobile-first responsive',
+    '',
+    `@use './tokens';`,
+    `@use './base';`,
+    `@use './shared';`,
+    ...merged.map((f) => `@use './sections/${f.replace(/^_|\.scss$/g, '')}';`),
+  ].join('\n') + '\n';
+  fs.writeFileSync(path.join(opts.out, 'index.scss'), index);
+
+  console.log(`[clone-merge] done → ${opts.out}`);
+  console.log(`  sections: ${merged.length}, selectors: ${totals.selectors} (shared ${totals.shared}, overrides ${totals.overrides}, mo-only ${totals.moOnly}, pc-only ${totals.pcOnly})`);
+  console.log(`  breakpoint: @media (min-width: ${opts.breakpoint}px)`);
+}
+
+const isMain = process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('clone-merge-responsive.js');
+if (isMain) {
+  try { main(); }
+  catch (e) {
+    console.error(`[clone-merge] FAIL: ${e.message}`);
+    if (process.env.DEBUG) console.error(e.stack);
+    process.exit(1);
+  }
+}
+
+export { mergeRules, emitMerged };

package/hooks/scripts/clone-spec.js

@@ -28,6 +28,7 @@ function parseArgs(argv) {
     else if (a.startsWith('--section=')) opts.section = a.slice(10);
     else if (a.startsWith('--feature=')) opts.feature = a.slice(10);
     else if (a.startsWith('--behaviors=')) opts.behaviors = a.slice(12);
+    else if (a === '--real-content') opts.realContent = true;
   }
   return { sectionsPath, opts };
 }
@@ -101,20 +102,28 @@ function sectionHasNode(section, tag, cls) {
   return (section.children || []).some(hit);
 }
 
+function diffLines(changed) {
+  return Object.entries(changed)
+    .map(([k, v]) => `    - ${k}: \`${v.from}\` → \`${v.to}\``).join('\n');
+}
+
 function behaviorsBlock(section, behaviors) {
   if (!behaviors) return null;
-  const scroll = (behaviors.scroll || []).filter((b) => sectionHasNode(section, b.tag, b.cls));
+  const inSection = (list) => (list || []).filter((b) => sectionHasNode(section, b.tag, b.cls));
+  const scroll = inSection(behaviors.scroll);
+  const hover = inSection(behaviors.hover);
+  const inview = inSection(behaviors.inview);
+  const timed = inSection(behaviors.timeDriven);
   // Tab groups aren't tag-keyed; attach to any section that contains a [role=tab]-ish node.
   const tabs = (behaviors.interactive || []).filter(() =>
     sectionHasNode(section, 'button') || sectionHasNode(section, 'li') || sectionHasNode(section, 'a'),
   );
-  if (!scroll.length && !tabs.length) return null;
+  const lib = behaviors.scrollLib;
+  if (!scroll.length && !tabs.length && !hover.length && !inview.length && !timed.length && !lib) return null;
 
   const lines = [];
   for (const b of scroll) {
-    const diffs = Object.entries(b.changed)
-      .map(([k, v]) => `    - ${k}: \`${v.from}\` → \`${v.to}\``).join('\n');
-    lines.push(`- **Scroll-triggered** on \`${b.label}\` (past ~${b.triggerScrollY}px scroll):\n${diffs}`);
+    lines.push(`- **Scroll-triggered** on \`${b.label}\` (past ~${b.triggerScrollY}px scroll):\n${diffLines(b.changed)}`);
   }
   for (const t of tabs) {
     const labels = (t.tabLabels || []).map((l) => `"${l}"`).join(', ') || '(unlabeled)';
@@ -123,6 +132,19 @@ function behaviorsBlock(section, behaviors) {
       : 'no content swap detected (styling-only tabs)';
     lines.push(`- **Tab group** ×${t.count} [${labels}]: ${swap}`);
   }
+  for (const b of hover) {
+    const tr = b.transition && b.transition !== 'all 0s ease 0s' ? ` (transition: \`${b.transition}\`)` : '';
+    lines.push(`- **Hover** on \`${b.label}\`${tr}:\n${diffLines(b.changed)}`);
+  }
+  for (const b of inview) {
+    lines.push(`- **In-view entrance** on \`${b.label}\` (enters at ~${b.triggerY}px):\n${diffLines(b.changed)}`);
+  }
+  for (const b of timed) {
+    lines.push(`- **Time-driven** \`${b.label}\` — ${b.mutations} mutations/3s [${(b.kinds || []).join(', ')}] → carousel/auto-cycle candidate`);
+  }
+  if (lib) {
+    lines.push(`- **Smooth-scroll library (page-level):** ${lib.name} (evidence: \`${lib.evidence}\`) → wire in globals, not per-section`);
+  }
   return lines.join('\n');
 }
 
@@ -171,7 +193,9 @@ ${cssBlock(section.css)}
 ## Assets (local paths only — never hotlink)
 ${assetsBlock(section.images)}
 
-## Text content (replace copyrighted copy with placeholders)
+## Text content ${meta.realContent
+    ? '(verbatim — user confirmed rights to reuse this copy)'
+    : '(replace copyrighted copy with placeholders)'}
 ${textBlock}
 
 ## Component candidates
@@ -179,7 +203,7 @@ ${componentsBlock(section.components)}
 
 ## Build checklist
 - [ ] HTML semantics + final tags chosen
-- [ ] SCSS via clone-to-scss.js (computed values as-is — no eyeballing)
+- [ ] SCSS started from the clone-to-scss.js draft — value edits only with evidence cited from computed.json/states.json/behaviors.json (no eyeballing); clone-validate.js is the judge
 - [ ] Every state above implemented
 - [ ] Interaction model confirmed on live site & wired
 - [ ] All assets local (public/images/${meta.feature}/) — no hotlinks
@@ -196,6 +220,7 @@ function main() {
     url: data.meta && data.meta.url,
     viewport: data.meta && data.meta.viewport,
     bp: opts.section ? (data.meta && data.meta.bp) : (data.meta && data.meta.bp) || '?',
+    realContent: !!opts.realContent,
   };
   // behaviors.json (active interaction sweep) lives next to the source computed.json.
   const behaviorsPath = opts.behaviors || path.join(path.dirname(sectionsPath), 'behaviors.json');
@@ -223,7 +248,7 @@ function main() {
 const isMain = process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('clone-spec.js');
 if (isMain) {
   if (!sectionsPath || !opts.out) {
-    console.error('Usage: node clone-spec.js <sections.json> --out=<dir> [--section=Name] [--feature=name] [--behaviors=path]');
+    console.error('Usage: node clone-spec.js <sections.json> --out=<dir> [--section=Name] [--feature=name] [--behaviors=path] [--real-content]');
     process.exit(1);
   }
   try { main(); }

package/hooks/scripts/clone-validate.js

@@ -34,10 +34,6 @@ function parseArgs(argv) {
 }
 
 const { stylesDir, sectionsPath, opts } = parseArgs(process.argv);
-if (!stylesDir || !sectionsPath) {
-  console.error('Usage: node clone-validate.js <styles-dir> <sections.json> [--section=<name>]');
-  process.exit(2);
-}
 
 // ─── Minimal SCSS parser ────────────────────────────────────────────
 // Strips comments, expands `&::pseudo` (one level), flattens nested rules.
@@ -272,9 +268,19 @@ function main() {
   process.exit(0);
 }
 
-try { main(); }
-catch (e) {
-  console.error(`[clone-validate] FAIL: ${e.message}`);
-  if (process.env.DEBUG) console.error(e.stack);
-  process.exit(2);
+// isMain 가드 — clone-merge-responsive.js가 parseScss를 import할 때 main()이 돌면 안 된다
+const isMain = process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('clone-validate.js');
+if (isMain) {
+  if (!stylesDir || !sectionsPath) {
+    console.error('Usage: node clone-validate.js <styles-dir> <sections.json> [--section=<name>]');
+    process.exit(2);
+  }
+  try { main(); }
+  catch (e) {
+    console.error(`[clone-validate] FAIL: ${e.message}`);
+    if (process.env.DEBUG) console.error(e.stack);
+    process.exit(2);
+  }
 }
+
+export { parseScss, normalize, compareValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "AI Coding Framework for Claude Code — 10+ agents, 59 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
@@ -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"

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,9 +66,11 @@ 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
+→ Phase 5: Pixel verification loop (BOTH viewports after merge)
 
 Working directory:
   /tmp/{feature}/
@@ -67,7 +79,9 @@ Working directory:
   └── 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}/
+  components/{feature}/, components/{feature}/_specs/{mo,pc}/,
+  styles/{feature}/{mo,pc}/ (per-BP drafts) → styles/{feature}/ (Phase 3C merged),
+  public/images/{feature}/, public/ (favicons/OG from assets/seo/)
 ```
 
 ---
@@ -124,10 +138,11 @@ node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <URL> \
   ├── 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
+  ├── behaviors.json      — ACTIVE sweep: scroll / tab / hover / in-view / time-driven + scrollLib
   ├── assets/
   │   ├── images/         — all <img>, background-image, <picture> sources
-  │   └── fonts/          — @font-face srcs
+  │   ├── fonts/          — @font-face srcs
+  │   └── seo/            — favicons, apple-touch-icons, OG images, webmanifest
   └── asset-map.json      — remote URL → local path mapping
 ```
 
@@ -149,7 +164,15 @@ node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <URL> \
    - 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
+   - Hover diff: hover interactive elements (1 sample per tag+class signature, max 30),
+     diff computed styles → JS-set hover states that :hover harvesting misses
+   - In-view entrance: fresh reload, tag below-fold "waiting to animate" nodes
+     (opacity 0 / transform offset), scroll each into view, diff → fade-up/slide-in
+   - Time-driven: 3s no-input MutationObserver watch → carousel/auto-cycle candidates
+   - Scroll-lib detection: Lenis / Locomotive Scroll (native scrolling feels different —
+     the user spots it immediately; wire the lib page-level, not per-section)
    Disable with --no-interact (restores the old fully-deterministic, screenshot-stable capture).
+10. SEO asset harvest: favicon / apple-touch-icon / webmanifest / og:image → assets/seo/
 ```
 
 ---
@@ -240,6 +263,26 @@ Refinement applied when converting rendered.html + computed.json → sections.js
 
 ---
 
+## 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:
+
+```
+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.
+```
+
+---
+
 ## Phase 3: Scaffold ← stack-specific code generation
 
 **⛔ Implement MO fully first → pass verification → then PC. No responsive conversion in this phase.**
@@ -251,78 +294,105 @@ 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
+  Prep (sequential, once):
+    a. Step 0: clone-spec.js → emit _specs/mo/{Section}.spec.md for every section
+    b. Step A: clone-to-scss.js → SCSS draft in styles/{feature}/mo/ (computed values)
+    c. Orchestrator resolves every spec TODO BEFORE dispatch:
+       ├─ Confirm the interaction model (spec.interaction is a heuristic guess;
+       │  the spec's active-capture "Dynamic behaviors" block overrides it on conflict)
+       ├─ List the states to implement (spec.states + Dynamic behaviors)
+       ├─ Mark copyrighted text for placeholder replacement (skip with --real-content)
+       └─ Map component candidates against component-index.json (reuse vs create)
+    d. 150-line split rule (mechanical — wc -l, don't override with "but it's related"):
+       a completed spec over 150 lines means the section is too big for one builder →
+       split into sub-component specs (one per card variant / repeated pattern) + one
+       wrapper spec that imports them.
+  Dispatch (parallel):
+    ⛔ Every builder prompt embeds the FULL spec text INLINE — never "go read the file".
+       The spec file stays on disk as the audit trail; the prompt must be self-sufficient.
+    ⛔ Builders that write files in parallel run in worktree isolation; sub-component
+       builders complete before their wrapper builder starts.
+    Builder contract (each agent):
+      1. Build HTML structure + semantic tags + framework-specific component file
+         ⛔ No CSS in <style> blocks — only @import/@use of styles/{feature}/mo/
+         ⛔ Build for the CONFIRMED interaction model in the spec; wire every state
+         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
+      2. Asset references → public/images/{feature}/ (already populated in Phase 1)
+      3. SCSS edits per Immutable Rule 1 (evidence-cited only)
+      4. Verify compile (tsc --noEmit or stack equivalent) before finishing
+  Merge (orchestrator, as builders complete):
+    5. Merge worktrees; resolve conflicts (you have full context on every spec)
+    6. clone-validate.js per section — Step B
+       ├─ PASS → section done
        └─ 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):
+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
+  2. Switch component style imports from styles/{feature}/{bp}/index.scss to the merged
+     styles/{feature}/index.scss
+  3. Review pc-only/mo-only selectors in the merge report — hide/show them with the
+     media query if the original does (evidence: the two sections.json trees)
+  4. → 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.
+
+Claude's role:
   ✅ 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)
+  ✅ SCSS value edits WITH cited evidence (computed.json/states.json/behaviors.json) —
+     clone-validate.js PASS is the judge
+  ❌ Do NOT invent CSS values without extraction evidence
   ❌ Do NOT write CSS directly in <style> blocks
-  ❌ Do NOT use vw/clamp/@media or create custom mixins in Phase 3A/3B
+  ❌ Do NOT hand-write vw/clamp/@media in Phase 3A/3B (responsive comes from Phase 3C merge)
   ❌ Do NOT hotlink remote URLs — all assets must use local public/images/ paths
 ```
 
@@ -382,6 +452,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.
@@ -404,6 +477,8 @@ NOT intended for:
 
 Claude must:
   - Replace copyrighted text content with placeholders (e.g. "[Lorem ipsum]") by default
+  - --real-content: ask ONE explicit confirmation (site ownership / permission) before
+    Phase 3; on confirmation keep text verbatim (clone-spec.js --real-content)
   - Skip and warn when robots.txt disallows fetching the target path
   - Refuse if the user's stated intent is brand impersonation or deception
 ```
@@ -423,3 +498,5 @@ Claude must:
 | 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. |
+| clone-merge-responsive.js reports many mo-only/pc-only selectors | Section detection diverged between BPs (layout differs structurally). Expected for hidden-on-mobile elements; verify each against the two sections.json trees and gate with the media query manually if needed. |
+| Merged build fails Phase 5 at one viewport only | The merge dropped or mis-bucketed a declaration. Diff the failing viewport's computed CSS against its sections.json; fix in the merged SCSS with that evidence. |