@@ -0,0 +1,101 @@
+"""Semantic duplicate detection for a newly opened GitHub issue.
+
+Reads {"current": {...}, "others": [...]} from issues_json (written by the
+calling workflow via the GitHub API) and writes a ranked list of likely
+duplicates to matches_json.
+
+THRESHOLD was empirically calibrated against confirmed duplicate/non-duplicate
+issue pairs in AOSSIE-Org/PictoPy: real duplicates scored 0.56-0.85, unrelated
+issues (including ones sharing identical issue-template boilerplate) scored
+<= 0.31. 0.55 sits in the gap with margin on both sides.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+THRESHOLD = 0.55
+MAX_RESULTS = 3
+
+
+def issue_text(issue: dict) -> str:
+    return f"{issue['title']} {issue['body']}".strip()
+
+
+def dot_product(a: list[float], b: list[float]) -> float:
+    return sum(x * y for x, y in zip(a, b))
+
+
+def find_duplicates(
+    current_embedding: list[float],
+    other_embeddings: list[list[float]],
+    others: list[dict],
+    threshold: float = THRESHOLD,
+    max_results: int = MAX_RESULTS,
+) -> list[dict]:
+    # Embeddings are normalized, so dot product equals cosine similarity.
+    # Sort by the raw score, not the rounded display value, so close scores
+    # that round to the same tenth (e.g. 90.04 vs 90.01) still rank correctly.
+    scored: list[tuple[float, dict]] = []
+    for issue, embedding in zip(others, other_embeddings):
+        score = dot_product(current_embedding, embedding) * 100
+        if score >= threshold * 100:
+            scored.append(
+                (
+                    score,
+                    {
+                        "number": issue["number"],
+                        "title": issue["title"],
+                        "url": issue["url"],
+                        "state": issue["state"],
+                        "score": round(score, 1),
+                    },
+                )
+            )
+    scored.sort(key=lambda item: -item[0])
+    return [match for _, match in scored[:max_results]]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("issues_json", type=Path)
+    parser.add_argument("matches_json", type=Path)
+    parser.add_argument("--threshold", type=float, default=THRESHOLD)
+    args = parser.parse_args()
+
+    data = json.loads(args.issues_json.read_text(encoding="utf-8"))
+    current = data["current"]
+    others = data["others"]
+
+    print(f"Threshold = {args.threshold}")
+    print(f"Current issue: #{current['number']}")
+    print(f"Candidate issues: {len(others)}")
+
+    if not others:
+        args.matches_json.write_text("[]", encoding="utf-8")
+        return
+
+    from sentence_transformers import SentenceTransformer
+
+    model = SentenceTransformer("all-MiniLM-L6-v2")
+    embeddings = model.encode(
+        [issue_text(current)] + [issue_text(o) for o in others],
+        normalize_embeddings=True,
+    ).tolist()
+
+    current_embedding, other_embeddings = embeddings[0], embeddings[1:]
+
+    for issue, embedding in zip(others, other_embeddings):
+        score = dot_product(current_embedding, embedding) * 100
+        print(f"Issue #{issue['number']} | Score={score:.1f} | Title={issue['title']}")
+
+    matches = find_duplicates(
+        current_embedding, other_embeddings, others, args.threshold
+    )
+    args.matches_json.write_text(json.dumps(matches), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,74 @@
+"""Run with: python .github/scripts/test_detect_duplicate_issue.py"""
+
+from detect_duplicate_issue import dot_product, find_duplicates
+
+
+def test_dot_product_matches_cosine_similarity_for_normalized_vectors() -> None:
+    assert dot_product([1.0, 0.0], [0.0, 1.0]) == 0.0
+    assert dot_product([1.0, 0.0], [1.0, 0.0]) == 1.0
+
+
+def test_find_duplicates_filters_below_threshold_and_sorts_descending() -> None:
+    others = [
+        {"number": 1, "title": "unrelated", "url": "u1", "state": "open"},
+        {"number": 2, "title": "near duplicate", "url": "u2", "state": "open"},
+        {"number": 3, "title": "borderline duplicate", "url": "u3", "state": "closed"},
+    ]
+    current_embedding = [1.0, 0.0]
+    other_embeddings = [[0.3, 0.0], [0.9, 0.0], [0.6, 0.0]]
+
+    matches = find_duplicates(
+        current_embedding, other_embeddings, others, threshold=0.55
+    )
+
+    assert [m["number"] for m in matches] == [2, 3]
+    assert matches[0]["score"] == 90.0
+
+
+def test_find_duplicates_ranks_by_raw_score_not_rounded_display_value() -> None:
+    others = [
+        {
+            "number": 1,
+            "title": "lower raw score, ties at 90.0 when rounded",
+            "url": "u1",
+            "state": "open",
+        },
+        {
+            "number": 2,
+            "title": "higher raw score, also ties at 90.0 when rounded",
+            "url": "u2",
+            "state": "open",
+        },
+        {"number": 3, "title": "clear top match", "url": "u3", "state": "open"},
+    ]
+    current_embedding = [1.0]
+    other_embeddings = [[0.9001], [0.9004], [0.95]]
+
+    matches = find_duplicates(
+        current_embedding, other_embeddings, others, threshold=0.5, max_results=2
+    )
+
+    assert [m["number"] for m in matches] == [3, 2]
+    assert matches[1]["score"] == 90.0
+
+
+def test_find_duplicates_respects_max_results() -> None:
+    others = [
+        {"number": i, "title": "t", "url": "u", "state": "open"} for i in range(5)
+    ]
+    current_embedding = [1.0]
+    other_embeddings = [[0.9] for _ in others]
+
+    matches = find_duplicates(
+        current_embedding, other_embeddings, others, threshold=0.5, max_results=3
+    )
+
+    assert len(matches) == 3
+
+
+if __name__ == "__main__":
+    test_dot_product_matches_cosine_similarity_for_normalized_vectors()
+    test_find_duplicates_filters_below_threshold_and_sorts_descending()
+    test_find_duplicates_ranks_by_raw_score_not_rounded_display_value()
+    test_find_duplicates_respects_max_results()
+    print("All tests passed.")
@@ -1,4 +1,4 @@
-name: Smart Duplicate Issue Detector (Semantic)
+name: Issue Triage
 
 on:
   issues:
@@ -8,18 +8,40 @@ permissions:
   issues: write
 
 jobs:
+  welcome-comment:
+    if: |
+      github.event.issue.author_association != 'OWNER' &&
+      github.event.issue.author_association != 'MEMBER' &&
+      github.event.issue.author_association != 'COLLABORATOR'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Add comment to issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: "👋 Thanks for opening this issue! The maintainers will review it shortly. Till then, do not open any PR. This is a strict rule we like to follow around here :)"
+            })
+
   detect-duplicates:
     runs-on: ubuntu-latest
 
     steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
 
       - name: Install dependencies
         run: |
-          pip install --no-cache-dir sentence-transformers scikit-learn
+          pip install --no-cache-dir sentence-transformers
 
       - name: Fetch upstream issues (AOSSIE-Org/PictoPy)
         uses: actions/github-script@v7
@@ -58,67 +80,7 @@ jobs:
             fs.writeFileSync("issues.json", JSON.stringify(data));
 
       - name: Run semantic similarity analysis
-        run: |
-          python << 'EOF'
-          import json
-          from sentence_transformers import SentenceTransformer
-          from sklearn.metrics.pairwise import cosine_similarity
-
-          THRESHOLD = 0.82
-          MAX_RESULTS = 3
-          print(f"Threshold = {THRESHOLD}")
-
-          with open("issues.json") as f:
-            data = json.load(f)
-
-          model = SentenceTransformer("all-MiniLM-L6-v2")
-
-          def text(issue):
-            return f"{issue['title']} {issue['body']}".strip()
-
-          current_text = text(data["current"])
-          others = data["others"]
-          print(f"Current issue: #{data['current']['number']}")
-          print(f"Candidate issues: {len(others)}")
-
-          if not others:
-            with open("matches.json", "w") as f:
-              json.dump([], f)
-            exit()
-
-          embeddings = model.encode(
-            [current_text] + [text(i) for i in others],
-            normalize_embeddings=True
-          )
-
-          current_vec = embeddings[0]
-          other_vecs = embeddings[1:]
-
-          sims = cosine_similarity([current_vec], other_vecs)[0]
-
-          matches = []
-
-          for issue, score in zip(others, sims):
-              print(
-                  f"Issue #{issue['number']} | "
-                  f"Score={score:.4f} | "
-                  f"Title={issue['title']}"
-              )
-
-              if score >= THRESHOLD:
-                  matches.append({
-                      "number": issue["number"],
-                      "title": issue["title"],
-                      "url": issue["url"],
-                      "state": issue["state"],
-                      "score": round(float(score) * 100, 1)
-                  })
-
-          matches = sorted(matches, key=lambda x: x["score"], reverse=True)[:MAX_RESULTS]
-
-          with open("matches.json", "w") as f:
-            json.dump(matches, f)
-          EOF
+        run: python .github/scripts/detect_duplicate_issue.py issues.json matches.json
 
       - name: Comment and soft-label in fork (non-blocking)
         uses: actions/github-script@v7