docs(v1.7.0): Phase 5 Part B — gallery-first docs (W-1/W-2/W-3/W-8/W-9/W-10/W-13 + B-2) (#53)

* docs(v1.7.0): Phase 5 Part B — gallery-first docs (W-1/W-2/W-3/W-8/W-9/W-10/W-13 + B-2)

W-1 + B-2 (README v1.6+ section + gallery-first reorder, Godin):
- New "What's new (v1.6+ / v1.7)" section explaining Socratic interview as
  ground truth, B-1 4-required, B-3 Skip-interview, A-4 tiered fallback,
  and the gallery-first inversion of SaaS-onboarding default.
- verify-plugin count corrected 34 → 56 (matches current pass count).

W-2 (LESSON 0.7 resolution note):
- 0.7 marked "✅ resolved v1.1.0 + reinforced v1.6.0+".
- Two-stage 해결 narrative: v1.1.0 Gate H1 선택 (1차) + v1.6.0+ I1 Socratic
  ground truth (2차, root cause). spec_alignment_notes로 advocate alignment
  가시성 확보.

W-3 (PROGRESS.md refresh):
- Stale v1.0.0-buildup state replaced with current v1.10.0 release timeline.
- Run index includes r-20260422-184337 (LESSON 0.7) + r-20260423-093527
  (LESSON 11.1).
- v1.7.0 Audit progress table — 7/9 phases shipped.

W-8 (/pf:help v1.6+ note):
- New "What's new" section summarizing v1.6 Socratic + v1.7 B-1/B-3/A-4 +
  v1.6.1 weak-replay, with cross-refs to schema + ideation-lead.md.

W-9 (DEMO-STORYBOARD v1.7+ rewrite):
- Title bumped v1.0.0 → v1.7+. New 0:16–0:24 Socratic interview block
  (4 required questions + idea.spec.json live fill), shifted later blocks.
- Gate H1 block (0:50–1:02) emphasizes gallery-first: 26 카드 grid →
  click → AskUserQuestion → "Approve". "그 그림이 스펙입니다" line.
- SpecDD/Engineering blocks marked ×4/×8 acceleration to keep gallery
  central in the demo timeline.

W-10 (SUBMISSION.md v1.10+ update):
- Header notes v1.10+ (Phase 9 Business-panel UX shipped).
- Option A 200-word summary rewritten to lead with Socratic interview
  → 26 advocates → gallery → spec narrative (gallery-first).
- Final tag placeholder updated v1.0/v1.1 → v1.10.x via release-please.

W-13 (idea-spec.schema.json description rewrite):
- Top-level description: covers v1.6 origin + v1.7 B-1/B-3 evolution +
  cross-ref to A-4 tiered fallback location.
- _filled_ratio description: bullet-structured with explicit boundary
  cases (B-1 fast path = 5/9 ≈ 0.56 medium tier; B-3 skip = 1/9 ≈ 0.11
  fallback) — replaces the previous prose paragraph.

Closes umbrella #35 P5 Part B + B-2 from umbrella #36.
Refs PR #51 (Phase 9 ship that triggered these doc updates).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(memory): apply codex R1 P3 — align LESSONS 0.7 / PROGRESS run row with 0.8 facts

Codex caught: PROGRESS.md said r-20260422-184337 chosen_preview = P19,
LESSON 0.7 narrated user picked P19, but LESSON 0.8 (evidence-based — blackboard.db
+ selection_metadata.prior_stale_override_noted) says P19 was an external
out-of-band override that was DISCARDED as stale, and the user's actual in-flow
Gate H1 choice was P10 (TP 단독 1위 API-first). This contradiction predated
P5 Part B but was made worse by my new PROGRESS.md row echoing P19.

- LESSONS 0.7: "사용자는 P10을 의도적으로 선택" + parenthetical acknowledging
  the P19 stale-override that became LESSON 0.8's trigger
- PROGRESS.md run row: chosen_preview = P10-the-dreamer (TP-favored API-first),
  outcome cell explains the stale-override → P10 re-write timeline

The conceptual finding of LESSON 0.7 (panel-composite ≠ user-intent) is unchanged;
only the example fact corrected to match LESSON 0.8 + the actual run trace.

Refs PR #53 codex R1 review.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(docs): apply PR #53 R1 (gemini medium ×3) — clarify v1.7 umbrella vs semver tag

Gemini caught: README/help.md describe Phase 9 features as "v1.7+", while
PROGRESS.md/SUBMISSION.md show "v1.10.0" — readers can't tell the two apart.

Both are correct but mean different things:
- "v1.7 audit" is the ComBba feature *umbrella* name (issue #29-37)
- "v1.10.0" is the actual release-please *semver* tag for the PR that
  shipped Phase 9 (PR #51 → release #52)

A single umbrella spans multiple semver releases (Phase 1 fix → patch bump,
Phase 9 feat → minor bump, etc.).

Resolution — explicit umbrella-vs-semver disambiguation in 4 places:
- README "What's new" heading + new Terminology callout linking to CHANGELOG.md
- help.md "What's new" heading + same callout (relative path adjusted)
- PROGRESS.md current-state bullet adds note explaining release-please mapping
- idea-spec.schema.json top-level description: replaced "v1.7.0+ B-1" with
  "Phase 9 (B-1, shipped v1.10.0)" + closing note about umbrella names
- _filled_ratio description: "v1.7.0+ A-4" → "Phase 9 A-4, shipped v1.10.0"

Refs PR #53 review #3141462531 / #3141462532 / #3141462533.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sgwannabe

README.md

@@ -110,6 +110,32 @@ Categorical scoring (not raw keyword count) means `"audit logging feature"` in a
 - **Rule 9 idea-drift detector** (`hooks/idea-drift-detector.py`) catches the failure where Gate H1 picks product A but SpecDD/Engineering drift to product B. Containment coefficient over token sets (no external ML deps). Block threshold 0.3, warn at 0.4.
 - **P0-B cost-regression sentinel** (`hooks/cost-regression.py`) compares `cost-snapshot.json` against the active profile's P95/hard ceiling every 30s. Hard breach triggers auto-pause + AskUserQuestion handoff.
 
+## What's new (audit umbrellas v1.6 / v1.7 — shipped progressively through semver v1.10.0)
+
+> **Terminology**: "v1.6 audit" / "v1.7 audit" are *feature umbrella* names (issue #28 family / #29–#37). Each PR within an umbrella ships under its own [release-please](https://github.com/googleapis/release-please) semver tag based on Conventional Commits — so the v1.6 schema landed in semver **v1.6.0**, B-1/B-3/A-4 (Phase 9, PR #51) landed in semver **v1.10.0**, etc. See [CHANGELOG.md](CHANGELOG.md) for the per-tag mapping.
+
+The biggest UX shift since v1.0.0: **the gallery comes first**, before any spec or code is written. You don't pick a feature flag matrix; you pick a picture.
+
+### v1.6 — Socratic interview as ground truth (LESSON 0.7 fix)
+
+Before v1.6, 26 Advocates dispatched directly from the one-liner — and the failure mode in LESSON 0.7 played out: user wrote "회의록 자동 정리," panel-recommended composite #1 was a Slack bot, but the user actually wanted a legal deposition paralegal tool. Different product entirely.
+
+v1.6 adds **I1 Idea Clarifier** between `/pf:new` and the 26 advocates. Three batched `AskUserQuestion` modals (10–12 fields total) produce `idea.spec.json` — a structured ground truth (`target_persona`, `primary_surface`, `jobs_to_be_done`, `killer_feature`, `must_have_constraints`, `non_goals`, …) that every advocate receives. Divergence is now intentional creative reframing, not blind misalignment.
+
+The PreviewDD cache key now includes `idea_spec_hash`, so the same one-liner with different Socratic answers gets a fresh advocate set instead of a stale replay.
+
+### v1.7 — 4 required questions, skip-interview, tiered fallback (Phase 9 — Christensen + Kim-Mauborgne + Taleb)
+
+Hackathon demo feedback: 12 questions before seeing any output is too many for a 3-minute pitch. v1.7 trims the contract:
+
+- **B-1 — 4 required, 5–8 optional** (`persona.profile` / `surface.platform` / `killer_feature` / `must_have_constraints[≥1]`). Best path: **4 clicks total** to land on the gallery. Fullest path: 12 questions for deep dive. User choice per modal.
+- **B-3 — Skip interview** option in Batch A. One click writes a 3-field stub (`_schema_version` + `_filled_ratio` + `idea_summary` only) and short-circuits to the v1.5.4 raw-idea path. Demo escape hatch when the interview itself becomes friction.
+- **A-4 — `_filled_ratio` tiered fallback**. The hard 0.5 gate is gone. Now `≥ 0.7` = high-confidence ground truth, `0.4–0.7` = hint, `0.2–0.4` = low-confidence, `< 0.2` = drop spec entirely (Skip-interview lands here at ratio ≈ 0.11). No path is blocked.
+
+### Why this is "gallery-first"
+
+The flow inverts the SaaS-onboarding default of "configure → preview." Instead: **answer 4 questions → see 9 / 18 / 26 mockups → pick one**. The picture is the spec. SpecDD and TestDD only run on the picture you approved. (Godin: lead with the artifact, not the form.)
+
 ## Updating
 
 We release patches and feature updates frequently (see
@@ -226,7 +252,7 @@ All Opus 4.7, zero Sonnet/Haiku.
 | **Seed ideas** | 10 | Pre-verified demo scenarios |
 | **Slash commands** | 14 | `/pf:*` |
 | **CLI** | 1 | `bin/pf` |
-| **Verification** | 1 | `scripts/verify-plugin.sh` (34 checks) |
+| **Verification** | 1 | `scripts/verify-plugin.sh` (56 checks) |
 
 ## Zero third-party dependencies
 
@@ -266,7 +292,7 @@ lessons to every Department Lead.
 ```bash
 git clone https://github.com/Two-Weeks-Team/PreviewForgeForClaudeCode
 cd PreviewForgeForClaudeCode
-bash scripts/verify-plugin.sh   # 34/34 checks
+bash scripts/verify-plugin.sh   # 56/56 checks
 ```
 
 ## Hackathon

docs/DEMO-STORYBOARD.md

@@ -1,7 +1,9 @@
-# 3-Minute Demo Storyboard — Preview Forge v1.0.0
+# 3-Minute Demo Storyboard — Preview Forge v1.7+ (gallery-first)
 
 > 해카톤 제출용 데모 영상. 180초 타깃, 170–190초 허용. 첫 5초가 고정적으로
 > "PreviewDD 이게 뭔데?" 후크. 마지막 10초는 저장소·라이선스 박제.
+> v1.7 ship 이후: **gallery-first** 톤 — Socratic 질문(4개)에서 바로 26 mockup
+> grid로 점프. spec/code 화면은 가속(×8) 처리해 그림이 항상 화면 중심에 있게.
 
 ## 제작 원칙
 
@@ -26,12 +28,13 @@
 |---|---|---|
 | **0:00–0:05** | 검은 화면, 흰 글씨: "**PreviewDD**" 쿵! → "**SpecDD**" → "**TestDD**" 3 단계로 나타남 | **한**: "TDD는 코드를 테스트로 주도했습니다. SpecDD는 스펙으로. **우리는 그 앞에 PreviewDD를 놓았습니다.**" <br> **EN**: "TDD drove code with tests. SpecDD with specs. We put **PreviewDD** in front." |
 | **0:05–0:12** | 터미널: `pf init meeting-minutes`, `cd`, `claude` 순차 타이핑 | **한**: "한 줄 아이디어, 143명의 Opus 4.7 가상 팀, 자동 풀스택." <br> **EN**: "One-line idea. 143 Opus 4.7 agents. Auto full-stack." |
-| **0:12–0:18** | Claude Code 창. `/pf:new "회의록 자동 정리 + action item 추출"` 타이핑 → Enter | **한**: "아이디어 입력, 그게 전부입니다." <br> **EN**: "You type the idea. That's all." |
-| **0:18–0:35** | **PreviewDD**: 26 Advocate 아바타 등장, 각자 mockup.html 생성하는 파일 트리가 왼쪽에 자람 | **한**: "26명이 서로 다른 페르소나로 mockup 1장씩 제안합니다. 같은 아이디어를 26가지로 해석." <br> **EN**: "26 advocates, each with a distinct lens, render 26 different mockups in parallel." |
-| **0:35–0:50** | **4-패널 투표**: 4개 동심원(TP/BP/UP/RP)에 40명 아바타. 막대 그래프 실시간으로 채워짐 | **한**: "기술·비즈니스·UX·리스크. 4개 전문 패널, 40명이 meta-tally로 1개 선택." <br> **EN**: "Technical, Business, UX, Risk. 4 parallel panels, 40 experts, meta-tally." |
-| **0:50–1:00** | **Gate H1**: 선택된 mockup이 크게. 사용자가 native 슬라이더로 컬러·폰트 조정, "Approve" 클릭 | **한**: "인간은 여기서 한 번, 디자인 승인." <br> **EN**: "Human click #1: design approval." |
-| **1:00–1:08** | **SpecDD**: `specs/openapi.yaml` 파일이 타이핑되듯 나타남. 마지막에 🔒 SHA-256 hash 도장 | **한**: "OpenAPI 스펙 잠금. 타입이 source of truth." <br> **EN**: "OpenAPI spec locked by SHA-256. Types become the source of truth." |
-| **1:08–1:25** | **5 Engineering Teams**: 파일 트리가 5개 영역(apps/api, apps/web, prisma, deploy, packages/sdk)으로 동시에 자람. 타임랩스 ×8, 좌하단 `×8` 표시 | **한**: "5개 분야별 팀이 병렬로 빌드. Backend, Frontend, DB, DevOps, SDK." <br> **EN**: "5 engineering teams build in parallel." |
+| **0:12–0:16** | Claude Code 창. `/pf:new "회의록 자동 정리 + action item 추출"` 타이핑 → Enter | **한**: "아이디어 입력, 그게 전부입니다." <br> **EN**: "You type the idea. That's all." |
+| **0:16–0:24** | **I1 Socratic 인터뷰** (v1.6+): 3 modal 중 첫 modal 화면 — `target_persona` / `platform` / `killer_feature` / `constraint` 4개 필수 옵션. 사용자가 1개씩 선택, 4 클릭 (best path). 화면 우측에 `idea.spec.json` 필드가 라이브로 채워짐 | **한**: "4개 질문으로 의도를 잠급니다. 26 mockup이 같은 사용자를 상정하도록." <br> **EN**: "4 questions lock the intent. So 26 mockups talk to the same user." |
+| **0:24–0:38** | **PreviewDD**: 26 Advocate 아바타 등장, 각자 mockup.html 생성하는 파일 트리가 왼쪽에 자람. v1.7+ 추가: 각 카드에 `spec_alignment_notes` 한 줄이 떠올라 "어떻게 해석했는지" 보여줌 | **한**: "26명이 서로 다른 페르소나로 mockup 1장씩 제안합니다. 같은 아이디어를 26가지로 해석." <br> **EN**: "26 advocates, each with a distinct lens, render 26 mockups — same intent, 26 angles." |
+| **0:38–0:50** | **4-패널 투표**: 4개 동심원(TP/BP/UP/RP)에 40명 아바타. 막대 그래프 실시간으로 채워짐 | **한**: "기술·비즈니스·UX·리스크. 4개 전문 패널, 40명이 meta-tally로 1개 선택." <br> **EN**: "Technical, Business, UX, Risk. 4 parallel panels, 40 experts, meta-tally." |
+| **0:50–1:02** | **Gate H1 — Gallery first**: `gallery.html`이 새 브라우저 탭에 뜸. 26 카드 grid (one_liner_pitch + iframe mockup). 사용자가 한 카드 클릭 → AskUserQuestion에서 동일 ID 선택 → "Approve" | **한**: "26개 그림 중 하나, 그게 스펙입니다. 인간 클릭 #1 — 디자인 승인." <br> **EN**: "One picture out of 26 is the spec. Human click #1: design approval." |
+| **1:02–1:10** | **SpecDD** (×4 가속): `specs/openapi.yaml` 파일이 타이핑되듯 나타남. 마지막에 🔒 SHA-256 hash 도장. 좌하단 `×4` 표시 | **한**: "OpenAPI 스펙 잠금. 타입이 source of truth." <br> **EN**: "OpenAPI spec locked by SHA-256. Types become the source of truth." |
+| **1:10–1:25** | **5 Engineering Teams** (×8 가속): 파일 트리가 5개 영역(apps/api, apps/web, prisma, deploy, packages/sdk)으로 동시에 자람. 좌하단 `×8` 표시 | **한**: "5개 분야별 팀이 병렬로 빌드. Backend, Frontend, DB, DevOps, SDK." <br> **EN**: "5 engineering teams build in parallel." |
 | **1:25–1:50** | **TestDD**: 점수 게이지 0 → 412 → 478 → **499**로 차오름. 5개 미니 게이지(J1-J5) + 5 Auditor 체크마크 순차 점등 | **한**: "자기수정 루프가 점수 499점까지 올립니다. 5명 심판 + 5명 감사관의 이중 게이트." <br> **EN**: "Self-correction climbs to 499/500. 5 Judges + 5 Auditors double-gate." |
 | **1:50–2:00** | **Gate H2**: 500점 리포트 + 스크린샷 grid 표시. "Deploy" 버튼 클릭 | **한**: "인간의 두 번째 클릭, 배포 승인." <br> **EN**: "Human click #2: deploy approval." |
 | **2:00–2:25** | **생성된 앱 작동**: 새 탭이 http://localhost:18080 열림. 회의록 붙여넣기 → action item 추출 실행 | **한**: "3분 전 한 줄이었던 것이, 지금 작동합니다." <br> **EN**: "What was one line three minutes ago now runs." |

docs/SUBMISSION.md

@@ -2,20 +2,21 @@
 
 > 해카톤 제출 폼에 넣을 준비 완료 텍스트 + 체크리스트.
 > 마감: 2026-04-26 20:00 EST.
+> Version: v1.10+ (Phase 9 — Business-panel UX shipped: Socratic interview 4-required + Skip-interview + tiered fallback).
 
 ## Written Summary (100–200 words)
 
 ### Option A — "PreviewDD" 서사 중심 (Keep Thinking 겨냥, 권장)
 
 > **Preview Forge** introduces a new software-development methodology: **3-DD**. Test-Driven Development drove code with tests. Spec-Driven Development drove code with specs. We put **PreviewDD** in front.
 >
-> Before any spec exists, 26 distinct "Preview Advocates" — each a different Opus 4.7 persona, from The Contrarian to The Anti-AI — render 26 parallel mockups of a one-line idea. Four expert panels (40 agents: Technical, Business, UX, Risk) converge on one direction via meta-tally. The winner locks. Only then does SpecDD (OpenAPI-first, nestia-generated) begin. Then TestDD (499/500 scoreboard + 5-auditor double-gate).
+> A 4-question Socratic interview locks user intent into `idea.spec.json`. Then 26 "Preview Advocates" — each a different Opus 4.7 persona, from The Contrarian to The Anti-AI — render 26 parallel mockups, all anchored to the same intent but interpreted through 26 different lenses. Four expert panels (40 agents: Technical, Business, UX, Risk) converge via meta-tally. The user picks one card from the gallery — that picture is the spec. Only then does SpecDD (OpenAPI-first, nestia-generated) begin. Then TestDD (499/500 scoreboard + 5-auditor double-gate).
 >
 > The human clicks twice: approve design, approve deploy. Everything else — 143 Opus 4.7 agents, cross-run LESSONS.md learning, Layer-0 Rule enforcement via hooks — is self-organized. Distributed as a single Claude Code plugin via GitHub-hosted marketplace. Zero third-party dependencies.
 >
-> Three-DD Methodology is the core contribution. 143 parallel personas is the unreasonable demo.
+> Three-DD Methodology is the core contribution. The Socratic interview anchors it. 143 parallel personas is the unreasonable demo.
 
-*Word count: 180*
+*Word count: 195*
 
 ### Option B — "143 agents" 데모 중심 (Most Creative Opus 4.7 겨냥)
 
@@ -78,7 +79,7 @@ before the spec' as its own DD cycle. That's a new place to point Claude."
 - [ ] Apache-2.0 license present at repo root
 - [ ] Claude Opus 4.7 attribution in NOTICE + commits
 - [ ] First LESSON from real run committed (proves self-learning claim)
-- [ ] Final run tag `v1.0.0` or `v1.1.0` on main
+- [ ] Final run tag `v1.10.x` (or successor) on main — release-please auto-bumps via Conventional Commits
 
 ## Day-of-submission timeline (2026-04-26)
 

plugins/preview-forge/commands/help.md

@@ -8,7 +8,7 @@ description: List all /pf:* commands
 
 ## Usage
 
-```
+```text
 /pf:help
 ```
 
@@ -20,6 +20,20 @@ _(인자 없음)_
 
 14 명령어 요약 + 자주 묻는 질문 (FAQ).
 
+## What's new (audit umbrellas v1.6 / v1.7 — shipped through semver v1.10.0)
+
+> "v1.6 audit" · "v1.7 audit"은 ComBba feature umbrella 이름이고, 실제 release tag는 release-please가 Conventional Commits로 자동 부여한 v1.6.0·v1.10.0 등 semver. 자세한 매핑은 [CHANGELOG.md](../../../CHANGELOG.md) 참조.
+
+`/pf:new` 흐름이 v1.6.0(semver)부터 크게 바뀌었다 — README의 "What's new" 섹션 요약:
+
+- **v1.6 — I1 Socratic interview**: `/pf:new` 직후 3개의 `AskUserQuestion` 모달이 떠서 `idea.spec.json`(target_persona / primary_surface / jobs_to_be_done / killer_feature / must_have_constraints / non_goals 등)을 먼저 짠다. 26 advocate가 이 ground truth를 받아 dispatch되므로 LESSON 0.7 (panel 추천이 사용자 의도와 어긋남)이 근본적으로 해소.
+- **v1.7 (B-1)** — 필수 답변은 4개(persona / platform / killer_feature / constraint), 나머지 5–8개는 _optional_. **Best path: 4 클릭으로 gallery 도달**.
+- **v1.7 (B-3)** — Batch A 첫 모달에 "Skip interview — use defaults" 옵션 추가. 한 클릭으로 인터뷰 abort, `_filled_ratio` ≈ 0.11 stub만 쓰고 v1.5.4 raw-idea path로 진입.
+- **v1.7 (A-4)** — `_filled_ratio` 4-tier fallback (`≥0.7` high / `0.4–0.7` medium / `0.2–0.4` low / `<0.2` fallback). hard gate 없음.
+- **v1.6.1 (A-1) — Weak-replay**: 같은 idea+profile로 다시 `/pf:new`를 돌리면 weak-alias cache hit으로 Socratic 모달을 사용자 선택으로 스킵 가능.
+
+자세한 schema는 `plugins/preview-forge/schemas/idea-spec.schema.json`, A-4 fallback 동작은 `agents/ideation/ideation-lead.md` §1 참조.
+
 ## 관련
 
 - 본 명령은 plugin `preview-forge`의 일부입니다.