@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/workflows/code-review-fix.md

@@ -18,7 +18,7 @@ Parse arguments and load project state:
 
 ```bash
 PHASE_ARG="${1}"
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op "${PHASE_ARG}")
+INIT=$(sdd-sdk query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -36,7 +36,7 @@ fi
 **Phase validation (before config gate):**
 If `phase_found` is false, report error and exit:
 ```
-Error: Phase ${PHASE_ARG} not found. Run /sdd-status to see available phases.
+Error: Phase ${PHASE_ARG} not found. Run /sdd:progress to see available phases.
 ```
 
 This runs BEFORE config gate check so user errors are surfaced immediately regardless of config state.
@@ -74,7 +74,7 @@ FIX_REPORT_PATH="${PHASE_DIR}/${PADDED_PHASE}-REVIEW-FIX.md"
 Check if code review is enabled via config:
 
 ```bash
-CODE_REVIEW_ENABLED=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.code_review 2>/dev/null || echo "true")
+CODE_REVIEW_ENABLED=$(sdd-sdk query config-get workflow.code_review 2>/dev/null || echo "true")
 ```
 
 If CODE_REVIEW_ENABLED is "false":
@@ -93,7 +93,7 @@ Verify that REVIEW.md exists:
 
 ```bash
 if [ ! -f "${REVIEW_PATH}" ]; then
-  echo "Error: No REVIEW.md found for Phase ${PHASE_ARG}. Run /sdd-code-review ${PHASE_ARG} first."
+  echo "Error: No REVIEW.md found for Phase ${PHASE_ARG}. Run /sdd:code-review ${PHASE_ARG} first."
   exit 1
 fi
 ```
@@ -186,10 +186,10 @@ echo "Applying fixes from ${REVIEW_PATH}..."
 echo "Fix scope: ${FIX_SCOPE}"
 ```
 
-Use Task() to spawn agent:
+Use Agent() to spawn agent:
 
