@opengsd/gsd-core 1.18.0 → 1.20.0

package/gsd-core/references/planning-config.md

@@ -35,6 +35,7 @@ Configuration options for `.planning/` directory behavior.
 | `git.base_branch` | `null` (auto-detect) | Target branch for PRs and merges (e.g. `"master"`, `"develop"`). When `null`, auto-detects from `git symbolic-ref refs/remotes/origin/HEAD`, falling back to `"main"`. |
 | `git.protected_branches` | (none) | Optional array of non-empty strings naming additional shared branches that should trigger protected-branch warnings |
 | `git.create_tag` | `true` | Create git tags on milestone completion |
+| `git.repo_tagging` | `"single"` | Milestone tagging mode: `"single"` (existing behavior) or `"per_repo"` (record one release per configured repository; each tag is pushed only after a per-repository confirmation) |
 | `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | Branch template for phase strategy |
 | `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | Branch template for milestone strategy |
 | `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
@@ -340,6 +341,7 @@ Set via `git.*` namespace (e.g., `"git": { "branching_strategy": "phase" }`).
 | `git.base_branch` | string\|null | `null` (auto-detect) | Any branch name | Target branch for PRs and merges; auto-detects from `origin/HEAD` when `null` |
 | `git.protected_branches` | array of non-empty strings | (none) | Non-empty branch names | Optional protected names added to the resolved base branch for execute-phase and ship warnings |
 | `git.create_tag` | boolean | `true` | `true`, `false` | Create git tags on milestone completion |
+| `git.repo_tagging` | string | `"single"` | `"single"`, `"per_repo"` | Milestone tagging mode; `"per_repo"` opts a multi-repo project into per-repository release records |
 | `git.phase_branch_template` | string | `"gsd/phase-{phase}-{slug}"` | Template with `{phase}`, `{slug}` | Branch naming template for `phase` strategy |
 | `git.milestone_branch_template` | string | `"gsd/{milestone}-{slug}"` | Template with `{milestone}`, `{slug}` | Branch naming template for `milestone` strategy |
 | `git.quick_branch_template` | string\|null | `null` | Template with `{slug}` | Optional branch template for quick-task runs |

package/gsd-core/references/tdd.md

@@ -316,7 +316,7 @@ git log --oneline -E --grep="^feat\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 git log --oneline -E --grep="^refactor\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 ```
 
