jdd-sprint-kit 0.4.0 → 0.5.0

package/README.md

@@ -12,28 +12,31 @@ User inputs (meeting notes, references, existing system context) raise AI's firs
 ## Overall Flow
 
 ```mermaid
-flowchart LR
-    A["1. Brief Input"] --> B["2. Existing System\n(Brownfield Scan)"]
-    B --> C["3. Planning\n(BMAD Auto-Pipeline)"]
-    C --> D["4. Specs\n(Specs Generation)"]
+flowchart TD
+    A["1. Provide Brief & Materials"] --> B["2. Analyze Existing System\n(Brownfield Scan)"]
+    B --> C["3. AI Generates PRD & Design\n(Auto-Pipeline)"]
+    C --> D["4. Generate Specs"]
     D --> JP1{{"JP1\nIs this the right\nproduct?"}}
-    JP1 -->|Approve| E["5. Deliverables\n(Deliverables Gen)"]
+    JP1 -->|Approve| E["5. Generate Prototype\n(Deliverables)"]
     JP1 -->|Revise| C
     E --> JP2{{"JP2\nIs this the right\nexperience?"}}
-    JP2 -->|Approve| F["6. Parallel\n(Implementation)"]
+    JP2 -->|Approve| F["6. Build\n(Parallel Implementation)"]
+    JP2 -->|Crystallize| CR["6b. Reconcile Documents\n(Crystallize)"]
     JP2 -->|Revise| E
     JP2 -.->|Re-examine requirements| JP1
-    F --> G["7. Validate"]
+    CR --> F
+    F --> G["7. Quality Check\n(Validate)"]
     G -->|Pass| H["Done"]
     G -->|Repeated failure| CB["Course Correction\n(Circuit Breaker)"]
     CB --> C
 
     style JP1 fill:#FFD700,stroke:#333
     style JP2 fill:#FFD700,stroke:#333
+    style CR fill:#87CEEB,stroke:#333
     style CB fill:#FF6B6B,stroke:#333
 ```
 
-Human involvement happens at exactly **2 points** (JP1, JP2) — everything else runs autonomously. If JP2 reveals issues with the requirements themselves, it loops back to JP1 — this is not a failure, but a normal discovery prompted by concrete deliverables.
+Human involvement happens at exactly **2 points** (JP1, JP2) — everything else runs autonomously. If JP2 reveals issues with the requirements themselves, it loops back to JP1 — this is not a failure, but a normal discovery prompted by concrete deliverables. After multiple JP2 revisions, **Crystallize** optionally reconciles all documents to match the finalized prototype before implementation begins.
 
 ---
 
@@ -66,23 +69,37 @@ npx jdd-sprint-kit init
 
 An interactive wizard detects your environment and installs Sprint Kit files.
 
-### (Optional) MCP Setup
+### (Optional) Connect Existing Service Data
 
-To connect existing service data, configure MCP servers:
+Sprint Kit can analyze your existing service code to avoid duplicate APIs and breaking changes. Three access methods exist, from simplest to most flexible:
 
+**Method 1: GitHub URL in brief.md** (simplest — no setup needed)
+Declare GitHub repo URLs in the `## Reference Sources` section of brief.md. Sprint auto-downloads a read-only snapshot via `gh api tarball/HEAD`.
+
+**Method 2: `--add-dir`** (for local clones)
+Add local repo directories when launching Claude Code:
 ```bash
-cp .mcp.json.example .mcp.json
-# Edit .mcp.json: update local paths for your environment
+claude --add-dir /path/to/backend-repo --add-dir /path/to/client-repo
 ```
 
+**Method 3: Figma MCP** (for live design data)
+```bash
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+```
+
+> Methods 1 and 2 were introduced in v0.4.0, replacing MCP filesystem servers which were restricted by Claude Code's MCP security to the project root directory only. Figma remains MCP because its data exists only on Figma's servers and cannot be downloaded as files.
+
 ### First Sprint Run
 
 ```bash
-# In Claude Code
+# In Claude Code — start a new feature (creates template if folder doesn't exist)
+/sprint my-feature-name
+
+# Or start immediately with an inline Brief
 /sprint "Describe the feature you want to build"
 ```
 
