jdd-sprint-kit 0.5.1 → 0.5.3

package/README.md

@@ -131,6 +131,8 @@ Direct:                        |←── Auto ───────────
 | **Guided** | BMad 12-step → `/specs` → `/preview` | Exploration needed — discover and define with AI |
 | **Direct** | `/specs` → `/preview` | Planning is complete — execute immediately |
 
+After prototype iteration, `/crystallize feature-name` reconciles all documents to match the finalized prototype (available on all routes).
+
 > For small tasks, use BMad Quick Flow: `/quick-spec` → `/dev-story` → `/code-review`
 
 Routes are not fixed. If you have materials but need deep exploration, use Guided with materials as reference input. After completing BMad 12-step, `/specs` auto-detects the artifacts — same as Direct.

package/package.json

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

package/src/lib/manifest.js

@@ -24,7 +24,7 @@ export const SPRINT_KIT_FILES = {
     'validate.md', 'circuit-breaker.md', 'summarize-prd.md',
   ],
   rules: [
-    'bmad-sprint-guide.md', 'bmad-sprint-protocol.md', 'bmad-mcp-search.md',
+    'jdd-sprint-guide.md', 'jdd-sprint-protocol.md', 'jdd-mcp-search.md',
   ],
   hooks: [
     'sprint-pre-compact.sh', 'sprint-session-recovery.sh',

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

@@ -557,7 +557,7 @@ When feedback arises from any path (A, P, or F), process with the same mechanism
    - F: Free-text entered directly by user
 2. **Impact analysis**: Calculate feedback scope
    - For apply-fix: list of affected files (upstream planning-artifacts/ + downstream specs/ + deliverables) + estimated time
-   - For regenerate: restart Phase based on Regeneration Scope Reference Table (`bmad-sprint-protocol.md`) + estimated time
+   - For regenerate: restart Phase based on Regeneration Scope Reference Table (`jdd-sprint-protocol.md`) + estimated time
 3. **Present options**: Offer cost-based choices via AskUserQuestion (in {communication_language})
    ```
    Modifications:
@@ -738,11 +738,11 @@ When [S] is selected, execute the Crystallize pipeline as defined in `.claude/co
 
 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`
+3. Execute the full Crystallize pipeline (S0-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.
+**Budget**: Crystallize has its own budget (~85-125 turns) separate from JP2 iteration budget (5 rounds). [S] does not count against the 5-round iteration limit.
 
 ## Conductor Roles
 

package/templates/.claude/commands/circuit-breaker.md

@@ -24,7 +24,7 @@ Systematically correct course when VALIDATE failures repeat or critical issues a
 
 ## Procedure
 
-Load config per Language Protocol in bmad-sprint-guide.md.
+Load config per Language Protocol in jdd-sprint-guide.md.
 
 ### Step 1: Failure Context Summary (Context Compaction)
 Summarize current work state and append to `specs/{feature}/planning-artifacts/circuit-breaker-log.md`:

package/templates/.claude/commands/crystallize.md

@@ -1,19 +1,19 @@
 ---
-description: "Reconcile all artifacts from finalized prototype (Sprint-route only)"
+description: "Reconcile all artifacts from finalized prototype"
 ---
 
 <!-- Quick Map
   Purpose: Finalized prototype → reconciled/ artifact set
   Dispatch: Runs directly (orchestrates BMad agents + @deliverable-generator)
   Inputs: $ARGUMENTS (feature-name)
-  Key Steps: Precondition → Analyze → Reconcile Planning → Generate Specs → Reconcile Deliverables → Verify → Summary
-  Route: Sprint-route only (depends on decision-diary.md, sprint-log.md JP Interactions)
+  Key Steps: Precondition → Decision Context → Analyze → Reconcile Planning → Generate Specs → Reconcile Deliverables → Verify → Summary
+  Route: All routes (Sprint, Guided, Direct)
 -->
 
 # /crystallize — Prototype-First Artifact Reconciliation
 
 > **Dispatch**: Runs directly (orchestrates sub-agents sequentially)
-> **Route**: Sprint-route only
+> **Route**: All routes (Sprint, Guided, Direct)
 
 ## Purpose
 
@@ -25,9 +25,9 @@ The prototype becomes the source of truth for product behavior. Existing artifac
 
 - After iterating on a prototype at JP2 until it matches the desired product
 - When documents need to accurately reflect the final product for execution (/parallel) and long-term reference (maintenance, handoff)
-- Sprint-route only — requires Sprint artifacts (decision-diary.md, sprint-log.md with JP Interactions)
+- Available on all routes: Sprint (`[S]` at JP2), Guided (`[S]` at `/preview` Step 3), Direct (`[S]` at `/preview` Step 3), or standalone (`/crystallize feature-name`)
 
-**Note**: Within `/sprint` auto-sprint flow, Crystallize is triggered via [S] Crystallize menu option at JP2. This standalone command is for cases where JP2 was completed with [C] but reconciliation is needed later.
+**Note**: Within `/sprint` auto-sprint flow, Crystallize is triggered via [S] Crystallize menu option at JP2. Within `/preview`, it is triggered via [S] at Step 3. The standalone command is for cases where JP2 was completed with [C] but reconciliation is needed later.
 
 ## Inputs
 
@@ -40,26 +40,64 @@ Before starting the pipeline, verify:
 
 1. `specs/{feature}/preview/` exists AND `src/` contains at least one `.tsx` file (Glob: `specs/{feature}/preview/src/**/*.tsx`)
 2. `specs/{feature}/planning-artifacts/` exists with `prd.md`, `architecture.md`, `epics-and-stories.md` (all 3 required)
-3. `specs/{feature}/sprint-log.md` exists (decision-diary.md is optional)
+3. Decision records available (optional — enriches S0 context when present):
+   - `specs/{feature}/decision-diary.md` OR `specs/{feature}/jp2-review-log.md` OR `specs/{feature}/sprint-log.md`
+   - If none exist, S0 is skipped and S1 runs without decision context
 4. If `specs/{feature}/reconciled/` already exists: prompt user — overwrite or abort
 
 On validation failure: report missing items (in {communication_language}) and abort.
 
 ## Procedure
 
-Load config per Language Protocol in bmad-sprint-guide.md.
+Load config per Language Protocol in jdd-sprint-guide.md.
 
-### Step S1: Prototype Analysis
+### Step S0: Decision Context Analysis
 
-Analyze the finalized prototype code and produce a structured analysis document.
+Analyze JP2 decision records to understand the intent and context behind prototype modifications BEFORE analyzing the code. This enables S1 and S2 to distinguish deliberate business decisions from implementation details.
 
-**Progress**: `"[S1/6] Analyzing prototype structure..."`
+**Progress**: `"[S0/7] Analyzing JP2 decision context..."`
 
-1. Create `specs/{feature}/reconciled/` directory
+1. Create `specs/{feature}/reconciled/` directory and `reconciled/planning-artifacts/`
 2. Copy immutable files:
    - `specs/{feature}/planning-artifacts/brownfield-context.md` → `reconciled/planning-artifacts/brownfield-context.md`
-   - `specs/{feature}/decision-diary.md` → `reconciled/decision-diary.md` (if exists)
-3. Invoke prototype analyzer:
+3. Copy decision records to reconciled/ (if exists):
+   - `specs/{feature}/decision-diary.md` → `reconciled/decision-diary.md`
+   - OR `specs/{feature}/jp2-review-log.md` → `reconciled/jp2-review-log.md` (fallback, serves equivalent role)
+4. Read JP2 decision records:
+   - Primary: `specs/{feature}/decision-diary.md` (if exists)
+   - Fallback: `specs/{feature}/jp2-review-log.md` (if exists, serves equivalent role)
+   - Also: `specs/{feature}/sprint-log.md` "JP Interactions" section (if exists)
+5. Produce decision context summary (Conductor writes directly — lightweight synthesis, not a Task):
+
+Write to `specs/{feature}/reconciled/decision-context.md`:
+
+```markdown
+# Decision Context: {feature_name}
+
+## Route
+{sprint / guided / direct} — {rich context / limited context}
+
+## JP2 Modification Intent Summary
+| # | Change | Intent | Business Decision | Affected Area |
+|---|--------|--------|-------------------|---------------|
+
+## Key Business Decisions
+| ID | Decision | Rationale |
+|----|----------|-----------|
+
+## Context for Prototype Analysis
+(Free-text summary: what to look for in the code, which changes are deliberate business decisions vs implementation adjustments)
+```
+
+If no decision records exist, skip this step and proceed to S1 without decision context. When decision records are minimal (Guided/Direct routes), S0 produces a lighter context document — prototype analysis (S1) carries more weight in this case.
+
+### Step S1: Prototype Analysis
+
+Analyze the finalized prototype code and produce a structured analysis document.
+
+**Progress**: `"[S1/7] Analyzing prototype structure..."`
+
+Invoke prototype analyzer:
 
 ```
 Task(subagent_type: "general-purpose", model: "sonnet")
@@ -69,6 +107,15 @@ Task(subagent_type: "general-purpose", model: "sonnet")
 
     Read every discovered file and extract a structured analysis.
 
+    IMPORTANT: Write ALL output in {document_output_language}.
+
+    {if decision-context.md exists}
+    Decision context (read this FIRST to understand WHY changes were made):
+      specs/{feature}/reconciled/decision-context.md
+    Use this context to annotate business rules with their decision origin
+    (e.g., 'Business Rule: 용어 변경 → D2 결정에 의한 의도적 선택').
+    {end if}
+
     Output format — write to specs/{feature}/reconciled/prototype-analysis.md:
 
     # Prototype Analysis: {feature_name}
@@ -97,7 +144,7 @@ Reconcile PRD, Architecture, and Epics using the prototype analysis as primary i
 
 **Product Brief is excluded** — it defines the problem space, which the prototype cannot supply.
 
-**Progress**: `"[S2/6] Reconciling PRD..."` → `"...Architecture..."` → `"...Epics..."` → `"...Cross-artifact validation..."`
+**Progress**: `"[S2/7] Reconciling PRD..."` → `"...Architecture..."` → `"...Epics..."` → `"...Cross-artifact validation..."`
 
 #### Reconciliation Principles
 
@@ -121,22 +168,26 @@ Task(subagent_type: "general-purpose", model: "opus")
   prompt: "You are John, Product Manager. Read your persona at _bmad/bmm/agents/pm.md.
     Read the PRD format guide at _bmad/docs/prd-format-guide.md.
 
+    IMPORTANT: Write ALL output in {document_output_language}.
+
     MODE: CRYSTALLIZE — reconcile PRD with finalized prototype.
 
     Primary input (what the product actually does):
       specs/{feature}/reconciled/prototype-analysis.md
 
+    Decision context (understand WHY changes were made):
+      specs/{feature}/reconciled/decision-context.md (if exists)
+
     Context reference (for content the prototype cannot supply):
       specs/{feature}/planning-artifacts/prd.md
-      specs/{feature}/decision-diary.md (if exists)
-      specs/{feature}/inputs/sprint-input.md (for brief_sentences)
+      specs/{feature}/inputs/sprint-input.md (for brief_sentences, if exists)
 
     Output: Write to specs/{feature}/reconciled/planning-artifacts/prd.md
 
     Reconciliation rules:
     - Every capability visible in prototype → document as FR with source tag
     - Map each FR to brief_sentences where possible: (source: PROTO, origin: BRIEF-N)
-    - Features from JP2 iteration: (source: PROTO, origin: DD-N) referencing decision-diary entry
+    - Features from JP2 iteration: (source: PROTO, origin: DD-N) referencing decision-diary/decision-context entry
     - NFRs, success criteria, constraints → carry forward: (source: carry-forward)
     - Mark carry-forward items with [carry-forward] tag
     - User journeys: reconstruct from prototype User Flows section
@@ -150,12 +201,17 @@ Task(subagent_type: "general-purpose", model: "opus")
 Task(subagent_type: "general-purpose", model: "opus")
   prompt: "You are Winston, Architect. Read your persona at _bmad/bmm/agents/architect.md.
 
+    IMPORTANT: Write ALL output in {document_output_language}.
+
     MODE: CRYSTALLIZE — reconcile Architecture with finalized prototype.
 
     Primary input:
       specs/{feature}/reconciled/prototype-analysis.md
       specs/{feature}/reconciled/planning-artifacts/prd.md (just written by S2a)
 
+    Decision context (understand WHY design decisions were made):
+      specs/{feature}/reconciled/decision-context.md (if exists)
+
     Context reference:
       specs/{feature}/planning-artifacts/architecture.md
       specs/{feature}/planning-artifacts/brownfield-context.md
@@ -178,6 +234,8 @@ Task(subagent_type: "general-purpose", model: "opus")
 Task(subagent_type: "general-purpose", model: "opus")
   prompt: "You are John, Product Manager. Read your persona at _bmad/bmm/agents/pm.md.
 
+    IMPORTANT: Write ALL output in {document_output_language}.
+
     MODE: CRYSTALLIZE — reconcile Epics with finalized prototype.
 
     Primary input:
@@ -204,6 +262,8 @@ Task(subagent_type: "general-purpose", model: "opus")
 Task(subagent_type: "general-purpose", model: "sonnet")
   prompt: "You are @scope-gate. Read your agent definition at .claude/agents/scope-gate.md.
 
+    IMPORTANT: Write ALL output in {document_output_language}.
+
     Validate cross-artifact consistency of 3 reconciled planning artifacts:
     - specs/{feature}/reconciled/planning-artifacts/prd.md
     - specs/{feature}/reconciled/planning-artifacts/architecture.md
@@ -224,17 +284,23 @@ Task(subagent_type: "general-purpose", model: "sonnet")
 
 Generate Specs 4-file from reconciled planning artifacts.
 
-**Progress**: `"[S3/6] Generating execution specs (requirements + design + tasks)..."`
+**Progress**: `"[S3/7] Generating execution specs (requirements + design + tasks)..."`
 
 ```
 Task(subagent_type: "general-purpose", model: "sonnet")
   prompt: "You are @deliverable-generator. Read and follow your agent definition at .claude/agents/deliverable-generator.md.
+
+    IMPORTANT: Write ALL output in {document_output_language}.
+
     Generate specs in specs-only mode.
     planning_artifacts: specs/{feature}/reconciled/planning-artifacts/
     prototype_analysis_path: specs/{feature}/reconciled/prototype-analysis.md
-    feature_name: {feature}
-    output_base: specs/{feature}/reconciled/
-    mode: specs-only"
+    feature_name: reconciled
+    output_base: specs/{feature}/
+    mode: specs-only
+
+    NOTE: output_base is specs/{feature}/ and feature_name is 'reconciled',
+    so output files will be written to specs/{feature}/reconciled/ directory."
 ```
 
 **Post-S3: Entropy/File Ownership Re-annotation**
@@ -253,31 +319,46 @@ After specs generation:
 
 Verify existing deliverables against prototype. Regenerate where needed.
 
-**Progress**: `"[S4/6] Verifying API spec..."` → `"...Regenerating BDD scenarios..."` → ...
+**Progress**: `"[S4/7] Verifying API spec..."` → `"...Regenerating BDD scenarios..."` → ...
 
-#### Verify Phase
+Invoke deliverable reconciler:
 
-For each verifiable deliverable, compare against prototype:
+```
+Task(subagent_type: "general-purpose", model: "sonnet")
+  prompt: "Reconcile deliverables for specs/{feature}/reconciled/.
+
+    IMPORTANT: Write ALL output in {document_output_language}.
+
+    ## Verify Phase
+    Compare existing deliverables against prototype and reconciled PRD:
+
+    1. api-spec.yaml: Read specs/{feature}/api-spec.yaml. Compare endpoints against
+       specs/{feature}/reconciled/prototype-analysis.md 'API Endpoint Inventory'.
+       If endpoints match (count + paths): copy to reconciled/.
+       If mismatch: regenerate from prototype-analysis + reconciled PRD.
 
-| Deliverable | Verify Against | On Mismatch |
-|-------------|---------------|-------------|
-| api-spec.yaml | MSW handlers (Glob `preview/src/mocks/**/*.ts`) | Regenerate from prototype-analysis API Inventory |
-| schema.dbml | store.ts data model | Regenerate from prototype-analysis Data Model |
-| api-sequences.md | api-spec.yaml endpoints | Regenerate |
+    2. schema.dbml: Read specs/{feature}/schema.dbml. Compare against
+       prototype-analysis.md 'Data Model'. Copy or regenerate.
 
-- On match: copy to `reconciled/`
-- On mismatch: regenerate and write to `reconciled/`
+    3. api-sequences.md: Read specs/{feature}/api-sequences.md. Compare against
+       reconciled api-spec. Copy or regenerate.
 
-#### Regenerate Phase
+    ## Regenerate Phase (always regenerate — source documents changed)
 
-Always regenerate these (source documents have changed):
+    4. bdd-scenarios/: Regenerate from specs/{feature}/reconciled/planning-artifacts/prd.md
+       acceptance criteria. Write to reconciled/bdd-scenarios/.
 
-| Deliverable | Source | Output |
-|-------------|--------|--------|
-| bdd-scenarios/ | reconciled/prd.md ACs | reconciled/bdd-scenarios/ |
-| key-flows.md | prototype User Flows + reconciled/prd.md journeys | reconciled/key-flows.md |
-| traceability-matrix.md | Full reconciled/ artifact set | reconciled/traceability-matrix.md |
-| decision-log.md | Merge: original ADRs + JP decisions + Crystallize decisions (mark superseded ADRs) | reconciled/decision-log.md |
+    5. key-flows.md: Regenerate from prototype-analysis User Flows +
+       reconciled PRD user journeys. Write to reconciled/key-flows.md.
+
+    6. traceability-matrix.md: Rebuild FR → Design → Task → BDD → API from
+       ALL reconciled/ artifacts. Target: 0 gaps. Use canonical task IDs from
+       reconciled/tasks.md (T-01, T-02, etc.). Write to reconciled/traceability-matrix.md.
+
+    7. decision-log.md: Read specs/{feature}/decision-log.md (original ADRs).
+       Merge with JP decisions from reconciled/decision-context.md.
+       Mark superseded ADRs. Write to reconciled/decision-log.md."
+```
 
 **Scope Gate**: Invoke @scope-gate with `stage=deliverables` on reconciled/ deliverables.
 
@@ -285,12 +366,14 @@ Always regenerate these (source documents have changed):
 
 Verify mutual consistency across the entire reconciled/ artifact set.
 
-**Progress**: `"[S5/6] Cross-artifact consistency check..."`
+**Progress**: `"[S5/7] Cross-artifact consistency check..."`
 
 ```
 Task(subagent_type: "general-purpose", model: "sonnet")
   prompt: "Perform cross-artifact consistency verification on specs/{feature}/reconciled/.
 
+    IMPORTANT: Write ALL output in {document_output_language}.
+
     Read ALL files in reconciled/ directory.
     Also read prototype MSW handlers (Glob: specs/{feature}/preview/src/mocks/**/*.ts).
 
@@ -313,7 +396,7 @@ Task(subagent_type: "general-purpose", model: "sonnet")
 
 Present reconciliation results to user (in {communication_language}).
 
-**Progress**: `"[S6/6] Generating summary..."`
+**Progress**: `"[S6/7] Generating summary..."`
 
 **Output format**:
 
@@ -350,10 +433,11 @@ Select: [C] Continue to /parallel | [R] Review reconciled/ | [X] Exit
 
 ## Budget
 
-~85-120 turns across 9 Task invocations. Separate from JP2 iteration budget.
+~85-125 turns across 9 Task invocations. Separate from JP2 iteration budget. S0 runs inline (no Task invocation).
 
 | Step | Model | Est. Turns |
 |------|-------|------------|
+| S0 Decision Context | Conductor (inline) | 0 (no Task) |
 | S1 Prototype Analysis | Sonnet | 5-8 |
 | S2a PRD | Opus | 15-20 |
 | S2b Architecture | Opus | 15-20 |
@@ -367,30 +451,30 @@ Select: [C] Continue to /parallel | [R] Review reconciled/ | [X] Exit
 
 ```
 specs/{feature}/reconciled/
-├── prototype-analysis.md
+├── decision-context.md             # S0 (if decision records exist)
+├── prototype-analysis.md           # S1
 ├── planning-artifacts/
 │   ├── prd.md
 │   ├── architecture.md
 │   ├── epics-and-stories.md
 │   └── brownfield-context.md
-├── entity-dictionary.md
+├── entity-dictionary.md            # S3
 ├── requirements.md
 ├── design.md
 ├── tasks.md
-├── api-spec.yaml
+├── api-spec.yaml                   # S4
 ├── api-sequences.md
 ├── schema.dbml
 ├── bdd-scenarios/
 ├── key-flows.md
 ├── traceability-matrix.md
 ├── decision-log.md
-└── decision-diary.md
+└── decision-diary.md               # (if exists in parent)
 ```
 
 ## Constraints
 
 1. **Prototype is immutable**: preview/ is never modified during Crystallize
 2. **Original artifacts are immutable**: specs/{feature}/ files (outside reconciled/) are never modified
-3. **Sprint-route only**: Requires Sprint artifacts (decision-diary.md, sprint-log.md JP Interactions). Not available for Guided/Direct routes.
-4. **Product Brief excluded**: Product Brief defines problem space — not reconcilable from prototype
-5. **Brownfield not re-scanned**: brownfield-context.md is copied as-is (JP2 iteration changes product design, not existing system landscape)
+3. **Product Brief excluded**: Product Brief defines problem space — not reconcilable from prototype
+4. **Brownfield not re-scanned**: brownfield-context.md is copied as-is (JP2 iteration changes product design, not existing system landscape)

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

@@ -31,7 +31,7 @@ Prerequisites:
 
 ## Procedure
 
-Load config per Language Protocol in bmad-sprint-guide.md.
+Load config per Language Protocol in jdd-sprint-guide.md.
 
 ### Step 1: Interface Contract Creation
 Create shared types/interfaces first (referenced by all Workers):
@@ -62,7 +62,7 @@ Create Worker agents via Claude Code Native Teams:
 1. Create team via TeamCreate
 2. Create each Worker via Task tool (`subagent_type: "worker"`, `model: "sonnet"`)
 3. Create tasks via TaskCreate, assign via TaskUpdate
-4. Instruct each Worker to reference `specs/{feature}/brownfield-context.md`:
+4. Instruct each Worker to reference `{specs_root}/brownfield-context.md` (or `{specs_root}/planning-artifacts/brownfield-context.md` for reconciled/):
    - Follow existing code patterns/conventions (based on configured client-docs MCP)
    - Maintain compatibility when extending existing APIs (based on configured backend-docs MCP)
    - Verify alignment with existing customer journey flows (based on configured svc-map MCP)

package/templates/.claude/commands/preview.md

@@ -26,7 +26,7 @@ Required files (in `specs/{feature}/` directory):
 
 ## Procedure
 
-Load config per Language Protocol in bmad-sprint-guide.md.
+Load config per Language Protocol in jdd-sprint-guide.md.
 
 ### Step 1: Specs Verification
 
@@ -62,12 +62,23 @@ This mode reads existing Specs 4-file and executes Stages 3-10:
 
 ### Step 3: Output Review
 
+Initialize `specs/{feature}/decision-diary.md` if it does not exist (with route metadata: `route: guided` or `route: direct`).
+
 Present generated Sprint Output Package to user for review (in {communication_language}):
 
-- **Approve** → run `/parallel` (parallel implementation)
-- **Feedback (Deliverables)** → re-run Step 2 (Specs preserved)
-- **Feedback (design)** → re-run `/specs` (modify Planning Artifacts)
-- **Abort** → exit
+| Option | Label | Description |
+|--------|-------|-------------|
+| **A** | Approve | Proceed to `/parallel` (parallel implementation) |
+| **S** | Crystallize | Reconcile all documents to match prototype, then proceed to execution |
+| **F1** | Feedback (Deliverables) | Re-run Step 2 (Specs preserved) |
+| **F2** | Feedback (design) | Re-run `/specs` (modify Planning Artifacts) |
+| **X** | Abort | Exit (artifacts preserved) |
+
+**On feedback (F1/F2)**: Record feedback to `specs/{feature}/decision-diary.md` Decisions table (Type, Content, Processing, Result) before re-running.
+
+**On [S] Crystallize**: Record selection in decision-diary.md → invoke `/crystallize {feature}`.
+
+**Iteration limit**: F1/F2 selections combined max 5 times. On exceed, warn (in {communication_language}): "5 review/edit rounds complete. Select [A] Approve, [S] Crystallize, or [X] Abort."
 
 ## Outputs
 - `specs/{feature-name}/api-spec.yaml`

package/templates/.claude/commands/specs.md

@@ -22,7 +22,7 @@ After BMad Phase 3 artifacts are ready and pass Implementation Readiness.
 
 ## Procedure
 
-Load config per Language Protocol in bmad-sprint-guide.md.
+Load config per Language Protocol in jdd-sprint-guide.md.
 
 ### Step 0: Feature Directory + Artifact Discovery
 

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

@@ -33,7 +33,7 @@ Prerequisites:
 
 ## Procedure
 
-Load config per Language Protocol in bmad-sprint-guide.md.
+Load config per Language Protocol in jdd-sprint-guide.md.
 
 ### Phase 0: Smart Launcher (runs in main session)
 
@@ -513,18 +513,36 @@ If Step 0d detected GitHub repo URLs and user selected [1] (download):
 
 2. **For each repo with status: pending**:
    a. Progress message (in {communication_language}): "원격 리포지토리 스냅샷 다운로드 중... ({N}/{total}: {owner_repo})"
-   b. Create temp directory: `mkdir -p /tmp/sprint-{feature}-{name} && chmod 700 /tmp/sprint-{feature}-{name}`
+   b. **Extract branch from URL** (if present):
+      - URL pattern `https://github.com/{owner}/{repo}/tree/{branch}` → extract `{branch}`
+      - URL pattern `https://github.com/{owner}/{repo}` (no `/tree/`) → default `{ref}` = `HEAD`
+      - Store `{ref}` for tarball API call and commit query
+   c. **Repo size pre-check**: `gh api repos/{owner_repo} --jq '.size'` (returns KB)
+      - Size < 1GB (< 1048576 KB): proceed silently
+      - Size >= 1GB: warn (in {communication_language}), then proceed without blocking:
+        ```
+        ⚠ {owner_repo}: approximately {size_mb}MB. Download may take several minutes.
+          For partial access (specific directories only), use: git clone + claude --add-dir
+          Downloading...
+        ```
+   d. **Create cache directory**: `mkdir -p ~/docs-cache/{feature}/{name} && chmod 700 ~/docs-cache/{feature}/{name}`
       - `{name}` = `{owner}-{repo}` (slash replaced with hyphen)
-   c. Download + extract: `gh api repos/{owner_repo}/tarball/HEAD | tar xz -C /tmp/sprint-{feature}-{name} --strip-components=1`
-   d. **On success** → add to `external_resources.external_repos`:
+   e. **Download + extract**: `gh api repos/{owner_repo}/tarball/{ref} | tar xz -C ~/docs-cache/{feature}/{name} --strip-components=1`
+   f. **Record snapshot version**: `gh api repos/{owner_repo}/commits/{ref} --jq '.sha + " " + .commit.committer.date'`
+      - Parse output: `{snapshot_commit}` = first field (SHA), `{snapshot_at}` = second field (ISO 8601)
+      - `{snapshot_branch}` = `{ref}` if explicitly extracted from URL, otherwise `"HEAD"`
+   g. **On success** → add to `external_resources.external_repos`:
       ```yaml
       - name: "{owner}-{repo}"
-        path: "/tmp/sprint-{feature}-{name}/"
+        path: "~/docs-cache/{feature}/{name}/"
         access_method: "tarball-snapshot"
         source_url: "https://github.com/{owner_repo}"
+        snapshot_commit: "{snapshot_commit}"
+        snapshot_branch: "{snapshot_branch}"
+        snapshot_at: "{snapshot_at}"
       ```
       Update github_repos status to `configured`
-   e. **On failure** → classify error and present via AskUserQuestion (in {communication_language}):
+   h. **On failure** → classify error and present via AskUserQuestion (in {communication_language}):
 
       | Error Pattern | Message |
       |---------------|---------|
@@ -538,11 +556,13 @@ If Step 0d detected GitHub repo URLs and user selected [1] (download):
       - [2] 해당 repo 없이 계속
       - [3] --add-dir로 수동 접근
 
-      - [1] selected: retry step 2c (max 1 retry)
+      - [1] selected: retry step 2e (max 1 retry)
       - [2] selected: update github_repos status to `not-configured`, proceed
       - [3] selected: guide user to clone + --add-dir, update github_repos status to `not-configured`
 
-   f. Completion message (in {communication_language}): "다운로드 완료 ({total}/{total}, {elapsed}초)"
+      Note: if only the version query (step 2f) fails, proceed with download success — record `snapshot_commit: "unknown"`.
+
+   i. Completion message (in {communication_language}): "다운로드 완료 ({total}/{total}, {elapsed}초)"
 
 3. **Update github_repos status**: `configured` (all succeeded) / `not-configured` (any failed)
 

package/templates/.claude/commands/summarize-prd.md

@@ -30,7 +30,7 @@ If argument is `help` → **Help Mode**. If last argument is `analyze` → **Ana
 
 ## Procedure
 
-Load config per Language Protocol in bmad-sprint-guide.md.
+Load config per Language Protocol in jdd-sprint-guide.md.
 
 ### Help Mode
 

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

@@ -30,7 +30,7 @@ Prerequisites:
 
 ## Procedure
 
-Load config per Language Protocol in bmad-sprint-guide.md.
+Load config per Language Protocol in jdd-sprint-guide.md.
 
 ### Phase 1: Automated Verification (all tasks)
 Applied to all Entropy levels:

package/templates/.claude/rules/{bmad-mcp-search.md → jdd-mcp-search.md}

@@ -26,12 +26,13 @@ For data sources that cannot be cloned locally (e.g., Figma live design data), c
 
 > **Do not use filesystem MCP servers for local clones.** Claude Code's MCP security restricts filesystem MCP servers to the project root directory. Use `--add-dir` instead.
 
-#### Method 3: GitHub Repo Snapshot (원격 repo, clone 없이)
+#### Method 3: GitHub Repo Snapshot (remote repo, no clone)
 
-brief.md의 `## 참고 소스` 섹션에 GitHub repo URL을 선언하거나, inputs/ 파일에 URL을 포함하면 Sprint 시작 시 자동으로 읽기 전용 스냅샷을 다운로드합니다.
-clone이 아닙니다 — git history 없이 현재 파일만 다운로드하여 temp 디렉토리에 추출합니다.
-Scanner는 추출된 파일에 Glob/Grep/Read로 접근합니다 (--add-dir와 동일한 방식).
-GitHub URL만 지원됩니다. GitLab/Bitbucket은 --add-dir를 사용하세요.
+Declare GitHub repo URLs in the `## Reference Sources` section of brief.md, or include them in inputs/ files. Sprint auto-downloads a read-only snapshot at Phase 0 start.
+Not a clone — downloads current files only via `gh api tarball` (no git history) to a persistent cache directory (`~/docs-cache/{feature}/{name}/`).
+Snapshot provenance (commit SHA, branch, timestamp) is recorded in sprint-input.md for traceability.
+Scanner accesses extracted files via Glob/Grep/Read (same as --add-dir).
+GitHub URLs only. For GitLab/Bitbucket, use --add-dir.
 
 ### External Data Source Roles
 

package/templates/.claude/rules/{bmad-sprint-guide.md → jdd-sprint-guide.md}

@@ -74,6 +74,7 @@ Build planning artifacts step-by-step through conversation with BMad agents.
 BMad 12-step (human-AI dialogue):
   /create-product-brief → /create-prd → /create-architecture → /create-epics
 → /specs → JP1 → /preview → JP2
+→ [S] Crystallize (optional): reconcile all artifacts with finalized prototype → reconciled/
 → /parallel → /validate
 ```
 
@@ -83,6 +84,7 @@ Use when finished PRD + Architecture + Epics already exist.
 
 ```
 /specs → JP1 → /preview → JP2
+→ [S] Crystallize (optional): reconcile all artifacts with finalized prototype → reconciled/
 → /parallel → /validate
 ```
 
@@ -170,9 +172,11 @@ Routes are not fixed. Adapt as needed:
 │       ├── inputs/                     # User originals + sprint-input.md
 │       ├── planning-artifacts/         # BMad artifacts (Sprint/Direct route)
 │       ├── brownfield-context.md       # Frozen snapshot
+│       ├── decision-diary.md          # JP decision summary
 │       ├── requirements.md
 │       ├── design.md
 │       ├── tasks.md
-│       └── preview/                    # React + MSW prototype
+│       ├── preview/                    # React + MSW prototype
+│       └── reconciled/                 # Crystallize output (prototype-reconciled artifacts)
 └── src/                                # Source code
 ```

package/templates/.claude/rules/{bmad-sprint-protocol.md → jdd-sprint-protocol.md}

@@ -203,19 +203,20 @@ Users see the calculated cost alongside the options.
 
 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.
+**Availability**: All routes (Sprint, Guided, Direct). Decision records (decision-diary.md, jp2-review-log.md, sprint-log.md JP Interactions) are optional — they enrich S0 Decision Context when present. Without them, S0 is skipped and S1 runs from code analysis alone.
 
 ### 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)
+  S0: Decision Context Analysis  → reconciled/decision-context.md (JP2 modification intent)
+  S1: Prototype Analysis         → reconciled/prototype-analysis.md (informed by S0)
+  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; ≤3 auto-fix, >3 user choice)
   S6: Summary → [C] /parallel with specs_root=reconciled/
 ```
 

package/templates/_bmad/docs/brownfield-context-format.md

@@ -163,11 +163,20 @@ data_sources:
   local-codebase: ok | not-configured | scan-error
   # External sources — dynamically listed from sprint-input.md external_resources
   # (source names come from external_resources.external_repos or MCP servers)
-  {source_name_1}: ok | timeout | error | empty-result | scan-error
-  {source_name_2}: ok | timeout | error | empty-result | scan-error
+  # For tarball-snapshot sources, include provenance from sprint-input.md:
+  #   snapshot_commit, snapshot_branch, snapshot_at
+  {source_name_1}:
+    status: ok | timeout | error | empty-result | scan-error
+    snapshot_commit: "a1b2c3d"  # (tarball-snapshot only) commit SHA at download time
+    snapshot_branch: "main"     # (tarball-snapshot only) branch or "HEAD"
+    snapshot_at: "2026-02-20T14:30:00Z"  # (tarball-snapshot only) commit timestamp
+  {source_name_2}:
+    status: ok | timeout | error | empty-result | scan-error
   figma: ok | timeout | error | not-configured  # only when external_resources.figma exists
 ```
 
