@jonit-dev/night-watch-cli 1.8.12-beta.9 → 1.8.14-beta.0

package/dist/scripts/night-watch-merger-cron.sh

@@ -14,6 +14,8 @@ set -euo pipefail
 #   NW_MERGER_BRANCH_PATTERNS=               - Comma-separated branch prefixes (empty = all)
 #   NW_MERGER_REBASE_BEFORE_MERGE=1          - Set to 1 to rebase before merging
 #   NW_MERGER_MAX_PRS_PER_RUN=0             - Max PRs to merge per run (0 = unlimited)
+#   NW_MERGER_CI_MAX_WAIT=300                - Max seconds to wait for checks after rebase
+#   NW_MERGER_CI_POLL_INTERVAL=15            - Seconds between check polls after rebase
 #   NW_DRY_RUN=0                             - Set to 1 for dry-run mode
 
 PROJECT_DIR="${1:?Usage: $0 /path/to/project}"
@@ -26,6 +28,8 @@ MERGE_METHOD="${NW_MERGER_MERGE_METHOD:-squash}"
 MIN_REVIEW_SCORE="${NW_MERGER_MIN_REVIEW_SCORE:-80}"
 REBASE_BEFORE_MERGE="${NW_MERGER_REBASE_BEFORE_MERGE:-1}"
 MAX_PRS_PER_RUN="${NW_MERGER_MAX_PRS_PER_RUN:-0}"
+CI_MAX_WAIT="${NW_MERGER_CI_MAX_WAIT:-300}"
+CI_POLL_INTERVAL="${NW_MERGER_CI_POLL_INTERVAL:-15}"
 BRANCH_PATTERNS_RAW="${NW_MERGER_BRANCH_PATTERNS:-}"
 READY_TO_MERGE_LABEL="${NW_PR_RESOLVER_READY_LABEL:-ready-to-merge}"
 SCRIPT_START_TIME=$(date +%s)
@@ -40,6 +44,12 @@ fi
 if ! [[ "${MIN_REVIEW_SCORE}" =~ ^[0-9]+$ ]]; then
   MIN_REVIEW_SCORE="80"
 fi
+if ! [[ "${CI_MAX_WAIT}" =~ ^[0-9]+$ ]]; then
+  CI_MAX_WAIT="300"
+fi
+if ! [[ "${CI_POLL_INTERVAL}" =~ ^[0-9]+$ ]] || [ "${CI_POLL_INTERVAL}" = "0" ]; then
+  CI_POLL_INTERVAL="15"
+fi
 # Clamp merge method to valid values
 case "${MERGE_METHOD}" in
   squash|merge|rebase) ;;
@@ -110,24 +120,145 @@ get_review_score() {
   echo "${score}"
 }
 
