gsd-antigravity-kit 1.32.0 → 2.0.0

package/.agent/skills/gsd/references/workflows/inbox.md

@@ -0,0 +1,384 @@
+<purpose>
+Triage and review all open GitHub issues and PRs against project contribution templates.
+Produces a structured report showing compliance status for each item, flags missing
+required fields, identifies label gaps, and optionally takes action (label, comment, close).
+</purpose>
+
+<required_reading>
+Before starting, read these project files to understand the review criteria:
+- `.github/ISSUE_TEMPLATE/feature_request.yml` — required fields for feature issues
+- `.github/ISSUE_TEMPLATE/enhancement.yml` — required fields for enhancement issues
+- `.github/ISSUE_TEMPLATE/chore.yml` — required fields for chore issues
+- `.github/ISSUE_TEMPLATE/bug_report.yml` — required fields for bug reports
+- `.github/PULL_REQUEST_TEMPLATE/feature.md` — required checklist for feature PRs
+- `.github/PULL_REQUEST_TEMPLATE/enhancement.md` — required checklist for enhancement PRs
+- `.github/PULL_REQUEST_TEMPLATE/fix.md` — required checklist for fix PRs
+- `CONTRIBUTING.md` — the issue-first rule and approval gates
+</required_reading>
+
+<process>
+
+<step name="preflight">
+Verify prerequisites:
+
+1. **`gh` CLI available and authenticated?**
+   ```bash
+   which gh && gh auth status 2>&1
+   ```
+   If not available: print setup instructions and exit.
+
+2. **Detect repository:**
+   If `--repo` flag provided, use that. Otherwise:
+   ```bash
+   gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null
+   ```
+   If no repo detected: error — must be in a git repo with a GitHub remote.
+
+3. **Parse flags:**
+   - `--issues` → set REVIEW_ISSUES=true, REVIEW_PRS=false
+   - `--prs` → set REVIEW_ISSUES=false, REVIEW_PRS=true
+   - `--label` → set AUTO_LABEL=true
+   - `--close-incomplete` → set AUTO_CLOSE=true
+   - Default (no flags): review both issues and PRs, report only (no auto-actions)
+</step>
+
+<step name="fetch_issues">
+Skip if REVIEW_ISSUES=false.
+
+Fetch all open issues:
+```bash
+gh issue list --state open --json number,title,labels,body,author,createdAt,updatedAt --limit 100
+```
+
+For each issue, classify by labels and body content:
+
+| Label/Pattern | Type | Template |
+|---|---|---|
+| `feature-request` | Feature | feature_request.yml |
+| `enhancement` | Enhancement | enhancement.yml |
+| `bug` | Bug | bug_report.yml |
+| `type: chore` | Chore | chore.yml |
+| No matching label | Unknown | Flag for manual triage |
+
+If an issue has no type label, attempt to classify from the body content:
+- Contains "### Feature name" → likely Feature
+- Contains "### What existing feature" → likely Enhancement
+- Contains "### What happened?" → likely Bug
+- Contains "### What is the maintenance task?" → likely Chore
+- Cannot determine → mark as `needs-triage`
+</step>
+
+<step name="review_issues">
+Skip if REVIEW_ISSUES=false.
+
+For each classified issue, review against its template requirements.
+
+**Feature Request Review Checklist:**
+- [ ] Pre-submission checklist present (4 checkboxes)
+- [ ] Feature name provided
+- [ ] Type of addition selected
+- [ ] Problem statement filled (not placeholder text)
+- [ ] What is being added described with examples
+- [ ] Full scope of changes listed (files created/modified/systems)
+- [ ] User stories present (minimum 2)
+- [ ] Acceptance criteria present (testable conditions)
+- [ ] Applicable runtimes selected
+- [ ] Breaking changes assessment present
+- [ ] Maintenance burden described
+- [ ] Alternatives considered (not empty)
+- **Label check:** Has `needs-review` label? Has `approved-feature` label?
+- **Gate check:** If PR exists linking this issue, does issue have `approved-feature`?
+
+**Enhancement Review Checklist:**
+- [ ] Pre-submission checklist present (4 checkboxes)
+- [ ] What is being improved identified
+- [ ] Current behavior described with examples
+- [ ] Proposed behavior described with examples
+- [ ] Reason and benefit articulated (not vague)
+- [ ] Scope of changes listed
+- [ ] Breaking changes assessed
+- [ ] Alternatives considered
+- [ ] Area affected selected
+- **Label check:** Has `needs-review` label? Has `approved-enhancement` label?
+- **Gate check:** If PR exists linking this issue, does issue have `approved-enhancement`?
+
+**Bug Report Review Checklist:**
+- [ ] GSD Version provided
+- [ ] Runtime selected
+- [ ] OS selected
+- [ ] Node.js version provided
+- [ ] Description of what happened
+- [ ] Expected behavior described
+- [ ] Steps to reproduce provided
+- [ ] Frequency selected
+- [ ] Severity/impact selected
+- [ ] PII checklist confirmed
+- **Label check:** Has `needs-triage` or `confirmed-bug` label?
+
+**Chore Review Checklist:**
+- [ ] Pre-submission checklist confirmed (no user-facing changes)
+- [ ] Maintenance task described
+- [ ] Type of maintenance selected
+- [ ] Current state described with specifics
+- [ ] Proposed work listed
+- [ ] Acceptance criteria present
+- [ ] Area affected selected
+- **Label check:** Has `needs-triage` label?
+
+**Scoring:** For each issue, calculate a completeness percentage:
+- Count required fields present vs. total required fields
+- Score = (present / total) * 100
+- Status: COMPLETE (100%), MOSTLY COMPLETE (75-99%), INCOMPLETE (50-74%), REJECT (<50%)
+</step>
+
+<step name="fetch_prs">
+Skip if REVIEW_PRS=false.
+
+Fetch all open PRs:
+```bash
+gh pr list --state open --json number,title,labels,body,author,headRefName,baseRefName,isDraft,createdAt,reviewDecision,statusCheckRollup --limit 100
+```
+
+For each PR, classify by body content and linked issue:
+
+| Body Pattern | Type | Template |
+|---|---|---|
+| Contains "## Feature PR" or "## Feature summary" | Feature PR | feature.md |
+| Contains "## Enhancement PR" or "## What this enhancement improves" | Enhancement PR | enhancement.md |
+| Contains "## Fix PR" or "## What was broken" | Fix PR | fix.md |
+| Uses default template | Wrong Template | Flag — must use typed template |
+| Cannot determine | Unknown | Flag for manual review |
+
+Also check for linked issues:
+```bash
+gh pr view {number} --json body -q '.body' | grep -oE '(Closes|Fixes|Resolves) #[0-9]+'
+```
+</step>
+
+<step name="review_prs">
+Skip if REVIEW_PRS=false.
+
+For each classified PR, review against its template requirements.
+
+**Feature PR Review Checklist:**
+- [ ] Uses feature PR template (not default)
+- [ ] Issue linked with `Closes #NNN`
+- [ ] Linked issue exists and has `approved-feature` label
+- [ ] Feature summary present
+- [ ] New files table filled
+- [ ] Modified files table filled
+- [ ] Implementation notes present
+- [ ] Spec compliance checklist present (acceptance criteria from issue)
+- [ ] Test coverage described
+- [ ] Platforms tested checked (macOS, Windows, Linux)
+- [ ] Runtimes tested checked
+- [ ] Scope confirmation checked
+- [ ] Full checklist completed
+- [ ] Breaking changes section filled
+- **CI check:** All status checks passing?
+- **Review check:** Has review approval?
+
+**Enhancement PR Review Checklist:**
+- [ ] Uses enhancement PR template (not default)
+- [ ] Issue linked with `Closes #NNN`
+- [ ] Linked issue exists and has `approved-enhancement` label
+- [ ] What is improved described
+- [ ] Before/after provided
+- [ ] Implementation approach described
+- [ ] Verification method described
+- [ ] Platforms tested checked
+- [ ] Runtimes tested checked
+- [ ] Scope confirmation checked
+- [ ] Full checklist completed
+- [ ] Breaking changes section filled
+- **CI check:** All status checks passing?
+
+**Fix PR Review Checklist:**
+- [ ] Uses fix PR template (not default)
+- [ ] Issue linked with `Fixes #NNN`
+- [ ] Linked issue exists and has `confirmed-bug` label
+- [ ] What was broken described
+- [ ] What the fix does described
+- [ ] Root cause explained
+- [ ] Verification method described
+- [ ] Regression test added (or explained why not)
+- [ ] Platforms tested checked
+- [ ] Runtimes tested checked
+- [ ] Full checklist completed
+- [ ] Breaking changes section filled
+- **CI check:** All status checks passing?
+
+**Cross-cutting PR Checks (all types):**
+- [ ] PR title is descriptive (not just "fix" or "update")
+- [ ] One concern per PR (not mixing fix + enhancement)
+- [ ] No unrelated formatting changes visible in diff
+- [ ] CHANGELOG.md updated
+- [ ] Not using `--no-verify` or skipping hooks
+
+**Scoring:** Same as issues — completeness percentage per PR.
+</step>
+
+<step name="check_gates">
+Cross-reference issues and PRs to enforce the issue-first rule:
+
+For each open PR:
+1. Extract linked issue number from body
+2. If no linked issue: **GATE VIOLATION** — PR has no issue
+3. If linked issue exists, check its labels:
+   - Feature PR → issue must have `approved-feature`
+   - Enhancement PR → issue must have `approved-enhancement`
+   - Fix PR → issue must have `confirmed-bug`
+4. If label is missing: **GATE VIOLATION** — PR opened before approval
+
+Report gate violations prominently — these are the most important findings because
+the project auto-closes PRs without proper approval gates.
+</step>
+
+<step name="generate_report">
+Produce a structured triage report:
+
+```
+===================================================================
+  GSD INBOX TRIAGE — {repo} — {date}
+===================================================================
+
+SUMMARY
+-------
+Open issues: {count}    Open PRs: {count}
+  Features:    {n}        Feature PRs:      {n}
+  Enhancements:{n}        Enhancement PRs:  {n}
+  Bugs:        {n}        Fix PRs:          {n}
+  Chores:      {n}        Wrong template:   {n}
+  Unclassified:{n}        No linked issue:  {n}
+
+GATE VIOLATIONS (action required)
+---------------------------------
+{For each violation:}
+  PR #{number}: {title}
+    Problem: {description — e.g., "No approved-feature label on linked issue #45"}
+    Action:  {what to do — e.g., "Close PR or approve issue #45 first"}
+
+ISSUES NEEDING ATTENTION
+------------------------
+{For each issue sorted by completeness score, lowest first:}
+  #{number} [{type}] {title}
+    Score: {percentage}% complete
+    Missing: {list of missing required fields}
+    Labels: {current labels} → Suggested: {recommended labels}
+    Age: {days since created}
+
+PRS NEEDING ATTENTION
+---------------------
+{For each PR sorted by completeness score, lowest first:}
+  #{number} [{type}] {title}
+    Score: {percentage}% complete
+    Missing: {list of missing checklist items}
+    CI: {passing/failing/pending}
+    Review: {approved/changes_requested/none}
+    Linked issue: #{issue_number} ({issue_status})
+    Age: {days since created}
+
+READY TO MERGE
+--------------
+{PRs that are 100% complete, CI passing, approved:}
+  #{number} {title} — ready
+
+STALE ITEMS (>30 days, no activity)
+------------------------------------
+{Issues and PRs with no updates in 30+ days}
+
+===================================================================
+```
+
+Write this report to `.planning/INBOX-TRIAGE.md` if a `.planning/` directory exists,
+otherwise print to console only.
+</step>
+
+<step name="auto_actions">
+Only execute if `--label` or `--close-incomplete` flags were set.
+
+**If --label:**
+For each issue/PR where labels are missing or incorrect:
+```bash
+gh issue edit {number} --add-label "{label}"
+```
+Or:
+```bash
+gh pr edit {number} --add-label "{label}"
+```
+
+Label recommendations:
+- Unclassified issues → add `needs-triage`
+- Feature issues without review → add `needs-review`
+- Enhancement issues without review → add `needs-review`
+- Bug reports without triage → add `needs-triage`
+- PRs with gate violations → add `gate-violation`
+
+**If --close-incomplete:**
+For issues scoring below 50% completeness:
+```bash
+gh issue close {number} --comment "Closed by GSD inbox triage: this issue is missing required fields per the issue template. Missing: {list}. Please reopen with a complete submission. See CONTRIBUTING.md for requirements."
+```
+
+For PRs with gate violations:
+```bash
+gh pr close {number} --comment "Closed by GSD inbox triage: this PR does not meet the issue-first requirement. {specific violation}. See CONTRIBUTING.md for the correct process."
+```
+
+Always confirm with the user before closing anything:
+```
+AskUserQuestion:
+  question: "Found {N} items to close. Review the list above — proceed with closing?"
+  options:
+    - label: "Close all"
+      description: "Close all {N} non-compliant items with explanation comments"
+    - label: "Let me pick"
+      description: "I'll choose which ones to close"
+    - label: "Skip"
+      description: "Don't close anything — report only"
+```
+</step>
+
+<step name="report">
+```
+───────────────────────────────────────────────────────────────
+
+## Inbox Triage Complete
+
+Reviewed: {issue_count} issues, {pr_count} PRs
+Gate violations: {violation_count}
+Ready to merge: {ready_count}
+Needing attention: {attention_count}
+Stale (30+ days): {stale_count}
+{If report saved: "Report saved to .planning/INBOX-TRIAGE.md"}
+
+Next steps:
+- Review gate violations first — these block the contribution pipeline
+- Address incomplete submissions (comment or close)
+- Merge ready PRs
+- Triage unclassified issues
+
+───────────────────────────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<offer_next>
+After triage:
+
+- /gsd-review — Run cross-AI peer review on a specific phase plan
+- /gsd-ship — Create a PR from completed work
+- /gsd-progress — See overall project state
+- /gsd-inbox --label — Re-run with auto-labeling enabled
+</offer_next>
+
+<success_criteria>
+- [ ] All open issues fetched and classified by type
+- [ ] Each issue reviewed against its template requirements
+- [ ] All open PRs fetched and classified by type
+- [ ] Each PR reviewed against its template checklist
+- [ ] Issue-first gate violations identified
+- [ ] Structured report generated with scores and action items
+- [ ] Auto-actions executed only when flagged and user-confirmed
+</success_criteria>

package/.agent/skills/gsd/references/workflows/manager.md

@@ -26,7 +26,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_count`, `in_progress_count`, `phases`, `recommended_actions`, `all_complete`, `waiting_signal`, `manager_flags`.
 
 `manager_flags` contains per-step passthrough flags from config:
