td-ai-tools 1.3.1 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/skills/README.md

@@ -14,9 +14,9 @@
 - `pr-solver`: Resolve GitHub pull request feedback by querying unresolved review conversations with the GitHub GraphQL API…
 - `pull-request`: Generates well-structured GitHub pull request descriptions for Shopify theme development teams by analyzing…
 - `pull-request-statamic`: Generates GitHub pull request descriptions for Statamic and Laravel development by analyzing git diffs and…
-- `record-changes`: Update `docs/changes.md` by summarizing the current branch against the primary development branch.
 - `shopify-cli`: Shopify CLI workflows for theme development.
 - `shopify-lint`: Run Shopify CLI Theme Check and Theory Digital's bundled Liquid, JavaScript, and CSS rules together, linting…
+- `shopify-pre-pr`: Prepare a Shopify theme branch for pull request.
 - `stylesheet-migration`: Migrate Shopify Liquid `{% stylesheet %}` blocks into theme CSS assets using bundled Python scripts.
 - `td-js-vanilla-rules`: Theory Digital vanilla JavaScript standards for Shopify theme work.
 - `td-review`: Run parallel code review agents on a PR (including TD theme compliance) and produce a synthesized findings…

package/skills/shopify-pre-pr/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: shopify-pre-pr
+version: 2.0.0
+description: Prepare a Shopify theme branch for pull request. Audits every modified vendor file (any file whose name does not contain `td-`) for TD CHANGE delimiter comments and adds the missing ones, then updates `docs/changes.md` with a branch summary. Use when a developer asks to prep a branch for PR, wrap or check vendor edits with TD CHANGE comments, record branch changes, document theme customizations, or refresh the project change log. Prefer comparing against `main`, but fall back to `origin/main`, `master`, or `origin/master` when the repository does not have a local `main` branch.
+---
+
+# Shopify Pre-PR
+
+Two passes over the current branch before it becomes a pull request:
+
+1. **Vendor delimiters** — every change to a vendor file must be wrapped in TD CHANGE comments. Add the missing ones.
+2. **Changelog** — record the branch in `docs/changes.md`.
+
+Run them in that order, so the changelog describes the final state of the branch.
+
+Vendor file: any changed file whose **basename does not contain `td-`** (`sections/header.liquid` is vendor; `sections/td-header.liquid` and `snippets/_td-globals.liquid` are custom). A `td-` directory does not make the files inside it custom.
+
+## Part 1 — Vendor Delimiter Audit
+
+### 1. Run the audit
+
+```bash
+python3 .agents/skills/shopify-pre-pr/scripts/vendor_change_audit.py
+```
+
+Options:
+
+- `--base release/x.y` — compare against an explicit base ref.
+- `--custom-prefix th-` — different custom prefix (repeatable).
+- `--format json` — machine-readable output.
+- `--strict` — exit 1 when any vendor change is missing delimiters, for hooks and CI.
+- Trailing paths — limit the audit to specific files or directories.
+
+The script compares the working tree against the merge base, so uncommitted work is included. For each modified vendor file it reports the correct comment syntax and the changed line ranges that are **not** inside a TD CHANGE block.
+
+Coverage is computed by scanning the **entire file** for delimiters and tracking nesting depth, not by looking at the diff context. A change is already covered when any enclosing block wraps it at any depth — including delimiters that were committed long before this branch. Do not add a second pair inside a block that already contains the change.
+
+### 2. Add the missing delimiters
+
+Read `references/td-change-delimiters.md` for the per-language syntax and placement rules, then edit each file the audit lists under **Needs delimiters**.
+
+Core rules:
+
+- Match the comment syntax to the language, and to the region inside `.liquid` files — `{% comment %}` tags in markup, `//` inside `{% javascript %}` or an inline `<script>`, `/* */` inside `{% stylesheet %}`.
+- Wrap the smallest complete, syntactically valid unit containing the change. Never split an open tag, attribute list, statement, or declaration block, and keep Liquid control flow balanced inside the block.
+- One delimiter pair per contiguous change, not one per line.
+- Do not reformat, reorder, or otherwise touch the surrounding vendor code — the only edit in this pass is inserting comment lines.
+- Never invent delimiters for changes the audit reports as not delimitable (`{% schema %}` blocks, `.json` files). Document those in Part 2 instead.
+
+### 3. Resolve the other findings
+
+- **Malformed markers** — an unclosed `TD CHANGE` or an orphan `END TD CHANGE`. Repair the pair; do not delete a marker just to balance the file, since existing wrapped edits must stay marked.
+- **Cannot be delimited** — `.json` files, unrecognized file types, and changes inside a `{% schema %}` block. These never appear under **Needs delimiters** because no comment syntax exists for them; carry each one into the changelog's vendor subsection with reapply detail.
+- **Other vendor-path changes** — new files without a custom prefix (rename to `td-` unless there is a documented reason) and deleted vendor files (confirm intent).
+
+### 4. Verify
+
+Re-run the audit. It must report zero files needing delimiters and no malformed markers before moving on. Then confirm the theme still parses — for example via the `shopify-lint` skill or `shopify theme check` — because a misplaced comment inside Liquid markup is a syntax error, not a no-op.
+
+## Part 2 — Record Changes
+
+Update `docs/changes.md` from the current branch diff. Preserve the existing document structure and add a concise, human-readable entry for the branch.
+
+### 1. Collect branch context
+
+```bash
+python3 .agents/skills/shopify-pre-pr/scripts/branch_diff_context.py
+```
+
+If the developer specifies another comparison branch, pass it explicitly:
+
+```bash
+python3 .agents/skills/shopify-pre-pr/scripts/branch_diff_context.py --base release/x.y
+```
+
+Read the existing `docs/changes.md` before editing so the new entry matches the current ordering, tone, and section layout.
+
+### 2. Inspect the actual code changes
+
+Use the script output to identify changed files, then inspect the relevant diffs and file contents with `git diff` and targeted file reads.
+
+Prioritize:
+
+- User-facing behavior changes
+- CMS setting/schema changes
+- CSS or markup changes that affect rendering
+- Renamed files and vendor-theme hotspots
+
+Do not summarize the `docs/changes.md` edit itself, or the delimiter comments added in Part 1, as branch work. If the branch contains unrelated skill or tooling files, either omit them from the changelog entry or separate them clearly when they are relevant to the project's maintenance history.
+
+### 3. Write the changelog entry
+
+Add a new entry near the top of `docs/changes.md`, directly under the intro, unless the file already uses another ordering convention.
+
+Follow the existing pattern:
+
+- `## <short title>`
+- `**Date:** YYYY-MM-DD`
+- `### Purpose`
+- `### Files changed`
+- `### Upgrade impact`
+- `### Notes`
+
+Guidelines:
+
+- Make the title describe the feature or fix, not the branch name.
+- Write `Purpose` in plain language with outcome-focused bullets.
+- Use the `Files changed` table to explain why each file matters.
+- Call out non-`td-` theme or vendor files in a separate subsection, and for each one record what changed and how to reapply it after a vendor theme update.
+- List every vendor edit that could not be delimited (`{% schema %}` blocks, JSON templates) explicitly in that subsection — the comments cannot mark them, so the changelog is the only record.
+- Mention renamed files explicitly.
+- Keep `Upgrade impact` brief and concrete.
+- Use `Notes` for implementation details, edge cases, or assumptions.
+
+### 4. Verify before finishing
+
+Before wrapping up:
+
+- Re-read the new markdown entry in context.
+- Confirm every listed file appears in the diff.
+- Confirm the documented behavior matches the code, not just the branch name.
+- Confirm every vendor file in the diff is either delimited or documented.
+- Mention any uncertainty if the diff is too broad to summarize with high confidence.
+
+## Resources
+
+- `scripts/vendor_change_audit.py`: Report which vendor-file changes lack TD CHANGE delimiters, with the correct comment syntax per file and per Liquid region.
+- `scripts/branch_diff_context.py`: Resolve the best available base branch and print a branch summary with file statuses and line counts.
+- `references/td-change-delimiters.md`: Delimiter format, per-language syntax table, and placement rules.