+When writing `data_sources` for tarball-snapshot repos, read `snapshot_commit`, `snapshot_branch`, and `snapshot_at` from `sprint-input.md` `external_resources.external_repos[]` and include them. For `add-dir` repos, omit snapshot fields (not applicable).
+
 ## Source Types
 
 `sources` 배열의 각 항목은 `type`과 `name`으로 구성된다:

package/templates/_bmad/docs/sprint-input-format.md

@@ -79,9 +79,12 @@ external_resources:
     status: configured | not-configured | reference-only
   external_repos:
     - name: "{repo-name}"
-      path: "{accessible local path}"
+      path: "{accessible local path}"  # ~/docs-cache/{feature}/{name}/ for tarball-snapshot
       access_method: "add-dir"  # or "tarball-snapshot"
       source_url: ""  # present when access_method is tarball-snapshot
+      snapshot_commit: ""  # commit SHA at download time (tarball-snapshot only)
+      snapshot_branch: ""  # branch name or "HEAD" (tarball-snapshot only)
+      snapshot_at: ""  # commit timestamp ISO 8601 (tarball-snapshot only)
   policy_docs:
     - "matching-policy.md"
   scan_notes: "매칭 엔진과 예약 플로우 중심으로 탐색"
@@ -124,9 +127,12 @@ flags:
 | `external_resources.github_repos.status` | (Y if github_repos exists) | `configured` (downloaded) / `not-configured` (download failed) / `reference-only` (URL only) |
 | `external_resources.external_repos` | N | External repo paths detected via `--add-dir` or tarball snapshot |
 | `external_resources.external_repos[].name` | (Y if external_repos exists) | Repo identifier (derived from directory name) |