-- `manager_flags.discuss` — appended to `/gsd:discuss-phase` args (e.g. `"--auto --analyze"`)
+- `manager_flags.discuss` — appended to `/gsd-discuss-phase` args (e.g. `"--auto --analyze"`)
 - `manager_flags.plan` — appended to plan agent init command
 - `manager_flags.execute` — appended to execute agent init command
 
@@ -113,8 +113,8 @@ If `all_complete` is true:
 ╚══════════════════════════════════════════════════════════════╝
 
 All {phase_count} phases done. Ready for final steps:
-  → /gsd:verify-work — run acceptance testing
-  → /gsd:complete-milestone — archive and wrap up
+  → /gsd-verify-work — run acceptance testing
+  → /gsd-complete-milestone — archive and wrap up
 ```
 
 Ask user via AskUserQuestion:
@@ -335,11 +335,11 @@ Display final status with progress bar:
  {milestone_version} — {milestone_name}
  {PROGRESS_BAR} {progress_pct}%  ({completed_count}/{phase_count} phases)
 
- Resume anytime: /gsd:manager
+ Resume anytime: /gsd-manager
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**Note:** Any background agents still running will continue to completion. Their results will be visible on next `/gsd:manager` or `/gsd:progress` invocation.
+**Note:** Any background agents still running will continue to completion. Their results will be visible on next `/gsd-manager` or `/gsd-progress` invocation.
 
 </step>
 

package/.agent/skills/gsd/references/workflows/new-milestone.md

@@ -140,7 +140,7 @@ Delete MILESTONE-CONTEXT.md if exists (consumed).
 Clear leftover phase directories from the previous milestone:
 
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" phases clear
+.agent/skills/gsd/bin/gsd-tools.cjs" phases clear --confirm
 ```
 
 ```bash

package/.agent/skills/gsd/references/workflows/next.md

@@ -34,6 +34,62 @@ No GSD project detected. Run `/gsd-new-project` to get started.
 Exit.
 </step>
 
+<step name="safety_gates">
+Run hard-stop checks before routing. Exit on first hit unless `--force` was passed.
+
+If `--force` flag was passed, skip all gates and the consecutive guard.
+Print a one-line warning: `⚠ --force: skipping safety gates`
+Then proceed directly to `determine_next_action`.
+
+**Gate 1: Unresolved checkpoint**
+Check if `.planning/.continue-here.md` exists:
+```bash
+[ -f .planning/.continue-here.md ]
+```
+If found:
+```
+⛔ Hard stop: Unresolved checkpoint
+
+`.planning/.continue-here.md` exists — a previous session left
+unfinished work that needs manual review before advancing.
+
+Read the file, resolve the issue, then delete it to continue.
+Use `--force` to bypass this check.
+```
+Exit (do not route).
+
+**Gate 2: Error state**
+Check if STATE.md contains `status: error` or `status: failed`:
+If found:
+```
+⛔ Hard stop: Project in error state
+
+STATE.md shows status: {status}. Resolve the error before advancing.
+Run `/gsd-health` to diagnose, or manually fix STATE.md.
+Use `--force` to bypass this check.
+```
+Exit.
+
+**Gate 3: Unchecked verification**
+Check if the current phase has a VERIFICATION.md with any `FAIL` items that don't have overrides:
+If found:
+```
+⛔ Hard stop: Unchecked verification failures
+
+VERIFICATION.md for phase {N} has {count} unresolved FAIL items.
+Address the failures or add overrides before advancing to the next phase.
+Use `--force` to bypass this check.
+```
+Exit.
+
+**Consecutive-call guard:**
+After passing all gates, check a counter file `.planning/.next-call-count`:
+- If file exists and count >= 6: prompt "You've called /gsd-next {N} times consecutively. Continue? [y/N]"
+- If user says no, exit
+- Increment the counter
+- The counter file is deleted by any non-`/gsd-next` command (convention — other workflows don't need to implement this, the note here is sufficient)
+</step>
+
 <step name="determine_next_action">
 Apply routing rules based on state:
 

package/.agent/skills/gsd/references/workflows/plan-phase.md

@@ -6,6 +6,10 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
 Read all files referenced by the invoking prompt's execution_context before starting.
 
 @references/docs/ui-brand.md
+@references/docs/revision-loop.md
+@references/docs/gate-prompts.md
+@references/docs/agent-contracts.md
+@references/docs/gates.md
 </required_reading>
 
 <available_agent_types>
@@ -769,13 +773,56 @@ Task(
 - **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
 - **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
 
+**Thinking partner for architectural tradeoffs (conditional):**
+If `features.thinking_partner` is enabled, scan the checker's issues for architectural tradeoff keywords
+("architecture", "approach", "strategy", "pattern", "vs", "alternative"). If found:
+
+```
+The plan-checker flagged an architectural decision point:
+{issue description}
+
+Brief analysis:
+- Option A: {approach_from_plan} — {pros/cons}
+- Option B: {alternative_approach} — {pros/cons}
+- Recommendation: {choice} aligned with {phase_goal}
+
+Apply this to the revision? [Yes] / [No, I'll decide]
+```
+
+If yes: include the recommendation in the revision prompt. If no: proceed to revision loop as normal.
+If thinking_partner disabled: skip this block entirely.
+
 ## 12. Revision Loop (Max 3 Iterations)
 
 Track `iteration_count` (starts at 1 after initial plan + check).
+Track `prev_issue_count` (initialized to `Infinity` before the loop begins).
+Track `stall_reentry_count` (starts at 0; incremented each time "Adjust approach" re-enters step 8).
 
 **If iteration_count < 3:**
 
-Display: `Sending back to planner for revision... (iteration {N}/3)`
+Parse issue count from checker return: count BLOCKER + WARNING entries in the YAML issues block (structured output from gsd-plan-checker). If the checker's return contains no YAML issues block (i.e., the plan was approved with no issues), treat `issue_count` as 0 and skip the stall check — the plan passed. Proceed to step 13.
+
+Display: `Revision iteration {N}/3 -- {blocker_count} blockers, {warning_count} warnings`
+
+**Stall detection:** If `issue_count >= prev_issue_count`:
+  Display: `Revision loop stalled — issue count not decreasing ({issue_count} issues remain after {N} iterations)`
+
+  **If `stall_reentry_count < 2`:**
+    Ask user:
+      Question: "Issues remain after {N} revision attempts with no progress. Proceed with current output?"
+      Options: "Proceed anyway" | "Adjust approach"
+    If "Proceed anyway": accept current plans and continue to step 13.
+    If "Adjust approach": increment `stall_reentry_count`, open freeform discussion, then re-enter step 8 (full replanning). Note: re-entry resets `iteration_count` and `prev_issue_count` but `stall_reentry_count` persists across re-entries and is capped at 2.
+
+  **If `stall_reentry_count >= 2`:**
+    Display: `Stall persists after 2 re-planning attempts. The following issues could not be resolved automatically:`
+    List the remaining issues from the checker.
+    Suggest: "Consider resolving these issues manually or running `/gsd-debug` to investigate root causes."
+    Options: "Proceed anyway" | "Abandon"
+    If "Proceed anyway": accept current plans and continue to step 13.
+    If "Abandon": stop workflow.
+
+Set `prev_issue_count = issue_count`.
 
 Revision prompt:
 

package/.agent/skills/gsd/references/workflows/quick.md

@@ -23,6 +23,7 @@ Valid GSD subagent types (use exact names — do not fall back to 'general-purpo
 - gsd-plan-checker — Reviews plan quality before execution
 - gsd-executor — Executes plan tasks, commits, creates SUMMARY.md
 - gsd-verifier — Verifies phase completion, checks quality gates
+- gsd-code-reviewer — Reviews source files for bugs, security issues, and code quality
 </available_agent_types>
 
 <process>
@@ -603,7 +604,44 @@ After executor returns:
    for WT in $WORKTREES; do
      WT_BRANCH=$(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null)
      if [ -n "$WT_BRANCH" ] && [ "$WT_BRANCH" != "HEAD" ]; then
-       git merge "$WT_BRANCH" --no-edit -m "chore: merge quick task worktree ($WT_BRANCH)" 2>&1 || echo "⚠ Merge conflict — resolve manually"
+       # --- Orchestrator file protection (#1756) ---
+       # Backup STATE.md and ROADMAP.md before merge (main always wins)
+       STATE_BACKUP=$(mktemp)
+       ROADMAP_BACKUP=$(mktemp)
+       git show HEAD:.planning/STATE.md > "$STATE_BACKUP" 2>/dev/null || true
+       git show HEAD:.planning/ROADMAP.md > "$ROADMAP_BACKUP" 2>/dev/null || true
+
+       # Snapshot files on main to detect resurrections
+       PRE_MERGE_FILES=$(git ls-files .planning/)
+
+       git merge "$WT_BRANCH" --no-edit -m "chore: merge quick task worktree ($WT_BRANCH)" 2>&1 || {
+         echo "⚠ Merge conflict — resolve manually"
+         rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
+         continue
+       }
+
+       # Restore orchestrator-owned files
+       if [ -s "$STATE_BACKUP" ]; then cp "$STATE_BACKUP" .planning/STATE.md; fi
+       if [ -s "$ROADMAP_BACKUP" ]; then cp "$ROADMAP_BACKUP" .planning/ROADMAP.md; fi
+       rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
+
+       # Remove files deleted on main but re-added by worktree
+       DELETED_FILES=$(git diff --diff-filter=A --name-only HEAD~1 -- .planning/ 2>/dev/null || true)
+       for RESURRECTED in $DELETED_FILES; do
+         if ! echo "$PRE_MERGE_FILES" | grep -qxF "$RESURRECTED"; then
+           git rm -f "$RESURRECTED" 2>/dev/null || true
+         fi
+       done
+
+       if ! git diff --quiet .planning/STATE.md .planning/ROADMAP.md 2>/dev/null || \
+          [ -n "$DELETED_FILES" ]; then
+.agent/skills/gsd/bin/gsd-tools.cjs" config-get commit_docs 2>/dev/null || echo "true")
+         if [ "$COMMIT_DOCS" != "false" ]; then
+           git add .planning/STATE.md .planning/ROADMAP.md 2>/dev/null || true
+           git commit --amend --no-edit 2>/dev/null || true
+         fi
+       fi
+
        git worktree remove "$WT" --force 2>/dev/null || true
        git branch -D "$WT_BRANCH" 2>/dev/null || true
      fi
@@ -622,6 +660,55 @@ Note: For quick tasks producing multiple plans (rare), spawn executors in parall
 
 ---
 
+**Step 6.25: Code review (auto)**
+
+Skip this step entirely if `$FULL_MODE` is false.
+
+**Config gate:**
+```bash
+.agent/skills/gsd/bin/gsd-tools.cjs" config-get workflow.code_review 2>/dev/null || echo "true")
+```
+If `"false"`, skip with message "Code review skipped (workflow.code_review=false)".
+
+**Scope files from executor's commits:**
+```bash
+# Find the diff base: last commit before quick task started
+# Use git log to find commits referencing the quick task id, then take the parent of the oldest
+QUICK_COMMITS=$(git log --oneline --format="%H" --grep="${quick_id}" 2>/dev/null)
+if [ -n "$QUICK_COMMITS" ]; then
+  DIFF_BASE=$(echo "$QUICK_COMMITS" | tail -1)^
+  # Verify parent exists (guard against first commit in repo)
+  git rev-parse "${DIFF_BASE}" >/dev/null 2>&1 || DIFF_BASE=$(echo "$QUICK_COMMITS" | tail -1)
+else
+  # No commits found for this quick task — skip review
+  DIFF_BASE=""
+fi
+
+if [ -n "$DIFF_BASE" ]; then
+  CHANGED_FILES=$(git diff --name-only "${DIFF_BASE}..HEAD" -- . ':!.planning' 2>/dev/null | tr '\n' ' ')
+else
+  CHANGED_FILES=""
+fi
+```
+
+If `CHANGED_FILES` is empty, skip with "No source files changed — skipping code review."
+
+**Invoke review:**
+```
+Task(
+  prompt="Review these files for bugs, security issues, and code quality.
+  Files: ${CHANGED_FILES}
+  Output: ${QUICK_DIR}/${quick_id}-REVIEW.md
+  Depth: quick",
+  subagent_type="gsd-code-reviewer",
+  model="{executor_model}"
+)
+```
+
+If review produces findings, display advisory message. **Error handling:** Failures are non-blocking — catch and proceed.
+
+---
+
 **Step 6.5: Verification (only when `$VALIDATE_MODE`)**
 
 Skip this step entirely if NOT `$VALIDATE_MODE`.
@@ -739,7 +826,14 @@ Build file list:
 ```bash
 # Explicitly stage all artifacts before commit — PLAN.md may be untracked
 # if the executor ran without worktree isolation and committed docs early
-git add ${file_list} 2>/dev/null
+# Filter .planning/ files from staging if commit_docs is disabled (#1783)
+.agent/skills/gsd/bin/gsd-tools.cjs" config-get commit_docs 2>/dev/null || echo "true")
+if [ "$COMMIT_DOCS" = "false" ]; then
+  file_list_filtered=$(echo "${file_list}" | tr ' ' '\n' | grep -v '^\.planning/' | tr '\n' ' ')
+  git add ${file_list_filtered} 2>/dev/null
+else
+  git add ${file_list} 2>/dev/null
+fi
 .agent/skills/gsd/bin/gsd-tools.cjs" commit "docs(quick-${quick_id}): ${DESCRIPTION}" --files ${file_list}
 ```