package/skills/shopify-pre-pr/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+    display_name: 'Shopify Pre-PR'
+    short_description: 'Delimit vendor edits and update docs/changes.md before a PR'
+    default_prompt: 'Use $shopify-pre-pr to wrap this branch''s vendor file changes in TD CHANGE comments and update docs/changes.md.'

package/skills/shopify-pre-pr/references/td-change-delimiters.md

@@ -0,0 +1,88 @@
+# TD CHANGE Delimiters
+
+Every edit to a vendor file (any file whose basename does not contain `td-`) must sit between a pair of TD CHANGE comments so the edit can be found and reapplied after a vendor theme update.
+
+## Canonical format
+
+```
+// ------------TD CHANGE-----------
+// ----------END TD CHANGE---------
+```
+
+Keep the marker text and dash counts exactly as above. Only the comment syntax changes per language.
+
+## Syntax by language
+
+| File | Start | End |
+|------|-------|-----|
+| `.liquid` (markup) | `{% comment %} ------------TD CHANGE----------- {% endcomment %}` | `{% comment %} ----------END TD CHANGE--------- {% endcomment %}` |
+| `.js`, `.mjs`, `.cjs`, `.ts` | `// ------------TD CHANGE-----------` | `// ----------END TD CHANGE---------` |
+| `.css` | `/* ------------TD CHANGE----------- */` | `/* ----------END TD CHANGE--------- */` |
+| `.scss`, `.sass` | `// ------------TD CHANGE-----------` | `// ----------END TD CHANGE---------` |
+| `.html`, `.svg`, `.xml` | `<!-- ------------TD CHANGE----------- -->` | `<!-- ----------END TD CHANGE--------- -->` |
+| `.yml`, `.yaml`, `.sh` | `# ------------TD CHANGE-----------` | `# ----------END TD CHANGE---------` |
+| `.json` | Not possible — see below | |
+
+Liquid comment tags are preferred over `<!-- -->` inside `.liquid` files because they are stripped server-side and never reach the rendered page.
+
+## Regions inside a `.liquid` file
+
+A `.liquid` file mixes languages, so the delimiter syntax depends on where the edit lands:
+
+- Inside `{% stylesheet %}` … `{% endstylesheet %}` → CSS block comments.
+- Inside `{% javascript %}` … `{% endjavascript %}` or an inline `<script>` → `//` line comments.
+- Inside `{% schema %}` … `{% endschema %}` → **cannot be commented** (it is JSON). Document the schema edit in `docs/changes.md` instead of wrapping it.
+
+## Placement rules
+
+- Put the delimiters on their own lines, at the indentation of the code they wrap.
+- Wrap the smallest complete, syntactically valid unit that contains the change — never split an open HTML tag, a Liquid tag, an attribute list, a CSS declaration block, or a statement.
+- Keep Liquid control flow balanced inside the block. If a change adds an `{% if %}` whose `{% endif %}` is elsewhere, extend the block to include both.
+- Wrap contiguous changes once rather than emitting a delimiter pair per line. Separate hunks in the same file get their own pairs.
+- Never nest a new pair inside an existing pair that already contains the change — coverage counts at any depth, so an enclosing block is already sufficient.
+- When a change deletes vendor code, leave the delimiters around the surrounding region and note the deletion in `docs/changes.md`; a comment cannot mark absent lines on its own.
+
+## Formats that cannot carry comments
+
+JSON (`templates/*.json`, `locales/*.json`, `config/settings_data.json`) has no comment syntax. Do not attempt to fake one. Record these edits in the vendor subsection of the `docs/changes.md` entry with enough detail to reapply them.
+
+## Examples
+
+Liquid markup:
+
+```liquid
+<div class="header__inner">
+  {% comment %} ------------TD CHANGE----------- {% endcomment %}
+  {% render 'td-announcement' %}
+  {% comment %} ----------END TD CHANGE--------- {% endcomment %}
+</div>
+```
+
+CSS:
+
+```css
+/* ------------TD CHANGE----------- */
+.header { --header-height: 72px; }
+/* ----------END TD CHANGE--------- */
+```
+
+JavaScript:
+
+```js
+// ------------TD CHANGE-----------
+if (!customElements.get('td-cart-drawer')) {
+  customElements.define('td-cart-drawer', TdCartDrawer);
+}
+// ----------END TD CHANGE---------
+```
+
+Stylesheet block inside a vendor section:
+
+```liquid
+{% stylesheet %}
+  .card { display: grid; }
+  /* ------------TD CHANGE----------- */
+  .card { gap: var(--td-gap); }
+  /* ----------END TD CHANGE--------- */
+{% endstylesheet %}
+```

package/skills/shopify-pre-pr/scripts/test_vendor_change_audit.py

