claude-dev-env 1.28.1 → 1.29.1

package/skills/qbug/SKILL.md

@@ -22,6 +22,7 @@ Shared artifacts with /bugteam are referenced below by path, using the `${CLAUDE
 - Pre-flight script: `${CLAUDE_SKILL_DIR}/../bugteam/scripts/bugteam_preflight.py`
 - Code-rules gate script: `${CLAUDE_SKILL_DIR}/../bugteam/scripts/bugteam_code_rules_gate.py`
 - Bug category rubric A–J: [`bugteam/PROMPTS.md`](../bugteam/PROMPTS.md#audit-spawn-prompt-xml-bugfind-teammate)
+- **Audit contract** (finding schema, proof-of-absence, adversarial pass, Haiku secondary, post-fix self-audit, diagnostics JSON): [`bugteam/reference/audit-contract.md`](../bugteam/reference/audit-contract.md)
 - PR comment lifecycle shape: [`bugteam/SKILL.md`](../bugteam/SKILL.md#step-25-pr-comments-one-review-per-loop)
 
 ## When this skill applies
@@ -52,6 +53,17 @@ python "${CLAUDE_SKILL_DIR}/../bugteam/scripts/bugteam_preflight.py"
 
 `${CLAUDE_SKILL_DIR}` is host-substituted before the shell runs. Non-zero → fix before continuing. `BUGTEAM_PREFLIGHT_SKIP=1` is emergency only. Add `--pre-commit` when `.pre-commit-config.yaml` exists.
 
+Pre-flight checks (in order):
+
+1. **Git hooks path** — verifies `git -C <repository_root> config --get core.hooksPath` resolves to a path ending in `hooks/git-hooks`. Queries the repository-effective config so repo-level overrides (Husky, lefthook) are detected. If unset or pointing elsewhere, exits non-zero:
+   ```
+   Git-side CODE_RULES enforcement is not active on this host.
+   Run: npx claude-dev-env .
+   Or:  git config --global core.hooksPath ~/.claude/hooks/git-hooks
+   ```
+2. **pytest** — runs the test suite when `pytest.ini` or `[tool.pytest]` is present.
+3. **pre-commit** — runs when `--pre-commit` flag is passed and `.pre-commit-config.yaml` exists.
+
 ## Step 1: Resolve PR scope (lead)
 
 1. `gh pr view --json number,baseRefName,headRefName,url`
@@ -76,7 +88,7 @@ qbug_temp_dir: Path = Path(tempfile.gettempdir()) / f"qbug-pr-{pr_number}"
 qbug_temp_dir.mkdir(parents=True, exist_ok=True)
 ```
 
-## Step 2: Spawn the single subagent
+## Step 2: Spawn the primary and secondary audit agents
 
 Before calling `Agent`, the lead resolves the three absolute paths the subagent needs and substitutes them into the prompt template (the `<gate_script>`, `<categories_file>`, and `<qbug_temp_dir>` placeholders in § Subagent cycle prompt):
 
