Add confidence signals, human-review gate, no-op removal, and file-list targeting to docs sweeps

.github/workflows/gh-aw-docs-applies-to-sweep.md

@@ -15,6 +15,7 @@ imports:
   - gh-aw-fragments/formatting.md
   - gh-aw-fragments/rigor.md
   - gh-aw-fragments/mcp-pagination.md
+  - gh-aw-fragments/findings-contract.md
 model: claude-sonnet-5
 engine:
   id: copilot
@@ -37,6 +38,11 @@ on:
         type: string
         required: false
         default: ""
+      target-files:
+        description: "Optional newline- or comma-separated list of docs-root-relative file paths to sweep. When set, overrides target-path and scope-mode: the sweep processes exactly these files."
+        type: string
+        required: false
+        default: ""
       scope-mode:
         description: "How to scope matched markdown files: auto preserves the default behavior, full scans every matched file, and shard applies rotating shard selection within the matched set."
         type: string
@@ -111,6 +117,7 @@ steps:
     env:
       DOCS_ROOT: ${{ inputs.docs-root }}
       TARGET_PATH: ${{ inputs.target-path }}
+      TARGET_FILES: ${{ inputs.target-files }}
       SCOPE_MODE: ${{ inputs.scope-mode }}
       TARGET_BATCH: ${{ inputs.target-batch-size }}
     run: |
@@ -132,6 +139,69 @@ steps:
           ;;
       esac
 
