claude-dev-env 2.16.0 → 2.17.0

package/.agents/skills/cert-classification-rule/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: cert-classification-rule
+description: Add or change a Samsung cert-failure classification rule (fixable, unfixable, mixed). Use when the user says add a fixable item, add an unfixable item, mark this rejection unfixable, add a mixed item, classify this cert rejection, or add a cert rule. Covers the unfixable pattern config, the paired production-path test, and the re-sort recipe for already-filed folders.
+---
+
+# Cert-Failure Classification Rule
+
+Add or change how a Samsung Galaxy Store certification rejection is sorted into one of four
+buckets: `Fold`, `unfixable`, `mixed`, or `fixable`. A rejection lands in a bucket from its
+must-fix issue titles plus a Fold device check, and the bucket decides which subfolder holds
+the theme folder.
+
+## Contents
+
+- [When to use](#when-to-use)
+- [Procedure checklist](#procedure-checklist)
+- [The classification model](#the-classification-model)
+- [How to add an unfixable title pattern](#how-to-add-an-unfixable-title-pattern)
+- [How to add the paired production-path test](#how-to-add-the-paired-production-path-test)
+- [Re-sort already-filed folders for a day](#re-sort-already-filed-folders-for-a-day)
+- [Gotchas](#gotchas)
+- [File index](#file-index)
+- [Folder map](#folder-map)
+
+## When to use
+
+Use this skill when the user asks to:
+
+- add a fixable item, add an unfixable item, or add a mixed item
+- mark a rejection unfixable, or classify a cert rejection
+- add a cert rule
+
+Almost every such request is one new unfixable title pattern plus its paired test. The
+`fixable` and `mixed` buckets are not configured by hand (see the model below), so a request
+to "add a fixable item" usually means "stop treating this title as unfixable" or "confirm
+this title stays fixable with a guard test".
+
+### When a title pattern cannot help
+
+If the rejection's only unfixable cue lives in the report description (the `L_TESTRESULT`
+text, for example `*Not Identifiable`) and no must-fix title carries it, stop and tell the
+user this exact point:
+
+> This rejection's only unfixable signal is in the report description, not a must-fix title.
+> The classifier reads titles only, so no pattern here will catch it — teaching it to read
+> the description is a code change to the classifier, not a config rule.
+
+## Procedure checklist
+
+Copy this and check each item off as you go:
+
+- [ ] Confirm the unfixable cue is in a must-fix **title**, not only the description (see Gotchas).
+- [ ] Append the new `{pattern, label, review_note}` after the Gallery entry in `unfixable_patterns.json`.
+- [ ] Add a paired production-path test: the live title classifies as `unfixable`, plus a negative guard for an out-of-scope title.
+- [ ] Run the tests from the `shared_utils` directory and confirm green.
+- [ ] Re-sort the affected day folders with the re-sort recipe (dry run first, then `--apply`).
+
+## The classification model
+
+`classify_failure(issue_titles, unfixable_patterns)` in
+`shared_utils/samsung_utils/cert_failure_classifier.py:71` decides the bucket from the
+must-fix issue titles:
+
+- **unfixable** — every title matches an unfixable pattern.
+- **mixed** — some titles match, some do not. This bucket is **derived**, never configured.
+  The classifier returns it once at least one title matches an unfixable pattern and at least
+  one does not.
+- **fixable** — no title matches any unfixable pattern. This is the **default**: a rejection
+  needs no pattern to be fixable.
+- **None** — there are no must-fix titles at all.
+
+Only the `unfixable_patterns` list is authored. Adding an unfixable pattern is the only way to
+move a title out of the default `fixable` bucket.
+
+**Visibility auto-fix (Stage 1) also gates on these patterns.**
+`classify_visibility_failure_title` in `visibility_failure_classifier.py` calls
+`get_matched_unfixable_patterns` / `load_unfixable_patterns` so a title that maps to a
+curated colour slot still sets `is_blocked_from_auto_fix=True` (and
+`can_auto_fix(record)` is False) when it matches Gallery, Clock system-UI, lock-screen
+video wallpaper crop, Quick-panel preview mismatch, or any other unfixable pattern.
+Changing a pattern here therefore changes both folder sorting and visibility auto-fix
+eligibility.
+
+**Lock-screen video wallpaper crop stays UNFIXABLE.** Pad-to-canvas (`lock_wallpaper_cover`,
+#1449) and tall-aspect image-gen outpaint (`lock_aspect_regen`, #1454) were tried and
+abandoned; Themes Studio automation for this class was cancelled. Do not reopen a crop,
+outpaint, pad, or Primary/color autofix for Blue Edge-style "cut on both side(s)" titles.
+
+The categorizer (`FailureCategorizer.categorize_and_move` in
+`shared_utils/samsung_utils/cert_failure_processor/failure_categorizer.py:65`) runs the Fold
+device check and the classifier, then resolves a single bucket in
+`_resolve_category_priority` (`failure_categorizer.py:105`):
+
+- An `unfixable` or `mixed` classification overrides the detector — these are the
+  `severity_priority_buckets` in
+  `shared_utils/samsung_utils/config/cert_failure.py:76` (`("unfixable", "mixed")`).
+- A `Fold` detector category is kept only when the classification is `fixable`.
+- A `fixable` classification applies only when no detector matched.
+
+`FoldDetector` (`failure_categorizer.py:37`) matches the device regex `SM-F[79]\d{2}[A-Z]?` or
+the keyword `fold` (config in `cert_failure.py:52`).
+
+## How to add an unfixable title pattern
+
+Patterns live in `shared_utils/samsung_utils/config/unfixable_patterns.json` as a JSON list
+under the `unfixable_patterns` key. Each entry is `{pattern, label, review_note}`.
+
+**The Gallery entry stays first (index 0).** The tests in
+`test_cert_failure_classifier.py::TestDefaultConfigPath` assert `result[0]` is the Gallery
+pattern. Append every new pattern after it; never insert ahead of it.
+
+Live pattern shape, anchored on the rejected surface (Gallery is the shipped example):
+
+```json
+{
+  "pattern": "(?i)<surface>.*poor visibility|poor visibility.*<surface>",
+  "label": "<Surface> visibility",
+  "review_note": "<honest note about the issue>"
+}
+```
+
+`(?i)` is case-insensitive. The two-sided alternation matches the surface either before or
+after the "poor visibility" phrase, because Samsung phrases the same title both ways. Replace
+`<surface>` with the lowercase app or screen name (`settings`, `clock`, `calculator`). Match
+against the **title** text the report shows, not the description.
+
+### Writing the review_note honestly
+
+`review_note` is the message the per-pattern explanation would carry in a review reply.
+`DEFAULT_THEME_REVIEW_NOTES` still calls `compose_review_notes` with an empty matched-pattern
+list. Devices-only, Quick-panel, and sound-preview labels in `cert_portal_notes_update_config.all_labels`
+are the exception: `resubmit_via_notes_only_update` APPENDs those `review_note` sentences on
+the existing ThemeUpdateProcessor path (search → Re-register → Certification Notes). Write a
+truthful note, because it becomes the pasted sentence for those classes.
+
+Do **not** fabricate a "Samsung confirmed" claim. State only what is true. The shipped Gallery
+note is true because Samsung Support did confirm that issue; a new pattern for a different
+issue must not borrow that wording unless the confirmation actually happened.
+
+## How to add the paired production-path test
+
+Every new unfixable pattern gets a paired test in
+`shared_utils/samsung_utils/tests/test_cert_failure_classifier.py` that drives the production
+path:
+
+1. Load the real patterns with `load_unfixable_patterns()` (no path argument, so it reads the
+   shipped config).
+2. Build the report HTML with the live must-fix title text, run it through
+   `extract_issue_titles`, then `classify_failure`, and assert the result is `unfixable`.
+3. Add a negative guard: an out-of-scope "poor visibility" title (a surface with no pattern)
+   classifies as `fixable`, so a future broad regex cannot silently swallow unrelated
+   rejections.
+
+Use the exact title strings Samsung's report produces. The existing
+`TestClassifyFailure::test_gallery_regex_matches_all_known_variants` shows the shape: a list of
+real title variants, each asserted as `unfixable` through `classify_failure`.
+
+Run the tests from the `shared_utils` directory (its pytest config is anchored there):
+
+```bash
+cd shared_utils && C:\Python313\python.exe -m pytest samsung_utils/tests/test_cert_failure_classifier.py -q
+```
+
+## Re-sort already-filed folders for a day
+
+After adding a pattern, theme folders filed for an earlier day still sit in their old bucket.
+Run `scripts/resort_cert_folders.py` to recompute each theme's bucket with the new patterns and
+move any folder whose current bucket differs from the computed one. The script reuses the
+production `FailureCategorizer` decision helpers (`_parse_rejection_text`, `_detect_category`,
+`_classify_from_html`, `_resolve_category_priority`), so it stays in step with the live
+categorizer. It runs dry by default and moves only on `--apply`.
+
+Set `PYTHONPATH` to the repo root so the import resolves the edited `shared_utils` tree rather
+than a pip-editable install:
+
+```bash
+set PYTHONPATH=Y:\Information Technology\Scripts\Automation\Python
+C:\Python313\python.exe .claude\skills\cert-classification-rule\scripts\resort_cert_folders.py "<cert base path>" June 18 PRIMARY
+C:\Python313\python.exe .claude\skills\cert-classification-rule\scripts\resort_cert_folders.py "<cert base path>" June 18 PRIMARY --apply
+```
+
+Cert-failure folders live at `<base>\<Month>\<day>\<account_folder>\<bucket>\<theme>`, where
+`<account_folder>` is `Themes` for PRIMARY and `Theme Editor Themes` for SECONDARY
+(`AccountFolderConfig` in `shared_utils/web_automation/config/account.py:91`).
+
+`scripts/resort_cert_folders.py` passes the repo `code_rules_enforcer` Write hook: output goes
+through a `logger` with %-style format strings (no bare `print()`), the base path is an
+argument, every named value is a typed `dataclass` field rather than a module-level
+`UPPER_SNAKE` constant, and loop variables carry the `each_` prefix.
+
+## Gotchas
+
+- **Only titles are matched, never the description.** The classifier reads the must-fix issue
+  **titles** via the `L_TITLE` regex in `extract_issue_titles`
+  (`cert_failure_classifier.py:40`). The rejection description text — the `L_TESTRESULT` span,
+  for example a `*Not Identifiable` note — is **not** read by the classifier. A signal that
+  lives only in the description will not flag a title unless that title also matches a pattern.
+  When a rejection's only "unfixable" cue is in the description, no title pattern can catch it.
+- **Do not reopen crop autofix.** Lock-screen video wallpaper "cut on both side(s)" is
+  UNFIXABLE. Closed #1449 (pad-to-canvas) and #1454 (tall outpaint) must stay closed.
+- **The Gallery entry stays at index 0** of `unfixable_patterns.json`. Tests assert
+  `result[0]` is Gallery; append new patterns after it.
+- **"-" placeholders are excluded.** Recommended-table rows show a `-` title; `extract_issue_titles`
+  drops them, so they never count toward a classification.
+- **Run tests from the `shared_utils` directory.** Its pytest config (`testpaths`,
+  `asyncio_mode`) is anchored there. A run from the repo root will not collect the tests
+  correctly.
+- **Use `C:\Python313\python.exe`.** The repo-root `.venv` is a Linux/NAS virtual environment
+  with no `Scripts\python.exe` on Windows.
+- **Set `PYTHONPATH` to the repo root for the re-sort.** Without it, the import can resolve a
+  pip-editable install of `shared_utils` whose config lacks the freshly added pattern, so the
+  new pattern does not take effect.
+
+## File index
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | This hub — the classification model, the add-a-rule procedure, the test recipe, and gotchas. |
+| `scripts/resort_cert_folders.py` | Re-sorts already-filed cert-failure folders for a day after a pattern change. Execute it (see the re-sort section); set `PYTHONPATH` to the repo root first. Dry-run by default, moves on `--apply`. |
+
+## Folder map
+
+- `SKILL.md` — hub.
+- `scripts/` — the re-sort utility, executed rather than read into context.

package/.agents/skills/cert-classification-rule/scripts/resort_cert_folders.py

@@ -0,0 +1,158 @@
+"""Re-sort already-filed cert-failure theme folders after the unfixable patterns change.
+
+Recomputes each theme's bucket from its HTML report using the production
+FailureCategorizer decision helpers, then moves folders whose current bucket no
+longer matches. Dry-run by default; pass --apply to move folders.
+"""
+
+import argparse
+import logging
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from shared_utils.samsung_utils.cert_failure_processor.failure_categorizer import (
+    FailureCategorizer,
+)
+from shared_utils.web_automation.config.account import (
+    AccountType,
+    account_folder_config,
+)
+
+logger = logging.getLogger("resort_cert_folders")
+
+
+@dataclass(frozen=True)
+class ResortConfig:
+    """Naming and discovery constants for the re-sort pass."""
+
+    report_glob: str = "*_Report.html"
+    log_format: str = "%(message)s"
+
+
+@dataclass(frozen=True)
+class FolderMove:
+    """A single planned move from a theme's current bucket to its computed bucket."""
+
+    theme_folder: Path
+    current_bucket: str
+    computed_bucket: str
+
+
+def compute_bucket(categorizer: FailureCategorizer, theme_folder: Path, resort_config: ResortConfig) -> str | None:
+    """Compute the bucket a theme folder belongs in from its HTML report.
+
+    Args:
+        categorizer: The production categorizer holding the loaded unfixable patterns.
+        theme_folder: The theme folder containing the cert-failure HTML report.
+        resort_config: Discovery and logging constants for this pass.
+
+    Returns:
+        The computed bucket name, or None when no report is present or no bucket applies.
+    """
+    all_reports = list(theme_folder.glob(resort_config.report_glob))
+    if not all_reports:
+        logger.warning("No report for '%s' - skipping", theme_folder.name)
+        return None
+    html_content = all_reports[0].read_text(encoding="utf-8", errors="ignore")
+    rejection_text = categorizer._parse_rejection_text(html_content)
+    detector_category = categorizer._detect_category(html_content, rejection_text)
+    classification = categorizer._classify_from_html(html_content)
+    return categorizer._resolve_category_priority(detector_category, classification)
+
+
+def plan_moves(account_root: Path, categorizer: FailureCategorizer, resort_config: ResortConfig) -> list[FolderMove]:
+    """Plan every move needed to bring a day's account folder into line with the patterns.
+
+    Args:
+        account_root: The <base>/<Month>/<day>/<account_folder> directory to scan.
+        categorizer: The production categorizer holding the loaded unfixable patterns.
+        resort_config: Discovery and logging constants for this pass.
+
+    Returns:
+        One FolderMove per theme whose current bucket differs from its computed bucket.
+    """
+    planned_moves: list[FolderMove] = []
+    for each_bucket_dir in sorted(path for path in account_root.iterdir() if path.is_dir()):
+        current_bucket = each_bucket_dir.name
+        for each_theme in sorted(path for path in each_bucket_dir.iterdir() if path.is_dir()):
+            computed_bucket = compute_bucket(categorizer, each_theme, resort_config)
+            if computed_bucket is not None and computed_bucket != current_bucket:
+                planned_moves.append(
+                    FolderMove(
+                        theme_folder=each_theme,
+                        current_bucket=current_bucket,
+                        computed_bucket=computed_bucket,
+                    )
+                )
+    return planned_moves
+
+
+def apply_move(account_root: Path, folder_move: FolderMove) -> None:
+    """Move one theme folder into its computed bucket directory.
+
+    Args:
+        account_root: The <base>/<Month>/<day>/<account_folder> directory.
+        folder_move: The planned move to carry out.
+    """
+    target_dir = account_root / folder_move.computed_bucket
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target_path = target_dir / folder_move.theme_folder.name
+    if target_path.exists():
+        logger.warning("Target exists for '%s' - skipping", folder_move.theme_folder.name)
+        return
+    shutil.move(str(folder_move.theme_folder), str(target_path))
+
+
+def run_resort(base_path: str, month: str, day: str, account_label: str, should_apply: bool) -> None:
+    """Plan and optionally apply a re-sort of one day's cert-failure folders.
+
+    Args:
+        base_path: The cert-failure base directory.
+        month: The month folder name (for example "June").
+        day: The day folder name (for example "18").
+        account_label: "PRIMARY" or "SECONDARY".
+        should_apply: When True, move folders; when False, only log the plan.
+    """
+    resort_config = ResortConfig()
+    logging.basicConfig(level=logging.INFO, format=resort_config.log_format)
+    account_type = AccountType[account_label]
+    account_folder = account_folder_config.get_folder_name(account_type)
+    account_root = Path(base_path) / month / day / account_folder
+    categorizer = FailureCategorizer(base_path)
+    planned_moves = plan_moves(account_root, categorizer, resort_config)
+    if not planned_moves:
+        logger.info("Nothing to re-sort in %s", account_root)
+        return
+    for each_move in planned_moves:
+        logger.info(
+            "%s: %s -> %s",
+            each_move.theme_folder.name,
+            each_move.current_bucket,
+            each_move.computed_bucket,
+        )
+        if should_apply:
+            apply_move(account_root, each_move)
+    logger.info("%d folder(s) %s", len(planned_moves), "moved" if should_apply else "planned (dry run)")
+
+
+def main() -> None:
+    """Parse arguments and run the re-sort pass."""
+    parser = argparse.ArgumentParser(description="Re-sort cert-failure folders after a pattern change.")
+    parser.add_argument("base_path", help="Cert-failure base directory.")
+    parser.add_argument("month", help='Month folder name, for example "June".')
+    parser.add_argument("day", help='Day folder name, for example "18".')
+    parser.add_argument("account", choices=["PRIMARY", "SECONDARY"], help="Account type.")
+    parser.add_argument("--apply", action="store_true", help="Move folders instead of dry-running.")
+    parsed_arguments = parser.parse_args()
+    run_resort(
+        parsed_arguments.base_path,
+        parsed_arguments.month,
+        parsed_arguments.day,
+        parsed_arguments.account,
+        parsed_arguments.apply,
+    )
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/eli5/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: eli5
+description: >-
+  Creates concise beginner-friendly HTML explanations with large visuals and minimal text. Triggers: ELI5, explain like I am 5, explain this simply, beginner explanation, every user-facing response.
+---
+
+# ELI5
+
+All user-facing responses follow this skill.
+Avoid all negative prose.
+
+## Contents
+
+- [Principle](#principle)
+- [When this applies](#when-this-applies)
+- [Skill classification](#skill-classification)
+- [Authority boundaries](#authority-boundaries)
+- [Composition boundary](#composition-boundary)
+- [Gotchas](#gotchas)
+- [Task seeding](#task-seeding)
+- [Process](#process)
+- [File index](#file-index)
+- [Folder map](#folder-map)
+
+## Principle
+
+Explain the current topic for a complete beginner with plain language, large
+visuals, and very few words. Keep the explanation concise, friendly, useful,
+self-contained, and browser-ready.
+
+ELI5 owns the HTML presentation envelope. Use one stable self-contained HTML
+artifact for the active task or conversation. Keep update-in-place continuity as
+the conversation continues, and share the current artifact after each update.
+
+## When this applies
+
+Apply ELI5 to every user-facing response, including responses that present a
+capability-specific artifact. Raw tool output, machine payloads, code, and
+native repository artifacts retain their required formats. Present their human
+explanation inside the HTML presentation envelope when the response is user-facing.
+
+### First-match refusal condition
+
+Evaluate this condition before task seeding. When no task tool is available,
+reply exactly: `ELI5 requires a session task tool. The artifact flow is paused.`
+
+## Skill classification
+
+**Dominant type:** Business Process & Team Automation.
+
+**Folder rationale:** `SKILL.md` holds the global artifact workflow, and
+`reference/task-seeds.md` holds its ordered session tasks. The leaf keeps its
+presentation capability local.
+
+## Authority boundaries
+
+| Owner | Owns | ELI5 action |
+|---|---|---|
+| ELI5 | Beginner framing, visual expectation, minimal content, HTML continuity, and sharing | Keep the response in one useful, stable artifact. |
+| `~/.claude/rules/asd-ste100-language.md` | Word choice, sentence structure, terminology, punctuation, procedural instructions, and safety text | Read and apply it before writing or updating any page or response prose. |
+| The named capability skill | Native data, evidence, workflow, and file-format requirements | Preserve its contract inside the HTML presentation envelope. |
+| User instructions and safety requirements | Task boundary, audience, confidentiality, and permitted result | Treat them as the controlling scope for the page. |
+| Human review | Technical accuracy, terminology, safety, confidentiality, intended meaning, and rendered usefulness | Review the completed artifact before delivery. |
+
+## Composition boundary
+
+ELI5 is a leaf skill. Explanation and visual composition remain one user-facing
+capability. ELI5 invokes zero presentation sub-skills. Named capability skills
+keep ownership of their native artifact rules while ELI5 supplies the global
+ HTML presentation envelope.
+
+## Gotchas
+
+- Keep the HTML presentation envelope active when another capability skill creates the page.
+- Keep sentence-level prose under `~/.claude/rules/asd-ste100-language.md`.
+- Preserve an explicit user-supplied output path and an existing artifact path.
+- Keep one artifact path across all updates in the active task or conversation.
+- Keep every page self-contained and browser-ready.
+- Preserve native wrapper, payload, evidence, and file-format contracts owned by
+  the named capability skill.
+- Use human review for accuracy, terminology, safety, confidentiality, meaning,
+  and rendered legibility.
+
+## Task seeding
+
+At skill start, register every item in `reference/task-seeds.md` as a session
+task through `TaskCreate`, `TodoWrite`, or the host task equivalent. Work from
+that task list. Mark each item complete with `PASS`, `FAIL` plus file evidence,
+or `N/A` plus the reason. When no task tool is available, use the exact refusal
+under [When this applies](#when-this-applies) before authoring the artifact.
+
+## Process
+
+1. **Deterministic — locate the current HTML artifact or create the first one.** Find the active
+   artifact, preserve an explicit user path, or create a clear self-contained
+   browser-ready HTML artifact when no path exists. Keep the chosen path for the
+   rest of the active task or conversation.
+2. **Borderline — add the current explanation to that artifact.** Read and apply
+   `~/.claude/rules/asd-ste100-language.md` to every sentence. Frame the topic
+   for a beginner, use a large useful visual, keep the text minimal, and update
+   the same artifact in place.
+3. **Judgment — share the updated artifact with the user.** Review technical meaning,
+   terminology, safety, confidentiality, accessibility, browser readiness, and
+   visual legibility. When a check reports a defect, repair the artifact, repeat
+   the review, and share after all checks pass.
+
+### Examples
+
+- **Creation:** Input — `Explain DNS for a beginner` with no artifact path.
+  Output — `dns-explanation.html` with one self-contained page and a large visual.
+- **Update and share:** Input — `Add why DNS caching helps` in the same
+  conversation. Output — the same `dns-explanation.html` path updated and shared.
+
+## File index
+
+| Path | Purpose |
+|---|---|
+| `SKILL.md` | Global ELI5 presentation contract, authority boundaries, gotchas, and artifact flow. |
+| `reference/task-seeds.md` | Ordered process items to register as session tasks. |
+
+## Folder map
+
+```text
+eli5/
+├── SKILL.md
+└── reference/
+    └── task-seeds.md
+```

package/.agents/skills/eli5/reference/task-seeds.md

@@ -0,0 +1,11 @@
+# ELI5 task seeds
+
+Register each item as a session task at the start of the ELI5 process. Complete
+each task with `PASS`, `FAIL` plus file evidence, or `N/A` plus the reason.
+
+1. Resolve the active HTML artifact path and preserve the stable path.
+2. Create the artifact when no active path exists and keep it self-contained.
+3. Apply the ASD-STE100 rule to page and response sentences.
+4. Add the concise beginner explanation and useful large visual in place.
+5. Review accuracy, terminology, safety, confidentiality, accessibility, and legibility.
+6. Share the updated artifact with the user.

package/.agents/skills/fresh-branch/scripts/test_create_fresh_branch.py

@@ -720,11 +720,10 @@ class TestWorktreeBranchTracking:
             capture_output=True,
             text=True,
         )
-        assert push_attempt.returncode != 0, (
-            "bare push should be refused, but it succeeded:\n"
+        assert read_remote_main_commit(repository_path) == origin_main_before, (
+            "bare push must not advance origin/main:\n"
             f"{push_attempt.stdout}{push_attempt.stderr}"
         )
-        assert read_remote_main_commit(repository_path) == origin_main_before
 
 
 class TestMainCli:

package/.agents/skills/name-by-capability-audit/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: name-by-capability-audit
+description: >-
+  Audit a GitHub PR for name-by-capability violations: driver/motive words on
+  reusable capability modules (queues and report routers may keep the driver
+  word), then apply capability-oriented renames by default. Triggers:
+  /name-by-capability-audit, name-by-capability audit, audit PR for naming, name
+  by capability, capability naming review, cert_fix rename check, driver word in
+  package name.
+---
+
+# Name-by-Capability Audit
+
+Audit a GitHub PR against the **name-by-capability** rule. Inspect paths and title wording for driver/motive words on reusable capability code, report findings with a rename direction, and apply the suggested renames by default. An explicit audit-only request ends after the report.
+
+## Gotchas
+
+- Name reusable libraries for the action they perform; a first cert caller still leaves the library capability-named. Score reuse potential alongside the PR title.
+- Correctly driver-named surfaces (`cert_fix_queue`, report routing/locate, unfixable patterns) are **OK** findings — list them under OK drivers.
+- Renames and new paths carry the most signal; when a PR expands an already-misnamed package, note the package name too.
+
+## When this applies
+
+- User invokes `/name-by-capability-audit <PR>` or asks to audit a PR for name-by-capability / capability naming.
+- PR adds or renames packages/modules, or frames a general shared operation with a driver/motive word (`cert_fix`, `cert_closeout`, `portal`, `export`, …).
+
+**First match wins:**
+
+- Missing PR number or URL → respond exactly: `Give a GitHub PR number or URL to audit for name-by-capability.`
+- User requests audit-only → finish the audit report and stop.
+- User gives a rename or fix direction → finish the audit report, then apply the direction they gave.
+- A violation with no user-supplied direction → finish the audit report, then apply the suggested rename direction by default.
+
+## Constraints
+
+- Report findings plus a suggested rename direction for each violation.
+- Suggest renames for paths the PR touched; for an expanded offense, also name the package the PR grew.
+- Distinguish **violation** vs **OK driver** using `reference/offense-examples.md`.
+
+## Process
+
+Register every bullet from `reference/task-seeds.md` on the host task tool (`TodoWrite` / `TaskCreate`). Mark each complete with evidence. Follow those seeds in order — do not restate them here.
+
+Load order for the rule: if `docs/agents/name-by-capability.md` exists, read it first; always keep `reference/rule-checklist.md` as the fallback when the doc is missing. On disagreement after the docs PR merges, prefer the repo doc and update the skill checklist in a follow-up.
+
+## Composition
+
+| Peer | Relationship |
+|------|----------------|
+| `shared-extraction-audit` | Layering and extraction (where code lives). Invoke when a path’s *role* is unclear; this skill only scores the *name*. |
+| `reviews` / PR review skills | May invoke this skill by name when naming is in scope |
+
+## File index
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Hub — gotchas, when-applies, process, composition |
+| `reference/rule-checklist.md` | Embedded rule + naming checklist (fallback when docs are missing) |
+| `reference/offense-examples.md` | Classifier + known OK drivers vs offenders |
+| `reference/fetch-commands.md` | Minimal `gh` fetch for PR naming surface |
+| `reference/report-template.md` | Compact report shape |
+| `reference/task-seeds.md` | Ordered task seeds for the audit run |
+
+## Folder map
+
+- `SKILL.md` — hub
+- `reference/` — rule, examples, fetch recipe, report template, task seeds

package/.agents/skills/name-by-capability-audit/reference/fetch-commands.md

@@ -0,0 +1,29 @@
+# Fetch PR naming surface
+
+**Execute** these commands (pwsh). Replace `<N>` with the PR number. Parse the PR number from a URL (`…/pull/2153` → `2153`) when the user pastes a link.
+
+Prefer this recipe so the user’s worktree stays as-is. Do not `gh pr checkout` for naming audits.
+
+## Metadata
+
+```powershell
+gh pr view <N> --json number,title,body,baseRefName,headRefName,url
+```
+
+## Paths and renames
+
+One paginated files list covers added, modified, and renamed paths (`status`, `previous_filename`). Use `--paginate --slurp` per `gh-cli-conventions` (not built-in `--jq` across pages):
+
+```powershell
+gh api repos/:owner/:repo/pulls/<N>/files --paginate --slurp
+```
+
+When `:owner` / `:repo` are unknown, resolve them from `gh pr view <N> --json headRepository,url` or the PR URL, then re-run the files call.
+
+## What to keep from the fetch
+
+- PR title and first paragraph of body (scope wording)
+- Every added or renamed path under package roots and `.claude/skills/`
+- New Python module stems whose names carry driver words
+
+Scoring rules for those signals live in `reference/rule-checklist.md` — this file only fetches.

package/.agents/skills/name-by-capability-audit/reference/offense-examples.md

@@ -0,0 +1,32 @@
+# Offense examples (this repo)
+
+Classify by **role** — the reusable work the surface performs — not by matching a string list. For whether code belongs in `shared_utils` vs a workflow package, invoke `shared-extraction-audit`; this map only scores names.
+
+## Quick classifier
+
+```
+Queue, report parser, or routing table for one workflow only?
+  YES → driver name OK
+Shared artifact change a second workflow would call?
+  YES → capability name required (flag when a driver word is present)
+  Stays inside that workflow → OK driver; state why in the report
+```
+
+## OK — correctly driver-named
+
+| Surface | Why OK |
+|---------|--------|
+| `cert_fix_queue` | Rejected-theme queue drain — driver-only orchestration |
+| Cert report title → which ops to run | Driver / routing |
+| Cert report locate / folder routing | Driver-only path finding for cert artifacts |
+| Unfixable / unfixable-pattern tables | Cert-report classification artifacts |
+
+## Violations — driver word on reusable capability
+
+| Surface | Why violation | Suggested rename direction |
+|---------|---------------|----------------------------|
+| `cert_closeout` color engine (batch color UID rewrite) | General STP color batch shared across workflows | Capability name: STP color batch / color UID rewrite |
+| `cert_fix_*` modules that are general STP patches | Patch logic reusable outside cert closeout | Name the STP operation (asset replace, sound slot, …) |
+| `cert_fix_page_indicators` | Thematic page-indicator pair generation is a reusable asset op | Capability: page indicators / home indicator pair |
+| Portal/export-named helper that any workflow could call | Motive word on a reusable library | Name the shared action (sheet write, APK locate, …) |
+| PR titled or scoped with a driver word when the diff is a general capability | Motive framing on a library change | Retitle/scope to the capability; keep driver wording on the queue/driver PR |