@@ -89,19 +101,27 @@ gate_script_path = (skill_dir / ".." / "bugteam" / "scripts" / "bugteam_code_rul
 categories_file_path = (skill_dir / ".." / "bugteam" / "PROMPTS.md").resolve()
 ```
 
-Then call `Agent`:
+Then call `Agent` twice in the same message — the primary clean-coder and the Haiku secondary run in parallel per the audit contract. The Haiku secondary receives an **audit-only** prompt (no FIX step, no git operations) and returns findings to the lead only. The lead merges their findings before the FIX step:
 
 ```
 Agent(
   subagent_type="clean-coder",
-  model="sonnet",
-  description="qbug audit/fix cycle for PR <number>",
+  model="opus",
+  description="qbug primary audit/fix cycle for PR <number>",
   prompt="<filled cycle XML; see § Subagent cycle prompt>",
   run_in_background=False
 )
+
+Agent(
+  subagent_type="code-quality-agent",
+  model="haiku",
+  description="qbug Haiku secondary audit for PR <number>",
+  prompt="<audit-only prompt: read the PR diff, apply A-J categories from <categories_file>, return structured findings. No FIX, no git add, no git commit, no git push.>",
+  run_in_background=False
+)
 ```
 
-One subagent, not a team. No `TeamCreate`, no `team_name`, no teammate shutdown protocol. The subagent returns when it has exited the cycle (`converged`, `stuck`, or `error`).
+The Haiku secondary is a read-only auditor per `audit-contract.md` — it returns findings to the lead and never modifies the working tree. The lead merges primary and Haiku secondary findings per the de-dup rules in the audit contract before proceeding. No `TeamCreate`, no `team_name`, no teammate shutdown protocol. The primary subagent returns when it has exited the cycle (`converged`, `stuck`, or `error`).
 
 ## Subagent cycle prompt
 
@@ -128,7 +148,8 @@ The subagent receives this prompt and loops internally — the lead does not re-
 
 <exit_conditions>
   The cycle stops when ONE of these is true. Check on every iteration:
-    - converged: most recent AUDIT returned zero findings.
+    - converged: most recent AUDIT returned zero findings AND
+      post_fix_audit_clean is true for the committing loop.
     - stuck: most recent FIX left `git rev-parse HEAD` unchanged.
     - error: three consecutive pre-audit gate rounds failed (three is
       chosen because two is within normal clean-coder variance; four
@@ -166,14 +187,22 @@ The subagent receives this prompt and loops internally — the lead does not re-
 
        - Read the patch file.
        - Audit only added/modified lines. Read <categories_file> for the
-         A–J category definitions; investigate each category explicitly
-         and return either at least one finding or a verified-clean
-         entry with cleared evidence.
-       - Assign each finding a stable id of the form `loop<N>-<K>`
-         (N=loop_count, K=1-based within this loop).
-       - Partition into anchored (line appears in the diff) vs
+         A–J category definitions; investigate each category explicitly.
+       - Follow the shared audit contract at
+         bugteam/reference/audit-contract.md. Per category: produce
+         either a Shape A structured finding or a Shape B structured
+         proof-of-absence. Bare "verified clean" labels are REJECTED.
+       - Run the contract's adversarial second pass after the primary
+         finding list.
+       - The LEAD spawns the Haiku secondary auditor in parallel with
+         this primary audit per the contract's Haiku secondary section.
+       - Partition findings into anchored (line appears in the diff) vs
          unanchored (line does not).
 
+       Persist the merged audit result to
+       <qbug_temp_dir>/loop-<loop_count>-audit.json per the contract's
+       persistence schema.
+
        Post ONE review per loop. Use the payload shape from
        <categories_file>'s sibling SKILL.md § "PR comments" — build
        the JSON with jq `--rawfile` / `-Rs` reading per-finding body
@@ -192,6 +221,7 @@ The subagent receives this prompt and loops internally — the lead does not re-
 
     4. FIX:
        Capture the pre-FIX sha: `pre_fix_sha = git rev-parse HEAD`.
+       Capture pre-fix file contents for every file this FIX will touch.
 
        Apply each fix. Read every file before editing. Preserve existing
        comments on lines you do not modify. Add type hints on every
@@ -200,6 +230,16 @@ The subagent receives this prompt and loops internally — the lead does not re-
        Validate each modified Python file with `python -m py_compile`
        (or the language-equivalent compile check).
 
+       Compute fix_diff: the diff between pre-fix and post-fix file contents
+       for every modified file.
+
+       Post-fix self-audit: follow the contract's post-fix self-audit
+       sequence at bugteam/reference/audit-contract.md. Paranoid mode
+       (Haiku secondary in parallel), internal iteration cap = 3, exit
+       "stuck: post-fix audit not converging" after 3 rounds with fresh
+       findings. Only when gate_findings empty AND post_fix_findings
+       empty: proceed to git add.
+
        Stage each modified path by explicit name: `git add <path>`.
        Create one commit summarizing the fixed findings. Let every git
        hook run. If a hook blocks the commit, capture its stderr, mark
@@ -208,6 +248,9 @@ The subagent receives this prompt and loops internally — the lead does not re-
 
        Push with a plain fast-forward: `git push`.
 
+       Write <qbug_temp_dir>/loop-<loop_count>-diagnostics.json per the
+       contract's diagnostics schema (all eight keys required).
+
        Reply to each finding at loop_comment_index[finding_id].finding_comment_id
        using the reply CLI shape (jq `-Rs` → `gh api .../comments/<id>/replies --input -`).
        Reply body is one of:
@@ -273,7 +316,7 @@ Delete the resolved `<qbug_temp_dir>` tree and any `.qbug-*.md` temp files in th
 
 ## Constraints
 
-- **One subagent, not a team.** Lead spawns a single `clean-coder` via the Agent tool. No `TeamCreate`. The subagent does not spawn further subagents.
+- **One primary + one secondary auditor, not a team.** Lead spawns a `clean-coder` primary (audit + fix cycle) and a `code-quality-agent` Haiku secondary (audit-only, read-only — no FIX, no git). No `TeamCreate`. Neither subagent spawns further subagents.
 - **No loop cap.** Cycle runs until `converged`, `stuck`, or `error`. User can interrupt.
 - **Code rules gate before every AUDIT.** Same `validate_content` logic as /bugteam.
 - **One commit per FIX action.** Linear branch, fast-forward push only.

package/skills/qbug/test_qbug_skill_audit_schema.py

@@ -0,0 +1,156 @@
+"""Tests verifying the shared audit contract and qbug's reference to it.
+
+The contract lives in bugteam/reference/audit-contract.md and is the single
+source of truth for finding schema, proof-of-absence shape, adversarial pass,
+Haiku secondary, and de-dup/merge rules. qbug/SKILL.md must reference it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+SKILL_FILE_PATH = Path(__file__).parent / "SKILL.md"
+PROMPTS_FILE_PATH = Path(__file__).parent.parent / "bugteam" / "PROMPTS.md"
+CONTRACT_FILE_PATH = (
+    Path(__file__).parent.parent / "bugteam" / "reference" / "audit-contract.md"
+)
+
+
+def _load_skill_text() -> str:
+    return SKILL_FILE_PATH.read_text(encoding="utf-8")
+
+
+def _load_prompts_text() -> str:
+    return PROMPTS_FILE_PATH.read_text(encoding="utf-8")
+
+
+def _load_contract_text() -> str:
+    return CONTRACT_FILE_PATH.read_text(encoding="utf-8")
+
+
+def test_skill_should_reference_audit_contract_by_path() -> None:
+    skill_text = _load_skill_text()
+    assert "audit-contract.md" in skill_text, (
+        "qbug/SKILL.md must reference the shared audit contract by path"
+    )
+
+
+def test_contract_should_require_structured_finding_schema() -> None:
+    contract_text = _load_contract_text()
+    assert "evidence_files" in contract_text, (
+        "Contract must require structured finding with evidence_files[]"
+    )
+    assert "proof_of_absence" in contract_text, (
+        "Contract must require structured proof-of-absence for clean categories"
+    )
+
+
+def test_contract_should_reject_bare_verified_clean_labels() -> None:
+    contract_text = _load_contract_text()
+    assert "lines_quoted" in contract_text, (
+        "Proof-of-absence must require lines_quoted[] not bare 'verified clean'"
+    )
+    assert "adversarial_probes" in contract_text, (
+        "Proof-of-absence must require adversarial_probes[]"
+    )
+
+
+def test_contract_should_require_adversarial_second_pass() -> None:
+    contract_text = _load_contract_text()
+    assert "Assume your first pass missed" in contract_text, (
+        "Contract must include the adversarial second-pass re-prompt"
+    )
+
+
+def test_should_require_haiku_secondary_auditor_spawn() -> None:
+    skill_text = _load_skill_text()
+    assert "haiku" in skill_text.lower(), (
+        "SKILL.md must reference Haiku secondary auditor"
+    )
+    assert "secondary" in skill_text.lower(), (
+        "SKILL.md must reference secondary auditor concept"
+    )
+
+
+def test_contract_should_require_dedup_merge_by_file_line_category() -> None:
+    contract_text = _load_contract_text()
+    assert (
+        "file, line, category" in contract_text
+        or "(file, line, category)" in contract_text
+    ), "De-dup key must be (file, line, category)"
+
+
+def test_contract_should_require_severity_max_wins_on_conflict() -> None:
+    contract_text = _load_contract_text()
+    assert (
+        "max wins" in contract_text.lower() or "severity conflict" in contract_text.lower()
+    ), "Severity conflict resolution must specify max wins"
+
+
+def test_should_require_loop_n_audit_json_persistence() -> None:
+    skill_text = _load_skill_text()
+    assert "loop-" in skill_text and "audit.json" in skill_text, (
+        "SKILL.md must reference loop-N-audit.json persistence path"
+    )
+
+
+def test_contract_should_require_findings_and_proof_of_absence_keys_in_json() -> None:
+    contract_text = _load_contract_text()
+    assert '"findings"' in contract_text or "findings[]" in contract_text, (
+        "loop-N-audit.json must have findings[] key"
+    )
+    assert (
+        '"proof_of_absence"' in contract_text or "proof_of_absence[]" in contract_text
+    ), "loop-N-audit.json must have proof_of_absence[] key"
+
+
+def test_contract_should_require_files_opened_in_proof_of_absence() -> None:
+    contract_text = _load_contract_text()
+    assert "files_opened" in contract_text, (
+        "Proof-of-absence struct must include files_opened[]"
+    )
+
+
+def test_step2_spawn_should_include_model_sonnet_parameter() -> None:
+    skill_text = _load_skill_text()
+    assert 'model="sonnet"' in skill_text, (
+        "Step 2 Agent() spawn template must include model=\"sonnet\" for the primary subagent"
+    )
+
+
+def test_step2_spawn_should_reference_clean_coder_and_haiku_secondary() -> None:
+    skill_text = _load_skill_text()
+    step2_marker = "## Step 2:"
+    step3_marker = "## Step 3:"
+    step2_start = skill_text.find(step2_marker)
+    step3_start = skill_text.find(step3_marker)
+    assert step2_start != -1, "SKILL.md must have a Step 2 section"
+    assert step3_start != -1, "SKILL.md must have a Step 3 section"
+    step2_region = skill_text[step2_start:step3_start]
+    assert "clean-coder" in step2_region, (
+        "Step 2 must reference the clean-coder primary subagent spawn"
+    )
+    assert "haiku" in step2_region.lower(), (
+        "Step 2 must reference the Haiku secondary auditor spawn"
+    )
+
+
+def test_prompts_md_should_contain_expanded_category_e_dead_code_variants() -> None:
+    prompts_text = _load_prompts_text()
+    assert (
+        "dead parameter" in prompts_text.lower()
+        or "dead parameters" in prompts_text.lower()
+    ), "Category E must cover dead parameters"
+    assert (
+        "dead local" in prompts_text.lower() or "dead locals" in prompts_text.lower()
+    ), "Category E must cover dead locals"
+    assert (
+        "dead import" in prompts_text.lower() or "dead imports" in prompts_text.lower()
+    ), "Category E must cover dead imports"
+    assert (
+        "dead branch" in prompts_text.lower() or "dead branches" in prompts_text.lower()
+    ), "Category E must cover dead branches"
+    assert (
+        "dead return" in prompts_text.lower() or "dead returns" in prompts_text.lower()
+    ), "Category E must cover dead returns"

package/skills/qbug/test_qbug_skill_post_fix_audit.py

@@ -0,0 +1,103 @@
+"""Tests verifying qbug SKILL.md contains required post-fix self-audit structural elements.
+
+Covers:
+- Post-fix self-audit inserted between py_compile and git add
+- Internal iteration cap of 3
+- loop-N-diagnostics.json with all eight source keys
+- converged condition requires both primary and post-fix audits clean
+- Stuck state when post-fix audit does not converge after 3 iterations
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+SKILL_FILE_PATH = Path(__file__).parent / "SKILL.md"
+
+
+def _load_skill_text() -> str:
+    return SKILL_FILE_PATH.read_text(encoding="utf-8")
+
+
+def test_should_require_post_fix_gate_before_git_add() -> None:
+    skill_text = _load_skill_text()
+    assert "bugteam_code_rules_gate" in skill_text, (
+        "FIX step must run bugteam_code_rules_gate against modified files"
+    )
+    assert "post-fix" in skill_text.lower() or "post_fix" in skill_text.lower(), (
+        "FIX step must reference a post-fix audit phase"
+    )
+
+
+def test_should_require_post_fix_audit_of_fix_diff() -> None:
+    skill_text = _load_skill_text()
+    assert "fix_diff" in skill_text, (
+        "FIX step must compute fix_diff for the post-fix scoped audit"
+    )
+
+
+def test_should_require_paranoid_mode_with_haiku_on_post_fix() -> None:
+    skill_text = _load_skill_text()
+    assert "paranoid" in skill_text.lower(), (
+        "Post-fix audit must be flagged as paranoid mode with Haiku secondary"
+    )
+
+
+def test_should_require_internal_iteration_cap_of_three() -> None:
+    skill_text = _load_skill_text()
+    assert "internal iteration cap = 3" in skill_text, (
+        "FIX step must specify the exact phrase 'internal iteration cap = 3'"
+    )
+    assert "stuck: post-fix audit not converging" in skill_text, (
+        "Exit message for cap exceeded must be 'stuck: post-fix audit not converging'"
+    )
+
+
+def test_should_only_git_add_when_post_fix_audit_is_clean() -> None:
+    skill_text = _load_skill_text()
+    post_fix_audit_block_header = "Post-fix self-audit"
+    post_fix_audit_block_index = skill_text.find(post_fix_audit_block_header)
+    assert post_fix_audit_block_index != -1, (
+        f"SKILL.md must contain the literal block header '{post_fix_audit_block_header}'"
+    )
+    git_add_index = skill_text.find("git add", post_fix_audit_block_index)
+    assert git_add_index > post_fix_audit_block_index, (
+        "git add must appear after the Post-fix self-audit block header, not before"
+    )
+
+
+def test_should_require_loop_n_diagnostics_json() -> None:
+    skill_text = _load_skill_text()
+    assert "diagnostics.json" in skill_text, (
+        "Each loop must write loop-N-diagnostics.json"
+    )
+
+
+def test_contract_should_require_all_eight_source_keys_in_diagnostics() -> None:
+    contract_path = (
+        Path(__file__).parent.parent / "bugteam" / "reference" / "audit-contract.md"
+    )
+    contract_text = contract_path.read_text(encoding="utf-8")
+    required_keys = [
+        "loop",
+        "gate_findings",
+        "primary_findings",
+        "adversarial_findings",
+        "haiku_findings",
+        "post_fix_findings",
+        "merged",
+        "deduped",
+    ]
+    for each_key in required_keys:
+        assert each_key in contract_text, (
+            f"loop-N-diagnostics.json schema in audit-contract.md must contain key '{each_key}'"
+        )
+
+
+def test_should_update_exit_conditions_to_require_post_fix_clean() -> None:
+    skill_text = _load_skill_text()
+    assert (
+        "post_fix_audit_clean" in skill_text
+        or "post-fix audit clean" in skill_text.lower()
+    ), "converged exit condition must require post_fix_audit_clean"