@opengsd/gsd-core 1.19.0 → 1.20.1

package/gsd-core/workflows/code-review-fix.md

@@ -270,7 +270,32 @@ if [ "$AUTO_MODE" = "true" ]; then
   # It is re-derived there from the final REVIEW.md's status, which is exactly the condition the
   # `break` below fires on. A variable set here and read nowhere would just be a decoy.
 
-  while [ $ITERATION -lt $MAX_ITERATIONS ]; do
+  # #4100: the loop used to stop only on a re-review returning `status: clean`. A review whose
+  # remaining findings are all OUTSIDE the fix scope (Info, or necessity findings without --all)
+  # never reaches clean, so the loop re-spawned the fixer with nothing to fix until the cap and then
+  # printed the degradation warning over a run with no work left. The fixer is the scope authority:
+  # its REVIEW-FIX.md `findings_in_scope` is read strictly — only a frontmatter value of 0 proves
+  # zero scope; a missing report or an unusable value keeps the old behaviour.
+  _gsd_fix_scope_empty() {
+    [ -f "$1" ] || return 1
+    _gsd_n=$(FIX_REPORT_PATH="$1" node -e "
+      const fs = require('fs');
+      try {
+        const content = fs.readFileSync(process.env.FIX_REPORT_PATH, 'utf-8');
+        const m = content.replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---/);
+        const v = m && m[1].match(/^findings_in_scope:[ \t]*([0-9]+)[ \t]*$/m);
+        process.stdout.write(v ? String(Number(v[1])) : '');
+      } catch (e) {}
+    " 2>/dev/null || true)
+    [ "$_gsd_n" = "0" ]
+  }
+  NO_SCOPE_LEFT=false
+  if _gsd_fix_scope_empty "${FIX_REPORT_PATH}"; then
+    NO_SCOPE_LEFT=true
+    echo "No findings in fix scope (${FIX_SCOPE}) — skipping the re-review loop. Out-of-scope findings remain in ${REVIEW_PATH}."
+  fi
+
+  while [ "$NO_SCOPE_LEFT" = false ] && [ $ITERATION -lt $MAX_ITERATIONS ]; do
     ITERATION=$((ITERATION + 1))
     
     echo ""
@@ -361,6 +386,12 @@ ${AGENT_SKILLS_FIXER}")
       echo "Warning: Iteration ${ITERATION} fixer failed to produce fix report. Stopping auto-loop."
       break
     fi
+    if _gsd_fix_scope_empty "${FIX_REPORT_PATH}"; then
+      NO_SCOPE_LEFT=true
+      echo ""
+      echo "✓ No in-scope findings remain after iteration ${ITERATION} (scope: ${FIX_SCOPE}). Out-of-scope findings remain in ${REVIEW_PATH}."
+      break
+    fi
   done
   
   # After loop completes. The iteration COUNTER alone does not distinguish degradation from success:
@@ -369,7 +400,7 @@ ${AGENT_SKILLS_FIXER}")
   # every finding was fixed — telling the operator the opposite of what happened, on the one path
   # where the cap and convergence coincide. Convergence is re-derived from the review the loop left
   # behind, the same signal cleanup_iteration_backups reads, so the two cannot disagree.