-# Check if CI is passing for a PR (all checks must be complete and none failing)
-ci_passing() {
+# Count pending review feedback that should send the PR back through reviewer
+# instead of allowing the merger to land it. We combine GitHub's review decision
+# with unresolved review threads because some providers leave actionable feedback
+# as thread comments without lowering the score.
+get_pending_review_feedback_count() {
   local pr_number="${1}"
-  local checks_json
-  checks_json=$(gh pr checks "${pr_number}" --json name,state,conclusion 2>/dev/null || echo "[]")
-  # Fail if any checks have explicit failures
-  local fail_count
-  fail_count=$(echo "${checks_json}" | jq '[.[] | select(.conclusion == "FAILURE" or .conclusion == "TIMED_OUT" or .conclusion == "CANCELLED" or .state == "FAILURE")] | length' 2>/dev/null || echo "999")
-  if [ "${fail_count}" != "0" ]; then
-    return 1
+  local review_decision=""
+  local change_request_count="0"
+  local unresolved_thread_count="0"
+  local repo=""
+  local owner=""
+  local name=""
+
+  review_decision=$(gh pr view "${pr_number}" --json reviewDecision --jq '.reviewDecision // ""' 2>/dev/null || echo "")
+
+  change_request_count=$(gh api "repos/{owner}/{repo}/pulls/${pr_number}/reviews" \
+    --jq '[.[] | select(.state == "CHANGES_REQUESTED")] | length' 2>/dev/null || echo "0")
+  if ! [[ "${change_request_count}" =~ ^[0-9]+$ ]]; then
+    change_request_count="0"
+  fi
+
+  repo=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null || echo "")
+  if [[ "${repo}" == */* ]]; then
+    owner="${repo%%/*}"
+    name="${repo#*/}"
+    unresolved_thread_count=$(gh api graphql \
+      -F owner="${owner}" \
+      -F name="${name}" \
+      -F number="${pr_number}" \
+      -f query='
+        query($owner: String!, $name: String!, $number: Int!) {
+          repository(owner: $owner, name: $name) {
+            pullRequest(number: $number) {
+              reviewThreads(first: 100) {
+                nodes {
+                  isResolved
+                }
+              }
+            }
+          }
+        }
+      ' \
+      --jq '[.data.repository.pullRequest.reviewThreads.nodes[]? | select(.isResolved == false)] | length' \
+      2>/dev/null || echo "0")
+    if ! [[ "${unresolved_thread_count}" =~ ^[0-9]+$ ]]; then
+      unresolved_thread_count="0"
+    fi
+  fi
+
+  if [ "${unresolved_thread_count}" -gt 0 ]; then
+    echo "${unresolved_thread_count}"
+    return 0
+  fi
+
+  if [ "${change_request_count}" -gt 0 ]; then
+    echo "${change_request_count}"
+    return 0
   fi
-  # Fail if any checks are still pending/in-progress (not yet concluded)
-  local pending_count
-  pending_count=$(echo "${checks_json}" | jq '[.[] | select(.state == "PENDING" or .state == "IN_PROGRESS" or (.conclusion == null and .state != "SUCCESS"))] | length' 2>/dev/null || echo "999")
-  if [ "${pending_count}" != "0" ]; then
-    return 1
+
+  if [ "${review_decision}" = "CHANGES_REQUESTED" ]; then
+    echo "1"
+    return 0
   fi
-  return 0
+
+  echo "0"
+}
+
+# Get the current head OID for a PR.
+get_pr_head_oid() {
+  local pr_number="${1}"
+  gh pr view "${pr_number}" --json headRefOid --jq '.headRefOid // ""' 2>/dev/null || echo ""
+}
+
+# Return the CI state for the PR's status rollup on the expected head OID.
+ci_status_for_head() {
+  local pr_number="${1}"
+  local expected_head="${2:-}"
+  local status_json
+
+  status_json=$(gh pr view "${pr_number}" --json headRefOid,statusCheckRollup 2>/dev/null || echo "")
+  if [ -z "${status_json}" ]; then
+    echo "unknown"
+    return 0
+  fi
+
+  echo "${status_json}" | jq -r --arg expected_head "${expected_head}" '
+    def in_list($values): . as $value | $values | index($value);
+    def check_run_failure:
+      .__typename == "CheckRun"
+      and ((.conclusion // "") | in_list(["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STALE", "STARTUP_FAILURE"]));
+    def status_context_failure:
+      .__typename == "StatusContext"
+      and ((.state // "") | in_list(["FAILURE", "ERROR"]));
+    def check_run_pending:
+      .__typename == "CheckRun"
+      and ((.status // "") != "COMPLETED" or .conclusion == null);
+    def status_context_pending:
+      .__typename == "StatusContext"
+      and ((.state // "") | in_list(["PENDING", "EXPECTED"]));
+    def check_run_nonpassing:
+      .__typename == "CheckRun"
+      and ((.conclusion // "") | in_list(["SUCCESS", "NEUTRAL", "SKIPPED"]) | not);
+    def status_context_nonpassing:
+      .__typename == "StatusContext"
+      and (.state // "") != "SUCCESS";
+    if ($expected_head != "" and (.headRefOid // "") != $expected_head) then
+      "head_mismatch"
+    elif ((.statusCheckRollup // []) | length) == 0 then
+      "absent"
+    elif any((.statusCheckRollup // [])[]; check_run_failure or status_context_failure) then
+      "failed"
+    elif any((.statusCheckRollup // [])[]; check_run_pending or status_context_pending) then
+      "pending"
+    elif any((.statusCheckRollup // [])[]; check_run_nonpassing or status_context_nonpassing) then
+      "failed"
+    else
+      "passing"
+    end
+  ' 2>/dev/null || echo "unknown"
+}
+
+wait_for_ci_passing_on_head() {
+  local pr_number="${1}"
+  local expected_head="${2}"
+  local ci_waited=0
+  LAST_CI_STATUS="unknown"
+
+  while [ "${ci_waited}" -lt "${CI_MAX_WAIT}" ]; do
+    LAST_CI_STATUS=$(ci_status_for_head "${pr_number}" "${expected_head}")
+    if [ "${LAST_CI_STATUS}" = "passing" ]; then
+      return 0
+    fi
+    log "INFO: PR #${pr_number}: Waiting for fresh CI on head ${expected_head} (${LAST_CI_STATUS}, ${ci_waited}s/${CI_MAX_WAIT}s)..."
+    sleep "${CI_POLL_INTERVAL}"
+    ci_waited=$((ci_waited + CI_POLL_INTERVAL))
+  done
+
+  LAST_CI_STATUS=$(ci_status_for_head "${pr_number}" "${expected_head}")
+  [ "${LAST_CI_STATUS}" = "passing" ]
 }
 
 # Rebase a PR against its base branch
@@ -254,9 +385,16 @@ while IFS= read -r pr_json; do
     continue
   fi
 
+  pr_head_oid=$(get_pr_head_oid "${pr_number}")
+  if [ -z "${pr_head_oid}" ]; then
+    log "INFO: PR #${pr_number} (${pr_branch}): Unable to determine PR head, skipping"
+    continue
+  fi
+
   # Check CI status
-  if ! ci_passing "${pr_number}"; then
-    log "INFO: PR #${pr_number} (${pr_branch}): CI not passing, skipping"
+  ci_status=$(ci_status_for_head "${pr_number}" "${pr_head_oid}")
+  if [ "${ci_status}" != "passing" ]; then
+    log "INFO: PR #${pr_number} (${pr_branch}): CI not passing on head ${pr_head_oid} (${ci_status}), skipping"
     continue
   fi
 
@@ -264,15 +402,22 @@ while IFS= read -r pr_json; do
   if [ "${MIN_REVIEW_SCORE}" -gt "0" ]; then
     score=$(get_review_score "${pr_number}")
     if [ "${score}" -lt "0" ] || [ "${score}" -lt "${MIN_REVIEW_SCORE}" ]; then
-      log "INFO: PR #${pr_number} (${pr_branch}): Review score ${score} < ${MIN_REVIEW_SCORE} (or no score found), skipping"
+      log "INFO: PR #${pr_number} (${pr_branch}): Review score ${score} < ${MIN_REVIEW_SCORE} (or no score found), reviewer job required before merge"
       continue
     fi
   fi
 
+  pending_review_feedback_count=$(get_pending_review_feedback_count "${pr_number}")
+  if [ "${pending_review_feedback_count}" -gt "0" ]; then
+    log "INFO: PR #${pr_number} (${pr_branch}): ${pending_review_feedback_count} pending review feedback item(s), reviewer job required before merge"
+    continue
+  fi
+
   log "INFO: PR #${pr_number} (${pr_branch}): Eligible for merge"
 
   # Rebase before merge if configured
   if [ "${REBASE_BEFORE_MERGE}" = "1" ]; then
+    pr_head_before_rebase="${pr_head_oid}"
     if ! rebase_pr "${pr_number}"; then
       log "WARN: PR #${pr_number}: Rebase failed, skipping"
       FAILED_PRS=$((FAILED_PRS + 1))
@@ -280,20 +425,20 @@ while IFS= read -r pr_json; do
     fi
     log "INFO: PR #${pr_number}: Rebase successful"
 
-    # Poll CI until all checks complete after rebase (up to 5 minutes)
-    ci_max_wait=300
-    ci_waited=0
-    ci_poll=15
-    while [ "${ci_waited}" -lt "${ci_max_wait}" ]; do
-      sleep "${ci_poll}"
-      ci_waited=$((ci_waited + ci_poll))
-      if ci_passing "${pr_number}"; then
-        break
-      fi
-      log "INFO: PR #${pr_number}: Waiting for CI after rebase (${ci_waited}s/${ci_max_wait}s)..."
-    done
-    if ! ci_passing "${pr_number}"; then
-      log "INFO: PR #${pr_number}: CI not passing after rebase (waited ${ci_waited}s), skipping"
+    pr_head_after_rebase=$(get_pr_head_oid "${pr_number}")
+    if [ -z "${pr_head_after_rebase}" ]; then
+      log "INFO: PR #${pr_number}: Unable to determine PR head after rebase, skipping"
+      continue
+    fi
+    if [ "${pr_head_after_rebase}" != "${pr_head_before_rebase}" ]; then
+      log "INFO: PR #${pr_number}: Head changed after rebase ${pr_head_before_rebase} -> ${pr_head_after_rebase}; waiting for fresh CI"
+    else
+      log "INFO: PR #${pr_number}: Head unchanged after rebase (${pr_head_after_rebase}); confirming CI"
+    fi
+
+    # Poll CI until all checks attached to the post-rebase head are complete and passing.
+    if ! wait_for_ci_passing_on_head "${pr_number}" "${pr_head_after_rebase}"; then
+      log "INFO: PR #${pr_number}: Fresh CI not passing on head ${pr_head_after_rebase} after rebase (${LAST_CI_STATUS}, waited ${CI_MAX_WAIT}s), skipping"
       continue
     fi
   fi

package/dist/scripts/night-watch-pr-reviewer-cron.sh

@@ -89,6 +89,26 @@ emit_result() {
   fi
 }
 
+is_pr_open() {
+  local pr_number="${1:?PR number required}"
+  local pr_state=""
+
+  pr_state=$(gh pr view "${pr_number}" --json state --jq '.state // ""' 2>/dev/null || echo "")
+  case "${pr_state}" in
+    OPEN)
+      return 0
+      ;;
+    MERGED|CLOSED)
+      return 1
+      ;;
+  esac
+
+  # Backward-compatible fallback for older gh versions or tests that do not
+  # support the state field. Treat an unknown/empty state as open only when the
+  # PR is still viewable by number.
+  gh pr view "${pr_number}" --json number >/dev/null 2>&1
+}
+
 require_provider_on_path() {
   if ! ensure_provider_on_path "${PROVIDER_CMD}"; then
     echo "ERROR: Provider '${PROVIDER_CMD}' not found in PATH or common installation locations" >&2
@@ -132,6 +152,72 @@ get_pr_comments() {
   } | awk '!seen[$0]++'
 }
 
+get_pr_pending_review_feedback_count() {
+  local pr_number="${1:?PR number required}"
+  local review_decision=""
+  local change_request_count="0"
+  local unresolved_thread_count="0"
+  local repo="${REPO:-}"
+  local owner=""
+  local name=""
+
+  review_decision=$(gh pr view "${pr_number}" --json reviewDecision --jq '.reviewDecision // ""' 2>/dev/null || echo "")
+
+  change_request_count=$(gh api "repos/{owner}/{repo}/pulls/${pr_number}/reviews" \
+    --jq '[.[] | select(.state == "CHANGES_REQUESTED")] | length' 2>/dev/null || echo "0")
+  if ! [[ "${change_request_count}" =~ ^[0-9]+$ ]]; then
+    change_request_count="0"
+  fi
+
+  if [ -z "${repo}" ]; then
+    repo=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null || echo "")
+  fi
+
+  if [[ "${repo}" == */* ]]; then
+    owner="${repo%%/*}"
+    name="${repo#*/}"
+    unresolved_thread_count=$(gh api graphql \
+      -F owner="${owner}" \
+      -F name="${name}" \
+      -F number="${pr_number}" \
+      -f query='
+        query($owner: String!, $name: String!, $number: Int!) {
+          repository(owner: $owner, name: $name) {
+            pullRequest(number: $number) {
+              reviewThreads(first: 100) {
+                nodes {
+                  isResolved
+                }
+              }
+            }
+          }
+        }
+      ' \
+      --jq '[.data.repository.pullRequest.reviewThreads.nodes[]? | select(.isResolved == false)] | length' \
+      2>/dev/null || echo "0")
+    if ! [[ "${unresolved_thread_count}" =~ ^[0-9]+$ ]]; then
+      unresolved_thread_count="0"
+    fi
+  fi
+
+  if [ "${unresolved_thread_count}" -gt 0 ]; then
+    echo "${unresolved_thread_count}"
+    return 0
+  fi
+
+  if [ "${change_request_count}" -gt 0 ]; then
+    echo "${change_request_count}"
+    return 0
+  fi
+
+  if [ "${review_decision}" = "CHANGES_REQUESTED" ]; then
+    echo "1"
+    return 0
+  fi
+
+  echo "0"
+}
+
 get_pr_head_ref_oid() {
   local pr_number="${1:?PR number required}"
   gh pr view "${pr_number}" --json headRefOid --jq '.headRefOid' 2>/dev/null || echo ""
@@ -654,7 +740,7 @@ fi
 
 if [ -n "${TARGET_PR}" ]; then
   OPEN_PRS=$(
-    if gh pr view "${TARGET_PR}" --json number >/dev/null 2>&1; then
+    if is_pr_open "${TARGET_PR}"; then
       echo "1"
     else
       echo "0"
@@ -760,6 +846,18 @@ while IFS=$'\t' read -r pr_number pr_branch pr_labels; do
     continue
   fi
 
+  PENDING_REVIEW_FEEDBACK_COUNT=$(get_pr_pending_review_feedback_count "${pr_number}")
+  if [ "${PENDING_REVIEW_FEEDBACK_COUNT}" -gt 0 ]; then
+    if [ "${local_ready_for_review_label_present}" -eq 1 ]; then
+      log "INFO: PR #${pr_number} (${pr_branch}) has pending review feedback; removing stale ${READY_FOR_REVIEW_LABEL} label"
+      clear_ready_for_human_review_label "${pr_number}"
+    fi
+    log "INFO: PR #${pr_number} (${pr_branch}) has ${PENDING_REVIEW_FEEDBACK_COUNT} pending review feedback item(s)"
+    NEEDS_WORK=1
+    PRS_NEEDING_WORK="${PRS_NEEDING_WORK} #${pr_number}"
+    continue
+  fi
+
   if has_ready_for_human_review_marker "${all_comments}" "${current_head_sha}"; then
     SKIPPED_ALREADY_REVIEWED_CURRENT_HEAD=1
     log "INFO: PR #${pr_number} (${pr_branch}) is already marked ready for human review at head ${current_head_sha:0:12}; skipping repeat automated review"
@@ -893,6 +991,7 @@ if [ -z "${TARGET_PR}" ] && [ "${WORKER_MODE}" != "1" ] && [ "${PARALLEL_ENABLED
   EXIT_CODE=0
   AUTO_MERGED_PRS=""
   AUTO_MERGE_FAILED_PRS=""
+  ACTUAL_REVIEWED_PRS=""
   NO_CHANGES_PRS=""
   MAX_WORKER_ATTEMPTS=1
   MAX_WORKER_FINAL_SCORE=""
@@ -937,6 +1036,7 @@ if [ -z "${TARGET_PR}" ] && [ "${WORKER_MODE}" != "1" ] && [ "${PARALLEL_ENABLED
     worker_status=$(printf '%s' "${worker_result}" | sed -n 's/^NIGHT_WATCH_RESULT:\([^|]*\).*$/\1/p')
     worker_auto_merged=$(printf '%s' "${worker_result}" | grep -oP '(?<=auto_merged=)[^|]+' || true)
     worker_auto_merge_failed=$(printf '%s' "${worker_result}" | grep -oP '(?<=auto_merge_failed=)[^|]+' || true)
+    worker_reviewed_prs=$(printf '%s' "${worker_result}" | grep -oP '(?<=prs=)[^|]+' || true)
     worker_attempts=$(printf '%s' "${worker_result}" | grep -oP '(?<=attempts=)[^|]+' || true)
     worker_final_score=$(printf '%s' "${worker_result}" | grep -oP '(?<=final_score=)[^|]+' || true)
     worker_no_changes=$(printf '%s' "${worker_result}" | grep -oP '(?<=no_changes_needed=)[^|]+' || true)
@@ -944,6 +1044,9 @@ if [ -z "${TARGET_PR}" ] && [ "${WORKER_MODE}" != "1" ] && [ "${PARALLEL_ENABLED
 
     AUTO_MERGED_PRS=$(append_csv "${AUTO_MERGED_PRS}" "${worker_auto_merged}")
     AUTO_MERGE_FAILED_PRS=$(append_csv "${AUTO_MERGE_FAILED_PRS}" "${worker_auto_merge_failed}")
+    if [ "${worker_status}" = "success_reviewed" ]; then
+      ACTUAL_REVIEWED_PRS=$(append_csv "${ACTUAL_REVIEWED_PRS}" "${worker_reviewed_prs}")
+    fi
     NO_CHANGES_PRS=$(append_csv "${NO_CHANGES_PRS}" "${worker_no_changes_prs}")
     if [ -z "${worker_no_changes_prs}" ] && [ "${worker_no_changes}" = "1" ]; then
       NO_CHANGES_PRS=$(append_csv "${NO_CHANGES_PRS}" "#${worker_pr}")
@@ -988,7 +1091,7 @@ if [ -z "${TARGET_PR}" ] && [ "${WORKER_MODE}" != "1" ] && [ "${PARALLEL_ENABLED
   # worker runs may have left behind.
   cleanup_reviewer_worktrees
 
-  emit_final_status "${EXIT_CODE}" "${PRS_NEEDING_WORK_CSV}" "${AUTO_MERGED_PRS}" "${AUTO_MERGE_FAILED_PRS}" "${MAX_WORKER_ATTEMPTS}" "${MAX_WORKER_FINAL_SCORE}" "0" "${NO_CHANGES_PRS}"
+  emit_final_status "${EXIT_CODE}" "${ACTUAL_REVIEWED_PRS}" "${AUTO_MERGED_PRS}" "${AUTO_MERGE_FAILED_PRS}" "${MAX_WORKER_ATTEMPTS}" "${MAX_WORKER_FINAL_SCORE}" "0" "${NO_CHANGES_PRS}"
   exit "${EXIT_CODE}"
 fi
 
@@ -1077,6 +1180,7 @@ if [ -n "${TARGET_PR}" ]; then
   TARGET_MERGE_STATE=$(gh pr view "${TARGET_PR}" --json mergeStateStatus --jq '.mergeStateStatus' 2>/dev/null || echo "UNKNOWN")
   TARGET_FAILED_CHECKS=$(get_pr_failed_ci_summary "${TARGET_PR}")
   TARGET_SCORE=$(get_pr_score "${TARGET_PR}")
+  TARGET_PENDING_REVIEW_FEEDBACK=$(get_pr_pending_review_feedback_count "${TARGET_PR}")
 
   TARGET_SCOPE_PROMPT+=$'\n## Preflight Data (from CLI)\n- mergeStateStatus: '"${TARGET_MERGE_STATE}"$'\n'
   if [ -n "${TARGET_FAILED_CHECKS}" ]; then
@@ -1084,6 +1188,7 @@ if [ -n "${TARGET_PR}" ]; then
   else
     TARGET_SCOPE_PROMPT+=$'- failing checks: none detected\n'
   fi
+  TARGET_SCOPE_PROMPT+=$'- pending review feedback: '"${TARGET_PENDING_REVIEW_FEEDBACK}"$' item(s)\n'
   if [ -n "${TARGET_SCORE}" ]; then
     TARGET_SCOPE_PROMPT+=$'- latest review score: '"${TARGET_SCORE}"$'/100\n'
     TARGET_SCOPE_PROMPT+=$'- action: fix\n'

package/dist/templates/audit.md

@@ -1,4 +1,6 @@
-You are the Night Watch Code Auditor. Your job is to scan the codebase for real engineering risks and write a structured, high-signal report.
+You are the Night Watch Code Auditor. Your job is to scan the codebase for systemic engineering risks and write a consolidated architecture/code-quality audit report for human prioritization.
+
+The default output is a broad report, not executor fodder. Do not create or recommend one board issue per finding unless an explicit "Board Issue Mode" section is appended to this prompt.
 
 ## What to look for
 
@@ -30,65 +32,97 @@ You are the Night Watch Code Auditor. Your job is to scan the codebase for real
 
 - `node_modules/`, `dist/`, `.git/`, `coverage/`, generated files.
 - Test files (`*.test.ts`, `*.spec.ts`, `__tests__/`) unless they expose production design flaws.
-- Intentional no-op catches in file walkers/read-only probing paths (e.g., `catch { continue }`, `catch { return null }` when clearly harmless).
+- Intentional no-op catches in file walkers/read-only probing paths (for example, `catch { continue }`, `catch { return null }` when clearly harmless).
 - Cosmetic style-only nits (formatting, naming preference, import order).
-- Hypothetical principle violations without concrete impact.
+- Hypothetical principle violations without concrete code evidence and impact.
 
 ## How to scan
 
 Use file-reading/search tools and scan systematically, prioritizing:
 
-- `src/` (core TypeScript implementation)
-- `scripts/` (automation and shell execution paths)
+- `src/` and package implementation directories.
+- `scripts/` and automation/runtime shell paths.
+- Shared configuration, scheduler, queue, provider, board, and command flows.
 
 For each potential issue, verify:
 
 1. It is real and actionable.
-2. It has concrete impact (correctness, security, scalability, operability, maintainability).
-3. The fix direction is clear.
+2. It has concrete impact on correctness, security, scalability, operability, or maintainability.
+3. The affected locations show a pattern or systemic design problem, not just a tiny isolated nit.
+4. The fix direction is useful for human planning.
+
+## Priority model
+
+Use an Effort x Impact priority model:
 
-## Severity model
+- **Impact**: critical, high, medium, low.
+- **Effort**: small, medium, large.
+- **Priority**: P0, P1, P2, P3.
 
-- **critical**: likely production outage/data loss/security exposure or severe architectural risk.
-- **high**: significant bug/risk with near-term impact.
-- **medium**: clear risk/smell that should be addressed soon.
-- **low**: valid but lower urgency.
+Assign P0/P1 only when the issue is urgent or unlocks significant risk reduction. Be selective.
 
 ## Report format
 
-Write findings to `logs/audit-report.md` using this exact format:
+Write `logs/audit-report.md` using this format:
 
 ```markdown
-# Code Audit Report
+# Architecture and Code Quality Audit
 
 Generated: <ISO timestamp>
 
-## Findings
+## Executive Summary
 
-### Finding 1
+One to three concise paragraphs covering the highest-risk themes, the likely cost of leaving them alone, and the recommended order of attack.
 
-- **Location**: `src/path/to/file.ts:42`
-- **Severity**: critical | high | medium | low
-- **Category**: empty_catch | critical_todo | hardcoded_secret | unhandled_promise | unsafe_assertion | scalability_hotspot | architecture_violation | srp_violation | dry_violation | kiss_violation | solid_violation | yagni_violation
-- **Description**: What the issue is, why it matters, and concrete impact
-- **Snippet**: `the offending code`
-- **Suggested Fix**: Specific fix direction (minimal, pragmatic)
+## Priority Matrix
 
-### Finding 2
+| Priority | Theme        | Impact | Effort | Why now        |
+| -------- | ------------ | ------ | ------ | -------------- |
+| P1       | <theme name> | high   | medium | <short reason> |
 
-...
-```
+## Findings by Theme
 
-If you find **no actionable issues**, write exactly this to `logs/audit-report.md`:
+### <Theme Name>
+
+Impact: critical | high | medium | low
+Effort: small | medium | large
+Priority: P0 | P1 | P2 | P3
+
+#### Evidence
+
+- `<path>:<line>` - what is happening and why it matters.
+- `<path>:<line>` - related evidence showing this is systemic.
+
+#### Architecture or Quality Rule Violated
+
+Name the concrete rule or boundary being violated.
+
+#### Recommended Direction
+
+Describe the pragmatic remediation path. Prefer grouped fixes and sequencing over tiny task breakdowns.
+
+#### Full Violation List
+
+- `<path>:<line>` - concise violation.
+- `<path>:<line>` - concise violation.
+
+## Cross-Cutting Recommendations
+
+- <Recommendation that helps multiple themes>
+
+## No-Issue Result
+
+If there are no actionable systemic issues, write exactly:
 
-```
 NO_ISSUES_FOUND
 ```
 
 ## Rules
 
-- Prioritize high-impact findings over volume. 3 strong findings beat 15 weak ones.
-- Report principle violations (SRP/DRY/KISS/SOLID/YAGNI) only when they create concrete risk.
+- Favor grouped systemic findings over granular one-off findings.
+- Include a full violation list under each theme so humans can size and prioritize the work.
+- Do not use `### Finding N` headings in default report mode.
+- Do not create one issue per finding, and do not optimize the report for automatic execution.
+- Report principle violations only when they create concrete risk.
 - Avoid theoretical architecture criticism without code evidence.
-- Be decisive: skip noisy false positives.
 - After writing the report, stop. Do NOT open PRs, push code, or make changes.