fix(review): distinguish leftover diff fences from applyable suggestions

.github/workflows/opencode-review-dispatch.yml

@@ -5623,24 +5623,221 @@ jobs:
             exit 0
           }
 
+          retry_inline_comments_one_at_a_time() {
+            local batch_payload_file="$1" review_body="$2" refused_locations_file="$3"
+            local attached_locations_file="${4:-}"
+            local deferred_locations_file="${5:-}"
+            local split_dir comment_file wrapped_file error_file response_file
+            local attached=0
+            local found=0
+            local -a split_args
+
+            : >"$refused_locations_file"
+            if [ -n "$attached_locations_file" ]; then
+              : >"$attached_locations_file"
+            fi
+            split_dir="$(mktemp -d)"
+            split_args=(
+              python3 "$GITHUB_WORKSPACE/scripts/ci/opencode_inline_comment_fallback.py"
+              --split-payload "$batch_payload_file"
+              --output-dir "$split_dir"
+              --retry-limit "${OPENCODE_INLINE_COMMENT_RETRY_LIMIT:-20}"
+            )
+            if [ -n "$deferred_locations_file" ]; then
+              : >"$deferred_locations_file"
+              split_args+=(--deferred-locations "$deferred_locations_file")
+            fi
+            if ! "${split_args[@]}"; then
+              rm -rf "$split_dir"
+              return 1
+            fi
+            for comment_file in "$split_dir"/comment-*.json; do
+              [ -f "$comment_file" ] || continue
+              found=1
+              wrapped_file="$(mktemp)"
+              error_file="$(mktemp)"
+              response_file="$(mktemp)"
+              if [ "$attached" -eq 0 ]; then
+                jq --arg body "$review_body" --arg event "REQUEST_CHANGES" \
+                  '.event = $event | .body = $body' "$comment_file" >"$wrapped_file"
+              else
+                cp "$comment_file" "$wrapped_file"
+              fi
+              if post_pull_review_with_retry \
+                "inline review one-at-a-time" \
+                "$review_write_token" \
+                "$wrapped_file" \
+                "$error_file" \
+                "$response_file"; then
+                attached=1
+                if [ -n "$attached_locations_file" ]; then
+                  python3 "$GITHUB_WORKSPACE/scripts/ci/opencode_inline_comment_fallback.py" \
+                    --record-attach \
+                    --attached-locations "$attached_locations_file" \
+                    --comment-file "$comment_file" || true
+                fi
+              else
+                python3 "$GITHUB_WORKSPACE/scripts/ci/opencode_inline_comment_fallback.py" \
+                  --record-refusal \
+                  --refused-locations "$refused_locations_file" \
+                  --comment-file "$comment_file" \
+                  --error-file "$error_file" || true
+                if [ -s "$error_file" ]; then
+                  cat "$error_file" >>"${refused_locations_file}.errors"
+                fi
+              fi
+              rm -f "$wrapped_file" "$error_file" "$response_file"
+              if [ "${REVIEW_PUBLICATION_STALE_HEAD:-}" = "1" ]; then
+                rm -rf "$split_dir"
+                return 1
+              fi
+            done
+            rm -rf "$split_dir"
+            if [ "$found" -eq 0 ] || [ "$attached" -eq 0 ]; then
+              return 1
+            fi
+            return 0
+          }
+
+          prefilter_inline_comments_to_hunks() {
+            local payload_file="$1"
+            local skipped_file="$2"
+            local applyable_file="${3:-}"
+            local leftover_file="${4:-}"
+            local hunks_diff_file
+            local filtered_file
+            local merge_base
+            local -a filter_args
+            hunks_diff_file="$(mktemp)"
+            filtered_file="$(mktemp)"
+            : >"$skipped_file"
+            : >"$hunks_diff_file"
+            if [ -n "$applyable_file" ]; then
+              : >"$applyable_file"
+            fi
+            if [ -n "$leftover_file" ]; then
+              : >"$leftover_file"
+            fi
+            if [ -n "${OPENCODE_SOURCE_WORKDIR:-}" ] && [ -n "${PR_BASE_SHA:-}" ] && [ -n "${PR_HEAD_SHA:-}" ]; then
+              merge_base="$(git -C "$OPENCODE_SOURCE_WORKDIR" merge-base "$PR_BASE_SHA" "$PR_HEAD_SHA" 2>/dev/null || true)"
+              if [ -z "$merge_base" ]; then
+                merge_base="$PR_BASE_SHA"
+              fi
+              git -C "$OPENCODE_SOURCE_WORKDIR" diff --unified=3 --find-renames --no-color --no-ext-diff \
+                "$merge_base" "$PR_HEAD_SHA" >"$hunks_diff_file" || : >"$hunks_diff_file"
+            fi
+            filter_args=(
+              python3 "$GITHUB_WORKSPACE/scripts/ci/opencode_inline_comment_fallback.py"
+              --filter-hunks
+              --payload "$payload_file"
+              --hunks-diff "$hunks_diff_file"
+              --output "$filtered_file"
+              --skipped-locations "$skipped_file"
+            )
+            if [ -n "$applyable_file" ]; then
+              filter_args+=(--applyable-locations "$applyable_file")
+            fi
+            if [ -n "$leftover_file" ]; then
+              filter_args+=(--leftover-diff-locations "$leftover_file")
+            fi
+            if "${filter_args[@]}"; then
+              mv "$filtered_file" "$payload_file"
+            else
+              rm -f "$filtered_file"
+            fi
+            rm -f "$hunks_diff_file"
+          }
+
           create_pull_review_with_payload() {
             local event="$1" body="$2" review_payload_file="$3" fallback_body_file="$4"
+            local source_body_file="${5:-}"
+            local control_json="${6:-}"
             local gh_error_file
             local rewritten_payload_file
             local review_response_file
+            local skipped_locations_file
+            local applyable_locations_file
+            local leftover_diff_locations_file
+            local comment_count
             gh_error_file="$(mktemp)"
             rewritten_payload_file="$(mktemp)"
             review_response_file="$(mktemp)"
+            skipped_locations_file="$(mktemp)"
+            applyable_locations_file="$(mktemp)"
+            leftover_diff_locations_file="$(mktemp)"
             body="$(ensure_review_body_has_change_graph "$body")"
             if jq --arg body "$body" '.body = $body' "$review_payload_file" >"$rewritten_payload_file"; then
               mv "$rewritten_payload_file" "$review_payload_file"
             else
               rm -f "$rewritten_payload_file"
             fi
+            prefilter_inline_comments_to_hunks "$review_payload_file" "$skipped_locations_file" "$applyable_locations_file" "$leftover_diff_locations_file"
+            comment_count="$(jq '.comments | length' "$review_payload_file" 2>/dev/null || printf '0')"
+            if [ "$comment_count" = "0" ] && [ -s "$skipped_locations_file" ] \
+              && [ -n "$source_body_file" ] && [ -n "$control_json" ]; then
+              build_inline_comment_failure_body \
+                "$source_body_file" "$fallback_body_file" "$control_json" \
+                "" "" "" "" "$skipped_locations_file" "$applyable_locations_file" \
+                "$leftover_diff_locations_file" || true
+              if [ -s "$fallback_body_file" ]; then
+                body="$(cat "$fallback_body_file")"
+                if jq --arg body "$body" '.body = $body | del(.comments)' \
+                  "$review_payload_file" >"$rewritten_payload_file"; then
+                  mv "$rewritten_payload_file" "$review_payload_file"
+                else
+                  rm -f "$rewritten_payload_file"
+                fi
+              fi
+            fi
             emit_review_body_to_action_log "$event" "$body" "$review_payload_file"
             if ! post_pull_review_with_retry "inline review" "$review_write_token" "$review_payload_file" "$gh_error_file" "$review_response_file"; then
               warn_gh_publication_failure "pull review inline comments" "$gh_error_file"
-              rm -f "$gh_error_file" "$review_response_file"
+              if [ "${REVIEW_PUBLICATION_STALE_HEAD:-}" != "1" ] \
+                && python3 "$GITHUB_WORKSPACE/scripts/ci/opencode_inline_comment_fallback.py" \
+                  --is-unprocessable --error-file "$gh_error_file"; then
+                refused_locations_file="$(mktemp)"
+                attached_locations_file="$(mktemp)"
+                deferred_locations_file="$(mktemp)"
+                if retry_inline_comments_one_at_a_time \
+                  "$review_payload_file" "$body" "$refused_locations_file" \
+                  "$attached_locations_file" "$deferred_locations_file"; then
+                  if { [ -s "$refused_locations_file" ] || [ -s "$deferred_locations_file" ] \
+                    || [ -s "$skipped_locations_file" ] || [ -s "$applyable_locations_file" ] \
+                    || [ -s "$leftover_diff_locations_file" ]; } \
+                    && [ -n "$source_body_file" ] && [ -n "$control_json" ]; then
+                    mixed_error_file="$gh_error_file"
+                    if [ -s "${refused_locations_file}.errors" ]; then
+                      mixed_error_file="${refused_locations_file}.errors"
+                    fi
+                    build_inline_comment_failure_body \
+                      "$source_body_file" "$fallback_body_file" "$control_json" \
+                      "$mixed_error_file" "$refused_locations_file" \
+                      "$attached_locations_file" "$deferred_locations_file" \
+                      "$skipped_locations_file" "$applyable_locations_file" \
+                      "$leftover_diff_locations_file" || true
+                    update_review_overview "$event" "$(cat "$fallback_body_file")"
+                  else
+                    update_review_overview "$event" "$body"
+                  fi
+                  rm -f "$gh_error_file" "$review_response_file" \
+                    "$refused_locations_file" "${refused_locations_file}.errors" \
+                    "$attached_locations_file" "$deferred_locations_file" \
+                    "$skipped_locations_file" "$applyable_locations_file" \
+                    "$leftover_diff_locations_file"
+                  return 0
+                fi
+                rm -f "$refused_locations_file" "${refused_locations_file}.errors" \
+                  "$attached_locations_file" "$deferred_locations_file"
+              fi
+              if [ -n "$source_body_file" ] && [ -n "$control_json" ]; then
+                build_inline_comment_failure_body \
+                  "$source_body_file" "$fallback_body_file" "$control_json" \
+                  "$gh_error_file" "" "" "" "$skipped_locations_file" \
+                  "$applyable_locations_file" "$leftover_diff_locations_file" || true
+              fi
+              rm -f "$gh_error_file" "$review_response_file" \
+                "$skipped_locations_file" "$applyable_locations_file" \
+                "$leftover_diff_locations_file"
               if [ "${REVIEW_PUBLICATION_STALE_HEAD:-}" = "1" ]; then
                 printf '::error::OpenCode inline review publication stopped because PR head advanced beyond %s.\n' "$HEAD_SHA"
                 return 1
@@ -5652,7 +5849,20 @@ jobs:
               fi
               return 1
             fi
-            rm -f "$gh_error_file" "$review_response_file"
+            if { [ -s "$skipped_locations_file" ] || [ -s "$applyable_locations_file" ] \
+              || [ -s "$leftover_diff_locations_file" ]; } \
+              && [ -n "$source_body_file" ] && [ -n "$control_json" ]; then
+              build_inline_comment_failure_body \
+                "$source_body_file" "$fallback_body_file" "$control_json" \
+                "" "" "" "" "$skipped_locations_file" "$applyable_locations_file" \
+                "$leftover_diff_locations_file" || true
+              if [ -s "$fallback_body_file" ]; then
+                body="$(cat "$fallback_body_file")"
+              fi
+            fi
+            rm -f "$gh_error_file" "$review_response_file" \
+              "$skipped_locations_file" "$applyable_locations_file" \
+              "$leftover_diff_locations_file"
             update_review_overview "$event" "$body"
           }
 