-### Tutorial — Try Without MCP
+### Tutorial
 
 To experience the full Sprint Kit pipeline, use the included example project:
 
@@ -91,7 +108,7 @@ To experience the full Sprint Kit pipeline, use the included example project:
 /sprint test-tutor-excl
 ```
 
-This is a scenario for adding a "tutor exclusion" feature to a fictional EduTalk service. 4 meeting notes are prepared in `specs/test-tutor-excl/inputs/`, and `brownfield-context.md` substitutes for MCP scan results. No MCP setup required.
+This is a scenario for adding a "tutor exclusion" feature to a fictional EduTalk service. 4 meeting notes are prepared in `specs/test-tutor-excl/inputs/`, and `brownfield-context.md` is pre-written to substitute for external data source scan results. No external data setup required.
 
 ---
 
@@ -101,6 +118,7 @@ This is a scenario for adding a "tutor exclusion" feature to a fictional EduTalk
 
 ```
 [Input + Brownfield + BMad] → [Specs] → JP1 → [Deliverables] → JP2 → [Execute]
+                                                                  ↳ [Crystallize] (optional)
 
 Sprint:   |←──────────────── Fully Auto ───────────────────────→|
 Guided:   |←── BMad Dialog ──→|←────────── Auto ───────────────→|
@@ -123,11 +141,12 @@ Routes are not fixed. If you have materials but need deep exploration, use Guide
 
 ## Brownfield — Existing System Integration
 
-AI must understand the existing service structure to avoid creating duplicate APIs or breaking existing screen flows. Brownfield data is cumulatively collected from **3 sources**:
+AI must understand the existing service structure to avoid creating duplicate APIs or breaking existing screen flows. Brownfield data is cumulatively collected from **4 sources**:
 
-1. **document-project artifacts** — Structured docs generated by BMad `/document-project` workflow scanning the existing codebase
-2. **MCP servers** — External memory stores the AI queries on demand
-3. **Local codebase** — Direct scan of source code in the same repository
+1. **document-project** — Structured docs generated by BMad `/document-project` workflow scanning the existing codebase
+2. **External repos** — Existing service code accessed via `--add-dir` (local clones) or tarball snapshot (GitHub URLs)
+3. **Figma** — Live design data accessed via MCP (OAuth)
+4. **Local codebase** — Direct scan of source code in the current project
 
 ### Brownfield Context Generation
 
@@ -135,7 +154,7 @@ AI must understand the existing service structure to avoid creating duplicate AP
 
 `/sprint` automatically generates brownfield-context.md:
 
-1. **Phase 0** — Topology detection: detect document-project presence, MCP connectivity, build tools to determine project type (`standalone` / `co-located` / `msa` / `monorepo`)
+1. **Phase 0** — Topology detection: detect document-project presence, external data sources (`--add-dir` paths, GitHub repo URLs, Figma MCP), build tools → determine project type (`standalone` / `co-located` / `msa` / `monorepo`)
 2. **Pass 1 (Broad Scan)** — Collect domain concepts (L1) and behavior patterns (L2) based on Brief keywords
 3. **Pass 2 (Targeted Scan)** — After Architecture/Epics, collect integration points (L3) and code-level details (L4)
 
