claude-dev-env 4.3.0 → 7.0.0

package/_shared/pr-loop/audit-contract.md

@@ -1,183 +0,0 @@
-# Audit contract
-
-Shared output schema and audit-loop contract used by `/bugteam`, `clean-room audit (code-quality-agent)`, and `/pr-fix-protocol`. Changing a shape here is a breaking change for every consuming skill.
-
-## Contents
-
-- Finding schema (Shape A, Shape B)
-- Adversarial second pass
-- Haiku secondary auditor
-- Post-fix self-audit
-- De-dup and merge
-- Persistence (loop-<L>-audit.json, loop-<L>-diagnostics.json)
-
-## Collection before severity filtering
-
-Audit collection reports every real finding. The collection record retains all
-seeded severities (`P0`, `P1`, `P2`) and every Shape A field (`file`, `line`,
-`category`, `severity`, `excerpt`, `failure_mode`, `evidence_files`). Do not drop a real finding because its severity is low.
-
-Severity or action filtering is a **separate consumer stage** after collection
-is complete. A consumer may select a subset for fix or posting; it must not
-rewrite the collection record or strip file, line, evidence, or category from
-retained entries.
-
-## Finding schema
-
-Each finding an audit produces MUST be one of exactly two shapes.
-
-### Shape A — structured finding
-
-```json
-{
-  "id": "loop<L>-<K>",
-  "file": "path/relative/to/repo/root.py",
-  "line": 123,
-  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q",
-  "severity": "P0 | P1 | P2",
-  "excerpt": "verbatim code snippet from the offending line(s)",
-  "failure_mode": "one sentence describing what goes wrong and when",
-  "evidence_files": ["additional/files/opened.py"]
-}
-```
-
-`id` is `loop<L>-<K>` where `L` is the loop counter (1-based) and `K` is the 1-based index within the loop. For `clean-room audit (code-quality-agent)` which runs once, use `find<K>`.
-
-### Shape B — structured proof-of-absence
-
-Used when an audit investigates a category and does NOT find a bug. Bare "verified clean" claims are REJECTED because they hide shallow reading.
-
-```json
-{
-  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q",
-  "files_opened": ["file1.py", "file2.py"],
-  "lines_quoted": [
-    {"file": "file1.py", "line": 88, "text": "verbatim line content"}
-  ],
-  "adversarial_probes": [
-    "what failure mode was tested for and how it was ruled out"
-  ]
-}
-```
-
-Every category an audit touches MUST have either at least one Shape A finding OR at least one Shape B proof-of-absence entry. A category with neither is a protocol violation.
-
-### Example — Shape A
-
-```json
-{
-  "id": "loop1-1",
-  "file": "scripts/db/neon.py",
-  "line": 43,
-  "category": "C",
-  "severity": "P1",
-  "excerpt": "load_dotenv(env_path, override=False)",
-  "failure_mode": "Called on every connect() — repeats file I/O per connection in scripts that open multiple short-lived connections.",
-  "evidence_files": ["scripts/db/neon.py", "scripts/update_new_releases.py"]
-}
-```
-
-### Example — Shape B
-
-```json
-{
-  "category": "H",
-  "files_opened": ["scripts/db/neon.py", "scripts/db/config.py"],
-  "lines_quoted": [
-    {"file": "scripts/db/neon.py", "line": 30, "text": "dsn = os.environ.get(\"DATABASE_URL\")"}
-  ],
-  "adversarial_probes": [
-    "Checked whether DATABASE_URL is interpolated into a shell — it is passed to psycopg.connect() directly with no shell involvement.",
-    "Checked whether the env path is user-controlled — it is derived from a fixed Y: drive constant, not user input."
-  ]
-}
-```
-
-## Adversarial second pass
-
-After the primary finding list is complete, every audit runs a second pass against itself with the prompt:
-
-> Assume your first pass missed at least 3 P1 bugs. Where are they?
-
-The audit must either produce new Shape A findings citing new file:line references not present in the first pass, or cite explicit Shape B adversarial-probe entries for each category it re-examined. An adversarial pass that returns "nothing new, confident first pass was complete" is REJECTED — produce evidence or findings, not confidence.
-
-## Haiku secondary auditor
-
-For single-subagent skills (`/bugteam`, `clean-room audit (code-quality-agent)`) the LEAD spawns two `Agent()` calls in one message:
-
-- **Primary** — `subagent_type=clean-coder`, `model=sonnet` (for `/bugteam` cycle) or `subagent_type=code-quality-agent`, `model=sonnet` (for clean-room audit).
-- **Secondary (Haiku)** — `subagent_type=code-quality-agent`, `model=haiku`, same self-contained clean-room prompt shape used by `clean-room audit (code-quality-agent)`.
-
-Both audit the same diff. The secondary returns findings to the LEAD only — never posted to the PR.
-
-Merge rules — applied whenever the LEAD combines findings from multiple sources (primary auditor, Haiku secondary auditor, adversarial pass):
-
-- **De-dup key**: `(file, line, category)`. Two findings sharing the same `(file, line, category)` tuple are the same finding and collapse into one entry.
-- **Severity conflict**: max wins (`P0 > P1 > P2`). When sources disagree on severity for the same de-dup key, the merged entry keeps the highest severity.
-- **Unique-to-secondary findings**: added to the merged set with the secondary's severity and source annotation.
-- **Unique-to-primary findings**: kept as-is.
-- **Zero secondary findings**: the primary set is trusted and the audit moves on.
-- **Malformed or non-parseable secondary output**: lead trusts the primary set and logs the event in `loop-<L>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
-
-For `/bugteam`, the single audit agent provides per-category coverage by walking all A–Q rubrics in one invocation.
-
-## Post-fix self-audit
-
-Audit-and-fix skills (`/bugteam`) MUST re-audit modified files between `py_compile` and `git add`. This catches fix-induced regressions in the same loop that introduced them rather than on loop N+1.
-
-Sequence:
-
-1. Capture pre-fix file contents for every file this FIX will touch.
-2. Apply edits.
-3. Run `py_compile` (or language-equivalent) on each modified file.
-4. Compute `fix_diff` against pre-fix contents for the modified set.
-5. Run `_shared/pr-loop/scripts/code_rules_gate.py` with explicit paths for every modified file.
-6. Spawn a scoped audit of `fix_diff` with full A–Q rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
-7. Read the previous loop's outcome XML (`<worktree_path>/.bugteam-pr<N>-loop<L-1>.outcomes.xml`) and obtain its total finding count. If this is the first loop (L <= 1) or the file does not exist, skip this comparison. Compute the post-fix total: previous total minus bugs fixed in this round plus new violations found in the post-fix audit (step 6). If the post-fix total exceeds the previous total, flag all new findings as same-loop fix-targets and revise. An increase in total findings across loop transitions is a regression.
-8. Any new findings become same-loop fix-targets. Internal iteration count increments by one.
-9. After 3 internal iterations with fresh findings each time, exit `stuck: post-fix audit not converging`.
-10. Only when `gate_findings` empty AND `post_fix_findings` empty: `git add`, commit, push.
-
-`converged` exit condition: `primary_audit_clean AND post_fix_audit_clean` for the committing loop.
-
-## De-dup and merge
-
-Findings from primary, adversarial, Haiku secondary, and post-fix passes are merged into a single deduped finding list before persistence.
-
-- **De-dup key:** `(file, line, category)`. Two findings sharing the same `(file, line, category)` tuple collapse into a single deduped entry.
-- **Severity conflict resolution:** `max wins`. When merged findings disagree on severity, the deduped entry carries the highest severity (`P0 > P1 > P2`).
-- **Excerpt and failure_mode:** the deduped entry inherits these fields from the highest-severity contributing finding. Ties keep the first observed contributor.
-- **`evidence_files`:** the deduped entry carries the union of every contributor's `evidence_files`, deduplicated and sorted.
-
-The merged list lands in `loop-<L>-diagnostics.json` under both `merged` (one entry per contributing finding) and `deduped` (one entry per unique `(file, line, category)` tuple).
-
-## Persistence
-
-Every audit loop writes two JSON files under the skill's scoped temp directory (resolved via `tempfile.gettempdir()`):
-
-### `loop-<L>-audit.json`
-
-```json
-{
-  "findings": [],
-  "proof_of_absence": [],
-  "source": "primary | haiku | adversarial | merged"
-}
-```
-
-### `loop-<L>-diagnostics.json`
-
-```json
-{
-  "loop": 1,
-  "gate_findings": [],
-  "primary_findings": [],
-  "adversarial_findings": [],
-  "haiku_findings": [],
-  "post_fix_findings": [],
-  "merged": [],
-  "deduped": []
-}
-```
-
-All eight keys MUST be present. Missing keys break convergence debugging.

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

@@ -1,151 +0,0 @@
-# Audit reply template
-
-Canonical reply shape for every orchestrator-to-thread reply posted by the PR-loop suite (`pr-converge`, `bugteam`, 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`, `pr-converge`) reads it before authoring a reply.
-
-Use `~/.claude/rules/asd-ste100-language.md` for user-facing word choice,
-sentence style, tone, punctuation, and prose form. This template owns review
-thread fields, evidence slots, and action/status structure.
-
-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 skills/agents listed above (read-only `clean-room audit` is excluded — it posts an audit review via `post_audit_thread.py` but never authors thread replies). The audit-body-skeleton consumers include `clean-room audit` alongside `bugteam` because both 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`, `clean-room audit`) 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/code-rules-gate.md

@@ -1,65 +0,0 @@
-# CODE_RULES gate
-
-Pre-audit validator run before each AUDIT (and pre-commit when applicable). Wraps `validate_content_for_full_gate` from `~/.claude/hooks/blocking/code_rules_enforcer.py`.
-
-## Script location
-
-Canonical: `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py` after install.
-
-Workflows reference it via:
-- all skills (bugteam, pr-converge): `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`
-
-Cross-skill path traversal works because every skill installs as a flat top-level dir under the skills lookup path (`~/.claude/skills/`, a directory pointer to `~/.agents/skills/`) and `_shared/` lives alongside `skills/` under `~/.claude/`.
-
-## Invocation
-
-Default mode (full PR diff against base):
-```bash
-python "<gate_script>" --base origin/<base_branch>
-```
-
-Staged mode (pre-commit subset):
-```bash
-python "<gate_script>" --staged
-```
-
-Path-scoped mode:
-```bash
-python "<gate_script>" --base origin/<base_branch> --only-under <prefix> [--only-under <other_prefix>]
-```
-
-## Exit codes
-
-- `0` — no violations on changed lines (advisories on touched-but-unchanged lines may still print)
-- `1` — at least one blocking violation on changed lines; halt
-- `2` — gate execution error (missing enforcer, git failure, malformed diff)
-
-## Workflow integration
-
-- **bugteam:** before every AUDIT in Step 3 of the loop. Non-zero → spawn clean-coder for standards fix; loop until exit 0 or 5 consecutive gate failures → `error: code rules gate failed pre-audit`.
-- **pr-converge:** before every push in the Fix protocol and before every commit during the fix loop. Halt on non-zero, fix violations, re-run.
-
-## Coverage
-
-- File-global UPPER_SNAKE constants (must live in `config/` outside exempt path families)
-- Magic values in production function bodies (literals other than 0, 1, -1)
-- Imports outside top of module
-- New code comments anywhere; comments tied to touched code are removed and comments tied to untouched code remain unchanged
-- File-global constants used by fewer than 2 functions/methods
-- Logging format-arg violations
-- Database column-name string magic (snake_case strings as first element of 2-tuples in function bodies)
-- Public-wrapper-drops-optional-kwargs of same-file delegates
-
-Test files use the same no-new-comment policy; their magic-value and constants-location exemptions remain.
-
-When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
-Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
-
-## Halt-fix-rerun protocol
-
-When the gate exits non-zero:
-1. Capture stderr (gate prints `<file>: Line <N>: <issue>` per violation)
-2. Group violations by file
-3. Apply fixes in the smallest change set (extract constants to `config/`, rename collection params with `all_` prefix, replace literals with named constants, etc.)
-4. Re-run the gate with the same arguments
-5. Cap at 5 consecutive failures (bugteam, pr-converge); on cap exceeded, exit `error`

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

@@ -1,60 +0,0 @@
-# Fix protocol
-
-## Sequence
-
-1. **Read each referenced file:line** before editing. The repo enforces read-before-edit at the tool layer.
-2. **Capture pre-fix SHA:** `git rev-parse HEAD`. Store as `pre_fix_sha`.
-3. **Capture pre-fix file contents** for every file this fix will touch. Used in step 8 for the post-fix self-audit diff.
-4. **TDD where applicable:** when the finding has behavior to test, write a failing test first; for pure doc, comment, or naming nits with no behavior, fix directly.
-5. **Apply each fix:**
-    - Preserve existing comments on lines left unchanged
-    - Add complete type hints on every signature touched
-    - Apply `~/.claude/rules/asd-ste100-language.md` to new user-facing prose
-6. **Validate each modified Python file:** `python -m py_compile <path>`. Halt on syntax error; fix and re-run.
-7. **Compute fix diff:** the diff between pre-fix and post-fix file contents for every modified file.
-8. **Post-fix self-audit:** follow [`audit-contract.md`](audit-contract.md) post-fix self-audit sequence. Internal iteration cap: 3. Three rounds with fresh findings → exit `stuck: post-fix audit not converging`. Only when `gate_findings` empty AND `post_fix_findings` empty → proceed to git add.
-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 + 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 the archived [`fix-resolve-thread` runbook](../../.agents/skills-archived/bugteam/reference/obstacles/fix-resolve-thread.md)).
-13. **Re-trigger reviewer** when the calling workflow specifies. Workflow-specific:
-    - **autoconverge** — terminal Bugbot, Copilot, and Codex gates re-run after each fix push per [`../../.agents/skills/autoconverge/reference/convergence.md`](../../.agents/skills/autoconverge/reference/convergence.md)
-    - **Archived pr-converge** — post `bugbot run` after every push; see archived skill reference
-    - **Archived bugteam** — skip external re-trigger; the next loop iteration audits
-
-## Stuck detection
-
-After step 11, when `git rev-parse HEAD` is unchanged from `pre_fix_sha`, the fix produced no commit. Exit reason: `stuck — could not address findings`. Record unresolved findings as `{file, line, severity, title, reason}` quadruples.
-
-## Constraints
-
-- Edit only files reachable from the PR diff's scope.
-- Append commits; the branch stays linear (one commit per fix loop, fast-forward push only).
-- No comment deletion on lines left unchanged.
-- No `--no-verify`. Hook rejections flag real underlying issues worth investigating.
-- **Narrow scope.** Fix only the exact defect at the specified file:line. No structural refactoring, no inlining helpers.
-- **Preserve helpers.** Do not remove or inline existing helper functions unless the finding explicitly names them.

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

@@ -1,75 +0,0 @@
-# MCP-based payloads
-
-Shared payload shapes for posting PR reviews and replies. Used by autoconverge
-terminal gates and the archived `bugteam` / `pr-converge` skills.
-
-## Build payloads with MCP tools
-
-Build payloads as structured arguments to MCP tools. Body content passes as a string parameter directly.
-
-## One review per loop
-
-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
-[`post-audit-thread-contract.md`](post-audit-thread-contract.md) for the contract
-and the archived
-[`bugteam` audit-posting section](../../.agents/skills-archived/bugteam/SKILL.md)
-for the historical invocation shape in
-[`PROMPTS.md`](../../.agents/skills-archived/bugteam/PROMPTS.md).
-
-## 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 a
-reply body rendered from
-[`audit-reply-template.md`](audit-reply-template.md):
-
-```
-add_reply_to_pull_request_comment(
-    commentId=finding_comment_id,
-    body=reply_body,
-    owner=owner,
-    repo=repo,
-    pullNumber=pull_number
-)
-```
-
-The `body` follows the unified reply skeleton documented in
-[`audit-reply-template.md` § Template skeleton](audit-reply-template.md#template-skeleton).
-
-## Anchor fallback (line not in diff)
-
-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.
-
-## Review POST failure
-
-There is no fallback payload to build. On retry exhaustion
-`post_audit_thread.py` exits `2` and the orchestrator halts — see
-[`post-audit-thread-contract.md`](post-audit-thread-contract.md) § Exit codes.
-A hard blocker on the audit-posting path is a halt condition, not a degraded
-flat-issue-comment fall-through.
-
-## Endpoints
-
-- 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
-
-`commit_id` and any `<head_sha_at_post_time>` reference: `git rev-parse HEAD` immediately before the POST, in the cwd of whichever subagent or process is posting.

package/_shared/pr-loop/post-audit-thread-contract.md

@@ -1,51 +0,0 @@
-# post_audit_thread.py invocation contract
-
-Single source of truth for how every PR-loop caller runs
-[`scripts/post_audit_thread.py`](scripts/post_audit_thread.py) to post one
-audit review per pass. The script posts an `APPROVE` review on `CLEAN` (an
-empty findings list, zero inline comments) and a `REQUEST_CHANGES` review on
-`DIRTY` (one inline anchored comment per finding). It reads its body skeleton
-from [`audit-reply-template.md`](audit-reply-template.md) at runtime.
-
-## Invocation
-
-```
-python "<pr-loop-scripts>/post_audit_thread.py" \
-  --skill <caller> \
-  --owner <owner> \
-  --repo <repo> \
-  --pr-number <N> \
-  --commit <head_sha> \
-  --state <CLEAN|DIRTY> \
-  --findings-json <path>
-```
-
-Capture `<head_sha>` with `git rev-parse HEAD` in the caller's cwd right before
-the call, so the review attaches to the commit the audit scoped. `--findings-json`
-points to a JSON file whose root is a list; on `CLEAN` the list is empty (`[]`).
-
-## Exit codes
-
-The script retries on its own with 1s / 4s / 16s backoff across four tries (one
-plus three retries). It then exits:
-
-| Exit | Meaning |
-|---|---|
-| `0` | Review posted. The new review's `html_url` is on stdout. |
-| `1` | User input error: bad arguments, malformed findings JSON, or a missing template. |
-| `2` | Retry exhaustion: every try failed. |
-
-## Per-caller policy
-
-The same exit codes carry different weight per caller:
-
-- **bugteam** — an exit `2` is a hard blocker. The lead exits with
-  `error: post_audit_thread retry exhausted`, and does not retry or fall back to
-  a flat issue comment.
-- **autoconverge clean-audit** — any post that does not land (a denied post, an
-  error, or an agent that never ran) is a recorded bypass, not a blocker. Every
-  review lens already cleared the HEAD, so the CLEAN post is a record-keeping
-  artifact. The run records a bypass note, sets the convergence check's
-  `--bugteam-post-blocked` flag, and proceeds to the terminal Bugbot gate. Full
-  policy: [`../../skills/autoconverge/reference/stop-conditions.md`](../../skills/autoconverge/reference/stop-conditions.md)
-  § "Clean-audit post bypassed".

package/_shared/pr-loop/precatch-rubric.md

@@ -1,66 +0,0 @@
-# Pre-catch lens checklist
-
-The shared checklist the internal pre-catch lenses read on demand. 
-
-## Lane 1 — Deterministic sweep
-
-The mechanical, static, and test classes belong to a deterministic run. The static-sweep 
-step owns them: it runs the CODE_RULES gate (`code_rules_gate.py --base origin/main`), 
-`ruff`, `mypy`, and stem-matched `pytest` over the changed files. A reading lens trusts the 
-sweep to have cleared them and reviews sweep-clean code.
-
-- Every CODE_RULES violation the gate reports is a finding.
-- Every `ruff` and `mypy` diagnostic on a changed file is a finding.
-- Every failing test in a changed production module's paired test is a finding.
-- **Proof of absence:** the gate exits 0, `ruff` and `mypy` report no diagnostic
-  on the changed files, and the stem-matched tests pass.
-
-## Lane 2 — Doc-vs-code parity
-
-Every doc claim in the diff matches the code it describes. Reuse the cross-file
-consistency prompt at
-[`../../.agents/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml`](../../.agents/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml)
-(installed as `~/.claude/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml`)
-and the drift rubric at
-[`../../audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`](../../audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md).
-
-- Every line citation resolves to the line it names.
-- Every referenced file or script path exists.
-- Every symbol is attributed to the file that defines it.
-- Every inventory table, env-var table, count claim, and ordering claim matches
-  the code.
-- **Proof of absence:** each referenced path, citation, symbol, and table checked
-  against its source and found in step.
-
-## Lane 3 — Test-assertion completeness
-
-Every changed or new production path carries a test that exercises its behavior.
-
-- Every changed or new production path has a paired test that calls it and asserts
-  on its return value or side effect.
-- A changed test pins the behavior it covers rather than hiding it behind a mock.
-- **Proof of absence:** each changed production path paired with a behavior test
-  that fails when the path regresses.
-
-## Lane 4 — PR-description-vs-diff two-way parity
-
-The PR body and the diff describe the same change, both directions.
-
-- Every claim in the PR body maps to a hunk in the diff.
-- Every hunk in the diff maps to a claim in the PR body.
-- Flag any invented path, invented count, or out-of-scope change.
-- **Proof of absence:** the two-way map complete — every claim has a hunk and
-  every hunk has a claim.
-
-## Lane 5 — Adversarial audit
-
-The bug-audit lens runs the adversarial second pass the audit contract specifies
-(`~/.claude/_shared/pr-loop/audit-contract.md`): assume the first A-Q pass missed
-at least three P1 bugs, then find them.
-
-- Return new file:line findings for the bugs the first pass missed.
-- Or return a per-category proof-of-absence entry naming each re-examined category
-  and why it holds.
-- A bare "nothing new" is not an acceptable result for this pass.
-- **Proof of absence:** a per-category adversarial-probe entry for each re-examined
-  A-Q category with no new finding.