ci: add workflow-lint to sanity-check triggers and gates for ci.yml

jq parses the test() argument as a JSON string, so \s and \b must be
double-escaped (\\s, \\b) to produce literal \s and \b after JSON
string parsing. Single backslash forms are invalid JSON escapes and
cause a compile error.

.gitea/workflows/ci.yml

@@ -5,11 +5,19 @@ on:
     branches: [main]
   pull_request:
     types: [opened, synchronize]
+  issue_comment:
+    types: [created, edited]
+
+env:
+  SELF_REVIEW_TTL_MIN: '45'
 
 jobs:
   test:
     runs-on: ubuntu-24.04
+    if: github.event_name == 'pull_request'
     steps:
+      - name: Install jq
+        run: sudo apt-get update && sudo apt-get install -y jq
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
@@ -18,14 +26,58 @@ jobs:
       - run: go vet ./...
       - run: go build -o review-bot ./cmd/review-bot
 
-  # Self-review using native SAP AI Core provider
-  # Models must match SAP AI Core deployments
-  # Available models: gpt-5, anthropic--claude-4.6-sonnet, anthropic--claude-4.6-opus
-  # Removed gpt-4.1, gpt-5-mini, gpt-4.1-mini - not deployed on AI Core
+  review-gate:
+    runs-on: ubuntu-24.04
+    if: github.event_name == 'pull_request' || (github.event_name == 'issue_comment' && github.event.issue.pull_request)
+    outputs:
+      allow_review: ${{ steps.gate.outputs.allow_review }}
+      reason: ${{ steps.gate.outputs.reason }}
+    steps:
+      - name: Install jq
+        run: sudo apt-get update && sudo apt-get install -y jq
+      - name: Check self-review gate
+        id: gate
+        env:
+          GITEA_TOKEN: ${{ secrets.RODIN_TOKEN }}
+        run: |
+          set -e
+          REPO=${{ github.repository }}
+          API="${{ github.server_url }}/api/v1"
+          if [ "${GITHUB_EVENT_NAME}" = "issue_comment" ]; then
+            PR=${{ github.event.issue.number }}
+          else
+            PR=${{ github.event.pull_request.number }}
+          fi
+          # Get head SHA from PR JSON (works for both events)
+          PR_JSON=$(curl -sS -H "Authorization: token $GITEA_TOKEN" "$API/repos/$REPO/pulls/$PR")
+          SHA=$(echo "$PR_JSON" | jq -r .head.sha)
+          UPDATED_AT=$(echo "$PR_JSON" | jq -r .updated_at)
+          NOW=$(date -u +%s)
+          PR_TS=$(date -u -d "$UPDATED_AT" +%s)
+          AGE_MIN=$(( (NOW - PR_TS) / 60 ))
+          TTL_MIN=${SELF_REVIEW_TTL_MIN}
+
+          COMMENTS=$(curl -sS -H "Authorization: token $GITEA_TOKEN" "$API/repos/$REPO/issues/$PR/comments?limit=200")
+          HAS_SR=$(echo "$COMMENTS" | jq -r --arg sha "$SHA" '[.[] | select(.user.login=="rodin") | select(.body|contains("Self-review against "+$sha)) | select(.body|test("(?im)^###\\s+Doc consistency\\b"))] | length')
+
+          if [ "$HAS_SR" -gt 0 ]; then
+            ALLOW=true
+            REASON=self-review
+          elif [ "$AGE_MIN" -ge "$TTL_MIN" ]; then
+            ALLOW=true
+            REASON=ttl
+          else
+            ALLOW=false
+            REASON=missing
+          fi
+
+          echo "allow_review=$ALLOW" >> $GITHUB_OUTPUT
+          echo "reason=$REASON" >> $GITHUB_OUTPUT
+
   review:
     runs-on: ubuntu-24.04
-    if: github.event_name == 'pull_request'
-    needs: test
+    if: needs.review-gate.outputs.reason == 'self-review' && (github.event_name == 'pull_request' || github.event_name == 'issue_comment')
+    needs: [review-gate]
     strategy:
       matrix:
         include:
@@ -39,19 +91,28 @@ jobs:
             token_secret: SECURITY_REVIEW_TOKEN
             model: gpt-5
             patterns_repo: rodin/security-patterns
-            patterns_files: "."
+            patterns_files: '.'
             system_prompt_file: SECURITY_REVIEW.md
     steps:
+      - name: Install jq
+        run: sudo apt-get update && sudo apt-get install -y jq
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
           go-version: '1.26'
       - run: go build -o review-bot ./cmd/review-bot
