[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C52Q9W0J442RN80AEYVEH6":3,"skill-same:01M6C52Q9W0J442RN80AEYVEH6":70},{"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":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":46,"repositoryHtmlUrl":47,"repositoryHomepageUrl":6,"ownerHtmlUrl":48,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":49,"install":50,"resources":63},"01M6C52Q9W0J442RN80AEYVEH6","releasing-apss",null,"Use when cutting, gating, tagging, or publishing a release of this APSS repo, or when explaining how releases work here. Trigger phrases: \"cut a release\", \"release APSS\", \"publish to crates.io\", \"create a release PR\", \"main to release\", \"promote main to release\", \"bump versions for the release\", \"tag a release\", \"run the release gate\", \"how do releases work here\", \"what gets published\", \"ship a new version\", \"publish a new crate for the first time\", \"403 Forbidden publishing to crates.io\", \"this token does not have the required permissions\", \"CARGO_REGISTRY_TOKEN\", \"publish-new scope\", \"the publish job failed\", \"half the crates published\". Covers the trunk-based main -> release branch flow, the Release Gate checks (source-branch, version-bump, changelog, QA, APS validation, security), release-create.yml tagging plus tiered crates.io publishing, and the one-time manual first publish a NEW crate name requires because the CI token is deliberately scoped publish-update only. Do NOT use for routine feature PRs into main (those need no release and no version bump), mid-feature version bumps, authoring standards, or consumer-side `apss install` (see the adopt\u002Fvisualize runbooks).","AgentParadise\u002Fagent-paradise-standards-system","AgentParadise","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F242330113?v=4","01M6C52MXXSE01NH5GKMC3N7JA","01M6C52N1MFCAYTGQ441SS13E8",3,"MIT","https:\u002F\u002Fgithub.com\u002FAgentParadise\u002Fagent-paradise-standards-system\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Freleasing-apss\u002FSKILL.md",[],[18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"releasing apss","first","publishing","only","version","use","repo","branch","work","how","visualize","publish","ci","promote","changelog","qa","permissions","run","create","pr","2026-11-10 10:12:30",false,"---\nname: releasing-apss\ndescription: >-\n  Use when cutting, gating, tagging, or publishing a release of this APSS repo,\n  or when explaining how releases work here. Trigger phrases: \"cut a release\",\n  \"release APSS\", \"publish to crates.io\", \"create a release PR\", \"main to\n  release\", \"promote main to release\", \"bump versions for the release\", \"tag a\n  release\", \"run the release gate\", \"how do releases work here\", \"what gets\n  published\", \"ship a new version\", \"publish a new crate for the first time\",\n  \"403 Forbidden publishing to crates.io\", \"this token does not have the\n  required permissions\", \"CARGO_REGISTRY_TOKEN\", \"publish-new scope\", \"the\n  publish job failed\", \"half the crates published\". Covers the trunk-based\n  main -> release branch flow, the Release Gate checks (source-branch,\n  version-bump, changelog, QA, APS validation, security), release-create.yml\n  tagging plus tiered crates.io publishing, and the one-time manual first\n  publish a NEW crate name requires because the CI token is deliberately scoped\n  publish-update only. Do NOT use for routine feature PRs into main (those need\n  no release and no version bump), mid-feature version bumps, authoring\n  standards, or consumer-side `apss install` (see the adopt\u002Fvisualize runbooks).\n---\n\n# Releasing APSS\n\n## Overview\n\nAPSS uses trunk-based development with a single `release` branch. Feature work\nmerges into `main` freely, with no version-bump pressure. A release is a\n`main -> release` pull request that the **Release Gate** validates; merging that\nPR into `release` triggers `release-create.yml`, which creates git tags, a\nGitHub Release, and (once configured) publishes crates to crates.io.\n\nThe single most load-bearing idea: **version bumps are enforced once, at the\nrelease gate, against the previous release. They are not required on merges to\nmain.** That is deliberate. Per-merge bump enforcement causes version churn and\nmerge conflicts on the version files when several PRs land between releases.\nBumping at release time lets changes accumulate on main and get versioned once.\n\n## The release model\n\n```\nfeature branch --PR--> main  (ci.yml: fmt, clippy, check, test, aps-validation)\n                        |        no version-bump pressure here\n                        |\n                  main --PR--> release   (release-gate.yml: the hard gate)\n                                  |\n                          merge into release\n                                  |\n                        release-create.yml: tags + GitHub Release + crates.io\n```\n\n- **`main` is the trunk.** `ci.yml` runs on every push\u002FPR to main and does NOT\n  run the version-bump check. Merge features here without bumping.\n- **`release` is the only branch releases come from.** A release PR's head must\n  be `main` (the `source-branch-check` rejects anything else), so any version\n  bumps must already be on `main` before you open the release PR.\n- **Tags are per-unit.** The system tag is `v\u003Cworkspace-version>`; each changed\n  standard\u002Fsubstandard gets its own tag (for example `APS-V1-0001-v0.2.1`,\n  `APS-V1-0000.CF01-v1.0.1`).\n\n## Inputs and preconditions\n\n- Changes already merged to `main` that you want to release.\n- The `release` branch exists on origin, and `CARGO_REGISTRY_TOKEN` plus the\n  `release-publish` environment are already configured (see Operational\n  state for the gotchas learned bootstrapping this).\n\n## Workflow: cutting a release\n\n1. **Find what changed since the last release.** The gate diffs the release PR\n   against the release base (the `release` branch tip, which equals the last\n   release). Compute the same set locally:\n   `git diff --name-only origin\u002Frelease..main`. A package needs a bump if it has\n   any changed file outside its `docs\u002F` directory.\n\n2. **Bump versions on main.** For each changed standard\u002Fsubstandard, bump the\n   `version` in its `standard.toml` \u002F `substandard.toml` AND the matching\n   `Cargo.toml`. If any system crate (`apss-core`, `aps-cli`, `apss-bootstrap`)\n   changed, bump the `[workspace.package] version` in the root `Cargo.toml`. Any\n   semver level satisfies the gate; there is no level enforcement, so patch is\n   fine for backwards-compatible changes. Land these via a normal PR into main.\n\n3. **Open the release PR: `main` -> `release`.** The PR body MUST contain a\n   `## Changelog` (or `## Release Notes` \u002F `## What Changed` \u002F `## Changes`)\n   section; `changelog-check` fails without it, and `release-create` extracts\n   that section into the GitHub Release notes.\n\n4. **Let the Release Gate run and pass.** It runs source-branch-check,\n   version-bump-check, changelog-check, full QA (fmt, clippy `-D warnings`,\n   check, test, release build), APS validation (`v1 validate repo` +\n   `distribution` + self-validation\u002Fbackwards-compat\u002FCF01\u002FDI01 tests),\n   cargo-audit, and dependency-review. The `release-gate-success` job aggregates\n   them and is the required status check.\n\n5. **Merge into `release`.** This fires `release-create.yml`, which tags every\n   changed unit, pushes tags, creates the GitHub Release from the changelog, and\n   runs the publish job.\n\n6. **Verify the publish against crates.io, not against the job's exit status.**\n   The publish job tolerates an already-published version, so a re-run after a\n   partial publish resumes rather than dying. That was NOT true before\n   2026-08-07: the job pre-checked with `cargo search`, whose eventually\n   consistent search endpoint kept reporting a just-published crate as missing,\n   making every re-run fail on the first crate that had already gone out. If you\n   are working on a release whose workflow predates that fix, expect re-runs to\n   fail and publish the remainder by hand (see the new-crate section below).\n\n   Check the actual registry rather than trusting a green job:\n\n   ```bash\n   for c in apss-core apss \u003Cchanged-standard-crates>; do\n     curl -s \"https:\u002F\u002Fcrates.io\u002Fapi\u002Fv1\u002Fcrates\u002F$c\" | jq -r '\"\\(.crate.name) \\(.crate.max_version)\"'\n   done\n   ```\n\n## What publishes and what does not\n\n`release-create.yml` publishes in dependency-tier order, only for changed units:\n\n- **Tier 1:** `apss-core` (only when a system crate changed).\n- **Tier 2\u002F3:** changed **official** standard crates under\n  `standards\u002Fv1\u002FAPS-V1-XXXX-\u003Cslug>` where `XXXX != 0000`, in dependency order.\n- **Last:** `apss` (the bootstrap binary).\n\n**Never published:** the meta-standard (`APS-V1-0000`) and its internal\nsubstandards, and everything under `standards-experimental\u002F`. These still get\ngit tags and release notes, but no `cargo publish`. Treat that exclusion as\nload-bearing: the publish job filters them out by directory prefix.\n\n## Releasing a crate that has NEVER been published\n\n**The first release of any new crate name needs a one-time manual `cargo\npublish`. CI cannot do it, by design.**\n\n`CARGO_REGISTRY_TOKEN` is deliberately scoped `publish-update` on crates `apss`\nand `apss-*`. It can push new *versions* of crates the project already owns, and\nnothing else. It cannot create a new crate name, because a CI token that could\nwould let anyone who leaked it squat or publish arbitrary `apss-*` packages. The\nnarrower scope is the security posture, not an oversight: do not \"fix\" this by\nadding `publish-new` to the CI token.\n\nThe symptom, if you forget: the publish job runs, tier 1 succeeds, and the new\ncrate fails with\n\n```\nerror: failed to publish \u003Ccrate> to registry at https:\u002F\u002Fcrates.io\nCaused by:\n  the remote server responded with an error (status 403 Forbidden):\n  this token does not have the required permissions to perform this action\n```\n\nThat message names the token, not the crate, so it is easy to misread as a\nworkflow bug. It is not. The workflow handles new packages correctly: detection\nis a `git diff` against the last release tag (a directory that did not exist\nreads as changed), the crate name is derived from the directory name rather than\nfrom history, and the publish attempt is made unconditionally, so a crate that\nhas never been published is never skipped.\n\n### The flow\n\n1. Let the release merge as normal. Tags and the GitHub Release are created, and\n   the publish job fails at the new crate. **This is expected and recoverable.**\n   Anything published before the failure (typically `apss-core`) stays published.\n2. Publish the new crate by hand, **from the release tag**, using a personal\n   credential that has `publish-new`. Publishing from a working tree instead of\n   the tag would put bytes on crates.io that do not match what the tag claims:\n\n   ```bash\n   git checkout \u003CTAG>              # e.g. APS-V1-0004-v1.0.0\n   cargo publish -p \u003Ccrate-name>\n   ```\n\n   Run `cargo publish --dry-run -p \u003Ccrate-name>` first. It packages the crate and\n   compiles it from the packaged tarball, which catches the real risk: files\n   pulled in by `include_str!` from outside `src\u002F` are only present if they sit\n   inside the crate directory.\n3. Finish the remaining tiers. The publish job now tolerates already-published\n   versions, so re-running it resumes from where it died and tier 3 (`apss`)\n   goes out automatically. No need to re-tag or re-release.\n\n   **If the re-run still fails on a crate that is already published**, the run\n   is using a workflow from before the 2026-08-07 fix (a re-run executes the\n   workflow file from the commit that triggered it, so fixing it on `main` does\n   not help an in-flight run). Do not fight it. Publish the remaining crates by\n   hand from their tags, exactly as in step 2:\n\n   ```bash\n   git checkout v\u003Csystem-version>     # e.g. v1.5.0\n   cargo publish -p apss\n   ```\n\n   The red job is then cosmetic. What matters is the registry.\n4. Every subsequent release of that crate is fully automated: `publish-update`\n   covers it from then on. `publish-new` is needed once per crate name, not once\n   per release.\n\n### Consider Trusted Publishing afterward\n\ncrates.io supports GitHub Actions OIDC, which removes the long-lived token from\nCI entirely. It has the same chicken-and-egg (trust cannot be configured for a\ncrate that does not exist yet), so it is a follow-up to step 2 rather than a\nreplacement for it. Worth doing if the shared token's blast radius matters.\n\n## Operational state (as of 2026-07-10)\n\nThe pipeline is now **live and proven end to end**: the `release` branch\nexists, `CARGO_REGISTRY_TOKEN` and the `release-publish` environment (required\nreviewer: repo owner) are configured, and the first real release\n(`v1.2.0`, PR #102) went through the gate clean and published all five\npublishable crates to crates.io successfully. Treat the workflow-level\ndescription above as trustworthy; this section now tracks known gotchas\ninstead of \"not wired yet\" caveats.\n\n- **What v1.5.0 actually cost (2026-08-07), as a worked example.** The release\n  that first published `apss-v1-0004-session-capture` needed three manual\n  interventions, and every one of them is now covered above. The publish job\n  403'd on the new crate (CI token is `publish-update` only, by design). The\n  operator's local token turned out to be dead, a *different* 403 reading\n  `authentication failed` rather than `does not have the required permissions`\n  (read that message carefully; the two mean different things). And both re-runs\n  then died on `apss-core@1.5.0 already exists`, because the old `cargo search`\n  pre-check never saw it. Final state was reached by publishing two of the three\n  crates by hand from their tags. The git tags and GitHub Release were correct\n  throughout; only the publish job was red. **Verify against crates.io, not\n  against the job.**\n- **Never push directly to `release`.** It is a real branch with a real\n  `push` trigger: any push, including a one-off debugging fix, fires\n  `release-create.yml` for real (tags + a GitHub Release get created\n  immediately, no gate). This happened by accident while bootstrapping the\n  pipeline; the `release-publish` approval gate is what prevented an\n  accidental crates.io publish, but the stray tags and a garbage GitHub\n  Release still had to be deleted by hand. Always land changes to `release`\n  through a gated `main -> release` PR, never `git push origin ...:release`.\n- **Local reusable workflows cannot live in a subdirectory of\n  `.github\u002Fworkflows\u002F`.** `uses: .\u002F.github\u002Fworkflows\u002Fchecks\u002Ffoo.yml` is\n  silently rejected by GitHub Actions (\"workflows must be defined at the top\n  level of the .github\u002Fworkflows\u002F directory\"). This isn't caught by\n  `actionlint` and doesn't show up as a normal failed run with useful\n  logs, it manifests as the workflow's `pull_request` trigger never firing\n  at all, forever, with GitHub's push-time workflow validation quietly\n  logging a 0-job \"failure\" on every unrelated push in the repo. If a\n  workflow that calls local reusable workflows never seems to trigger, check\n  this first. All check workflows now live flat in `.github\u002Fworkflows\u002F`\n  (`source-branch-check.yml`, `version-bump-check.yml`,\n  `changelog-check.yml`), not in a `checks\u002F` subdirectory.\n- **`cargo test`'s positional filter matches the full test *name*, not the\n  file name.** `cargo test -p foo -- self_validation` silently matches zero\n  tests (and reports success) if no test function's name contains that exact\n  substring. Use `cargo test -p foo --test self_validation_test` (selects by\n  binary\u002Ffile name, runs every test in it) for gate\u002FCI test-selection steps,\n  never a bare positional substring filter you haven't verified matches\n  something.\n- **The changelog in the GitHub Release can come out thin.** `create-release`\n  extracts release notes via `git log -1 --pretty=%B` on the merge commit, but\n  a standard GitHub PR-merge commit only contains a short \"Merge pull request\n  #N from ...\" summary, not the full PR body, even though the PR body is what\n  `changelog-check` validated. The version table still comes through\n  correctly; the prose changelog does not. Known gap, not yet fixed in the\n  workflow; expect to edit the GitHub Release notes by hand after a merge if\n  you want the full PR body preserved there.\n- **`release-create.yml`'s crate-name and version derivation are regex\u002Fgrep\n  based and have had real bugs**, not just cosmetic ones: extracting a\n  standard's numeric ID from its directory name via `sed 's\u002F-.*\u002F\u002F'` cut at\n  the first hyphen (`APS-V1-0000-meta` -> `APS`, not `0000`), and a\n  workspace-inherited crate's version was read via `grep '^version'` on its\n  own `Cargo.toml`, which matched the literal string `version.workspace =\n  true` when that crate has no direct version line. Both are fixed, but if a\n  future refactor changes directory-naming or `Cargo.toml` shape, re-verify\n  this script by extracting it and running it locally against real repo\n  history (`git log`, redirecting `$GITHUB_OUTPUT` to a file) before trusting\n  a real run, the failure mode is silent corruption, not an error.\n- **Crates were published manually before this automation existed.** The\n  idempotency check (skip if already on crates.io) protects against\n  re-publishing, but if crate layout or naming ever changes, confirm current\n  crates.io versions before trusting a first automated publish of a\n  previously-manual crate.\n\n## Recommended practices (as of 2026-07-10)\n\n- **Prep without publishing first** for anything unproven: do the bumps, open\n  the `main -> release` PR, and let the gate pass, then stop before merging.\n  The merge into `release` is the irreversible step (tags + a GitHub Release\n  happen immediately and automatically; crates.io publish pauses for manual\n  approval on `release-publish`, but the tags\u002Frelease do not). Review the\n  gate result before pulling that trigger.\n- **If the release gate's `pull_request` trigger doesn't fire on a PR at\n  all** (no check appears, not even a red X, just nothing), check\n  `mergeable`\u002F`mergeStateStatus` on the PR first\n  (`gh pr view N --json mergeable,mergeStateStatus`). GitHub cannot evaluate\n  `pull_request` triggers against a PR it can't compute a merge for; a\n  `CONFLICTING` PR silently never gets checks, which looks identical to a\n  broken workflow registration from the outside. Resolve the conflict, then\n  it fires immediately.\n- **Keep rename\u002Fsweep changes out of source comments when avoidable.** The\n  version-bump check counts any non-`docs\u002F` change (including a comment-only edit\n  to a `.rs` file) as bump-requiring, so a broad sweep forces patch bumps across\n  many units at the next release. Harmless, but it widens the bump set.\n- **Match the changed set exactly.** Bump only units that changed since the last\n  release. Over-bumping unchanged standards creates tags and (if published)\n  releases for units that did not change.\n\n## Workflow file map\n\n- `.github\u002Fworkflows\u002Fci.yml`: main trunk CI (no version-bump gate).\n- `.github\u002Fworkflows\u002Fmain-to-release-gate.yml`: the `main -> release` PR gate\n  (`name: Release Gate`; the file is not named `release-gate.yml` because\n  that path had a permanently stuck workflow registration and had to be\n  renamed to force GitHub to re-register it, see Operational state above).\n- `.github\u002Fworkflows\u002Fsource-branch-check.yml`: head must be `main`.\n- `.github\u002Fworkflows\u002Fversion-bump-check.yml`: changed units must bump\n  (docs-only exempt; any level).\n- `.github\u002Fworkflows\u002Fchangelog-check.yml`: PR body needs a changelog\n  section.\n- `.github\u002Fworkflows\u002Frelease-create.yml`: on push to `release`, tags + GitHub\n  Release + tiered crates.io publish (the `publish` job pauses for manual\n  approval on the `release-publish` environment).\n","# Releasing APSS\n\n## Overview\n\nAPSS uses trunk-based development with a single `release` branch. Feature work\nmerges into `main` freely, with no version-bump pressure. A release is a\n`main -> release` pull request that the **Release Gate** validates; merging that\nPR into `release` triggers `release-create.yml`, which creates git tags, a\nGitHub Release, and (once configured) publishes crates to crates.io.\n\nThe single most load-bearing idea: **version bumps are enforced once, at the\nrelease gate, against the previous release. They are not required on merges to\nmain.** That is deliberate. Per-merge bump enforcement causes version churn and\nmerge conflicts on the version files when several PRs land between releases.\nBumping at release time lets changes accumulate on main and get versioned once.\n\n## The release model\n\n```\nfeature branch --PR--> main  (ci.yml: fmt, clippy, check, test, aps-validation)\n                        |        no version-bump pressure here\n                        |\n                  main --PR--> release   (release-gate.yml: the hard gate)\n                                  |\n                          merge into release\n                                  |\n                        release-create.yml: tags + GitHub Release + crates.io\n```\n\n- **`main` is the trunk.** `ci.yml` runs on every push\u002FPR to main and does NOT\n  run the version-bump check. Merge features here without bumping.\n- **`release` is the only branch releases come from.** A release PR's head must\n  be `main` (the `source-branch-check` rejects anything else), so any version\n  bumps must already be on `main` before you open the release PR.\n- **Tags are per-unit.** The system tag is `v\u003Cworkspace-version>`; each changed\n  standard\u002Fsubstandard gets its own tag (for example `APS-V1-0001-v0.2.1`,\n  `APS-V1-0000.CF01-v1.0.1`).\n\n## Inputs and preconditions\n\n- Changes already merged to `main` that you want to release.\n- The `release` branch exists on origin, and `CARGO_REGISTRY_TOKEN` plus the\n  `release-publish` environment are already configured (see Operational\n  state for the gotchas learned bootstrapping this).\n\n## Workflow: cutting a release\n\n1. **Find what changed since the last release.** The gate diffs the release PR\n   against the release base (the `release` branch tip, which equals the last\n   release). Compute the same set locally:\n   `git diff --name-only origin\u002Frelease..main`. A package needs a bump if it has\n   any changed file outside its `docs\u002F` directory.\n\n2. **Bump versions on main.** For each changed standard\u002Fsubstandard, bump the\n   `version` in its `standard.toml` \u002F `substandard.toml` AND the matching\n   `Cargo.toml`. If any system crate (`apss-core`, `aps-cli`, `apss-bootstrap`)\n   changed, bump the `[workspace.package] version` in the root `Cargo.toml`. Any\n   semver level satisfies the gate; there is no level enforcement, so patch is\n   fine for backwards-compatible changes. Land these via a normal PR into main.\n\n3. **Open the release PR: `main` -> `release`.** The PR body MUST contain a\n   `## Changelog` (or `## Release Notes` \u002F `## What Changed` \u002F `## Changes`)\n   section; `changelog-check` fails without it, and `release-create` extracts\n   that section into the GitHub Release notes.\n\n4. **Let the Release Gate run and pass.** It runs source-branch-check,\n   version-bump-check, changelog-check, full QA (fmt, clippy `-D warnings`,\n   check, test, release build), APS validation (`v1 validate repo` +\n   `distribution` + self-validation\u002Fbackwards-compat\u002FCF01\u002FDI01 tests),\n   cargo-audit, and dependency-review. The `release-gate-success` job aggregates\n   them and is the required status check.\n\n5. **Merge into `release`.** This fires `release-create.yml`, which tags every\n   changed unit, pushes tags, creates the GitHub Release from the changelog, and\n   runs the publish job.\n\n6. **Verify the publish against crates.io, not against the job's exit status.**\n   The publish job tolerates an already-published version, so a re-run after a\n   partial publish resumes rather than dying. That was NOT true before\n   2026-08-07: the job pre-checked with `cargo search`, whose eventually\n   consistent search endpoint kept reporting a just-published crate as missing,\n   making every re-run fail on the first crate that had already gone out. If you\n   are working on a release whose workflow predates that fix, expect re-runs to\n   fail and publish the remainder by hand (see the new-crate section below).\n\n   Check the actual registry rather than trusting a green job:\n\n   ```bash\n   for c in apss-core apss \u003Cchanged-standard-crates>; do\n     curl -s \"https:\u002F\u002Fcrates.io\u002Fapi\u002Fv1\u002Fcrates\u002F$c\" | jq -r '\"\\(.crate.name) \\(.crate.max_version)\"'\n   done\n   ```\n\n## What publishes and what does not\n\n`release-create.yml` publishes in dependency-tier order, only for changed units:\n\n- **Tier 1:** `apss-core` (only when a system crate changed).\n- **Tier 2\u002F3:** changed **official** standard crates under\n  `standards\u002Fv1\u002FAPS-V1-XXXX-\u003Cslug>` where `XXXX != 0000`, in dependency order.\n- **Last:** `apss` (the bootstrap binary).\n\n**Never published:** the meta-standard (`APS-V1-0000`) and its internal\nsubstandards, and everything under `standards-experimental\u002F`. These still get\ngit tags and release notes, but no `cargo publish`. Treat that exclusion as\nload-bearing: the publish job filters them out by directory prefix.\n\n## Releasing a crate that has NEVER been published\n\n**The first release of any new crate name needs a one-time manual `cargo\npublish`. CI cannot do it, by design.**\n\n`CARGO_REGISTRY_TOKEN` is deliberately scoped `publish-update` on crates `apss`\nand `apss-*`. It can push new *versions* of crates the project already owns, and\nnothing else. It cannot create a new crate name, because a CI token that could\nwould let anyone who leaked it squat or publish arbitrary `apss-*` packages. The\nnarrower scope is the security posture, not an oversight: do not \"fix\" this by\nadding `publish-new` to the CI token.\n\nThe symptom, if you forget: the publish job runs, tier 1 succeeds, and the new\ncrate fails with\n\n```\nerror: failed to publish \u003Ccrate> to registry at https:\u002F\u002Fcrates.io\nCaused by:\n  the remote server responded with an error (status 403 Forbidden):\n  this token does not have the required permissions to perform this action\n```\n\nThat message names the token, not the crate, so it is easy to misread as a\nworkflow bug. It is not. The workflow handles new packages correctly: detection\nis a `git diff` against the last release tag (a directory that did not exist\nreads as changed), the crate name is derived from the directory name rather than\nfrom history, and the publish attempt is made unconditionally, so a crate that\nhas never been published is never skipped.\n\n### The flow\n\n1. Let the release merge as normal. Tags and the GitHub Release are created, and\n   the publish job fails at the new crate. **This is expected and recoverable.**\n   Anything published before the failure (typically `apss-core`) stays published.\n2. Publish the new crate by hand, **from the release tag**, using a personal\n   credential that has `publish-new`. Publishing from a working tree instead of\n   the tag would put bytes on crates.io that do not match what the tag claims:\n\n   ```bash\n   git checkout \u003CTAG>              # e.g. APS-V1-0004-v1.0.0\n   cargo publish -p \u003Ccrate-name>\n   ```\n\n   Run `cargo publish --dry-run -p \u003Ccrate-name>` first. It packages the crate and\n   compiles it from the packaged tarball, which catches the real risk: files\n   pulled in by `include_str!` from outside `src\u002F` are only present if they sit\n   inside the crate directory.\n3. Finish the remaining tiers. The publish job now tolerates already-published\n   versions, so re-running it resumes from where it died and tier 3 (`apss`)\n   goes out automatically. No need to re-tag or re-release.\n\n   **If the re-run still fails on a crate that is already published**, the run\n   is using a workflow from before the 2026-08-07 fix (a re-run executes the\n   workflow file from the commit that triggered it, so fixing it on `main` does\n   not help an in-flight run). Do not fight it. Publish the remaining crates by\n   hand from their tags, exactly as in step 2:\n\n   ```bash\n   git checkout v\u003Csystem-version>     # e.g. v1.5.0\n   cargo publish -p apss\n   ```\n\n   The red job is then cosmetic. What matters is the registry.\n4. Every subsequent release of that crate is fully automated: `publish-update`\n   covers it from then on. `publish-new` is needed once per crate name, not once\n   per release.\n\n### Consider Trusted Publishing afterward\n\ncrates.io supports GitHub Actions OIDC, which removes the long-lived token from\nCI entirely. It has the same chicken-and-egg (trust cannot be configured for a\ncrate that does not exist yet), so it is a follow-up to step 2 rather than a\nreplacement for it. Worth doing if the shared token's blast radius matters.\n\n## Operational state (as of 2026-07-10)\n\nThe pipeline is now **live and proven end to end**: the `release` branch\nexists, `CARGO_REGISTRY_TOKEN` and the `release-publish` environment (required\nreviewer: repo owner) are configured, and the first real release\n(`v1.2.0`, PR #102) went through the gate clean and published all five\npublishable crates to crates.io successfully. Treat the workflow-level\ndescription above as trustworthy; this section now tracks known gotchas\ninstead of \"not wired yet\" caveats.\n\n- **What v1.5.0 actually cost (2026-08-07), as a worked example.** The release\n  that first published `apss-v1-0004-session-capture` needed three manual\n  interventions, and every one of them is now covered above. The publish job\n  403'd on the new crate (CI token is `publish-update` only, by design). The\n  operator's local token turned out to be dead, a *different* 403 reading\n  `authentication failed` rather than `does not have the required permissions`\n  (read that message carefully; the two mean different things). And both re-runs\n  then died on `apss-core@1.5.0 already exists`, because the old `cargo search`\n  pre-check never saw it. Final state was reached by publishing two of the three\n  crates by hand from their tags. The git tags and GitHub Release were correct\n  throughout; only the publish job was red. **Verify against crates.io, not\n  against the job.**\n- **Never push directly to `release`.** It is a real branch with a real\n  `push` trigger: any push, including a one-off debugging fix, fires\n  `release-create.yml` for real (tags + a GitHub Release get created\n  immediately, no gate). This happened by accident while bootstrapping the\n  pipeline; the `release-publish` approval gate is what prevented an\n  accidental crates.io publish, but the stray tags and a garbage GitHub\n  Release still had to be deleted by hand. Always land changes to `release`\n  through a gated `main -> release` PR, never `git push origin ...:release`.\n- **Local reusable workflows cannot live in a subdirectory of\n  `.github\u002Fworkflows\u002F`.** `uses: .\u002F.github\u002Fworkflows\u002Fchecks\u002Ffoo.yml` is\n  silently rejected by GitHub Actions (\"workflows must be defined at the top\n  level of the .github\u002Fworkflows\u002F directory\"). This isn't caught by\n  `actionlint` and doesn't show up as a normal failed run with useful\n  logs, it manifests as the workflow's `pull_request` trigger never firing\n  at all, forever, with GitHub's push-time workflow validation quietly\n  logging a 0-job \"failure\" on every unrelated push in the repo. If a\n  workflow that calls local reusable workflows never seems to trigger, check\n  this first. All check workflows now live flat in `.github\u002Fworkflows\u002F`\n  (`source-branch-check.yml`, `version-bump-check.yml`,\n  `changelog-check.yml`), not in a `checks\u002F` subdirectory.\n- **`cargo test`'s positional filter matches the full test *name*, not the\n  file name.** `cargo test -p foo -- self_validation` silently matches zero\n  tests (and reports success) if no test function's name contains that exact\n  substring. Use `cargo test -p foo --test self_validation_test` (selects by\n  binary\u002Ffile name, runs every test in it) for gate\u002FCI test-selection steps,\n  never a bare positional substring filter you haven't verified matches\n  something.\n- **The changelog in the GitHub Release can come out thin.** `create-release`\n  extracts release notes via `git log -1 --pretty=%B` on the merge commit, but\n  a standard GitHub PR-merge commit only contains a short \"Merge pull request\n  #N from ...\" summary, not the full PR body, even though the PR body is what\n  `changelog-check` validated. The version table still comes through\n  correctly; the prose changelog does not. Known gap, not yet fixed in the\n  workflow; expect to edit the GitHub Release notes by hand after a merge if\n  you want the full PR body preserved there.\n- **`release-create.yml`'s crate-name and version derivation are regex\u002Fgrep\n  based and have had real bugs**, not just cosmetic ones: extracting a\n  standard's numeric ID from its directory name via `sed 's\u002F-.*\u002F\u002F'` cut at\n  the first hyphen (`APS-V1-0000-meta` -> `APS`, not `0000`), and a\n  workspace-inherited crate's version was read via `grep '^version'` on its\n  own `Cargo.toml`, which matched the literal string `version.workspace =\n  true` when that crate has no direct version line. Both are fixed, but if a\n  future refactor changes directory-naming or `Cargo.toml` shape, re-verify\n  this script by extracting it and running it locally against real repo\n  history (`git log`, redirecting `$GITHUB_OUTPUT` to a file) before trusting\n  a real run, the failure mode is silent corruption, not an error.\n- **Crates were published manually before this automation existed.** The\n  idempotency check (skip if already on crates.io) protects against\n  re-publishing, but if crate layout or naming ever changes, confirm current\n  crates.io versions before trusting a first automated publish of a\n  previously-manual crate.\n\n## Recommended practices (as of 2026-07-10)\n\n- **Prep without publishing first** for anything unproven: do the bumps, open\n  the `main -> release` PR, and let the gate pass, then stop before merging.\n  The merge into `release` is the irreversible step (tags + a GitHub Release\n  happen immediately and automatically; crates.io publish pauses for manual\n  approval on `release-publish`, but the tags\u002Frelease do not). Review the\n  gate result before pulling that trigger.\n- **If the release gate's `pull_request` trigger doesn't fire on a PR at\n  all** (no check appears, not even a red X, just nothing), check\n  `mergeable`\u002F`mergeStateStatus` on the PR first\n  (`gh pr view N --json mergeable,mergeStateStatus`). GitHub cannot evaluate\n  `pull_request` triggers against a PR it can't compute a merge for; a\n  `CONFLICTING` PR silently never gets checks, which looks identical to a\n  broken workflow registration from the outside. Resolve the conflict, then\n  it fires immediately.\n- **Keep rename\u002Fsweep changes out of source comments when avoidable.** The\n  version-bump check counts any non-`docs\u002F` change (including a comment-only edit\n  to a `.rs` file) as bump-requiring, so a broad sweep forces patch bumps across\n  many units at the next release. Harmless, but it widens the bump set.\n- **Match the changed set exactly.** Bump only units that changed since the last\n  release. Over-bumping unchanged standards creates tags and (if published)\n  releases for units that did not change.\n\n## Workflow file map\n\n- `.github\u002Fworkflows\u002Fci.yml`: main trunk CI (no version-bump gate).\n- `.github\u002Fworkflows\u002Fmain-to-release-gate.yml`: the `main -> release` PR gate\n  (`name: Release Gate`; the file is not named `release-gate.yml` because\n  that path had a permanently stuck workflow registration and had to be\n  renamed to force GitHub to re-register it, see Operational state above).\n- `.github\u002Fworkflows\u002Fsource-branch-check.yml`: head must be `main`.\n- `.github\u002Fworkflows\u002Fversion-bump-check.yml`: changed units must bump\n  (docs-only exempt; any level).\n- `.github\u002Fworkflows\u002Fchangelog-check.yml`: PR body needs a changelog\n  section.\n- `.github\u002Fworkflows\u002Frelease-create.yml`: on push to `release`, tags + GitHub\n  Release + tiered crates.io publish (the `publish` job pauses for manual\n  approval on the `release-publish` environment).\n",{"name":5,"description":7},"main","eb6d0f95e313ba4464c2f6b78686807f8f1bace6",".claude\u002Fskills\u002Freleasing-apss",1,"https:\u002F\u002Fgithub.com\u002FAgentParadise\u002Fagent-paradise-standards-system","https:\u002F\u002Fgithub.com\u002FAgentParadise","2026-11-13 18:42:19",{"source":8,"skillName":5,"commands":51,"prompt":61,"zipAvailable":62},[52,55,58],{"tool":53,"command":54},"npx","npx skills add AgentParadise\u002Fagent-paradise-standards-system --skill releasing-apss",{"tool":56,"command":57},"bunx","bunx skills add AgentParadise\u002Fagent-paradise-standards-system --skill releasing-apss",{"tool":59,"command":60},"pnpm","pnpm dlx skills add AgentParadise\u002Fagent-paradise-standards-system --skill releasing-apss","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FAgentParadise\u002Fagent-paradise-standards-system\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Freleasing-apss\u002FSKILL.md",true,[64],{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"agents\u002Fopenai.yaml","REFERENCE","参考文档",262,"https:\u002F\u002Fgithub.com\u002FTimothyMeadows\u002FHephaera\u002Fblob\u002Fmain\u002Fskills\u002Fbuild-accessible-motion-systems\u002Fagents\u002Fopenai.yaml",[71,91],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":87,"publishedAt":38},"01M6C52WB5WW3Q46YWJRJ5A503","code-review","Review source changes for defects.","https:\u002F\u002Fgithub.com\u002FAgentParadise\u002Fagent-paradise-standards-system\u002Fblob\u002Fmain\u002Fstandards-experimental\u002Fv1\u002FEXP-V1-0005-agent-recipe\u002Ftests\u002Ffixtures\u002Fvalid-recipe\u002Fskills\u002Fcode-review\u002FSKILL.md",[77,82],{"categoryNo":78,"categoryName":79,"taxonomyType":80,"taxonomyTypeDesc":81},"01JBSEEDCAT000000000000007","代码审查","SCENARIO","使用场景",{"categoryNo":83,"categoryName":84,"taxonomyType":85,"taxonomyTypeDesc":86},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[88,89,90],"code review","review","code",{"skillNo":92,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":97,"publishedAt":38},"01M6C52TEXTDJRDEYRR5WDH5VJ","https:\u002F\u002Fgithub.com\u002FAgentParadise\u002Fagent-paradise-standards-system\u002Fblob\u002Fmain\u002Fstandards-experimental\u002Fv1\u002FEXP-V1-0005-agent-recipe\u002Fexamples\u002Fvalid\u002Fpr-reviewer\u002Fskills\u002Fcode-review\u002FSKILL.md",[95,96],{"categoryNo":78,"categoryName":79,"taxonomyType":80,"taxonomyTypeDesc":81},{"categoryNo":83,"categoryName":84,"taxonomyType":85,"taxonomyTypeDesc":86},[88,89,90]]