@@ -0,0 +1,424 @@
+from __future__ import annotations
+
+from pathlib import Path
+import os
+import subprocess
+import tempfile
+import unittest
+
+from vendor_change_audit import (
+    coverage_for_range,
+    delimiters,
+    build_report,
+    comment_style,
+    is_custom,
+    parse_hunk_ranges,
+    scan_liquid_regions,
+    scan_markers,
+)
+
+
+SCRIPT = Path(__file__).resolve().parent / "vendor_change_audit.py"
+
+
+def covered(text: str) -> set[int]:
+    return scan_markers(text.splitlines())["covered"]
+
+
+class MarkerScanTests(unittest.TestCase):
+    def test_lines_between_markers_are_covered(self) -> None:
+        result = scan_markers(
+            [
+                "const a = 1;",
+                "// ------------TD CHANGE-----------",
+                "const b = 2;",
+                "// ----------END TD CHANGE---------",
+                "const c = 3;",
+            ]
+        )
+
+        self.assertEqual(result["covered"], {2, 3, 4})
+        self.assertEqual(result["blocks"], [{"start": 2, "end": 4, "depth": 1}])
+        self.assertEqual(result["unclosed_starts"], [])
+        self.assertEqual(result["unmatched_ends"], [])
+
+    def test_nested_blocks_keep_outer_coverage(self) -> None:
+        result = scan_markers(
+            [
+                "outer before",
+                "{% comment %} ------------TD CHANGE----------- {% endcomment %}",
+                "still inside outer",
+                "{% comment %} ------------TD CHANGE----------- {% endcomment %}",
+                "inside inner",
+                "{% comment %} ----------END TD CHANGE--------- {% endcomment %}",
+                "back in outer only",
+                "{% comment %} ----------END TD CHANGE--------- {% endcomment %}",
+                "outer after",
+            ]
+        )
+
+        self.assertEqual(result["covered"], {2, 3, 4, 5, 6, 7, 8})
+        self.assertEqual(
+            result["blocks"],
+            [{"start": 2, "end": 8, "depth": 1}, {"start": 4, "end": 6, "depth": 2}],
+        )
+
+    def test_end_marker_is_not_mistaken_for_a_start(self) -> None:
+        result = scan_markers(
+            [
+                "// ----------END TD CHANGE---------",
+                "after",
+            ]
+        )
+
+        self.assertEqual(result["unmatched_ends"], [1])
+        self.assertEqual(result["covered"], {1})
+        self.assertNotIn(2, result["covered"])
+
+    def test_unclosed_start_is_reported(self) -> None:
+        result = scan_markers(["/* ------------TD CHANGE----------- */", "body {}"])
+
+        self.assertEqual(result["unclosed_starts"], [1])
+        self.assertEqual(result["blocks"], [])
+
+    def test_loose_marker_spellings_still_count(self) -> None:
+        self.assertEqual(
+            covered("a\n# TD-CHANGE\nb\n# end td change\nc\n"),
+            {2, 3, 4},
+        )
+
+
+class CoverageTests(unittest.TestCase):
+    def test_range_fully_inside_block(self) -> None:
+        self.assertEqual(coverage_for_range({5, 6, 7}, 5, 7), "covered")
+
+    def test_range_outside_block(self) -> None:
+        self.assertEqual(coverage_for_range({5, 6, 7}, 10, 12), "uncovered")
+
+    def test_range_straddling_a_block_edge(self) -> None:
+        self.assertEqual(coverage_for_range({5, 6, 7}, 6, 9), "partial")
+
+
+class HunkParsingTests(unittest.TestCase):
+    def test_parses_multi_line_hunks(self) -> None:
+        diff = "@@ -10,2 +10,3 @@\n+new\n@@ -40 +41 @@\n+edit\n"
+
+        self.assertEqual(parse_hunk_ranges(diff), [(10, 12), (41, 41)])
+
+    def test_pure_deletion_reports_the_adjacent_line(self) -> None:
+        self.assertEqual(parse_hunk_ranges("@@ -10,3 +9,0 @@\n-gone\n"), [(9, 9)])
+
+    def test_deletion_at_file_start_clamps_to_line_one(self) -> None:
+        self.assertEqual(parse_hunk_ranges("@@ -1,3 +0,0 @@\n-gone\n"), [(1, 1)])
+
+
+class ClassificationTests(unittest.TestCase):
+    def test_custom_prefix_detected_anywhere_in_basename(self) -> None:
+        self.assertTrue(is_custom("sections/td-hero.liquid", ("td-",)))
+        self.assertTrue(is_custom("snippets/_td-helper.liquid", ("td-",)))
+        self.assertFalse(is_custom("sections/header.liquid", ("td-",)))
+
+    def test_directory_named_td_does_not_make_a_file_custom(self) -> None:
+        self.assertFalse(is_custom("td-theme/sections/header.liquid", ("td-",)))
+
+    def test_json_has_no_comment_style(self) -> None:
+        self.assertIsNone(comment_style("templates/index.json"))
+
+    def test_delimiters_match_the_house_format(self) -> None:
+        style = comment_style("assets/base.js")
+        assert style is not None
+        self.assertEqual(
+            delimiters(style),
+            ("// ------------TD CHANGE-----------", "// ----------END TD CHANGE---------"),
+        )
+
+    def test_liquid_uses_comment_tags(self) -> None:
+        style = comment_style("sections/header.liquid")
+        assert style is not None
+        self.assertEqual(
+            delimiters(style),
+            (
+                "{% comment %} ------------TD CHANGE----------- {% endcomment %}",
+                "{% comment %} ----------END TD CHANGE--------- {% endcomment %}",
+            ),
+        )
+
+
+class LiquidRegionTests(unittest.TestCase):
+    def test_schema_block_is_located(self) -> None:
+        regions = scan_liquid_regions(
+            [
+                "<div>markup</div>",
+                "{% schema %}",
+                '{ "name": "Header" }',
+                "{% endschema %}",
+            ]
+        )
+
+        self.assertEqual(regions, [{"name": "schema", "start": 2, "end": 4, "extension": None}])
+
+    def test_stylesheet_and_javascript_blocks_map_to_their_syntax(self) -> None:
+        regions = scan_liquid_regions(
+            [
+                "{% stylesheet %}",
+                ".a { color: red; }",
+                "{% endstylesheet %}",
+                "{%- javascript -%}",
+                "const a = 1;",
+                "{%- endjavascript -%}",
+            ]
+        )
+
+        self.assertEqual(
+            regions,
+            [
+                {"name": "stylesheet", "start": 1, "end": 3, "extension": ".css"},
+                {"name": "javascript", "start": 4, "end": 6, "extension": ".js"},
+            ],
+        )
+
+    def test_external_script_tag_is_not_treated_as_a_js_region(self) -> None:
+        regions = scan_liquid_regions(['<script src="{{ \'a.js\' | asset_url }}" defer></script>'])
+
+        self.assertEqual(regions, [])
+
+
+class RepoFixture:
+    """A throwaway git repo with a `main` branch and a feature branch."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def git(self, *args: str) -> str:
+        completed = subprocess.run(
+            ["git", *args],
+            cwd=self.root,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return completed.stdout
+
+    def write(self, relative: str, content: str) -> None:
+        path = self.root / relative
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content)
+
+    def init(self) -> None:
+        self.git("init", "--initial-branch=main")
+        self.git("config", "user.email", "test@example.com")
+        self.git("config", "user.name", "Test")
+
+    def commit(self, message: str) -> None:
+        self.git("add", "-A")
+        self.git("commit", "-m", message)
+
+
+class BuildReportTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self._cwd = os.getcwd()
+        self.repo = RepoFixture(Path(self._tmp.name))
+        self.repo.init()
+        self.repo.write(
+            "sections/header.liquid",
+            "<header>\n  <span>Vendor</span>\n</header>\n",
+        )
+        self.repo.write("assets/base.css", "body { margin: 0; }\n")
+        self.repo.write("sections/td-hero.liquid", "<section>Hero</section>\n")
+        self.repo.write("templates/index.json", '{ "sections": {} }\n')
+        self.repo.commit("base")
+        self.repo.git("checkout", "-b", "feature")
+        os.chdir(self.repo.root)
+
+    def tearDown(self) -> None:
+        os.chdir(self._cwd)
+        self._tmp.cleanup()
+
+    def entry_for(self, report: dict[str, object], path: str) -> dict[str, object]:
+        for entry in report["files"]:  # type: ignore[union-attr]
+            if entry["path"] == path:
+                return entry
+        raise AssertionError(f"no entry for {path}")
+
+    def test_undelimited_vendor_edit_is_flagged(self) -> None:
+        self.repo.write(
+            "sections/header.liquid",
+            "<header>\n  <span>Vendor</span>\n  <span>Added</span>\n</header>\n",
+        )
+
+        report = build_report("main", ("td-",), [])
+        entry = self.entry_for(report, "sections/header.liquid")
+
+        self.assertEqual(entry["category"], "vendor_modified")
+        self.assertTrue(entry["needs_delimiters"])
+        self.assertEqual(entry["hunks"], [{"start": 3, "end": 3, "coverage": "uncovered"}])
+
+    def test_delimited_vendor_edit_passes(self) -> None:
+        self.repo.write(
+            "sections/header.liquid",
+            "<header>\n"
+            "  <span>Vendor</span>\n"
+            "  {% comment %} ------------TD CHANGE----------- {% endcomment %}\n"
+            "  <span>Added</span>\n"
+            "  {% comment %} ----------END TD CHANGE--------- {% endcomment %}\n"
+            "</header>\n",
+        )
+
+        report = build_report("main", ("td-",), [])
+        entry = self.entry_for(report, "sections/header.liquid")
+
+        self.assertFalse(entry["needs_delimiters"])
+        self.assertEqual([hunk["coverage"] for hunk in entry["hunks"]], ["covered"])
+
+    def test_edit_inside_a_pre_existing_outer_block_passes(self) -> None:
+        # The delimiters are already on main, far from the new edit: coverage has
+        # to be judged from the whole file, not from the diff context.
+        self.repo.write(
+            "assets/base.css",
+            "/* ------------TD CHANGE----------- */\n"
+            "body { margin: 0; }\n"
+            ".a {}\n"
+            ".b {}\n"
+            "/* ----------END TD CHANGE--------- */\n",
+        )
+        self.repo.commit("wrap existing region")
+        self.repo.write(
+            "assets/base.css",
+            "/* ------------TD CHANGE----------- */\n"
+            "body { margin: 0; }\n"
+            ".a {}\n"
+            ".new { color: red; }\n"
+            ".b {}\n"
+            "/* ----------END TD CHANGE--------- */\n",
+        )
+
+        report = build_report("main", ("td-",), [])
+        entry = self.entry_for(report, "assets/base.css")
+
+        self.assertFalse(entry["needs_delimiters"])
+
+    def test_custom_and_ignored_files_are_not_audited(self) -> None:
+        self.repo.write("sections/td-hero.liquid", "<section>Hero v2</section>\n")
+        self.repo.write("docs/changes.md", "# Changes\n")
+
+        report = build_report("main", ("td-",), [])
+
+        self.assertEqual(self.entry_for(report, "sections/td-hero.liquid")["category"], "custom")
+        self.assertEqual(self.entry_for(report, "docs/changes.md")["category"], "ignored")
+
+    def test_json_vendor_edit_is_reported_as_not_delimitable(self) -> None:
+        self.repo.write("templates/index.json", '{ "sections": { "a": {} } }\n')
+
+        report = build_report("main", ("td-",), [])
+        entry = self.entry_for(report, "templates/index.json")
+
+        self.assertEqual(entry["category"], "not_delimitable")
+
+    def test_schema_edit_is_marked_undelimitable(self) -> None:
+        self.repo.write(
+            "sections/header.liquid",
+            "<header>\n"
+            "  <span>Vendor</span>\n"
+            "</header>\n"
+            "{% schema %}\n"
+            '{ "name": "Header", "settings": [] }\n'
+            "{% endschema %}\n",
+        )
+        self.repo.commit("add schema")
+        self.repo.write(
+            "sections/header.liquid",
+            "<header>\n"
+            "  <span>Vendor</span>\n"
+            "</header>\n"
+            "{% schema %}\n"
+            '{ "name": "Header", "settings": [{ "id": "td_flag" }] }\n'
+            "{% endschema %}\n",
+        )
+
+        report = build_report("main", ("td-",), [])
+        entry = self.entry_for(report, "sections/header.liquid")
+
+        self.assertEqual(entry["hunks"][0]["region"], "schema")
+        self.assertFalse(entry["hunks"][0]["delimitable"])
+        # Impossible to delimit, so it must not be reported as actionable work.
+        self.assertFalse(entry["needs_delimiters"])
+        self.assertEqual(len(entry["undelimitable_hunks"]), 1)
+
+        completed = subprocess.run(
+            ["python3", str(SCRIPT), "--strict"],
+            cwd=self.repo.root,
+            capture_output=True,
+            text=True,
+        )
+
+        self.assertEqual(completed.returncode, 0)
+        self.assertIn("Cannot be delimited", completed.stdout)
+        self.assertNotIn("Needs delimiters", completed.stdout)
+
+    def test_stylesheet_block_edit_suggests_css_delimiters(self) -> None:
+        self.repo.write(
+            "sections/header.liquid",
+            "<header></header>\n{% stylesheet %}\n.a {}\n{% endstylesheet %}\n",
+        )
+        self.repo.commit("add stylesheet block")
+        self.repo.write(
+            "sections/header.liquid",
+            "<header></header>\n{% stylesheet %}\n.a {}\n.b {}\n{% endstylesheet %}\n",
+        )
+
+        report = build_report("main", ("td-",), [])
+        entry = self.entry_for(report, "sections/header.liquid")
+
+        self.assertEqual(entry["hunks"][0]["region"], "stylesheet")
+        self.assertEqual(entry["hunks"][0]["start_delimiter"], "/* ------------TD CHANGE----------- */")
+
+    def test_untracked_vendor_file_is_reported(self) -> None:
+        self.repo.write("snippets/promo.liquid", "<p>promo</p>\n")
+
+        report = build_report("main", ("td-",), [])
+
+        self.assertEqual(self.entry_for(report, "snippets/promo.liquid")["category"], "vendor_added")
+
+    def test_malformed_markers_are_reported(self) -> None:
+        self.repo.write(
+            "assets/base.css",
+            "/* ------------TD CHANGE----------- */\nbody { margin: 1px; }\n",
+        )
+
+        report = build_report("main", ("td-",), [])
+        entry = self.entry_for(report, "assets/base.css")
+
+        self.assertTrue(entry["malformed"])
+        self.assertEqual(entry["unclosed_starts"], [1])
+
+    def test_strict_mode_exits_non_zero_on_uncovered_change(self) -> None:
+        self.repo.write(
+            "sections/header.liquid",
+            "<header>\n  <span>Vendor</span>\n  <span>Added</span>\n</header>\n",
+        )
+
+        completed = subprocess.run(
+            ["python3", str(SCRIPT), "--strict"],
+            cwd=self.repo.root,
+            capture_output=True,
+            text=True,
+        )
+
+        self.assertEqual(completed.returncode, 1)
+        self.assertIn("Needs delimiters", completed.stdout)
+
+    def test_clean_branch_exits_zero_in_strict_mode(self) -> None:
+        completed = subprocess.run(
+            ["python3", str(SCRIPT), "--strict"],
+            cwd=self.repo.root,
+            capture_output=True,
+            text=True,
+        )
+
+        self.assertEqual(completed.returncode, 0)
+        self.assertIn("No vendor files changed", completed.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/shopify-pre-pr/scripts/vendor_change_audit.py

@@ -0,0 +1,540 @@
+#!/usr/bin/env python3
+"""Audit branch changes to vendor files for TD CHANGE delimiter coverage.
+
+A vendor file is any changed file whose basename does not contain the custom
+prefix (`td-` by default). Every modification to such a file must sit inside a
+pair of TD CHANGE delimiter comments. This script reports, per file, which
+changed line ranges are already inside a delimiter block at any nesting depth
+and which still need to be wrapped.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+DEFAULT_BASE_CANDIDATES = ("main", "origin/main", "master", "origin/master")
+
+START_TEXT = "------------TD CHANGE-----------"
+END_TEXT = "----------END TD CHANGE---------"
+
+# `END` is checked before `START`, because an end marker also matches the start
+# pattern. Separators are loose so hand-typed variants still count as coverage.
+END_MARKER = re.compile(r"END[\s_-]*TD[\s_-]*CHANGE", re.IGNORECASE)
+START_MARKER = re.compile(r"TD[\s_-]*CHANGE", re.IGNORECASE)
+
+HUNK_HEADER = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
+
+# Comment styles keyed by extension. `None` means the format cannot carry
+# comments at all, so the change has to be documented instead of delimited.
+LINE_COMMENT = "line"
+BLOCK_COMMENT = "block"
+
+COMMENT_STYLES: dict[str, dict[str, str] | None] = {
+    ".liquid": {"kind": BLOCK_COMMENT, "open": "{% comment %}", "close": "{% endcomment %}", "language": "liquid"},
+    ".js": {"kind": LINE_COMMENT, "open": "//", "language": "javascript"},
+    ".mjs": {"kind": LINE_COMMENT, "open": "//", "language": "javascript"},
+    ".cjs": {"kind": LINE_COMMENT, "open": "//", "language": "javascript"},
+    ".ts": {"kind": LINE_COMMENT, "open": "//", "language": "typescript"},
+    ".css": {"kind": BLOCK_COMMENT, "open": "/*", "close": "*/", "language": "css"},
+    ".scss": {"kind": LINE_COMMENT, "open": "//", "language": "scss"},
+    ".sass": {"kind": LINE_COMMENT, "open": "//", "language": "sass"},
+    ".html": {"kind": BLOCK_COMMENT, "open": "<!--", "close": "-->", "language": "html"},
+    ".svg": {"kind": BLOCK_COMMENT, "open": "<!--", "close": "-->", "language": "svg"},
+    ".xml": {"kind": BLOCK_COMMENT, "open": "<!--", "close": "-->", "language": "xml"},
+    ".md": {"kind": BLOCK_COMMENT, "open": "<!--", "close": "-->", "language": "markdown"},
+    ".yml": {"kind": LINE_COMMENT, "open": "#", "language": "yaml"},
+    ".yaml": {"kind": LINE_COMMENT, "open": "#", "language": "yaml"},
+    ".sh": {"kind": LINE_COMMENT, "open": "#", "language": "shell"},
+    ".json": None,
+    ".jsonc": None,
+}
+
+# Regions inside a `.liquid` file that use a different comment syntax than the
+# surrounding Liquid markup, or that cannot be commented at all.
+LIQUID_REGIONS = (
+    ("schema", re.compile(r"\{%-?\s*schema\s*-?%\}"), re.compile(r"\{%-?\s*endschema\s*-?%\}"), None),
+    ("javascript", re.compile(r"\{%-?\s*javascript\s*-?%\}"), re.compile(r"\{%-?\s*endjavascript\s*-?%\}"), ".js"),
+    ("stylesheet", re.compile(r"\{%-?\s*stylesheet[^%]*-?%\}"), re.compile(r"\{%-?\s*endstylesheet\s*-?%\}"), ".css"),
+    ("script tag", re.compile(r"<script(?![^>]*\bsrc=)[^>]*>"), re.compile(r"</script>"), ".js"),
+    ("style tag", re.compile(r"<style[^>]*>"), re.compile(r"</style>"), ".css"),
+)
+
+# Paths that are project tooling or documentation rather than theme vendor code.
+IGNORED_PREFIXES = (".agents/", ".claude/", ".codex/", ".github/", ".vscode/", "docs/", "node_modules/")
+IGNORED_BASENAMES = ("package-lock.json", "yarn.lock", "pnpm-lock.yaml", ".gitignore", "README.md", "AGENTS.md", "CLAUDE.md")
+
+
+def run_git(*args: str) -> str:
+    completed = subprocess.run(
+        ["git", *args],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+def ref_exists(ref: str) -> bool:
+    completed = subprocess.run(
+        ["git", "rev-parse", "--verify", f"{ref}^{{commit}}"],
+        capture_output=True,
+        text=True,
+    )
+    return completed.returncode == 0
+
+
+def resolve_base_ref(explicit_base: str | None) -> str:
+    if explicit_base:
+        if not ref_exists(explicit_base):
+            raise SystemExit(f"Base ref not found: {explicit_base}")
+        return explicit_base
+
+    for candidate in DEFAULT_BASE_CANDIDATES:
+        if ref_exists(candidate):
+            return candidate
+
+    searched = ", ".join(DEFAULT_BASE_CANDIDATES)
+    raise SystemExit(f"No base ref found. Tried: {searched}")
+
+
+def is_ignored(path: str) -> bool:
+    if path.startswith(IGNORED_PREFIXES):
+        return True
+    return os.path.basename(path) in IGNORED_BASENAMES
+
+
+def is_custom(path: str, prefixes: tuple[str, ...]) -> bool:
+    """A file is custom (not vendor) when its basename contains a custom prefix."""
+    basename = os.path.basename(path)
+    return any(prefix in basename for prefix in prefixes)
+
+
+def comment_style(path: str) -> dict[str, str] | None:
+    _, ext = os.path.splitext(path)
+    return COMMENT_STYLES.get(ext.lower())
+
+
+def has_known_extension(path: str) -> bool:
+    _, ext = os.path.splitext(path)
+    return ext.lower() in COMMENT_STYLES
+
+
+def delimiters(style: dict[str, str]) -> tuple[str, str]:
+    """Render the start/end delimiter lines for a comment style."""
+    if style["kind"] == LINE_COMMENT:
+        return f"{style['open']} {START_TEXT}", f"{style['open']} {END_TEXT}"
+    return (
+        f"{style['open']} {START_TEXT} {style['close']}",
+        f"{style['open']} {END_TEXT} {style['close']}",
+    )
+
+
+def parse_hunk_ranges(diff_output: str) -> list[tuple[int, int]]:
+    """Extract post-image line ranges from a `-U0` diff.
+
+    A pure deletion (`+c,0`) is reported as the single line `c`, the line the
+    removed content used to follow, so its surroundings are still checked for
+    delimiter coverage.
+    """
+    ranges: list[tuple[int, int]] = []
+    for line in diff_output.splitlines():
+        match = HUNK_HEADER.match(line)
+        if not match:
+            continue
+        start = int(match.group(1))
+        count = 1 if match.group(2) is None else int(match.group(2))
+        if count == 0:
+            ranges.append((max(start, 1), max(start, 1)))
+            continue
+        ranges.append((start, start + count - 1))
+    return ranges
+
+
+def scan_markers(lines: list[str]) -> dict[str, object]:
+    """Walk a file and record which lines sit inside a TD CHANGE block.
+
+    Nesting is tracked with a depth counter, so a change enclosed by an outer
+    block counts as covered even when an inner block sits beside it. Marker
+    lines themselves count as covered.
+    """
+    covered: set[int] = set()
+    blocks: list[dict[str, int]] = []
+    unclosed: list[int] = []
+    unmatched_ends: list[int] = []
+    open_starts: list[int] = []
+
+    for index, line in enumerate(lines, start=1):
+        if END_MARKER.search(line):
+            if open_starts:
+                start_line = open_starts.pop()
+                blocks.append({"start": start_line, "end": index, "depth": len(open_starts) + 1})
+            else:
+                unmatched_ends.append(index)
+            covered.add(index)
+            continue
+
+        if START_MARKER.search(line):
+            open_starts.append(index)
+            covered.add(index)
+            continue
+
+        if open_starts:
+            covered.add(index)
+
+    unclosed = sorted(open_starts)
+    return {
+        "covered": covered,
+        "blocks": sorted(blocks, key=lambda block: block["start"]),
+        "unclosed_starts": unclosed,
+        "unmatched_ends": unmatched_ends,
+    }
+
+
+def scan_liquid_regions(lines: list[str]) -> list[dict[str, object]]:
+    """Locate embedded regions in a Liquid file that need a different comment syntax."""
+    regions: list[dict[str, object]] = []
+    open_region: dict[str, object] | None = None
+
+    for index, line in enumerate(lines, start=1):
+        if open_region is not None:
+            if open_region["_end"].search(line):  # type: ignore[union-attr]
+                open_region["end"] = index
+                del open_region["_end"]
+                regions.append(open_region)
+                open_region = None
+            continue
+
+        for name, start_pattern, end_pattern, ext in LIQUID_REGIONS:
+            if not start_pattern.search(line):
+                continue
+            if end_pattern.search(line):
+                # Opened and closed on one line; nothing spans into later lines.
+                regions.append({"name": name, "start": index, "end": index, "extension": ext})
+            else:
+                open_region = {"name": name, "start": index, "end": 0, "extension": ext, "_end": end_pattern}
+            break
+
+    if open_region is not None:
+        open_region["end"] = len(lines)
+        del open_region["_end"]
+        regions.append(open_region)
+
+    return regions
+
+
+def region_for_range(regions: list[dict[str, object]], start: int, end: int) -> dict[str, object] | None:
+    for region in regions:
+        if start <= region["end"] and end >= region["start"]:  # type: ignore[operator]
+            return region
+    return None
+
+
+def coverage_for_range(covered: set[int], start: int, end: int) -> str:
+    total = end - start + 1
+    inside = sum(1 for line in range(start, end + 1) if line in covered)
+    if inside == 0:
+        return "uncovered"
+    if inside == total:
+        return "covered"
+    return "partial"
+
+
+def audit_file(path: str, merge_base: str, prefixes: tuple[str, ...], status: str) -> dict[str, object]:
+    """Classify one changed file and, for vendor edits, check delimiter coverage."""
+    entry: dict[str, object] = {"path": path, "status": status}
+
+    if is_ignored(path):
+        entry["category"] = "ignored"
+        return entry
+
+    if is_custom(path, prefixes):
+        entry["category"] = "custom"
+        return entry
+
+    if status == "D":
+        entry["category"] = "vendor_deleted"
+        return entry
+
+    if status == "A":
+        entry["category"] = "vendor_added"
+        return entry
+
+    style = comment_style(path)
+    if style is None:
+        entry["category"] = "not_delimitable"
+        entry["reason"] = (
+            "JSON does not support comments" if has_known_extension(path) else "unrecognized file type"
+        )
+        return entry
+
+    entry["category"] = "vendor_modified"
+    entry["language"] = style["language"]
+    start_delimiter, end_delimiter = delimiters(style)
+    entry["start_delimiter"] = start_delimiter
+    entry["end_delimiter"] = end_delimiter
+
+    try:
+        with open(path, encoding="utf-8") as handle:
+            lines = handle.read().splitlines()
+    except (OSError, UnicodeDecodeError) as error:
+        entry["category"] = "unreadable"
+        entry["reason"] = str(error)
+        return entry
+
+    diff = run_git("diff", "-U0", merge_base, "--", path)
+    ranges = parse_hunk_ranges(diff)
+    markers = scan_markers(lines)
+    covered: set[int] = markers["covered"]  # type: ignore[assignment]
+    regions = scan_liquid_regions(lines) if path.lower().endswith(".liquid") else []
+
+    hunks: list[dict[str, object]] = []
+    for start, end in ranges:
+        hunk: dict[str, object] = {
+            "start": start,
+            "end": end,
+            "coverage": coverage_for_range(covered, start, end),
+        }
+        region = region_for_range(regions, start, end)
+        if region is not None:
+            hunk["region"] = region["name"]
+            region_extension = region["extension"]
+            if region_extension is None:
+                hunk["delimitable"] = False
+            else:
+                region_style = COMMENT_STYLES[region_extension]
+                assert region_style is not None
+                region_start, region_end = delimiters(region_style)
+                hunk["start_delimiter"] = region_start
+                hunk["end_delimiter"] = region_end
+        hunks.append(hunk)
+
+    entry["hunks"] = hunks
+    entry["blocks"] = markers["blocks"]
+    entry["unclosed_starts"] = markers["unclosed_starts"]
+    entry["unmatched_ends"] = markers["unmatched_ends"]
+    # A hunk in a region that cannot carry comments is never actionable here, so
+    # it does not count as needing delimiters — it has to be documented instead.
+    entry["needs_delimiters"] = any(
+        hunk["coverage"] != "covered" and hunk.get("delimitable") is not False for hunk in hunks
+    )
+    entry["undelimitable_hunks"] = [
+        hunk for hunk in hunks if hunk["coverage"] != "covered" and hunk.get("delimitable") is False
+    ]
+    entry["malformed"] = bool(markers["unclosed_starts"] or markers["unmatched_ends"])
+    return entry
+
+
+def parse_name_status(output: str) -> list[dict[str, str]]:
+    files: list[dict[str, str]] = []
+    for line in output.splitlines():
+        if not line:
+            continue
+        parts = line.split("\t")
+        status = parts[0]
+
+        if status.startswith("R") and len(parts) >= 3:
+            files.append({"status": "M", "path": parts[2], "old_path": parts[1]})
+            continue
+
+        path = parts[1] if len(parts) > 1 else ""
+        files.append({"status": status[0], "path": path, "old_path": ""})
+    return files
+
+
+def build_report(base_ref: str, prefixes: tuple[str, ...], paths: list[str]) -> dict[str, object]:
+    current_branch = run_git("branch", "--show-current")
+    merge_base = run_git("merge-base", base_ref, "HEAD")
+
+    diff_args = ["diff", "--name-status", "--find-renames", merge_base]
+    if paths:
+        diff_args += ["--", *paths]
+    changed = parse_name_status(run_git(*diff_args))
+
+    untracked_args = ["ls-files", "--others", "--exclude-standard"]
+    if paths:
+        untracked_args += ["--", *paths]
+    tracked_paths = {item["path"] for item in changed}
+    for path in run_git(*untracked_args).splitlines():
+        if path and path not in tracked_paths:
+            changed.append({"status": "A", "path": path, "old_path": ""})
+
+    entries = [audit_file(item["path"], merge_base, prefixes, item["status"]) for item in changed]
+
+    return {
+        "current_branch": current_branch,
+        "base_ref": base_ref,
+        "merge_base": merge_base,
+        "custom_prefixes": list(prefixes),
+        "files": entries,
+    }
+
+
+def describe_hunk(hunk: dict[str, object]) -> str:
+    start, end = hunk["start"], hunk["end"]
+    location = f"{start}" if start == end else f"{start}-{end}"
+    if hunk.get("region"):
+        location += f" (inside {hunk['region']})"
+    if hunk.get("delimitable") is False:
+        location += " — cannot be commented"
+    if hunk["coverage"] == "partial":
+        location += " — partially delimited"
+    return location
+
+
+def print_markdown(report: dict[str, object]) -> None:
+    files: list[dict[str, object]] = report["files"]  # type: ignore[assignment]
+    vendor = [entry for entry in files if entry["category"] == "vendor_modified"]
+    needs = [entry for entry in vendor if entry.get("needs_delimiters")]
+    clean = [
+        entry
+        for entry in vendor
+        if not entry.get("needs_delimiters") and not entry.get("undelimitable_hunks")
+    ]
+    malformed = [entry for entry in vendor if entry.get("malformed")]
+    undelimitable = [entry for entry in files if entry["category"] == "not_delimitable"]
+    undelimitable_hunks = [entry for entry in vendor if entry.get("undelimitable_hunks")]
+    added = [entry for entry in files if entry["category"] == "vendor_added"]
+    deleted = [entry for entry in files if entry["category"] == "vendor_deleted"]
+    unreadable = [entry for entry in files if entry["category"] == "unreadable"]
+
+    print("# Vendor Change Audit")
+    print()
+    print(f"- Current branch: `{report['current_branch']}`")
+    print(f"- Base ref: `{report['base_ref']}`")
+    print(f"- Merge base: `{report['merge_base']}`")
+    print(f"- Custom prefixes: {', '.join(f'`{prefix}`' for prefix in report['custom_prefixes'])}")
+    print(f"- Vendor files modified: {len(vendor)} ({len(needs)} needing delimiters)")
+    print()
+
+    if needs:
+        print("## Needs delimiters")
+        print()
+        for entry in needs:
+            print(f"### `{entry['path']}` ({entry['language']})")
+            print()
+            print(f"- Start: `{entry['start_delimiter']}`")
+            print(f"- End: `{entry['end_delimiter']}`")
+            open_hunks = [
+                hunk
+                for hunk in entry["hunks"]  # type: ignore[union-attr]
+                if hunk["coverage"] != "covered" and hunk.get("delimitable") is not False
+            ]
+            for hunk in open_hunks:
+                extra = ""
+                if hunk.get("start_delimiter"):
+                    extra = f" — use `{hunk['start_delimiter']}` / `{hunk['end_delimiter']}`"
+                print(f"- Lines {describe_hunk(hunk)}{extra}")
+            print()
+
+    if clean:
+        print("## Already delimited")
+        print()
+        for entry in clean:
+            count = len(entry["hunks"])  # type: ignore[arg-type]
+            blocks = len(entry["blocks"])  # type: ignore[arg-type]
+            print(f"- `{entry['path']}` — {count} changed hunk(s) inside {blocks} TD CHANGE block(s)")
+        print()
+
+    if malformed:
+        print("## Malformed markers")
+        print()
+        for entry in malformed:
+            for line in entry["unclosed_starts"]:  # type: ignore[union-attr]
+                print(f"- `{entry['path']}:{line}` — TD CHANGE opened without an END TD CHANGE")
+            for line in entry["unmatched_ends"]:  # type: ignore[union-attr]
+                print(f"- `{entry['path']}:{line}` — END TD CHANGE without a matching TD CHANGE")
+        print()
+
+    if undelimitable or undelimitable_hunks:
+        print("## Cannot be delimited")
+        print()
+        print("Delimiters are impossible here. Document these in `docs/changes.md` with reapply steps.")
+        print()
+        for entry in undelimitable:
+            print(f"- `{entry['path']}` — {entry['reason']}")
+        for entry in undelimitable_hunks:
+            for hunk in entry["undelimitable_hunks"]:  # type: ignore[union-attr]
+                location = hunk["start"] if hunk["start"] == hunk["end"] else f"{hunk['start']}-{hunk['end']}"
+                print(f"- `{entry['path']}` lines {location} — inside {hunk['region']}")
+        print()
+
+    if added or deleted:
+        print("## Other vendor-path changes")
+        print()
+        for entry in added:
+            print(f"- `{entry['path']}` — new file without a custom prefix; rename it or justify it")
+        for entry in deleted:
+            print(f"- `{entry['path']}` — vendor file deleted; confirm this is intentional")
+        print()
+
+    if unreadable:
+        print("## Unreadable")
+        print()
+        for entry in unreadable:
+            print(f"- `{entry['path']}` — {entry['reason']}")
+        print()
+
+    if not vendor and not undelimitable and not added and not deleted:
+        print("No vendor files changed on this branch.")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Audit vendor file changes on this branch for TD CHANGE delimiter coverage."
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        help="Optional path filters. Defaults to every changed file on the branch.",
+    )
+    parser.add_argument(
+        "--base",
+        help="Explicit base ref to compare against. Defaults to main/origin-main or master/origin-master fallback.",
+    )
+    parser.add_argument(
+        "--custom-prefix",
+        action="append",
+        default=None,
+        help="Filename substring marking a file as custom rather than vendor. Repeatable. Defaults to `td-`.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("markdown", "json"),
+        default="markdown",
+        help="Output format.",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Exit 1 when any vendor change is missing delimiters.",
+    )
+    args = parser.parse_args()
+
+    prefixes = tuple(args.custom_prefix or ["td-"])
+    base_ref = resolve_base_ref(args.base)
+    report = build_report(base_ref, prefixes, args.paths)
+
+    if args.format == "json":
+        print(json.dumps(report, indent=2))
+    else:
+        print_markdown(report)
+
+    if args.strict:
+        files: list[dict[str, object]] = report["files"]  # type: ignore[assignment]
+        if any(entry.get("needs_delimiters") or entry.get("malformed") for entry in files):
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except subprocess.CalledProcessError as error:
+        sys.stderr.write(error.stderr or str(error))
+        raise SystemExit(error.returncode)

