claude-dev-env 2.9.0 → 2.10.0

package/skills/_shared/pr-loop/scripts/audit_category_schema.py

@@ -0,0 +1,355 @@
+"""Load and validate the A-Q audit-category schema.
+
+One machine-readable source under audit-rubrics/audit-categories.json holds
+each category id, title, slug, and sub-bucket id/axis pairs. Worked examples
+stay in the rubric markdown files only.
+
+::
+
+    schema = load_audit_category_schema()
+    entries = category_id_title_entries()
+    # entries[0] == ("A", "API contract verification")
+    findings = validate_projections()
+    # findings == [] when rubrics and prompt skeletons match the schema
+
+Use validate_projections before shipping a rubric or prompt change so the
+three surfaces cannot drift.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+from skills_pr_loop_constants.audit_category_schema_constants import (
+    CATEGORY_ID_KEY,
+    CATEGORY_RUBRICS_DIRECTORY,
+    CATEGORY_SLUG_KEY,
+    CATEGORY_SLUG_PREFIX_TEMPLATE,
+    CATEGORY_SUB_BUCKETS_KEY,
+    CATEGORY_TITLE_KEY,
+    EXPECTED_CATEGORY_IDS,
+    HEADING_LETTER_GROUP,
+    HEADING_PATTERN,
+    HEADING_TITLE_GROUP,
+    JSON_INDENT,
+    NEWLINE,
+    PACKAGE_ROOT,
+    PROMPTS_DIRECTORY,
+    RUBRIC_SUB_BUCKET_ROW_TEMPLATE,
+    SCHEMA_CATEGORIES_KEY,
+    SCHEMA_RELATIVE_PATH,
+    SCHEMA_VERSION,
+    SCHEMA_VERSION_KEY,
+    SKELETON_COUNT_PATTERN,
+    SKELETON_PLACEHOLDER_FRAGMENT,
+    SKELETON_SEPARATOR_LINE,
+    SUB_BUCKET_AXIS_KEY,
+    UTF8_ENCODING,
+)
+
+CategoryMapping = dict[str, object]
+SchemaMapping = dict[str, object]
+
+
+def audit_category_schema_path() -> Path:
+    """Return the path to the committed A-Q schema JSON file.
+
+    Returns:
+        Absolute path to audit-categories.json under the package root.
+    """
+    return PACKAGE_ROOT / SCHEMA_RELATIVE_PATH
+
+
+def load_audit_category_schema() -> SchemaMapping:
+    """Load and structurally check the A-Q schema document.
+
+    Returns:
+        The schema object with schema_version and categories.
+
+    Raises:
+        FileNotFoundError: When the schema file is missing.
+        ValueError: When required fields or order are wrong.
+        json.JSONDecodeError: When the schema file is not valid JSON.
+    """
+    schema_path = audit_category_schema_path()
+    loaded_document = json.loads(schema_path.read_text(encoding=UTF8_ENCODING))
+    if not isinstance(loaded_document, dict):
+        raise ValueError("schema root must be an object")
+    if loaded_document.get(SCHEMA_VERSION_KEY) != SCHEMA_VERSION:
+        raise ValueError(
+            f"schema_version must be {SCHEMA_VERSION}, "
+            f"got {loaded_document.get(SCHEMA_VERSION_KEY)!r}"
+        )
+    all_categories = loaded_document.get(SCHEMA_CATEGORIES_KEY)
+    if not isinstance(all_categories, list) or not all_categories:
+        raise ValueError("categories must be a non-empty list")
+    all_ids = [
+        each_category.get(CATEGORY_ID_KEY)
+        for each_category in all_categories
+        if isinstance(each_category, dict)
+    ]
+    if all_ids != list(EXPECTED_CATEGORY_IDS):
+        raise ValueError(f"categories must list A-Q in order, got {all_ids!r}")
+    all_checked_categories: list[CategoryMapping] = []
+    for each_category in all_categories:
+        if not isinstance(each_category, dict):
+            raise ValueError("each category must be an object")
+        all_checked_categories.append(_require_category_shape(each_category))
+    return {
+        SCHEMA_VERSION_KEY: SCHEMA_VERSION,
+        SCHEMA_CATEGORIES_KEY: all_checked_categories,
+    }
+
+
+def _require_category_shape(all_category_fields: CategoryMapping) -> CategoryMapping:
+    category_id = all_category_fields.get(CATEGORY_ID_KEY)
+    if not isinstance(category_id, str) or len(category_id) != 1:
+        raise ValueError(f"category id must be a single letter, got {category_id!r}")
+    title = all_category_fields.get(CATEGORY_TITLE_KEY)
+    if not isinstance(title, str) or not title.strip():
+        raise ValueError(f"category {category_id} title must be a non-empty string")
+    slug = all_category_fields.get(CATEGORY_SLUG_KEY)
+    expected_slug_prefix = CATEGORY_SLUG_PREFIX_TEMPLATE.format(letter=category_id.lower())
+    if not isinstance(slug, str) or not slug.startswith(expected_slug_prefix):
+        raise ValueError(
+            f"category {category_id} slug must start with {expected_slug_prefix!r}, "
+            f"got {slug!r}"
+        )
+    all_sub_bucket_fields = all_category_fields.get(CATEGORY_SUB_BUCKETS_KEY)
+    if not isinstance(all_sub_bucket_fields, list) or not all_sub_bucket_fields:
+        raise ValueError(f"category {category_id} needs a non-empty sub_buckets list")
+    all_sub_buckets: list[CategoryMapping] = []
+    for each_index, each_sub_bucket in enumerate(all_sub_bucket_fields):
+        if not isinstance(each_sub_bucket, dict):
+            raise ValueError(f"category {category_id} sub_bucket {each_index} must be object")
+        expected_id = f"{category_id}{each_index + 1}"
+        sub_bucket_id = each_sub_bucket.get(CATEGORY_ID_KEY)
+        if sub_bucket_id != expected_id:
+            raise ValueError(
+                f"category {category_id} sub_bucket {each_index} id must be "
+                f"{expected_id}, got {sub_bucket_id!r}"
+            )
+        axis_name = each_sub_bucket.get(SUB_BUCKET_AXIS_KEY)
+        if not isinstance(axis_name, str) or not axis_name.strip():
+            raise ValueError(
+                f"category {category_id} sub_bucket {sub_bucket_id} needs axis_name"
+            )
+        all_sub_buckets.append(
+            {CATEGORY_ID_KEY: expected_id, SUB_BUCKET_AXIS_KEY: axis_name}
+        )
+    return {
+        CATEGORY_ID_KEY: category_id,
+        CATEGORY_TITLE_KEY: title,
+        CATEGORY_SLUG_KEY: slug,
+        CATEGORY_SUB_BUCKETS_KEY: all_sub_buckets,
+    }
+
+
+def category_id_title_entries() -> list[tuple[str, str]]:
+    """Return (id, title) pairs in A-Q order from the schema.
+
+    Returns:
+        List of (category letter, title) tuples from the schema file.
+    """
+    all_schema = load_audit_category_schema()
+    all_categories = all_schema[SCHEMA_CATEGORIES_KEY]
+    assert isinstance(all_categories, list)
+    all_entries: list[tuple[str, str]] = []
+    for each_category in all_categories:
+        assert isinstance(each_category, dict)
+        category_id = each_category[CATEGORY_ID_KEY]
+        title = each_category[CATEGORY_TITLE_KEY]
+        assert isinstance(category_id, str)
+        assert isinstance(title, str)
+        all_entries.append((category_id, title))
+    return all_entries
+
+
+def render_skeleton_projections(all_schema: SchemaMapping) -> dict[str, str]:
+    """Build deterministic skeleton text per category from the schema only.
+
+    Args:
+        all_schema: Loaded audit-category schema.
+
+    Returns:
+        Map of category letter to a stable multi-line skeleton projection.
+    """
+    projection_by_letter: dict[str, str] = {}
+    all_categories = all_schema[SCHEMA_CATEGORIES_KEY]
+    assert isinstance(all_categories, list)
+    for each_category in all_categories:
+        assert isinstance(each_category, dict)
+        category_id = each_category[CATEGORY_ID_KEY]
+        title = each_category[CATEGORY_TITLE_KEY]
+        slug = each_category[CATEGORY_SLUG_KEY]
+        all_sub_buckets = each_category[CATEGORY_SUB_BUCKETS_KEY]
+        assert isinstance(category_id, str)
+        assert isinstance(title, str)
+        assert isinstance(slug, str)
+        assert isinstance(all_sub_buckets, list)
+        sub_bucket_count = len(all_sub_buckets)
+        all_lines = [
+            f"Category {category_id} — {title}",
+            f"slug: {slug}",
+            f"decomposed into {sub_bucket_count} sub-buckets",
+            f"For each sub-bucket {category_id}1-{category_id}{sub_bucket_count}:",
+        ]
+        for each_sub_bucket in all_sub_buckets:
+            assert isinstance(each_sub_bucket, dict)
+            sub_bucket_id = each_sub_bucket[CATEGORY_ID_KEY]
+            axis_name = each_sub_bucket[SUB_BUCKET_AXIS_KEY]
+            all_lines.append(f"{sub_bucket_id}. {axis_name}")
+        projection_by_letter[category_id] = NEWLINE.join(all_lines) + NEWLINE
+    return projection_by_letter
+
+
+def _validate_one_category(each_category: CategoryMapping) -> list[str]:
+    category_id = each_category[CATEGORY_ID_KEY]
+    slug = each_category[CATEGORY_SLUG_KEY]
+    title = each_category[CATEGORY_TITLE_KEY]
+    all_sub_buckets = each_category[CATEGORY_SUB_BUCKETS_KEY]
+    assert isinstance(category_id, str)
+    assert isinstance(slug, str)
+    assert isinstance(title, str)
+    assert isinstance(all_sub_buckets, list)
+    all_findings: list[str] = []
+    rubric_path = CATEGORY_RUBRICS_DIRECTORY / f"{slug}.md"
+    prompt_path = PROMPTS_DIRECTORY / f"{slug}.md"
+    if not rubric_path.is_file():
+        return [f"{category_id}: missing rubric {rubric_path.name}"]
+    if not prompt_path.is_file():
+        return [f"{category_id}: missing prompt {prompt_path.name}"]
+    rubric_text = rubric_path.read_text(encoding=UTF8_ENCODING)
+    all_rubric_lines = rubric_text.splitlines()
+    if not all_rubric_lines:
+        return [f"{category_id}: empty rubric"]
+    heading_match = HEADING_PATTERN.match(all_rubric_lines[0])
+    if heading_match is None:
+        return [f"{category_id}: rubric heading does not match pattern"]
+    heading_letter = heading_match.group(HEADING_LETTER_GROUP)
+    heading_title = heading_match.group(HEADING_TITLE_GROUP)
+    if heading_letter != category_id:
+        all_findings.append(f"{category_id}: rubric heading letter {heading_letter!r}")
+    if heading_title != title:
+        all_findings.append(
+            f"{category_id}: rubric title {heading_title!r} != schema {title!r}"
+        )
+    row_pattern = re.compile(
+        RUBRIC_SUB_BUCKET_ROW_TEMPLATE.format(category_id=re.escape(category_id)),
+        re.MULTILINE,
+    )
+    all_rubric_rows = row_pattern.findall(rubric_text)
+    all_schema_rows: list[tuple[str, str]] = []
+    for each_sub_bucket in all_sub_buckets:
+        assert isinstance(each_sub_bucket, dict)
+        sub_bucket_id = each_sub_bucket[CATEGORY_ID_KEY]
+        axis_name = each_sub_bucket[SUB_BUCKET_AXIS_KEY]
+        assert isinstance(sub_bucket_id, str)
+        assert isinstance(axis_name, str)
+        all_schema_rows.append((sub_bucket_id, axis_name))
+    all_rubric_pairs = [(row_id, axis.strip()) for row_id, axis in all_rubric_rows]
+    if all_rubric_pairs != all_schema_rows:
+        all_findings.append(
+            f"{category_id}: rubric sub-buckets {all_rubric_pairs!r} "
+            f"!= schema {all_schema_rows!r}"
+        )
+    all_findings.extend(
+        _validate_prompt_skeleton_count(category_id, prompt_path, len(all_sub_buckets))
+    )
+    return all_findings
+
+
+def _validate_prompt_skeleton_count(
+    category_id: str,
+    prompt_path: Path,
+    sub_bucket_count: int,
+) -> list[str]:
+    prompt_text = prompt_path.read_text(encoding=UTF8_ENCODING)
+    all_skeleton_lines: list[str] = []
+    for each_line in prompt_text.splitlines():
+        if each_line == SKELETON_SEPARATOR_LINE:
+            break
+        all_skeleton_lines.append(each_line)
+    skeleton_text = NEWLINE.join(all_skeleton_lines)
+    if SKELETON_PLACEHOLDER_FRAGMENT in skeleton_text:
+        return [
+            f"{category_id}: prompt skeleton still uses [N] placeholder; "
+            f"use numeric count {sub_bucket_count}"
+        ]
+    count_match = SKELETON_COUNT_PATTERN.search(skeleton_text)
+    if count_match is None:
+        return [f"{category_id}: prompt skeleton missing sub-bucket count form"]
+    skeleton_count = int(count_match.group(HEADING_LETTER_GROUP))
+    if skeleton_count != sub_bucket_count:
+        return [
+            f"{category_id}: prompt skeleton count {skeleton_count} "
+            f"!= schema {sub_bucket_count}"
+        ]
+    return []
+
+
+def validate_projections() -> list[str]:
+    """Compare schema against on-disk rubric and prompt skeleton projections.
+
+    Returns:
+        Finding strings; empty when every category is in parity.
+    """
+    all_schema = load_audit_category_schema()
+    all_categories = all_schema[SCHEMA_CATEGORIES_KEY]
+    assert isinstance(all_categories, list)
+    all_findings: list[str] = []
+    for each_category in all_categories:
+        assert isinstance(each_category, dict)
+        all_findings.extend(_validate_one_category(each_category))
+    return all_findings
+
+
+def main(all_argv: list[str]) -> int:
+    """CLI: validate projections or print deterministic skeleton projections.
+
+    Args:
+        all_argv: Argument list without the program name.
+
+    Returns:
+        Process exit code (0 success, 1 validation findings).
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--validate",
+        action="store_true",
+        help="Validate rubric and prompt projections against the schema.",
+    )
+    parser.add_argument(
+        "--render-skeletons",
+        action="store_true",
+        help="Print deterministic skeleton projections as JSON.",
+    )
+    arguments = parser.parse_args(all_argv)
+    if arguments.validate:
+        all_findings = validate_projections()
+        if all_findings:
+            for each_finding in all_findings:
+                print(each_finding, file=sys.stderr)
+            return 1
+        print("OK")
+        return 0
+    if arguments.render_skeletons:
+        all_schema = load_audit_category_schema()
+        print(
+            json.dumps(
+                render_skeleton_projections(all_schema),
+                indent=JSON_INDENT,
+                ensure_ascii=False,
+            )
+        )
+        return 0
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/CLAUDE.md

