@zigrivers/scaffold 3.27.0 → 3.28.0

package/content/tools/review-code.md

@@ -133,7 +133,7 @@ echo "$AGENT_FINDINGS" > /tmp/agent-findings.json
 mmr reconcile "$JOB_ID" --channel superpowers --input /tmp/agent-findings.json
 ```
 
-The agent's review output must use MMR-compatible finding schema: each finding needs `severity` (P0-P3), `location` (file:line), and `description` (`suggestion` is optional).
+The agent's review output must use MMR-compatible finding schema: each finding needs `severity` (P0-P3), `category` (correctness, edge-case, security, acceptance-criteria, test-coverage, or another stable category), `location` (file:line), and `description` (`suggestion` is optional).
 
 If `mmr` is not installed (`command -v mmr` fails), fall back to the manual multi-channel flow below.
 
@@ -363,7 +363,8 @@ Respond with JSON:
   "findings": [
     {
       "severity": "P0" | "P1" | "P2" | "P3",
-      "location": "file:line or section",
+      "category": "correctness|edge-case|security|acceptance-criteria|test-coverage",
+      "location": "relative/path/to/file.ts:42",
       "description": "what is wrong",
       "suggestion": "specific fix"
     }
@@ -397,10 +398,352 @@ Otherwise:
 1. Fix all findings at or above `fix_threshold` (read from `results.fix_threshold` in the verdict JSON; default `P2`)
 2. Re-run the channels that produced findings
 3. Keep iterating as long as each new round surfaces *different, concrete, fixable* findings — that is healthy review/fix iteration, not a stuck loop
-4. The 3-round limit is **per finding**: stop and surface to the user when the *same* blocking finding (or set) recurs across 3 attempts without progress. Other stop conditions: a finding is genuinely ambiguous (channels contradict each other), or the user explicitly asks to stop. Use verdict `needs-user-decision` for ambiguity, `blocked` for stuck-loop cases.
+4. The 3-round limit is **per finding hash**, enforced by the wrapper-side bookkeeping in Step 7a (`.scaffold/review-attempts/<session-id>.json`). Stop and surface to the user when any blocking finding's hash hits 3 attempts (`_review_at_strike_limit` returns true). Other stop conditions: a finding is genuinely ambiguous (channels contradict each other), or the user explicitly asks to stop. Use verdict `needs-user-decision` for ambiguity, `blocked` for stuck-hash cases. Identity components — `location`, `category`, `description`, `suggestion` — mirror MMR T2-A's forthcoming native `finding_key` (v3.30).
 
 **Fix cycle channel rule:** Re-run only channels that originally completed or ran as compensating passes. Never retry a channel marked `not_installed`, `auth_failed`, or `timeout` during fix rounds — its availability does not change within a session.
 
+### Step 7a: Wrapper-Side Per-Finding Hash (Stopgap until MMR v3.30)
+
+Same wrapper-side bookkeeping as `review-pr.md` Step 7a. Local review reuses
+the helper semantics, with local-session derivation (no PR number) and the
+portable hardening noted below.
+
+This section is throwaway — when MMR v3.30 lands, replace this entire block
+with `mmr review --session <id> --max-rounds N` and read `finding_key` from
+the verdict JSON directly.
+
+#### Session id (review-code variant)
+
+```bash
+_review_session_id() {
+  _review_sanitize_session_id() {
+    local raw="$1" sanitized
+    sanitized=$(printf '%s' "$raw" | tr -c 'a-zA-Z0-9_.-' '_')
+    if [ -z "$sanitized" ] || [ "$sanitized" = "." ] || [ "$sanitized" = ".." ]; then
+      echo "Error: review session id resolves to an unsafe path segment" >&2
+      return 1
+    fi
+    printf '%s' "$sanitized"
+  }
+
+  if [ -n "${REVIEW_SESSION_ID:-}" ]; then
+    _review_sanitize_session_id "$REVIEW_SESSION_ID" || return 1
+    return
+  fi
+  if [ -n "${__REVIEW_SESSION_ID:-}" ]; then
+    _review_sanitize_session_id "$__REVIEW_SESSION_ID" || return 1
+    return
+  fi
+  local branch base
+  branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+  base="${BASE_REF:-main}"
+  if [ -n "$branch" ] && [ "$branch" != "HEAD" ]; then
+    __REVIEW_SESSION_ID=$(_review_sanitize_session_id "$branch@$base") || return 1
+    printf '%s' "$__REVIEW_SESSION_ID"
+    return
+  fi
+  local commit
+  commit=$(git rev-parse --short HEAD 2>/dev/null || echo "")
+  if [ -n "$commit" ]; then
+    __REVIEW_SESSION_ID=$(_review_sanitize_session_id "commit-$commit") || return 1
+    printf '%s' "$__REVIEW_SESSION_ID"
+    return
+  fi
+  __REVIEW_SESSION_ID=$(_review_sanitize_session_id "ts-$(date -u +%Y-%m-%dT%H:%M:%SZ)") || return 1
+  printf '%s' "$__REVIEW_SESSION_ID"
+}
+
+_review_attempts_file() {
+  local id; id=$(_review_session_id) || return 1
+  mkdir -p .scaffold/review-attempts || return 1
+  printf '.scaffold/review-attempts/%s.json' "$id"
+}
+```
+
+#### Normalization, hashing, shingle, and attempt-recording helpers
+
+The functions `_review_normalize_location`, `_review_normalize_description`,
+`_review_normalize_suggestion`, `_review_finding_hash`,
+`_review_description_shingle`, `_review_record_attempt`, and
+`_review_at_strike_limit` match the semantics of the ones defined in
+`content/tools/review-pr.md` Step 7a. They are reproduced here so this file is
+self-contained:
+
+They are intentionally reproduced in this tool file instead of sourced from a
+shared script because agent-facing tool markdown must be self-contained until
+MMR v3.30 provides native `finding_key` and session tracking.
+
+The local-review variant also makes dependency checks explicit, preserves
+backtick code spans in suggestions, and keeps short-description shingles useful
+with shorter n-grams.
+
+```bash
+_review_require_jq() {
+  command -v jq >/dev/null 2>&1 || {
+    echo "Error: jq is required for review finding bookkeeping" >&2
+    return 1
+  }
+}
+
+_review_require_python3() {
+  command -v python3 >/dev/null 2>&1 || {
+    echo "Error: python3 is required for review finding normalization" >&2
+    return 1
+  }
+}
+
+_review_sha1() {
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 1 | awk '{print $1}'
+  elif command -v sha1sum >/dev/null 2>&1; then
+    sha1sum | awk '{print $1}'
+  else
+    echo "Error: shasum or sha1sum is required for review finding hashing" >&2
+    return 1
+  fi
+}
+
+_review_normalize_location() {
+  # Input: $1 = raw location (e.g. "src/foo.ts:42-44" or "pkg/Bar.kt (line 10)")
+  # Output: lowercased file path with trailing :N, :N-M, :N:M, (line N) stripped
+  printf '%s' "$1" \
+    | tr '[:upper:]' '[:lower:]' \
+    | awk '{ sub(/^[ \t]+/, ""); sub(/[ \t]+$/, ""); print }' \
+    | sed -E 's/(:[0-9]+(:[0-9]+)?(-[0-9]+)?|[[:space:]]+\(line[[:space:]]+[0-9]+\))$//'
+}
+
+_review_normalize_description() {
+  # Input: $1 = raw description
+  # Output: tokenize on backticks → normalize non-code segments → reassemble
+  _review_require_python3 || return 1
+  printf '%s' "$1" | python3 -c '
+import re, sys
+s = sys.stdin.read()
+out = []
+pattern = re.compile(r"(```[\s\S]*?```|`[^`]*`)")
+pos = 0
+for match in pattern.finditer(s):
+    seg = s[pos:match.start()]
+    seg = seg.lower()
+    seg = re.sub(r"\bline\s+\d+\b", "", seg)
+    seg = re.sub(r"\bat\s+line\s+\d+\b", "", seg)
+    seg = re.sub(r"^\s*(p[0-3]|critical|high|medium|low|trivial)\s*:\s*", "", seg)
+    seg = re.sub(r"\s+", " ", seg).strip()
+    if seg:
+        out.append(seg)
+    out.append(match.group(0))
+    pos = match.end()
+seg = s[pos:]
+seg = seg.lower()
+seg = re.sub(r"\bline\s+\d+\b", "", seg)
+seg = re.sub(r"\bat\s+line\s+\d+\b", "", seg)
+seg = re.sub(r"^\s*(p[0-3]|critical|high|medium|low|trivial)\s*:\s*", "", seg)
+seg = re.sub(r"\s+", " ", seg).strip()
+if seg:
+    out.append(seg)
+print(" ".join(p for p in out if p))
+'
+}
+
+_review_normalize_suggestion() {
+  _review_require_python3 || return 1
+  printf '%s' "$1" | python3 -c '
+import re, sys
+s = sys.stdin.read()
+out = []
+pattern = re.compile(r"(```[\s\S]*?```|`[^`]*`)")
+pos = 0
+for match in pattern.finditer(s):
+    seg = re.sub(r"\s+", " ", s[pos:match.start()].lower()).strip()
+    if seg:
+        out.append(seg)
+    out.append(match.group(0))
+    pos = match.end()
+seg = re.sub(r"\s+", " ", s[pos:].lower()).strip()
+if seg:
+    out.append(seg)
+print(" ".join(p for p in out if p))
+'
+}
+
+_review_finding_hash() {
+  # Input: $1 = single-finding JSON object (with location, category, description, suggestion fields)
+  # Output: 40-char sha1 hex of normalized_location + "|" + category + "|" + sha1(description_normalized) + "|" + sha1(suggestion_normalized)
+  _review_require_jq || return 1
+  local f="$1"
+  local loc cat desc sugg
+  loc=$(printf '%s' "$f"  | jq -r '.location // ""')
+  cat=$(printf '%s' "$f"  | jq -r '.category // ""')
+  desc=$(printf '%s' "$f" | jq -r '.description // ""')
+  sugg=$(printf '%s' "$f" | jq -r '.suggestion // ""')
+
+  local nloc ndesc nsugg dhash shash
+  nloc=$(_review_normalize_location "$loc") || return 1
+  ndesc=$(_review_normalize_description "$desc") || return 1
+  nsugg=$(_review_normalize_suggestion "$sugg") || return 1
+  dhash=$(printf '%s' "$ndesc" | _review_sha1) || return 1
+  shash=$(printf '%s' "$nsugg" | _review_sha1) || return 1
+
+  printf '%s|%s|%s|%s' "$nloc" "$cat" "$dhash" "$shash" \
+    | _review_sha1
+}
+
+_review_description_shingle() {
+  # Input: $1 = normalized description
+  # Output: JSON array of normalized 5-grams (token-based)
+  _review_require_python3 || return 1
+  printf '%s' "$1" | python3 -c '
+import json, sys
+tokens = sys.stdin.read().split()
+n = min(5, len(tokens))
+shingles = [] if n == 0 else sorted({" ".join(tokens[i:i+n]) for i in range(len(tokens)-n+1)})
+print(json.dumps(shingles))
+'
+}
+
+_review_record_attempt() {
+  # Input: $1 = finding JSON, $2 = current round number (1-based), $3 = optional precomputed finding hash
+  # Side effect: increments attempts in the attempts file
+  # Output: prints new attempt count on stdout
+  _review_require_jq || return 1
+  local f="$1" round="$2" hash="${3:-}"
+  local file loc desc nloc ndesc shingle
+  file=$(_review_attempts_file)
+  loc=$(printf '%s' "$f"  | jq -r '.location // ""')
+  desc=$(printf '%s' "$f" | jq -r '.description // ""')
+  nloc=$(_review_normalize_location "$loc") || return 1
+  ndesc=$(_review_normalize_description "$desc") || return 1
+  if [ -z "$hash" ]; then
+    hash=$(_review_finding_hash "$f") || return 1
+  fi
+  shingle=$(_review_description_shingle "$ndesc") || return 1
+
+  [ -f "$file" ] || jq -n --arg id "$(_review_session_id)" --arg created "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    '{session_id: $id, created_at: $created, findings: {}}' > "$file"
+
+  jq --arg h "$hash" --arg loc "$nloc" --argjson sh "$shingle" --argjson r "$round" '
+    .findings[$h] = (
+      .findings[$h] // {attempts: 0, first_seen_round: $r, normalized_location: $loc, description_shingle: $sh}
+      | .attempts += (if .last_seen_round == $r then 0 else 1 end)
+      | .last_seen_round = $r
+    )
+  ' "$file" > "$file.tmp" && mv "$file.tmp" "$file"
+
+  jq -r --arg h "$hash" '.findings[$h].attempts' "$file"
+}
+
+_review_at_strike_limit() {
+  # Input: $1 = finding JSON, $2 = optional precomputed finding hash
+  # Exit: 0 if hash already has >= REVIEW_STRIKE_LIMIT attempts, 1 otherwise
+  _review_require_jq || return 1
+  local f="$1" file hash
+  hash="${2:-}"
+  file=$(_review_attempts_file)
+  [ -f "$file" ] || return 1
+  [ -n "$hash" ] || hash=$(_review_finding_hash "$f") || return 1
+  local n; n=$(jq -r --arg h "$hash" '.findings[$h].attempts // 0' "$file")
+  [ "$n" -ge "${REVIEW_STRIKE_LIMIT:-3}" ]
+}
+```
+
+This bookkeeping assumes sequential execution within a single workspace or
+worktree. Do not run multiple review/fix loops against the same
+`REVIEW_SESSION_ID` concurrently.
+
+#### Per-round flow
+
+After each `mmr review …` call (or `mmr results "$JOB_ID"` for the manual
+fallback), iterate the reconciled findings at or above `fix_threshold`. For each
+blocking finding, compute its hash, call `_review_at_strike_limit "$f" "$hash"`
+before incrementing, and stop the fix loop with verdict `blocked` per Step 8 if
+the hash is already at `${REVIEW_STRIKE_LIMIT:-3}` recorded attempts. Otherwise,
+call `_review_record_attempt "$f" "$ROUND" "$hash"` to record the current
+round before applying the next fix.
+
+For very noisy fix loops you may suggest `--fix-threshold P1` to narrow the
+gate; the project default stays at P2 per the design's Decision 4. Do not
+auto-change the threshold.
+
+Identity components — `location`, `category`, `description`, and `suggestion`
+— mirror MMR T2-A's forthcoming native `finding_key` so this remains a clean
+migration when v3.30 ships.
+
+### Step 7b: File blocking findings as Beads tasks (opt-in)
+
+If `.mmr.yaml` has `beads.create_issues_from_blocking_findings: true` AND `.beads/`
+exists, file each blocking finding (severity at-or-above `beads.fix_threshold`,
+default `P2`) as a Beads bug. This is purely additive tracking — it does NOT replace
+Step 7's fix-in-place flow; it creates a durable record of findings that ought to
+become standalone follow-up work.
+
+```bash
+# First: gate on the opt-in flag in .mmr.yaml. Defaults to disabled.
+# Uses pure bash + grep/sed — no yq dependency.
+beads_enabled=false
+beads_fix_threshold=P2
+beads_default_type=bug
+if [ -f .mmr.yaml ]; then
+  # POSIX character classes ([[:space:]]) for BSD-sed compatibility (macOS default).
+  # Patterns tolerate trailing whitespace/comments — uncommenting a template line with
+  # a trailing `# comment` should still match.
+  if grep -qE '^[[:space:]]*create_issues_from_blocking_findings:[[:space:]]*true([[:space:]]+#.*)?[[:space:]]*$' .mmr.yaml; then
+    beads_enabled=true
+  fi
+  if v=$(grep -E '^[[:space:]]*fix_threshold:[[:space:]]*P[0-4]([[:space:]]+#.*)?[[:space:]]*$' .mmr.yaml | head -1 | sed -E 's/^[^:]*:[[:space:]]*(P[0-4]).*/\1/'); [ -n "$v" ]; then
+    beads_fix_threshold=$v
+  fi
+  if v=$(grep -E '^[[:space:]]*default_type:[[:space:]]*[a-zA-Z]+([[:space:]]+#.*)?[[:space:]]*$' .mmr.yaml | head -1 | sed -E 's/^[^:]*:[[:space:]]*([a-zA-Z]+).*/\1/'); [ -n "$v" ]; then
+    beads_default_type=$v
+  fi
+fi
+
+if [ "$beads_enabled" = "true" ] && [ -d .beads ] && command -v bd >/dev/null 2>&1 \
+   && command -v mmr >/dev/null 2>&1 && [ -n "${JOB_ID:-}" ]; then
+  # Skip when the review-code flow ran in manual fallback mode (no mmr, no JOB_ID).
+  threshold_rank=$(case "$beads_fix_threshold" in P0) echo 0;; P1) echo 1;; P2) echo 2;; P3) echo 3;; *) echo 4;; esac)
+
+  # Capture the reconciled findings from the MMR job we already ran upstream.
+  # MMR JSON shape: { reconciled_findings: [{ severity, location, description, suggestion, ... }] }
+  review_json=$(mmr results "$JOB_ID" --format json)
+
+  while IFS= read -r finding; do
+    title=$(jq -r '.description | .[0:120]' <<<"$finding")
+    severity=$(jq -r '.severity' <<<"$finding")
+    pnum="${severity#P}"
+    description=$(jq -r --arg job "$JOB_ID" '"\(.description)\n\nSuggestion: \(.suggestion // "(none)")\n\nLocation: \(.location // "(unknown)")\n\nFirst seen in MMR job: \($job)"' <<<"$finding")
+    # Per-finding identity for a future dedupe-on-re-runs mechanism (matches
+    # review-pr.md Step 7b). NOTE: bd v1.0.4 has no `bd list --external-ref`
+    # flag, so the bridge does not enforce dedupe at write time — known
+    # limitation; same-job re-runs will create duplicates.
+    loc=$(jq -r '.location // ""' <<<"$finding")
+    desc_for_hash=$(jq -r '.description // ""' <<<"$finding")
+    finding_hash=$(printf '%s|%s' "$loc" "$desc_for_hash" | shasum -a 1 | cut -c1-8)
+
+    args=(
+      "$title"
+      --type "$beads_default_type"
+      -p "$pnum"
+      --description "$description"
+      --external-ref "mmr:$finding_hash"
+    )
+    if [ -n "${SOURCE_BD_ID:-}" ]; then
+      args+=(--deps "discovered-from:$SOURCE_BD_ID")
+    fi
+    bd create "${args[@]}"
+  done < <(jq -c --argjson maxRank "$threshold_rank" '
+    .reconciled_findings[]?
+    | (.severity | sub("^P";"") | tonumber) as $rank
+    | select($rank <= $maxRank)
+  ' <<<"$review_json")
+fi
+```
+
+Same shell idioms as `review-pr.md` Step 7b — see that file for notes on the jq
+arguments and UTF-8-safe truncation. The `.mmr.yaml` opt-in flag is read first;
+the rest of the block is skipped unless `beads.create_issues_from_blocking_findings`
+is `true`. The `--deps discovered-from:$SOURCE_BD_ID` flag is conditional on a
+non-empty `$SOURCE_BD_ID`.
+
 ### Step 8: Final Verdict
 
 Return exactly one verdict:
@@ -446,3 +789,4 @@ for the next delivery step (commit, push, or PR creation).
 4. **Independence** — never share one channel's output with another.
 5. **Fix before proceeding** — findings at or above `fix_threshold` must be resolved before moving to the next task.
 6. **Dispatch pattern** follows `multi-model-review-dispatch` knowledge entry. When modifying channel dispatch in this file, verify consistency with `review-pr.md` and `post-implementation-review.md`.
+7. **3-round limit (per finding hash)** — never attempt to fix the *same* blocking finding (identified by the Step 7a hash of `location` + `category` + `description` + `suggestion`) more than 3 times. The attempts file `.scaffold/review-attempts/<session-id>.json` is the exact-hash source of truth; `_review_at_strike_limit` checks it. Description and suggestion are intentionally part of the strict hash to mirror MMR T2-A's forthcoming native `finding_key`; the same-underlying-defect stop condition is a co-equal guard for wording jitter that produces new hashes. Each round that surfaces genuinely different findings with *new* hashes is healthy iteration — keep going. Stop when a hash hits 3 attempts, when the same underlying defect recurs across 3 rounds even if reviewer wording produces new hashes, when channels contradict each other, or when the user asks to stop. For noisy fix loops, optionally suggest `--fix-threshold P1` (the project default stays at P2).