fix(sdk-review): FP-R-01 (docstring URLs) + FP-S-01 (Session in __init__) + COM-01 squash-subject

Three more FPs surfaced reviewing what actually posted to py#161:

FP-R-01: HC-01 fired on 'https://dms.example.com/...' inside a docstring
  Example: block — documentation, not runtime code. Added 'docstring-lines'
  AST helper; check-hardcode skips URLs on docstring lines (Python).

FP-S-01: HTTP-01 fired on requests.Session() created in __init__ — which is
  the pattern the rule RECOMMENDS. Added 'http-session-lines' AST helper that
  lists only sessions created OUTSIDE __init__ (per-invocation); check-http-
  hygiene fires only on those.

COM-01: rewritten to check a single subject — the PR title (squash-merge
  subject that lands on main), falling back to HEAD's non-merge subject.
  Was emitting one finding per intermediate commit (33 on py#161); those
  messages are discarded by squash-merge. orchestrate now exports PR_TITLE.

Net effect on py#161: 8 BLOCK + 34 FLAG  →  4 BLOCK + 0 FLAG, all 4 real TPs
(DIS-07, DC-02, PY-TEL-06, TD-10 on a genuinely new module). Zero FP.
Bats 81/81 both repos.

Author: tiagoek

.claude/scripts/check-commits.sh

@@ -1,47 +1,42 @@
 #!/usr/bin/env bash
 # check-commits.sh — Conventional Commits enforcement.
+#
+# The repos squash-merge PRs, so ONLY the final squashed subject (which
+# defaults to the PR title) becomes a commit on main. Checking every
+# intermediate commit floods the review with findings for messages that
+# will be discarded. We therefore check a single subject:
+#   1. PR_TITLE  (env, set by orchestrate from the PR metadata) if available
+#   2. else the most recent non-merge commit subject (HEAD)
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/lib/json-emit.sh"
 
 LANGUAGE="${LANGUAGE:-python}"
-# Resolve BASE_SHA from GITHUB_BASE_REF merge-base when not explicitly set —
-# HEAD~10 is a poor fallback (only reachable when the PR has ≥10 commits).
-if [ -z "${BASE_SHA:-}" ]; then
-  base_ref="${GITHUB_BASE_REF:-main}"
-  # Try origin/<ref>, then <ref>, then finally HEAD~10 as last resort
-  if git rev-parse --verify "origin/${base_ref}" >/dev/null 2>&1; then
-    BASE_SHA=$(git merge-base HEAD "origin/${base_ref}" 2>/dev/null || echo "HEAD~10")
-  elif git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
-    BASE_SHA=$(git merge-base HEAD "$base_ref" 2>/dev/null || echo "HEAD~10")
-  else
-    BASE_SHA="HEAD~10"
-  fi
-fi
 HEAD_SHA="${HEAD_SHA:-HEAD}"
+PR_TITLE="${PR_TITLE:-}"
 
 STARTED=$(now_iso)
 findings=$(mktemp); trap 'rm -f "$findings"' EXIT
 
-# List commit subjects
-commits=$(git log "${BASE_SHA}..${HEAD_SHA}" --format='%H %s' 2>/dev/null || echo "")
 prefix_regex='^(feat|fix|refactor|chore|docs|test|ci|build|perf|style|revert)(\([a-z0-9_/-]+\))?!?:[[:space:]]+.+'
 
-echo "$commits" | while IFS= read -r line; do
-  [ -z "$line" ] && continue
-  sha=$(echo "$line" | cut -d' ' -f1)
-  subject=$(echo "$line" | cut -d' ' -f2-)
-  # Skip merge commits (identified by 2+ parents, robust regardless of message shape)
-  parents=$(git rev-list --parents -n 1 "$sha" 2>/dev/null | awk '{print NF-1}')
-  if [ "${parents:-0}" -gt 1 ]; then continue; fi
-  # Also skip legacy "Merge branch/pull/etc" defaults
-  if echo "$subject" | grep -qiE '^Merge '; then continue; fi
+# Pick the single subject that will land on main after squash-merge.
+if [ -n "$PR_TITLE" ]; then
+  subject="$PR_TITLE"
+  location="PR_TITLE"
+else
+  # Most recent non-merge commit subject.
+  subject=$({ git log "$HEAD_SHA" --no-merges -1 --format='%s' 2>/dev/null || true; })
+  location="COMMIT:$({ git rev-parse "$HEAD_SHA" 2>/dev/null || echo HEAD; })"
+fi
+
+if [ -n "$subject" ] && ! echo "$subject" | grep -qiE '^Merge '; then
   if ! echo "$subject" | grep -qE "$prefix_regex"; then
-    emit_finding "COM-01" "FLAG" "COMMIT:$sha" 1 \
-      "Commit '$subject' does not follow Conventional Commits" \
-      "Prefix with feat:/fix:/chore:/docs:/test:/refactor:/ci:/build:/perf:/style:/revert:" >> "$findings"
+    emit_finding "COM-01" "FLAG" "$location" 1 \
+      "Squash-merge subject '$subject' does not follow Conventional Commits" \
+      "The PR title becomes the squashed commit — prefix with feat:/fix:/chore:/docs:/test:/refactor:/ci:/build:/perf:/style:/revert:" >> "$findings"
   fi
-done
+fi
 
 status=$(status_from_findings < "$findings")
 emit_report "commits" "$LANGUAGE" "$status" "$STARTED" < "$findings"

.claude/scripts/check-hardcode.sh

@@ -69,6 +69,21 @@ echo "$diff_content" | awk -v ignore="$ignore_files" '
   [ -z "$file" ] && continue
   if [ "$(is_skill_file "$file")" = "true" ]; then continue; fi
 
+  # FP-R-01: skip URLs that live inside a Python docstring (documentation
+  # examples, not runtime code). Compute the docstring line set once per file.
+  if [ "$LANGUAGE" = "python" ] && echo "$file" | grep -q '\.py$'; then
+    if [ "${_docstring_file:-}" != "$file" ]; then
+      _docstring_file="$file"
+      _docstring_lines=""
+      if [ -f "$REPO_ROOT/$file" ]; then
+        _docstring_lines=$(python3 "$SCRIPT_DIR/lib/ast_python_checks.py" docstring-lines "$REPO_ROOT/$file" 2>/dev/null || echo "")
+      fi
+    fi
+    if [ -n "$_docstring_lines" ] && echo "$_docstring_lines" | grep -qx "$line_num"; then
+      continue
+    fi
+  fi
+
   # HC-01: hardcoded URL. Extract each URL and check individually so a line
   # with both example.com (allowed) and api.com (real) still fires on the real one.
   # Use word boundary via (^|[^A-Za-z0-9]) so we don't match tokens inside identifiers.

.claude/scripts/check-http-hygiene.sh

@@ -40,6 +40,19 @@ echo "$diff_content" | awk '
   [ -z "$file" ] && continue
   if [ "$(is_skill_file "$file")" = "true" ]; then continue; fi
   if echo "$content" | grep -qE '(requests|httpx)\.(Session|AsyncClient)\(\)'; then
+    # FP-S-01: a Session created in __init__ is the RECOMMENDED pattern, not a
+    # finding. Use AST to confirm this line is a per-invocation session (i.e.
+    # created outside __init__). Only fire if the line is in that set. When the
+    # file isn't on disk (no REPO_ROOT context), fall back to firing.
+    if [ "$LANGUAGE" = "python" ] && echo "$file" | grep -q '\.py$' && [ -f "$REPO_ROOT/$file" ]; then
+      if [ "${_http_file:-}" != "$file" ]; then
+        _http_file="$file"
+        _http_lines=$(python3 "$SCRIPT_DIR/lib/ast_python_checks.py" http-session-lines "$REPO_ROOT/$file" 2>/dev/null || echo "")
+      fi
+      if ! echo "$_http_lines" | grep -qx "$line_num"; then
+        continue  # session is in __init__ (or class/module level) → correct pattern
+      fi
+    fi
     emit_finding_if_touched "HTTP-01" "FLAG" "$file" "$line_num" \
       "HTTP session created per invocation — prefer single instance in __init__" "" >> "$findings"
   fi

.claude/scripts/lib/ast_python_checks.py

@@ -501,6 +501,64 @@ def main(argv: list[str]) -> int:
         module_dir = files[0]
         return 0 if check_pt_04(module_dir) else 1
 
+    # FP-R-01: docstring-lines prints "1" for every line number that falls
+    # inside a module/class/function docstring, so line-based checks (e.g.
+    # check-hardcode HC-01) can skip URLs that live in documentation examples.
+    if check_name == "docstring-lines":
+        for f in files:
+            tree = parse_file(f)
+            if tree is None:
+                continue
+            for node in ast.walk(tree):
+                if not isinstance(
+                    node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+                ):
+                    continue
+                doc = ast.get_docstring(node, clean=False)
+                if not doc:
+                    continue
+                # The docstring is the first statement's Constant node.
+                body = getattr(node, "body", [])
+                if not body:
+                    continue
+                first = body[0]
+                if (
+                    isinstance(first, ast.Expr)
+                    and isinstance(first.value, ast.Constant)
+                    and isinstance(first.value.value, str)
+                ):
+                    start = first.value.lineno
+                    end = getattr(first.value, "end_lineno", start)
+                    for ln in range(start, end + 1):
+                        print(ln)
+        return 0
+
+    # FP-S-01: http-session-lines prints the line number of every
+    # requests.Session()/httpx.Client()/AsyncClient() call that is NOT inside
+    # __init__ (or a module/class-level assignment). A session created in
+    # __init__ is the RECOMMENDED pattern, so HTTP-01 must not fire on it.
+    # Only lines printed here are per-invocation sessions worth flagging.
+    if check_name == "http-session-lines":
+        SESSION_CTORS = {"Session", "Client", "AsyncClient"}
+        for f in files:
+            tree = parse_file(f)
+            if tree is None:
+                continue
+            # Map every function def to whether it is __init__.
+            for node in ast.walk(tree):
+                if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+                if node.name == "__init__":
+                    continue  # sessions here are the correct pattern
+                for sub in ast.walk(node):
+                    if (
+                        isinstance(sub, ast.Call)
+                        and isinstance(sub.func, ast.Attribute)
+                        and sub.func.attr in SESSION_CTORS
+                    ):
+                        print(sub.lineno)
+        return 0
+
     if check_name not in CHECKS:
         print(f"ERROR: unknown check {check_name}", file=sys.stderr)
         return 2

.claude/scripts/orchestrate.sh

@@ -57,6 +57,9 @@ fi
 if [ "$DRY_RUN" != "true" ]; then
   gh pr view "$PR_NUMBER" --json body -q .body > "$TMPDIR_RUN/pr-body.txt" 2>/dev/null || echo "" > "$TMPDIR_RUN/pr-body.txt"
   HEAD_SHA=$(get_pr_head_sha "$PR_NUMBER")
+  # PR title feeds check-commits (squash-merge subject). Non-fatal if it fails.
+  PR_TITLE=$(gh pr view "$PR_NUMBER" --json title -q .title 2>/dev/null || echo "")
+  export PR_TITLE
 elif [ -n "${LOCAL_PR_BODY:-}" ] && [ -f "$LOCAL_PR_BODY" ]; then
   cp "$LOCAL_PR_BODY" "$TMPDIR_RUN/pr-body.txt"
   HEAD_SHA="${HEAD_SHA:-HEAD}"