+      - name: Set PR_NUMBER for event type
+        run: |
+          if [ "${GITHUB_EVENT_NAME}" = "issue_comment" ]; then
+            echo "PR_NUMBER=${{ github.event.issue.number }}" >> $GITHUB_ENV
+          else
+            echo "PR_NUMBER=${{ github.event.pull_request.number }}" >> $GITHUB_ENV
+          fi
       - name: Run ${{ matrix.name }} review
         env:
           VCS_URL: ${{ github.server_url }}
           GITEA_REPO: ${{ github.repository }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_NUMBER: ${{ env.PR_NUMBER }}
           REVIEWER_TOKEN: ${{ secrets[matrix.token_secret] }}
           REVIEWER_NAME: ${{ matrix.name }}
           LLM_PROVIDER: aicore
@@ -61,9 +122,9 @@ jobs:
           AICORE_AUTH_URL: ${{ secrets.AICORE_AUTH_URL }}
           AICORE_API_URL: ${{ secrets.AICORE_API_URL }}
           AICORE_RESOURCE_GROUP: ${{ secrets.AICORE_RESOURCE_GROUP }}
-          CONVENTIONS_FILE: "CONVENTIONS.md"
+          CONVENTIONS_FILE: 'CONVENTIONS.md'
           PATTERNS_REPO: ${{ matrix.patterns_repo || 'rodin/go-patterns' }}
           PATTERNS_FILES: ${{ matrix.patterns_files || 'README.md,patterns/' }}
-          LLM_TIMEOUT: "600"
+          LLM_TIMEOUT: '600'
           SYSTEM_PROMPT_FILE: ${{ matrix.system_prompt_file }}
         run: ./review-bot

.gitea/workflows/workflow-lint.yml

@@ -0,0 +1,42 @@
+name: Workflow Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  workflow-sanity:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Sanity check ci.yml triggers and gates
+        run: |
+          set -euo pipefail
+          python3 - <<'PY'
+import sys, yaml, re
+from pathlib import Path
+p = Path('.gitea/workflows/ci.yml')
+w = yaml.safe_load(p.read_text())
+# 1) Top-level 'on' must exist and include pull_request + issue_comment
+on = w.get('on')
+assert isinstance(on, dict), "ci.yml: top-level 'on' must be a mapping"
+assert 'pull_request' in on, "ci.yml: missing on.pull_request"
+assert 'issue_comment' in on, "ci.yml: missing on.issue_comment (self-review trigger)"
+pr_types = on['pull_request'].get('types', []) if isinstance(on['pull_request'], dict) else []
+ic_types = on['issue_comment'].get('types', []) if isinstance(on['issue_comment'], dict) else []
+for t in ['opened','synchronize']:
+    assert t in pr_types, f"ci.yml: pull_request.types must include '{t}'"
+for t in ['created','edited']:
+    assert t in ic_types, f"ci.yml: issue_comment.types must include '{t}'"
+# 2) review-gate must run on both PR and issue_comment (if condition string)
+rg_if = w['jobs']['review-gate'].get('if','')
+assert 'github.event_name == ' in rg_if and 'issue_comment' in rg_if and 'pull_request' in rg_if, \
+    "ci.yml: review-gate.if must include both pull_request and issue_comment"
+# 3) review job must require self-review reason
+rev_if = w['jobs']['review'].get('if','')
+assert "needs.review-gate.outputs.reason == 'self-review'" in rev_if, \
+    "ci.yml: review.if must require reason=='self-review'"
+print('OK: ci.yml triggers and gates look sane')
+PY

cmd/review-bot/main_test.go

@@ -903,12 +903,17 @@ func TestMainSubprocess_InvalidRepo(t *testing.T) {
 		flag.CommandLine = flag.NewFlagSet(os.Args[0], flag.ExitOnError)
 		args := baseSubprocessArgs()
 		// Replace the canonical --repo value with an invalid one.
+		found := false
 		for i, a := range args {
 			if a == "--repo" && i+1 < len(args) {
 				args[i+1] = "invalidrepo"
+				found = true
 				break
 			}
 		}
+		if !found {
+			t.Fatal("baseSubprocessArgs() does not contain --repo; test is broken")
+		}
 		os.Args = args
 		main()
 		return
@@ -930,12 +935,17 @@ func TestMainSubprocess_InvalidPRNumber(t *testing.T) {
 		flag.CommandLine = flag.NewFlagSet(os.Args[0], flag.ExitOnError)
 		args := baseSubprocessArgs()
 		// Replace the canonical --pr value with a non-numeric string.
+		found := false
 		for i, a := range args {
 			if a == "--pr" && i+1 < len(args) {
 				args[i+1] = "notanumber"
+				found = true
 				break
 			}
 		}
+		if !found {
+			t.Fatal("baseSubprocessArgs() does not contain --pr; test is broken")
+		}
 		os.Args = args
 		main()
 		return

cmd/review-bot/validatedocmap.go

@@ -61,6 +61,13 @@ func validateDocmapPath(localPath, resolvedRoot string) error {
 		return fmt.Errorf("symlinks are not allowed")
 	}
 
+	// Reject anything that is not a regular file (directories, FIFOs, device
+	// nodes, etc.) — ParseDocMapConfig expects a plain YAML file and would
+	// produce a confusing error on non-regular entries.
+	if !fi.Mode().IsRegular() {
+		return fmt.Errorf("docmap must be a regular file")
+	}
+
 	// Confine to resolvedRoot: use the fully-resolved path so that a directory
 	// symlink inside the repo cannot carry the path outside the root.
 	rel, err := filepath.Rel(resolvedRoot, resolvedPath)
@@ -171,6 +178,9 @@ func runValidateDocmap(args []string) int {
 		// Normalize Windows-style backslashes to forward slashes so that
 		// changed-file paths from git on Windows match doc-map globs.
 		f = strings.ReplaceAll(f, "\\", "/")
+		// Strip a leading "./" emitted by non-git tools (e.g. `find`) so that
+		// paths like "./cmd/foo.go" match doc-map globs written as "cmd/**".
+		f = strings.TrimPrefix(f, "./")
 		if !review.FileCoveredByDocMap(cfg, f) {
 			uncovered = append(uncovered, f)
 		}
@@ -189,7 +199,7 @@ func runValidateDocmap(args []string) int {
 	staleDocs := checkStaleDocs(cfg, resolvedRoot)
 	if len(staleDocs) > 0 {
 		failed = true
-		fmt.Fprintln(errWriter, "ERROR: stale docmap docs: entries (paths do not exist):")
+		fmt.Fprintln(errWriter, "ERROR: stale docmap entries (paths do not exist):")
 		for _, d := range staleDocs {
 			fmt.Fprintf(errWriter, "  %s\n", d)
 		}

cmd/review-bot/validatedocmap_test.go

@@ -599,3 +599,53 @@ func TestValidateDocmapPath_DirSymlinkBypass(t *testing.T) {
 		t.Error("expected rejection of dir-symlink bypass, got nil error")
 	}
 }
+
+// TestValidateDocmapPath_NonRegularFile verifies that --docmap pointing at a
+// non-regular file (e.g. a directory) is rejected with a clear error before
+// ParseDocMapConfig is called.
+func TestValidateDocmapPath_NonRegularFile(t *testing.T) {
+	dir := t.TempDir()
+
+	// Use the directory itself as the docmap path — directories pass Lstat but
+	// are not regular files.
+	reviewBotDir := filepath.Join(dir, ".review-bot")
+	if err := os.MkdirAll(reviewBotDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+
+	code, _, stderr := stdinValidateDocmap(t,
+		"",
+		[]string{"--docmap", reviewBotDir, "--repo-root", dir},
+	)
+	if code != 2 {
+		t.Errorf("expected exit 2 for directory docmap, got %d; stderr: %q", code, stderr)
+	}
+	if !strings.Contains(stderr, "regular file") && !strings.Contains(stderr, "invalid") {
+		t.Errorf("expected regular-file rejection in stderr, got %q", stderr)
+	}
+}
+
+// TestRunValidateDocmap_DotSlashPrefix verifies that paths emitted with a
+// leading "./" (e.g. from `find` or `ls`) match doc-map globs correctly.
+// Without TrimPrefix, "./cmd/foo.go" would not match the pattern "cmd/**".
+func TestRunValidateDocmap_DotSlashPrefix(t *testing.T) {
+	dir := t.TempDir()
+	makeDocFile(t, dir, "docs/foo.md")
+
+	docmap := makeDocmapInDir(t, dir, `
+mappings:
+  - paths:
+      - "cmd/**"
+    docs:
+      - docs/foo.md
+`)
+
+	// File with a leading "./" should be treated as covered.
+	code, _, stderr := stdinValidateDocmap(t,
+		"./cmd/foo.go\n",
+		[]string{"--docmap", docmap, "--repo-root", dir},
+	)
+	if code != 0 {
+		t.Errorf("expected exit 0 for './' prefixed covered file, got %d; stderr: %q", code, stderr)
+	}
+}