@@ -5766,12 +5976,45 @@ jobs:
           build_inline_comment_failure_body() {
             local body_file="$1"
             local output_file="$2"
-
-            {
-              cat "$body_file"
-              printf '\n## Inline comment publishing failed\n\n'
-              printf 'GitHub did not accept the inline review comments for the cited finding lines, so OpenCode did not copy suggested diffs into this PR-level body. Re-run the review after the findings are anchored to changed diff lines, or inspect the workflow log/control JSON and apply the changes manually.\n'
-            } >"$output_file"
+            local control_json="$3"
+            local error_file="${4:-}"
+            local refused_locations_file="${5:-}"
+            local attached_locations_file="${6:-}"
+            local deferred_locations_file="${7:-}"
+            local skipped_locations_file="${8:-}"
+            local applyable_locations_file="${9:-}"
+            local leftover_diff_locations_file="${10:-}"
+            local -a fallback_args
+
+            fallback_args=(
+              python3 "$GITHUB_WORKSPACE/scripts/ci/opencode_inline_comment_fallback.py"
+              --control "$control_json"
+              --body "$body_file"
+              --output "$output_file"
+              --retry-limit "${OPENCODE_INLINE_COMMENT_RETRY_LIMIT:-20}"
+            )
+            if [ -n "$error_file" ]; then
+              fallback_args+=(--error-file "$error_file")
+            fi
+            if [ -n "$refused_locations_file" ]; then
+              fallback_args+=(--refused-locations "$refused_locations_file")
+            fi
+            if [ -n "$attached_locations_file" ]; then
+              fallback_args+=(--attached-locations "$attached_locations_file")
+            fi
+            if [ -n "$deferred_locations_file" ]; then
+              fallback_args+=(--deferred-locations "$deferred_locations_file")
+            fi
+            if [ -n "$skipped_locations_file" ]; then
+              fallback_args+=(--skipped-locations "$skipped_locations_file")
+            fi
+            if [ -n "$applyable_locations_file" ]; then
+              fallback_args+=(--applyable-locations "$applyable_locations_file")
+            fi
+            if [ -n "$leftover_diff_locations_file" ]; then
+              fallback_args+=(--leftover-diff-locations "$leftover_diff_locations_file")
+            fi
+            "${fallback_args[@]}"
           }
 
           publish_request_changes_from_control() {
@@ -5785,8 +6028,8 @@ jobs:
             fallback_body_file="$(mktemp)"
             format_request_changes_body "$control_json" "$body_file"
             build_request_changes_review_payload "$control_json" "$body_file" "$payload_file"
-            build_inline_comment_failure_body "$body_file" "$fallback_body_file"
-            create_pull_review_with_payload "REQUEST_CHANGES" "$(cat "$body_file")" "$payload_file" "$fallback_body_file"
+            build_inline_comment_failure_body "$body_file" "$fallback_body_file" "$control_json"
+            create_pull_review_with_payload "REQUEST_CHANGES" "$(cat "$body_file")" "$payload_file" "$fallback_body_file" "$body_file" "$control_json"
             rm -f "$body_file" "$payload_file" "$fallback_body_file"
           }
 