-  if [ $ITERATION -ge $MAX_ITERATIONS ]; then
+  if [ "$NO_SCOPE_LEFT" = false ] && [ $ITERATION -ge $MAX_ITERATIONS ]; then
     LOOP_END_STATUS=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
       const fs = require('fs');
       try {
@@ -491,8 +522,9 @@ which is the one distinction #3829 exists to make.
 Convergence is re-derived here rather than carried. Shell state does not survive the loop's fence, so
 a flag set there would be gone by this step — and once nothing in the loop consumed it, keeping it
 would have left a variable set in one place and read in none. The loop breaks on exactly one
-condition, a re-review returning clean, and that leaves `REVIEW.md` at `status: clean`: the final
-review's status IS the converged case. Hitting `MAX_ITERATIONS` leaves the last re-review non-clean,
+condition that counts as convergence, a re-review returning clean, and that leaves `REVIEW.md` at
+`status: clean`: the final review's status IS the converged case. Its other stop, nothing left in
+fix scope (#4100), leaves out-of-scope findings in a non-clean review, so the backups are kept. Hitting `MAX_ITERATIONS` leaves the last re-review non-clean,
 and the backups are kept.
 
 ```bash
@@ -586,7 +618,16 @@ echo ""
 
 If status is "all_fixed":
 ```bash
-if [ "$FIX_STATUS" = "all_fixed" ]; then
+if [ "${FINDINGS_IN_SCOPE:-}" = "0" ]; then
+  # #4100: a vacuous all_fixed (nothing was in scope) must not claim the review is resolved.
+  echo "○ No findings were in fix scope (${FIX_SCOPE}). Out-of-scope findings (Info, and necessity unless --all) remain in ${REVIEW_PATH}."
+  echo ""
+  if [ "${FIX_SCOPE}" != "all" ]; then
+    echo "Next step:"
+    echo "  /gsd:code-review ${PHASE_NUMBER} --fix --all  — Include them in the fix scope"
+    echo ""
+  fi
+elif [ "$FIX_STATUS" = "all_fixed" ]; then
   echo "✓ All issues resolved."
   echo ""
   echo "Full report: ${FIX_REPORT_PATH}"

package/gsd-core/workflows/code-review.md

@@ -932,6 +932,8 @@ CRITICAL=$(echo "$FRONTMATTER" | grep -E "^[[:space:]]*(critical|blocker):" | he
 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)
+# #4100: necessity is a SUBSET of warning+info, never part of total. Absent at quick depth.
+NECESSITY=$(echo "$FRONTMATTER" | grep -E "^[[:space:]]*necessity:" | head -1 | cut -d: -f2 | sed 's/#.*//' | xargs)
 ```
 
 Display inline summary to user:
@@ -950,6 +952,7 @@ Display inline summary to user:
     Critical:  ${CRITICAL}
     Warning:   ${WARNING}
     Info:      ${INFO}
+    Necessity: ${NECESSITY:-not assessed} (of the above; skipped by --fix unless --all)
 
 ---
     Total:     ${TOTAL}

package/gsd-core/workflows/execute-phase.md

@@ -958,7 +958,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
    if [ "${TEST_EXIT}" -eq 0 ]; then
      # Update ROADMAP plan progress for each completed plan in this wave
      for plan_id in {completed_plan_ids}; do
-       gsd_run query roadmap.update-plan-progress "${PHASE_NUMBER}" "${plan_id}" "complete"
+       PROGRESS=$(gsd_run query roadmap.update-plan-progress "${PHASE_NUMBER}" "${plan_id}" "complete") && REASON=$(jq -er '.reason//""' <<<"$PROGRESS") && [ "$REASON" != missing_phase_details ] || { echo "ERROR: ROADMAP update-plan-progress did not complete for ${PHASE_NUMBER}-${plan_id} (missing_phase_details decline, failed query, or jq not installed). STOP: skip this plan's completion steps." >&2; exit 1; }
      done
 
      # Only commit tracking files if they actually changed

package/gsd-core/workflows/execute-plan.md

@@ -504,7 +504,7 @@ IS_WORKTREE=$([ -f .git ] && echo "true" || echo "false")
 
 if [ "$IS_WORKTREE" != "true" ]; then
   # use_worktrees: false → this handler is the sole post-plan sync point (#2661)
-  gsd_run query roadmap.update-plan-progress "${PHASE}"
+  PROGRESS=$(gsd_run query roadmap.update-plan-progress "${PHASE}") && REASON=$(jq -er '.reason//""' <<<"$PROGRESS") && [ "$REASON" != missing_phase_details ] || { echo "ERROR: ROADMAP update-plan-progress did not complete for ${PHASE}-${PLAN} (missing_phase_details decline, failed query, or jq not installed). STOP: skip this plan's completion steps." >&2; exit 1; }
 fi
 ```
 Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct count and status (`In Progress` or `Complete` with date).

package/gsd-core/workflows/plan-phase/steps/stall-detection-helpers.md

@@ -103,23 +103,27 @@ PLANNER_STALL_THRESHOLD_MINUTES=$(gsd_run query config-get planner.stall_thresho
 # a reliability risk this fix cannot afford: a malformed config value would
 # abort the stall-watcher itself with a bash syntax error, silently defeating
 # the exact hang-recovery this issue is about. Reject anything that is not a
-# bare non-negative integer before it is ever used, so a bad config value
-# degrades to the safe default instead of crashing the watcher.
-[[ "$PLANNER_STALL_INTERVAL_MINUTES" =~ ^[0-9]+$ ]] || PLANNER_STALL_INTERVAL_MINUTES=5
-[[ "$PLANNER_STALL_THRESHOLD_MINUTES" =~ ^[0-9]+$ ]] || PLANNER_STALL_THRESHOLD_MINUTES=10
+# bare positive integer before it is ever used, so a bad config value
+# degrades to the safe default instead of crashing the watcher. Zero is
+# rejected too (#3923): an interval of 0 makes every gsd_stall_watch cycle a
+# zero-length sleep, and a threshold of 0 declares a healthy agent stalled on
+# the first check. At most 9 digits, so `* 60` can never overflow.
+[[ "$PLANNER_STALL_INTERVAL_MINUTES" =~ ^[1-9][0-9]{0,8}$ ]] || PLANNER_STALL_INTERVAL_MINUTES=5
+[[ "$PLANNER_STALL_THRESHOLD_MINUTES" =~ ^[1-9][0-9]{0,8}$ ]] || PLANNER_STALL_THRESHOLD_MINUTES=10
 
 # gsd_stall_should_recover — pure decision function, no IO, no sleeping. Given how
 # long the orchestrator has been waiting plus two liveness signals (a completion
 # marker found in the agent's output file, and fresh on-disk artifact activity),
 # decides whether to keep waiting, treat the wait as satisfied, or auto-surface the
 # existing accept/retry/stop recovery menu (9a/11a). Never kills or retries anything
-# itself — it only classifies. Re-validates both numeric args as bare non-negative
-# integers (defense in depth — safe to call with any input, not just the resolved
-# config globals above) before either ever reaches arithmetic expansion.
+# itself — it only classifies. Re-validates both numeric args as bounded bare
+# non-negative integers (defense in depth — safe to call with any input, not just
+# the resolved config globals above, which are always >= 1) before either ever
+# reaches arithmetic expansion. It accepts 0 so callers can test boundaries.
 gsd_stall_should_recover() {
   local elapsed_seconds="$1" threshold_minutes="$2" marker_found="$3" artifact_fresh="$4"
-  [[ "$elapsed_seconds" =~ ^[0-9]+$ ]] || elapsed_seconds=0
-  [[ "$threshold_minutes" =~ ^[0-9]+$ ]] || threshold_minutes=10
+  [[ "$elapsed_seconds" =~ ^[0-9]{1,15}$ ]] || elapsed_seconds=0
+  [[ "$threshold_minutes" =~ ^[0-9]{1,9}$ ]] || threshold_minutes=10
   local threshold_seconds=$(( threshold_minutes * 60 ))
   if [ "$marker_found" = "true" ]; then
     echo "marker_received"; return 0

package/gsd-core/workflows/plan-phase.md

@@ -1441,7 +1441,7 @@ This step is derived entirely from existing PLAN frontmatter — no extra LLM pa
 gsd_run query roadmap.annotate-dependencies "${PHASE_NUMBER}"
 ```
 
-This operation is idempotent: if wave headers or cross-cutting constraints already exist in the ROADMAP phase section, the command returns without modifying the file. Skip this step if `plan_count` is 0.
+Skip this step if `plan_count` is 0. Re-running regenerates the annotation from current PLAN frontmatter; an unchanged result writes nothing, and an unrecognised checklist row leaves ROADMAP.md untouched and reports `skipped: "unrecognised_checklist_row"`. The `**Cross-cutting constraints:**` header line ends in an HTML-comment marker; that block is machine-owned and the bullets directly under it are regenerated. Put hand-written bullets after a blank line. Bullets kept from a block written before the marker existed are reported as `stale_legacy_constraints`.
 
 ## 13d. Commit Plans if commit_docs is true
 

package/gsd-core/workflows/pr-branch.md

@@ -90,6 +90,8 @@ jq dependency). Write dirty repo names to a temp file so the list survives acros
 subsequent command executions:
 
 ```bash
+# #5548: drop inherited repo-location vars (set inside git hooks) so cwd, not GIT_DIR, picks ROOT.
+unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_OBJECT_DIRECTORY GIT_DIR GIT_WORK_TREE GIT_IMPLICIT_WORK_TREE GIT_GRAFT_FILE GIT_INDEX_FILE GIT_NO_REPLACE_OBJECTS GIT_REPLACE_REF_BASE GIT_PREFIX GIT_SHALLOW_FILE GIT_COMMON_DIR
 ROOT=$(git rev-parse --show-toplevel)
 DIRTY_FILE=$(mktemp)
 

package/gsd-core/workflows/reapply-patches.md

@@ -10,6 +10,21 @@ After a GSD update wipes and reinstalls files, this workflow merges user's previ
 
 <process>
 
+## Step 0: Parse interactive mode (#4435)
+
+Read the arguments passed after `--reapply`:
+
+- no `--interactive` → `INTERACTIVE_MODE=off` (the default; Step 4 runs exactly as before)
+- bare `--interactive` or `--interactive=exceptions` → `INTERACTIVE_MODE=exceptions`
+- `--interactive=all` → `INTERACTIVE_MODE=all`
+- any other `--interactive=<value>` → STOP with: `unknown --interactive value '<value>' (expected exceptions or all)`. Do not reapply anything.
+
+When the mode is not `off`, tell the user once, before the first prompt: on the first interactive run
+for this install, `--interactive=all` is recommended, because the recommendations have not yet been
+checked against this install's customizations.
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in the arguments OR `workflow.text_mode` is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes where `AskUserQuestion` is not available.
+
 ## Step 1: Detect backed-up patches
 
 Check for local patches directory:
@@ -250,6 +265,75 @@ merge paths below, unchanged. If the classifier cannot run at all (e.g. `GSD_HOM
 unset), fall back to merging every file as before; never report `Incorporated` without the
 classifier's structured confirmation.
 
+### Step 4 interactive review (#4435) — only when `INTERACTIVE_MODE` is not `off`
+
+Verbatim matching cannot see an edit that upstream adopted in different words, an edit whose
+surrounding stock text upstream rewrote, or an edit whose anchor lines upstream deleted. Interactive
+mode shows each user edit (hunk) and lets the USER decide. Present and gate: the tool recommends,
+the user decides, and nothing is retired without the user's answer.
+
+```bash
+DECISIONS_FILE="$(mktemp "${TMPDIR:-/tmp}/gsd-reapply-decisions.XXXXXX")"
+HUNKS_ARGS=(
+  --patches-dir "$PATCHES_DIR"
+  --config-dir  "$CONFIG_DIR"
+)
+if [ -d "$PRISTINE_DIR" ]; then
+  HUNKS_ARGS+=(--pristine-dir "$PRISTINE_DIR")
+fi
+HUNKS_ARGS+=(--hunks --json)
+
+# Informational: exits 0. Each hunk carries hunk_hash, kind, stock_lines, user_lines,
+# recommendation (keep | retire | review), reasons, and exception (true/false).
+HUNKS_OUTPUT="$(node "${GSD_HOME}/gsd-core/bin/verify-reapply-patches.cjs" "${HUNKS_ARGS[@]}")"
+```
+
+The decisions file lives in a temp directory, never inside `gsd-local-patches/`, because the
+Step 5a gate treats every file in that directory as a backed-up patch.
+
+For each file in `HUNKS_OUTPUT.files`, for each hunk:
+
+- `INTERACTIVE_MODE=all`: present EVERY hunk.
+- `INTERACTIVE_MODE=exceptions`: present only hunks with `exception: true`. Every other hunk is kept
+  without asking. Print one summary line for each:
+  `kept without review: {file} hunk {hunk_id}: "{first user line, truncated to 60 chars}"`.
+
+Presenting a hunk means asking the user one question (`AskUserQuestion`, or under TEXT_MODE a
+plain-text numbered list the user answers by number) that shows:
+
+- **Stock text:** `stock_lines` (or "(none — your lines were inserted)" when empty)
+- **Your text:** `user_lines` (or "(none — you deleted the stock text)" when empty)
+- **Recommendation:** `recommendation`, with `reasons` explained in plain words:
+  `already_upstream` (the shipped file already has it), `partially_upstream` (only some of it is
+  there), `region_changed_upstream` (upstream also changed this spot, for example by rewording it),
+  `anchor_orphaned` (the lines it sat between are gone), `baseline_unconfirmed` (no verified
+  pre-update copy, so read the whole file), `diff_too_large` (the file changed too much to split it
+  into separate edits)
+- Options: **Keep** (graft it), **Retire** (drop it; keep upstream's text), **Rewrite** (the user
+  supplies replacement text, which is applied instead)
+
+Write a decision entry only from the user's answer to that hunk's question. Never write `retire` or
+`rewrite` for a hunk the user was not asked about, and never pick an answer on the user's behalf,
+even when the recommendation is `retire`. A hunk kept without review in `exceptions` mode is
+recorded as `keep`. Record each answer in `DECISIONS_FILE` as JSON:
+
+```json
+{ "decisions": [ { "file": "<file>", "hunk_hash": "<hunk_hash>", "disposition": "keep|retire|rewrite" } ] }
+```
+
+A `rewrite` entry must also carry `"replacement_lines": [...]` — exactly the lines the user supplied.
+The Step 5a gate then requires those lines to be present in the merged file, so a rewrite is verified
+like any kept edit. `keep` and `retire` entries never carry `replacement_lines`.
+
+Shell variables do not survive between separate command invocations. Write `INTERACTIVE_MODE` and the
+`DECISIONS_FILE` path down when you set them, and set both again in the same command that runs the
+Step 5a verifier.
+
+Then merge each file with the paths below, applying only `keep` hunks and the user's replacement
+text for `rewrite` hunks. A file whose hunks were all retired is left exactly as installed and
+reported `Incorporated` ("Retired by user decision"). A file with some hunks retired is reported
+`Merged` with "{N} hunk(s) retired by user decision".
+
 For each file in `backup-meta.json`:
 
 1. **Read the backed-up version** (user's modified copy from `gsd-local-patches/`)
@@ -352,6 +436,11 @@ VERIFY_ARGS=(
 if [ -d "$PRISTINE_DIR" ]; then
   VERIFY_ARGS+=(--pristine-dir "$PRISTINE_DIR")
 fi
+# #4435: hunks the user retired or rewrote are excused only through the recorded,
+# hash-bound decisions. A decision whose hunk no longer matches exits 2 (stale).
+if [ "$INTERACTIVE_MODE" != "off" ] && [ -s "$DECISIONS_FILE" ]; then
+  VERIFY_ARGS+=(--decisions "$DECISIONS_FILE")
+fi
 VERIFY_ARGS+=(--json)
 
 # Capture stdout (the structured JSON report) separately from stderr so that
@@ -456,6 +545,18 @@ Then re-run /gsd:update --reapply to re-verify.
 
 Do not proceed to cleanup until the verifier exits 0.
 
+**If `VERIFY_STATUS` is 2 and stderr names a `stale decision`** (#4435), a recorded answer no longer
+matches its hunk because the backup or baseline changed after the user saw it. STOP, discard
+`DECISIONS_FILE`, and re-run `/gsd:update --reapply --interactive` so the user decides on the current
+text. Never edit the decisions file to make it match.
+
+When decisions were passed, the JSON report carries `decisions.retired` — every hunk excused by a
+user `retire` or `rewrite` decision. Before Step 6, show the user this list (file, hunk id,
+disposition) and ask them to confirm that each one is a decision they made. The gate can prove that a
+decision matches the exact text that was shown, but not who made it, so the user's confirmation of
+this list is the final check. If the user disowns any entry, restore that hunk from the backup and
+re-run Step 5a without it. List each confirmed entry in the Step 7 report.
+
 **Only when `VERIFY_STATUS` is 0** (or when all files had zero significant user-added lines, which the verifier reports as `Failures: 0`) may execution continue to gate 5b.
 
 ### 5b: Hunk Verification Table review (advisory gate, #1999)
@@ -493,6 +594,8 @@ Do not proceed to cleanup until both gates (5a and 5b) pass.
 
 ## Step 6: Cleanup option
 
+If `DECISIONS_FILE` was created (#4435), delete it now: `rm -f "$DECISIONS_FILE"`.
+
 Ask user:
 - "Keep patch backups for reference?" → preserve `gsd-local-patches/`
 - "Clean up patch backups?" → remove `gsd-local-patches/` directory
@@ -520,6 +623,7 @@ Ask user:
 - [ ] User modifications identified and merged into new version
 - [ ] Superseded customizations classified `Incorporated` by the deterministic pre-flight classifier (pristine-confirmed) and not re-grafted
 - [ ] Conflicts surfaced to user with both versions shown
+- [ ] With `--interactive`, every presented hunk was decided by the user (never by the agent), retired/rewritten hunks were passed to the Step 5a gate through the hash-bound decisions file, and each retirement is listed in the report
 - [ ] Status reported for each file with summary of what was preserved
 - [ ] Post-merge verification checks each file for dropped hunks and warns if content appears missing
 </success_criteria>