@@ -8,6 +8,7 @@ Python package of named constants for the `pr-loop` shared scripts. All constant
 |---|---|
 | `__init__.py` | Package marker. |
 | `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, fix status values, audit constraint texts, audit category entries, fix execution steps, and fix constraint texts. |
+| `audit_category_schema_constants.py` | Paths, regexes, and encoding constants for `audit_category_schema.py` (A-Q schema load and projection parity). |
 | `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
 | `handoff_constants.py` | Filename, path-segment, and template constants for the durable handoff writer. |
 | `pacer_constants.py` | Entry-skill names, pacer tokens, CLI flags, and result keys for `select_converge_pacer.py`. |

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/audit_category_schema_constants.py

@@ -0,0 +1,32 @@
+"""Constants for audit_category_schema path resolution and parity checks."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent.parent
+PACKAGE_ROOT = SCRIPTS_DIRECTORY.parents[3]
+SCHEMA_RELATIVE_PATH = Path("audit-rubrics") / "audit-categories.json"
+CATEGORY_RUBRICS_DIRECTORY = PACKAGE_ROOT / "audit-rubrics" / "category_rubrics"
+PROMPTS_DIRECTORY = PACKAGE_ROOT / "audit-rubrics" / "prompts"
+HEADING_PATTERN = re.compile(r"^# Category ([A-Q]) — (.+)$")
+HEADING_LETTER_GROUP = 1
+HEADING_TITLE_GROUP = 2
+EXPECTED_CATEGORY_IDS = tuple("ABCDEFGHIJKLMNOPQ")
+SCHEMA_VERSION = 1
+JSON_INDENT = 2
+NEWLINE = "\n"
+UTF8_ENCODING = "utf-8"
+RUBRIC_SUB_BUCKET_ROW_TEMPLATE = r"^\| ({category_id}\d+) \| ([^|]+) \|"
+SKELETON_COUNT_PATTERN = re.compile(r"decomposed into (\d+) sub-buckets")
+SKELETON_PLACEHOLDER_FRAGMENT = "decomposed into [N] sub-buckets"
+SKELETON_SEPARATOR_LINE = "---"
+CATEGORY_SLUG_PREFIX_TEMPLATE = "category-{letter}-"
+CATEGORY_ID_KEY = "id"
+CATEGORY_TITLE_KEY = "title"
+CATEGORY_SLUG_KEY = "slug"
+CATEGORY_SUB_BUCKETS_KEY = "sub_buckets"
+SUB_BUCKET_AXIS_KEY = "axis_name"
+SCHEMA_CATEGORIES_KEY = "categories"
+SCHEMA_VERSION_KEY = "schema_version"

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/path_resolver_constants.py

@@ -2,6 +2,8 @@
 
 import re
 
+from audit_category_schema import category_id_title_entries
+
 RUN_NAME_TEMPLATE_SINGLE = "bugteam-pr-{number}"
 RUN_NAME_TEMPLATE_MULTI = "bugteam-{sanitized_branch}"
 PER_PR_WORKSPACE_TEMPLATE = "pr-{number}"
@@ -24,30 +26,16 @@ ALL_AUDIT_CONSTRAINT_TEXTS = [
     "Work exclusively within the worktree directory.",
     "Every finding must cite file:line.",
     "Document each finding with severity, file, line, and suggested fix.",
+    "Report every real finding. Collection retains all severities "
+    "(P0, P1, P2). Do not drop findings by severity during collection; "
+    "severity or action filtering is a separate consumer stage after the "
+    "collection record is complete.",
     "Read each file in the diff before reporting on it.",
     "Double-quote every path in shell commands and write paths with "
     "forward slashes (e.g. C:/Users/...), even on Windows.",
 ]
 
-ALL_AUDIT_CATEGORY_ENTRIES = [
-    ("A", "API contract verification"),
-    ("B", "Selector / query / engine compatibility"),
-    ("C", "Resource cleanup and lifecycle"),
-    ("D", "Variable scoping, ordering, and unbound references"),
-    ("E", "Dead code and unused imports"),
-    ("F", "Silent failures"),
-    ("G", "Off-by-one, bounds, integer overflow"),
-    ("H", "Security boundaries"),
-    ("I", "Concurrency hazards"),
-    ("J", "CODE_RULES.md compliance"),
-    ("K", "Codebase conflicts (incomplete propagation)"),
-    ("L", "Behavior-equivalence for refactors"),
-    ("M", "Producer/consumer cardinality vs collection-type contract"),
-    ("N", "Test-name scenario verifier"),
-    ("O", "Docstring / fixture-prose vs implementation drift"),
-    ("P", "Name / regex / word-list vs behavior-contract precision"),
-    ("Q", "Cross-surface claim consistency (terminology, PR-description claims, message-vs-guard)"),
-]
+ALL_AUDIT_CATEGORY_ENTRIES = category_id_title_entries()
 
 AUDIT_RUBRIC_REFERENCE_TEXT = (
     "The category list above is a summary. The binding definition of each "

package/skills/_shared/pr-loop/scripts/test_audit_category_schema.py

@@ -0,0 +1,94 @@
+"""Parity tests for the A-Q audit-category schema and projections."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from skills_pr_loop_constants.audit_category_schema_constants import (
+    CATEGORY_SLUG_KEY,
+    CATEGORY_SUB_BUCKETS_KEY,
+    PROMPTS_DIRECTORY,
+    SCHEMA_CATEGORIES_KEY,
+    SKELETON_PLACEHOLDER_FRAGMENT,
+    SKELETON_SEPARATOR_LINE,
+    UTF8_ENCODING,
+)
+from skills_pr_loop_constants.path_resolver_constants import ALL_AUDIT_CATEGORY_ENTRIES
+
+
+def _load_audit_category_schema() -> ModuleType:
+    module_path = _SCRIPTS_DIR / "audit_category_schema.py"
+    spec = importlib.util.spec_from_file_location("audit_category_schema", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["audit_category_schema"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+audit_category_schema = _load_audit_category_schema()
+
+
+def test_schema_lists_a_through_q_in_order() -> None:
+    schema = audit_category_schema.load_audit_category_schema()
+    all_ids = [each_category["id"] for each_category in schema["categories"]]
+    assert all_ids == list("ABCDEFGHIJKLMNOPQ")
+
+
+def test_schema_entries_match_constant_export() -> None:
+    assert (
+        audit_category_schema.category_id_title_entries()
+        == list(ALL_AUDIT_CATEGORY_ENTRIES)
+    )
+
+
+def test_validate_projections_matches_rubrics_and_prompts() -> None:
+    all_findings = audit_category_schema.validate_projections()
+    assert all_findings == [], all_findings
+
+
+def test_skeleton_projection_is_byte_stable() -> None:
+    schema = audit_category_schema.load_audit_category_schema()
+    first_render = audit_category_schema.render_skeleton_projections(schema)
+    second_render = audit_category_schema.render_skeleton_projections(
+        json.loads(json.dumps(schema))
+    )
+    assert first_render == second_render
+    assert "A1" in first_render["A"]
+    assert first_render["A"].count("\n") >= 1
+
+
+def test_schema_omits_worked_example_prose() -> None:
+    schema_path = audit_category_schema.audit_category_schema_path()
+    schema_text = schema_path.read_text(encoding="utf-8")
+    assert "Examples of Category" not in schema_text
+    assert "Sample prompt" not in schema_text
+
+
+def test_no_prompt_skeleton_uses_placeholder_count() -> None:
+    """Migrated prompts state a numeric sub-bucket count, never [N]."""
+    schema = audit_category_schema.load_audit_category_schema()
+    all_findings = audit_category_schema.validate_projections()
+    assert all_findings == [], all_findings
+    for each_category in schema[SCHEMA_CATEGORIES_KEY]:
+        slug = each_category[CATEGORY_SLUG_KEY]
+        assert isinstance(slug, str)
+        prompt_path = PROMPTS_DIRECTORY / f"{slug}.md"
+        all_skeleton_lines: list[str] = []
+        for each_line in prompt_path.read_text(encoding=UTF8_ENCODING).splitlines():
+            if each_line == SKELETON_SEPARATOR_LINE:
+                break
+            all_skeleton_lines.append(each_line)
+        skeleton_text = "\n".join(all_skeleton_lines)
+        assert SKELETON_PLACEHOLDER_FRAGMENT not in skeleton_text, slug
+        sub_bucket_count = len(each_category[CATEGORY_SUB_BUCKETS_KEY])
+        assert f"decomposed into {sub_bucket_count} sub-buckets" in skeleton_text, slug

package/skills/_shared/pr-loop/scripts/test_build_audit_prompt.py

@@ -424,3 +424,24 @@ def test_precatch_rubric_adversarial_lane_uses_a_through_q() -> None:
     rubric_text = _PRECATCH_RUBRIC_PATH.read_text(encoding="utf-8")
     assert _A_THROUGH_Q_PATTERN.search(rubric_text) is not None
     assert _STALE_A_THROUGH_P_PATTERN.search(rubric_text) is None
+
+
+def test_audit_prompt_constraints_require_collection_before_severity_filter() -> None:
+    root = _build_audit_root()
+    constraints = root.find("constraints")
+    assert constraints is not None
+    all_constraint_texts = [
+        each_constraint.text or "" for each_constraint in constraints
+    ]
+    joined = "\n".join(all_constraint_texts)
+    assert "Report every real finding" in joined
+    assert "Do not drop findings by severity during collection" in joined
+    assert "separate consumer stage" in joined
+    assert "P0" in joined and "P1" in joined and "P2" in joined
+
+
+def test_audit_contract_documents_collection_before_severity_filtering() -> None:
+    contract_text = _AUDIT_CONTRACT_PATH.read_text(encoding="utf-8")
+    assert "## Collection before severity filtering" in contract_text
+    assert "separate consumer stage" in contract_text
+    assert "Do not drop a real finding because its severity is low" in contract_text

package/skills/autoconverge/reference/convergence.md

@@ -152,7 +152,8 @@ existing fix + re-converge path.
 - Runs after Bugbot and Copilot. Honors `reviews_disabled.py --reviewer codex`,
   the weekly usage probe via `is_codex_review_required` (shared threshold
   constant — no inline percent), and the wrapper's `codex_down` class.
-- Opt-out token or `codex_down` → set `codexDown`, no stamp, move to the
+- Missing opt-in (the default), opt-out token, or `codex_down` → set
+  `codexDown`, no stamp, move to the
   convergence check with `--codex-down`. A `codex_down` classification also
   records a `codexNote` so the skip stays visible in the final report.
 - Usage at/below threshold or null → skip with no stamp; the machine checklist

package/skills/autoconverge/reference/stop-conditions.md

@@ -88,10 +88,12 @@ Each reviewer-down condition below skips its own convergence-check gate. The fla
   `--copilot-down` (the Copilot review gate and the pending-requested-reviews
   gate bypassed), then mark-ready. `copilotNote` records the bypass for the
   final report.
-- **Terminal Codex gate skipped (opt-out, usage, or `codex_down`)** — the
+- **Terminal Codex gate skipped (no opt-in, opt-out, usage, or `codex_down`)** — the
   conditional-required Codex gate runs after Bugbot and Copilot. When
-  `CLAUDE_REVIEWS_DISABLED` lists `codex` (`reviews_disabled.py --reviewer codex`
-  exit 0), the gate sets `codexDown` and advances with no review. When the weekly
+  `reviews_disabled.py --reviewer codex` exits 0 — which it does whenever
+  `CLAUDE_REVIEWS_ENABLED` omits `codex`, the default, and whenever
+  `CLAUDE_REVIEWS_DISABLED` lists it — the gate sets `codexDown` and advances
+  with no review. When the weekly
   usage probe reports `percent_left` null or at/below the shared threshold
   (`is_codex_review_required` false), the gate skips without a stamp; the
   convergence check applies the same rule. When the codex-review wrapper

package/skills/beat-sheet/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: beat-sheet
+description: "Formats a reply as single-line beats in plain everyday words. Triggers: '/beat-sheet', 'beat sheet this', 'give me the beats', 'write this as beats', 'too long', 'shorter', 'what?', 'english', 'no sense', 'jargon', 'huh?'."
+---
+
+# beat-sheet
+
+Write in single-line beats. Make each line one complete thought,
+under 12 words, with a blank line between lines. Keep it to ten
+lines, each one covering a new point. Order: situation, problem,
+fix, how it works. Put any command in its own code fence. Start
+with one short bold title line. Use plain everyday words a tired
+reader can skim.
+
+## Plain words
+
+Name the real thing first — a file, an image, a control, a
+screen, a size, an id, a proof. Prefer a word the reader can point
+at over an abstract one. When a word only makes sense on this
+project, say what it is in the app or on disk (a Theme Studio
+control, a package file name).
+
+## What the reader gets
+
+Lead with the answer. Put most of the reply on what they asked;
+keep warnings short. For "what's wrong" or "what's missing",
+answer in this order: what's wrong, what's missing, what follows.
+For an explain request, give a short summary unless they ask for
+more.
+
+## Around the work
+
+Before the first tool call, say in one sentence what you'll do.
+While working, speak up only on an important find or a change of
+course. When you finish, open with the result — what happened or
+what you found — then add detail only if it helps.
+
+## Job size
+
+Do the job asked, at the size asked. Decide small things
+yourself; ask only when two readings would change the work. When
+the ask looks off or a better path is clear, say so in one
+sentence, then do what was asked. Finish the whole job.
+
+## Before sending
+
+Read the reply as someone new to the project. Replace any word
+that needs a glossary with the thing itself.
+
+## Visual beats
+
+Add a visual only when it earns its space beyond what the beats
+already show on their own. See `reference/visual-beats.md` for the
+shape picker, the `rich` setup, and a working example.

package/skills/beat-sheet/reference/visual-beats.md

@@ -0,0 +1,29 @@
+# Visual beats
+
+Use one visual per reply, at most, sitting between beats in place
+of the beat it explains.
+
+Build it with `rich` (`pip install rich`), then paste the printed
+text into a fenced block. Set `no_color=True` and a fixed `width`
+so the output holds its shape in a terminal and on GitHub.
+
+Pick the shape by what the beat carries:
+
+| Shape | Carries |
+|---|---|
+| `Panel` | one claim worth framing |
+| `Table` | values a reader compares |
+| `Tree` | a stack, or parts inside a whole |
+
+```python
+from rich.console import Console
+from rich.table import Table
+from rich import box
+
+console = Console(width=64, no_color=True, force_terminal=False)
+table = Table(box=box.SIMPLE_HEAVY, title="Slice budget")
+table.add_column("slice")
+table.add_column("lines", justify="right")
+table.add_row("tests", "200")
+console.print(table)
+```