+      # target-files overrides target-path and scope-mode: audit exactly the
+      # listed files (newline- or comma-separated, docs-root-relative).
+      if [ -n "$TARGET_FILES" ]; then
+        SELECTION_MODE="files"
+        : > /tmp/gh-aw/sweep-data/all.txt
+        : > /tmp/gh-aw/sweep-data/shard.txt
+        : > /tmp/gh-aw/sweep-data/recent.txt
+        : > /tmp/gh-aw/sweep-data/in-scope.txt
+
+        REQUESTED_COUNT=0
+        printf '%s' "$TARGET_FILES" | tr ',' '\n' > /tmp/gh-aw/sweep-data/target-files.raw
+        while IFS= read -r raw || [ -n "$raw" ]; do
+          entry=$(printf '%s' "$raw" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+          [ -z "$entry" ] && continue
+          REQUESTED_COUNT=$(( REQUESTED_COUNT + 1 ))
+          entry=${entry#/}
+          if [ "$DOCS_ROOT_CLEAN" = "." ] || [ -z "$DOCS_ROOT_CLEAN" ]; then
+            resolved="$entry"
+          else
+            case "$entry" in
+              "$DOCS_ROOT_CLEAN"/*) resolved="$entry" ;;
+              *) resolved="$DOCS_ROOT_CLEAN/$entry" ;;
+            esac
+          fi
+          if [ -f "$resolved" ]; then
+            echo "$resolved" >> /tmp/gh-aw/sweep-data/all.txt
+          else
+            echo "target-files: '$resolved' not found; skipping"
+          fi
+        done < /tmp/gh-aw/sweep-data/target-files.raw
+
+        sort -u /tmp/gh-aw/sweep-data/all.txt > /tmp/gh-aw/sweep-data/in-scope.txt
+        cp /tmp/gh-aw/sweep-data/in-scope.txt /tmp/gh-aw/sweep-data/all.txt
+
+        while IFS= read -r f; do
+          [ -z "$f" ] && continue
+          [ ! -f "$f" ] && continue
+          mkdir -p "/tmp/gh-aw/sweep-data/scope/$(dirname "$f")"
+          cp "$f" "/tmp/gh-aw/sweep-data/scope/$f"
+        done < /tmp/gh-aw/sweep-data/in-scope.txt
+
+        IN_SCOPE_COUNT=$(wc -l < /tmp/gh-aw/sweep-data/in-scope.txt | tr -d ' ')
+      cat > /tmp/gh-aw/sweep-data/stats.json <<EOF
+      {
+        "total": $IN_SCOPE_COUNT,
+        "shard_n": 1,
+        "shard_slot": 0,
+        "shard_count": $IN_SCOPE_COUNT,
+        "recent_count": 0,
+        "in_scope_count": $IN_SCOPE_COUNT,
+        "requested_count": $REQUESTED_COUNT,
+        "iso_week": "$(date +%G-W%V)",
+        "docs_root": "$DOCS_ROOT",
+        "scope_mode": "files",
+        "selection_mode": "files",
+        "target_path": "$TARGET_PATH_CLEAN",
+        "scope_root": "$DOCS_ROOT_CLEAN"
+      }
+      EOF
+        echo "Sweep targets (file list): requested=$REQUESTED_COUNT in_scope=$IN_SCOPE_COUNT"
+        exit 0
+      fi
+
       if [ -n "$TARGET_PATH_CLEAN" ]; then
         if [ "$DOCS_ROOT_CLEAN" = "." ] || [ -z "$DOCS_ROOT_CLEAN" ]; then
           SCOPE_ROOT="$TARGET_PATH_CLEAN"
@@ -312,7 +382,9 @@ Categories (use exactly these strings):
 - `inconsistent-applies-to` — `applies_to` contradicts other frontmatter (e.g., `products:` says one thing, `applies_to:` another).
 - `outdated-applies-to` — references a deployment or lifecycle value that is deprecated per the verified reference.
 
-For each finding extract `file`, `line`, `category`, `severity`, `evidence`, and `suggested_fix` when you can produce a concrete YAML snippet confidently.
+These five are the complete category allowlist for this sweep (see the **Findings contract**).
+
+For each finding extract `file`, `line`, `category`, `severity`, `confidence`, `evidence`, and `suggested_fix` when you can produce a concrete YAML snippet confidently. Set `confidence` per the **Findings contract**: syntax and value errors verified against the published reference are usually `high`; dimension-choice or convention judgments are usually `medium`.
 
 Strip the `/tmp/gh-aw/sweep-data/scope/` prefix from `file` so paths are repo-relative.
 
@@ -326,6 +398,9 @@ Cap at `${{ inputs.max-per-fix-issue }}` distinct files. If empty, call `noop` a
 - Shard mode with `target_path`: `"No applies_to issues under /<target_path> in shard <slot>/<n> (<in_scope_count> pages)"`.
 - Full mode with `target_path`: `"No applies_to issues under /<target_path> (<in_scope_count> pages)"`.
 - Full mode without `target_path`: `"No applies_to issues in full sweep <docs_root> (<in_scope_count> pages)"`.
+- Files mode: `"No applies_to issues in the requested file list (<in_scope_count> files)"`.
+
+**Files mode**: when `selection_mode` is `files`, the caller supplied an explicit file list via `target-files`; audit exactly those files and ignore `target_path`/shard framing. Use an explicit-file-list description in the title (`file list — <in_scope_count> pages`) and scope-summary (`Explicit file list · <in_scope_count> of <requested_count> requested files in scope.`).
 
 ## Output: fix-issue body
 
@@ -355,6 +430,7 @@ Use one of these scope-summary lines:
   line: 4
   category: invalid-applies-to-value
   severity: high
+  confidence: high
   evidence: "applies_to.deployment.ess uses an unrecognized deployment key; use `ech` for Elastic Cloud Hosted"
   suggested_fix: |
     applies_to:
@@ -364,6 +440,7 @@ Use one of these scope-summary lines:
   line: 1
   category: missing-applies-to
   severity: high
+  confidence: high
   evidence: "frontmatter has no applies_to key"
 ```
 
@@ -377,7 +454,7 @@ Use one of these scope-summary lines:
 <!-- gh-aw-docs-applies-to-sweep:run=<iso_week>:shard=<slot>/<n> -->
 ```
 
-Keep the YAML block parseable. Use the literal `|` block scalar for multi-line `suggested_fix` values.
+Keep the YAML block parseable — every entry must have `file`, `line`, `category`, `severity`, `confidence`, `evidence`. Use the literal `|` block scalar for multi-line `suggested_fix` values.
 
 ## What to skip