claude-dev-env 2.8.0 → 2.10.0

package/skills/_shared/advisor/CLAUDE.md

@@ -0,0 +1,9 @@
+# Advisor
+
+**Canonical home:**
+
+@~/.claude/_shared/advisor/CLAUDE.md
+
+@~/.claude/_shared/advisor/advisor-protocol.md
+
+Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `tier_model_ids.py`, constants under `scripts/config/`).

package/skills/_shared/advisor/advisor-protocol.md

@@ -0,0 +1,5 @@
+# Advisor protocol
+
+**Canonical home:**
+
+@~/.claude/_shared/advisor/advisor-protocol.md

package/skills/_shared/advisor/scripts/README.md

@@ -0,0 +1,9 @@
+# Advisor scripts
+
+**Canonical home:**
+
+@~/.claude/_shared/advisor/scripts/model_tier_run_validator.py
+
+@~/.claude/_shared/advisor/scripts/tier_model_ids.py
+
+Full tree: `~/.claude/_shared/advisor/scripts/`.

package/skills/_shared/end-of-run-gotcha-recommendations.md

@@ -0,0 +1,156 @@
+# End-of-run gotcha recommendations
+
+**Shared close-out** for every skill.
+
+After the deliverable, recommend pasteable gotchas from issues **this run** hit.
+
+## When
+
+- **With issues:** end of work, after the deliverable.
+- **Clean run:** end with the deliverable only.
+
+## What counts
+
+Keep only items that **bit this run**:
+
+- Wrong **path, file, or config**
+- **Command / CLI** failed or needed different flags
+- **Auth, permission, or environment** blocked a step
+- **Data shape** mismatch (empty set, wrong schema, bad field)
+- **Tool, UI, or selector** missed the target
+- **Timing** needed a retry or longer wait
+- **Dependency or install** gap or wrong version
+- **Output format** wrong for the next step
+- A **workaround** required to finish
+
+## What to produce
+
+**Order (hard):**
+
+1. Show findings in chat; categorize as P0-P3.
+2. Then `AskUserQuestion`.
+3. On confirm only, file via `issue-tracker`.
+
+### Cold-reader frame
+
+Assume zero context.
+
+**Exactly two setup sentences**, each on its **own rendered line**:
+
+1. What we were doing.
+2. Why these notes matter.
+
+### 1. Chat findings (always first)
+
+#### Sentence law (HARD)
+
+| Rule | Required |
+|---|---|
+| **One sentence per rendered line** | Exactly one terminal `.` `?` or `!` on that line |
+| **No collapsed pairs** | A single markdown newline is **not** a line break — it joins sentences |
+| **Force the break** | Blank line between every prose sentence, **or** one list item per sentence |
+| **No clause glue** | No em-dash or semicolon joining two clauses |
+| **One idea** | If you can split it, split it |
+| **Heavy detail** | Prefer an **ASCII infographic** over a stack of sentences |
+
+**Self-check before send:** paste the chat into a viewer that collapses soft breaks.
+
+If two periods appear on one visual line, **split or diagram**.
+
+#### Per gotcha (HARD shape)
+
+| Part | Form |
+|---|---|
+| **Title** | Heading fragment only |
+| **Broke** | One sentence alone on its rendered line |
+| **Fix** | One sentence alone on its rendered line |
+| **ASCII** | Required for path, flag, or before/after |
+
+**Cap: two prose sentences per gotcha.**
+
+```markdown
+## Session close-out
+
+We built phone-theme prompts from a project style catalog.
+
+Keep these traps for the next run.
+
+## Gotcha recommendations
+
+### Wrong catalog folder
+
+The style picker failed outside the project.
+
+Run from the project root with data/midjourney_sref_catalog.json.
+
+```text
+wrong folder --> fail
+project root --> data/midjourney_sref_catalog.json
+```
+```
+
+**Wrong (soft break joins sentences into one line):**
+
+```markdown
+The style picker failed outside the project.
+Run from the project root with data/midjourney_sref_catalog.json.
+```
+
+Renders as one line with **two** sentences.
+
+**Right (blank line forces two lines):**
+
+```markdown
+The style picker failed outside the project.
+
+Run from the project root with data/midjourney_sref_catalog.json.
+```
+
+**Right (list items):**
+
+```markdown
+- The style picker failed outside the project.
+- Run from the project root with data/midjourney_sref_catalog.json.
+```
+
+### 2. Issue offer (`AskUserQuestion`)
+
+Only after the chat block.
+
+| Field | Limit |
+|---|---|
+| **Question** | One short sentence |
+| **Header** | `File issues` |
+| **label** | Plain name |
+| **description** | One short sentence |
+
+Detail and ASCII stay in chat.
+
+**On confirm:** file via `issue-tracker`.
+
+Cold-reader issue body.
+
+Clean run: skip.
+
+## Built-in skill gotcha
+
+**Two sentences on one rendered line.**
+
+Markdown soft-breaks join prose.
+
+Review the close-out before send.
+
+Split with a blank line or a list item.
+
+Or move the detail into an ASCII infographic.
+
+## Rules
+
+- Cold-reader first.
+- Chat first, then ask.
+- One sentence per **rendered** line.
+- Blank line or list item between prose sentences.
+- Two prose sentences per gotcha max.
+- ASCII for path, flag, or before/after.
+- File only on confirm.
+- Lived issues only.

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