-| `external_resources.external_repos[].path` | (Y if external_repos exists) | Accessible local path to the repo |
+| `external_resources.external_repos[].path` | (Y if external_repos exists) | Accessible local path to the repo (`~/docs-cache/{feature}/{name}/` for tarball-snapshot) |
 | `external_resources.external_repos[].access_method` | (Y if external_repos exists) | How the path was provided (`add-dir` / `tarball-snapshot`) |
 | `external_resources.external_repos[].source_url` | N | Original URL (for tarball re-download; present when access_method is `tarball-snapshot`) |
+| `external_resources.external_repos[].snapshot_commit` | N | Commit SHA at download time (tarball-snapshot only; `"unknown"` if query failed) |
+| `external_resources.external_repos[].snapshot_branch` | N | Branch name extracted from URL, or `"HEAD"` if default (tarball-snapshot only) |
+| `external_resources.external_repos[].snapshot_at` | N | Commit timestamp ISO 8601 (tarball-snapshot only) |
 | `external_resources.github_repos[].notes` | N | 탐색 힌트 (brief.md 참고 소스 섹션에서 전달). Scanner가 참조 |
 | `external_resources.policy_docs` | N | Scanner 우선 탐색 대상 문서명 목록 (brief.md 참고 소스 섹션에서 전달) |
 | `external_resources.scan_notes` | N | 전체 탐색 자유 형식 메모 (brief.md 참고 소스 섹션에서 전달) |