package/skills/record-changes/SKILL.md

@@ -1,76 +0,0 @@
----
-name: record-changes
-version: 1.0.0
-description: Update `docs/changes.md` by summarizing the current branch against the primary development branch. Use when a developer asks to record branch changes, document theme customizations, refresh the project change log, or write a branch summary into `docs/changes.md`. Prefer comparing against `main`, but fall back to `origin/main`, `master`, or `origin/master` when the repository does not have a local `main` branch.
----
-
-# Record Changes
-
-Update `docs/changes.md` from the current branch diff. Preserve the existing document structure and add a concise, human-readable entry for the branch.
-
-## Workflow
-
-### 1. Collect Branch Context
-
-Run the bundled script first:
-
-```bash
-python3 .agents/skills/record-changes/scripts/branch_diff_context.py
-```
-
-If the developer specifies another comparison branch, pass it explicitly:
-
-```bash
-python3 .agents/skills/record-changes/scripts/branch_diff_context.py --base release/x.y
-```
-
-Read the existing `docs/changes.md` before editing so the new entry matches the current ordering, tone, and section layout.
-
-### 2. Inspect the Actual Code Changes
-
-Use the script output to identify changed files, then inspect the relevant diffs and file contents with `git diff` and targeted file reads.
-
-Prioritize:
-
-- User-facing behavior changes
-- CMS setting/schema changes
-- CSS or markup changes that affect rendering
-- Renamed files and vendor-theme hotspots
-
-Do not summarize the `docs/changes.md` edit itself as part of the branch work. If the branch contains unrelated skill or tooling files, either omit them from the changelog entry or separate them clearly when they are relevant to the project's maintenance history.
-
-### 3. Write the Changelog Entry
-
-Add a new entry near the top of `docs/changes.md`, directly under the intro, unless the file already uses another ordering convention.
-
-Follow the existing pattern:
-
-- `## <short title>`
-- `**Date:** YYYY-MM-DD`
-- `### Purpose`
-- `### Files changed`
-- `### Upgrade impact`
-- `### Notes`
-
-Guidelines:
-
-- Make the title describe the feature or fix, not the branch name.
-- Write `Purpose` in plain language with outcome-focused bullets.
-- Use the `Files changed` table to explain why each file matters.
-- Call out non-`td-` theme or vendor files in a separate subsection when in a Shopify project.
-- Mention renamed files explicitly.
-- Keep `Upgrade impact` brief and concrete.
-- Use `Notes` for implementation details, edge cases, or assumptions.
-
-### 4. Verify Before Finishing
-
-Before wrapping up:
-
-- Re-read the new markdown entry in context.
-- Confirm every listed file appears in the diff.
-- Confirm the documented behavior matches the code, not just the branch name.
-- Mention any uncertainty if the diff is too broad to summarize with high confidence.
-
-## Resource
-
-- `scripts/branch_diff_context.py`: Resolve the best available base branch and print a branch summary with file statuses and line counts.

package/skills/record-changes/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-    display_name: 'Record Changes'
-    short_description: 'Summarize branch changes into docs/changes.md'
-    default_prompt: 'Use $record-changes to compare this branch to main and update docs/changes.md.'