@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/workflows/execute-plan.md

@@ -9,6 +9,16 @@ Read config.json for planning behavior settings.
 @~/.claude/sdd/references/git-integration.md
 </required_reading>
 
+<atomic_close_out_invariant>
+For each executed plan, the only complete close-out order is:
+`production-code commit(s) -> SUMMARY commit -> STATE/ROADMAP update`.
+
+The only legal half-state is mid-production-commits while the executor is still
+actively working. Once production commits for a plan exist, returning without a
+committed SUMMARY.md is an illegal partial-plan state. The next execute-phase
+resume must detect that condition before dispatching another executor.
+</atomic_close_out_invariant>
+
 <available_agent_types>
 Valid SDD subagent types (use exact names — do not fall back to 'general-purpose'):
 - sdd-executor — Executes plan tasks, commits, creates SUMMARY.md
@@ -20,7 +30,7 @@ Valid SDD subagent types (use exact names — do not fall back to 'general-purpo
 Load execution context (paths only to minimize orchestrator context):
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init execute-phase "${PHASE}")
+INIT=$(sdd-sdk query init.execute-phase "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -40,7 +50,7 @@ Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix
 
 ```bash
 PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+')
-# config settings can be fetched via sdd-tools config-get if needed
+# config settings can be fetched via sdd-sdk query config-get if needed
 ```
 
 <if mode="yolo">
@@ -61,10 +71,19 @@ PLAN_START_EPOCH=$(date +%s)
 
 <step name="parse_segments">
 ```bash
+# Count tasks — match <task tag at any indentation level
+TASK_COUNT=$(grep -cE '^\s*<task[[:space:]>]' .planning/phases/XX-name/{phase}-{plan}-PLAN.md 2>/dev/null || echo "0")
+INLINE_THRESHOLD=$(sdd-sdk query config-get workflow.inline_plan_threshold 2>/dev/null || echo "2")
 grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 ```
 
-**Routing by checkpoint type:**
+**Primary routing: task count threshold (#1979)**
+
+If `INLINE_THRESHOLD > 0` AND `TASK_COUNT <= INLINE_THRESHOLD`: Use Pattern C (inline) regardless of checkpoint type. Small plans execute faster inline — avoids ~14K token subagent spawn overhead and preserves prompt cache. Configure threshold via `workflow.inline_plan_threshold` (default: 2, set to `0` to always spawn subagents).
+
+Otherwise: Apply checkpoint-based routing below.
+
+**Checkpoint-based routing (plans with > threshold tasks):**
 
 | Checkpoints | Pattern | Execution |
 |-------------|---------|-----------|
@@ -72,7 +91,7 @@ grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 | Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN |
 | Decision | C (main) | Execute entirely in main context |
 
-**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn Task(subagent_type="sdd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, hard-reset the branch with `git reset --hard {EXPECTED_BASE}` before starting work (safe — runs before any agent work), then verify with `[ "$(git rev-parse HEAD)" != "{EXPECTED_BASE}" ] && exit 1`. This corrects a known issue where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD (affects all platforms).
+**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn Agent(subagent_type="sdd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to: (1) FIRST assert `git symbolic-ref HEAD` resolves to a per-agent branch (NOT a protected ref like `main`/`master`/`develop`/`trunk`/`release/*`) and HALT with a blocker if not — never self-recover via `git update-ref refs/heads/<protected>` (#2924); (2) only after that assertion passes, run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, hard-reset the branch with `git reset --hard {EXPECTED_BASE}` before starting work, then verify with `[ "$(git rev-parse HEAD)" != "{EXPECTED_BASE}" ] && exit 1`. The HEAD assertion (Step 1) MUST run before any reset/checkout. This corrects a known issue where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD (affects all platforms — #2015) and prevents the destructive HEAD-on-master self-recovery path (#2924).
 
 **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
 
@@ -107,12 +126,18 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
 2. Per segment:
    - Subagent route: spawn sdd-executor for assigned tasks only. Prompt: task range, plan path, read full plan for context, execute assigned tasks, track deviations, NO SUMMARY/commit. Track via agent protocol.
    - Main route: execute tasks using standard flow (step name="execute")
-3. After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → commit → self-check:
+3. **Critical ordering — write and commit SUMMARY.md as one atomic block.** Do NOT
+   emit narrative output between the Write tool call and the commit tool call.
+   Truncation at this boundary is a known failure mode (see #2070 rescue logic in
+   execute-phase.md step 5.5).
+
+   After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → self-check:
    - Verify key-files.created exist on disk with `[ -f ]`
    - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
    - Re-run ALL `<acceptance_criteria>` from every task — if any fail, fix before finalizing SUMMARY
    - Re-run the plan-level `<verification>` commands — log results in SUMMARY
    - Append `## Self-Check: PASSED` or `## Self-Check: FAILED` to SUMMARY
+   Then commit (no narrative between Write and commit).
 
    **Known Claude Code bug (classifyHandoffIfNeeded):** If any segment agent reports "failed" with `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Run spot-checks; if they pass, treat as successful.
 
@@ -132,7 +157,7 @@ This IS the execution instructions. Follow exactly. If plan references CONTEXT.m
 
 <step name="previous_phase_check">
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phases list --type summaries --raw
+sdd-sdk query phases.list --type summaries --raw
 # Extract the second-to-last summary from the JSON result
 ```
 
@@ -230,7 +255,12 @@ See `~/.claude/sdd/references/tdd.md` for structure.
 Your commits may trigger pre-commit hooks. Auto-fix hooks handle themselves transparently — files get fixed and re-staged automatically.
 
 **If running as a parallel executor agent (spawned by execute-phase):**
-Use `--no-verify` on all commits. Pre-commit hooks cause build lock contention when multiple agents commit simultaneously (e.g., cargo lock fights in Rust projects). The orchestrator validates once after all agents complete.
+Run commits normally — let pre-commit hooks run. Do NOT use `--no-verify` by default
+(#2924). Hooks should run so issues surface at the introducing commit, and silent
+bypass violates project CLAUDE.md guidance. If a project explicitly opts out via
+`workflow.worktree_skip_hooks=true`, the orchestrator will surface that flag in the
+prompt; absent that signal, hooks run normally. If a hook fails, follow the
+sequential-mode handling below.
 
 **If running as the sole executor (sequential mode):**
 If a commit is BLOCKED by a hook:
@@ -246,13 +276,9 @@ If a commit is BLOCKED by a hook:
 <task_commit>
 ## Task Commit Protocol
 
-Follow the task commit protocol from the sdd-executor agent definition (single source of truth):
-- Stage files individually (NEVER `git add .` or `git add -A`)
-- Format: `{type}({phase}-{plan}): {concise description}` with bullet points for key changes
-- Types: feat, fix, test, refactor, perf, docs, style, chore
-- Sub-repos: use `commit-to-subrepo` when `sub_repos` is configured
-- Record commit hash for SUMMARY tracking
-- Check for untracked generated files after each commit
+Canonical per-task commit rules live in **`agents/sdd-executor.md`** (`<task_commit_protocol>`). Follow that section for staging, `{type}({phase}-{plan})` messages, `commit-to-subrepo` when `sub_repos` is set, post-commit checks, and untracked-file handling — do not duplicate or paraphrase the full protocol here (single source of truth).
+
+**Orchestrator note:** After each task, the spawned executor reports commit hashes; this workflow does not re-specify commit semantics beyond pointing at the executor.
 
 </task_commit>
 
@@ -285,7 +311,7 @@ If verification fails:
 
 **Check if node repair is enabled** (default: on):
 ```bash
-NODE_REPAIR=$(node "./.claude/sdd/bin/sdd-tools.cjs" config-get workflow.node_repair 2>/dev/null || echo "true")
+NODE_REPAIR=$(sdd-sdk query config-get workflow.node_repair 2>/dev/null || echo "true")
 ```
 
 If `NODE_REPAIR` is `true`: invoke `@./.claude/sdd/workflows/node-repair.md` with:
@@ -326,6 +352,11 @@ If user_setup exists: create `{phase}-USER-SETUP.md` using template `~/.claude/s
 </step>
 
 <step name="create_summary">
+**Critical ordering — write and commit SUMMARY.md as one atomic block.** Do NOT
+emit narrative output between the Write tool call and the commit tool call.
+Truncation at this boundary is a known failure mode (see #2070 rescue logic in
+execute-phase.md step 5.5).
+
 Create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`. Use `~/.claude/sdd/templates/summary.md`.
 
 **Frontmatter:** phase, plan, subsystem, tags | requires/provides/affects | tech-stack.added/patterns | key-files.created/modified | key-decisions | requirements-completed (**MUST** copy `requirements` array from PLAN.md frontmatter verbatim) | duration ($DURATION), completed ($PLAN_END_TIME date).
@@ -344,7 +375,7 @@ Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready f
 handles STATE.md/ROADMAP.md updates centrally after merging worktrees to avoid
 merge conflicts).
 
-Update STATE.md using sdd-tools:
+Update STATE.md using sdd-sdk query (or legacy sdd-tools) state mutations:
 
 ```bash
 # Auto-detect parallel mode: .git is a file in worktrees, a directory in main repo
@@ -353,13 +384,13 @@ IS_WORKTREE=$([ -f .git ] && echo "true" || echo "false")
 # Skip in parallel mode — orchestrator handles STATE.md centrally
 if [ "$IS_WORKTREE" != "true" ]; then
   # Advance plan counter (handles last-plan edge case)
-  node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state advance-plan
+  sdd-sdk query state.advance-plan
 
   # Recalculate progress bar from disk state
-  node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state update-progress
+  sdd-sdk query state.update-progress
 
   # Record execution metrics
-  node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state record-metric \
+  sdd-sdk query state.record-metric \
     --phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
     --tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
 fi
@@ -372,19 +403,19 @@ From SUMMARY: Extract decisions and add to STATE.md:
 ```bash
 # Add each decision from SUMMARY key-decisions
 # Prefer file inputs for shell-safe text (preserves `$`, `*`, etc. exactly)
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state add-decision \
+sdd-sdk query state.add-decision \
   --phase "${PHASE}" --summary-file "${DECISION_TEXT_FILE}" --rationale-file "${RATIONALE_FILE}"
 
 # Add blockers if any found
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state add-blocker --text-file "${BLOCKER_TEXT_FILE}"
+sdd-sdk query state.add-blocker --text-file "${BLOCKER_TEXT_FILE}"
 ```
 </step>
 
 <step name="update_session_continuity">
-Update session info using sdd-tools:
+Update session info using sdd-sdk query (or legacy sdd-tools):
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state record-session \
+sdd-sdk query state.record-session \
   --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md" \
   --resume-file "None"
 ```
@@ -397,16 +428,20 @@ If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interacti
 </step>
 
 <step name="update_roadmap">
-**Skip this step if running in parallel mode** (the orchestrator handles ROADMAP.md
-updates centrally after merging worktrees).
+Run this step only when NOT executing inside a git worktree (i.e.
+`use_worktrees: false`, the bug #2661 reproducer). In worktree mode each
+worktree has its own ROADMAP.md, so per-plan writes here would diverge
+across siblings; the orchestrator owns the post-merge sync centrally
+(see execute-phase.md §5.7, single-writer contract from #1486 / dcb50396).
 
 ```bash
-# Auto-detect parallel mode: .git is a file in worktrees, a directory in main repo
+# Auto-detect worktree mode: .git is a file in worktrees, a directory in main repo.
+# This mirrors the use_worktrees config flag for the executing handler.
 IS_WORKTREE=$([ -f .git ] && echo "true" || echo "false")
 
-# Skip in parallel mode — orchestrator handles ROADMAP.md centrally
 if [ "$IS_WORKTREE" != "true" ]; then
-  node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap update-plan-progress "${PHASE}"
+  # use_worktrees: false → this handler is the sole post-plan sync point (#2661)
+  sdd-sdk query roadmap.update-plan-progress "${PHASE}"
 fi
 ```
 Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct count and status (`In Progress` or `Complete` with date).
@@ -416,13 +451,18 @@ Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct co
 Mark completed requirements from the PLAN.md frontmatter `requirements:` field:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" requirements mark-complete ${REQ_IDS}
+sdd-sdk query requirements.mark-complete ${REQ_IDS}
 ```
 
 Extract requirement IDs from the plan's frontmatter (e.g., `requirements: [AUTH-01, AUTH-02]`). If no requirements field, skip.
 </step>
 
 <step name="git_commit_metadata">
+**Critical ordering — write and commit SUMMARY.md as one atomic block.** Do NOT
+emit narrative output between the Write tool call and the commit tool call.
+Truncation at this boundary is a known failure mode (see #2070 rescue logic in
+execute-phase.md step 5.5).
+
 Task code already committed per-task. Commit plan metadata:
 
 ```bash
@@ -431,9 +471,9 @@ IS_WORKTREE=$([ -f .git ] && echo "true" || echo "false")
 
 # In parallel mode: exclude STATE.md and ROADMAP.md (orchestrator commits these)
 if [ "$IS_WORKTREE" = "true" ]; then
-  node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/REQUIREMENTS.md
+  sdd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/REQUIREMENTS.md
 else
-  node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+  sdd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
 fi
 ```
 </step>
@@ -449,7 +489,7 @@ git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null || true
 Update only structural changes: new src/ dir → STRUCTURE.md | deps → STACK.md | file pattern → CONVENTIONS.md | API client → INTEGRATIONS.md | config → STACK.md | renamed → update paths. Skip code-only/bugfix/content changes.
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
+sdd-sdk query commit "" --files .planning/codebase/*.md --amend
 ```
 </step>
 
@@ -463,9 +503,9 @@ If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + e
 
 | Condition | Route | Action |
 |-----------|-------|--------|
-| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/sdd-execute-phase {phase}` + `/sdd-verify-work`. STOP here. |
-| summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/sdd-plan-phase {Z+1}` + `/sdd-verify-work {Z}` + `/sdd-discuss-phase {Z+1}` |
-| summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/sdd-complete-milestone` + `/sdd-verify-work` + `/sdd-add-phase` |
+| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/sdd:execute-phase {phase}` + `/sdd:verify-work`. STOP here. |
+| summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/sdd:plan-phase {Z+1}` + `/sdd:verify-work {Z}` + `/sdd:discuss-phase {Z+1}` |
+| summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/sdd:complete-milestone` + `/sdd:verify-work` + `/sdd-add-phase` |
 
 All routes: `/clear` first for fresh context.
 </step>

package/sdd/workflows/explore.md

@@ -60,12 +60,14 @@ This would take ~30 seconds and might surface useful context.
 
 If yes, spawn a research agent:
 ```
-Task(
+Agent(
   prompt="Quick research: {specific_question}. Return 3-5 key findings, no more than 200 words.",
   subagent_type="sdd-phase-researcher"
 )
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
 Share findings and continue the conversation.
 
 If the topic doesn't warrant research, skip this step entirely. **Don't force it.**
@@ -82,6 +84,8 @@ When the conversation reaches natural conclusions or the developer signals readi
 | Research question | `.planning/research/questions.md` (append) | Open questions that need deeper investigation |
 | Requirement | `REQUIREMENTS.md` (append) | Clear requirements that emerged from discussion |
 | New phase | `ROADMAP.md` (append) | Scope large enough to warrant its own phase |
+| Spike | `/sdd:spike` (invoke) | Feasibility uncertainty surfaced — "will this API work?", "can we do X?" |
+| Sketch | `/sdd:sketch` (invoke) | Design direction unclear — "what should this look like?", "how should this feel?" |
 
 Present suggestions:
 ```
@@ -111,7 +115,7 @@ For each selected output, write the file:
 
 Commit if `commit_docs` is enabled:
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: capture exploration — {topic_slug}" --files {file_list}
+sdd-sdk query commit "docs: capture exploration — {topic_slug}" --files {file_list}
 ```
 
 ## Step 6: Close
@@ -123,7 +127,7 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: capture exploration —
 **Outputs:** {count} artifact(s) created
 {list of created files}
 
-Continue exploring with `/sdd-explore` or start working with `/sdd-next`.
+Continue exploring with `/sdd:explore` or start working with `/sdd:progress --next`.
 ```
 
 </process>

package/sdd/workflows/extract-learnings.md

@@ -0,0 +1,242 @@
+<purpose>
+Extract decisions, lessons learned, patterns discovered, and surprises encountered from completed phase artifacts into a structured LEARNINGS.md file. Captures institutional knowledge that would otherwise be lost between phases.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<objective>
+Analyze completed phase artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md, UAT.md, STATE.md) and extract structured learnings into 4 categories: decisions, lessons, patterns, and surprises. Each extracted item includes source attribution. The output is a LEARNINGS.md file with YAML frontmatter containing metadata about the extraction.
+</objective>
+
+<process>
+
+<step name="initialize">
+Parse arguments and load project state:
+
+```bash
+INIT=$(sdd-sdk query init.phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`.
+
+If phase not found, exit with error: "Phase {PHASE_ARG} not found."
+</step>
+
+<step name="collect_artifacts">
+Read the phase artifacts. PLAN.md and SUMMARY.md are required; VERIFICATION.md, UAT.md, and STATE.md are optional.
+
+**Required artifacts:**
+- `${PHASE_DIR}/*-PLAN.md` — all plan files for the phase
+- `${PHASE_DIR}/*-SUMMARY.md` — all summary files for the phase
+
+If PLAN.md or SUMMARY.md files are not found or missing, exit with error: "Required artifacts missing. PLAN.md and SUMMARY.md are required for learning extraction."
+
+**Optional artifacts (read if available, skip if not found):**
+- `${PHASE_DIR}/*-VERIFICATION.md` — verification results
+- `${PHASE_DIR}/*-UAT.md` — user acceptance test results
+- `.planning/STATE.md` — project state with decisions and blockers
+
+Track which optional artifacts are missing for the `missing_artifacts` frontmatter field.
+</step>
+
+<step name="extract-learnings">
+Analyze all collected artifacts and extract learnings into 4 categories:
+
+### 1. Decisions
+Technical and architectural decisions made during the phase. Look for:
+- Explicit decisions documented in PLAN.md or SUMMARY.md
+- Technology choices and their rationale
+- Trade-offs that were evaluated
+- Design decisions recorded in STATE.md
+
+Each decision entry must include:
+- **What** was decided
+- **Why** it was decided (rationale)
+- **Source:** attribution to the artifact where the decision was found (e.g., "Source: 03-01-PLAN.md")
+
+### 2. Lessons
+Things learned during execution that were not known beforehand. Look for:
+- Unexpected complexity in SUMMARY.md
+- Issues discovered during verification in VERIFICATION.md
+- Failed approaches documented in SUMMARY.md
+- UAT feedback that revealed gaps
+
+Each lesson entry must include:
+- **What** was learned
+- **Context** for the lesson
+- **Source:** attribution to the originating artifact
+
+### 3. Patterns
+Reusable patterns, approaches, or techniques discovered. Look for:
+- Successful implementation patterns in SUMMARY.md
+- Testing patterns from VERIFICATION.md or UAT.md
+- Workflow patterns that worked well
+- Code organization patterns from PLAN.md
+
+Each pattern entry must include:
+- **Pattern** name/description
+- **When to use** it
+- **Source:** attribution to the originating artifact
+
+### 4. Surprises
+Unexpected findings, behaviors, or outcomes. Look for:
+- Things that took longer or shorter than estimated
+- Unexpected dependencies or interactions
+- Edge cases not anticipated in planning
+- Performance or behavior that differed from expectations
+
+Each surprise entry must include:
+- **What** was surprising
+- **Impact** of the surprise
+- **Source:** attribution to the originating artifact
+</step>
+
+<step name="capture_thought_integration">
+**What this step is:** `capture_thought` is an **optional convention**, not a bundled SDD tool. SDD does not ship one and does not require one. The step is a hook for users who run a memory / knowledge-base MCP server (for example ExoCortex-style servers, `claude-mem`, or `mem0`-style servers) that exposes a tool with this exact name. If any MCP server in the current session provides a `capture_thought` tool with the signature below, each extracted learning is routed through it with metadata. If no such tool is present, the step is a silent no-op — `LEARNINGS.md` is always the primary output.
+
+**Detection:** Check whether a tool named `capture_thought` is available in the current session. Do not assume any specific MCP server is connected.
+
+**If available**, call once per extracted learning:
+
+```
+capture_thought({
+  category: "decision" | "lesson" | "pattern" | "surprise",
+  phase: PHASE_NUMBER,
+  content: LEARNING_TEXT,
+  source: ARTIFACT_NAME
+})
+```
+
+**If not available** (no MCP server in the session exposes this tool, or the runtime does not support it), skip the step silently and continue. The workflow must not fail or warn — this is expected behavior for users who do not run a knowledge-base MCP.
+</step>
+
+<step name="write_learnings">
+Write the LEARNINGS.md file to the phase directory. If a previous LEARNINGS.md exists, overwrite it (replace the file entirely).
+
+Output path: `${PHASE_DIR}/${PADDED_PHASE}-LEARNINGS.md`
+
+The file must have YAML frontmatter with these fields:
+```yaml
+---
+phase: {PHASE_NUMBER}
+phase_name: "{PHASE_NAME}"
+project: "{PROJECT_NAME}"
+generated: "{ISO_DATE}"
+counts:
+  decisions: {N}
+  lessons: {N}
+  patterns: {N}
+  surprises: {N}
+missing_artifacts:
+  - "{ARTIFACT_NAME}"
+---
+```
+
+Individual items may carry an optional `graduated:` annotation (added by `graduation.md` when a cluster is promoted):
+```markdown
+**Graduated:** {target-file}:{ISO_DATE}
+```
+This annotation is appended after the item's existing fields and prevents the item from being re-surfaced in future graduation scans. Do not add this field during extraction — it is written only by the graduation workflow.
+
+The body follows this structure:
+```markdown
+# Phase {PHASE_NUMBER} Learnings: {PHASE_NAME}
+
+## Decisions
+
+### {Decision Title}
+{What was decided}
+
+**Rationale:** {Why}
+**Source:** {artifact file}
+
+---
+
+## Lessons
+
+### {Lesson Title}
+{What was learned}
+
+**Context:** {context}
+**Source:** {artifact file}
+
+---
+
+## Patterns
+
+### {Pattern Name}
+{Description}
+
+**When to use:** {applicability}
+**Source:** {artifact file}
+
+---
+
+## Surprises
+
+### {Surprise Title}
+{What was surprising}
+
+**Impact:** {impact description}
+**Source:** {artifact file}
+```
+</step>
+
+<step name="update_state">
+Update STATE.md to reflect the learning extraction:
+
+```bash
+sdd-sdk query state.update "Last Activity" "$(date +%Y-%m-%d)"
+```
+</step>
+
+<step name="report">
+```
+---------------------------------------------------------------
+
+## Learnings Extracted: Phase {X} — {Name}
+
+Decisions:  {N}
+Lessons:    {N}
+Patterns:   {N}
+Surprises:  {N}
+Total:      {N}
+
+Output: {PHASE_DIR}/{PADDED_PHASE}-LEARNINGS.md
+
+Missing artifacts: {list or "none"}
+
+Next steps:
+- Review extracted learnings for accuracy
+- /sdd:progress — see overall project state
+- /sdd:execute-phase {next} — continue to next phase
+
+---------------------------------------------------------------
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Phase artifacts located and read successfully
+- [ ] All 4 categories extracted: decisions, lessons, patterns, surprises
+- [ ] Each extracted item has source attribution
+- [ ] LEARNINGS.md written with correct YAML frontmatter
+- [ ] Missing optional artifacts tracked in frontmatter
+- [ ] capture_thought integration attempted if tool available
+- [ ] STATE.md updated with extraction activity
+- [ ] User receives summary report
+</success_criteria>
+
+<critical_rules>
+- PLAN.md and SUMMARY.md are required — exit with clear error if missing
+- VERIFICATION.md, UAT.md, and STATE.md are optional — extract from them if present, skip gracefully if not found
+- Every extracted learning must have source attribution back to the originating artifact
+- Running extract-learnings twice on the same phase must overwrite (replace) the previous LEARNINGS.md, not append
+- Do not fabricate learnings — only extract what is explicitly documented in artifacts
+- If capture_thought is unavailable, the workflow must not fail — graceful degradation to file-only output
+- LEARNINGS.md frontmatter must include counts for all 4 categories and list any missing_artifacts
+</critical_rules>

package/sdd/workflows/fast.md

@@ -5,7 +5,7 @@ no research, no plan checking. Just: understand → do → commit → log.
 For tasks like: fix a typo, update a config value, add a missing import, rename a
 variable, commit uncommitted work, add a .gitignore entry, bump a version number.
 
-Use /sdd-quick for anything that needs multi-step planning or research.
+Use /sdd:quick for anything that needs multi-step planning or research.
 </purpose>
 
 <process>
@@ -34,8 +34,8 @@ If the task seems non-trivial (multi-file refactor, new feature, needs research)
 say:
 
 ```
-This looks like it needs planning. Use /sdd-quick instead:
-  /sdd-quick "{task description}"
+This looks like it needs planning. Use /sdd:quick instead:
+  /sdd:quick "{task description}"
 ```
 
 And stop.
@@ -51,12 +51,13 @@ Do the work directly:
 **No PLAN.md.** Just do it.
 </step>
 
-<step name="commit">
-Commit the change atomically:
+<step name="halt_for_manual_commit">
+**FORK NOTE — this fork disables auto-commit.** Do NOT run `git add` or `git commit`. Stop here and tell the user:
 
-```bash
-git add -A
-git commit -m "fix: {concise description of what changed}"
+```
+✅ Changes applied. Review the diff and commit manually:
+   git add -A
+   git commit -m "fix: <concise description>"
 ```
 
 Use conventional commit format: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:` as appropriate.
@@ -80,8 +81,8 @@ Report completion:
 
 ```
 ✅ Done: {what was changed}
-   Commit: {short hash}
    Files: {list of changed files}
+   Manual git: review diff and commit when ready (this fork does not auto-commit).
 ```
 
 No next-step suggestions. No workflow routing. Just done.
@@ -93,13 +94,13 @@ No next-step suggestions. No workflow routing. Just done.
 - NEVER spawn a Task/subagent — this runs inline
 - NEVER create PLAN.md or SUMMARY.md files
 - NEVER run research or plan-checking
-- If the task takes more than 3 file edits, STOP and redirect to /sdd-quick
-- If you're unsure how to implement it, STOP and redirect to /sdd-quick
+- If the task takes more than 3 file edits, STOP and redirect to /sdd:quick
+- If you're unsure how to implement it, STOP and redirect to /sdd:quick
 </guardrails>
 
 <success_criteria>
 - [ ] Task completed in current context (no subagents)
-- [ ] Atomic git commit with conventional message
+- [ ] Changes staged for user to commit manually (fork policy — no auto-commit)
 - [ ] STATE.md updated if it exists
 - [ ] Total operation under 2 minutes wall time
 </success_criteria>