claude-dev-env 1.38.0 → 1.39.0

package/CLAUDE.md

@@ -1,54 +1,28 @@
 # Claude Development Assistant
 
- The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
+The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
 
 ## Code Rules
 @~/.claude/docs/CODE_RULES.md
 
+When a UNC path is mapped to a drive letter, ALWAYS prefer the drive letter and NEVER use UNC.
+
+## GOTCHAS
+When making code changes, make sure you are working in the proper worktree path for the task at hand.
+When writing to an existing file, you must either EDIT the file, or remove it and THEN re-write it if it's truly a full re-write.
+
 ## File-Global Constants
 
 **file_global_constants_use_count:** Every module-level constant in production code outside `config/` must be referenced by at least two methods, functions, or classes in the same file. One reference → move to `config/` and import as a local alias. Zero references → delete (dead code). Test files are exempt.
 
 Full rule including the decision table, examples, and exemption details: [`packages/claude-dev-env/rules/file-global-constants.md`](rules/file-global-constants.md).
 
-## SOLID Principles
-
-**SRP (Single Responsibility)** always applies: one reason to change per function, class, or module — regardless of paradigm.
-
-**OCP, LSP, ISP, DIP** apply where two or more concrete implementations already share a contract. With a single concretion, Right-Sized Engineering takes precedence: use concrete classes, functions when no state, and direct imports. Refactor toward OCP/DIP at the commit that introduces the second concrete implementation.
-
-Full rule including the reconciliation with Right-Sized Engineering, misapplication signals, and when-it-adds-value criteria: [`packages/claude-dev-env/docs/CODE_RULES.md`](docs/CODE_RULES.md) §7.5.
-
-## Core Philosophy
+## Test Philosophy
 
-**TDD IS NON-NEGOTIABLE.** Build it right, build it simple. Maintainable > Clever.
+When writing tests, always write tests that actually test the behavior of the function against actual, real data and environments.
 
-## Expectations for Claude
-
-1. **ALWAYS FOLLOW TDD** - No production code without failing test
-2. **MANDATORY SELF-CHECK before proposing** - See protocol below
-3. Assess refactoring after every green
-
-**BEFORE proposing plans/implementation:**
-
-☐ "Is this KISS?" (simplest? unnecessary complexity?)
-☐ "Over-engineering?" (multiple files? premature abstractions?)
-☐ Test infrastructure? (ONE file, functions, YAGNI)
-☐ Tests add value? (no existence checks, no constant tests)
-☐ Files (proper modules, correct dirs, no empty __init__.py)
-☐ Quality (DRY, types complete, no Any/any)
+When writing tests, always ensure you utilize the production code paths instead of duplicating explicitly for the test.
 
 ## Additional Non-overlapping Rules
 
 - **task_scope:** Match every action to what was explicitly requested. When intent is ambiguous, research official docs and present options via AskUserQuestion before making any changes. Proceed with edits only on explicit instruction.
-
-## Tool Policies
-- **context7:** Before writing code using any library/framework/SDK/API, call `resolve-library-id` then `query-docs` via Context7 MCP. Use the fetched docs to write code. Applies to all libs including React, Next.js, Django, Express, Prisma.
-- **gh MCP:** Always use `mcp__plugin_github_github__*` tools for any GitHub operations (branches, PRs, file operations). Do not use the `Bash` tool to invoke `gh` or `git` CLI for GitHub operations.
-
-## Compaction
-When compacting, always preserve:
-- Active task and current goal
-- Full list of modified files
-- Any failing test names or error messages
-- Current git branch and PR state

package/_shared/pr-loop/audit-reply-template.md

