claude-dev-env 2.9.0 → 2.11.0

package/skills/pr-converge/scripts/check_convergence.py

@@ -16,17 +16,16 @@ Each bypass flag closes one reviewer gate when that reviewer is unavailable.
 the Copilot review and pending-review gates. ``--bugteam-post-blocked`` skips
 the bugteam CLEAN-review gate. ``--codex-down`` skips the Codex review gate.
 
-Each flag also honors its own reviews-disabled token: "bugbot", "copilot",
-"bugteam", or "codex". A caller that cannot pass the flag reaches the same
-bypass by exporting the token. The mark-ready blocker hook re-runs this script
-with no flags, so its convergence re-check reads the bypass from the exported
-token instead. For Codex, sticky job-dir state ``codex_down: true`` is a third
-bypass source when the original run could not re-pass ``--codex-down``.
-
-Copilot and Bugbot waivers are disk-authoritative.
+Bugbot, bugteam, and codex are off by default. Each gate runs only when
+``CLAUDE_REVIEWS_ENABLED`` lists its token, and a token in
+``CLAUDE_REVIEWS_DISABLED`` forces one off even when the opt-in lists it.
+Copilot runs by default and stops only when the disabled list names it. For
+Codex, sticky job-dir state ``codex_down: true`` is a further bypass source
+when the original run could not re-pass ``--codex-down``.
+
+Every reviewer waiver is disk-authoritative.
 When ``~/.claude/settings.json`` is readable, its env block is the single source.
 The frozen process env is only a fallback when that disk read fails (logged once).
-Bugteam's opt-out is env-only via ``_resolve_bugteam_post_blocked``.
 A probe error does not waive the gate; the live GitHub checks still run.
 
 The Codex gate is conditional-required: it demands