@@ -12,7 +12,24 @@ those skills invoke during each loop tick.
 | `prompts/` | XML agent prompt templates. |
 | `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, pacer selection, and preflight checks. |
 
-## Key files
+## Canonical-path stubs (`~/.claude/_shared/pr-loop/`)
+
+Open a stub, then load the `@` target:
+
+| Stub here | Load |
+|---|---|
+| `audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
+| `audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
+| `code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
+| `fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
+| `gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
+| `post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
+| `precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
+| `worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
+| `scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (live in this tree)
 
 | File | Role |
 |---|---|

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

@@ -0,0 +1,5 @@
+# Audit contract
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/audit-contract.md

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

@@ -0,0 +1,5 @@
+# Audit reply template
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/audit-reply-template.md

package/skills/_shared/pr-loop/code-rules-gate.md

@@ -0,0 +1,5 @@
+# Code rules gate
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/code-rules-gate.md

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

@@ -0,0 +1,5 @@
+# Fix protocol
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/fix-protocol.md

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

@@ -0,0 +1,5 @@
+# Gh payloads
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/gh-payloads.md

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

@@ -0,0 +1,5 @@
+# Post-audit thread contract
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/post-audit-thread-contract.md

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

@@ -0,0 +1,5 @@
+# Precatch rubric
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/precatch-rubric.md

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

@@ -2,10 +2,18 @@
 
 Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr-converge` invoke these scripts during each loop tick.
 
-## Key files
+## Two script homes
+
+| Home | Path |
+|---|---|
+| **Skill-local** (this folder) | Converge helpers: `build_*_prompt.py`, `init_loop_state.py`, `portable_converge_driver.py`, … |
+| **Runtime** (top-level shared) | Gate / preflight / review helpers — see `RUNTIME_SCRIPTS.md` → `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (skill-local)
 
 | File | Role |
 |---|---|
+| `audit_category_schema.py` | Loads the A-Q schema JSON, exports category entries, validates rubric/prompt projections, renders deterministic skeletons. |
 | `build_audit_prompt.py` | Assembles the audit agent prompt from loop state and category constants. |
 | `build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings XML. |
 | `init_loop_state.py` | Initializes the per-PR `loop-state.json` file in the workspace directory. |

package/skills/_shared/pr-loop/scripts/RUNTIME_SCRIPTS.md

@@ -0,0 +1,29 @@
+# PR-loop runtime scripts
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/scripts/code_rules_gate.py
+
+@~/.claude/_shared/pr-loop/scripts/preflight.py
+
+@~/.claude/_shared/pr-loop/scripts/post_audit_thread.py
+
+@~/.claude/_shared/pr-loop/scripts/post_audit_review.py
+
+@~/.claude/_shared/pr-loop/scripts/gh_util.py
+
+@~/.claude/_shared/pr-loop/scripts/reviews_disabled.py
+
+@~/.claude/_shared/pr-loop/scripts/reviewer_availability.py
+
+@~/.claude/_shared/pr-loop/scripts/copilot_quota.py
+
+@~/.claude/_shared/pr-loop/scripts/grant_project_claude_permissions.py
+
+@~/.claude/_shared/pr-loop/scripts/revoke_project_claude_permissions.py
+
+@~/.claude/_shared/pr-loop/scripts/verify_review.py
+
+@~/.claude/_shared/pr-loop/scripts/README.md
+
+Skill-local converge helpers (`build_*_prompt.py`, `init_loop_state.py`, and siblings) live in this `scripts/` folder. Runtime gate, preflight, and review helpers live under `~/.claude/_shared/pr-loop/scripts/`.

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`. |