@@ -0,0 +1,147 @@
+# Audit reply template
+
+Canonical reply shape for every orchestrator-to-thread reply posted by the PR-loop suite (`pr-converge`, `bugteam`, `qbug`, and the `clean-coder` agent). Every reply Claude posts to an unresolved review thread on a draft PR uses this template.
+
+Read this doc before authoring any code that posts a reply. The template is the contract emitted by every `clean-coder` reply path; the audit-skill wiring (`bugteam`, `qbug`, `pr-converge`) reads it before authoring a reply.
+
+This doc has two surfaces, called out separately so consumers do not conflate them: the **reply template** (this section and below) shapes the body Claude posts back to a single review thread; the **audit body skeleton** in [Relationship to the audit review body](#relationship-to-the-audit-review-body) shapes the parent review `post_audit_thread.py` posts at audit time. The reply-template consumers are the four skills/agents listed above (read-only `findbugs` is excluded — it posts an audit review via `post_audit_thread.py` but never authors thread replies). The audit-body-skeleton consumers include `findbugs` alongside `bugteam` and `qbug` because all three skills post audit reviews via the same script.
+
+## Provenance
+
+The template mirrors Anthropic's `claude[bot]` reply structure observed on `anthropics/claude-code`. Reference example: PR `anthropics/claude-code#10826`, inline comment `2483980211`. Reading that thread shows the structural anchors this template captures: a status header line, a horizontal-rule separator, an `<action_heading> ✅` section, a plain-language explanation, anchored `**`<file>:<line>`:**` bullets, and a closing paragraph.
+
+## When the template applies
+
+Every reply path uses the same skeleton. Two paths exist; both produce a reply with the structure below.
+
+| Path | When the orchestrator picks it | Code-side action |
+|---|---|---|
+| Fix | Thread classified `still_applies`. Code change addresses the finding. | `clean-coder` commits the fix, pushes, then replies. |
+| No-longer-applies | Thread classified `no_longer_applies`. Concern is moot under the current code (file removed, intent satisfied differently, refactor obviated the concern). | No code change. Orchestrator posts the reply directly. |
+
+## Template skeleton
+
+```
+**Claude finished @<reviewer>'s task** —— <status_line>
+
+---
+### <action_heading> ✅
+
+<1–2 paragraph plain-language explanation>
+
+**`<file>:<line>`:**
+- <bullet describing change or rationale>
+- <bullet describing change or rationale>
+
+<closing paragraph>
+```
+
+### Placeholder reference
+
+| Placeholder | Required value |
+|---|---|
+| `<reviewer>` | GitHub login of the reviewer whose thread the reply addresses (e.g., `cursor[bot]`, `copilot-pull-request-reviewer[bot]`, `claude[bot]`, the bugteam-account login, a human reviewer's login). |
+| `<status_line>` | One of two fixed strings, see [Per-path variation](#per-path-variation). |
+| `<action_heading>` | Per-path content, see [Per-path variation](#per-path-variation). |
+| `<file>:<line>` | Path relative to repo root and the line number the reviewer anchored to. Multiple `**`<file>:<line>`:**` blocks are allowed when the reply spans more than one anchor in the same thread. |
+| Bullets | Two or more bullets per anchor block. Each bullet is one sentence. |
+| Closing paragraph | One paragraph that ties the bullets back to the reviewer's concern. Affirmative phrasing only. |
+
+The separator between the header and `<action_heading>` is a Markdown horizontal rule (`---`) on its own line. The em-dash separator inside the header line is `——` (two em-dashes, U+2014 ×2). Both render correctly on GitHub.
+
+## Per-path variation
+
+| Path | `<status_line>` | `<action_heading>` |
+|---|---|---|
+| Fix | `Fixed in <SHA>` (short SHA, 7 characters) | Finding-specific action verb. Example: `Replaced Any with concrete type`, `Renamed handle_request to dispatch_webhook`, `Added missing Raises: section`. |
+| No longer applies | `This concern no longer applies` | Reason-specific. Example: `File removed in commit <SHA>`, `Intent satisfied via refactor in commit <SHA>`, `Concern superseded by upstream change`. |
+
+## Structural identity rule
+
+The skeleton is identical across both paths. The only per-path differences are `<status_line>` and `<action_heading>`. Every other element is present in both paths:
+
+- The header line with `**Claude finished @<reviewer>'s task** —— <status_line>` is present in both paths.
+- The horizontal rule separator is present in both paths.
+- The `### <action_heading> ✅` line is present in both paths.
+- The plain-language explanation is present in both paths.
+- The `**`<file>:<line>`:**` bullet blocks are present in both paths. On the fix path, bullets describe what changed. On the no-longer-applies path, bullets describe why the concern is moot at that anchor.
+- The closing paragraph is present in both paths.
+
+A reply that omits any of these elements does not satisfy the template.
+
+## Worked example — fix path
+
+Reviewer thread (synthesized for this doc):
+
+> `cursor[bot]` on `src/foo.py:42`:
+> The `handle_request` function returns `Any`. Name the concrete return type so callers do not lose type information.
+
+Reply posted by `clean-coder` after committing the fix at SHA `a3f9c12`:
+
+```markdown
+**Claude finished @cursor[bot]'s task** —— Fixed in a3f9c12
+
+---
+### Replaced Any with concrete return type ✅
+
+The reviewer's concern is correct: returning `Any` from a public function erases type information for every caller and defeats `mypy`'s ability to catch shape mismatches downstream. The fix names the concrete return type the function already produces.
+
+**`src/foo.py:42`:**
+- Changed the return annotation from `Any` to `RequestOutcome`.
+- Renamed the function from `handle_request` to `dispatch_webhook` to comply with the banned-prefix rule (`handle_` is one of the banned function prefixes per `CODE_RULES.md`).
+- Added a Google-style `Returns:` section to the docstring naming the new return type.
+
+The function signature now matches its actual behavior, and `mypy --strict` reports zero errors on the touched file.
+```
+
+## Worked example — no-longer-applies path
+
+Reviewer thread (synthesized for this doc):
+
+> `copilot-pull-request-reviewer[bot]` on `src/legacy_adapter.py:88`:
+> This compatibility shim should be removed once the upstream migration completes. Add a TODO with the planned removal date.
+
+Reply posted by the orchestrator directly (no code change) after the upstream migration lands and removes the shim file entirely:
+
+```markdown
+**Claude finished @copilot-pull-request-reviewer[bot]'s task** —— This concern no longer applies
+
+---
+### File removed in commit b8e2d4f ✅
+
+The compatibility shim the reviewer flagged is no longer present in the tree. The upstream migration completed in commit `b8e2d4f`, and the same commit deleted `src/legacy_adapter.py` outright. There is no longer any shim to add a TODO to, and there is no longer any caller that imports from the removed module.
+
+**`src/legacy_adapter.py:88`:**
+- The anchored line lives in a file deleted by commit `b8e2d4f`.
+- A repo-wide grep for `legacy_adapter` returns zero matches.
+- The two former call sites (`src/api/router.py`, `src/api/middleware.py`) import from the consolidated module instead.
+
+The thread can be resolved without further action; the reviewer's underlying concern is satisfied by the deletion rather than by the originally requested TODO.
+```
+
+## Relationship to the audit review body
+
+The audit review body posted by `post_audit_thread.py` (consumers: `bugteam`, `findbugs`, `qbug`) shares the same header anchor pattern:
+
+<!-- audit-body-skeleton:start -->
+```
+**<Skill> audit completed** —— <state_label>
+
+---
+### <heading>
+
+<summary paragraph>
+
+**Findings:** <N> | **Severity:** <P0 count>P0 / <P1 count>P1 / <P2 count>P2
+
+<optional collapsed details section per finding>
+```
+<!-- audit-body-skeleton:end -->
+
+The audit review body announces a complete audit pass; the reply template addresses one specific thread. They use the same `**Title** —— <status>` header convention so a reader scanning a PR sees consistent visual anchoring across both surfaces.
+
+## Cross-references
+
+- [`audit-contract.md`](audit-contract.md) — finding schema (Shape A / Shape B), adversarial second pass, post-fix self-audit, persistence layout. The fields in a Shape A finding (`file`, `line`, `failure_mode`) feed the placeholders in this template. Replies cite the same `<file>:<line>` anchors that the originating audit recorded.
+- [`fix-protocol.md`](fix-protocol.md) — step 12 of the fix protocol describes the reply step and renders this template's full structure.
+- [`gh-payloads.md`](gh-payloads.md) — MCP and REST endpoints used to post replies (`add_reply_to_pull_request_comment` and `post_fix_reply.py`). The transport is independent of the template; both transports accept the body string this template defines.

package/_shared/pr-loop/fix-protocol.md

@@ -16,10 +16,31 @@
 9. **Stage by explicit path:** `git add <path>` for each modified file. Avoid `git add -A` and `git add .`.
 10. **Create one commit** summarizing the fixed findings. Let every git hook run. When a hook blocks the commit, capture stderr, mark every finding in this loop `status=hook_blocked`, and move to the next iteration without retrying this loop.
 11. **Push fast-forward:** `git push origin <branch>`. Verify `git fetch origin <branch> && git rev-parse origin/<branch>` matches `HEAD`.
-12. **Reply inline** on each finding's comment thread using the [`gh-payloads.md`](gh-payloads.md) reply shape. Reply body is one of:
-    - `Fixed in <short_sha>`
-    - `Could not address this loop: <one-line reason>`
-    - `Hook blocked the fix commit: <one-line summary>`
+12. **Reply + resolve, atomic per thread.** For each finding, post the reply and call `resolve_thread` as one logical action — no yield to the orchestrator between them, no batching all replies before any resolves.
+
+    The reply body uses the unified template from [`audit-reply-template.md`](audit-reply-template.md). Skeleton (identical across all paths):
+
+    ```
+    **Claude finished @<reviewer>'s task** —— <status_line>
+
+    ---
+    ### <action_heading> ✅
+
+    <1–2 paragraph plain-language explanation>
+
+    **`<file>:<line>`:**
+    - <bullet describing change or rationale>
+    - <bullet describing change or rationale>
+
+    <closing paragraph>
+    ```
+
+    Per-path `<status_line>` / `<action_heading>`:
+    - `status=fixed`: `Fixed in <short_sha>` (7-char SHA) / finding-specific action verb (e.g., `Replaced Any with concrete type`).
+    - `status=could_not_address`: `Could not address this loop` / one-line reason text.
+    - `status=hook_blocked`: `Hook blocked the fix commit` / one-line hook summary.
+
+    Transport: post the reply via [`gh-payloads.md`](gh-payloads.md), then call `pull_request_review_write(method="resolve_thread", threadId=<thread_node_id>, ...)` for the same thread before moving to the next finding (this is the PR review thread node ID — `PRRT_kwDOxxx` — distinct from the numeric comment ID; harvest it at audit time when calling `get_review_comments`, see [`skills/bugteam/reference/obstacles/fix-resolve-thread.md`](../../skills/bugteam/reference/obstacles/fix-resolve-thread.md)).
 13. **Re-trigger reviewer** when the calling workflow specifies. Workflow-specific:
     - `pr-converge`: post `bugbot run` issue comment after every push (Cursor Bugbot)
     - `monitor-many`: post `bugbot run` issue comment AND call `requested_reviewers` API for Copilot

package/_shared/pr-loop/gh-payloads.md

@@ -8,42 +8,29 @@ Build payloads as structured arguments to MCP tools. Body content passes as a st
 
 ## One review per loop
 
-Call `pull_request_review_write` once per audit loop. Payload: `event: "COMMENT"`, the review body, and one `comments[]` object per anchored finding.
-
-```
-pull_request_review_write(
-    method="create",
-    event="COMMENT",
-    body=review_body,
-    commitID=head_sha,
-    owner=owner,
-    repo=repo,
-    pullNumber=pull_number,
-    comments=[
-        {path: file_path, line: line_number, side: "RIGHT", body: finding_body}
-    ]
-)
-```
-
-Single-line anchors: `{path, line, side: "RIGHT", body}`. Multi-line anchors add `start_line` and `start_side: "RIGHT"`.
-
-Zero findings still post one review. Body line: `## /<workflow> loop <N> audit: 0P0 / 0P1 / 0P2 → clean`. `comments: []`.
-
-## Review body template
-
-```
-## /<workflow> loop <N> audit: <P0>P0 / <P1>P1 / <P2>P2
-
-### Findings without a diff anchor
-(only when needed)
-- **[severity] title** — <file>:<line> — <one-line description>
-```
-
-`<workflow>` is the calling skill name (`bugteam`, `qbug`, `pr-converge`).
+Posting the per-loop audit review is handled by
+[`_shared/pr-loop/scripts/post_audit_thread.py`](scripts/post_audit_thread.py).
+The script owns the review-create/POST/retry flow internally; callers no longer
+build the GitHub reviews-API payload themselves. See
+[`skills/bugteam/SKILL.md` § Audit posting](../../skills/bugteam/SKILL.md#audit-posting)
+for the contract and [`skills/bugteam/PROMPTS.md`](../../skills/bugteam/PROMPTS.md)
+for the AUDIT-step invocation shape.
+
+## Review body skeleton
+
+The review body skeleton lives in
+[`audit-reply-template.md`](audit-reply-template.md) between the
+`<!-- audit-body-skeleton:start -->` and `<!-- audit-body-skeleton:end -->`
+markers. `post_audit_thread.py` reads that skeleton at runtime and substitutes
+its placeholders (`<Skill>`, `<state_label>`, `<heading>`, severity counts,
+collapsed `<details>` block). Callers pass the skill name, state, commit SHA,
+and findings JSON; the body shape is owned by the template.
 
 ## Reply to a finding
 
-Call `add_reply_to_pull_request_comment` with the finding comment ID and reply body:
+Call `add_reply_to_pull_request_comment` with the finding comment ID and a
+reply body rendered from
+[`audit-reply-template.md`](audit-reply-template.md):
 
 ```
 add_reply_to_pull_request_comment(
@@ -55,30 +42,30 @@ add_reply_to_pull_request_comment(
 )
 ```
 
-## Anchor fallback (line not in diff)
-
-Lines not in the PR diff cannot anchor an inline comment. Omit them from `comments[]` and list under the review body's `### Findings without a diff anchor` section. Outcome record per finding: `used_fallback="true"`, empty `finding_comment_id`, `finding_comment_url` = parent review URL.
+The `body` follows the unified reply skeleton documented in
+[`audit-reply-template.md` § Template skeleton](audit-reply-template.md#template-skeleton).
 
-## Review POST failure fallback (issue comment)
+## Anchor fallback (line not in diff)
 
-When the review POST fails, call `add_issue_comment` with the full review body:
+Lines not in the PR diff cannot anchor an inline comment. The AUDIT teammate
+keeps such findings out of the findings JSON handed to
+`post_audit_thread.py`, lists them in the audit outcome XML under `<finding>`
+with an empty `finding_comment_id`, and surfaces them in the calling skill's
+user-facing output (chat reply to the user) rather than in the PR review body.
 
-```
-add_issue_comment(
-    owner=owner,
-    repo=repo,
-    issueNumber=pull_number,
-    body=fallback_body
-)
-```
+## Review POST failure
 
-All findings in the loop record `used_fallback="true"`; `finding_comment_url` = issue comment URL.
+There is no fallback path. `post_audit_thread.py` exits `2` on retry
+exhaustion (four non-2xx responses across the built-in `1s / 4s / 16s` backoff)
+and the orchestrator halts with `error: post_audit_thread retry exhausted`.
+A hard blocker on the audit-posting path is a halt condition, not a degraded
+flat-issue-comment fall-through.
 
 ## Endpoints
 
-- Review: `pull_request_review_write(method="create", ...)`
-- Reply: `add_reply_to_pull_request_comment(...)`
-- Fallback issue comment: `add_issue_comment(...)`
+- Review: handled by `post_audit_thread.py` (POSTs to
+  `/repos/{owner}/{repo}/pulls/{N}/reviews` internally).
+- Reply: `add_reply_to_pull_request_comment(...)`.
 
 ## SHA capture timing
 

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -15,18 +15,13 @@ from config.code_rules_gate_constants import (
     ALL_CODE_FILE_EXTENSIONS,
     ALL_GIT_DIFF_CACHED_NAME_ONLY_NULL_TERMINATED_COMMAND,
     ALL_GIT_DIFF_NAME_ONLY_NULL_TERMINATED_COMMAND_PREFIX,
-    ALL_LITERAL_KEYWORD_EXEMPTIONS,
     ALL_TEST_FILENAME_GLOB_SUFFIXES,
     ALL_TEST_FILENAME_SUFFIXES,
-    COLUMN_KEY_PATTERN_TEMPLATE,
-    CONFIG_PATH_SEGMENT,
     EXPECTED_NON_RENAME_COLUMN_COUNT,
     EXPECTED_RENAME_COLUMN_COUNT,
-    EXPECTED_TUPLE_PAIR_LENGTH,
     GIT_NAME_STATUS_ADDED_PREFIX,
     GIT_NAME_STATUS_RENAMED_PREFIX,
     MAX_VIOLATIONS_PER_CHECK,
-    MINIMUM_COLUMN_NAME_LENGTH_AFTER_FIRST_CHAR,
     PYTHON_FILE_EXTENSION,
     TEST_CONFTEST_FILENAME,
     TEST_FILENAME_PREFIX,
@@ -365,58 +360,6 @@ def is_test_path(file_path: str) -> bool:
     return False
 
 
-def check_database_column_string_magic(content: str, file_path: str) -> list[str]:
-    """Flag string literals that look like database/HTTP column or key names inside function bodies.
-
-    Triggers when a snake_case string literal appears as the first element of a
-    two-element tuple inside a function body (the characteristic column-name/value
-    pair pattern). Files under ``config/`` and test files are exempt.
-    """
-    normalized_path = file_path.replace("\\", "/")
-    if CONFIG_PATH_SEGMENT in normalized_path:
-        return []
-    if is_test_path(normalized_path):
-        return []
-    try:
-        tree = ast.parse(content)
-    except SyntaxError:
-        return []
-    issues: list[str] = []
-    column_key_pattern = re.compile(
-        COLUMN_KEY_PATTERN_TEMPLATE.format(
-            minimum_length=MINIMUM_COLUMN_NAME_LENGTH_AFTER_FIRST_CHAR
-        )
-    )
-    seen_tuple_node_ids: set[int] = set()
-    for each_node in ast.walk(tree):
-        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            continue
-        for each_child in ast.walk(each_node):
-            if not isinstance(each_child, ast.Tuple):
-                continue
-            if id(each_child) in seen_tuple_node_ids:
-                continue
-            seen_tuple_node_ids.add(id(each_child))
-            if len(each_child.elts) != EXPECTED_TUPLE_PAIR_LENGTH:
-                continue
-            first_element = each_child.elts[0]
-            if not isinstance(first_element, ast.Constant):
-                continue
-            if not isinstance(first_element.value, str):
-                continue
-            literal_text = first_element.value
-            if not column_key_pattern.match(literal_text):
-                continue
-            if literal_text in ALL_LITERAL_KEYWORD_EXEMPTIONS:
-                continue
-            issues.append(
-                f"Line {first_element.lineno}: Column-name string magic {literal_text!r} - extract to config"
-            )
-            if len(issues) >= MAX_VIOLATIONS_PER_CHECK:
-                return issues
-    return issues
-
-
 def _iter_calls_excluding_nested_functions(node: ast.AST) -> Iterator[ast.Call]:
     for each_child in ast.iter_child_nodes(node):
         if isinstance(each_child, (ast.FunctionDef, ast.AsyncFunctionDef)):
@@ -826,9 +769,6 @@ def run_gate(
             repository_root.resolve(), relative_posix
         )
         issues = validate_content(content, relative_posix, prior_content)
-        issues.extend(
-            check_database_column_string_magic(content, relative_posix)
-        )
         issues.extend(check_wrapper_plumb_through(content, relative_posix))
         if not issues:
             continue

package/_shared/pr-loop/scripts/config/post_audit_thread_constants.py

@@ -0,0 +1,189 @@
+"""Constants for post_audit_thread.py.
+
+Centralizes every literal the script and its tests need so the script body
+contains no magic values beyond the integer literals exempt from
+``check_magic_values`` (``0``, ``1``, ``-1``). Constants live here per
+CODE_RULES.md §4 (Config Locations) and §3 (Reuse Constants).
+
+All scalar constants stay narrowly typed so the consuming script and tests
+can rely on ``int`` / ``str`` / ``tuple`` semantics without runtime checks.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+SKILL_BUGTEAM: str = "bugteam"
+SKILL_FINDBUGS: str = "findbugs"
+SKILL_QBUG: str = "qbug"
+ALL_SUPPORTED_SKILLS: tuple[str, ...] = (SKILL_BUGTEAM, SKILL_FINDBUGS, SKILL_QBUG)
+
+STATE_CLEAN: str = "CLEAN"
+STATE_DIRTY: str = "DIRTY"
+ALL_SUPPORTED_STATES: tuple[str, ...] = (STATE_CLEAN, STATE_DIRTY)
+
+SEVERITY_TAG_P0: str = "P0"
+SEVERITY_TAG_P1: str = "P1"
+SEVERITY_TAG_P2: str = "P2"
+ALL_SUPPORTED_SEVERITY_TAGS: tuple[str, ...] = (
+    SEVERITY_TAG_P0,
+    SEVERITY_TAG_P1,
+    SEVERITY_TAG_P2,
+)
+
+INLINE_COMMENT_SIDE_RIGHT: str = "RIGHT"
+INLINE_COMMENT_SIDE_LEFT: str = "LEFT"
+ALL_SUPPORTED_INLINE_COMMENT_SIDES: tuple[str, ...] = (
+    INLINE_COMMENT_SIDE_RIGHT,
+    INLINE_COMMENT_SIDE_LEFT,
+)
+
+GITHUB_API_BASE_URL: str = "https://api.github.com"
+GITHUB_API_USER_AGENT: str = "post_audit_thread.py/1"
+GITHUB_API_ACCEPT_HEADER: str = "application/vnd.github+json"
+GITHUB_API_VERSION_HEADER: str = "2022-11-28"
+
+GITHUB_REVIEW_EVENT_APPROVE: str = "APPROVE"
+GITHUB_REVIEW_EVENT_REQUEST_CHANGES: str = "REQUEST_CHANGES"
+
+HTTP_STATUS_SUCCESS_RANGE_LOW: int = 200
+HTTP_STATUS_SUCCESS_RANGE_HIGH: int = 300
+
+HTTP_AUTHORIZATION_BEARER_PREFIX: str = "Bearer "
+HTTP_HEADER_AUTHORIZATION: str = "Authorization"
+HTTP_HEADER_ACCEPT: str = "Accept"
+HTTP_HEADER_CONTENT_TYPE: str = "Content-Type"
+HTTP_HEADER_GITHUB_API_VERSION: str = "X-GitHub-Api-Version"
+HTTP_HEADER_USER_AGENT: str = "User-Agent"
+HTTP_METHOD_POST: str = "POST"
+HTTP_REQUEST_CONTENT_TYPE: str = "application/json"
+HTTP_REQUEST_TIMEOUT_SECONDS: int = 30
+ERROR_RESPONSE_PREVIEW_CHARS: int = 200
+
+MAX_RETRY_ATTEMPTS: int = 3
+ALL_RETRY_BACKOFF_SECONDS: tuple[int, ...] = (1, 4, 16)
+
+EXIT_CODE_USER_ERROR: int = 1
+EXIT_CODE_RETRY_EXHAUSTED: int = 2
+
+SHORT_SHA_LENGTH: int = 7
+
+ALL_GH_AUTH_TOKEN_COMMAND_PARTS: tuple[str, ...] = ("gh", "auth", "token")
+
+GH_TOKEN_ENV_VAR_NAME: str = "GH_TOKEN"
+GITHUB_TOKEN_ENV_VAR_NAME: str = "GITHUB_TOKEN"
+ALL_GH_TOKEN_ENV_VAR_NAMES: tuple[str, ...] = (
+    GH_TOKEN_ENV_VAR_NAME,
+    GITHUB_TOKEN_ENV_VAR_NAME,
+)
+
+JSON_FIELD_PATH: str = "path"
+JSON_FIELD_LINE: str = "line"
+JSON_FIELD_SIDE: str = "side"
+JSON_FIELD_SEVERITY: str = "severity"
+JSON_FIELD_DESCRIPTION: str = "description"
+JSON_FIELD_FIX_SUMMARY: str = "fix_summary"
+ALL_REQUIRED_FINDING_FIELDS: tuple[str, ...] = (
+    JSON_FIELD_PATH,
+    JSON_FIELD_LINE,
+    JSON_FIELD_SIDE,
+    JSON_FIELD_SEVERITY,
+    JSON_FIELD_DESCRIPTION,
+    JSON_FIELD_FIX_SUMMARY,
+)
+
+REVIEW_REQUEST_FIELD_COMMIT_ID: str = "commit_id"
+REVIEW_REQUEST_FIELD_BODY: str = "body"
+REVIEW_REQUEST_FIELD_EVENT: str = "event"
+REVIEW_REQUEST_FIELD_COMMENTS: str = "comments"
+
+REVIEW_RESPONSE_FIELD_HTML_URL: str = "html_url"
+
+INLINE_COMMENT_FIELD_PATH: str = "path"
+INLINE_COMMENT_FIELD_LINE: str = "line"
+INLINE_COMMENT_FIELD_SIDE: str = "side"
+INLINE_COMMENT_FIELD_BODY: str = "body"
+
+AUDIT_REPLY_TEMPLATE_FILENAME: str = "audit-reply-template.md"
+TEMPLATE_FENCE_TOKEN: str = "```"
+
+PLACEHOLDER_SKILL: str = "<Skill>"
+PLACEHOLDER_STATE_LABEL: str = "<state_label>"
+PLACEHOLDER_HEADING: str = "<heading>"
+PLACEHOLDER_SUMMARY_PARAGRAPH: str = "<summary paragraph>"
+PLACEHOLDER_FINDINGS_COUNT: str = "<N>"
+PLACEHOLDER_P0_COUNT: str = "<P0 count>"
+PLACEHOLDER_P1_COUNT: str = "<P1 count>"
+PLACEHOLDER_P2_COUNT: str = "<P2 count>"
+PLACEHOLDER_DETAILS_BLOCK: str = "<optional collapsed details section per finding>"
+
+STATE_LABEL_FOR_CLEAN: str = "Clean — no findings"
+STATE_LABEL_FOR_DIRTY: str = "Findings requested"
+HEADING_FOR_CLEAN: str = "Audit pass clean"
+HEADING_FOR_DIRTY: str = "Findings recorded as inline review comments"
+
+SUMMARY_PARAGRAPH_CLEAN_TEMPLATE: str = (
+    "The {skill_display} audit pass against commit `{short_commit}` found no "
+    "findings. No inline review comments were posted; the PR carries zero "
+    "unresolved threads originating from this audit pass."
+)
+SUMMARY_PARAGRAPH_DIRTY_TEMPLATE: str = (
+    "The {skill_display} audit pass against commit `{short_commit}` surfaced "
+    "{findings_count} finding(s). Each finding is posted below as an inline "
+    "review comment so it becomes its own resolvable thread; the unresolved-"
+    "thread gate picks them up at the next pr-converge step boundary."
+)
+
+DETAILS_BLOCK_HEADER: str = "<details>\n<summary>Finding details</summary>\n"
+DETAILS_BLOCK_BULLET_TEMPLATE: str = (
+    "- **[{severity}]** `{path}:{line}` — {description}"
+)
+DETAILS_BLOCK_FOOTER: str = "\n</details>"
+
+INLINE_COMMENT_BODY_TEMPLATE: str = (
+    "**[{severity}] {skill_display} audit finding**\n\n"
+    "{description}\n\n"
+    "**Suggested fix:** {fix_summary}"
+)
+
+CLI_FLAG_SKILL: str = "--skill"
+CLI_FLAG_OWNER: str = "--owner"
+CLI_FLAG_REPO: str = "--repo"
+CLI_FLAG_PR_NUMBER: str = "--pr-number"
+CLI_FLAG_COMMIT: str = "--commit"
+CLI_FLAG_STATE: str = "--state"
+CLI_FLAG_FINDINGS_JSON: str = "--findings-json"
+
+REVIEWS_API_PATH_TEMPLATE: str = "/repos/{owner}/{repo}/pulls/{pr_number}/reviews"
+SINGLE_REVIEW_API_PATH_TEMPLATE: str = (
+    "/repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id}"
+)
+SINGLE_REVIEW_COMMENTS_API_PATH_TEMPLATE: str = (
+    "/repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id}/comments"
+)
+
+AUDIT_BODY_SKELETON_OPEN_MARKER: str = "<!-- audit-body-skeleton:start -->"
+AUDIT_BODY_SKELETON_CLOSE_MARKER: str = "<!-- audit-body-skeleton:end -->"
+
+
+def script_directory() -> Path:
+    """Return the absolute path of the parent directory holding the consuming script.
+
+    Returns:
+        Path to ``_shared/pr-loop/scripts/`` resolved through this constants
+        module's location. Callers may walk up one further level
+        (``script_directory().parent``) to reach the
+        ``_shared/pr-loop/`` directory where ``audit-reply-template.md`` lives.
+    """
+    return Path(__file__).resolve().parent.parent
+
+
+def template_path() -> Path:
+    """Return the absolute path to ``audit-reply-template.md``.
+
+    Returns:
+        Path object pointing to ``_shared/pr-loop/audit-reply-template.md``
+        relative to this constants module. Callers read this file at runtime
+        so the markdown doc remains the source of truth for the body skeleton.
+    """
+    return script_directory().parent / AUDIT_REPLY_TEMPLATE_FILENAME