@@ -105,11 +104,11 @@ from pr_converge_skill_constants.constants import (
 )
 from reviews_disabled import (
     is_bugbot_disabled_via_env,
-    is_bugteam_disabled_via_env,
-    is_codex_disabled_via_env,
     is_copilot_disabled_via_env,
 )
 from check_convergence_availability import (
+    _is_bugteam_disabled_via_resolved_settings,
+    _is_codex_disabled_via_resolved_settings,
     _resolve_bugbot_waiver,
     _resolve_copilot_waiver,
     _waiver_from_cli_flag,
@@ -815,18 +814,21 @@ def _resolve_copilot_down(is_copilot_down_flag: bool) -> bool:
 
 
 def _resolve_bugteam_post_blocked(is_bugteam_post_blocked_flag: bool) -> bool:
-    """Combine the --bugteam-post-blocked flag with the bugteam env opt-out.
+    """Combine the --bugteam-post-blocked flag with the resolved bugteam opt-in.
 
     ::
 
-        flag True, env unset                        -> True   (caller passed the flag)
-        flag False, reviews-disabled lists bugteam  -> True   (exported token)
-        flag False, env unset                       -> False  (gate runs)
+        flag True                                   -> True   (caller passed the flag)
+        flag False, reviews-enabled lists bugteam   -> False  (gate runs)
+        flag False, neither list names bugteam      -> True   (off by default)
+        flag False, reviews-disabled lists bugteam  -> True   (opt-out wins)
 
-    The mark-ready blocker hook re-runs this script with no flags, so the env
-    fallback lets an exported bugteam token carry the bypass into that re-check.
+    Bugteam is off by default and runs only on an explicit opt-in. Settings on
+    disk are the source when readable, so a settings.json opt-in reaches the
+    mark-ready blocker hook, which re-runs this script with no flags. The
+    process env is the fallback when that disk read fails.
     """
-    return is_bugteam_post_blocked_flag or is_bugteam_disabled_via_env()
+    return is_bugteam_post_blocked_flag or _is_bugteam_disabled_via_resolved_settings()
 
 
 def _resolve_codex_down(
@@ -854,7 +856,7 @@ def _resolve_codex_down(
     """
     return (
         is_codex_down_flag
-        or is_codex_disabled_via_env()
+        or _is_codex_disabled_via_resolved_settings()
         or _read_codex_down_from_job_state(all_job_state_fields)
     )
 

package/skills/pr-converge/scripts/check_convergence_availability.py

@@ -45,6 +45,8 @@ from pr_loop_shared_constants.copilot_quota_constants import (
 )
 from pr_loop_shared_constants.reviews_disabled_constants import (
     CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN,
     CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
     CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR,
@@ -120,8 +122,15 @@ def _log_disk_settings_fallback_once() -> None:
     )
 
 
+@functools.lru_cache(maxsize=1)
 def _resolve_reviews_settings() -> _ReviewsSettings:
-    """Return disabled and enabled tokens from disk, or env when disk is unreadable."""
+    """Return disabled and enabled tokens from disk, or env when disk is unreadable.
+
+    Cached for the process. Four reviewer gates ask for these tokens in one
+    run, and settings cannot change under a running check, so the disk read
+    and JSON parse happen once. A test that rebinds the settings path calls
+    ``_resolve_reviews_settings.cache_clear()`` first.
+    """
     all_disk_env_entries = _try_read_disk_env_block()
     if all_disk_env_entries is not None:
         return _ReviewsSettings(
@@ -147,18 +156,52 @@ def _is_copilot_disabled_via_resolved_settings() -> bool:
     )
 
 
+def _is_off_by_default_reviewer_disabled(reviewer_token: str) -> bool:
+    """Return True when the resolved settings leave an opt-in reviewer off.
+
+    ::
+
+        enabled names the token, disabled empty  -> False  (gate runs)
+        neither list names the token             -> True   (off by default)
+        both lists name the token                -> True   (opt-out wins)
+
+    Args:
+        reviewer_token: The lowercase reviewer token to look up in both lists.
+
+    Returns:
+        True when the reviewer stays off for this run.
+    """
+    reviews_settings = _resolve_reviews_settings()
+    is_opted_out = reviewer_token in reviews_settings.disabled_tokens
+    is_opted_in = reviewer_token in reviews_settings.enabled_tokens
+    return is_opted_out or not is_opted_in
+
+
 def _is_bugbot_disabled_via_resolved_settings() -> bool:
     """Return True when the resolved settings disable the bugbot reviewer.
 
     Bugbot is off by default. It is disabled when the disabled list names it, or
     when the enabled list does not name it.
     """
-    reviews_settings = _resolve_reviews_settings()
-    is_opted_out = (
-        CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN in reviews_settings.disabled_tokens
-    )
-    is_opted_in = CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN in reviews_settings.enabled_tokens
-    return is_opted_out or not is_opted_in
+    return _is_off_by_default_reviewer_disabled(CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN)
+
+
+def _is_bugteam_disabled_via_resolved_settings() -> bool:
+    """Return True when the resolved settings disable the bug-audit family.
+
+    Bugteam is off by default. It is disabled when the disabled list names it,
+    or when the enabled list does not name it.
+    """
+    return _is_off_by_default_reviewer_disabled(CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN)
+
+
+def _is_codex_disabled_via_resolved_settings() -> bool:
+    """Return True when the resolved settings disable the Codex reviewer.
+
+    Codex is off by default. It is disabled when the disabled list names it, or
+    when the enabled list does not name it.
+    """
+    return _is_off_by_default_reviewer_disabled(CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN)
 
 
 def _unavailable_note(reviewer_token: str, message: str) -> str:

package/skills/pr-converge/scripts/conftest.py

@@ -3,6 +3,41 @@
 import sys
 from pathlib import Path
 
+import pytest
+
 _scripts_directory = Path(__file__).resolve().parent
 if str(_scripts_directory) not in sys.path:
     sys.path.insert(0, str(_scripts_directory))
+
+import check_convergence_availability  # noqa: E402
+from pr_loop_shared_constants.reviews_disabled_constants import (  # noqa: E402
+    CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR,
+    CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME,
+)
+
+_MISSING_SETTINGS_PATH = Path("settings-absent-in-tests.json")
+
+
+@pytest.fixture(autouse=True)
+def opt_gated_reviewers_in(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Point settings at an absent file and opt bugteam and codex in.
+
+    Bugteam and codex are off by default, and the resolver reads the real
+    ``~/.claude/settings.json`` first. Both together would decide these cases
+    from whatever the host machine has on disk. Aiming the resolver at an
+    absent path restores the env fallback, and the opt-in lets each case reach
+    the gate it was written for. A case that tests the lists themselves
+    overrides this from its own body.
+    """
+    check_convergence_availability._resolve_reviews_settings.cache_clear()
+    monkeypatch.setattr(
+        check_convergence_availability,
+        "get_claude_user_settings_path",
+        lambda: _MISSING_SETTINGS_PATH,
+    )
+    all_opted_in_tokens = CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR.join(
+        (CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN, CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN)
+    )
+    monkeypatch.setenv(CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME, all_opted_in_tokens)

package/skills/pr-converge/scripts/test_check_convergence_availability.py

@@ -86,6 +86,7 @@ def _write_settings(
 def _reset_probe_cache_and_env(monkeypatch: pytest.MonkeyPatch) -> None:
     availability._probe_copilot_quota.cache_clear()
     availability._log_disk_settings_fallback_once.cache_clear()
+    availability._resolve_reviews_settings.cache_clear()
     monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
     monkeypatch.delenv("CLAUDE_REVIEWS_ENABLED", raising=False)
     monkeypatch.setattr(
@@ -324,3 +325,67 @@ def should_probe_copilot_when_neither_flag_env_nor_disk_disable_it(
     waiver = availability._resolve_copilot_waiver(False)
     assert waiver.is_waived is True
     assert waiver.bypass_note == "copilot unavailable: quota exhausted"
+
+
+def should_disable_bugteam_when_neither_disk_list_names_it(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    settings_path = _write_settings(
+        tmp_path, reviews_disabled_value="", reviews_enabled_value=""
+    )
+    monkeypatch.setattr(
+        availability, "get_claude_user_settings_path", lambda: settings_path
+    )
+    assert availability._is_bugteam_disabled_via_resolved_settings() is True
+
+
+def should_enable_bugteam_when_disk_enables_it_even_if_env_omits_opt_in(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_ENABLED", raising=False)
+    settings_path = _write_settings(
+        tmp_path, reviews_disabled_value="", reviews_enabled_value="bugteam"
+    )
+    monkeypatch.setattr(
+        availability, "get_claude_user_settings_path", lambda: settings_path
+    )
+    assert availability._is_bugteam_disabled_via_resolved_settings() is False
+
+
+def should_disable_bugteam_when_disk_disables_and_enables_it(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    settings_path = _write_settings(
+        tmp_path, reviews_disabled_value="bugteam", reviews_enabled_value="bugteam"
+    )
+    monkeypatch.setattr(
+        availability, "get_claude_user_settings_path", lambda: settings_path
+    )
+    assert availability._is_bugteam_disabled_via_resolved_settings() is True
+
+
+def should_disable_codex_when_neither_disk_list_names_it(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    settings_path = _write_settings(
+        tmp_path, reviews_disabled_value="", reviews_enabled_value=""
+    )
+    monkeypatch.setattr(
+        availability, "get_claude_user_settings_path", lambda: settings_path
+    )
+    assert availability._is_codex_disabled_via_resolved_settings() is True
+
+
+def should_enable_codex_when_disk_enables_it_even_if_env_omits_opt_in(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_ENABLED", raising=False)
+    settings_path = _write_settings(
+        tmp_path, reviews_disabled_value="", reviews_enabled_value="codex"
+    )
+    monkeypatch.setattr(
+        availability, "get_claude_user_settings_path", lambda: settings_path
+    )
+    assert availability._is_codex_disabled_via_resolved_settings() is False
+
+

package/skills/pr-converge/scripts/test_check_convergence_codex.py

@@ -370,7 +370,7 @@ def should_resolve_codex_down_true_when_env_disables_codex(
     ) is True
 
 
-def should_resolve_codex_down_false_when_flag_unset_and_env_empty(
+def should_resolve_codex_down_false_when_flag_unset_and_codex_opted_in(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
@@ -380,6 +380,16 @@ def should_resolve_codex_down_false_when_flag_unset_and_env_empty(
     ) is False
 
 
+def should_resolve_codex_down_true_when_neither_list_names_codex(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_ENABLED", raising=False)
+    monkeypatch.delenv("CLAUDE_JOB_DIR", raising=False)
+    assert check_convergence._resolve_codex_down(
+        False, check_convergence._read_job_state()
+    ) is True
+
+
 def should_resolve_codex_down_true_when_job_state_sticky_down(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,

package/skills/pr-converge/scripts/test_check_convergence_contract.py

@@ -294,14 +294,21 @@ def test_resolve_bugteam_post_blocked_true_when_env_disables_bugteam(
     assert check_convergence._resolve_bugteam_post_blocked(False) is True
 
 
-def test_resolve_bugteam_post_blocked_false_when_flag_unset_and_env_empty(
+def test_resolve_bugteam_post_blocked_false_when_flag_unset_and_bugteam_opted_in(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
     assert check_convergence._resolve_bugteam_post_blocked(False) is False
 
 
-def test_resolve_bugteam_post_blocked_false_when_env_disables_only_copilot(
+def test_resolve_bugteam_post_blocked_true_when_neither_list_names_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_ENABLED", raising=False)
+    assert check_convergence._resolve_bugteam_post_blocked(False) is True
+
+
+def test_resolve_bugteam_post_blocked_false_when_opted_in_and_env_disables_copilot(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot")

package/skills/pr-loop-cloud-transport/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr-loop-cloud-transport
-description: Runs any PR-loop skill in a Claude Code session whose gh CLI cannot act on the PR. Use at run start when pr-converge, autoconverge, bugteam, qbug, findbugs, fixbugs, monitor-open-prs, or copilot-review runs in a cloud session, when `command -v gh` or `gh auth status` fails, or when an MCP tool call fails with InputValidationError.
+description: Runs any PR-loop skill in a Claude Code session whose gh CLI cannot act on the PR. Use at run start when pr-converge, autoconverge, bugteam, clean-room audit, pr-fix-protocol, or copilot-review runs in a cloud session, when `command -v gh` or `gh auth status` fails, or when an MCP tool call fails with InputValidationError.
 ---
 
 # PR-loop cloud transport

package/skills/rebase/SKILL.md

@@ -93,7 +93,9 @@ When in doubt, ask. Both work; the choice affects history shape, not correctness
 
 ## Phase 3 — Verification gates (mandatory before push)
 
-`py_compile`, `tsc --noEmit`, `cargo check`, etc. validate **syntax and types**, not **import resolution and runtime correctness**. Run real checks:
+`py_compile`, `tsc --noEmit`, `cargo check`, etc. validate **syntax and types**, not **import resolution and runtime correctness**. Run real checks.
+
+Before each gate command, state in one line which gate it is and why it applies to this rebase ("post-rebase gate: `pkg_x` carried a conflict resolution, running its suite").
 
 8. **Real import check.** For Python:
 
@@ -105,7 +107,16 @@ When in doubt, ask. Both work; the choice affects history shape, not correctness
 
 9. **Test collection.** `pytest --collect-only -q` on the changed packages catches NameError, AttributeError, and ImportError surfaces beyond plain imports.
 
-10. **Targeted test run.** Run the test suite for every package the rebase touched. Do not push a rebase that dropped or broke test coverage that was passing pre-rebase.
+10. **Targeted test run — scoped by content diff.** First check, per candidate package, whether the rebase changed its content at all:
+
+    ```
+    git diff <pre-rebase-tip> HEAD -- <package>
+    ```
+
+    - **Empty diff:** the package's files are byte-for-byte what the branch already carried before the rebase, and that state was verified pre-rebase. The compile and collect-only gates (steps 8–9) cover the remaining import-level risk; skip the package's full suite.
+    - **Non-empty diff, a conflict resolution, or an auto-merged file (step 6) in the package:** run its full suite. Do not push a rebase that dropped or broke test coverage that was passing pre-rebase.
+
+    Capture the pre-rebase tip SHA before the rebase begins; step 15 pins the force-with-lease to that same SHA.
 
 11. **Reference scan for removals/renames.** For every symbol the rebase deleted or renamed (per the commit messages from step 4), scan the post-rebase tree using the same tool-preference order as step 4:
 
@@ -145,6 +156,7 @@ When in doubt, ask. Both work; the choice affects history shape, not correctness
 - **Auditing only `git diff --name-only`.** Files unchanged by the rebase can still break if their imports depended on what the rebase removed.
 - **Force-pushing under "the user asked me to fix the conflicts" interpretation.** Force-push is a separate authorization from "fix this." Ask.
 - **Bare `--force` instead of `--force-with-lease=<branch>:<sha>`.** Loses the safety net against concurrent pushes.
+- **Running full suites for packages the rebase left byte-for-byte the same.** The step-10 content diff settles it in seconds; a long suite on unchanged content stalls the session.
 
 ## Quick decision flowchart
 
@@ -157,7 +169,7 @@ Solo, ≤5 commits ahead?     ──► straight rebase
 After rebase, BEFORE push:
   python -c "import …"      ──► must succeed
   pytest --collect-only     ──► must succeed
-  targeted pytest run       ──► must pass
+  pytest, packages w/ diff  ──► must pass
   symbol scan (serena → Grep) ──► no stale references
 
 Push:

package/skills/reviewer-gates/SKILL.md

@@ -16,7 +16,7 @@ description: >-
 - **Skill-capable contexts** (a lead session with the `Skill` tool): `Skill({skill: "reviewer-gates", args: "--skill <caller> <gate> [gate parameters]"})`.
 - **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says "Read `~/.claude/skills/reviewer-gates/SKILL.md` and apply the `<gate>` section with the parameters below."
 
-Every invocation carries the caller's identity (`--skill <caller>`, e.g. `pr-converge`, `qbug`). The refusal line in Gate 1 and every logged decision names the caller, so a multi-skill session's transcript shows which loop each gate served.
+Every invocation carries the caller's identity (`--skill <caller>`, e.g. `pr-converge`, `bugteam`). The refusal line in Gate 1 and every logged decision names the caller, so a multi-skill session's transcript shows which loop each gate served.
 
 ## Gate 1: Reviewer opt-out (`CLAUDE_REVIEWS_DISABLED`)
 
@@ -24,7 +24,7 @@ The `CLAUDE_REVIEWS_DISABLED` environment variable is a comma-separated token li
 
 | Token | Disables |
 |---|---|
-| `bugteam` | The whole bug-audit family: `/bugteam`, `/qbug`, `/findbugs`, and audit dispatch in `/monitor-open-prs` |
+| `bugteam` | The whole bug-audit family: `/bugteam`, `clean-room audit (code-quality-agent)`, and audit dispatch in `/pr-converge` |
 | `bugbot` | Cursor Bugbot triggering and polling |
 | `copilot` | GitHub Copilot review requests and polling |
 | `codex` | Codex reviewer requests and polling |

package/skills/show/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: show
+description: Create and review inline visual explanations, diagrams, interactive widgets, mockups, charts, and illustrations. Triggers on "/show", "show me", "draw", "diagram this", "visualize", "map this out", "make it interactive", or a request for a mockup, chart, or illustration.
+---
+
+# Show
+
+Use this skill when a user asks to show, draw, map, visualize, explain visually, or build an interactive visual.
+
+## Routes
+
+Pick the row whose intent matches the request, then follow `workflows/create-visual.md`.
+
+| Intent | Route |
+|---|---|
+| Steps, decisions, lifecycle, transformation | `flowchart` |
+| Architecture, containment, hierarchy | `structural` |
+| Mechanism, intuition, spatial metaphor | `illustrative` |
+| Entity or class relationships | `erd` |
+| Controls that change a visual explanation | `interactive` |
+| UI surface, form, card, dashboard | `mockup` |
+| Quantitative or geographic data | `chart` |
+| Illustration or generative art | `art` |
+
+Each route's references and template live in `routing.yaml`; the template sets the output type.
+
+## Invariants
+
+- Design, palette, and color meaning follow `references/core-design.md`.
+- SVG output follows `references/svg-contract.md`; HTML output follows `references/host-and-html.md`.
+- Prefer multiple focused visuals over one dense canvas, and keep explanatory prose outside the visual.
+- Keep one diagram family per visual.
+- When the visual shows code, a diff, or a plan that lives in a repo, read the real lines and tie every arrow to a `path:line` citation before drawing. When the picture and the source disagree, the picture is wrong.
+- `samples/` holds good examples the user has picked out. Read them on demand to study what works; the rules stay in the references.
+
+## Workflows
+
+- New visual: `workflows/create-visual.md`
+- Review or repair: `workflows/review-visual.md`
+
+## Validation
+
+Run from any working directory:
+
+```text
+python <skill-root>/scripts/validate-package.py
+python <skill-root>/scripts/validate-artifact.py <artifact>
+```
+
+The package is complete only when package checks, artifact checks, and rendered inspection all pass.
+

package/skills/show/references/accessibility.md

@@ -0,0 +1,7 @@
+# Accessibility
+
+Interactive controls have accessible names and visible focus. Decorative icons use `aria-hidden="true"`.
+
+SVG roots use `role="img"`. Text remains readable in light and dark modes. Color never carries meaning without a label, shape, position, or legend.
+
+The hidden summary heading each HTML widget opens with is set in `references/host-and-html.md`; the `<title>` and `<desc>` order each SVG opens with is set in `references/svg-contract.md`.

package/skills/show/references/art.md

@@ -0,0 +1,3 @@
+# Art
+
+Use art for illustration and generative composition. Keep the requested subject and style clear. Provide accessible surrounding prose when the image itself cannot expose equivalent meaning.

package/skills/show/references/charts.md

@@ -0,0 +1,3 @@
+# Charts
+
+Choose a chart by the question the data answers. Label axes and units, preserve truthful scale, and provide a text summary for key findings. Use color for categories or emphasis rather than decoration.

package/skills/show/references/core-design.md

@@ -0,0 +1,14 @@
+# Core design
+
+Use flat surfaces, transparent outer containers, sentence case, the 16-at-680 scaled text floor set in `references/svg-contract.md`, and weights 400 or 500. Keep visible prose outside the visual. Use no decorative gradients, glow, blur, noise, or drop shadows. Use no emoji. Keep a visual compact and split it when labels or relationships become hard to read.
+
+## Color
+
+Color is the default, in the style of `samples/`: pick a palette of three to four named hues (for example a red, a green, an amber) plus neutral grays and near-black text, and use it throughout the visual.
+
+- Paint category and state surfaces with light tinted fills of the palette hues (for example `#DFF0E4` under a `#1E8449` stroke), with white or warm-white cards for plain content.
+- Draw strokes and text in strong fixed colors: near-black `#1A1A1A` for primary text, mid-gray for secondary, a palette hue for anything whose color carries meaning.
+- Use each hue for one meaning and keep that meaning consistent across the visual; a short legend explains any pairing the reader cannot work out alone.
+- The palette is fixed rather than host-derived, so every SVG owns its background rect — see `references/svg-contract.md`.
+- Keep contrast strong: text and strokes hold up against the fill behind them.
+- Reserve a monochrome outline style for the rare case the user asks for it.

package/skills/show/references/erds.md

@@ -0,0 +1,3 @@
+# Entity relationship diagrams
+
+Use an embeddable HTML or SVG ERD. Show entities, key fields, and cardinality. Keep relationship labels short and avoid crossing unrelated entities.

package/skills/show/references/flowcharts.md

@@ -0,0 +1,3 @@
+# Flowcharts
+
+Use one direction, top-to-bottom or left-to-right. Keep a diagram to four or five primary nodes. Use at least 20 units between peer boxes and route arrows around obstacles. Use a stepper for a multi-stage cycle with per-stage detail.

package/skills/show/references/host-and-html.md

@@ -0,0 +1,3 @@
+# HTML host contract
+
+Return an embeddable fragment without `doctype`, `html`, `head`, or `body`. Begin with the hidden summary heading. Use host CSS variables for surfaces and text. Do not use `position: fixed`, nested scrolling, comments, or unapproved remote resources.

package/skills/show/references/illustrative-diagrams.md

@@ -0,0 +1,10 @@
+# Illustrative diagrams
+
+Draw the mechanism or a useful spatial metaphor.
+
+- Draw each idea as a physical object: machine, pipe, valve, stamp, funnel, conveyor, lever, drawer. Reach for an object first, and for a word only when no object carries the idea.
+- Text inside the visual is evidence: exact identifiers, field names, and example values, verbatim, in monospace. Explanatory sentences stay in the surrounding prose.
+- Color carries meaning and holds the same meaning across every panel — for example red for a defect, green for correct flow, amber for the change. One story per panel, panels numbered, read in order.
+- Every route and arrow ends touching its target. Long paths carry motion cues such as chevrons or trails to show direction.
+
+Use one functional two-stop gradient only when it is a continuous physical property. Keep physical scene colors consistent and give a dark-mode treatment when needed.

package/skills/show/references/interaction.md

@@ -0,0 +1,3 @@
+# Interaction
+
+Use local JavaScript for filtering, sorting, toggling, and simple calculations. Use `sendPrompt(text)` when the next action needs model reasoning. Give every control an accessible name, keyboard behavior, and visible state.

package/skills/show/references/mockups.md

@@ -0,0 +1,3 @@
+# Mockups
+
+Use a bounded interface surface with clear hierarchy, realistic labels, and host variables. Keep controls visually consistent and make the primary action obvious.

package/skills/show/references/quality-gates.md

@@ -0,0 +1,7 @@
+# Quality gates
+
+Judgment checks a script cannot make. Run them by eye on the rendered result, after `scripts/validate-artifact.py` passes.
+
+- The artifact is self-contained and uses an approved external-resource origin when a resource is needed.
+- Rendered output has no clipping, unintended overlap, or unreadable contrast.
+- The visual reads at display scale, not just at full zoom.

package/skills/show/references/structural-diagrams.md

@@ -0,0 +1,3 @@
+# Structural diagrams
+
+Use a rounded outer container and two or three levels of containment at most. Keep external inputs and outputs outside the container. Give each region a short name and description.

package/skills/show/references/subject-inventory.md

@@ -0,0 +1,21 @@
+# Subject inventory
+
+List every element of the subject a reader expects to find, then mark each one kept or cut and say why in prose.
+
+For a diff or a pull request the list is fixed and needs no judgment:
+
+- Files touched
+- Identifiers added and removed
+- Behavior changed
+- Tests added
+- Docs changed
+- Commits
+
+Read those six from the repo itself:
+
+```bash
+git diff --stat <base>..<head>
+git log --oneline <base>..<head>
+```
+
+Every element then sits in a visual or gets named in the surrounding prose. An inventory too large for one canvas becomes an overview visual plus detail visuals.

package/skills/show/references/svg-contract.md

@@ -0,0 +1,22 @@
+# SVG contract
+
+Put `<title>`, `<desc>`, then `<defs>` first. Every connector has `fill="none"`; arrowheads use the standard marker. Avoid negative coordinates, clipping, crossing labels, and standalone labels outside a region or callout.
+
+## Canvas tiers
+
+Pick one of two widths:
+
+- **Standard** — `viewBox="0 0 680 H"`. Use it for a single small explainer.
+- **Large infographic** — `viewBox="0 0 W H"` with `W` from 1360 to 2000. This is the default for anything with two or more panels or more than about 6 labeled elements.
+
+## Text floor
+
+The smallest caption sits at `16 × (width / 680)` units, rounded to the nearest whole unit: 16 at 680, 32 at 1360, 41 at 1760. Body text sits above that floor.
+
+## Safe area
+
+The safe area scales with the canvas the same way: `40 × (width / 680)` units, so 40 at 680 and about 80 at 1360. Keep authored content inside it.
+
+## Background
+
+Every SVG draws its own opaque warm-white background rect (for example `#F2EFE6` or `#FFFFFF`) as the first shape after `<defs>`, covering the full viewBox. The visual carries a fixed palette (see `references/core-design.md`), so an owned background keeps it legible on light and dark hosts alike.

package/skills/show/routing.yaml

@@ -0,0 +1,30 @@
+workflow: workflows/create-visual.md
+shared_references:
+  - references/core-design.md
+  - references/accessibility.md
+  - references/quality-gates.md
+routes:
+  flowchart:
+    references: [references/svg-contract.md, references/subject-inventory.md, references/flowcharts.md]
+    template: templates/svg-base.svg
+  structural:
+    references: [references/svg-contract.md, references/subject-inventory.md, references/structural-diagrams.md]
+    template: templates/svg-base.svg
+  illustrative:
+    references: [references/svg-contract.md, references/subject-inventory.md, references/illustrative-diagrams.md]
+    template: templates/svg-base.svg
+  erd:
+    references: [references/host-and-html.md, references/subject-inventory.md, references/erds.md]
+    template: templates/html-widget.html
+  interactive:
+    references: [references/host-and-html.md, references/interaction.md]
+    template: templates/html-widget.html
+  mockup:
+    references: [references/host-and-html.md, references/mockups.md]
+    template: templates/html-widget.html
+  chart:
+    references: [references/host-and-html.md, references/charts.md]
+    template: templates/html-widget.html
+  art:
+    references: [references/art.md]
+    template: templates/html-widget.html