git:20260613.28fc6d8 to git:20260714.958977b

- description: Advance the onboarding Q&A loop after `clad init <intent>`. Pass the user's answer to the next pending question as a positional argument; the LLM refines spec/docs based on the full Q-A history and may emit new follow-up questions. Reads/writes `.cladding/onboarding/state.yaml`. Use when the user is mid-onboarding and you have collected their reply to one clarifying question — never invent answers.

- # Cladding clarify (formerly `refine`)

-

- Drives the **iterative onboarding loop** initiated by `clad init <intent>`. The init pass writes `.cladding/onboarding/state.yaml` with 2–3 clarifying questions; `clad clarify <answer>` advances the loop one question at a time.

-

- ## Artifacts produced (by Tier)

-

- | Tier | File | Authority |

- |---|---|---|

- | A | `spec/scenarios/<slug>-<hash6>.yaml` (refined, v0.3.45+) | Spec SSoT (onboarding output) |

- | B | `spec/architecture.yaml` (refined) | Design SSoT |

- | B | `spec/capabilities.yaml` (refined) | Design SSoT |

- | B | `docs/project-context.md` (refined) | Design SSoT |

- | D | `.cladding/onboarding/state.yaml` (Q&A history updated) | transient audit |

-

- Existing files divert to `.cladding/scan/*.proposal` per the SSoT model's refresh policy. See [`docs/ssot-model.md`](../../docs/ssot-model.md).

-

- ## Flow

-

- 1. `clad init <intent>` → produces initial artifacts + writes `state.yaml` with pending questions

- 2. Orchestrator asks the user the **first pending question verbatim**

- 3. User replies

- 4. Orchestrator runs `clad clarify <user's reply>` (positional, no quotes needed)

- 5. `clad clarify` marks the question answered, re-runs the LLM with the full Q-A history, refines artifacts, may add new follow-up questions

- 6. Loop until `status: done`

-

- ## Variadic positional

-

- ```

- clad clarify 법인 사업자만 (개인사업자 제외)

- clad clarify "한국 시장 위주"

- clad clarify 카드 + 간편결제 우선

- ```

-

- All tokens are joined with spaces — quoting is optional.

-

- ## Flags

-

- - `--cwd <path>` — directory containing `.cladding/onboarding/state.yaml` (default cwd)

- - `--no-llm` — force deterministic interpreter; current artifact bodies are preserved and the answer is logged as a Q&A footnote in `docs/project-context.md`

- - `--json` — emit a `RefineReport` JSON (`{cwd, answered, newQuestions, mode, status}`) instead of the formatted text

-

- ## Output (text mode)

-

- - Pulse summary line — `✓ clarify answered · mode: greenfield · source: llm`

- - Created / proposal entries for refined artifacts (existing files divert to `.cladding/scan/*.proposal`)

- - New clarifying questions printed as a numbered list (if any)

- - Closing line — `남은 질문: N 개. clad clarify <답변> 으로 계속.` OR `✓ 모든 질문에 답변 완료 — 온보딩 종료.`

-

- ## Exit codes

-

- - `0` — answer accepted (or no-op when state is already done)

- - `1` — fatal error (corrupt state file)

- - `2` — usage error (no state file present, or no answer provided)

-

- ## State file

-

- `.cladding/onboarding/state.yaml` shape:

-

- ```yaml

- intent: "결제 SaaS for B2B"

- language: typescript

- projectName: payment-saas

- mode: greenfield

- startedAt: 2026-05-21T12:34:56.789Z

- status: active

- qa:

- - question: "주 사용자가 개인? 사업자?"

- answer: "법인 사업자만"

- - question: "어떤 결제수단 우선?"

- answer: null

- ```

- `status: done` is set once every question has an answer AND the latest refinement returned no new questions. The file stays on disk as an audit log of the onboarding decisions.

- ## When NOT to invoke

- - `state.yaml` does not exist → exit 2. Run `clad init <intent>` first.

- - The user has not replied yet — never invent answers. Wait for their actual response.

- - The user is asking about an unrelated topic — pause the loop and resume later when they're ready.