AGENTS.md

@@ -2,3 +2,8 @@
 
 <!-- CWL-ENTRY -->
 > **Agents: read the master context FIRST.** Before any work, read [`docs/CWL-MASTER-CONTEXT.md`](docs/CWL-MASTER-CONTEXT.md) (mission · naruon-as-platform + inter-component UML · cross-cutting disciplines · conventions · roadmap · current state), the live **GitHub Project #1** <https://github.com/orgs/ContextualWisdomLab/projects/1> (work/roadmap source of truth), the full spec **ContextualWisdomLab/naruon#974**, and operate the Project per [`docs/agent-github-project-protocol.md`](docs/agent-github-project-protocol.md). The repo/Project — not any private agent memory — is the source of truth.
+Materialize accepts only exact SHA-256 pins or a bounded relative `-r` include (no `.`/`..`); a lone `--require-hashes` directive is not trust evidence. See [`docs/doctoring/review-inline-comment-422-fallback.md`](docs/doctoring/review-inline-comment-422-fallback.md).
+
+
+Overview receipts treat only a closed ```suggestion fence on a non-LEFT comment as applyable. A leftover ```diff whose prose mentions the token, and every LEFT suggestion, stay leftover (`cannot-provide` / `LEFT`). Leftover receipt path/reason rows and Manual-edit excerpts strip HTML comment delimiters and metacharacters before they enter `<!-- opencode-review-overview -->`. See [`ARCHITECTURE.md`](ARCHITECTURE.md) and [`docs/doctoring/review-inline-comment-422-fallback.md`](docs/doctoring/review-inline-comment-422-fallback.md).
+Leftover overview paths that contain `-->`, `<!--`, or a suggestion fence are omitted.