[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M756YR7F1920CGK9CCKHEX63":3,"skill-same:01M756YR7F1920CGK9CCKHEX63":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":30,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":32,"install":33,"resources":46},"01M756YR7F1920CGK9CCKHEX63","release-lanorme",null,"Use when cutting, shipping, releasing, or publishing a new LaNorme version (a \"0.x.y\" bump, a tag, a PyPI release). Runs every release gate (unit tests, the dogfood, generated docs in sync), records a eval audit (precision\u002Frecall\u002FF1 per scored rule plus end-to-end performance, stamped with the version and hardware) to evals\u002Fresults\u002F, bumps the version, tags, and creates the GitHub Release that auto-publishes to PyPI and deploys the versioned docs.","lanorme\u002Flanorme","lanorme","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F289880483?v=4","01M756YE5P1Y6R0SE0SHBC7ZPF","01M756YE6QHCA3SRDKNSHVPSYF",3,"MIT","https:\u002F\u002Fgithub.com\u002Flanorme\u002Flanorme\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frelease-lanorme\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: release-lanorme\ndescription: Use when cutting, shipping, releasing, or publishing a new LaNorme version (a \"0.x.y\" bump, a tag, a PyPI release). Runs every release gate (unit tests, the dogfood, generated docs in sync), records a eval audit (precision\u002Frecall\u002FF1 per scored rule plus end-to-end performance, stamped with the version and hardware) to evals\u002Fresults\u002F, bumps the version, tags, and creates the GitHub Release that auto-publishes to PyPI and deploys the versioned docs.\nlicense: MIT\ncompatibility: Requires Python 3.13+, uv, git, and gh, run from a clean main checkout.\nmetadata:\n  project: lanorme\n---\n\n# Release LaNorme\n\nThis page explains how to cut a release and the discipline every release runs:\nthe gates, a recorded eval audit, regenerated docs, and the automated\npublish. Creating a GitHub Release fires `.github\u002Fworkflows\u002Frelease.yml` (builds\nand publishes to PyPI through Trusted Publishing, OIDC, no token handled) and\n`.github\u002Fworkflows\u002Fdocs.yml` (deploys that version's docs with mike). `uv\npublish` is never run by hand.\n\n## The release discipline\n\nEvery release records the same evidence so a green tag is auditable later:\n\n1. **Tests and dogfood** pass (`pytest tests\u002Funit`, `lanorme check .`).\n2. **Generated docs are in sync** with the tool (`scripts\u002Fgen_docs.py --check`):\n   the configuration reference, JSON schema, rule index, and llms files.\n3. **A eval audit is recorded** to `evals\u002Fresults\u002FvX.Y.Z.json`: the\n   accuracy metrics (precision, recall, F1 per scored rule against the labelled\n   corpora, for the dev split, the sealed holdout split and the gap between\n   them) and the end-to-end performance numbers, each stamped with the\n   LaNorme version, the git commit, the Python version, and the hardware\n   (platform and processor). Accuracy is deterministic and is the audit's\n   backbone; performance is informative and machine-dependent (the hardware\n   stamp is what makes it interpretable).\n4. **No holdout regression.** The audit runs with `--gate latest`: it fails\n   when any rule's holdout precision or recall falls more than 0.02 below the\n   best value any comparable committed `evals\u002Fresults\u002Fv*.json` recorded (one\n   that scored the same holdout files), not merely the latest, and lists the\n   rules. It also fails when a holdout file the newest recorded audit digested\n   was removed or changed, unless `evals\u002Fholdout_revisions.json` accepts that\n   exact new digest with a reason. Dev numbers are informational and never\n   block.\n5. **RULES.md reflects the measured F1** for every rule that has a corpus. If a\n   rule's F1 moved, update its line before tagging.\n\n`scripts\u002Frelease.sh` enforces steps 1 to 4 (it refuses to tag if any gate fails\nor the docs are stale); step 5 is a human check on the audit output.\n\n## Versioning\n\nThe public surface is the rule codes used in `select` \u002F `ignore` \u002F\n`per-file-ignores` and the config keys under `[tool.lanorme]`. The deciding\nquestion is whether a green codebase could go red on upgrade:\n\n- patch (`0.y.z`): no existing codebase's result changes (fixes, docs, opt-in\n  checks, new config keys with safe defaults).\n- minor (`0.y.0`): a green codebase can newly fail (a new default-on check, a\n  default-on rule made stricter, a renamed or removed rule code, a changed\n  default). Before 1.0, every breaking change is a minor.\n- major (`1.0.0`): the stability commitment.\n\nThe README \"Versioning\" section is canonical; keep them in step.\n\n## Steps\n\n1. Pick the new version `X.Y.Z`.\n2. Add a `## [X.Y.Z]` section to `CHANGELOG.md` describing the user-facing\n   changes. Required: the release notes are taken verbatim from it.\n3. Regenerate the docs and review the audit numbers:\n\n   ```\n   uv run python scripts\u002Fgen_docs.py\n   uv run python evals\u002Faudit.py --version X.Y.Z --output \u002Ftmp\u002Fpreview.json --gate latest\n   ```\n\n   Read the preview; if any F1 changed, update that rule's line in\n   `docs\u002FRULES.md`. A holdout regression fails the preview and the release: fix\n   the rule, never the holdout files (see `CONTRIBUTING.md`). Commit the regenerated docs and any RULES.md change. Do not\n   commit the audit file yourself: `release.sh` records the committed\n   `evals\u002Fresults\u002FvX.Y.Z.json` for you, against the release commit (step 4), so\n   its version and commit stamp match the released tree.\n4. From the repo root, run the helper:\n\n   ```\n   scripts\u002Frelease.sh X.Y.Z\n   ```\n\n   It refuses unless you are on `main`, the CHANGELOG section exists, the docs\n   are in sync, and the gates pass (including an eval-audit precheck that the\n   corpora are complete and not stale and that no holdout number regressed). Then it bumps the version in `pyproject.toml` and\n   `src\u002Flanorme\u002F__init__.py`, builds, runs `twine check`, commits the release,\n   records the eval audit against that commit (a second `Record X.Y.Z eval\n   audit` commit), tags `vX.Y.Z`, pushes, and creates the GitHub Release.\n5. Watch the publish and docs workflows, then verify the package is live:\n\n   ```\n   gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId') --exit-status\n   uvx --refresh --from lanorme==X.Y.Z lanorme --version\n   ```\n\n   The docs workflow publishes `X.Y.Z` (and moves the `latest` alias) at\n   https:\u002F\u002Flanorme.github.io\u002Flanorme\u002F.\n\n## Gotchas\n\n- `scripts\u002Frelease.sh` refuses to do anything unless you are on `main`, the\n  working tree is clean, the `## [X.Y.Z]` CHANGELOG section exists, and the\n  gates pass. It is safe to run; it tags nothing until every gate is green.\n- The version lives in **two** files (`pyproject.toml` and\n  `src\u002Flanorme\u002F__init__.py`); `release.sh` bumps both. The manual fallback must\n  too, or the build and `lanorme --version` disagree.\n- `uv publish` is never run by hand. PyPI publishing is OIDC Trusted Publishing,\n  fired only by the GitHub Release.\n- The eval audit's accuracy step is strict: if a scorer sees a finding that\n  is not in its corpus `labels.json`, or `validate_corpora.py` finds an\n  unlabelled file or comment, a label whose line hash is missing or no longer\n  matches its line, a label of the wrong polarity for its directory, or a\n  file off its recorded split, it errors rather than scoring a wrong number.\n  That means a fixture went stale, not that the release is blocked on\n  performance; fix the labels. The split is recorded per file in\n  `labels.json` (the name hash only proposes one for a new file), and\n  `uv run python evals\u002Fvalidate_corpora.py --stamp` fills a missing split or\n  line hash.\n- The holdout gate holds each rule to the best comparable release over the\n  whole history of `evals\u002Fresults\u002Fv*.json`, not the newest alone. A rule no\n  comparable audit has holdout numbers for is skipped, not failed, and the\n  gate prints a note when it gated nothing, so the first release after a\n  corpus gains a holdout split records the baseline the next one is held to.\n- Performance numbers are machine-dependent. The audit stamps the hardware so\n  they are interpretable, but do not compare them across machines.\n\n## If something fails\n\n- A gate (tests, dogfood, stale docs) fails: nothing is committed or tagged. Fix\n  and re-run.\n- The eval audit's accuracy step fails (a scorer flags an unlabelled\n  finding): the corpus is out of date. Fix the labels or the fixture, re-run.\n- The holdout gate fails: a change since the last release made a rule worse on\n  data it was not tuned on, or a holdout file changed. Fix or revert the rule\n  change; do not edit the holdout files to pass. A holdout edit that is right\n  on its own merits (a label proved wrong) goes in its own reviewed change with\n  an `evals\u002Fholdout_revisions.json` entry naming the new digest and the reason.\n- The publish workflow fails (for example a PyPI outage): the tag and release\n  already exist, so do not re-tag. Re-run with `gh run rerun \u003Cid>` or\n  `gh workflow run release.yml`.\n\n## Manual fallback (no script)\n\nEdit `CHANGELOG.md`, run `uv run python scripts\u002Fgen_docs.py`, `uv run --group\ndev pytest tests\u002Funit`, and `uv run lanorme check .`. Bump `version` in\n`pyproject.toml` and `__version__` in `src\u002Flanorme\u002F__init__.py`, then `uv\nbuild`, `git commit -m \"Release X.Y.Z\"`. Now record the audit against that\ncommit: `uv run python evals\u002Faudit.py --version X.Y.Z --gate latest` and `git commit -m\n\"Record X.Y.Z eval audit\" evals\u002Fresults\u002F`. Finally `git tag -a vX.Y.Z`, `git\npush origin main`, `git push origin vX.Y.Z`, and `gh release create vX.Y.Z\ndist\u002F* --notes \"...\"`.\n","# Release LaNorme\n\nThis page explains how to cut a release and the discipline every release runs:\nthe gates, a recorded eval audit, regenerated docs, and the automated\npublish. Creating a GitHub Release fires `.github\u002Fworkflows\u002Frelease.yml` (builds\nand publishes to PyPI through Trusted Publishing, OIDC, no token handled) and\n`.github\u002Fworkflows\u002Fdocs.yml` (deploys that version's docs with mike). `uv\npublish` is never run by hand.\n\n## The release discipline\n\nEvery release records the same evidence so a green tag is auditable later:\n\n1. **Tests and dogfood** pass (`pytest tests\u002Funit`, `lanorme check .`).\n2. **Generated docs are in sync** with the tool (`scripts\u002Fgen_docs.py --check`):\n   the configuration reference, JSON schema, rule index, and llms files.\n3. **A eval audit is recorded** to `evals\u002Fresults\u002FvX.Y.Z.json`: the\n   accuracy metrics (precision, recall, F1 per scored rule against the labelled\n   corpora, for the dev split, the sealed holdout split and the gap between\n   them) and the end-to-end performance numbers, each stamped with the\n   LaNorme version, the git commit, the Python version, and the hardware\n   (platform and processor). Accuracy is deterministic and is the audit's\n   backbone; performance is informative and machine-dependent (the hardware\n   stamp is what makes it interpretable).\n4. **No holdout regression.** The audit runs with `--gate latest`: it fails\n   when any rule's holdout precision or recall falls more than 0.02 below the\n   best value any comparable committed `evals\u002Fresults\u002Fv*.json` recorded (one\n   that scored the same holdout files), not merely the latest, and lists the\n   rules. It also fails when a holdout file the newest recorded audit digested\n   was removed or changed, unless `evals\u002Fholdout_revisions.json` accepts that\n   exact new digest with a reason. Dev numbers are informational and never\n   block.\n5. **RULES.md reflects the measured F1** for every rule that has a corpus. If a\n   rule's F1 moved, update its line before tagging.\n\n`scripts\u002Frelease.sh` enforces steps 1 to 4 (it refuses to tag if any gate fails\nor the docs are stale); step 5 is a human check on the audit output.\n\n## Versioning\n\nThe public surface is the rule codes used in `select` \u002F `ignore` \u002F\n`per-file-ignores` and the config keys under `[tool.lanorme]`. The deciding\nquestion is whether a green codebase could go red on upgrade:\n\n- patch (`0.y.z`): no existing codebase's result changes (fixes, docs, opt-in\n  checks, new config keys with safe defaults).\n- minor (`0.y.0`): a green codebase can newly fail (a new default-on check, a\n  default-on rule made stricter, a renamed or removed rule code, a changed\n  default). Before 1.0, every breaking change is a minor.\n- major (`1.0.0`): the stability commitment.\n\nThe README \"Versioning\" section is canonical; keep them in step.\n\n## Steps\n\n1. Pick the new version `X.Y.Z`.\n2. Add a `## [X.Y.Z]` section to `CHANGELOG.md` describing the user-facing\n   changes. Required: the release notes are taken verbatim from it.\n3. Regenerate the docs and review the audit numbers:\n\n   ```\n   uv run python scripts\u002Fgen_docs.py\n   uv run python evals\u002Faudit.py --version X.Y.Z --output \u002Ftmp\u002Fpreview.json --gate latest\n   ```\n\n   Read the preview; if any F1 changed, update that rule's line in\n   `docs\u002FRULES.md`. A holdout regression fails the preview and the release: fix\n   the rule, never the holdout files (see `CONTRIBUTING.md`). Commit the regenerated docs and any RULES.md change. Do not\n   commit the audit file yourself: `release.sh` records the committed\n   `evals\u002Fresults\u002FvX.Y.Z.json` for you, against the release commit (step 4), so\n   its version and commit stamp match the released tree.\n4. From the repo root, run the helper:\n\n   ```\n   scripts\u002Frelease.sh X.Y.Z\n   ```\n\n   It refuses unless you are on `main`, the CHANGELOG section exists, the docs\n   are in sync, and the gates pass (including an eval-audit precheck that the\n   corpora are complete and not stale and that no holdout number regressed). Then it bumps the version in `pyproject.toml` and\n   `src\u002Flanorme\u002F__init__.py`, builds, runs `twine check`, commits the release,\n   records the eval audit against that commit (a second `Record X.Y.Z eval\n   audit` commit), tags `vX.Y.Z`, pushes, and creates the GitHub Release.\n5. Watch the publish and docs workflows, then verify the package is live:\n\n   ```\n   gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId') --exit-status\n   uvx --refresh --from lanorme==X.Y.Z lanorme --version\n   ```\n\n   The docs workflow publishes `X.Y.Z` (and moves the `latest` alias) at\n   https:\u002F\u002Flanorme.github.io\u002Flanorme\u002F.\n\n## Gotchas\n\n- `scripts\u002Frelease.sh` refuses to do anything unless you are on `main`, the\n  working tree is clean, the `## [X.Y.Z]` CHANGELOG section exists, and the\n  gates pass. It is safe to run; it tags nothing until every gate is green.\n- The version lives in **two** files (`pyproject.toml` and\n  `src\u002Flanorme\u002F__init__.py`); `release.sh` bumps both. The manual fallback must\n  too, or the build and `lanorme --version` disagree.\n- `uv publish` is never run by hand. PyPI publishing is OIDC Trusted Publishing,\n  fired only by the GitHub Release.\n- The eval audit's accuracy step is strict: if a scorer sees a finding that\n  is not in its corpus `labels.json`, or `validate_corpora.py` finds an\n  unlabelled file or comment, a label whose line hash is missing or no longer\n  matches its line, a label of the wrong polarity for its directory, or a\n  file off its recorded split, it errors rather than scoring a wrong number.\n  That means a fixture went stale, not that the release is blocked on\n  performance; fix the labels. The split is recorded per file in\n  `labels.json` (the name hash only proposes one for a new file), and\n  `uv run python evals\u002Fvalidate_corpora.py --stamp` fills a missing split or\n  line hash.\n- The holdout gate holds each rule to the best comparable release over the\n  whole history of `evals\u002Fresults\u002Fv*.json`, not the newest alone. A rule no\n  comparable audit has holdout numbers for is skipped, not failed, and the\n  gate prints a note when it gated nothing, so the first release after a\n  corpus gains a holdout split records the baseline the next one is held to.\n- Performance numbers are machine-dependent. The audit stamps the hardware so\n  they are interpretable, but do not compare them across machines.\n\n## If something fails\n\n- A gate (tests, dogfood, stale docs) fails: nothing is committed or tagged. Fix\n  and re-run.\n- The eval audit's accuracy step fails (a scorer flags an unlabelled\n  finding): the corpus is out of date. Fix the labels or the fixture, re-run.\n- The holdout gate fails: a change since the last release made a rule worse on\n  data it was not tuned on, or a holdout file changed. Fix or revert the rule\n  change; do not edit the holdout files to pass. A holdout edit that is right\n  on its own merits (a label proved wrong) goes in its own reviewed change with\n  an `evals\u002Fholdout_revisions.json` entry naming the new digest and the reason.\n- The publish workflow fails (for example a PyPI outage): the tag and release\n  already exist, so do not re-tag. Re-run with `gh run rerun \u003Cid>` or\n  `gh workflow run release.yml`.\n\n## Manual fallback (no script)\n\nEdit `CHANGELOG.md`, run `uv run python scripts\u002Fgen_docs.py`, `uv run --group\ndev pytest tests\u002Funit`, and `uv run lanorme check .`. Bump `version` in\n`pyproject.toml` and `__version__` in `src\u002Flanorme\u002F__init__.py`, then `uv\nbuild`, `git commit -m \"Release X.Y.Z\"`. Now record the audit against that\ncommit: `uv run python evals\u002Faudit.py --version X.Y.Z --gate latest` and `git commit -m\n\"Record X.Y.Z eval audit\" evals\u002Fresults\u002F`. Finally `git tag -a vX.Y.Z`, `git\npush origin main`, `git push origin vX.Y.Z`, and `gh release create vX.Y.Z\ndist\u002F* --notes \"...\"`.\n",{"name":5,"license":14,"metadata":23,"description":7,"compatibility":24},{"project":9},"Requires Python 3.13+, uv, git, and gh, run from a clean main checkout.","main","49cf2b150731b9b2f20c63a00f55911ec76efd07",".claude\u002Fskills\u002Frelease-lanorme",6,"https:\u002F\u002Fgithub.com\u002Flanorme\u002Flanorme","https:\u002F\u002Flanorme.github.io\u002Flanorme\u002F","https:\u002F\u002Fgithub.com\u002Flanorme","2026-11-14 08:19:23",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add lanorme\u002Flanorme --skill release-lanorme",{"tool":39,"command":40},"bunx","bunx skills add lanorme\u002Flanorme --skill release-lanorme",{"tool":42,"command":43},"pnpm","pnpm dlx skills add lanorme\u002Flanorme --skill release-lanorme","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flanorme\u002Flanorme\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frelease-lanorme\u002FSKILL.md",true,[],[48,55,62,69,75,81],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":18},"01M756ZM21V76B0ZBFZAY82KF1","valid-minimal","A minimal valid skill used as a parser fixture.","https:\u002F\u002Fgithub.com\u002Flanorme\u002Flanorme\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fvalid-minimal\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":18},"01M756ZHMJ94FRJ1JG09KY46DN","valid-links","A valid skill that links to a bundled reference file.","https:\u002F\u002Fgithub.com\u002Flanorme\u002Flanorme\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fvalid-links\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":18},"01M756ZE4AK413FAJFMNGFA9CZ","valid-folded","A valid skill whose description is a folded block scalar spanning multiple lines, to make sure the parser does not call it empty.","https:\u002F\u002Fgithub.com\u002Flanorme\u002Flanorme\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fvalid-folded\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":18},"01M756ZCXB36P5G924X31E7Y0T","unterminated","https:\u002F\u002Fgithub.com\u002Flanorme\u002Flanorme\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Funterminated\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":18},"01M756ZBMET5CDBKZB1XQRNA0J","missing-desc","https:\u002F\u002Fgithub.com\u002Flanorme\u002Flanorme\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fmissing-desc\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M756ZA64EC9QA4KCY33GQB7E","invalid-no-frontmatter","https:\u002F\u002Fgithub.com\u002Flanorme\u002Flanorme\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Finvalid-no-frontmatter\u002FSKILL.md",[],[]]