-```
-Task(subagent_type="sdd-code-fixer", prompt="
+```text
+Agent(subagent_type="sdd-code-fixer", prompt="
 <files_to_read>
 ${REVIEW_PATH}
 </files_to_read>
@@ -207,9 +207,11 @@ Read REVIEW.md findings, apply fixes, commit each atomically, write REVIEW-FIX.m
 ")
 ```
 
+> **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.
+
 **Agent failure handling:**
 
-If Task() fails:
+If Agent() fails:
 ```
 Error: Code fix agent failed: ${error_message}
 ```
@@ -221,7 +223,7 @@ Check if FIX_REPORT_PATH exists:
 Either way:
 ```
 Some fix commits may already exist in git history — check git log for fix(${PADDED_PHASE}) commits.
-You can retry with /sdd-code-review-fix ${PHASE_ARG}.
+You can retry with /sdd:code-review ${PHASE_ARG} --fix.
 ```
 
 Exit workflow (skip auto loop).
@@ -270,7 +272,7 @@ if [ "$AUTO_MODE" = "true" ]; then
     
     # Spawn sdd-code-reviewer agent to re-review
     # (This overwrites REVIEW_PATH with latest review state)
-    Task(subagent_type="sdd-code-reviewer", prompt="
+    Agent(subagent_type="sdd-code-reviewer", prompt="
 <config>
 depth: ${REVIEW_DEPTH}
 phase_dir: ${PHASE_DIR}
@@ -281,6 +283,7 @@ ${FILES_CONFIG}
 Re-review the phase at ${REVIEW_DEPTH} depth. Write findings to ${REVIEW_PATH}.
 Do NOT commit the output — the orchestrator handles that.
 ")
+    # 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 before proceeding.
     
     # Check new REVIEW.md status
     NEW_STATUS=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
@@ -303,7 +306,7 @@ Do NOT commit the output — the orchestrator handles that.
     # Still has issues — spawn fixer again
     echo "Issues remain. Applying fixes for iteration ${ITERATION}..."
     
-    Task(subagent_type="sdd-code-fixer", prompt="
+    Agent(subagent_type="sdd-code-fixer", prompt="
 <files_to_read>
 ${REVIEW_PATH}
 </files_to_read>
@@ -319,6 +322,7 @@ iteration: ${ITERATION}
 
 Read REVIEW.md findings, apply fixes, commit each atomically, write REVIEW-FIX.md (overwrite previous). Do NOT commit REVIEW-FIX.md.
 ")
+    # 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 before proceeding.
     
     # Check if fixer succeeded
     if [ ! -f "${FIX_REPORT_PATH}" ]; then
@@ -359,7 +363,7 @@ if [ -f "${FIX_REPORT_PATH}" ]; then
     echo "REVIEW-FIX.md created at ${FIX_REPORT_PATH}"
     
     if [ "$COMMIT_DOCS" = "true" ]; then
-      node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit \
+      sdd-sdk query commit \
         "docs(${PADDED_PHASE}): add code review fix report" \
         --files "${FIX_REPORT_PATH}"
     fi
@@ -394,7 +398,7 @@ if [ ! -f "${FIX_REPORT_PATH}" ]; then
   echo "The fixer agent may have failed before completing."
   echo "Check git log for any fix(${PADDED_PHASE}) commits."
   echo ""
-  echo "Retry: /sdd-code-review-fix ${PHASE_ARG}"
+  echo "Retry: /sdd:code-review ${PHASE_ARG} --fix"
   echo ""
   echo "═══════════════════════════════════════════════════════════════"
   exit 1
@@ -451,7 +455,7 @@ if [ "$FIX_STATUS" = "all_fixed" ]; then
   echo "Full report: ${FIX_REPORT_PATH}"
   echo ""
   echo "Next step:"
-  echo "  /sdd-verify-work  — Verify phase completion"
+  echo "  /sdd:verify-work  — Verify phase completion"
   echo ""
 fi
 ```
@@ -465,8 +469,8 @@ if [ "$FIX_STATUS" = "partial" ] || [ "$FIX_STATUS" = "none_fixed" ]; then
   echo ""
   echo "Next steps:"
   echo "  cat ${FIX_REPORT_PATH}                     — View fix report"
-  echo "  /sdd-code-review ${PHASE_NUMBER}           — Re-review code"
-  echo "  /sdd-verify-work                           — Verify phase completion"
+  echo "  /sdd:code-review ${PHASE_NUMBER}           — Re-review code"
+  echo "  /sdd:verify-work                           — Verify phase completion"
   echo ""
 fi
 ```

package/sdd/workflows/code-review.md

@@ -17,7 +17,7 @@ Parse arguments and load project state:
 
 ```bash
 PHASE_ARG="${1}"
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op "${PHASE_ARG}")
+INIT=$(sdd-sdk query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -35,7 +35,7 @@ fi
 **Phase validation (before config gate):**
 If `phase_found` is false, report error and exit:
 ```
-Error: Phase ${PHASE_ARG} not found. Run /sdd-status to see available phases.
+Error: Phase ${PHASE_ARG} not found. Run /sdd:progress to see available phases.
 ```
 
 This runs BEFORE config gate check so user errors are surfaced immediately regardless of config state.
@@ -74,7 +74,7 @@ fi
 Check if code review is enabled via config:
 
 ```bash
-CODE_REVIEW_ENABLED=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.code_review 2>/dev/null || echo "true")
+CODE_REVIEW_ENABLED=$(sdd-sdk query config-get workflow.code_review 2>/dev/null || echo "true")
 ```
 
 If CODE_REVIEW_ENABLED is "false":
@@ -90,14 +90,14 @@ Default is true — only skip on explicit false. This check runs AFTER phase val
 Determine review depth with priority order:
 
 1. DEPTH_OVERRIDE from --depth flag (highest priority)
-2. Config value: `node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.code_review_depth 2>/dev/null`
+2. Config value: `sdd-sdk query config-get workflow.code_review_depth 2>/dev/null`
 3. Default: "standard"
 
 ```bash
 if [ -n "$DEPTH_OVERRIDE" ]; then
   REVIEW_DEPTH="$DEPTH_OVERRIDE"
 else
-  CONFIG_DEPTH=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.code_review_depth 2>/dev/null || echo "")
+  CONFIG_DEPTH=$(sdd-sdk query config-get workflow.code_review_depth 2>/dev/null || echo "")
   REVIEW_DEPTH="${CONFIG_DEPTH:-standard}"
 fi
 ```
@@ -172,9 +172,15 @@ if [ -z "$FILES_OVERRIDE" ]; then
         for (const line of yaml.split('\n')) {
           if (/^\s+created:/.test(line)) { inSection = 'created'; continue; }
           if (/^\s+modified:/.test(line)) { inSection = 'modified'; continue; }
-          if (/^\s+\w+:/.test(line) && !/^\s+-/.test(line)) { inSection = null; continue; }
+          if (/^\s*[\w-]+:/.test(line) && !/^\s*-/.test(line)) { inSection = null; continue; }
           if (inSection && /^\s+-\s+(.+)/.test(line)) {
-            files.push(line.match(/^\s+-\s+(.+)/)[1].trim());
+            let raw = line.match(/^\s+-\s+(.+)/)[1].trim();
+            raw = raw.replace(/^['"]|['"]$/g, '');
+            raw = raw.replace(/\s+\([^)]*\)\s*$/, '');
+            raw = raw.split(/\s+—\s/)[0].trim();
+            if (/\//.test(raw) && /\.[A-Za-z0-9]+$/.test(raw)) {
+              files.push(raw);
+            }
           }
         }
         if (files.length) console.log(files.join('\n'));
@@ -227,7 +233,7 @@ if [ ${#REVIEW_FILES[@]} -eq 0 ]; then
   else
     # Fail closed — no reliable diff base found. Do not use arbitrary HEAD~N.
     echo "Warning: No phase commits found for '${PADDED_PHASE}'. Cannot determine reliable diff scope."
-    echo "Use --files flag to specify files explicitly: /sdd-code-review ${PHASE_ARG} --files=file1,file2,..."
+    echo "Use --files flag to specify files explicitly: /sdd:code-review ${PHASE_ARG} --files=file1,file2,..."
   fi
 fi
 ```
@@ -312,6 +318,78 @@ No source files changed in phase ${PHASE_ARG}. Skipping review.
 Exit workflow. Do NOT spawn agent or create REVIEW.md.
 </step>
 
+<step name="structural_pre_pass">
+Optional structural cross-module pass powered by fallow.
+
+Read fallow config gates:
+```bash
+FALLOW_ENABLED=$(sdd-sdk query config-get code_quality.fallow.enabled 2>/dev/null || echo "false")
+FALLOW_SCOPE=$(sdd-sdk query config-get code_quality.fallow.scope 2>/dev/null || echo "phase")
+FALLOW_PROFILE=$(sdd-sdk query config-get code_quality.fallow.profile 2>/dev/null || echo "standard")
+FALLOW_MCP=$(sdd-sdk query config-get code_quality.fallow.mcp 2>/dev/null || echo "false")
+```
+
+Defaults are fail-closed and opt-in:
+- `enabled=false` (skip entirely)
+- `scope=phase`
+- `profile=standard`
+- `mcp=false`
+
+When `FALLOW_ENABLED=true`:
+
+1) Resolve binary via PATH first, then `node_modules/.bin/fallow`.
+```bash
+FALLOW_BIN=$(FALLOW_CWD="$(pwd)" node -e "
+const { resolveFallowBinary } = require('./sdd/bin/lib/fallow-runner.cjs');
+const resolved = resolveFallowBinary({ cwd: process.env.FALLOW_CWD });
+if (resolved) process.stdout.write(resolved);
+")
+```
+
+2) If binary is missing, fail with actionable message:
+```bash
+if [ -z \"$FALLOW_BIN\" ]; then
+  echo \"Error: fallow is enabled but no binary was found.\"
+  echo \"Install fallow via \`npm install -D fallow\` or \`cargo install fallow\`.\"
+  # Exit workflow
+fi
+```
+
+3) Execute structural pass and persist JSON (bounded at 120s; on timeout, behaves as a fallow crash):
+```bash
+FALLOW_JSON_PATH="${PHASE_DIR}/FALLOW.json"
+FALLOW_STDERR_TMP=$(mktemp)
+if [ \"$FALLOW_SCOPE\" = \"repo\" ]; then
+  timeout 120 \"$FALLOW_BIN\" audit --json --profile \"$FALLOW_PROFILE\" > \"${FALLOW_JSON_PATH}.tmp\" 2>\"$FALLOW_STDERR_TMP\"
+  FALLOW_EXIT=$?
+else
+  # phase scope: pass the already-computed review file set
+  printf '%s\n' \"${REVIEW_FILES[@]}\" | timeout 120 \"$FALLOW_BIN\" audit --json --profile \"$FALLOW_PROFILE\" --stdin-files > \"${FALLOW_JSON_PATH}.tmp\" 2>\"$FALLOW_STDERR_TMP\"
+  FALLOW_EXIT=$?
+fi
+if [ $FALLOW_EXIT -ne 0 ]; then
+  FALLOW_STDERR_SUMMARY=$(head -5 \"$FALLOW_STDERR_TMP\")
+  rm -f \"${FALLOW_JSON_PATH}.tmp\" \"$FALLOW_STDERR_TMP\"
+  echo \"WARNING: fallow structural pre-pass failed: ${FALLOW_STDERR_SUMMARY}\"
+  FALLOW_JSON_PATH=""
+else
+  mv \"${FALLOW_JSON_PATH}.tmp\" \"$FALLOW_JSON_PATH\"
+  rm -f \"$FALLOW_STDERR_TMP\"
+fi
+```
+
+On any failure of the structural pre-pass (binary missing, non-zero exit, timeout, or JSON parse error), the workflow continues with no `<structural_findings>` injection; the reviewer agent receives a normal review request.
+
+4) Optional MCP bridge path (runtime-dependent):
+- If `FALLOW_MCP=true`, set reviewer input mode to MCP-backed structural findings.
+- Otherwise pass static JSON findings from `FALLOW.json`.
+
+When disabled, set:
+```bash
+FALLOW_JSON_PATH=""
+```
+</step>
+
 <step name="spawn_reviewer">
 Compute the review output path:
 ```bash
@@ -344,14 +422,32 @@ for file in "${REVIEW_FILES[@]}"; do
 done
 ```
 
+Build structural findings block for agent:
+```bash
+STRUCTURAL_FINDINGS_BLOCK=""
+MAX_FINDINGS_SIZE=50000
+if [ -n "$FALLOW_JSON_PATH" ] && [ -f "$FALLOW_JSON_PATH" ]; then
+  FALLOW_JSON_SIZE=$(wc -c < "$FALLOW_JSON_PATH" | tr -d '[:space:]')
+  if [ "$FALLOW_JSON_SIZE" -le "$MAX_FINDINGS_SIZE" ]; then
+    # Escape any literal closing tag before embedding; the closing tag literal is escaped to prevent prompt-structure breakage if a fallow finding's file path or message contains the sequence.
+    SAFE_FALLOW_JSON=$(sed 's#</structural_findings>#<\/structural_findings>#g' "$FALLOW_JSON_PATH")
+    STRUCTURAL_FINDINGS_BLOCK=$(printf '<structural_findings>\n%s\n</structural_findings>\n' "$SAFE_FALLOW_JSON")
+  else
+    echo "Warning: skipping structural findings embed (${FALLOW_JSON_SIZE} bytes > ${MAX_FINDINGS_SIZE} bytes). Re-run with narrower scope/profile if needed."
+  fi
+fi
+```
+
 Spawn the sdd-code-reviewer agent:
 
 ```
-Task(subagent_type="sdd-code-reviewer", prompt="
+Agent(subagent_type="sdd-code-reviewer", prompt="
 <files_to_read>
 ${FILES_TO_READ}
 </files_to_read>
 
+${STRUCTURAL_FINDINGS_BLOCK}
+
 <config>
 depth: ${REVIEW_DEPTH}
 phase_dir: ${PHASE_DIR}
@@ -366,13 +462,15 @@ Do NOT commit the output — the orchestrator handles that.
 ")
 ```
 
+> **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.
+
 **Agent failure handling:**
 
-If the Task() call fails (agent error, timeout, or exception):
+If the Agent() call fails (agent error, timeout, or exception):
 ```
 Error: Code review agent failed: ${error_message}
 
-No REVIEW.md created. You can retry with /sdd-code-review ${PHASE_ARG} or check agent logs.
+No REVIEW.md created. You can retry with /sdd:code-review ${PHASE_ARG} or check agent logs.
 ```
 
 Do NOT proceed to commit_review step. Do NOT create a partial or empty REVIEW.md. Exit workflow.
@@ -395,7 +493,7 @@ if [ -f "${REVIEW_PATH}" ]; then
     echo "REVIEW.md created at ${REVIEW_PATH}"
     
     if [ "$COMMIT_DOCS" = "true" ]; then
-      node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit \
+      sdd-sdk query commit \
         "docs(${PADDED_PHASE}): add code review report" \
         --files "${REVIEW_PATH}"
     fi
@@ -405,7 +503,7 @@ if [ -f "${REVIEW_PATH}" ]; then
   fi
 else
   echo "Warning: Agent completed but REVIEW.md not found at ${REVIEW_PATH}. This may indicate an agent issue."
-  echo "No REVIEW.md to commit. Please retry with /sdd-code-review ${PHASE_ARG}"
+  echo "No REVIEW.md to commit. Please retry with /sdd:code-review ${PHASE_ARG}"
 fi
 ```
 </step>
@@ -427,7 +525,7 @@ FRONTMATTER=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
 # Parse fields from frontmatter only (not full file)
 STATUS=$(echo "$FRONTMATTER" | grep "^status:" | cut -d: -f2 | xargs)
 FILES_REVIEWED=$(echo "$FRONTMATTER" | grep "^files_reviewed:" | cut -d: -f2 | xargs)
-CRITICAL=$(echo "$FRONTMATTER" | grep "critical:" | head -1 | cut -d: -f2 | xargs)
+CRITICAL=$(echo "$FRONTMATTER" | grep -E "^[[:space:]]*(critical|blocker):" | head -1 | cut -d: -f2 | xargs)
 WARNING=$(echo "$FRONTMATTER" | grep "warning:" | head -1 | cut -d: -f2 | xargs)
 INFO=$(echo "$FRONTMATTER" | grep "info:" | head -1 | cut -d: -f2 | xargs)
 TOTAL=$(echo "$FRONTMATTER" | grep "total:" | head -1 | cut -d: -f2 | xargs)
@@ -469,14 +567,14 @@ If total findings > 0:
 Full report: ${REVIEW_PATH}
 
 Next steps:
-  /sdd-code-review-fix ${PHASE_NUMBER}  — Auto-fix issues
+  /sdd:code-review ${PHASE_NUMBER} --fix  — Auto-fix issues
   cat ${REVIEW_PATH}                     — View full report
 ```
 
 If critical > 0 or warning > 0, list top 3 issues inline:
 ```bash
 echo "Top issues:"
-grep -A 3 "^### CR-\|^### WR-" "${REVIEW_PATH}" | head -n 12
+grep -A 3 "^### CR-\|^### BL-\|^### WR-" "${REVIEW_PATH}" | head -n 12
 ```
 
 **Note on tests:** Automated tests for this command and workflow are planned for Phase 4 (Pipeline Integration & Testing, requirement INFR-03). Phase 2 focuses on correct implementation; Phase 4 adds regression coverage across platforms.

package/sdd/workflows/commit.md

@@ -0,0 +1,166 @@
+# /sdd:commit — Manual Conventional Commit
+
+Interactive git commit. Surveys the working tree, suggests a conventional commit message
+from the diff, asks the user to confirm, then stages + commits **specific files only**.
+
+This is the fork-added replacement for the auto-commit step previously embedded in `/sdd:fast`.
+Team policy: never auto-stage with `git add -A` / `git add .` without explicit consent.
+
+## Argument parsing
+
+Set TEXT_MODE=true if `--text` appears in `$ARGUMENTS` OR `workflow.text_mode` is true in the
+init JSON. When TEXT_MODE is active, replace every AskUserQuestion call below with a plain-text
+numbered list and ask the user to type their choice — every runtime can handle that, including
+non-Claude runtimes (Codex, Gemini) that render AskUserQuestion as inert markdown.
+
+## Process
+
+<step name="check_repo">
+Verify a git repository:
+
+```bash
+git rev-parse --show-toplevel
+```
+
+If this errors, STOP and tell the user: "Not in a git repository — nothing to commit."
+</step>
+
+<step name="survey_changes">
+Show the user what's changed:
+
+```bash
+echo "=== Tracked modifications ==="
+git status --short | grep -Ev "^\?\?" || echo "(none)"
+echo
+echo "=== Untracked files ==="
+git status --short | grep "^??" || echo "(none)"
+echo
+echo "=== Diff summary ==="
+git diff --stat HEAD 2>/dev/null
+```
+
+If working tree is clean (`git status --porcelain` empty), STOP and tell the user
+"Nothing to commit — working tree is clean."
+</step>
+
+<step name="select_files">
+Default behavior: **stage only tracked modifications** — never untracked, never `-A`.
+
+If untracked files exist, ask the user (via AskUserQuestion, or a plain-text numbered list
+when TEXT_MODE is active) which they want included:
+
+- **Tracked changes only** (recommended — safest)
+- **Also stage these untracked files: [list]** (only if user confirms each one is intentional)
+- **Cancel** — abort the commit
+
+If the user invoked the command with `--all`, skip the question but **still echo the file list
+back and ask one final yes/no confirmation** before proceeding — `--all` is not a license to
+commit secrets without showing the user.
+
+Refuse to stage files matching common secret patterns. If a candidate file matches any of these
+patterns, omit it from the stage list and warn the user:
+
+- `*.env`, `.env.*` (env files)
+- `*.pem`, `*.key`, `*.crt`, `*.p12`, `*.pfx` (keys / certs)
+- `*credentials*`, `*secret*`, `*token*` (credential-like names)
+- `node_modules/`, `dist/`, `build/`, `coverage/` (build artifacts — already gitignored, but defense-in-depth)
+
+The user can override per-file by re-running with the file explicitly named in their message.
+</step>
+
+<step name="suggest_message">
+If the user passed a message as the first argument, **use it verbatim** and skip to the next step.
+
+Otherwise, generate a conventional commit message from the staged diff:
+
+```bash
+git diff --cached    # primary source — only the files about to be committed
+```
+
+If nothing is staged yet (because we're previewing before staging), use:
+
+```bash
+git diff             # working-tree diff for the files we plan to stage
+```
+
+Pick a type from this table — choose the **dominant** change type, not the loudest:
+
+| Type       | When                                             |
+| ---------- | ------------------------------------------------ |
+| `feat`     | New user-facing feature, endpoint, component     |
+| `fix`      | Bug fix, error correction                        |
+| `refactor` | Internal cleanup, no behavior change             |
+| `test`     | Test-only changes (TDD RED, missing coverage)    |
+| `docs`     | Documentation only                               |
+| `chore`    | Config, tooling, deps, build scripts             |
+| `perf`     | Performance improvement, no behavior change      |
+| `style`    | Formatting, whitespace, no logic change          |
+
+Format: `<type>(<scope>): <subject>`
+- `<scope>` is optional — use it when changes are localized to one module (e.g., `feat(auth):`).
+- `<subject>` must be ≤ 72 chars, lowercase, no trailing period, imperative mood ("add X" not "added X").
+
+If the change is large enough to warrant a body, include 2-4 bullet lines beneath the subject
+explaining the *why* (not the *what* — the diff shows what).
+
+Show the user the proposed message + the staged file list. Ask (via AskUserQuestion, or a
+plain-text numbered list when TEXT_MODE is active):
+
+- **Commit with this message**
+- **Edit the message** — user types a replacement; you re-show + re-confirm
+- **Cancel** — abort, leave the working tree as-is
+</step>
+
+<step name="stage_and_commit">
+Stage the approved files explicitly — never `-A`, never `.`:
+
+```bash
+git add path/to/file1 path/to/file2 …
+```
+
+Commit using a HEREDOC for multi-line-message safety:
+
+```bash
+git commit -m "$(cat <<'EOF'
+<approved message>
+EOF
+)"
+```
+
+If a pre-commit hook fails:
+- Show the hook's output to the user
+- Do NOT pass `--no-verify` to bypass it
+- Stop and let the user fix the underlying issue, then re-run `/sdd:commit`
+
+Never `git commit --amend` an existing commit unless the user explicitly asked. Amend rewrites
+history and surprises co-authors.
+</step>
+
+<step name="report">
+Print the short hash and what landed:
+
+```
+✅ Committed {short-hash}: <type>(<scope>): <subject>
+   Files: <file1>, <file2>, …
+
+Run `git push` when ready (this skill does not push).
+```
+
+No next-step suggestions. No workflow routing. Done.
+</step>
+
+## Guardrails
+
+- NEVER `git add -A` or `git add .` without an explicit confirmation step that lists every file going in.
+- NEVER `git push` from this skill — pushing is a separate, riskier action; user runs it manually.
+- NEVER `--amend` unless the user explicitly asked.
+- NEVER pass `--no-verify` to bypass hooks — surface the failure and stop.
+- NEVER stage files matching the secret-pattern allowlist above without an explicit per-file confirmation.
+
+## Success criteria
+
+- [ ] User saw the proposed message before commit
+- [ ] User saw every file going into the commit
+- [ ] Commit landed on the current branch (not detached HEAD, not main without intent)
+- [ ] No `.env` / credentials / build artifacts were staged
+- [ ] No `--amend`, no `--no-verify`, no `git push`