@@ -150,22 +169,29 @@ Running BMad `/document-project` before Sprint improves scan quality:
 /document-project
 ```
 
-This analyzes the existing codebase and generates structured docs under `_bmad-output/` (`project-overview.md`, `api-contracts.md`, `data-models.md`, etc.). Sprint's Brownfield Scanner uses these as seed data to narrow MCP/local scan scope.
+This analyzes the existing codebase and generates structured docs under `_bmad-output/` (`project-overview.md`, `api-contracts.md`, `data-models.md`, etc.). Sprint's Brownfield Scanner uses these as seed data to narrow scan scope.
+
+#### External Data Sources
+
+External service data can be provided through 3 methods (see Quick Start for setup):
 
-#### MCP Server Configuration
+| Source Type | Access Method | When to Use |
+|-------------|---------------|-------------|
+| **External repos** (backend, client, service-map) | `--add-dir` (local clone) or tarball snapshot (GitHub URL in brief.md) | When existing service code needs analysis |
+| **Figma** | MCP (OAuth) | When live design data needs analysis |
 
-To connect external service data, configure MCP servers:
+The 4 roles external data can fill:
 
-| MCP Server | Provided Information |
-|------------|---------------------|
-| `backend-docs` | API specs, domain policies, business rules, data models |
-| `client-docs` | Component structure, state management patterns, code conventions, screen flows |
-| `svc-map` | Customer journeys, screen screenshots, flow graphs, service maps |
-| `figma` | Latest wireframes, design tokens, component specs (live OAuth) |
+| Role | Provided Information |
+|------|---------------------|
+| **backend-docs** | API specs, domain policies, business rules, data models |
+| **client-docs** | Component structure, state management patterns, screen flows |
+| **svc-map** | Customer journeys, screen screenshots, flow graphs |
+| **figma** | Wireframes, design tokens, component specs |
 
-#### Manual Preparation (Without MCP)
+#### Manual Preparation (Without External Sources)
 
-You can manually write brownfield-context.md and provide it to Sprint without MCP:
+You can manually write brownfield-context.md and provide it to Sprint without any external data:
 
 ```bash
 # Place directly in the feature directory
@@ -210,7 +236,8 @@ For Greenfield projects with no existing system, Sprint works normally without B
 │       ├── api-spec.yaml            # OpenAPI 3.1
 │       ├── schema.dbml              # DB schema
 │       ├── bdd-scenarios/           # Gherkin acceptance tests
