feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00
parent cfd84875bf
commit 58515ab0f3
251 changed files with 31470 additions and 109 deletions
@@ -0,0 +1,107 @@
+# Contracts 2, 3, 4 — Option Enumeration / Plan Gap / Direct-Response
+
+Root SSOT: [`rules/advisory-depth.md`](../../../../../rules/advisory-depth.md) §"Contract 2~4"
+parent: [`README.md`](README.md)
+
+## Contract 2 — Exhaustive Option Enumeration
+
+When the user mentions any ordering, comparison, design choice, or "how should I do X", the agent must enumerate the **full option space**, not only the option the user happens to have named.
+
+### Rule of thumb
+
+- If the user names 1 ordering of N items, enumerate all `N!` orderings.
+- If the user names 1 design approach, enumerate at least the canonical alternatives (typically 3–5).
+- If the user asks "which library", enumerate the realistic candidates with their distinct trade-offs.
+- If the user describes a workflow with N steps, list which steps can be reordered, which can be parallelized, which can be skipped, and which are blocking.
+
+### Per-option fields
+
+For each option in the enumeration:
+
+```text
+- **케이스 / Case:** <one-line label>
+- **적용 상황 / When it fits:** <the situations where this option is the right answer>
+- **고려사항 / Considerations:** <what must be true / what must be watched>
+- **장점 / Pros:** <concrete, not vague>
+- **단점 / Cons:** <concrete, not vague>
+- **비교 / Compared to others:** <how this differs from the other options in the same enumeration>
+```
+
+### Conditional recommendation (NOT flat)
+
+After enumerating, the agent provides a **conditional recommendation**:
+
+```text
+- If <situation A> → use <option α>, because <reason>.
+- If <situation B> → use <option β>, because <reason>.
+- If <situation C> → use <option γ>, because <reason>.
+```
+
+**Flat recommendations like "X를 추천합니다" are insufficient.** The agent always ties recommendations to situations.
+
+## Contract 3 — Plan Gap Detection
+
+When the user asks the agent to review, critique, or extend a plan document, the agent must explicitly identify:
+
+1. **Tasks that should be in the plan but are not.** For each:
+   - Why it should be there (tied to the spec or original goal).
+   - Where it should slot in the order (before / after which existing step).
+   - What breaks if it is omitted.
+2. **Tasks that are in the plan but should not be.** For each, the reason for removal and the impact.
+3. **Tasks whose ordering is wrong.** For each, the corrected ordering and why.
+4. **Implicit assumptions in the plan.** Surface them as explicit prerequisites.
+
+A plan review that returns only "the plan looks good" is treated as `BLOCKED`. The agent must surface gaps or explicitly declare "no gaps found, all N tasks needed match the spec" with the matrix of plan-task → spec-section to prove it.
+
+## Contract 4 — Direct-Response Template
+
+When the controller answers directly (no subagent dispatch), the response still uses a structured shape. The template scales with question size; sections can be tight one-liners for trivial questions, but they cannot be skipped.
+
+### Template
+
+```markdown
+## 1. 질문 이해 / Question understood
+- <한 줄 요약>
+- 함의된 목표 / Implied goal: <what the user is actually trying to achieve>
+- 함의된 제약 / Implied constraints: <budgets, deadlines, stack, scale; pulled from project context or asked if missing>
+
+## 2. 경우의 수 / Option space
+- <Option 1>
+- <Option 2>
+- <Option 3>
+- ... (exhaustive per Contract 2)
+
+## 3. 각 경우 분석 / Per-option analysis
+### Case 1: <label>
+- 적용 상황 / When it fits: ...
+- 고려사항 / Considerations: ...
+- 장점 / Pros: ...
+- 단점 / Cons: ...
+### Case 2: ...
+
+## 4. 비교 표 / Comparison matrix
+| Option | 적합 상황 | 주요 장점 | 주요 단점 | 비고 |
+| --- | --- | --- | --- | --- |
+
+(Required when there are 3+ options. Optional below that.)
+
+## 5. 권고 / Conditional recommendation
+- If <situation A> → <option α>, because ...
+- If <situation B> → <option β>, because ...
+(Flat "추천: X" is forbidden.)
+
+## 6. 다음 결정 / Next decisions
+- What the user must decide before the next step
+- What information is still missing
+- What questions the agent has for the user
+```
+
+### Trivial lookups
+
+For trivial single-fact questions (for example "이 메서드는 어디 있나요?"), the template collapses to §1 + a one-line answer with `file:line` citation, and §2~§6 are written as "해당 없음 / N/A — trivial lookup". **The agent still names what it skipped and why; it does not silently drop sections.**
+
+## Antigravity-specific 메모
+
+- Contract 4 의 §1~§6 은 chat 본문 응답에 적용. Stop hook 본문 미수신으로 자동 enforce 불가. agent self-check 단독.
+- Contract 3 plan review "looks fine" 자동 BLOCKED 는 정책 — runtime enforcement 없음. self-check 로 강제.
+- 사용자가 ordering / 비교를 물으면 (Contract 2 적용) full `N!` 또는 3~5 canonical alternatives 열거하지 않은 응답은 부족한 advisory 로 자동 폐기.