docs: CONTRIBUTING + ideation-lead wording cleanup (#95 / #82 #89 follow-up) (#101)

* docs(contributing): clarify regression-test path + LESSONS.md location (#95 / #82)

Wording-only follow-up to PR #82's CONTRIBUTING semantic-scope refresh.
Two minor fixes that drifted as the test layout matured:

- Bug-fix checklist now points to `tests/` (fixture / e2e / boilerplate
  lint) for regression placement, with `.github/workflows/ci.yml` called
  out as wiring rather than the test home.
- LESSONS.md path is given as the full `plugins/preview-forge/memory/`
  location to match §1 LESSON guidance higher in the file.

No change to the 57-check verify count, 144 agent total, 14 commands,
26 advocates, or commit-prefix examples — all of those still match the
filesystem snapshot.

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

* docs(agents): ideation-lead A-4 cascade + sub-agent template alignment (#95 / #89)

Wording follow-up to PR #98's A-4 enforcement section. Two spots in
`agents/ideation/ideation-lead.md` still described the cascade with the
older conceptual labels only; this commit makes the script-canonical
mode names visible everywhere they appear:

- §1 cascade table: each tier row now annotates its
  `filled-ratio-gate.sh mode=` value (`ground-truth` / `hint` /
  `low-confidence` / `fallback-omit-spec`) next to the conceptual
  high/medium/low/fallback label, and the fallback row spells out that
  the IDEA_SPEC_CONFIDENCE line is dropped (not just the IDEA_SPEC).
- §2 advocate-dispatch template: replaces the old "fallback인 경우 라인을
  빼라" LLM-discretion prose with a script-enforced contract — I_LEAD
  derives the IDEA_SPEC / IDEA_SPEC_CONFIDENCE *structure* from
  `filled-ratio-gate.sh --prompt-fragment` (which lines, which
  confidence label, whether the confidence line is omitted) and only
  substitutes the actual `idea.spec.json` payload into the
  `<splice runs/<id>/idea.spec.json …>` placeholder. Advocates consume
  whatever shape arrives without second-guessing tier or omit decisions.

This closes the LLM-trust → script-enforced loop for A-4: the gate is
now load-bearing not only for tier classification but also for the
advocate-prompt construction itself.

No code or test changes; the byte-equal fixtures in
`tests/fixtures/filled-ratio-gating/verify.sh` still pass and
`tests/test-advocate-boilerplate.sh` (which lints advocates only,
not ideation-lead.md) is untouched.

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

CONTRIBUTING.md

@@ -106,9 +106,11 @@ To add a new role, justify why an existing member is insufficient.
 ### 4. 🐛 Bug fix
 
 Use the bug report issue template. All bug fix PRs must:
-- Include a regression test (in `.github/workflows/ci.yml` if hook-related)
+- Include a regression test (under `tests/` — fixture, e2e, or boilerplate
+  lint as appropriate; CI wiring lives in `.github/workflows/ci.yml`)
 - Pass `bash scripts/verify-plugin.sh`
-- Include a LESSON entry in `LESSONS.md` (root cause + prevention)
+- Include a LESSON entry in `plugins/preview-forge/memory/LESSONS.md`
+  (root cause + prevention)
 
 ### 5. 📝 Documentation / spec
 

plugins/preview-forge/agents/ideation/ideation-lead.md

@@ -29,12 +29,12 @@ model: opus
 - I1은 **항상** 3-batch AskUserQuestion을 수행하여 `runs/<id>/idea.spec.json`을 산출 (이미 존재하면 스킵)
 - 산출된 `idea.spec.json._filled_ratio`를 4-tier로 매핑 (v1.7.0+ A-4 — B-1과 동시 ship; threshold 0.4 설정 근거: B-1 fast-path 실제 minimum은 5/9 ≈ 0.56 (idea_summary + target_persona + primary_surface + killer_feature + must_have_constraints; nested object는 binary slot 규칙). 5/9에 edge-case safety margin을 더해 0.5 → 0.4로 내림. PR #51 R2 review에서 원래 "4/9 ≈ 0.44" 근거는 binary slot 규칙을 반영하지 못한 오류로 정정 — `idea-clarifier.md` §"Soft anchor 정책" 참조):
 
-  | `_filled_ratio` | tier | dispatch 동작 | advocate 받는 신호 |
+  | `_filled_ratio` | tier (script `mode=`) | dispatch 동작 | advocate 받는 신호 |
   |---|---|---|---|
-  | `≥ 0.7` | **high** | 정상 dispatch, spec을 ground truth로 사용 | `IDEA_SPEC_CONFIDENCE: high` |
-  | `0.4 ≤ ratio < 0.7` | **medium** | 정상 dispatch, spec을 hint로 사용 (자유 해석 허용 폭 ↑) | `IDEA_SPEC_CONFIDENCE: medium` |
-  | `0.2 ≤ ratio < 0.4` | **low** | 정상 dispatch + Blackboard `ideation.spec_confidence_tier=low` (이전 `low_spec_quality`의 후계) | `IDEA_SPEC_CONFIDENCE: low` |
-  | `< 0.2` | **fallback** | **v1.5.4 path**: advocate dispatch 시 `idea.spec.json`을 **전달하지 않음** (`IDEA_SPEC: <not provided — fallback v1.5.4 path>` — `<...>` 플레이스홀더는 리터럴이 아니라 실제 런타임 substitution 결과; 아래 §2 dispatch template과 동일 형식). Blackboard `ideation.spec_fallback_v1_5_4=true` 기록. B-3 "Skip interview" 선택자가 자동으로 이 경로 진입 (ratio ≈ 0.11) | spec 미전달 |
+  | `≥ 0.7` | **high** (`ground-truth`) | 정상 dispatch, spec을 ground truth로 사용 | `IDEA_SPEC_CONFIDENCE: high` |
+  | `0.4 ≤ ratio < 0.7` | **medium** (`hint`) | 정상 dispatch, spec을 hint로 사용 (자유 해석 허용 폭 ↑) | `IDEA_SPEC_CONFIDENCE: medium` |
+  | `0.2 ≤ ratio < 0.4` | **low** (`low-confidence`) | 정상 dispatch + Blackboard `ideation.spec_confidence_tier=low` (이전 `low_spec_quality`의 후계) | `IDEA_SPEC_CONFIDENCE: low` |
+  | `< 0.2` | **fallback** (`fallback-omit-spec`) | **v1.5.4 path**: advocate dispatch 시 `idea.spec.json`을 **전달하지 않음** (`IDEA_SPEC: <not provided — fallback v1.5.4 path>` — `<...>` 플레이스홀더는 리터럴이 아니라 실제 런타임 substitution 결과; 아래 §2 dispatch template과 동일 형식). Blackboard `ideation.spec_fallback_v1_5_4=true` 기록. B-3 "Skip interview" 선택자가 자동으로 이 경로 진입 (ratio ≈ 0.11) | spec 미전달 (`IDEA_SPEC_CONFIDENCE` 라인도 누락) |
 
   hard gate 없음 — 해커톤 데모 UX 우선. weak-replay short-circuit이 먼저 걸러졌다면 이 경로에는 도달하지 않는다. I_LEAD는 Bash 도구가 없으므로 stderr 대신 Blackboard로 기록.
 
@@ -120,9 +120,17 @@ IDEA_SPEC: <not provided — fallback v1.5.4 path>
 ```text
 ROLE: <advocate name> (P01 ~ P26 중 선택)
 IDEA: <from idea.json — raw one-liner for creative reframing>
+# IDEA_SPEC + IDEA_SPEC_CONFIDENCE 두 줄의 **구조**(어느 라인을 포함할지,
+# 어떤 confidence 라벨을 쓸지, fallback에서 IDEA_SPEC_CONFIDENCE를 누락할지)는
+# I_LEAD가 §1 Enforcement 단계에서
+# `bash scripts/filled-ratio-gate.sh --prompt-fragment runs/<id>/idea.spec.json`
+# 의 stdout으로 결정한다 (byte-stable, 4-tier별로 정해진 scaffold). I_LEAD는 그
+# scaffold의 `<splice runs/<id>/idea.spec.json …>` 자리에만 실제 JSON 본문을
+# 끼워넣고 그 외 wording·라인 유무는 손대지 않는다 — tier 판단·omit 여부 등은
+# advocate 쪽에서 second-guess 하지 않는다. fallback-omit-spec tier에서는
+# IDEA_SPEC_CONFIDENCE 라인이 의도적으로 누락되어 들어오므로, advocate는 그
+# 부재 자체를 "spec 없음" 신호로 해석하면 된다 (별도의 default 값을 만들어내지 말 것).
 IDEA_SPEC: <from idea.spec.json — structured ground truth from I1 Socratic interview>
-  # 단, A-4 fallback tier(< 0.2)인 경우 IDEA_SPEC 라인 자체를 빼고
-  # `IDEA_SPEC: <not provided — fallback v1.5.4 path>`로 대체한다.
   # Advocate는 spec의 채워진 필드를 ground truth로 삼되, null/"unknown" 필드는
   # 자유 해석 가능. v1.7.0+ A-6: **모든** spec 해석은 반드시 6-tuple의
   # spec_alignment_notes에 기록 (null 필드뿐 아니라 그대로 따른 경우도).
@@ -131,10 +139,11 @@ IDEA_SPEC: <from idea.spec.json — structured ground truth from I1 Socratic int
   # 빈 문자열은 preview-card.schema.json (minLength:1) 위반으로 previews.json
   # validation이 실패한다.
 IDEA_SPEC_CONFIDENCE: <high | medium | low>   # v1.7.0+ A-4 — A-4 §1 표 참조.
-  # `high`: spec 그대로 anchor. divergence 최소화.
-  # `medium`: spec을 hint로. null 필드는 자유 해석 OK, 채워진 필드는 anchor.
-  # `low`: spec은 약한 hint. 큰 divergence 허용 (최소 ratio가 4 required only인 경우).
-  # `fallback` tier에서는 이 라인도 함께 누락된다 (advocate는 spec 받지 않음).
+  # `high`  (mode=ground-truth)   : spec 그대로 anchor. divergence 최소화.
+  # `medium`(mode=hint)            : spec을 hint로. null 필드는 자유 해석 OK, 채워진 필드는 anchor.
+  # `low`   (mode=low-confidence)  : spec은 약한 hint. 큰 divergence 허용.
+  # `fallback-omit-spec` tier에서는 이 라인 자체가 fragment에서 누락된다
+  # (advocate는 spec을 받지 않으며 v1.5.4 marker 한 줄만 본다).
 DOMAIN_HINT: <optional, from scripts/detect-surface.sh>
 MOCKUP_GUIDANCE: 페르소나에 맞는 self-contained mockup.html (inline CSS only, max 500 lines)
 OUTPUT_FORMAT: