claude-dev-env 2.16.0 → 2.17.0

package/.agents/skills/review-tier/scripts/test_generation.py

@@ -0,0 +1,171 @@
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from review_tier import build_generation, inventory_generation, router_state_directory, router_state_root, router_state_root_id
+
+
+def test_generation_uses_live_git_surface(tmp_path: Path) -> None:
+    subprocess.run(["git", "init", "-q", "-b", "main"], cwd=tmp_path, check=True)
+    (tmp_path / "tracked.py").write_text("x = 1\n", encoding="utf-8")
+    subprocess.run(["git", "add", "tracked.py"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "-c", "user.name=Test", "-c", "user.email=test@example.com", "commit", "-qm", "init"], cwd=tmp_path, check=True)
+    (tmp_path / "untracked.py").write_text("y = 2\n", encoding="utf-8")
+    inventory = inventory_generation(tmp_path)
+    assert "untracked.py" in inventory["untracked"]
+    card = build_generation(tmp_path, card_path=tmp_path / "card.json")
+    assert card["inventory_hash"] == inventory["inventory_hash"]
+
+
+def test_router_state_root_id_is_stable_for_normalized_roots(tmp_path: Path) -> None:
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data-link").symlink_to(tmp_path / "data", target_is_directory=True)
+    state_root = router_state_root(tmp_path, {"CLAUDE_PLUGIN_DATA": str(tmp_path / "data" / ".." / "data")})
+    symlink_root = router_state_root(tmp_path, {"CLAUDE_PLUGIN_DATA": str(tmp_path / "data-link")})
+    assert state_root == symlink_root
+    assert router_state_root_id(state_root) == router_state_root_id(symlink_root)
+
+
+def test_router_state_directory_is_scoped_under_the_router_root(tmp_path: Path) -> None:
+    state_directory = router_state_directory(tmp_path)
+    custom_environment = {"CLAUDE_PLUGIN_DATA": str(tmp_path / "custom-data")}
+    custom_state_directory = router_state_directory(tmp_path, custom_environment)
+
+    assert state_directory.parent == router_state_root(tmp_path)
+    assert custom_state_directory == router_state_root(tmp_path, custom_environment) / state_directory.name
+    assert custom_state_directory != state_directory
+    assert len(state_directory.name) == 64
+
+
+def test_generation_records_committed_and_working_domains_once(tmp_path: Path) -> None:
+    repository = tmp_path / "repository"
+    repository.mkdir()
+    subprocess.run(["git", "init", "-q", "-b", "main"], cwd=repository, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=repository, check=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=repository, check=True)
+    tracked = repository / "packages" / "feature.py"
+    tracked.parent.mkdir()
+    tracked.write_text("one\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=repository, check=True)
+    subprocess.run(["git", "commit", "-qm", "initial"], cwd=repository, check=True)
+    initial_commit = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repository, check=True, capture_output=True, text=True).stdout.strip()
+    tracked.write_text("one\nbase\n", encoding="utf-8")
+    subprocess.run(["git", "add", str(tracked)], cwd=repository, check=True)
+    subprocess.run(["git", "commit", "-qm", "feature"], cwd=repository, check=True)
+    tracked.write_text("one\ntwo\n", encoding="utf-8")
+    subprocess.run(["git", "add", str(tracked)], cwd=repository, check=True)
+    tracked.write_text("one\ntwo\nthree\n", encoding="utf-8")
+    (repository / "new.py").write_text("new\n", encoding="utf-8")
+    inventory = inventory_generation(repository, initial_commit)
+    records = {record["path"]: record["domains"] for record in inventory["files_by_domain"]}
+    assert records["packages/feature.py"] == ["committed", "staged", "unstaged"]
+    assert records["new.py"] == ["untracked"]
+    assert inventory["base_ref"] and inventory["merge_base"] and inventory["HEAD"]
+
+
+@pytest.mark.parametrize("base_ref", ["missing", "HEAD~99"])
+def test_invalid_base_writes_no_card(tmp_path: Path, base_ref: str) -> None:
+    repository = tmp_path / "repository"
+    repository.mkdir()
+    subprocess.run(["git", "init", "-q", "-b", "main"], cwd=repository, check=True)
+    (repository / "seed.txt").write_text("seed\n", encoding="utf-8")
+    subprocess.run(["git", "add", "seed.txt"], cwd=repository, check=True)
+    subprocess.run(["git", "-c", "user.name=Test", "-c", "user.email=test@example.com", "commit", "-qm", "initial"], cwd=repository, check=True)
+    with pytest.raises(ValueError, match="INVALID_BASE_REF"):
+        build_generation(repository, base_ref=base_ref, card_path=tmp_path / "card.json")
+    assert not (tmp_path / "card.json").exists()
+
+
+def _git_repository(root: Path) -> None:
+    subprocess.run(["git", "init", "-q", "-b", "main"], cwd=root, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=root, check=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=root, check=True)
+    (root / "seed.txt").write_text("seed\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=root, check=True)
+    subprocess.run(["git", "commit", "-qm", "initial"], cwd=root, check=True)
+
+
+def test_diff_hash_changes_when_same_path_content_changes(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    tracked_path = tmp_path / "seed.txt"
+    first_hash = inventory_generation(tmp_path)["diff_hash"]
+    tracked_path.write_text("changed\n", encoding="utf-8")
+    assert inventory_generation(tmp_path)["diff_hash"] != first_hash
+
+
+def test_effective_lines_include_committed_staged_unstaged_and_untracked(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    committed_path = tmp_path / "committed.txt"
+    committed_path.write_text("one\ntwo\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-qm", "committed"], cwd=tmp_path, check=True)
+    staged_path = tmp_path / "staged.txt"
+    staged_path.write_text("one\ntwo\n", encoding="utf-8")
+    subprocess.run(["git", "add", str(staged_path)], cwd=tmp_path, check=True)
+    staged_path.write_text("one\ntwo\nthree\n", encoding="utf-8")
+    unstaged_path = tmp_path / "seed.txt"
+    unstaged_path.write_text("seed\nchanged\n", encoding="utf-8")
+    (tmp_path / "untracked.txt").write_text("one\ntwo\n", encoding="utf-8")
+    inventory = inventory_generation(tmp_path)
+    assert inventory["lines"] >= 6
+
+
+def test_inventory_preserves_rename_prior_path_and_operations(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    old_path = tmp_path / "old name.txt"
+    old_path.write_text("content\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-qm", "rename source"], cwd=tmp_path, check=True)
+    new_path = tmp_path / "new name.txt"
+    old_path.rename(new_path)
+    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True)
+    records = {record["path"]: record for record in inventory_generation(tmp_path)["files_by_domain"]}
+    assert records["new name.txt"]["prior_path"] == "old name.txt"
+    assert records["new name.txt"]["operation_by_domain"]["staged"] == "R"
+
+
+def test_inventory_preserves_delete_binary_space_unicode_and_symlink_identity(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    deleted = tmp_path / "deleted file.txt"
+    deleted.write_text("delete me\n", encoding="utf-8")
+    binary = tmp_path / "binary.bin"
+    binary.write_bytes(b"\0\xff")
+    unicode_path = tmp_path / "café.txt"
+    unicode_path.write_text("unicode\n", encoding="utf-8")
+    link = tmp_path / "link.txt"
+    link.symlink_to("seed.txt")
+    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-qm", "surface"], cwd=tmp_path, check=True)
+    surface_commit = subprocess.run(["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, capture_output=True, text=True).stdout.strip()
+    deleted.unlink()
+    binary.write_bytes(b"\0\x00changed")
+    unicode_path.write_text("unicode changed\n", encoding="utf-8")
+    link.unlink()
+    link.symlink_to("café.txt")
+    subprocess.run(["git", "add", "-u"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True)
+    records = {record["path"]: record for record in inventory_generation(tmp_path, surface_commit)["files_by_domain"]}
+    assert records["deleted file.txt"]["content_sha256"] != "0" * 64
+    assert records["binary.bin"]["binary"] is True
+    assert records["café.txt"]["path"] == "café.txt"
+    assert records["link.txt"]["content_sha256"]
+
+
+def test_package_count_uses_distinct_monorepo_package_keys(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    for path in ("packages/one/a.py", "packages/one/b.py", "apps/two/c.py", "root.py"):
+        target = tmp_path / path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text("x\n", encoding="utf-8")
+    assert inventory_generation(tmp_path)["packages"] == 3
+
+
+def test_explicit_and_default_base_provenance_fields_are_exact(tmp_path: Path) -> None:
+    _git_repository(tmp_path)
+    default_inventory = inventory_generation(tmp_path)
+    explicit_inventory = inventory_generation(tmp_path, "HEAD")
+    assert default_inventory["base_source"] == "configured_fallback"
+    assert explicit_inventory["base_source"] == "explicit"
+    for field in ("base_ref", "base_source", "base_sha", "merge_base_sha", "head_sha"):
+        assert default_inventory[field]

package/.agents/skills/review-tier/scripts/test_review_tier.py

@@ -0,0 +1,33 @@
+from review_tier import build_decision, calculate_tier, canonical_json_hash, effective_tier, load_policy, policy_hash
+
+
+def test_public_policy_functions_return_behavior() -> None:
+    tier_policy = load_policy()
+    assert policy_hash(tier_policy)
+    assert canonical_json_hash(tier_policy) == policy_hash(tier_policy)
+    decision = build_decision({}, "base", "head", ".", "digest", requested_override="T1")
+    assert decision["effective_tier"] == "T1"
+
+
+def test_tier_boundaries_and_hard_trigger() -> None:
+    assert calculate_tier({"files": 0, "lines": 0, "packages": 0, "risk": 0}) == "T1"
+    assert calculate_tier({"files": 2}) == "T2"
+    assert calculate_tier({"files": 5}) == "T2"
+    assert calculate_tier({"hard_triggers": ["security"]}) == "T3"
+
+
+def test_all_six_axes_accept_zero_one_two_boundaries() -> None:
+    axes = ("files", "lines", "packages", "risk", "public_api", "dependencies")
+    assert calculate_tier({axis: 0 for axis in axes}) == "T1"
+    assert calculate_tier({axis: 1 for axis in axes}) == "T3"
+    assert calculate_tier({axis: 2 for axis in axes}) == "T3"
+
+
+def test_score_boundaries_keep_small_changes_below_t3() -> None:
+    assert calculate_tier({"files": 1, "lines": 1}) == "T2"
+    assert calculate_tier({"files": 2, "packages": 1, "risk": 1}) == "T3"
+
+
+def test_upward_and_approved_downward_override() -> None:
+    assert effective_tier("T1", "T3") == "T3"
+    assert effective_tier("T3", "T1") == "T1"

package/.agents/skills/session-log/SKILL.md

@@ -25,7 +25,7 @@ Sessions come in many shapes — convergence loops, feature builds, research div
 - **The `Artifact` tool wraps the file in a document skeleton at publish time.** It adds `<!doctype html>…<head>…</head><body>` around whatever the file holds — write page content only (a `<title>`, a `<style>` block, and the body markup). Do not include `<!DOCTYPE>`, `<html>`, `<head>`, or `<body>` tags in the file itself.
 - **The `Artifact` tool redeploys to the same URL only within the current run.** Editing the session's HTML file in a later step of this same skill run and calling `Artifact` again does not mint a new URL — it updates the same published page in place. A fresh session has no memory of an artifact's URL from an earlier run, so republishing a session report written in a prior session always mints a new URL (there is no other way to target the old one without the user supplying it).
 - **Vault paths sit outside `.claude/`.** Headless vault paths (e.g., `$OBSIDIAN_VAULT_PATH`) resolve outside the project tree. Session reports use HTML regardless of vault location — the Artifact tool needs a written file to publish.
-- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html, but the rule at `~/.claude/rules/doc-prose-cuts.md` applies as a writing standard — skip historical and comparative language when composing the report; the rule file lists the full trigger set.
+- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html. Apply `~/.claude/rules/asd-ste100-language.md` for user-facing word choice and sentence style, and keep the session report current and self-contained.
 - **`write_existing_file_blocker` rejects Write on existing paths.** Use Write only when creating a fresh session report; use Edit for the vault-context append in step 3.
 - **Obsidian frontmatter index is HTML-blind.** Obsidian's native YAML-frontmatter parser reads only `.md` files. HTML files do not appear in Obsidian's frontmatter index. Search by content still works; search by `type: session-report` does not.
 

package/.agents/skills/shared-extraction-audit/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: shared-extraction-audit
+description: Audits pull requests and packages for general helpers living in workflow-specific code instead of shared_utils, then applies extraction fixes by default in small tested CLs. Use when reviewing PRs for architectural layering, migrating utilities out of cert_fix_queue/theme_dialer_pipeline/skills, auditing "similar offenses", or when the user mentions extraction audit, shared_utils migration, orchestration-only packages, thin wrappers, or layer inversions.
+---
+
+# Shared Extraction Audit
+
+Audit PRs and packages, report findings, and apply extraction fixes by default to keep **orchestration packages thin** and **shared_utils canonical**.
+
+## When to use
+
+- User points at a PR (e.g. `#1954`, `#1965`) and asks for the same review loop
+- A package grew `fix_one`, `_default_*`, backup upload, rembg session, or residual gates alongside orchestration
+- Before merge: confirm consumers are adapters, not second implementations
+
+## Target architecture
+
+| Layer | Holds | Examples |
+|-------|--------|----------|
+| **shared_utils** | Reusable actions, I/O, DB flips, inference, constants used by 2+ workflows | `status_promotion`, `background_removal`, `drive_production_backup`, `stp_filenames` |
+| **Workflow package** | Orchestration, CLI, sweep loops, workflow-specific constants only | `cert_fix_queue/pipeline/queue_run.py`, `theme_dialer_pipeline` compose runners |
+| **Skills / scripts** | Operator entrypoints that **delegate** to shared_utils | No parallel rembg/session stacks |
+
+**Load-bearing rule:** If another package would import it, put it in `shared_utils`. After the move, every former caller imports the shared symbol and the old module is deleted.
+
+## Audit workflow
+
+Copy to TodoWrite:
+
+```
+Shared extraction audit:
+- [ ] 1. Scope the PR (base branch, changed packages, stated goal)
+- [ ] 2. Map canonical homes already in shared_utils
+- [ ] 3. Grep for offense patterns (see reference/offense-taxonomy.md)
+- [ ] 4. Write prioritized findings (P0–P3)
+- [ ] 5. Apply the prioritized fix band by default; an explicit audit-only request ends after the report
+- [ ] 6. Extract in small CLs (~100 lines) + move/adjust tests
+- [ ] 7. Run scoped pytest, commit, push, update PR
+```
+
+### Step 1 — Scope
+
+```bash
+git fetch origin pull/<N>/head:pr-<N>   # or checkout feature branch
+git diff <base>...<head> --stat
+git diff <base>...<head> --name-only | rg 'shared_utils|cert_fix_queue|theme_dialer|clean_room|\.claude/skills'
+```
+
+Read the PR summary, then verify **what landed correctly** before listing offenses.
+
+### Step 2 — Search patterns
+
+Run these greps on the PR diff scope:
+
+```bash
+# Rename-only seams and re-export facades
+rg '_default_|def _.*_flipper|def _.*_one\b|promote_one|fix_one|backup_upload' <package> shared_utils
+rg '^from shared_utils\..* import \w+$' <package>
+
+# Layer inversions (shared importing consumer)
+rg 'from (cert_fix_queue|theme_dialer_pipeline|clean_room_theme_icons)\.' shared_utils/
+
+# Parallel stacks (second session/cache for same concern)
+rg 'new_session|lru_cache.*session|rembg\.remove' .claude/skills shared_utils
+
+# Duplicate constants
+rg 'ALPHA_CHANNEL_INDEX|RGBA_ALPHA|DEFAULT_.*_PREFIX|ONEUI_STP_BASENAME' --glob '*.py'
+
+# Duplicate test support
+rg 'fail_if_called|build_rejected_theme_row|preserve_supplied_alpha' --glob '**/tests/**'
+```
+
+### Step 3 — Classify offenses
+
+Use [reference/offense-taxonomy.md](reference/offense-taxonomy.md). Assign priority:
+
+| Priority | Meaning |
+|----------|---------|
+| **P0** | Layer inversion or duplicate production stack (must fix before merge) |
+| **P1** | General helper/constants/tests still in consumer package |
+| **P2** | Module shape, I/O overlap, monolith size |
+| **P3** | Stale names, docstrings, test attribute bugs |
+
+### Step 4 — Report template
+
+```markdown
+## PR #<N> extraction audit
+
+### Done well
+- [canonical modules and deletions]
+
+### P0 — …
+| Offense | Where | Target module | Tests |
+|---------|-------|---------------|-------|
+
+### Suggested fix order
+1. …
+```
+
+Apply the prioritized fixes after the report by default. An explicit audit-only request ends after the report.
+
+## Fix workflow
+
+### Extraction rules
+
+1. **Move behavior** — delete the consumer copy; every caller imports the shared symbol
+2. **Wire shared APIs at the call site** — e.g. `db_flipper=promote_theme_to_status` with `filename_prefix=...`
+3. **Retarget every caller, then delete the old module** — grep the old import path; remove re-export facades
+4. **Constants:** one source; workflow CLI keeps only workflow-specific names (`LEDGER_FILENAME`, exit codes)
+5. **Tests move with behavior** — shared module gets shared tests; orchestration keeps integration tests only
+6. **Small CLs** — one concern per commit (~100 lines); run scoped pytest after each
+
+### Canonical target map (this repo)
+
+| Need | Home |
+|------|------|
+| Theme DB status flip | `shared_utils/theme_db/status_promotion.py` |
+| Account folder ↔ ThemeAccount | `shared_utils/theme_persistence/account_adapter.py` |
+| STP basename parsing | `shared_utils/samsung_utils/stp_filenames.py` |
+| Drive backup upload | `shared_utils/files/drive_production_backup.py` |
+| Timestamp scratch dirs | `shared_utils/files/timestamp_directory_retention.py` |
+| Foreground extraction | `shared_utils/theme_assets/background_removal.py` |
+| Cert fix / promote actions | `shared_utils/theme_assets/cert_closeout/` |
+| Fixed-STP promotion sweep | `shared_utils/samsung_utils/promote_fixed_stp_sweep.py` |
+| Cert queue orchestration only | `cert_fix_queue/pipeline/` (`queue_run`) and `run_cli` |
+
+See also `.claude/rules/reuse-existing-tooling.md` before adding helpers.
+
+### Verification
+
+```bash
+# Package under change (from its directory or shared_utils)
+cd shared_utils && python -m pytest path/to/tests -n 0 -q
+cd cert_fix_queue && python -m pytest tests/ -n 0 -q
+
+# After moving tests: bump CI collect floor in .github/workflows/standalone-packages-tests.yml if applicable
+```
+
+Provide evidence: pytest output counts, not "should work".
+
+### Git / PR
+
+- Branch: `cursor/<topic>-593d` or existing PR branch
+- Commit message: `Extract <what> from <package> into shared_utils`
+- Update PR body: architecture table + test counts
+- Do not merge; draft PR unless user says otherwise
+
+## Anti-patterns (flag these)
+
+- `_default_*` adapter around a shared_utils function in a consumer module
+- Workflow module that only does `from shared_utils... import foo as foo`
+- `fix_one.py` / `promote_one.py` / `promote_run.py` / `backup_upload.py` in orchestration packages
+- `shared_utils` importing `theme_dialer_pipeline` or `cert_fix_queue`
+- Second rembg/BiRefNet session in a skill while `background_removal` exists
+- Identical `tests/support.py` in two packages
+- `config/constants.py` that only aliases extracted helpers
+
+## Examples
+
+See [reference/examples.md](reference/examples.md) for cert_fix_queue (#1965) and background_removal (#1954) audits.

package/.agents/skills/shared-extraction-audit/reference/examples.md

@@ -0,0 +1,46 @@
+# Audit examples (this repo)
+
+## cert_fix_queue — PR #1965
+
+**Goal:** `cert_fix_queue` holds orchestration only; general cert-fix utilities in `shared_utils`.
+
+**Done well:**
+- `locate_cert_folder_for_row`, `select_production_stp`, atomic copy, drive staged upload → shared_utils
+- Deleted `fix_one.py`, `promote_one.py`, `backup_upload.py` from pipeline
+
+**Offenses found and fixed:**
+- `_default_db_flipper` in `fix_theme.py` → wire `db_flipper=promote_theme_to_status` at the call site; delete the wrapper
+- `production_backup.py` under cert_closeout → `shared_utils/files/drive_production_backup.py`
+- Duplicate test `support.py` → `shared_utils/theme_assets/testing/cert_fix_test_support.py`
+- `fix_queue_constants.py` misnamed → `fix_outcomes.py`
+- `_account_by_fixed_stps_folder` → `cert_failure_folder_to_theme_account_map()` in `account_adapter`
+- `_fresh_run_directories` / scratch helpers → `allocate_timestamp_run_directory()`
+
+**Pipeline after:**
+```
+cert_fix_queue/pipeline/
+  queue_run.py
+  promote_run.py
+run_cli.py
+```
+
+---
+
+## background_removal — PR #1954
+
+**Goal:** One BiRefNet CPU path in `shared_utils/theme_assets/background_removal.py`.
+
+**Done well:**
+- Deleted `clean_room_theme_icons/chroma.py`, dialer `art_masks.py`, `png_io.py`
+- Added `pixel_masks.py`, `png_canonical.py`
+- Clean-room and dialer call `extract_foreground` / `extract_foreground_file`
+
+**Remaining offenses (audit):**
+- P0: Residual gates in `theme_dialer_pipeline/pipeline/chroma_extract.py` (shared algorithm output)
+- P0: `_extract_component_foreground` wrapper; same pattern inlined in `compose_from_masters.py`
+- P0: Parallel rembg in `misc-asset-remaster/scripts/generated_alpha_mask.py`
+- P1: Duplicate extraction test fixtures (dialer conftest vs clean-room conftest)
+- P1: `ALPHA_CHANNEL_INDEX` duplicated across dialer/clean-room/color_constants
+- P2: Atomic write helpers inside 723-line `background_removal.py`; PNG path vs `png_canonical`
+
+**Suggested fix order:** residual gates → shared test fixtures → dedupe constants → migrate misc rembg → I/O split (optional).

package/.agents/skills/shared-extraction-audit/reference/offense-taxonomy.md

@@ -0,0 +1,100 @@
+# Offense taxonomy
+
+## O1 — General action in workflow package
+
+**Signal:** Per-item function named `*_one`, `fix_*`, `promote_*`, `upload_*` in orchestration tree.
+
+**Example:** `cert_fix_queue/pipeline/fix_one.py` → `shared_utils/.../fix_theme.py` (`fix_cert_rejected_theme`).
+
+**Fix:** Move module; consumer passes workflow-specific `filename_prefix` / folder ids at call site.
+
+---
+
+## O2 — Thin wrapper / default seam / re-export facade
+
+**Signal:** `_default_db_flipper`, `_default_*` that only renames kwargs and calls shared_utils. Also: a workflow module that only re-exports a shared symbol under the old path.
+
+**Example:** Wrapper around `promote_theme_to_status` with `db_flip_log_filename_prefix`. After a move, `clean_room_theme_icons.rebuild_nine_patch` still contains `from shared_utils... import rebuild_nine_patch`.
+
+**Fix:** Update every caller to the shared symbol (`filename_prefix`, `shared_utils.theme_assets.nine_patch_rebuild`, etc.) and delete the wrapper or facade.
+
+---
+
+## O3 — Layer inversion
+
+**Signal:** `shared_utils/...` imports from `cert_fix_queue`, `theme_dialer_pipeline`, `clean_room_theme_icons`, or `.claude/skills/...`.
+
+**Fix:** Move imported symbol into shared_utils; consumer imports shared.
+
+---
+
+## O4 — Parallel production stack
+
+**Signal:** Second implementation of same concern (rembg session, despill, STP walk, DB flip) in skill or sibling package.
+
+**Example:** `misc-asset-remaster/.../generated_alpha_mask.py` vs `background_removal.py`.
+
+**Fix:** Delegate to canonical module; delete duplicate constants and session cache.
+
+---
+
+## O5 — Validation/gates on shared output in consumer
+
+**Signal:** Functions that only inspect output of shared algorithm (residual alpha, edge green excess) live in dialer/clean-room.
+
+**Example:** `theme_dialer_pipeline/pipeline/chroma_extract.py` using `edge_green_excess_mask` from shared.
+
+**Fix:** `shared_utils/theme_assets/background_removal/residual_gates.py` (or sibling); optional `extract_foreground_gated`.
+
+---
+
+## O6 — Duplicate constants
+
+**Signal:** Same literal or semantic constant in workflow `config/constants.py` and shared config.
+
+**Examples:** `ALPHA_CHANNEL_INDEX`, `ONEUI_STP_BASENAME_RE`, two `DEFAULT_*_DB_FLIP_*` with same value.
+
+**Fix:** Single definition in shared config; delete consumer copies.
+
+---
+
+## O7 — Misplaced config module
+
+**Signal:** Constants named for workflow A live under package B's config (e.g. `fix_queue_constants` under `cert_closeout`).
+
+**Fix:** Rename/move to owning workflow or shared outcomes module; drop re-export-only facades.
+
+---
+
+## O8 — Duplicate test support
+
+**Signal:** Identical or near-identical `tests/support.py`, conftest bypass fixtures, synthetic PNG writers in multiple packages.
+
+**Fix:** `shared_utils/theme_assets/testing/` or `shared_utils/.../tests/fixtures.py`; one import path.
+
+---
+
+## O9 — General I/O in domain module
+
+**Signal:** Atomic staged writes, Drive upload, UTC helpers duplicated inside a 700-line domain file.
+
+**Fix:** `shared_utils/files/` (e.g. `drive_production_backup`, `timestamp_directory_retention`, `record_persist`).
+
+---
+
+## O10 — Stale identifiers
+
+**Signal:** Docstrings/tests still say `fix_one`, `promote_one`, `backup_upload` after rename.
+
+**Fix:** Update docs; no behavior change.
+
+---
+
+## Priority guide
+
+| Offense | Typical priority |
+|---------|------------------|
+| O3, O4 | P0 |
+| O1, O2, O5, O6, O7, O8 | P1 |
+| O9, monolith size | P2 |
+| O10 | P3 |

package/.agents/skills/source-command-logifix/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "source-command-logifix"
+description: "Restore the Logitech Gaming Software (LCore) tray icon when it disappears on Windows"
+---
+
+# source-command-logifix
+
+Use this skill when the user asks to run the migrated source command `logifix`.
+
+## Command Template
+
+Run the logifix recovery script to restore the LCore tray icon. The procedure is verified in `sessions/System Support/2. Logitech Tray Icon Fix Recurrence.md` (2026-04-25).
+
+Execute the script via PowerShell 7+:
+
+```
+pwsh -NoProfile -File "$HOME\.Codex\skills\logifix\scripts\logifix.ps1"
+```
+
+The script will prompt for UAC once. Approve it. After it finishes, ask the user to confirm the tray icon is now visible.
+
+If the script reports that UAC was canceled, or LCore did not respond after both relaunch attempts, instruct the user:
+
+1. Press **Ctrl+Shift+Esc** to open Task Manager.
+2. Find **Windows Explorer** in the process list.
+3. Right-click → **Restart**.
+4. Re-run `/logifix`.
+
+The Task Manager Explorer restart is the guaranteed-correct fallback because it always hits the user's interactive session and the right elevation context, regardless of how the calling shell was launched.

package/.agents/skills/source-command-sr-loop/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: "source-command-sr-loop"
+description: "Converging cleanup loop: repeat /simplify until clean, then repeat /code-review --fix until clean"
+---
+
+# source-command-sr-loop
+
+Use this skill when the user asks to run the migrated source command `sr-loop`.
+
+## Command Template
+
+Run the converging cleanup loop on the target the user names (a PR URL,
+a branch, or blank for the current branch's diff). Each phase invokes an
+existing skill and repeats it until a pass returns zero new findings.
+
+### Phase A — loop simplify
+
+1. Invoke the `simplify` skill (or its local equivalent, e.g. `e-simplify`)
+   on the target. Let it run its 4-lens review fan-out (reuse,
+   simplification, efficiency, altitude) and apply its fixes.
+2. After each pass: run the scoped test suite (test files beside the touched
+   code, not the full repo suite), commit once (commit body via
+   `git commit -F <file>`, 10-minute timeout — the pre-commit gate runs its
+   own tests), and push to the PR head branch. The PR stays draft.
+3. Repeat the invocation. Skips are sticky: carry every adjudicated skip
+   forward into the next pass as "already adjudicated — do not re-report: ..."
+   context, or the loop never converges.
+4. Phase A converges when a full pass returns zero new findings. When the
+   previous pass changed only a line or two, a single combined-lens
+   confirmation agent may serve as the final pass.
+
+### Phase B — loop code-review with fixes
+
+1. Run the real code-review command through a headless subprocess in the
+   target worktree: `claude -p "/code-review low --fix" --max-turns 40` with a
+   10-minute timeout, reading its final text for findings and applied fixes.
+   (The skill's `disable-model-invocation` flag blocks only programmatic tool
+   starts; a `-p` prompt arrives as user input and loads normally.) Fallback
+   when the headless run fails: invoke the `e-code-review` skill with
+   `low --fix` — same review-and-fix contract, no invocation restriction.
+2. After any pass that changed files: test, commit, push as in Phase A.
+3. Repeat until a pass reports zero findings. Phase B usually converges in
+   one pass when Phase A ran first.
+
+### Finish
+
+Report: passes run per phase, commits pushed with hashes, fixes applied, and
+the standing skip list with reasons.
+
+### Constraints (observed under headless runs)
+
+- Run this loop in the main conversation. A wrapper subagent cannot see the
+  review skills, and a nested agent's own subagent reports route to the main
+  conversation instead of back to it.
+- Scope test runs to the touched files; a full-suite run can outlive one
+  foreground tool call.
+- A hung or newly slow test suite is a finding to investigate, not an
+  inconvenience.

package/.agents/skills-archived/AGENTS.md

@@ -0,0 +1,45 @@
+# skills-archived
+
+Versioned archive of retired Claude Code skills. These trees stay in the repository for reference and history but are not shipped to users.
+
+## Layout
+
+Each subdirectory is one retired skill with its historical `SKILL.md`, reference docs, scripts, and tests. Live runtime helpers for convergence and Codex review live under `packages/claude-dev-env/_shared/pr-loop/scripts/` — not in these trees.
+
+## Installer behavior
+
+`bin/install.mjs` copies skills only from `.agents/skills/`. This directory is outside that path and outside the `.claude/skills` lookup pointer, so archived skills never install to `~/.agents/skills/`.
+
+`bin/ever-shipped-skills.mjs` still lists retired skill names so a full install prunes stale copies from prior releases.
+
+## Archived skills
+
+| Skill | Role |
+|---|---|
+| `anthropic-plan` | Source-grounded plan packet workflow |
+| `auditing-claude-config` | Claude Code startup instruction audit |
+| `beat-sheet` | Single-line beat formatting |
+| `bugteam` | Open PR audit-fix loop |
+| `closeout` | Session obstacle harvest to GitHub issues |
+| `codex-review` | Local Codex PR reviewer (runtime scripts in `_shared`) |
+| `comments` | PR review comment guide |
+| `condensing-instructions` | Instruction slimming for Claude 5 |
+| `copilot-finding-triage` | Copilot gate finding tiering |
+| `copilot-review` | Copilot reviewer babysitter |
+| `descriptions` | PR description guide |
+| `emergencies` | Emergency change guide |
+| `grokify` | Grok Build handoff prompt |
+| `plan-to-pr` | Plan packet to PR workflow |
+| `pr-converge` | Paced PR convergence loop (runtime scripts in `_shared`) |
+| `pr-fix-protocol` | Reviewer finding fix protocol |
+| `pr-loop-cloud-transport` | Cloud session gh-to-MCP transport |
+| `pr-loop-lifecycle` | PR-loop open and close |
+| `recall` | Obsidian vault recall |
+| `release-notes-html` | Session release-notes HTML page |
+| `remember` | Obsidian vault remember |
+| `reviewer-gates` | External reviewer availability gates |
+| `reviews` | Code review guide |
+| `show` | Inline visual explanations |
+| `split-pr` | PR split analyzer |
+
+Prompt-generator dependency skills (`agent-prompt`, `pmin`, `pmax`, `pmid`, `prompt-generator`) shipped via the `@jl-cmd/prompt-generator` npm package and never had source trees in this repository.