@su-record/vibe 3.1.0 → 3.2.1

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/hooks/scripts/verify-ledger.js

@@ -2,7 +2,7 @@
 /**
  * verify-ledger CLI — vibe.verify 결과를 run-ledger에 기록.
  *
- * 사용법: node hooks/scripts/verify-ledger.js pass|fail
+ * 사용법: node hooks/scripts/verify-ledger.js pass|fail <run-id> <results-json-path>
  *
  * vibe.verify/SKILL.md 에서 검증 완료 시 호출.
  * stdout 출력은 에이전트가 Bash로 실행하는 컨텍스트이므로 허용.
@@ -10,13 +10,33 @@
  */
 
 import { recordVerify } from './lib/run-ledger.js';
+import fs from 'fs';
 
 const arg = process.argv[2];
+const runId = process.argv[3];
+const resultsPath = process.argv[4];
 const passed = arg === 'pass';
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 
-recordVerify(projectDir, passed);
+function readResults(filePath) {
+  try {
+    if (!filePath) return [];
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+const recorded = recordVerify(projectDir, passed, {
+  runId,
+  verificationResults: readResults(resultsPath),
+});
 
 const status = passed ? 'pass' : 'fail';
-process.stdout.write(`[verify-ledger] recorded: verifyPassed=${passed} (${status})\n`);
+if (recorded) {
+  process.stdout.write(`[verify-ledger] recorded: verifyPassed=${passed} (${status})\n`);
+} else {
+  process.stderr.write('[verify-ledger] WARNING: run-ledger or evidence.json write failed\n');
+}
 process.exit(0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@su-record/vibe",
-  "version": "3.1.0",
-  "description": "AI Coding Framework for Claude Code — 10+ agents, 59 skills, multi-LLM orchestration",
+  "version": "3.2.1",
+  "description": "AI Coding Framework for Claude Code — 7+ agents, 60 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
   "exports": {
@@ -94,7 +94,6 @@
     "dist/",
     "vibe/",
     "languages/",
-    "commands/",
     "agents/",
     "skills/",
     "hooks/",

package/skills/clone/SKILL.md

@@ -71,36 +71,15 @@ Input: a URL (or multiple URLs for multi-page clones)
 → Phase 3C: Responsive merge (clone-merge-responsive.js — mobile-first @media)
 → Phase 4: Compile gate
 → Phase 5: Pixel verification loop (BOTH viewports after merge)
-
-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/{mo,pc}/,
-  styles/{feature}/{mo,pc}/ (per-BP drafts) → styles/{feature}/ (Phase 3C merged),
-  public/images/{feature}/, public/ (favicons/OG from assets/seo/)
 ```
 
+> 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).
 
 ---
 
@@ -130,50 +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 / tab / hover / in-view / time-driven + scrollLib
-  ├── assets/
-  │   ├── images/         — all <img>, background-image, <picture> sources
-  │   ├── fonts/          — @font-face srcs
-  │   └── seo/            — favicons, apple-touch-icons, OG images, webmanifest
-  └── 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
-   - 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/
-```
+> 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).
 
 ---
 
@@ -203,63 +139,7 @@ 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
-
-```
-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
-
-```
-/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: [...] }
-      }
-    ]
-  }
-```
+> Read `references/refine-rules.md` for the full refinement rule set and the sections.json output schema.
 
 ---
 
@@ -324,44 +204,8 @@ node {{VIBE_PATH}}/hooks/scripts/clone-validate.js \
 ⛔ **Do NOT write custom SCSS / spec generation scripts.**
 ⛔ **Do NOT proceed past a section without a clone-validate.js PASS for it.**
 
-```
 Phase 3A: MO Scaffold — parallel builder dispatch
   Input: /tmp/{feature}/mo/sections.json
-  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
@@ -375,27 +219,12 @@ Phase 3C: Responsive Integration (after both MO+PC pass Phase 5)
        --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.
+  → 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
-  ✅ 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 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
 ```
 
+> 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
@@ -462,41 +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
-  - --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
-```
-
----
+## 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. |
-| 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. |
+> 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.

package/skills/clone/references/capture-rules.md

@@ -0,0 +1,48 @@
+# Clone — Phase 1 Capture Output & Rules
+
+> Loaded by vibe.clone SKILL.md Phase 1 (Capture) — full per-breakpoint output directory listing and the deterministic capture rule set.
+
+### 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 / tab / hover / in-view / time-driven + scrollLib
+  ├── assets/
+  │   ├── images/         — all <img>, background-image, <picture> sources
+  │   ├── fonts/          — @font-face srcs
+  │   └── seo/            — favicons, apple-touch-icons, OG images, webmanifest
+  └── 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
+   - 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/
+```

package/skills/clone/references/legal-and-error-recovery.md

@@ -0,0 +1,40 @@
+# Clone — Legal & Ethical Notes + Error Recovery
+
+> Loaded by vibe.clone SKILL.md — full legal/ethical usage notes and the Error Recovery troubleshooting table.
+
+## 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
+  - --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
+```
+
+## 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. |
+| 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. |

package/skills/clone/references/refine-rules.md

@@ -0,0 +1,61 @@
+# Clone — Phase 2 Refinement Rules & Output Schema
+
+> Loaded by vibe.clone SKILL.md Phase 2 (Refine) — full refinement rule set and the sections.json output schema.
+
+### Refinement rules
+
+```
+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
+
+```
+/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: [...] }
+      }
+    ]
+  }
+```