-If RED or GREEN gate commits are missing, add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.
+If RED or GREEN gate commits are missing, or no GREEN commit follows a RED commit (#5275), add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.
 </gate_enforcement>
 
 <end_of_phase_review>
@@ -342,7 +342,7 @@ TDD Plans: {count} | Gate violations: {count}
 
 ### What the Review Checks
 
-1. **Gate sequence:** Each TDD plan has RED → GREEN commits in order. A plan is scored on its own `test(<plan>):` / `feat(<plan>):` commits, with one exception (#4867): a RED-only probe plan is satisfied by a `feat(...)` commit under a plan that declares it in `depends_on`, directly or through a chain. That is the gap-closure shape (probe plan, then the fix plan that depends on it). The plan's own RED is still required, a plan nothing depends on is scored alone, and the report names the plan that supplied the GREEN (`Plan {id} GREEN is supplied by dependent plan {id}.`).
+1. **Gate sequence:** Each TDD plan has RED → GREEN commits in order (#5275). Order is commit ancestry, not log position or commit date: a GREEN counts only when it descends from a RED commit of the plan, so a history merged from worktree branches is judged by what each commit descends from. A plan with both commit kinds but no GREEN after a RED fails with `reason: green_before_red` and the line `Plan {id} GREEN precedes RED: no feat(...) commit descends from a test(...) commit.`, distinct from the `missing` row for a plan without a RED or GREEN commit. If git cannot answer the ancestry question, the GREEN keeps its credit rather than becoming a violation. A plan is scored on its own `test(<plan>):` / `feat(<plan>):` commits, with one exception (#4867): a RED-only probe plan is satisfied by a `feat(...)` commit under a plan that declares it in `depends_on`, directly or through a chain. That is the gap-closure shape (probe plan, then the fix plan that depends on it). The plan's own RED is still required, a plan nothing depends on is scored alone, and the report names the plan that supplied the GREEN (`Plan {id} GREEN is supplied by dependent plan {id}.`).
 2. **Test quality:** RED phase tests fail for the right reason (not import errors or syntax)
 3. **Minimal GREEN:** Implementation is minimal — no premature optimization in GREEN phase
 4. **Refactor discipline:** If REFACTOR commit exists, tests still pass

package/gsd-core/templates/DEBUG.md

@@ -25,6 +25,17 @@ bug_class: null  <!-- assigned at Phase 1.75 — bohrbug|heisenbug-mandelbug|con
 reasoning_checkpoint: null  <!-- populated before every fix attempt — see structured_returns -->
 tdd_checkpoint: null  <!-- populated when tdd_mode is active after root cause confirmed -->
 
+## Session Loop
+<!-- Read and written only by the checkpoint loop that drives gsd-debugger (on Pi, the top-level session); gsd-debugger never edits it. OVERWRITE on each dispatch and each wait -->
+
+goal: find_and_fix | find_root_cause_only
+tdd_mode: false
+tdd_phase: none | green
+resume_count: 0
+awaiting: none | [header of the return whose question is open]
+question: none | [checkpoint type and the full question text shown to the user]
+last_next_action: [next_action seen before the last re-dispatch]
+
 ## Symptoms
 <!-- Written during gathering, then immutable -->
 
@@ -78,6 +89,11 @@ files_changed: []
 - `reasoning_checkpoint`: OVERWRITE before every fix_and_verify — seven-field structured reasoning record (hypothesis, confirming_evidence, falsification_test, fix_rationale, blind_spots, candidate_causes, and_gate) — see `gsd-debugger.md` Structured Reasoning Checkpoint
 - `tdd_checkpoint`: OVERWRITE during TDD red/green phases — test file, name, status, failure output
 
+**Session Loop:**
+- Owned by the checkpoint loop that drives `gsd-debugger`; on Pi that loop is the top-level session, which holds no state in memory between turns (#5638)
+- OVERWRITE on each dispatch and each wait; the debugger never edits it and `## Current Focus` rewrites never touch it
+- Fields: goal, tdd_mode, tdd_phase, resume_count, awaiting, question, last_next_action
+
 **Symptoms:**
 - Written during initial gathering phase
 - IMMUTABLE after gathering complete

package/gsd-core/templates/config.json

@@ -30,7 +30,8 @@
     "sub_repos": []
   },
   "git": {
-    "create_tag": true
+    "create_tag": true,
+    "repo_tagging": "single"
   },
   "parallelization": {
     "enabled": true,

package/gsd-core/templates/verification-report.md

@@ -16,7 +16,7 @@ covered_files: # #4155 — see agents/gsd-verifier.md's "Create VERIFICATION.md"
   - .planning/phases/XX-name/{phase_num}-{plan}-PLAN.md
   - .planning/phases/XX-name/{phase_num}-{plan}-SUMMARY.md
   - src/{changed-file}.cts
-covered_digest: "v3:sha256:{digest from verification.fingerprint}"
+covered_digest: "v4:sha256:{digest from verification.fingerprint}"
 behavior_unverified: 0 # Count of ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (present + wired, behavior not exercised)
 behavior_unverified_items: # Only if behavior_unverified > 0 — the truths above as structured items; emitted regardless of overall status
   - truth: "Observable truth whose state transition or cancellation/cleanup/ordering invariant no test exercises"

package/gsd-core/workflows/audit-fix.md

@@ -128,7 +128,8 @@ if [ -z "$AUDIT_TEST_CMD" ]; then
   elif [ -f "Justfile" ] || [ -f "justfile" ]; then
     AUDIT_TEST_CMD="just test"
   elif [ -f "package.json" ]; then
-    AUDIT_TEST_CMD="npm test"
+    AUDIT_TEST_CMD=$(gsd_run query resolve-package-manager test --cwd . 2>/dev/null || echo "npm test")
+    [ -n "$AUDIT_TEST_CMD" ] || AUDIT_TEST_CMD="npm test"
   elif [ -f "Cargo.toml" ]; then
     AUDIT_TEST_CMD="cargo test"
   elif [ -f "go.mod" ]; then

package/gsd-core/workflows/code-review/steps/structural-pre-pass.md

@@ -2,8 +2,17 @@ When `FALLOW_ENABLED=true`:
 
 1) Resolve binary via `node_modules/.bin/fallow` first, then PATH.
 ```bash
+# gsd-resolve-lib begin fallow-runner.cjs (#5640): load helpers from the installed runtime, not the cwd
+_gsd_lib_probe="fallow-runner.cjs"
+_gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+GSD_LIB_DIR=""
+_gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+_gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: fallow-runner.cjs not found in the GSD runtime. Looked in: ${GSD_TOOLS:+${GSD_TOOLS%/*}/lib, }${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib. Reinstall: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+export GSD_LIB_DIR
+# gsd-resolve-lib end
 FALLOW_BIN=$(FALLOW_CWD="$(pwd)" node -e "
-const { resolveFallowBinary } = require('./gsd-core/bin/lib/fallow-runner.cjs');
+const { resolveFallowBinary } = require(require('path').join(process.env.GSD_LIB_DIR, 'fallow-runner.cjs'));
 const resolved = resolveFallowBinary({ cwd: process.env.FALLOW_CWD });
 if (resolved) process.stdout.write(resolved);
 ")

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

@@ -32,8 +32,20 @@ PHASE_ARG="${1}"
 # logic (e.g., --all and --auto imply --fix). Resolved BEFORE the init call below so
 # the section-manifest gate forwards the RESOLVED (post-implication) fix decision, not
 # just a literal --fix token check.
+# gsd-resolve-lib begin code-review-flags.cjs (#5640): load helpers from the installed runtime, not the cwd
+_gsd_lib_probe="code-review-flags.cjs"
+_gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+_gsd_gr="$(command -v gsd_run 2>/dev/null || true)"
+case "$_gsd_gr" in /*) ;; *) _gsd_gr="" ;; esac # a gsd_run shell function prints its bare name: not a path
+[ -n "$_gsd_gr" ] && _gsd_gr="$(dirname "$(node -p "require('fs').realpathSync(process.argv[1])" "$_gsd_gr" 2>/dev/null || echo "$_gsd_gr")")/lib"
+GSD_LIB_DIR=""
+_gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+_gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "$_gsd_gr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: code-review-flags.cjs not found in the GSD runtime. Looked in: ${GSD_TOOLS:+${GSD_TOOLS%/*}/lib, }${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${_gsd_gr:-next to gsd_run (not on PATH)}, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib. Reinstall: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+export GSD_LIB_DIR
+# gsd-resolve-lib end
 FLAGS_JSON=$(node -e "
-  const { parseCodeReviewFlags } = require('./gsd-core/bin/lib/code-review-flags.cjs');
+  const { parseCodeReviewFlags } = require(require('path').join(process.env.GSD_LIB_DIR, 'code-review-flags.cjs'));
   const flags = parseCodeReviewFlags(process.argv.slice(1));
   process.stdout.write(JSON.stringify(flags));
 " -- "$@" 2>/dev/null)
@@ -125,12 +137,25 @@ If FILES_OVERRIDE is set (from --files flag):
 ```bash
 if [ -n "$FILES_OVERRIDE" ]; then
   REVIEW_FILES=()
-  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+  # #5519: compare the repository root and each resolved path in ONE form. On Windows Git Bash,
+  # `git rev-parse --show-toplevel` (a native program) reports a mixed path (C:/Users/..) while
+  # GNU `realpath` reports an MSYS POSIX path (/c/Users/..); the two never share a prefix, so
+  # every entry looked "outside". `cygpath -m` exists exactly where the forms differ and maps both
+  # to the mixed form; elsewhere the value passes through unchanged.
+  _gsd_norm_path() {
+    if command -v cygpath >/dev/null 2>&1; then cygpath -m "$1"; else printf '%s' "$1"; fi
+  }
+  REPO_ROOT=$(_gsd_norm_path "$(git rev-parse --show-toplevel 2>/dev/null)")
   
   for file_path in "${FILES_ARRAY[@]}"; do
-    # Security: validate path is within repository (prevent path traversal)
-    ABS_PATH=$(realpath -m "${file_path}" 2>/dev/null || echo "${file_path}")
-    if [[ "$ABS_PATH" != "$REPO_ROOT"* ]]; then
+    # Security: validate path is within repository (prevent path traversal). Compare on a path
+    # boundary: the root itself or anything under "<root>/" — a sibling such as "<root>-other"
+    # shares the prefix but is not inside.
+    ABS_PATH=$(_gsd_norm_path "$(realpath -m "${file_path}" 2>/dev/null || echo "${file_path}")")
+    # Fail closed on two shapes that cannot be trusted: an empty root (git failed, so nothing can be
+    # "inside" it) and a path that still holds ".." segments (a resolved path never does, so it was
+    # not resolved — no GNU realpath).
+    if [ -z "$REPO_ROOT" ] || [[ "$ABS_PATH" == */../* || "$ABS_PATH" == */.. ]] || [[ "$ABS_PATH" != "$REPO_ROOT" && "$ABS_PATH" != "$REPO_ROOT"/* ]]; then
       echo "Error: File path outside repository, skipping: ${file_path}"
       continue
     fi
@@ -437,8 +462,20 @@ DEPTH_PAYLOAD=$(printf '%s\n' "${REVIEW_FILES[@]}" | FLAG_DEPTH="$DEPTH_OVERRIDE
   }));
 ")
 
+# gsd-resolve-lib begin code-review-depth.cjs (#5640): load helpers from the installed runtime, not the cwd
+_gsd_lib_probe="code-review-depth.cjs"
+_gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+_gsd_gr="$(command -v gsd_run 2>/dev/null || true)"
+case "$_gsd_gr" in /*) ;; *) _gsd_gr="" ;; esac # a gsd_run shell function prints its bare name: not a path
+[ -n "$_gsd_gr" ] && _gsd_gr="$(dirname "$(node -p "require('fs').realpathSync(process.argv[1])" "$_gsd_gr" 2>/dev/null || echo "$_gsd_gr")")/lib"
+GSD_LIB_DIR=""
+_gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+_gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "$_gsd_gr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: code-review-depth.cjs not found in the GSD runtime. Looked in: ${GSD_TOOLS:+${GSD_TOOLS%/*}/lib, }${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${_gsd_gr:-next to gsd_run (not on PATH)}, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib. Reinstall: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+export GSD_LIB_DIR
+# gsd-resolve-lib end
 DEPTH_JSON=$(echo "$DEPTH_PAYLOAD" | node -e "
-  const { resolveCodeReviewDepth } = require('./gsd-core/bin/lib/code-review-depth.cjs');
+  const { resolveCodeReviewDepth } = require(require('path').join(process.env.GSD_LIB_DIR, 'code-review-depth.cjs'));
   const input = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf-8'));
   process.stdout.write(JSON.stringify(resolveCodeReviewDepth(input)));
 ")
@@ -737,9 +774,21 @@ if [ -n "$FALLOW_JSON_PATH" ] && [ -f "$FALLOW_JSON_PATH" ]; then
   # Normalize fallow's raw report into the compact {summary, findings[]} contract
   # the reviewer consumes (real fallow schema -> normalized findings).
   FALLOW_NORMALIZED_PATH="${PHASE_DIR}/FALLOW-normalized.json"
+  # gsd-resolve-lib begin fallow-runner.cjs (#5640): load helpers from the installed runtime, not the cwd
+  _gsd_lib_probe="fallow-runner.cjs"
+  _gsd_rt="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  _gsd_gr="$(command -v gsd_run 2>/dev/null || true)"
+  case "$_gsd_gr" in /*) ;; *) _gsd_gr="" ;; esac # a gsd_run shell function prints its bare name: not a path
+  [ -n "$_gsd_gr" ] && _gsd_gr="$(dirname "$(node -p "require('fs').realpathSync(process.argv[1])" "$_gsd_gr" 2>/dev/null || echo "$_gsd_gr")")/lib"
+  GSD_LIB_DIR=""
+  _gsd_pick() { for _gsd_d; do if [ -n "$_gsd_d" ] && [ -f "$_gsd_d/$_gsd_lib_probe" ]; then GSD_LIB_DIR="$_gsd_d"; return 0; fi; done; return 1; }
+  _gsd_pick "${GSD_TOOLS:+${GSD_TOOLS%/*}/lib}" "$_gsd_rt/gsd-core/bin/lib" "$_gsd_rt/.claude/gsd-core/bin/lib" "$_gsd_rt/.codex/gsd-core/bin/lib" "$_gsd_gr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib" || true
+  if [ -z "$GSD_LIB_DIR" ]; then echo "ERROR: fallow-runner.cjs not found in the GSD runtime (looked in ${_gsd_rt}/gsd-core/bin/lib (and its .claude and .codex forms), ${_gsd_gr:-next to gsd_run (not on PATH)}, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/lib, ${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/lib); continuing without it." >&2; fi
+  export GSD_LIB_DIR
+  # gsd-resolve-lib end
   FALLOW_SRC="$FALLOW_JSON_PATH" FALLOW_OUT="$FALLOW_NORMALIZED_PATH" node -e "
     const fs = require('fs');
-    const { normalizeFallowReportFile } = require('./gsd-core/bin/lib/fallow-runner.cjs');
+    const { normalizeFallowReportFile } = require(require('path').join(process.env.GSD_LIB_DIR, 'fallow-runner.cjs'));
     const n = normalizeFallowReportFile(process.env.FALLOW_SRC);
     fs.writeFileSync(process.env.FALLOW_OUT, JSON.stringify(n, null, 2));
   " 2>/dev/null && FALLOW_EMBED_PATH="$FALLOW_NORMALIZED_PATH" || FALLOW_EMBED_PATH="$FALLOW_JSON_PATH"
@@ -883,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:
@@ -901,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}
@@ -943,6 +995,11 @@ grep -A 3 "^### CR-\|^### BL-\|^### WR-" "${REVIEW_PATH}" | head -n 12
 **Windows:** This workflow uses bash features (arrays, process substitution). On Windows, it requires
 Git Bash or WSL. Native PowerShell is not supported. The CI matrix (Ubuntu/macOS/Windows)
 runs under Git Bash on Windows runners, which provides bash compatibility.
+The `--files` containment check compares the repository root with each resolved path, and Git Bash
+reports them in different forms (`git rev-parse` returns `C:/Users/...`, GNU `realpath` returns
+`/c/Users/...`), so both are normalized with `cygpath -m` (shipped with Git Bash) before the
+comparison. Relative paths and absolute paths in either form are accepted when they are inside the
+repository (#5519).
 
 **macOS:** macOS ships with bash 3.2 (GPL licensing). This workflow does NOT use `mapfile` (bash 4+
 only) — all array construction uses portable `while IFS= read -r` loops compatible with bash 3.2.

package/gsd-core/workflows/complete-milestone/steps/project-md-evolution-review.md

@@ -0,0 +1,145 @@
+<step name="evolve_project_full_review">
+
+Full PROJECT.md evolution review at milestone completion.
+
+Read all phase summaries:
+
+```bash
+_SUMMARIES=( .planning/phases/*-*/*-SUMMARY.md )
+if [ -e "${_SUMMARIES[0]}" ]; then cat "${_SUMMARIES[@]}"; fi
+```
+
+**Full review checklist:**
+
+1. **"What This Is" accuracy:**
+   - Compare current description to what was built
+   - Update if product has meaningfully changed
+
+2. **Core Value check:**
+   - Still the right priority? Did shipping reveal a different core value?
+   - Update if the ONE thing has shifted
+
+3. **Business Context check (only if the section is present):**
+   - Skip entirely if PROJECT.md has no `## Business Context` section
+   - Customer, revenue model, and success metric still accurate after shipping?
+   - Update any field that drifted; refresh the linked strategy doc reference if it moved
+
+4. **Requirements audit:**
+
+   **Validated section:**
+   - All Active requirements shipped this milestone → Move to Validated
+   - Format: `- ✓ [Requirement] — v[X.Y]`
+
+   **Active section:**
+   - Remove requirements moved to Validated
+   - Add new requirements for next milestone
+   - Keep unaddressed requirements
+
+   **Out of Scope audit:**
+   - Review each item — reasoning still valid?
+   - Remove irrelevant items
+   - Add requirements invalidated during milestone
+
+5. **Context update:**
+   - Current codebase state (LOC, tech stack)
+   - User feedback themes (if any)
+   - Known issues or technical debt
+
+6. **Key Decisions audit:**
+   - Extract all decisions from milestone phase summaries
+   - Add to Key Decisions table with outcomes
+   - Mark ✓ Good, ⚠️ Revisit, or — Pending
+
+7. **Constraints check:**
+   - Any constraints changed during development? Update as needed
+
+Update PROJECT.md inline. Update "Last updated" footer:
+
+```markdown
+---
+*Last updated: [date] after v[X.Y] milestone*
+```
+
+**Example full evolution (v1.0 → v1.1 prep):**
+
+Before:
+
+```markdown
+## What This Is
+
+A real-time collaborative whiteboard for remote teams.
+
+## Core Value
+
+Real-time sync that feels instant.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] Canvas drawing tools
+- [ ] Real-time sync < 500ms
+- [ ] User authentication
+- [ ] Export to PNG
+
+### Out of Scope
+
+- Mobile app — web-first approach
+- Video chat — use external tools
+```
+
+After v1.0:
+
+```markdown
+## What This Is
+
+A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.
+
+## Core Value
+
+Real-time sync that feels instant.
+
+## Requirements
+
+### Validated
+
+- ✓ Canvas drawing tools — v1.0
+- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
+- ✓ User authentication — v1.0
+
+### Active
+
+- [ ] Export to PNG
+- [ ] Undo/redo history
+- [ ] Shape tools (rectangles, circles)
+
+### Out of Scope
+
+- Mobile app — web-first approach, PWA works well
+- Video chat — use external tools
+- Offline mode — real-time is core value
+
+## Context
+
+Shipped v1.0 with 2,400 LOC TypeScript.
+Tech stack: Next.js, Supabase, Canvas API.
+Initial user testing showed demand for shape tools.
+```
+
+**Step complete when:**
+
+- [ ] "What This Is" reviewed and updated if needed
+- [ ] Core Value verified as still correct
+- [ ] Business Context checked (or confirmed absent)
+- [ ] All shipped requirements moved to Validated
+- [ ] New requirements added to Active for next milestone
+- [ ] Out of Scope reasoning audited
+- [ ] Context updated with current state
+- [ ] All milestone decisions added to Key Decisions
+- [ ] "Last updated" footer reflects milestone completion
+
+</step>

package/gsd-core/workflows/complete-milestone/steps/release-map.md

@@ -0,0 +1,80 @@
+<step name="release_map">
+
+Per-repository release mapping (#3628, ADR-3628). Runs only when the init JSON has `repo_tagging` set to `per_repo` AND a non-empty `sub_repos` list. A GSD milestone version names planned work; each repository has its own release version, so no `v[X.Y]` tag is created in the current directory on this path.
+
+This file is read twice: Part 1 from `archive_milestone`, Part 2 from `push_release_tags`.
+
+Text mode: when `TEXT_MODE` is active, replace every `AskUserQuestion` with a numbered plain-text list.
+
+Working directory for the two JSON files: `RELEASE_MAP_DIR="${TMPDIR:-/tmp}/gsd-release-map-v[X.Y]"`, created with `mkdir -p "$RELEASE_MAP_DIR"`; the map file is `"$RELEASE_MAP_DIR/release-map.json"`. Shell state does not persist between commands, so re-derive these paths in every command that uses them. Write both JSON files with the Write tool; never build them with `echo`, a heredoc or any shell interpolation of the answers.
+
+## Part 1 — Collect, preflight, confirm, tag (runs inside `archive_milestone`, before `milestone complete`)
+
+1. **Collect one entry per repository in `sub_repos`.** For each repository ask for:
+   - `status`: `released`, `deployed`, or `unreleased`.
+   - `release`: the repository's release version. When a tag is created it becomes the tag name, so it must match `^[A-Za-z0-9][A-Za-z0-9._+-]{0,199}$`; re-ask on a mismatch, never alter or skip it. Leave it empty for an `unreleased` repository and never invent one.
+   - `reference`: a commit SHA or pull request reference (free text).
+   - `environment`: free text, for example `production`, `npm`, `development`.
+   - tag choice: `create` (create an annotated tag named `release`; requires a non-empty `release`) or `skip` (record the repository, create nothing). An `unreleased` repository defaults to `skip`.
+
+   Every text field is limited to 200 characters and a map to 256 entries; re-ask when a value is longer. If `git_create_tag` from init is `false`, do not ask the tag choice: every entry is recorded with a `tag` of `none`, no `tags.json` is built, and steps 3, 5 and 6 are skipped (the tag verb and the tag-state update); step 4 asks "Record this release map?" instead. Part 2 does not run.
+
+2. **Build `release-map.json`** (array of `{ "repo", "release", "reference", "environment", "status", "tag" }`) with provisional tag states: `created` for a `create` entry, `skipped` for a `skip` entry, `none` when tagging is disabled. When tags are requested, also build `tags.json` in the same directory: `{ "repo": "<repo>", "tag": "<release>", "ref": "<ref>" }` for each `create` entry and `{ "repo": "<repo>", "skip": true }` for each `skip` entry. `ref` is the entry's `reference`, lowercased, only when it matches `^[0-9a-f]{7,40}$`; any other reference text (for example `PR #412`) is recorded but the tag is placed on the repository's current `HEAD`.
+
+3. **Validate everything before anything is written:**
+
+   ```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; _gsd_id_ok() { case "$("$1" runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') return 0;; *) return 1;; esac; }; _gsd_homes() { set -- "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}" "$HOME/.gemini/antigravity-ide" "$HOME/.gemini/antigravity-cli" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}" "${CLINE_CONFIG_DIR:-$HOME/.cline}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}" "${CODEX_HOME:-$HOME/.codex}" "${COPILOT_CONFIG_DIR:-${COPILOT_HOME:-$HOME/.copilot}}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}" "${HERMES_HOME:-$HOME/.hermes}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}" "${KIMI_CONFIG_DIR:-$HOME/.config/agents}" "$HOME/.agents" "${KIMI_CODE_HOME:-$HOME/.kimi-code}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}" "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}" "${TRAE_CONFIG_DIR:-$HOME/.trae}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}" "${ZCODE_CONFIG_DIR:-$HOME/.zcode}" "${GROK_AGENTS_HOME:-$HOME/.agents}"; for _h; do _gsd_at "$_h/gsd-core/bin/${_GSD_SHIM_NAME}" && return 0; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif _gsd_homes; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; [ -n "$_G" ] && _gsd_id_ok "$_G"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and no identity-proving gsd_run is on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; _gsd_id_ok gsd_run && GSD_IDENTITY_STATUS=ok; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+   gsd_run query milestone release-tags --map "$RELEASE_MAP_DIR/tags.json" --dry-run
+   gsd_run query milestone.complete "v[X.Y]" --dry-run --release-map "$RELEASE_MAP_DIR/release-map.json"
+   ```
+
+   If the first reports `ok: false`, show each error with its repository and `reason`; a `tag_conflict` means the tag already exists at a different commit and is never overwritten. If the second fails, it lists every release map problem. Let the user correct the entries or abort, and repeat. Do not continue while either check fails.
+
+4. **One consolidated confirmation.** Show a single table and ask once (AskUserQuestion: "Create these tags? Nothing is pushed." — Create / Edit / Cancel). Include the commit each tag will be placed on (`commit`, shortened, from the dry-run result) and say so when the tag lands on the repository's current `HEAD` rather than a given SHA or when the result reports `detached_head`:
+
+   ```text
+   Milestone v[X.Y] — [Name]
+
+   Repository  Release     Reference   Environment  Tag     Commit
+   dashboard   v5.78.0     PR #412     production   create  HEAD (a1b2c3d)
+   composers   unreleased  abc1234     development  skip    —
+   ```
+
+   On Cancel, stop: nothing has been written and `milestone complete` is not called.
+
+5. **Create the tags:**
+
+   ```bash
+   gsd_run query milestone release-tags --map "$RELEASE_MAP_DIR/tags.json"
+   ```
+
+   If the command exits non-zero, report every repository's status and the `created` list (`repo:tag` pairs already written). Stop before `milestone complete`; running the same command again is safe, it retries only what failed and reports tags already written as `already_tagged`. Tags are placed on commits that already exist in each repository, so merge or squash a repository's release branch before running this flow if the tag must sit on the merged commit.
+
+6. **Record the outcome in the map.** Rewrite `release-map.json` so each `create` entry's `tag` is that repository's `status` from the result (`created` or `already_tagged`); leave `skipped` and `none` as they are. Valid `status` values are `released`, `deployed`, `unreleased`; valid `tag` values are `created`, `already_tagged`, `skipped`, `none`.
+
+7. **Archive the map with the milestone** by adding `--release-map "$RELEASE_MAP_DIR/release-map.json"` to every `milestone complete` call in `archive_milestone`. The map is stored as recorded, whether or not any tag was created.
+
+## Part 2 — Push confirmation (runs after the archive, in place of the single-repository push prompt)
+
+Nothing is pushed by default. For each repository whose entry has `tag` of `created` or `already_tagged`, one at a time. Take `REPO`, `REMOTE` and `TAG` only from the validated release map and the repository's own `git remote` list, and write them into the commands below as single-quoted literals.
+
+Choose the remote: `origin` when `git -C "$REPO" remote` lists it; when there are several remotes and none is `origin`, show the list and ask which one; when there is none, report that and move on. Then show where the push would go (the push URL, with any embedded credentials removed before it is shown):
+
+```bash
+git -C "$REPO" remote get-url --push "$REMOTE"
+```
+
+Ask a separate question naming the repository, the tag, the remote and that URL:
+
+`Push tag <tag> from <repo> to remote <remote> (<url>)? (y/n)`
+
+Only on `y`, push that one tag, with `GIT_TERMINAL_PROMPT=0` exported:
+
+```bash
+git -C "$REPO" push -- "$REMOTE" "refs/tags/$TAG"
+```
+
+A decline, a failed push, or a push that does not finish is reported for that repository only; continue with the next repository. Never push branches, never push several tags in one command, and never push without the answer for that repository.
+
+</step>