-│       └── preview/                 # React + MSW prototype
+│       ├── preview/                 # React + MSW prototype
+│       └── reconciled/              # Crystallize output (prototype-reconciled artifacts)
 └── docs/                            # Framework documentation
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jdd-sprint-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Judgment-Driven Development toolkit for BMad Method",
   "type": "module",
   "bin": {

package/templates/.claude/agents/auto-sprint.md

@@ -68,7 +68,8 @@ Specify `model: "sonnet"` parameter on Task invocation. When unspecified, parent
 2. Set budget: simple=20, medium=40, complex=60 max_turns per sub-agent
 3. Ensure `specs/{feature_name}/planning-artifacts/` directory exists
 4. If `force_jp1_review` flag → show Grade C Brief warning banner at JP1
-5. Initialize Sprint Log: Create `specs/{feature_name}/sprint-log.md` with Timeline table header + Decisions Made + Issues Encountered sections
+5. Initialize Sprint Log: Create `specs/{feature_name}/sprint-log.md` with Timeline table header + JP Interactions + Decisions Made + Issues Encountered sections
+6. Initialize Decision Diary: Create `specs/{feature_name}/decision-diary.md` with Sprint Context (complexity, topology, goals) + Decisions table header
 6. Record Sprint start time for adaptive time estimation
 7. Display initial progress with complexity-based time estimate from sprint-input.md
 
@@ -578,8 +579,10 @@ When feedback arises from any path (A, P, or F), process with the same mechanism
    - **[M] Apply fix + propagate**: Edit all dependent files bidirectionally (upstream + downstream) per feedback item → Scope Gate verification → on PASS return to JP, on FAIL show missing items + offer additional fix or switch to regenerate
      - At JP1: Scope Gate `stage=spec`
      - At JP2: Scope Gate `stage=spec` + `stage=deliverables` (run both)
-   - **[R] Regenerate**: Record feedback in `specs/{feature_name}/planning-artifacts/feedback-log.md` → re-run pipeline from affected Phase (includes Scope Gate)
-5. **Record feedback**: Regardless of processing method, record feedback content + selected method + result in `feedback-log.md`
+   - **[R] Regenerate**: Record feedback → re-run pipeline from affected Phase (includes Scope Gate)
+5. **Record interaction**: Regardless of processing method:
+   - Append full exchange to sprint-log.md **JP Interactions** section (Visual Summary presented, user input, impact analysis, processing choice, result)
+   - Append structured row to decision-diary.md **Decisions** table (JP, Type, Content, Processing, Result)
 
 ### Step 5: Deliverables Generation
 
@@ -703,15 +706,16 @@ npm install && npm run dev
 
 > To provide feedback, select [F] Comment. Apply-fix/regenerate options will be presented with cost.
 
-#### Step 6b: A/P/C Menu
+#### Step 6b: A/P/S/C Menu
 
-Present 5 options via AskUserQuestion (same structure as JP1, in {communication_language}):
+Present 6 options via AskUserQuestion (in {communication_language}):
 
 | Option | Label | Description |
 |--------|-------|-------------|
 | **A** | Advanced Elicitation | Deep exploration of Deliverables (API Spec, BDD, Prototype focus) |
 | **P** | Party Mode | Multi-perspective review by full BMad agent panel |
-| **C** | Continue | Approve JP2 → proceed to Execute (parallel implementation) |
+| **S** | Crystallize | Finalize all documents to match prototype, then proceed to execution |
+| **C** | Continue | Approve JP2 → proceed to Execute with current documents |
 | **F** | Comment | Enter feedback → impact analysis → apply-fix/regenerate choice |
 | **X** | Exit | Abort Sprint |
 
@@ -721,11 +725,24 @@ Present 5 options via AskUserQuestion (same structure as JP1, in {communication_
 |-----------|--------|
 | **A** | Ask user for exploration target (api-spec/bdd/prototype/schema) → read full file → present 3~5 questions from Advanced Elicitation Protocol JP2 set → on feedback: execute **Comment handling flow** → regenerate Visual Summary → return to menu |
 | **P** | Invoke Party Mode workflow (`Skill("bmad:core:workflows:party-mode")`, pass JP2 artifact paths) → discussion summary → ask user to accept/reject → on accept: execute **Comment handling flow** → regenerate Visual Summary → return to menu |
-| **C** | Proceed to Execute (parallel implementation) |
+| **S** | Execute **Crystallize pipeline** (see below) → on completion proceed to Execute with `specs_root=reconciled/` |
+| **C** | Proceed to Execute (parallel implementation) with `specs_root=specs/{feature_name}/` |
 | **F** | Execute **Comment handling flow** (see Step 4c) → regenerate Visual Summary → return to menu |
 | **X** | Abort Sprint, inform that artifacts are preserved (`specs/{feature_name}/` is retained) |
 
-**Iteration limit**: A/P/F selections combined max 5 times. On exceed, warn (in {communication_language}): "5 review/edit rounds complete. Select [C] Continue or [X] Exit."
+**Iteration limit**: A/P/F selections combined max 5 times. On exceed, warn (in {communication_language}): "5 review/edit rounds complete. Select [S] Crystallize, [C] Continue, or [X] Exit."
+
+#### [S] Crystallize Pipeline
+
+When [S] is selected, execute the Crystallize pipeline as defined in `.claude/commands/crystallize.md`.
+
+1. Record `[S] Crystallize` selection in decision-diary.md
+2. Append to sprint-log.md JP Interactions: `**[User] Selection: [S] Crystallize**`
+3. Execute the full Crystallize pipeline (S1-S6) as defined in crystallize.md, passing `feature_name`
+4. On Crystallize S6 [C] Continue: proceed to Execute with `specs_root=specs/{feature_name}/reconciled/`
+5. On Crystallize S6 [X] Exit: return to JP2 menu (reconciled/ is preserved)
+
+**Budget**: Crystallize has its own budget (~85-120 turns) separate from JP2 iteration budget (5 rounds). [S] does not count against the 5-round iteration limit.
 
 ## Conductor Roles
 
@@ -765,7 +782,7 @@ When drift is detected (Scope Gate FAIL or goal drift):
 5. **3 consecutive FAILs on optional stages** → skip stage + include warning in final output
 
 **B. Upstream Issue** (`failure_source: upstream:{stage}`):
-1. Record Scope Gate's `suggested_fix` in `planning-artifacts/feedback-log.md`
+1. Record Scope Gate's `suggested_fix` in `decision-diary.md`
 2. Re-invoke cause stage (`{stage}`) agent — include feedback in prompt:
    "Previous artifact received the following feedback:
    <feedback>{suggested_fix content}</feedback>
@@ -798,7 +815,7 @@ When Comment handling flow executes at a JP, process according to user's selecte
 
 When user selects [M] Apply fix + propagate:
 
-1. Record feedback items in `specs/{feature_name}/planning-artifacts/feedback-log.md`
+1. Record feedback items in `specs/{feature_name}/decision-diary.md`
 2. For each feedback item, traverse affected files bidirectionally and edit:
    - **upstream** (specs → planning-artifacts): edit planning-artifacts files where the concept is expressed
    - **downstream** (planning-artifacts → specs → deliverables): edit specs/deliverables files where the concept is expressed
@@ -813,7 +830,7 @@ When user selects [M] Apply fix + propagate:
 
 When user selects [R] Regenerate:
 
-1. Record feedback text in `specs/{feature_name}/planning-artifacts/feedback-log.md`
+1. Record feedback text in `specs/{feature_name}/decision-diary.md`
 2. Back up existing artifacts then overwrite (preserve previous versions)
 3. Include feedback in prompt when invoking restart stage agent:
    ```

package/templates/.claude/agents/deliverable-generator.md

@@ -23,6 +23,7 @@ Progress-oriented. Reports each pipeline stage completion with counts (e.g., "Op
   - **full**: Run the complete 10-Stage pipeline
   - **specs-only**: Run Stage 1-2 only (invoked by /specs — generates Entity Dictionary + Specs 4-file only)
   - **deliverables-only**: Run Stage 3-10 only (invoked by /preview or Auto Sprint after JP1 approval — requires pre-existing Specs 4-file)
+- `prototype_analysis_path` (optional): Path to prototype-analysis.md — used as cross-reference during specs-only mode when invoked by /crystallize. When present, use the prototype analysis to validate entity naming, verify API endpoint coverage, and cross-check user flows against PRD FRs. When absent, behavior is unchanged (backward compatible).
 
 ## Execution Protocol — 10-Stage Pipeline
 

package/templates/.claude/commands/parallel.md

@@ -18,12 +18,17 @@ After Specs + Deliverables generation is complete. Run after JP2 approval.
 
 `$ARGUMENTS`: not used
 
+Parameters (when invoked from auto-sprint):
+- `specs_root`: Base directory for specs files. Default: `specs/{feature}/`. After Crystallize: `specs/{feature}/reconciled/`.
+
 Prerequisites:
-- `specs/{feature}/tasks.md` exists
-- `specs/{feature}/brownfield-context.md` exists
+- `{specs_root}/tasks.md` exists
+- `{specs_root}/brownfield-context.md` exists (or `{specs_root}/planning-artifacts/brownfield-context.md` for reconciled/)
 - File Ownership assignment complete
 - Interface contracts (shared types) defined
 
+**Path resolution**: All specs file references in this command use `{specs_root}` as base path. When `specs_root` is not provided, default to `specs/{feature}/`.
+
 ## Procedure
 
 Load config per Language Protocol in bmad-sprint-guide.md.

package/templates/.claude/commands/sprint.md

@@ -78,7 +78,12 @@ Parse `$ARGUMENTS` — 2 entry points, 1 pipeline:
 3. **Verify specs/{feature_name}/ exists**:
    If missing → auto-create + guide:
    a. Create `specs/{feature_name}/inputs/`
-   b. Generate `specs/{feature_name}/inputs/brief.md` template:
+   b. Generate `specs/{feature_name}/inputs/brief.md` template (in {document_output_language}):
+      Section headings and placeholder text must be written in {document_output_language}.
+      HTML comments (guidance for the user) are written in {communication_language}.
+      The `## Reference Sources` section heading and sub-section headings are always in English (machine-parseable).
+
+      Example (when document_output_language=Korean, communication_language=Korean):
       ```markdown
       # {feature_name}
 
@@ -88,7 +93,7 @@ Parse `$ARGUMENTS` — 2 entry points, 1 pipeline:
       ## 만들어야 할 기능
       (구체적인 기능을 설명하세요)
 
-      ## 참고 소스
+      ## Reference Sources
 
       ### GitHub
       <!-- 기존 서비스 코드가 있으면 URL과 탐색 힌트를 작성하세요 -->
@@ -99,11 +104,11 @@ Parse `$ARGUMENTS` — 2 entry points, 1 pipeline:
       <!-- Figma 디자인 URL이 있으면 작성하세요 -->
       <!-- - https://figma.com/design/{fileKey}/... -->
 
-      ### 정책 문서
+      ### Policy Docs
       <!-- Scanner가 우선 탐색할 정책/도메인 문서명 -->
       <!-- - document-name.md -->
 
-      ### 탐색 메모
+      ### Scan Notes
       <!-- Brownfield 탐색 시 참고할 자유 형식 메모 -->
       ```
    c. Message (in {communication_language}):
@@ -281,16 +286,16 @@ See `_bmad/docs/sprint-input-format.md` for reference analysis format.
    - 5 or fewer: include all (default: included in Sprint scope)
    - Over 5: include top 3, rest as "next Sprint candidates"
 4. **Contradiction detection**: Record contradictions between Brief and references in Detected Contradictions (no auto-resolution)
-5. **Parse '참고 소스' section from brief.md** (if exists):
-   - Detect heading: `## 참고 소스` / `## Reference Sources` / `## References`
-   - Parse sub-sections:
-     - `### GitHub`: extract URLs + per-URL notes (indented text below URL)
+5. **Parse Reference Sources section from brief.md** (if exists):
+   - Detect heading (canonical → fallback): `## Reference Sources` / `## 참고 소스` / `## References`
+   - Parse sub-sections (canonical → fallback):
+     - `### GitHub` / `### GitHub`: extract URLs + per-URL notes (indented text below URL)
        - URL pattern: `https://github.com/{owner}/{repo}` (`.git` suffix auto-strip)
        - Notes: non-URL indented lines below each URL
-     - `### Figma`: extract URLs + notes
+     - `### Figma` / `### Figma`: extract URLs + notes
        - URL pattern: `https://figma.com/design/{fileKey}/...` or `.../file/{fileKey}/...`
-     - `### 정책 문서` / `### Policy Docs`: collect document names (line items)
-     - `### 탐색 메모` / `### Scan Notes`: collect as free-text
+     - `### Policy Docs` / `### 정책 문서`: collect document names (line items)
+     - `### Scan Notes` / `### 탐색 메모`: collect as free-text
    - 참고 소스 섹션의 GitHub repos는 사용자 명시 의도 → AskUserQuestion 없이 다운로드 대상 확정
    - 섹션이 없거나 비어있으면 → skip (기존 auto-detect만 사용)
    - HTML 주석으로 감싸인 라인 (`<!-- ... -->`)은 skip (템플릿 상태 그대로)

package/templates/.claude/commands/validate.md

@@ -18,11 +18,16 @@ After Worker implementation is complete. Run after PARALLEL completion + merge.
 
 `$ARGUMENTS`: not used
 
+Parameters (when invoked from auto-sprint):
+- `specs_root`: Base directory for specs files. Default: `specs/{feature}/`. After Crystallize: `specs/{feature}/reconciled/`.
+
 Prerequisites:
 - PARALLEL complete: all Worker tasks done
 - Code merged into main branch
 - Build succeeds
 
+**Path resolution**: All specs file references in this command use `{specs_root}` as base path. When `specs_root` is not provided, default to `specs/{feature}/`. This ensures Judges verify against reconciled artifacts when Crystallize was used.
+
 ## Procedure
 
 Load config per Language Protocol in bmad-sprint-guide.md.
@@ -42,8 +47,8 @@ Phase 1 failure → request fix from file's owning Worker → re-run Phase 1 aft
 ### Phase 2: AI Judge Verification (Medium + Low Entropy)
 Run Judge agents in parallel. Pass each Judge:
 - `changed_files`: result of `git diff --name-only {base_branch}...HEAD`
-- `feature_dir`: `specs/{feature}/`
-- `brownfield_path`: `specs/{feature}/brownfield-context.md`
+- `feature_dir`: `{specs_root}` (default: `specs/{feature}/`)
+- `brownfield_path`: `{specs_root}/brownfield-context.md` (or `{specs_root}/planning-artifacts/brownfield-context.md` for reconciled/)
 
 1. **Code Quality Judge** (`judge-quality`):
    - Code structure, patterns, duplication

package/templates/.claude/rules/bmad-sprint-guide.md

@@ -61,6 +61,7 @@ Place materials in specs/{feature}/inputs/ → /sprint {feature-name}
   → JP1: "Is this the right product for the customer?" (requirements judgment)
   Phase 2: Deliverables (OpenAPI + DBML + BDD + Prototype)
   → JP2: "Is this the experience the customer wants?" (prototype judgment)
+  → [S] Crystallize (optional): reconcile all artifacts with finalized prototype → reconciled/
   → On approval: /parallel → /validate
 ```
 
@@ -140,6 +141,7 @@ Routes are not fixed. Adapt as needed:
 - `/sprint` — **Sprint route**: Brief/materials → auto Specs + Deliverables + Prototype (2 JPs)
 - `/specs` — **Specs generation**: Planning Artifacts → Specs 4-file
 - `/preview` — **Deliverables generation**: Specs → OpenAPI + DBML + BDD + Prototype
+- `/crystallize` — **Prototype reconciliation**: Finalized prototype → reconciled/ artifact set (Sprint-route only)
 - `/parallel` — Multi-agent parallel execution
 - `/validate` — 3-Phase verification pipeline
 - `/circuit-breaker` — Course correction

package/templates/.claude/rules/bmad-sprint-protocol.md

@@ -17,6 +17,7 @@ Brownfield data is used at every Sprint phase. Sources are cumulatively collecte
 | **Specs generation** (`/specs`) | Copy frozen snapshot (@deliverable-generator Stage 2) |
 | **Parallel** (`/parallel`) | Workers read frozen snapshot |
 | **Validate** (`/validate`) | Judges verify against brownfield-context.md |
+| **Crystallize** (`/crystallize`) | Copy brownfield-context.md to reconciled/planning-artifacts/ (unchanged) |
 
 ## Causal Chain Propagation Flow (Optional)
 
@@ -70,7 +71,8 @@ specs/{feature}/
 │   ├── epics-and-stories.md    # Epics & Stories
 │   └── brownfield-context.md   # L1~L4 raw collection (appended during work)
 │
-├── sprint-log.md               # Sprint execution log (timeline + decisions + issues)
+├── sprint-log.md               # Sprint execution log (timeline + decisions + issues + JP Interactions)
+├── decision-diary.md           # JP decision summary table (replaces feedback-log.md)
 ├── brownfield-context.md       # Frozen snapshot (L1~L4, for Workers)
 ├── entity-dictionary.md        # Entity Dictionary
 ├── requirements.md             # PRD → requirements
@@ -86,7 +88,27 @@ specs/{feature}/
 ├── traceability-matrix.md      # FR → Design → Task → BDD → API mapping
 ├── key-flows.md                # Key user flows step-by-step (for JP2 verification)
 ├── readiness.md                # JP1/JP2 Readiness data (for Layer 0 auto-approval)
-└── preview/                    # React + MSW prototype (npm run dev)
+├── preview/                    # React + MSW prototype (npm run dev)
+│
+└── reconciled/                 # Crystallize output (prototype-reconciled artifact set)
+    ├── prototype-analysis.md   # Prototype structure analysis
+    ├── planning-artifacts/     # Reconciled planning artifacts
+    │   ├── prd.md              # PRD final (reconciled with prototype)
+    │   ├── architecture.md     # Architecture final (reconciled)
+    │   ├── epics-and-stories.md # Epics final (reconciled)
+    │   └── brownfield-context.md # Copy (unchanged)
+    ├── entity-dictionary.md    # Reconciled entity dictionary
+    ├── requirements.md         # Reconciled requirements
+    ├── design.md               # Reconciled design
+    ├── tasks.md                # Reconciled tasks (with Entropy + File Ownership)
+    ├── api-spec.yaml           # Verified/regenerated API contract
+    ├── api-sequences.md        # Verified/regenerated sequence diagrams
+    ├── schema.dbml             # Verified/regenerated DB schema
+    ├── bdd-scenarios/          # Regenerated acceptance tests
+    ├── key-flows.md            # Regenerated key flows
+    ├── traceability-matrix.md  # Rebuilt traceability
+    ├── decision-log.md         # Merged decision history
+    └── decision-diary.md       # Copy of JP decision summary
 ```
 
 ## Handoff Rules
@@ -142,7 +164,7 @@ See `docs/judgment-driven-development.md` Customer-Lens Judgment Points.
 
 - **Judgment target**: prototype, screen flows, interactions
 - **Presentation format**: working prototype + key scenario walkthrough guide
-- **Response**: Confirm / Comment
+- **Response**: Confirm / Crystallize (Sprint-route only) / Comment
 
 ### Comment Handling Flow
 
@@ -176,3 +198,95 @@ Guide for determining regeneration start point based on feedback magnitude:
 
 This table is a reference for the system when calculating regeneration scope during impact analysis.
 Users see the calculated cost alongside the options.
+
+## Crystallize Flow (Sprint-route only)
+
+After JP2 prototype iteration, [S] Crystallize reconciles all upstream artifacts with the finalized prototype. Creates `reconciled/` directory with the definitive artifact set.
+
+**Availability**: Sprint-route only. Depends on Sprint artifacts (decision-diary.md, sprint-log.md JP Interactions). Not available for Guided/Direct routes.
+
+### Crystallize Pipeline
+
+```
+[S] Crystallize at JP2
+  S1: Prototype Analysis        → reconciled/prototype-analysis.md
+  S2: Reconcile Planning        → reconciled/planning-artifacts/ (PRD, Architecture, Epics)
+  S2-G: Cross-Artifact Gate     → PASS/FAIL
+  S3: Generate Execution Specs  → reconciled/ (entity-dict, requirements, design, tasks)
+  S3-G: Scope Gate (spec)       → PASS/FAIL
+  S4: Reconcile Deliverables    → reconciled/ (api-spec, bdd, key-flows, traceability, etc.)
+  S5: Cross-Artifact Consistency → PASS/FAIL (gap=0 required)
+  S6: Summary → [C] /parallel with specs_root=reconciled/
+```
+
+### Reconciliation Principles
+
+- **From prototype**: screens, features, API endpoints, data model, user flows
+- **Carry-forward from existing docs**: NFRs, security, deployment, scaling, monitoring, ADRs
+- **Product Brief excluded**: defines problem space, not derivable from prototype
+
+### Source Attribution Tags (Crystallize)
+
+| Tag | Meaning |
+|-----|---------|
+| `(source: PROTO, origin: BRIEF-N)` | Confirmed in prototype, originally from brief sentence N |
+| `(source: PROTO, origin: DD-N)` | Confirmed in prototype, originated from decision-diary entry N |
+| `(source: carry-forward, origin: BRIEF-N)` | Not in prototype, carried from original doc, originally from brief |
+| `(source: carry-forward)` | Not in prototype, carried from original doc (NFR, security, etc.) |
+
+Items carried forward from existing documents are marked with `[carry-forward]` inline tag in the reconciled artifact text.
+
+### Downstream Integration
+
+After Crystallize, `/parallel` and `/validate` use `specs_root` parameter to read from `reconciled/` instead of the base `specs/{feature}/` directory. Original artifacts remain untouched.
+
+## Sprint Log Extension: JP Interactions
+
+sprint-log.md is extended with a **JP Interactions** section that records the full text of each JP exchange.
+
+```markdown
+## JP Interactions
+
+### JP1 Round 1
+**[System] Visual Summary**
+{Visual Summary full text}
+
+**[User] Selection: [F] Comment**
+{user feedback text}
+
+**[System] Impact Analysis**
+{analysis result}
+
+**[User] Choice: [M] Apply fix**
+
+**[System] Result**
+Files modified: {list}
+Scope Gate: PASS
+```
+
+**Recording points**: After each AskUserQuestion response at JP1 (Step 4b/4c) and JP2 (Step 6b/6c), append the exchange to sprint-log.md JP Interactions section.
+
+## Decision Diary
+
+decision-diary.md is a structured table of JP decisions and feedback. Replaces feedback-log.md.
+
+**Role differentiation**:
+- **sprint-log.md**: execution timeline + JP interaction full text (for AI context and audit)
+- **decision-diary.md**: structured decision summary (for product expert quick reference)
+
+**Format**:
+```markdown
+# Decision Diary: {feature_name}
+
+## Sprint Context
+- Complexity: {simple/medium/complex}
+- Topology: {co-located/msa/monorepo/standalone}
+- Goals: {goals list}
+- Crystallize: {Yes/No}
+
+## Decisions
+| # | JP | Type | Content | Processing | Result |
+|---|-----|------|---------|------------|--------|
+```
+
+**Recording point**: After each Comment Handling Flow completion, append a row to the Decisions table.